本文记录 WorkBuddy 接入第三方 Claude API 的完整配置过程包含 models.json 字段说明、常见报错排查适合有一定动手能力的开发者参考。一、背景WorkBuddy 是腾讯云推出的桌面级 AI Agent 工具支持自然语言驱动本地文件操作、多 Agent 并行执行等功能。它内置了混元、DeepSeek、GLM 等模型但官方暂未直接提供 Claude 系列模型的接入入口。好在 WorkBuddy 支持通过配置文件自定义模型接口地址只要对端服务兼容 OpenAI Chat Completions 格式理论上任何模型都可以接入。本文以 Claude 模型为例记录配置过程和踩坑经历。二、环境说明操作系统Windows 11macOS 步骤基本一致WorkBuddy 版本最新桌面版接口格式OpenAI 兼容的 Chat Completions/v1/chat/completions三、配置文件位置WorkBuddy 的本地模型配置文件路径如下WindowsC:\Users\用户名\.workbuddy\models.json运行项目并下载源码1macOS / Linux~/.workbuddy/models.json运行项目并下载源码1如果目录下没有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列表]}关键字段说明字段类型说明idstring模型唯一标识需与接口实际支持的 model 参数一致urlstring完整请求地址填到/v1/chat/completions这一级apiKeystring对应服务商的 API KeymaxInputTokensint最大输入 token 数按模型实际上限填写maxOutputTokensint最大输出 token 数supportsToolCallbool是否支持函数调用 / Tool UsesupportsImagesbool是否支持图片输入多模态availableModelsarray控制模型下拉列表中显示哪些项五、完整配置示例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/completionsAPI Key你的密钥模型 ID如claude-sonnet-5七、配置生效前必须完全重启修改完models.json或保存图形化配置后必须完全退出 WorkBuddy 再重新启动配置才会生效。Windows 用户注意关闭主窗口不等于退出程序WorkBuddy 通常会最小化到系统托盘继续运行。需要在托盘图标上右键选择退出再重新打开。八、接口连通性验证配置前可以先用 curl 验证接口是否可以正常访问排除网络问题。Windows PowerShellcurl 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}运行项目并下载源码powershell1234macOS / Linuxcurl 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}运行项目并下载源码bash返回的 JSON 中包含choices[0].message.content字段说明接口正常。如果这一步就报错先排查网络和密钥不要急着去 WorkBuddy 里调试。九、常见报错及排查9.1 模型列表中看不到新添加的模型原因WorkBuddy 没有完全重启或者availableModels数组里没有包含该模型 ID。排查步骤确认availableModels数组里有对应的模型 ID系统托盘右键完全退出 WorkBuddy重新打开9.2401 Authentication Failed原因apiKey填写有误或密钥已失效。排查先用上面的 curl 命令单独测试密钥是否有效。注意apiKey字段只填密钥本身不要加Bearer前缀WorkBuddy 会自动拼接。9.3404 Model Not Found原因id字段与服务端实际支持的模型 ID 不一致。排查对照服务商文档或控制台确认模型 ID。例如 Haiku 的完整 ID 是claude-haiku-4-5-20251001少写任何部分都会 404。9.4读取本地模型配置失败原因models.jsonJSON 格式有误或编码不是 UTF-8 无 BOM。排查把 JSON 内容粘贴到 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 格式的审查报告。运行项目并下载源码12十一、小结步骤操作要点找到配置文件~/.workbuddy/models.json不存在则新建填写字段url填完整路径到/v1/chat/completionsid与服务端一致保存编码UTF-8 无 BOMJSON 格式合法重启应用系统托盘完全退出再重新启动验证连通先用 curl 测试接口再到 WorkBuddy 里切换模型