---

name: brave-search-setup
description: 配置 Brave Search API 并解决 web_search 功能的网络/代理问题。适用于用户需要：(1) 设置 Brave Search API 密钥，(2) 修复 web_search 抓取失败，(3) 为 macOS 上的 OpenClaw 工具配置 Clash/V2Ray/Surge 代理，或 (4) 诊断 web_search/web_fetch 工具的 "fetch failed" 错误。

Brave Search 设置与代理配置

配置 Brave Search API 并解决 OpenClaw 网络工具的连接问题。

前提条件

• Brave Search API 密钥（从 https://brave.com/search/api/ 获取）
• 已安装 OpenClaw CLI
• 如需突破 GFW 限制，需准备已安装代理客户端（Clash/V2Ray/Surge）的 macOS 设备

快速设置

步骤 1：配置 API 密钥

# 方案 A：通过 config.patch 配置（密钥将安全存储）  
openclaw gateway config.patch --raw '{"tools":{"web":{"search":{"apiKey":"YOUR_BRAVE_API_KEY","enabled":true,"provider":"brave"}}}}'  

或直接编辑 ~/.openclaw/openclaw.json：

{  
  "tools": {  
    "web": {  
      "search": {  
        "enabled": true,  
        "provider": "brave",  
        "apiKey": "YOUR_BRAVE_API_KEY"  
      }  
    }  
  }  
}  

步骤 2：无代理测试

openclaw web.search --query "test" --count 1  

若成功 → 完成配置。
若显示 "fetch failed" → 继续配置代理。

代理设置 (macOS)

步骤3：检测代理端口

常见客户端代理端口：

• Clash: 7890 (HTTP), 7891 (SOCKS5), 7897 (mixed-port)
• Surge: 6152, 6153
• V2Ray: 1080, 10808

检测实际端口：

# 检查 Clash 是否在运行
ps aux | grep -i clash

# 从 Clash 配置中查找 mixed-port
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（推荐 - 重启后依然有效）

# 为当前会话及未来会话设置
launchctl setenv HTTPS_PROXY http://127.0.0.1:7897
launchctl setenv HTTP_PROXY http://127.0.0.1:7897

方法 B: Shell 导出（仅当前会话）

export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897

方法 C: 添加到 shell 配置文件中（永久生效）

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：启用网关重启

openclaw gateway config.patch --raw '{"commands":{"restart":true}}'

步骤6：使用代理重启网关

# 重启以应用代理环境变量
openclaw gateway restart

# 或者使用 SIGUSR1
kill -USR1 $(pgrep -f "openclaw gateway")

步骤7：验证

# 测试网页搜索
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工具失败
原因：Gateway进程启动时未加载代理环境变量
解决方案：设置HTTPS_PROXY后重启Gateway服务

Gateway重启时提示权限被拒绝

启用重启命令：

openclaw gateway config.patch --raw '{"commands":{"restart":true}}'

API密钥错误

验证密钥是否设置：

openclaw gateway config.get | grep -A5 'web.*search'

使用curl直接测试：

curl -s "https://api.search.brave.com/res/v1/web/search?q=test&count=1" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: YOUR_API_KEY"

混合端口与独立端口

Clash的"mixed-port"（默认7897）同时处理HTTP和SOCKS5流量
如使用独立端口：

• HTTP代理端口：7890
• SOCKS5代理端口：7891（需特殊处理）

高级：工具级代理设置

并非所有工具都遵循HTTPS_PROXY环境变量。对于不支持的工具：

# 安装proxychains-ng
brew install proxychains-ng

# 配置
sudo tee /usr/local/etc/proxychains.conf <<EOF
strict_chain
proxy_dns
[ProxyList]
http 127.0.0.1 7897
EOF

# 通过代理运行
proxychains4 openclaw web.search --query "test"

工作流摘要

1. 配置API密钥 → 使用config.patch或编辑JSON
2. 测试连接 → 如失败则需配置代理
3. 检测端口 → 检查Clash/Surge配置
4. 设置环境变量 → 使用launchctl setenv或shell导出
5. 重启Gateway → 执行openclaw gateway restart
6. 验证功能 → 运行测试搜索

参考文档

• 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