WorkBuddy 接入 Claude API 教程：本地 AI Agent 实现自定义模型配置

本文记录 WorkBuddy 接入第三方 Claude API 的完整配置过程，包含 models.json 字段说明、常见报错排查，适合有一定动手能力的开发者参考。

---

一、背景

WorkBuddy 是腾讯云推出的桌面级 AI Agent 工具，支持自然语言驱动本地文件操作、多 Agent 并行执行等功能。它内置了混元、DeepSeek、GLM 等模型，但官方暂未直接提供 Claude 系列模型的接入入口。

好在 WorkBuddy 支持通过配置文件自定义模型接口地址，只要对端服务兼容 OpenAI Chat Completions 格式，理论上任何模型都可以接入。

本文以 Claude 模型为例，记录配置过程和踩坑经历。

二、环境说明

• 操作系统：Windows 11（macOS 步骤基本一致）
• WorkBuddy 版本：最新桌面版
• 接口格式：OpenAI 兼容的 Chat Completions（/v1/chat/completions）

---

三、配置文件位置

WorkBuddy 的本地模型配置文件路径如下：

Windows：

C:\Users\<用户名>\.workbuddy\models.json

macOS / Linux：

~/.workbuddy/models.json

如果目录下没有 models.json，新建一个即可。

⚠️ 注意：文件必须保存为 UTF-8 无 BOM 编码，否则 WorkBuddy 读取时会报 JSON 解析错误。Windows 用户建议用 VS Code 编辑，右下角可以确认编码格式。

---

四、配置文件结构说明

models.json 的基本结构如下：

{
  "models": [
    {
      "id": "模型ID",
      "name": "显示名称",
      "vendor": "厂商名",
      "url": "完整的 chat completions 接口地址",
      "apiKey": "你的 API Key",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": true
    }
  ],
  "availableModels": ["模型ID列表"]
}

关键字段说明：

字段	类型	说明
id	string	模型唯一标识，需与接口实际支持的 model 参数一致
url	string	完整请求地址，填到 /v1/chat/completions 这一级
apiKey	string	对应服务商的 API Key
maxInputTokens	int	最大输入 token 数，按模型实际上限填写
maxOutputTokens	int	最大输出 token 数
supportsToolCall	bool	是否支持函数调用 / Tool Use
supportsImages	bool	是否支持图片输入（多模态）
availableModels	array	控制模型下拉列表中显示哪些项

---

五、完整配置示例（Claude 系列）

下面是接入 Claude 系列模型的完整配置示例：

{
  "models": [
    {
      "id": "claude-opus-4-7",
      "name": "Claude Opus 4.7",
      "vendor": "Custom",
      "url": "https://gw.claudeapi.com/v1/chat/completions",
      "apiKey": "sk-你的密钥",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": true
    },
    {
      "id": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",
      "vendor": "Custom",
      "url": "https://gw.claudeapi.com/v1/chat/completions",
      "apiKey": "sk-你的密钥",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": true
    },
    {
      "id": "claude-haiku-4-5-20251001",
      "name": "Claude Haiku 4.5",
      "vendor": "Custom",
      "url": "https://gw.claudeapi.com/v1/chat/completions",
      "apiKey": "sk-你的密钥",
      "maxInputTokens": 200000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": [
    "claude-opus-4-7",
    "claude-sonnet-4-6",
    "claude-haiku-4-5-20251001"
  ]
}

关于 url 字段：

如果你有其他可用的兼容接口，替换 base URL 即可，字段格式不变。

关于模型 ID：

模型 ID 必须与接口服务端实际支持的 model 参数完全一致，包括大小写和连字符。上面列出的 ID 是我写这篇文章时验证可用的版本，建议以你使用的服务商控制台为准。

---

六、新版 WorkBuddy 的界面配置方式

部分较新版本的 WorkBuddy 已经提供了图形化的模型配置入口，不再依赖手动编辑 models.json。

可以在应用内找以下入口：

• 设置 → 模型管理
• 设置 → 自定义模型
• 侧边栏 → Claw（部分版本）

如果有图形化界面，按字段含义填入对应内容即可：

• Base URL / 基础地址： https://gw.claudeapi.com/v1
• 完整请求地址： https://gw.claudeapi.com/v1/chat/completions
• API Key： 你的密钥
• 模型 ID： 如 claude-sonnet-4-6
  

---

七、配置生效前必须完全重启

修改完 models.json 或保存图形化配置后，必须完全退出 WorkBuddy 再重新启动，配置才会生效。

Windows 用户注意：关闭主窗口不等于退出程序，WorkBuddy 通常会最小化到系统托盘继续运行。需要在托盘图标上右键选择"退出"，再重新打开。

---

八、接口连通性验证

配置前可以先用 curl 验证接口是否可以正常访问，排除网络问题。

Windows PowerShell：

curl https://gw.claudeapi.com/v1/chat/completions `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer sk-你的密钥" `
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"你好"}],"stream":false}'

