WorkBuddy 桌面版接入第三方中转平台教程

# WorkBuddy 桌面版接入第三方中转平台

> 目标：把中转平台 `https://api.zaimod.com` 的模型挂进 WorkBuddy 桌面客户端，让它出现在「模型」列表里，并且能真正调用 MCP 连接器与技能干活。
>
> 两条路：图形界面点几下（适合零星加两三个），或者直接手改 `models.json`（适合一次灌十几个）。地址只记一句：**必须带 `/v1`，但不用自己补 `/chat/completions`**。

---

## 一、先搞清楚三件事

**接口是 OpenAI 兼容协议。** WorkBuddy 桌面版里的「自定义」供应商只认 OpenAI 兼容协议，中转平台恰好就是这种：基础地址 `https://api.zaimod.com/v1`，后面接 `/chat/completions`。

**地址只影响一处，不用纠结写法。** 填 `https://api.zaimod.com/v1` 就够，客户端发请求前会自己规范化成完整端点；填完整路径也不会重复。真正致命的是**漏掉 `/v1`**。

**能不能调工具，取决于一个勾。** `supportsToolCall` 关掉，这个模型就只能陪你聊天：MCP 连接器、技能、读写本地文件全部不可用，界面上看着"接好了"，实际是个哑巴。

三行记牢：

| 要填的东西 | 正确写法                             | 写错会怎样                                                           |
| ----- | -------------------------------- | --------------------------------------------------------------- |
| 接口地址  | `https://api.zaimod.com/v1`       | 只写 `https://api.zaimod.com` → 请求打到 `/chat/completions` → **404** |
| 模型名称  | 平台 `/v1/models` 返回的 `id` 原样复制    | 差一个字符或大小写 → **model not found**                                 |
| 令牌    | `sk-...` 原样粘贴，不带 `Bearer`、不带首尾空格 | **401 Invalid token**                                           |

---

## 二、准备：一把令牌 + 一串模型 id

### 先建令牌

平台后台 →「令牌管理」→ 新建。分组选默认档或 OpenAI 兼容档（各家叫法不同，判断标准只有一条：这个分组本身要能访问你准备用的模型）。建完复制完整 Key。

![](/uploads/editor/20261101/img_6ae655ce1ec1f6.83419061.png)

### 再查模型 id

别凭印象写模型名，直接问平台要清单：

```bash
curl https://api.zaimod.com/v1/models \
  -H "Authorization: Bearer sk-你的令牌"
```

![](/uploads/editor/20261101/img_6ae655fbb5b8a2.30447068.png)

返回的 JSON 里每个 `"id"` 就是「模型名称」该填的值。

> 本文示例中的 `gpt-4o`、`deepseek-chat`、`claude-sonnet-4-5` 只是格式示意，具体有哪些模型以你自己平台返回的清单为准。中转平台的模型池更新很快，别的教程里的名字搬过来大概率已经下架。

顺手用这个命令判断地址和令牌是否正常，返回码本身就说明问题：

| 返回    | 含义                     |
| ----- | ---------------------- |
| `200` | 地址对、令牌对，可以直接往下走        |
| `401` | 地址通了，令牌有问题（错、被禁用、分组不对） |
| `404` | 地址有问题，绝大多数是漏了 `/v1`    |

---

## 三、方式一：图形界面添加

适合零散加两三个、想边填边测的情况。

**1. 左下角头像 → 设置 → 模型**  
左侧栏「功能」分组下的「模型」，页面标题写着「自定义模型」。

![](/uploads/editor/20261101/img_6ae6562b76a975.03072134.png)

**2. 点右上角「添加模型」**  
留意这行说明：「模型添加后会自动写入到本地 `%USERPROFILE%\.workbuddy\models.json` 文件中」。这句话很重要，它说明 GUI 只是这个 json 的编辑器，两者是同一份配置。

**3. 供应商选「自定义」**  
下拉里其实只有「自定义」一项，副标题写着「仅支持 OpenAI 兼容协议 API」，不用找别的选项。

![](/uploads/editor/20261101/img_6ae6563572d618.86460361.png)

**4. 填三个框**

- **接口地址**：`https://api.zaimod.com/v1`
- **API Key**：`sk-` 开头的令牌，右边小眼睛可以核对有没有粘进空格
- **模型名称**：上一步查到的 `id`，例如 `gpt-4o`

![](/uploads/editor/20261101/img_6ae65663f2e922.09954834.png)

**5. 勾高级配置**

四个勾选框，决定这个模型在客户端里能干什么：

