WorkBuddy 安装与使用

Camofox Web Search 通过本地 stdio 桥接器接入腾讯 WorkBuddy。WorkBuddy 5.3.8 的 HTTP 连接器只支持静态请求头，不会在这里展开 ${WEB_SEARCH_API_KEY}；桥接器从 WorkBuddy 进程读取 Key，再连接 Gateway 的 Streamable HTTP MCP endpoint。WorkBuddy 获得只读的 web_search 与 web_fetch 工具，浏览器流量、认证、Provider 回退和 SSRF 防护仍由自托管 Gateway 负责。

WorkBuddy 任务 → 本地 stdio 桥接器 → 带认证的 /mcp → Camofox Web Search → 浏览器/Provider

五分钟接入

使用 curl -fsS https://search.example.com/readyz 确认 Gateway 已就绪。
安装 CLI，通过 install workbuddy 写入用户级或项目级配置。
让 WorkBuddy 桌面进程读取 WEB_SEARCH_API_KEY，并完全重启 WorkBuddy。
打开插件 → MCP 服务器，批准 camofox_web，确认连接器为绿色。
执行 doctor workbuddy --live，再让 WorkBuddy 实际调用两个 Camofox 工具。

下面给出完整命令和各平台配置方法。

前置条件

已运行 Camofox Web Search，并取得公开的 WEB_SEARCH_API_KEY。
WorkBuddy 5.3.8；本接入使用 macOS ARM64 桌面端验收，升级到更新版本后应重新执行 doctor。
安装 Node.js 22 或更高版本，用于运行 camofox-web-search 配置 CLI。

修改 WorkBuddy 前先验证 Gateway：

curl -fsS https://search.example.com/readyz

安装

安装 CLI，让当前 Shell 能读取公开 Key，然后选择用户级或项目级配置：

npm install -g camofox-web-search
export WEB_SEARCH_API_KEY="<通过安全方式从服务端 .env 复制>"

camofox-web-search install workbuddy \
  --endpoint https://search.example.com \
  --scope user

用户级配置写入 ~/.workbuddy/mcp.json，对所有 WorkBuddy 项目生效。项目级配置写入当前目录下的 .workbuddy/mcp.json：

camofox-web-search install workbuddy \
  --endpoint https://search.example.com \
  --scope project

受管条目包含 Node.js 与 workbuddy-bridge.js 的本地绝对路径，以及非敏感的 Gateway endpoint。真实 Token 和 Authorization 请求头都不会写入 WorkBuddy 配置。移动或替换 Node.js、全局 camofox-web-search 安装后应重新执行安装器；明确刷新旧的受管路径时使用 --force。

如需审计生成的配置，可直接查看文件，或与仓库中的 WorkBuddy 配置示例对照；该操作不会输出 Key：

sed -n '1,120p' ~/.workbuddy/mcp.json

让 WorkBuddy 读取 Key

桌面应用不一定继承交互式 Shell 中执行的 export。macOS 上应完全退出 WorkBuddy，把变量注入当前用户的 launch 环境，再重新打开应用：

launchctl setenv WEB_SEARCH_API_KEY "$WEB_SEARCH_API_KEY"
open -a WorkBuddy

不再使用时可从 launch 环境移除：

launchctl unsetenv WEB_SEARCH_API_KEY

Windows 上可设置用户环境变量，然后重启 WorkBuddy：

[Environment]::SetEnvironmentVariable("WEB_SEARCH_API_KEY", "<公开 Gateway Key>", "User")

不要把环境变量引用替换成真实 Token 并提交到仓库。

信任并使用连接器

在 WorkBuddy 中打开插件 → MCP 服务器。如果出现信任提示，批准 camofox_web，并确认状态为绿色。然后明确要求 WorkBuddy 使用 Camofox 工具，例如：

使用 camofox_web 的 web_search 查找 Model Context Protocol 官方规范，再用 camofox_web 的 web_fetch 阅读首个主要结果并引用来源。

验收时明确工具名，可以避免误用 WorkBuddy 内置的 Web Search Skill。

只有任务中实际出现 camofox_web_web_search 与 camofox_web_web_fetch 调用才算通过验收；仅返回普通文字答案不能证明接入成功。

诊断

使用与安装相同的 scope 执行 doctor：

camofox-web-search doctor workbuddy \
  --endpoint https://search.example.com \
  --scope user \
  --live

该命令会检查本地 WorkBuddy 桥接条目、环境变量、传输安全、Gateway 健康状态、准确的 MCP 工具集合和一次真实搜索。

验收清单

doctor 的配置、环境变量、传输、健康检查、MCP 工具和实时搜索均显示 PASS。
WorkBuddy 显示 camofox_web 已连接，并且只有 web_search、web_fetch 两个工具。
明确的测试提示词确实触发两个连接器工具。
~/.workbuddy/mcp.json、.workbuddy/mcp.json、截图和日志中均没有 API Key 或 Authorization 请求头。

排障

现象	检查方式
连接器显示红色	确认配置中的 Node.js 和桥接器路径仍存在、endpoint 正确；设置环境变量后重启 WorkBuddy，并查看 MCP 详情。
`401 unauthorized`	确认 WorkBuddy 继承了服务端生成的同一 `WEB_SEARCH_API_KEY`；不要把 Key 写入仓库配置。
看不到工具	批准连接器信任、确认 `camofox_web` 已启用，并在重启 WorkBuddy 后新建任务。
远程连接失败	远程 endpoint 必须使用 HTTPS；如果配置了代理，应排除会破坏 MCP 流式传输的 Gateway 主机。
项目连接器未出现	打开包含 `.workbuddy/mcp.json` 的同一目录，或改用 `--scope user`。

卸载

只删除受管的 camofox_web，保留其他 WorkBuddy 连接器：

camofox-web-search uninstall workbuddy \
  --endpoint https://search.example.com \
  --scope user

卸载后重启 WorkBuddy。卸载不会删除操作系统环境中的 WEB_SEARCH_API_KEY。