macOS / Linux：

curl https://gw.claudeapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"你好"}],"stream":false}'

返回的 JSON 中包含 choices[0].message.content 字段，说明接口正常。如果这一步就报错，先排查网络和密钥，不要急着去 WorkBuddy 里调试。

---

九、常见报错及排查

9.1 模型列表中看不到新添加的模型

原因： WorkBuddy 没有完全重启，或者 availableModels 数组里没有包含该模型 ID。

排查步骤：

1. 确认 availableModels 数组里有对应的模型 ID
2. 系统托盘右键完全退出 WorkBuddy
3. 重新打开

---

9.2 401 Authentication Failed

原因： apiKey 填写有误，或密钥已失效。

排查： 先用上面的 curl 命令单独测试密钥是否有效。注意 apiKey 字段只填密钥本身，不要加 Bearer 前缀，WorkBuddy 会自动拼接。

---

9.3 404 Model Not Found

原因： id 字段与服务端实际支持的模型 ID 不一致。

排查： 对照服务商文档或控制台确认模型 ID。例如 Haiku 的完整 ID 是 claude-haiku-4-5-20251001，少写任何部分都会 404。

---

9.4 读取本地模型配置失败

原因： models.json JSON 格式有误，或编码不是 UTF-8 无 BOM。

排查：

1. 把 JSON 内容粘贴到 jsonlint.com 检查格式
2. 用 VS Code 打开文件，右下角确认编码是 UTF-8（不是 UTF-8 with BOM）
3. 检查有没有多余的逗号（JSON 最后一个元素后面不能有逗号）

---

9.5 Tool Call 不生效

原因： 模型本身不支持 Tool Use，或者 supportsToolCall 字段设置为 false。

排查： 确认模型支持 Tool Call，并将 supportsToolCall 设为 true。Claude Opus 和 Sonnet 系列均支持，Haiku 系列部分版本支持。

---

十、配置完成后的效果

配置生效后，在 WorkBuddy 对话界面的模型选择器中可以看到新添加的 Claude 模型，切换后即可正常对话。

WorkBuddy 的 Skills 功能同样支持使用自定义模型，可以指定 Claude 处理特定类型的任务，例如：

使用 Claude Opus 4.7，对 src/ 目录下的最近变更进行代码审查，
重点检查安全漏洞和性能瓶颈，输出 Markdown 格式的审查报告。

---

十一、小结

步骤	操作要点
找到配置文件	~/.workbuddy/models.json，不存在则新建
填写字段	url 填完整路径到 /v1/chat/completions，id 与服务端一致
保存编码	UTF-8 无 BOM，JSON 格式合法
重启应用	系统托盘完全退出，再重新启动
验证连通	先用 curl 测试接口，再到 WorkBuddy 里切换模型

---

如果遇到本文未覆盖的报错，欢迎在评论区留言，看到会补充。