WorkBuddy/CodeBuddy 自定义接入第三方Claude sonnet-5/opus 5 /GPT 5.6 API 教程
>本文记录 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列表"] } ```  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-5", "name": "Claude Opus 5", "vendor": "Custom", "url": "https://api.new.bi/v1/chat/completions", "apiKey": "sk-你的密钥", "maxInputTokens": 200000, "maxOutputTokens": 8192, "supportsToolCall": true, "supportsImages": true }, { "id": "claude-sonnet-5", "name": claude-sonnet-5", "vendor": "Custom", "url": "https:///api.new.bi/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:///api.new.bi/v1/chat/completions", "apiKey": "sk-你的密钥", "maxInputTokens": 200000, "maxOutputTokens": 4096, "supportsToolCall": true, "supportsImages": false } ], "availableModels": [ "claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5-20251001" ] } ```  json **关于 `url` 字段：** 如果你有其他可用的兼容接口，替换 base URL 即可，字段格式不变。 **关于模型 ID：** 模型 ID 必须与接口服务端实际支持的 `model` 参数完全一致，包括大小写和连字符。上面列出的 ID 是我写这篇文章时验证可用的版本，建议以你使用的服务商控制台为准。 ---- ### 六、新版 WorkBuddy 的界面配置方式 部分较新版本的 WorkBuddy 已经提供了图形化的模型配置入口，不再依赖手动编辑 `models.json`。 可以在应用内找以下入口： - 设置 → 模型管理 - 设置 → 自定义模型 - 侧边栏 → Claw（部分版本） 如果有图形化界面，按字段含义填入对应内容即可： ** New.bi 牛逼平台，GPT/Claude模型官方1.5折，稳定性目前属于市面上比较好的** - **Base URL / 基础地址：** `https:///api.new.bi/v1` - **完整请求地址：** `https:///api.new.bi/v1/chat/completions` - **API Key：** 你的密钥 - **模型 ID：** 如claude-sonnet-5  ### 七、配置生效前必须完全重启 修改完 `models.json` 或保存图形化配置后，**必须完全退出 WorkBuddy 再重新启动**，配置才会生效。 Windows 用户注意：关闭主窗口不等于退出程序，WorkBuddy 通常会最小化到系统托盘继续运行。需要在托盘图标上右键选择"退出"，再重新打开。 ---- 编辑 ### 八、接口连通性验证 配置前可以先用 curl 验证接口是否可以正常访问，排除网络问题。 **Windows PowerShell：** ``` curl https:///api.new.bi/v1/chat/completions ` -H "Content-Type: application/json" ` -H "Authorization: Bearer sk-你的密钥" ` -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"你好"}],"stream":false}' ```  powershell **macOS / Linux：** ``` curl https:///api.new.bi/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的密钥" \ -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"你好"}],"stream":false}' ```  返回的 JSON 中包含 `choices[0].message.content` 字段，说明接口正常。如果这一步就报错，先排查网络和密钥，不要急着去 WorkBuddy 里调试。 ---- ### 九、常见报错及排查 #### 9.1 模型列表中看不到新添加的模型 **原因：** WorkBuddy 没有完全重启，或者 `availableModels` 数组里没有包含该模型 ID。 **排查步骤：** - 确认 `availableModels` 数组里有对应的模型 ID - 系统托盘右键完全退出 WorkBuddy - 重新打开 ---- #### 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。 **排查：** - 把 JSON 内容粘贴到 [jsonlint.com](https://jsonlint.com/) 检查格式 - 用 VS Code 打开文件，右下角确认编码是 `UTF-8`（不是 `UTF-8 with BOM`） - 检查有没有多余的逗号（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 里切换模型|