| 勾选项   | 什么时候勾                             | 勾错的后果                       |
| ----- | --------------------------------- | --------------------------- |
| 工具调用  | 模型支持 function call（主流对话模型都支持）     | 不勾：Agent 不会调用 MCP 与技能，只能纯聊天 |
| 图片输入  | 只有视觉模型勾                           | 纯文本模型勾了，带图对话直接 400          |
| 思考模式  | 只有推理模型（带 thinking / reasoning 的）勾 | 模型不支持却勾了，可能报参数错误            |
| 自定义协议 | 基本永远不勾                            | 勾了地址原样发送、不再自动补端点，普通中转直接 404 |

**6. 填 token 上限 → 测试连接 → 保存**

输入、输出两个框都留空就是「使用提供商默认值」，最省事。要填就按模型真实规格填，框下面还有 `32K / 64K / 128K / 256K` 与 `8K / 16K / 32K / 64K` 的快捷档。

填超规格的后果不是当下报错，而是在长对话里突然截断——很难排查，所以不确定就留空。

---

## 四、保存之后，文件里发生了什么

点下「保存」的一瞬间，这条模型就写进了 `models.json`，而且地址被**规范化**过了：

```json
{
  "id": "gpt-4o",
  "name": "gpt-4o",
  "vendor": "Custom",
  "url": "https://api.zaimod.com/v1/chat/completions",
  "apiKey": "sk-...",
  "supportsToolCall": true,
  "supportsImages": true,
  "supportsReasoning": false,
  "useCustomProtocol": false,
  "maxInputTokens": 131072,
  "maxOutputTokens": 32768
}
```

注意 `url` 末尾的 `/chat/completions` 是软件自己加的，你在界面里只填了 `.../v1`。规范化按这个顺序走：

1. 去掉地址末尾所有 `/`
2. 如果结尾是 `/chat/completions`，先剪掉
3. 再统一追加一个 `/chat/completions`

所以 `.../v1`、`.../v1/`、`.../v1/chat/completions` 三种写法最后都落到同一个地址，不会出现 `/chat/completions/chat/completions`。**但它不会替你补 `/v1`**，第 2 步只会剪不会加。

> 这也解释了一类经典困惑：抄别人的 json 时看到 `url` 是 `.../v1/chat/completions`，以为接口地址必须写到这么细，于是手改时只写了域名 `https://api.zaimod.com`，结果 404。记住：**`/v1` 必须有，`/chat/completions` 可有可无**。

![](/uploads/editor/20261101/img_6ae6567be132c0.19287014.png)

---

## 五、方式二：直接手改 models.json

一次要灌十个八个模型时，界面上一个个点太慢，直接编辑文件更快。列表里每条右边的铅笔图标点开就是同一个表单，两种方式是等价的。

### 文件在哪

| 情况            | 路径                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------- |
| Windows       | `%USERPROFILE%\.workbuddy\models.json`，如 `C:\Users\Administrator\.workbuddy\models.json` |
| macOS / Linux | `~/.workbuddy/models.json`                                                               |
| 改过配置目录        | 环境变量 `WORKBUDDY_CONFIG_DIR` 指向哪就在哪                                                       |
| 装过多个实例        | 可能是 `~/.workbuddy-2`、`~/.workbuddy-3`（带实例号后缀）                                            |

文件不存在就自己新建，**编码必须是 UTF-8 无 BOM**。带 BOM 会让整份配置解析失败，界面上所有自定义模型一起消失，看着像被谁删了。

![用 VS Code 编辑 models.json：注意 url 与 apiKey 都是普通字符串](images/workbuddy/06-json-editor.png)

### 根结构

两种写法都认，用数组最省事：

```json
[ { "id": "..." }, { "id": "..." } ]
```

也可以包一层对象：

```json
{ "models": [ { "id": "..." } ] }
```

### 字段释义

| 字段                  | 必填 | 含义与注意                                                                        |
| ------------------- | -- | ---------------------------------------------------------------------------- |
| `id`                | 是  | 模型唯一标识，同时就是发给接口的 `model` 值，**必须与平台一致，大小写敏感**                                 |
| `name`              | 否  | 界面显示名，一般跟 `id` 填一样                                                           |
| `vendor`            | 是  | 固定 `"Custom"`，表示自定义 OpenAI 兼容供应商                                             |
| `url`               | 是  | `https://api.zaimod.com/v1` 即可，写成完整 `/v1/chat/completions` 也行，**但一定要带 `/v1`** |
| `apiKey`            | 是  | 平台令牌 `sk-...`，不要带 `Bearer` 前缀                                                |
| `supportsToolCall`  | 否  | `true` 才能调用 MCP 连接器与技能，Agent 干活的前提                                           |
| `supportsImages`    | 否  | 视觉模型才 `true`；纯文本模型开了会误发图片导致报错                                                |
| `supportsReasoning` | 否  | 深度思考模型才 `true`                                                               |
| `useCustomProtocol` | 否  | 普通 OpenAI 兼容必须 `false`；`true` 时地址原样发送，不做任何补全                                 |
| `maxInputTokens`    | 否  | 上下文输入上限；不填等于用提供商默认值                                                          |
| `maxOutputTokens`   | 否  | 单次输出上限；同样可留空                                                                 |

