Brave Search Setup

核心用法

本技能提供完整的 Brave Search API 配置与网络代理排障方案，主要面向 macOS 用户解决 OpenClaw 的 web_search 和 web_fetch 工具连接问题。

配置流程：
1. API 密钥设置：通过 openclaw gateway config.patch 或编辑 ~/.openclaw/openclaw.json 注入 Brave Search API key
2. 连通性测试：执行 openclaw web.search --query "test" 验证基础功能
3. 代理诊断：检测 Clash/V2Ray/Surge 端口（7890/7897/1080 等），使用 launchctl setenv 设置系统级代理变量
4. 网关重启：必须重启 OpenClaw gateway 进程以加载代理环境变量
5. 功能验证：同时测试 web.search 与 web.fetch 确保双通路正常

关键命令矩阵：

| 场景 | 命令 |

|------|------|

| 快速配置 API | `config.patch --raw '{"tools":{"web":{"search":{"apiKey":"..."}}}}'` |

| 持久化代理 | `launchctl setenv HTTPS_PROXY http://127.0.0.1:7897` |

| 网关重启 | `openclaw gateway restart` 或 `kill -USR1 $(pgrep -f "openclaw gateway")` |

| 端口探测 | `nc -z 127.0.0.1 $port` 循环测试 |

显著优点

• 场景针对性强：专为 "fetch failed" 错误设计，覆盖 GFW 环境下最常见的 Clash 代理配置痛点
• 多层级解决方案：提供 session 级（export）、系统级（launchctl）、永久级（.zshrc）三种代理注入方式
• 诊断链条完整：从 API 配置 → 代理检测 → 环境变量 → 进程重启形成闭环排障

潜在缺点与局限性

• 平台局限：代理配置章节重度依赖 macOS 生态（launchctl、Clash Verge 路径），Linux/Windows 用户需自行适配
• 工具绑定：紧密耦合 OpenClaw CLI 特定命令结构，不适用于其他 LLM 工具链
• 代理客户端假设：预设用户使用 Clash/Surge/V2Ray 主流方案，小众代理工具缺乏覆盖
• 安全风险：明文 API key 存储于本地 JSON 文件，虽标注 "securely stored" 但未说明加密机制
• 重启依赖：必须重启 gateway 进程才能生效，可能影响正在进行的长任务

适合人群

• macOS + OpenClaw 用户遭遇 "fetch failed" 错误
• 需要通过代理访问 Brave Search API 的中国大陆开发者
• 熟悉命令行但需快速参考代理端口映射的技术用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 密钥泄露 | API key 以明文写入配置文件 | 定期轮换密钥，限制 IP 白名单 |

| 代理绕过失败 | 部分工具不遵循 HTTPS_PROXY 变量 | 备选 proxychains-ng 方案已提供 |

| 配置持久化冲突 | launchctl 与 shell profile 设置冲突 | 统一使用 launchctl 并验证 `env` 输出 |

| 进程状态丢失 | gateway 重启中断正在执行的命令 | 选择低峰期操作或使用 SIGUSR1 热重载 |

核心用法

brave-search-setup 是专为 OpenClaw 用户设计的网络配置技能，解决三大场景：
1. Brave Search API 密钥配置 — 通过 config.patch 命令或手动编辑 ~/.openclaw/openclaw.json 启用搜索功能
2. 代理穿透配置 — 针对中国大陆用户，提供 Clash/V2Ray/Surge 等 macOS 代理客户端的完整对接方案
3. 网络故障诊断 — 系统性排查 "fetch failed" 错误的根因

配置流程（四步闭环）

配置 API Key → 直连测试 → 代理检测/设置 → 网关重启 → 验证

关键命令速查：

• 配置密钥：openclaw gateway config.patch --raw '{"tools":{"web":{"search":{"apiKey":"..."}}}}'
• 持久化代理（推荐）：launchctl setenv HTTPS_PROXY http://127.0.0.1:7897
• 重启网关：openclaw gateway restart 或 kill -USR1 $(pgrep -f "openclaw gateway")
• 端口检测：for port in 7890 7891 7897 ...; do nc -z 127.0.0.1 $port && echo "Port $port open"; done

代理端口对照表：

| 客户端 | HTTP | SOCKS5 | Mixed |

|--------|------|--------|-------|

| Clash Verge | 7890 | 7891 | **7897**（推荐） |

| Surge | 6152 | 6153 | - |

| V2Ray | - | 1080/10808 | - |

显著优点

1. 场景精准定位 — 唯一覆盖 "API 配置 + 代理穿透 + 故障排查" 三合一的技术文档型技能
2. 命令即拿即用 — 提供可直接复制的 shell 命令，含循环检测端口、动态配置 patch 等实用脚本
3. 分层解决方案 — 从 session-only 到永久配置（~/.zshrc），再到 launchctl 系统级环境变量，满足不同持久化需求
4. 深度诊断覆盖 — 明确区分 "浏览器能翻墙但 OpenClaw 不能" 的典型场景（网关进程先于代理启动）

潜在缺点与局限性

1. 平台高度局限 — 核心脚本 detect-proxy.sh 硬编码 macOS 路径（~/Library/Application Support/io.github.clash-verge-rev...），Linux/Windows 用户需自行适配
2. 依赖外部密钥 — 需用户自行申请 Brave Search API key（brave.com/search/api/），免费额度有限
3. 无自动化回滚 — 写入 ~/.zshrc 的代理配置需手动删除，技能未提供 "一键卸载代理配置" 功能
4. 代理chains方案未完善 — 提及 proxychains-ng 但标记为 "Advanced"，缺少常见失败场景的处理

适合人群

• macOS 用户：尤其是使用 Clash Verge/Surge 的科学上网用户
• OpenClaw 新用户：需要首次配置 web_search 功能
• 网络故障排查者：遇到 "fetch failed" 但不确定是 API 问题还是代理问题的开发者

常规风险

| 风险点 | 等级 | 说明 |

|--------|------|------|

| 持久化 shell 配置修改 | 低 | `>> ~/.zshrc` 操作可逆，但需用户手动编辑删除 |

| API 密钥泄露 | 中 | 用户若错误地将真实密钥粘贴到公共场景，存在泄露风险 |

| 代理端口冲突 | 低 | 7897 端口被占用时需手动检测并更换 |

| 网关重启失败 | 低 | 需先启用 `commands.restart: true` 权限 |

安全认证亮点

本技能通过 CLS-Certify S级认证（89分），核心安全特性：

• 零外部依赖：无第三方 npm/pip 包引入
• 零网络外泄：仅检测本地 127.0.0.1 端口，无 outbound 请求
• 无危险函数：未使用 eval/exec/system 等代码注入风险点
• 隐私合规：符合 GDPR/CCPA 数据最小化原则

> ⚠️ 注意：安全认证仅反映代码静态扫描结果，不代表功能正确性保证。代理配置需用户自行承担网络合规责任。