​

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


----

### 一、背景


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

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

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

![image](https://developer.qcloudimg.com/http-save/yehe-12697473/afae0615366ffa3515afc8ed5948abfc.png)![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)​编辑


### 二、环境说明


	- 操作系统：Windows 11（macOS 步骤基本一致）

	- WorkBuddy 版本：最新桌面版

	- 接口格式：OpenAI 兼容的 Chat Completions（`/v1/chat/completions`）


----

### 三、配置文件位置


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

**Windows：**


```
C:\Users\<用户名>\.workbuddy\models.json
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)



**macOS / Linux：**


```
~/.workbuddy/models.json
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)


如果目录下没有 `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列表"]
}
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)

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 系列模型的完整配置示例：![image](https://developer.qcloudimg.com/http-save/yehe-12697473/1f82e433c4939babe396c29943ccc275.png)![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)​编辑


```
{
  "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"
  ]
}
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)

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

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-12697473/604c893b505ea1f00650401c56f65d42.png)![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)​


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


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

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


----

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-12697473/d27ac8649dcc9d968bc279c6fa873286.png)![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)​编辑

### 八、接口连通性验证


配置前可以先用 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}'
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)


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}'
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)


返回的 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 格式的审查报告。
```
![image](https://developer.qcloudimg.com/http-save/yehe-12697473/45cf913e5d9d3c9b2058033056d3dd23.gif)




----

### 十一、小结


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

​

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

WorkBuddy/CodeBuddy 自定义接入第三方Claude sonnet-5/opus 5 /GPT 5.6 API 教程

开发工具

人工智能

编程语言

WorkBuddy接入Claude API完整教程，涵盖models.json配置、关键字段说明、图形化配置入口及常见报错排查。提供已验证的Claude系列模型ID示例，附curl连通性测试方法。重点解决模型列表不显示、401鉴权失败、404模型不存在等高频问题，帮助开发者快速实现自定义模型接入。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

WorkBuddy/CodeBuddy 自定义接入第三方Claude sonnet-5/opus 5 /GPT 5.6 API 教程-腾讯云开发者社区-腾讯云

WorkBuddy/CodeBuddy 自定义接入第三方Claude sonnet-5/opus 5 /GPT 5.6 API 教程

WorkBuddy/CodeBuddy 自定义接入第三方Claude sonnet-5/opus 5 /GPT 5.6 API 教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