Brave Search Setup & Proxy Configuration
Setup Brave Search API and resolve network connectivity issues for OpenClaw web tools.
Prerequisites
- - Brave Search API key (get from https://brave.com/search/api/)
- OpenClaw CLI installed
- macOS with proxy client (Clash/V2Ray/Surge) if behind GFW
Quick Setup
Step 1: Configure API Key
CODEBLOCK0
Or edit ~/.openclaw/openclaw.json directly:
CODEBLOCK1
Step 2: Test Without Proxy
CODEBLOCK2
If works → Done.
If "fetch failed" → Continue to proxy setup.
Proxy Setup (macOS)
Step 3: Detect Proxy Port
Common proxy ports by client:
- - Clash: 7890 (HTTP), 7891 (SOCKS5), 7897 (mixed-port)
- Surge: 6152, 6153
- V2Ray: 1080, 10808
Detect actual port:
CODEBLOCK3
Step 4: Set System Proxy
Method A: launchctl (Recommended - survives restart)
CODEBLOCK4
Method B: Shell export (Session only)
CODEBLOCK5
Method C: Add to shell profile (Permanent)
CODEBLOCK6
Step 5: Enable Gateway Restart
CODEBLOCK7
Step 6: Restart Gateway with Proxy
CODEBLOCK8
Step 7: Verify
CODEBLOCK9
Troubleshooting
"fetch failed" but proxy works in browser
Symptom: Browser can access Google, but OpenClaw tools fail.
Cause: Gateway process started before proxy env vars were set.
Solution: Restart Gateway after setting HTTPS_PROXY.
Permission denied on Gateway restart
Enable restart command:
CODEBLOCK10
API key errors
Verify key is set:
CODEBLOCK11
Test directly with curl:
CODEBLOCK12
Mixed-port vs dedicated ports
Clash "mixed-port" (default 7897) handles both HTTP and SOCKS5.
If using dedicated ports:
- - HTTP proxy: 7890
- SOCKS5 proxy: 7891 (requires different handling)
Advanced: Per-Tool Proxy
Not all tools respect HTTPS_PROXY. For tools that don't:
CODEBLOCK13
Workflow Summary
- 1. Configure API key →
config.patch or edit JSON - Test → If fails, proxy needed
- Detect port → Check Clash/Surge config
- Set env vars →
launchctl setenv or shell export - Restart Gateway → INLINECODE3
- Verify → Run test search
References
- - Brave Search API Docs: https://api.search.brave.com/app/docs
- OpenClaw Config: https://docs.openclaw.ai/config
- Clash Verge: https://github.com/clash-verge-rev/clash-verge-rev
Brave Search 设置与代理配置
设置 Brave Search API 并解决 OpenClaw 网络工具的网络连接问题。
前置条件
- - Brave Search API 密钥（从 https://brave.com/search/api/ 获取）
- 已安装 OpenClaw CLI
- 若处于 GFW 后方，需使用 macOS 代理客户端（Clash/V2Ray/Surge）
快速设置
步骤 1：配置 API 密钥
bash
选项 A：通过 config.patch 配置（密钥将安全存储）
openclaw gateway config.patch --raw {tools:{web:{search:{apiKey:YOUR
BRAVEAPI_KEY,enabled:true,provider:brave}}}}
或直接编辑 ~/.openclaw/openclaw.json：
json
{
tools: {
web: {
search: {
enabled: true,
provider: brave,
apiKey: YOURBRAVEAPI_KEY
}
}
}
}
步骤 2：无代理测试
bash
openclaw web.search --query test --count 1
如果成功 → 完成。
如果出现fetch failed → 继续代理设置。
代理设置（macOS）
步骤 3：检测代理端口
各客户端常见代理端口：
- - Clash：7890（HTTP）、7891（SOCKS5）、7897（混合端口）
- Surge：6152、6153
- V2Ray：1080、10808
检测实际端口：
bash
检查 Clash 是否运行
ps aux | grep -i clash
从 Clash 配置中查找混合端口
cat ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/clash-verge.yaml | grep mixed-port
或测试常见端口
for port in 7890 7891 7897 6152 6153 1080 10808; do
if nc -z 127.0.0.1 $port 2>/dev/null; then
echo 端口 $port 已开放
fi
done
步骤 4：设置系统代理
方法 A：launchctl（推荐，重启后生效）
bash
为当前会话和未来会话设置
launchctl setenv HTTPS_PROXY http://127.0.0.1:7897
launchctl setenv HTTP_PROXY http://127.0.0.1:7897
方法 B：Shell 导出（仅当前会话）
bash
export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
方法 C：添加到 Shell 配置文件（永久生效）
bash
echo export HTTPS_PROXY=http://127.0.0.1:7897 >> ~/.zshrc
echo export HTTP_PROXY=http://127.0.0.1:7897 >> ~/.zshrc
source ~/.zshrc
步骤 5：启用网关重启
bash
openclaw gateway config.patch --raw {commands:{restart:true}}
步骤 6：使用代理重启网关
bash
重启以加载代理环境变量
openclaw gateway restart
或使用 SIGUSR1
kill -USR1 $(pgrep -f openclaw gateway)
步骤 7：验证
bash
测试网络搜索
openclaw web.search --query Brave Search test --count 1
测试网页抓取
openclaw web.fetch --url https://api.search.brave.com --max-chars 100
故障排除
fetch failed但浏览器中代理正常工作
症状：浏览器可以访问 Google，但 OpenClaw 工具失败。
原因：网关进程在设置代理环境变量之前启动。
解决方案：设置 HTTPS_PROXY 后重启网关。
网关重启权限被拒绝
启用重启命令：
bash
openclaw gateway config.patch --raw {commands:{restart:true}}
API 密钥错误
验证密钥是否已设置：
bash
openclaw gateway config.get | grep -A5 web.*search
直接使用 curl 测试：
bash
curl -s https://api.search.brave.com/res/v1/web/search?q=test&count=1 \
-H Accept: application/json \
-H X-Subscription-Token: YOURAPIKEY
混合端口与专用端口
Clash 混合端口（默认 7897）同时处理 HTTP 和 SOCKS5。
如果使用专用端口：
- - HTTP 代理：7890
- SOCKS5 代理：7891（需要不同处理方式）
高级：按工具配置代理
并非所有工具都遵循 HTTPS_PROXY。对于不遵循的工具：
bash
使用 proxychains-ng
brew install proxychains-ng
配置
sudo tee /usr/local/etc/proxychains.conf <
使用代理运行
proxychains4 openclaw web.search --query test
工作流程总结
- 1. 配置 API 密钥 → config.patch 或编辑 JSON
- 测试 → 如果失败，需要代理
- 检测端口 → 检查 Clash/Surge 配置
- 设置环境变量 → launchctl setenv 或 shell 导出
- 重启网关 → openclaw gateway restart
- 验证 → 运行测试搜索
参考
- - Brave Search API 文档：https://api.search.brave.com/app/docs
- OpenClaw 配置：https://docs.openclaw.ai/config
- Clash Verge：https://github.com/clash-verge-rev/clash-verge-rev