还有两个可选字段偶尔有用：`onlyReasoning`（`true` 表示该模型只能思考模式、不允许关闭）和 `temperature`（默认采样温度）。

### 一份能直接用的小样

```json
[
  {
    "id": "gpt-4o",
    "name": "gpt-4o",
    "vendor": "Custom",
    "url": "https://api.zaimod.com/v1",
    "apiKey": "sk-替换成你自己的令牌",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": false,
    "useCustomProtocol": false,
    "maxInputTokens": 131072,
    "maxOutputTokens": 32768
  },
  {
    "id": "deepseek-chat",
    "name": "deepseek-chat",
    "vendor": "Custom",
    "url": "https://api.zaimod.com/v1",
    "apiKey": "sk-替换成你自己的令牌",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "useCustomProtocol": false,
    "maxInputTokens": 65536,
    "maxOutputTokens": 8192
  },
  {
    "id": "claude-sonnet-4-5",
    "name": "claude-sonnet-4-5",
    "vendor": "Custom",
    "url": "https://api.zaimod.com/v1",
    "apiKey": "sk-替换成你自己的令牌",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false,
    "maxInputTokens": 200000,
    "maxOutputTokens": 64000
  }
]
```

三条都用了同一个地址、同一个 key，区别只在能力开关和 token 上限——这正是"一个平台接多个模型"的正常写法，不需要每个模型单独建令牌。

> 手写 JSON 的三个死法：多一个逗号、用了中文引号 `“”`、把地址写成 Markdown 链接格式 `[https://...](https://...)`。第三种是从网页复制粘贴时最常见的，JSON 里只认裸字符串。

### 不想把令牌明文写在文件里

`apiKey` 和 `url` 都支持 `${变量名}` 占位，客户端启动时从系统环境变量取值：

```json
"apiKey": "${CXHAO_API_KEY}"
```

设好环境变量后完全退出客户端再启动。取不到值时，`${CXHAO_API_KEY}` 会被原样当成密钥发出去，结果就是 401——看到 401 先怀疑变量名拼错了，或者环境变量改了没重启。

### 一次批量生成

Windows 自带 PowerShell，改 `$ids` 一行就能刷新整份配置：

```powershell
$ids = 'gpt-4o','deepseek-chat','claude-sonnet-4-5'
$list = foreach ($i in $ids) {
  [ordered]@{
    id = $i; name = $i; vendor = 'Custom'
    url = 'https://api.zaimod.com/v1'
    apiKey = $env:CXHAO_API_KEY
    supportsToolCall = $true; supportsImages = $false; supportsReasoning = $false
    useCustomProtocol = $false
    maxInputTokens = 131072; maxOutputTokens = 32768
  }
}
$out = "$env:USERPROFILE\.workbuddy\models.json"
[IO.File]::WriteAllText($out, (ConvertTo-Json -InputObject @($list) -Depth 5),
  (New-Object System.Text.UTF8Encoding($false)))
```

最后一行特意用 .NET 写入并传 `$false`（表示不要 BOM）。很多人用 `Out-File` 或重定向写 json，结果带上了 BOM，客户端读不出来，还以为脚本写坏了。

---

## 六、生效与验证

**1. 让客户端重新读配置**

保存后回「模型」页看看有没有出现。没出现就**右键托盘图标 → 退出**，再重新启动。

只点窗口右上角的 × 关不掉它，托盘进程还在后台跑，读的仍是旧配置——这是"改了没反应"最常见的原因。

**2. 点列表里的「测试连接」**

每行右侧三个图标：铅笔=编辑、链环=测试连接、垃圾桶=删除。点链环，右上角会弹绿色「连接成功」。

![](/uploads/editor/20261101/img_6ae656aeb38572.28144663.png)

这个测试只验证"地址+Key 能连上、模型存在"，**不代表**长上下文和工具调用可用，所以别只看这一下。

**3. 真跑一句话**

新建任务，把模型切到刚加的那个，问一句简单问题。能正常回话，才算真正接通。

**4. 验证工具调用**

直接给它派活："列出当前工作目录下的文件"。它真的去读目录，说明 `supportsToolCall` 生效；如果只是文字描述、或者提示不支持工具，就是没开或没重启。

