WorkBuddy 桌面版API接入 - 数字先锋API文档

### WorkBuddy 桌面版接入第三方 OpenAI 兼容 API
以`https://api.cxsee.com/v1`示例
>一共有**两种配置方式：
①GUI界面可视化添加；
②直接本地编辑`models.json`批量维护多模型**
>⚠️接口是OpenAI兼容协议，配置框填写基础地址`[https://api.cxsee.com/v1]`即可

## 📍方式一：软件GUI界面添加（适合少量模型，图形化）
1. WorkBuddy桌面版左下角头像 打开【设置】→【模型】，点右上角**添加模型**

![](/uploads/editor/20261005/img_6ac3ae2d3ced79.36037371.png)

2. 供应商下拉框选择：**自定义（Custom，OpenAI兼容协议）**

![](https://img.cxweixin.cn/uploads/202610/2026100521491926830.png)

3. 填写参数：
    - **接口地址**：`[https://api.cxsee.com/v1](https://api.cxsee.com/v1)`
    - **API Key**：填写该中转平台分配的sk‑xxxx密钥
    - **模型名称(id)**：填写后端实际模型名（例如`deepseek‑flash` / `gpt‑6‑sol`，**这个ID必须和服务端识别的模型名字保持一致，否则调用会报model不存在**！）

![](https://img.cxweixin.cn/uploads/202610/2026100521492053506.png)

4. **高级配置勾选能力项（非常关键！Agent工具调用取决于这里）**
    - `supportsToolCall` 工具调用：✅勾选，如果该模型支持function‑call；
    - `supportsImages`图片输入（多模态识图）✅勾选仅对视觉模型；纯文本模型不要勾选；
    - `supportsReasoning`思考模式：仅深度思考模型开启；
5. 输入/输出最大token上限：按模型规格填写（如131072输入，65536输出）
6. 点【测试连接】验证连通；测试成功后保存；保存后软件自动写入本地`%USERPROFILE%\.workbuddy\models.json`配置文件。

>❗GUI新增保存之后，配置直接落盘到本地json；反过来**手动修改json之后需要完全退出托盘后台重启客户端，GUI界面才会同步刷新出来！**

## 📍方式二：直接编辑本地`models.json`批量维护多个模型（适合一次性导入一堆模型）

![](https://img.cxweixin.cn/uploads/202610/2026100521474293853.png)

### Windows路径
```
%USERPROFILE%\.workbuddy\models.json
#完整示例路径：C:\Users\Administrator\.workbuddy\models.json
```
>如果文件不存在，直接新建该文件；**编码必须保存为UTF‑8无BOM！否则读取报错，模型加载失败**

![](https://img.cxweixin.cn/uploads/202610/2026100521492016151.png)

### JSON字段释义（对应截图里面字段）
|字段|含义|
|---|---|
|`id`|模型唯一标识（同时作为调用时提交给API的model名字，**必须和后端一致！**）|
|`name`|客户端界面展示名称，一般和id保持相同即可|
|`vendor`|固定写`"Custom"`（自定义第三方OpenAI兼容）|
|`url`|中转基础接口地址：`"[https://api.cxsee.com/v1]"`|
|`apiKey`|平台密钥sk‑xxxx|
|`supportsToolCall`|`true/false` 是否支持工具调用（Agent最重要，开启之后workbuddy才可以使用MCP连接器/skill技能）|
|`supportsImages`|`true/false` 是否支持图片输入识图|
|`supportsReasoning`|`true/false` 深度思考模式|
|`useCustomProtocol`|保持`false`（普通OpenAI兼容协议不要打开自定义协议）|
|`maxInputTokens`|模型最大上下文输入token上限；`maxOutputTokens`最大输出token上限|

### 参考样例（一次性配置3个模型对接cxsee中转，和你的截图内容对齐）
```json
[
  {
    "id": "deepseek-flash",
    "name": "deepseek-flash",
    "vendor": "Custom",
    "url": "[https://api.cxsee.com/v1](https://api.cxsee.com/v1)",
    "apiKey": "sk-aAtcIOgmdCb47kphFxxxx7UXHI3",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": false,
    "useCustomProtocol": false,
    "maxInputTokens": 131072,
    "maxOutputTokens": 65536
  },
  {
    "id": "gpt-6-luna",
    "name": "gpt-6-luna",
    "vendor": "Custom",
    "url": "[https://api.cxsee.com/v1](https://api.cxsee.com/v1)",
    "apiKey": "sk-aAtcIOgmdCbkphFxxxx7UXHI3",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "useCustomProtocol": false,
    "maxInputTokens": 32768,
    "maxOutputTokens": 32768
  },
  {
    "id": "gpt-6-sol",
    "name": "gpt-6-sol",
    "vendor": "Custom",
    "url": "[https://api.cxsee.com/v1](https://api.cxsee.com/v1)",
    "apiKey": "sk-aAtcIOgmdClrkphFxxxx7UXHI3",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "useCustomProtocol": false,
    "maxInputTokens": 131072,
    "maxOutputTokens": 65536
  }
]
```
>✅编辑保存之后：**务必右键托盘图标完全退出WorkBuddy桌面客户端，重新启动软件；模型列表就加载出来了！**
>❗**不要只关闭主窗口！后台托盘进程还在运行不会重新读取json！**
>👇**最后可点击这里测试模型是否可用**

![](/uploads/editor/20261005/img_6ac3ad8b0cf5a4.28749296.png)

## ⚠️高频踩坑点（Agent调用MCP/技能经常出问题的根源）
1. **`id`字段值必须和后端中转平台上的模型名称完全一模一样！大小写敏感；写错id，调用返回model not found报错。**
2. `supportsToolCall`字段！**如果你希望这个第三方模型能够调用MCP连接器、Skill智能体工具，必须设置为true；如果关闭false，该模型无法执行Agent工具调用，只能做普通问答！（这是最容易踩坑的点，很多人接入之后Agent不会调用业务连接器就是这个开关没打开）**
3. JSON语法错误（逗号多写少写、中文符号、编码BOM）会直接导致整个models.json加载失败，所有自定义模型全部消失；编辑完建议先用JSON校验工具校验语法。
4. GUI界面编辑之后会覆盖本地models.json；如果你长期维护批量模型，优先手动维护json，不要再用GUI去修改该批模型，防止被覆盖。
5. token上限不要填的大于该模型官方规格，否则会发生上下文截断报错。

## 💡延伸（对接WorkBuddy桌面版Agent+MCP连接器）
当第三方自定义模型开启`supportsToolCall:true`之后，桌面端就可以正常调用本地MCP‑stdio技能，也可以调用远端SSE的MCP连接器，就可以完整跑本地Agent；
>⚠️注意：**桌面版本地models.json只是桌面客户端的自定义模型配置；不等于WorkBuddy开放平台（open.workbuddy.cn）云端的模型配置，二者互相独立，不要混淆！**
>桌面版是本地客户端使用第三方模型；开放平台是企业云端开发Buddy应用。

上一篇：通义千问(qwen) 视频模型格式下一篇：Gemini-TTS 语音合成 API文档