# WorkBuddy 集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（WorkBuddy 5.5.6（官网 2026-09 查阅；Win10+ / macOS 12+，无 Linux 桌面包））

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ❌（自定义模型仅 OpenAI Chat Completions）· GPT ✅ · 国产 ✅ · Gemini ❌ |
| 协议与 Base URL | OpenAI Chat：接口地址填 `https://api.qcode.cc/openai/v1` |
| 配置位置 | 应用内：设置 → 模型 → 自定义模型（高级工具分组） |
| 官方文档 | [codebuddy.cn/work](https://www.codebuddy.cn/work/) |

[WorkBuddy](https://www.codebuddy.cn/work/) 是腾讯云推出的桌面 AI 智能体，偏办公交付（纪要、表格、PPT、轻度代码），和 [CodeBuddy](https://www.codebuddy.cn/docs)（IDE / CLI 编程助手）同属一个产品族。它**不是** Claude Code 的替代品：仓库级重构、测试、CI 仍应走 [Claude Code](/docs/getting-started/installation) 或 [Codex CLI](/docs/ide/codex)。

本文只讲一件事：把 QCode.cc 配成 WorkBuddy 的**自定义模型**，让同一把 `cr_` 密钥在 WorkBuddy 里调用我们在售的 GPT / GLM / Kimi / DeepSeek / Qwen。

> **🔴 WorkBuddy 用不了 Claude 模型。** WorkBuddy 的自定义模型只支持 **OpenAI Chat Completions**
> 协议，而 QCode 的 OpenAI 腿**不接受 Claude 模型**（填 `claude-…` 会返回
> `model_not_available_on_endpoint`）。因此在 WorkBuddy 里可以正常使用 **GPT 系与国产四家族**，
> 但不能使用 Claude。要用 Claude，请改用支持 Anthropic 协议的客户端 ——
> [Claude Code](/docs/getting-started/installation)、[Cline](/docs/ide/cline)、
> [Zed](/docs/ide/zed) 等。详见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

QCode.cc 与腾讯、WorkBuddy、CodeBuddy 均无隶属关系。界面文案以你安装的 WorkBuddy 版本为准；字段含义以 [官方模型配置](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model) 为准。

## 前置条件

- 已安装 WorkBuddy（Windows 10+ / macOS 12+，无 Linux 桌面包；官网：[codebuddy.cn/work](https://www.codebuddy.cn/work/)；安装步骤见官方 [Mac](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Installation-Mac-Guide) / [Windows](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Installation-Win-Guide) 指南）
- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- 同一把 Key 三种协议都能用。WorkBuddy 的自定义模型走 **OpenAI Chat Completions**，对应 QCode 的 `/openai/v1/chat/completions`。协议与 `BASE_URL` 口径见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)

## 用图形界面接入（推荐）

官方模型页写明：自定义模型应通过设置页的可视化界面添加，**不必手改配置文件**。腾讯云 TokenHub 的 WorkBuddy 接入说明也是同一条路径。

1. 启动 WorkBuddy → 左下角账户 → **设置**
2. 左侧选 **模型** → 自定义模型里点 **添加模型**
3. 提供商选 **自定义 / Custom**
4. 按表填写后保存，再在对话页的模型选择器里选中刚加的模型

| 字段 | 填写值 | 说明 |
|------|--------|------|
| 提供商 | `自定义` / `Custom` | 不要选腾讯云 Token Plan 等内置套餐 |
| 接口地址 | `https://api.qcode.cc/openai/v1` | 中国大陆优先 `https://asia.qcode.cc/openai/v1` |
| API Key | 你的 QCode.cc 密钥（`cr_` 开头） | 不要带前后空格 |
| 模型名称 | 例如 `gpt-6-sol` | 必须是 [qcode.cc/models](https://qcode.cc/models) 上的真实 id，逐字符一致 |
| 高级工具 | 按需勾选「工具调用」「图片输入」「推理模式」 | TokenHub 官方示例建议按任务需要勾选，不是强制 |

同一把 Key 可以加多条自定义模型，只改「模型名称」，接口地址和 Key 保持不变。例如再加一条 `glm-5.2`、一条 `deepseek-v4-pro`。

### 接口地址怎么填（自定义协议）

官方「自定义协议」开关的行为是：

| 开关 | 行为 |
|------|------|
| 关闭（默认） | 使用标准 `/chat/completions` 路径，自动校验并补全接口地址 |
| 开启 | 按你填写的 URL **原样**发请求，跳过路径校验与自动补全 |

因此默认应填到 `/openai/v1` 为止（与 [环境变量配置](/docs/getting-started/environment) 里 OpenAI 兼容工具的 `OPENAI_BASE_URL` 一致），让 WorkBuddy 自己补 `/chat/completions`。

- **不要**在默认关着「自定义协议」时把地址写成 `.../openai/v1/chat/completions`，可能被再拼一次路径而 404
- 如果默认补全后请求失败，再按 TokenHub 官方示例的写法，把完整地址 `https://api.qcode.cc/openai/v1/chat/completions` 填进去，并**打开**「自定义协议」
- **末尾不要带 `/`**，原因与其它 SDK 相同：多一个斜杠会拼出 `//chat/completions`

三个接入域业务能力相同，只是网络路由不同。同一把 Key 通用：

| 节点 | 接口地址（自定义协议关闭时） |
|------|------------------------------|
| 国际（Route 53） | `https://api.qcode.cc/openai/v1` |
| 亚洲（大陆推荐） | `https://asia.qcode.cc/openai/v1` |
| 北美 / 欧洲 | `https://us.qcode.cc/openai/v1` |

### 配置存在哪、会不会上传

官方说明：

- 配置参数（含 API Key）只保存在本地 `workbuddy/models.json`，**不上传云端**
- 旧版通过 `~/.codebuddy/models.json` 配过的自定义模型，界面升级后仍可用，并可以在 UI 里查看 / 编辑 / 删除
- 自定义模型产生的 Token 费用由你向第三方（这里是 QCode.cc）支付，不走 WorkBuddy 内置积分

本页**不提供**手写 `models.json` 的字段模板。官方已改为 UI 为主；字段名以你本机版本和 [官方模型配置](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model) 为准。需要批量改时，先在 UI 里加一条，再对照本地文件，不要从第三方博客抄 schema。

## 推荐先配哪些模型

下列 id 于 2026-09-18 经 [qcode.cc/models](https://qcode.cc/models) 与 `GET https://api.qcode.cc/api/v1/models` 两处交叉确认。单价不在本页复制，**以 qcode.cc/models 实时值为准**（管理员可调费率）。

| 模型 id | 适合 |
|-----------|------|
| `gpt-5.6-terra` | GPT 系日常档 |
| `glm-5.2` | 智谱旗舰，中文办公常见 |
| `kimi-k3` | 月之暗面旗舰，长上下文 |
| `deepseek-v4-pro` | DeepSeek 旗舰，单价最低的一档之一 |
| `qwen3.8-max` | 通义旗舰 |

同族里还有更轻的 `glm-5.3-flash`、`deepseek-v4-flash`、`deepseek-v4.1-flash`、`qwen3.8-flash`、`qwen3.7-plus`，当前都在售；上一代的 `glm-5.1` 与 `kimi-k2.6` 已下架，填了会报错。选型原则见 [模型选择指南](/docs/usage/model-selection)；不要把未出现在 [qcode.cc/models](https://qcode.cc/models) 上的名字填进「模型名称」。

WorkBuddy 这条链路走 OpenAI Chat Completions，**不要**把 `ANTHROPIC_BASE_URL`（`https://api.qcode.cc/api`）填进接口地址——那是 Claude Code / Anthropic SDK 用的前缀。

## 验证

先确认 QCode 的 OpenAI 路径对你的网络是通的（与 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) 第 4 节同一条自测）：

```bash
KEY="cr_你的密钥"

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# → 400 = 路径与密钥都通（缺请求体属预期）；401 = 密钥无效；404 = 路径前缀错了
```

中国大陆把主机换成 `asia.qcode.cc` 再测一次。然后回到 WorkBuddy，选中刚加的模型发一句「ping」。能收到回复即接入成功。

路径通但 WorkBuddy 仍报错时，按上一节核对：接口地址有没有多余的 `/chat/completions` 或尾斜杠、自定义协议开关是否与填写方式匹配、模型 id 是否逐字符等于上表。

## 常见问题

### 保存后模型选择器里看不到

自 v5.1.1 起官方说明模型配置支持热更新，通常保存即生效；若选择器里仍没有，完全退出 WorkBuddy（不要只关窗口留托盘）再打开，并到设置 → 模型里确认这条自定义模型没有被删。

### 请求 404

1. 自定义协议**关闭**时，接口地址填 `https://api.qcode.cc/openai/v1`，不要自己加上 `/chat/completions`
2. 自定义协议**开启**时，填完整 `https://api.qcode.cc/openai/v1/chat/completions`
3. 末尾不要 `/`
4. 不要误填 `https://api.qcode.cc/api`（那是 Anthropic Messages 前缀）

### 请求 401

密钥必须是 `cr_` 开头、无空格。到 [qcode.cc/dashboard](https://qcode.cc/dashboard) 确认密钥有效。WorkBuddy 把 Key 存在本地，换 Key 后要回到这条自定义模型里改，不会自动同步。

### 模型名填了但回复很怪 / 直接失败

「模型名称」必须是本端点在售 id，例如 `gpt-5.6-terra`，不是展示名「GPT 5.6 Terra」，也不是其它平台的别名。实时清单：[qcode.cc/models](https://qcode.cc/models) 或带密钥 `GET https://api.qcode.cc/openai/v1/models`（**这条列表才是 WorkBuddy 能填的集合**，不含 Claude）。

### 会不会把对话上传给腾讯？

官方模型页的口径：WorkBuddy 在自定义模型场景下是通信链路，把输入转发到你配置的第三方；API Key 仅本地保存。具体以 [官方模型配置](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model) 和腾讯用户协议为准。发到 QCode 的请求可在 [probe.qcode.cc](https://probe.qcode.cc) 用同一把 Key 查看。

### WorkBuddy 能替代 Claude Code 吗？

不能当作一对一替换。WorkBuddy 优化办公多 Agent 交付；Claude Code / Codex 优化仓库内编码循环。可以同时用：办公文档走 WorkBuddy，改代码走 [CC Switch](/docs/ide/cc-switch) 切到的 Claude Code，两套工具共用一把 QCode Key，配额规则见 [计费说明](/docs/reference/billing)。

## 下一步

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 三种协议、三个域名、`BASE_URL` 对照
- [CC Switch 配置](/docs/ide/cc-switch) — 在 Claude Code / Codex 之间切换同一把 Key
- [模型选择指南](/docs/usage/model-selection) — 日常默认用哪一档
- [计费说明](/docs/reference/billing) — 套餐与配额
- 实时型号与单价：[qcode.cc/models](https://qcode.cc/models)

> 还没有 QCode.cc API Key？前往 [qcode.cc/pricing](https://qcode.cc/pricing) 选套餐。