---

## 七、高频踩坑

**1. 地址漏了 `/v1`**

最高频。`https://api.zaimod.com` 会被拼成 `https://api.zaimod.com/chat/completions`，平台没有这个路由，返回 404，而界面上只会说连接失败。

**2. `id` 和平台不一致**

大小写敏感；带日期后缀的模型（`xxx-2025-09-29`）少写日期就是另一个模型。别手打，`/v1/models` 里复制。

**3. `supportsToolCall` 没打开**

模型接上了、也能聊天，但 Agent 什么都不会做，十个里有九个是漏了这个勾。改完记得重启。

**4. JSON 一个字符错，整份配置全消失**

逗号、中文引号、BOM 任意一条踩中，整个文件解析失败，所有自定义模型从界面消失。改完先过一遍 JSON 校验再重启。

**5. GUI 和手改互相覆盖**

GUI 的增删操作会重写整个文件，你顺手加的私有字段可能没了；反过来手改之后再用 GUI 编辑同一批，格式也可能被整理。原则：**批量维护的那批模型只用文件维护，别再交给 GUI 动**。

**6. token 上限拍脑袋填**

填得比模型真实规格大，长对话会被静默截断或直接报上下文超限。不确定就留空用默认值。

**7. 一个模型配一把令牌**

没必要，还容易改漏。同一平台一把令牌能访问它分组下的所有模型，全篇用同一把就行。

---

## 八、排错速查

| 现象                          | 原因                           | 处理                              |
| --------------------------- | ---------------------------- | ------------------------------- |
| 保存时提示「接口地址仅支持 HTTP 或 HTTPS」 | 地址里混进了空格、中文括号或 Markdown 链接符号 | 只粘纯地址，以 `https://` 开头           |
| 测试连接 401                    | 令牌错、被禁用、或该分组无权访问此模型          | 重新复制令牌；核对分组                     |
| 测试连接 404                    | 地址漏了 `/v1`，或写了 `/v1/v1`      | 统一改成 `https://api.zaimod.com/v1` |
| 报 model not found / 模型不存在   | `id` 与平台不一致                  | 从 `/v1/models` 复制原始 id          |
| 连接成功，但一对话就 400              | token 上限超过模型规格               | 清空输入/输出两框，用默认值                  |
| 模型列表整块空掉                    | JSON 语法错、BOM、逗号问题            | 校验语法，另存为 UTF-8 无 BOM            |
| 能聊天但不调工具、不用技能               | `supportsToolCall` 为 `false` | 改 `true` 后彻底重启                  |
| 发图片报错                       | 纯文本模型勾了图片输入，或视觉模型忘了勾         | 按模型能力重新设置                       |
| 改完文件没反应                     | 只关了窗口，托盘进程还在                 | 右键托盘退出后重开                       |
| 有多个 WorkBuddy 实例，改了不生效      | 改的是另一个实例的目录                  | 确认路径带实例号后缀的那个                   |

---

## 九、延伸

### 桌面版自定义模型 ≠ 开放平台

`models.json` 只是**本地客户端**的自定义模型配置。WorkBuddy 开放平台（云端开发 Buddy 应用）的模型配置是另一套体系，两者互不同步，别把本地这份当成云端配额。

### 把工具调用打通之后能多做什么

`supportsToolCall: true` 之后，桌面端就能调本地 stdio 的 MCP、远端 SSE 的 MCP，也能跑技能，这才算把 Agent 跑起来：读文件、查资料、执行命令、生成交付物都靠这条链路。所以选模型时，"聊天好不好"和"工具调用稳不稳"要分开看。

### 模型怎么选

| 场景             | 建议                               |
| -------------- | -------------------------------- |
| 日常问答、改文案       | 便宜的中小模型，输出 token 上限给够            |
| 长文档、读代码库       | 上下文 128K 以上的模型，输入上限别虚标           |
| Agent 多步任务、调工具 | 挑工具调用稳的旗舰款，`supportsToolCall` 必开 |
| 看图、截图排错        | 必须勾图片输入的视觉模型                     |
| 复杂推理、数学        | 勾思考模式，输出上限放宽                     |

### 安全提醒

- `models.json` 里默认是**明文密钥**，介意就用 `${环境变量}` 占位
- 别把这份文件丢进 Git 仓库，也别整份截图外发（截图前遮掉 `apiKey`）
- 令牌泄漏了直接去平台后台删掉重建，比在本地反复改快

上一篇：获取API接口地址与密钥{else}上一篇：没有了下一篇：API 密钥令牌查询及兑换{else}下一篇：没有了