# CodeBuddy 自定义模型

> **最后核实**：2026-11-10 · 📄 依据官方文档（CodeBuddy IDE 4.12.4，2026-11-06 发布；CLI 文档对应 v2.182.0）· ✅ QCode 接入按 CodeBuddy Code CLI 2.182.0 实测（2026-11-10）

CodeBuddy 能用自己的 key：自定义模型写在 `models.json`（用户级 `~/.codebuddy/models.json`），官方写明「目前仅支持 OpenAI 接口格式的 API」。截至 2026-11-10，按 CodeBuddy Code CLI 2.182.0 实测：QCode 的 OpenAI Chat Completions（`url` 填完整路径）与 OpenAI Responses（`url` 填 base）都能用，CLI 使用这些模型不需要登录腾讯账号。IDE 部分依据官方文档。

## 接入速览

| 项目 | 说明 |
|---|---|
| 能不能用自己的 key | 能。IDE 与 CLI 都读 `models.json`；CLI 不登录即可使用（✅ 实测） |
| 可用模型 | Claude ❌（该协议不走 Anthropic 端点）· GPT ✅ · 国产 ✅ · Gemini ❌（QCode 暂不提供） |
| Chat Completions | `url`：`https://api.qcode.cc/openai/v1/chat/completions`（完整路径）· ✅ CLI 实测 |
| Responses（CLI） | `"api": "openai-responses"`，`url`：`https://api.qcode.cc/openai/v1` · ✅ CLI 实测 |
| 环境变量（CLI） | `CODEBUDDY_BASE_URL=https://api.qcode.cc/openai/v1`（OpenAI Chat）· ✅ CLI 实测 |
| 配置文件 | 用户级 `~/.codebuddy/models.json`；项目级 `<project-root>/.codebuddy/models.json` |
| 官方文档 | [IDE models.json](https://www.codebuddy.cn/docs/ide/Features/models) · [CLI models.json](https://www.codebuddy.cn/docs/cli/models) · [CLI 环境变量](https://www.codebuddy.cn/docs/cli/env-vars) |

CodeBuddy 是腾讯云的 AI 编程工具。官方产品简介写明它「同时支持插件、IDE 和 CLI 三种编程形态」：插件装进 VS Code 或 JetBrains 系列，CodeBuddy IDE 是独立 IDE，CodeBuddy Code 是命令行工具（命令 `codebuddy`）。国内站是 [codebuddy.cn](https://www.codebuddy.cn)，国际站是 [codebuddy.ai](https://www.codebuddy.ai)，两站文档里自定义模型的文件路径相同。同一个团队的办公产品 WorkBuddy 与它共用底座，配置见 [WorkBuddy 自定义模型](/docs/ide/workbuddy)。

QCode.cc 与腾讯、CodeBuddy 无隶属关系。界面与字段以你安装的版本为准。

## 用哪条协议

| 入口 | 协议 | QCode 填写值 | 可用型号 |
|---|---|---|---|
| `models.json`（IDE 与 CLI） | OpenAI Chat Completions | `url`：`https://api.qcode.cc/openai/v1/chat/completions` | GPT 与 DeepSeek / GLM / Kimi / Qwen |
| `models.json` 加 `"api": "openai-responses"`（CLI） | OpenAI Responses | `url`：`https://api.qcode.cc/openai/v1` | GPT |
| `CODEBUDDY_BASE_URL`（CLI） | OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT 与 DeepSeek / GLM / Kimi / Qwen |

这几条协议在 QCode 上可用 GPT 与国产型号。Claude 型号走 Anthropic 端点，CodeBuddy 的自定义模型不走该协议；需要 Claude 的读者请用支持 Anthropic 端点的工具，例如 [Claude Code](/docs/getting-started/installation)、[ZCode](/docs/ide/zcode) 或 [Qoder](/docs/ide/qoder)。三种协议的对照见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。中国大陆网络可以把 `api.qcode.cc` 换成 `asia.qcode.cc`，路径不变，同一把密钥通用。

## 安装 CodeBuddy Code CLI

官方安装指南给出的方式（前置要求 Node.js 18.20 或更高版本），2026-11-10 实测用的就是它：

```bash
npm install -g @tencent-ai/codebuddy-code
```

不想装 Node.js 时，官方还提供 Homebrew 与原生二进制（Beta）：

```bash
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

Windows PowerShell 用 `irm https://www.codebuddy.cn/cli/install.ps1 | iex`。装完用 `codebuddy --version` 验证（实测版本 2.182.0）。下面的自定义模型不需要登录腾讯账号即可使用。IDE 与插件到 [codebuddy.cn](https://www.codebuddy.cn) 下载，只想用 IDE 可跳过本节。

## 配置 models.json

### 文件位置

官方写明两个级别：

- 用户级：`~/.codebuddy/models.json`，全局配置，适用于所有项目
- 项目级：`<project-root>/.codebuddy/models.json`，优先级高于用户级

按优先级从高到低合并：项目级、用户级、内置默认配置。相同 `id` 的模型会被覆盖，不同 `id` 的会被追加。IDE 与 CLI 读的是同样的路径。

### CLI：最小可用 models.json（✅ 实测）

把下面内容存为 `~/.codebuddy/models.json`。第一条走 Chat Completions，第二条走 Responses，密钥从环境变量读取：

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}
```

然后导出密钥，给两个模型各发一句测试：

```bash
export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra
```

回复 `OK` 即表示该模型可用。`id` 会作为模型名发给 QCode，必须是 [qcode.cc/models](https://qcode.cc/models) 在售的型号 ID，逐字符一致。Chat 条目还可以用 `gpt-6.1-sol`、`deepseek-v4-pro`、`glm-5.3`、`kimi-k3`、`qwen3.8-max`（见 [国产模型](/docs/usage/cn-models)）；Responses 条目用 GPT 型号。各模型单价见 https://qcode.cc/models。`maxInputTokens`、`maxOutputTokens` 与图片、推理等能力项，按所选模型的实际能力填写。

### 两种 `url` 规则

Chat Completions（默认）的官方原文：「url 字段必须是接口完整路径,一般以 /chat/completions 结尾」，并列出了错误示例：

```text
❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434
```

`api` 设为 `openai-responses` 时规则相反。官方原文：「`api` 设为 `openai-responses` 后，该模型改用 OpenAI Responses API：请求发往 `{url}/responses`」，同页补充「url 填 base URL，末尾带不带 /responses 都可以」。

| `url` 写法 | 结果 |
|---|---|
| `https://api.qcode.cc/openai/v1/chat/completions` | ✅ Chat Completions（实测） |
| `https://api.qcode.cc/openai/v1` | ✅ 配 `"api": "openai-responses"`（实测）；用于 Chat 时不是完整路径 |
| `https://api.qcode.cc/api` | ❌ 那是 Anthropic Messages 的前缀，不是 OpenAI 路径 |

Responses 填 `https://api.qcode.cc/openai` 也实测通过；本文统一用 `/openai/v1`，两条目共用一个 base。官方还写明：只有模型配置里显式写出的 `api` 才会切换协议。

### CodeBuddy IDE（📄 依据官方文档）

IDE 文档写的是同样的文件路径与 Chat 字段。IDE 文档对 `apiKey` 的说明是「实际密钥值，非环境变量名」，所以要直接写密钥。IDE 用的 Chat 条目：

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}
```

IDE 的字段表里没有 `api` 字段，Responses 条目留给 CLI。IDE 与 CLI 共用同一个 `~/.codebuddy/models.json` 时，每个条目都直接写密钥；CLI 同样接受直接写入的密钥。官方提醒：不要把含真实密钥的 `models.json` 提交到版本控制，并建议把文件权限设为 600（仅所有者可读写）。

### 字段表

| 字段 | 类型 | 说明（据官方字段表） |
|---|---|---|
| `id` | string | 必填。模型唯一标识符 |
| `name` | string | 模型显示名称 |
| `vendor` | string | 模型服务方名称（官方示例为 OpenAI, Google），本文填 `QCode` |
| `apiKey` | string | API 密钥。IDE 文档写「实际密钥值，非环境变量名」；CLI 文档写「支持环境变量引用」 |
| `maxInputTokens` | number | 最大输入 token 数 |
| `maxOutputTokens` | number | 最大输出 token 数 |
| `url` | string | API 端点 URL（必须是接口完整路径，一般以 `/chat/completions` 结尾） |
| `supportsToolCall` | boolean | 是否支持工具调用 |
| `supportsImages` | boolean | 是否支持图片输入 |
| `supportsReasoning` | boolean | 是否支持推理模式 |

CLI 文档另有三个字段：`api`（请求协议，设为 `openai-responses` 时改走 Responses API）、`temperature`（采样温度，0-2）、`relatedModels`（在 lite / reasoning 等场景用哪个模型 id）。顶层的 `availableModels` 是字符串数组，只有列在其中的模型 id 才显示在下拉列表里；未配置或为空数组时显示所有模型。

### 用 `${VAR_NAME}` 引用环境变量（CLI）

CLI 文档写明 `apiKey` 和 `url` 字段支持环境变量引用语法 `${VAR_NAME}`；上面配置里 `apiKey` 的引用已实测可用。官方注意事项：环境变量在 CLI 启动时解析；如果环境变量不存在，将保留原始占位符，会导致 API 调用失败。

### 热重载

官方：配置文件支持热重载，文件变更会被自动检测，带 1 秒防抖延迟；监听的就是上面两个 `models.json`。

## CLI 环境变量

官方环境变量页列出三个与第三方模型有关的变量：

| 变量 | 官方说明 |
|---|---|
| `CODEBUDDY_API_KEY` | API 密钥。设置此密钥用于模型接口调用。在非交互模式 (-p) 下始终使用此密钥 |
| `CODEBUDDY_BASE_URL` | 覆盖 API 端点地址，通常与 `CODEBUDDY_API_KEY` 配合使用 |
| `CODEBUDDY_MODEL` | 覆盖默认代理模型 |

截至 2026-11-10，按 CodeBuddy Code CLI 2.182.0 实测：`CODEBUDDY_BASE_URL` 填的是 OpenAI Chat Completions 的 base，CLI 会在后面补 `/chat/completions`。填 `https://api.qcode.cc/openai/v1`，再选 GPT 或国产型号；这条路线不需要 `models.json`：

```bash
export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
```

`CODEBUDDY_BASE_URL` 要填到 `/openai/v1`：填 `https://api.qcode.cc/api` 时请求会发到 `/api/chat/completions`，QCode 返回 HTTP 400。

## 验证

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

```bash
KEY="cr_xxx"

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 = 路径前缀错了
```

然后：

1. CLI：运行上面的 `codebuddy -p` 测试，回复 `OK` 即成功。要交互使用，运行 `codebuddy --model deepseek-v4-flash`。
2. IDE：打开模型下拉列表。官方说明通过 `models.json` 添加的模型会自动带上 `custom` 标签，便于识别和过滤。给新模型发一句简短消息。
3. 在 [probe.qcode.cc](https://probe.qcode.cc) 输入你的密钥，可以看到这次请求和应答的模型。

## 常见问题

### 配置未生效

官方排查清单：检查 JSON 格式是否正确；确认文件路径是否正确；查看日志输出确认配置是否被加载；确认环境变量中的 API 密钥是否已设置。热重载有 1 秒防抖，确保文件确实已保存到磁盘。

### 模型没有出现在下拉列表

官方：检查模型 ID 是否在 `availableModels` 中列出，并确认 `models` 配置是否正确。注意项目级的 `availableModels` 会完全覆盖用户级，不做合并。官方故障排查段把「id, name, provider」列为必填字段，字段表则只把 `id` 标为必填、字段名写作 `vendor`；把 `id`、`name`、`vendor` 都填上，两种写法都能满足。

### 请求 404

Chat 条目的 `url` 没写到 `/chat/completions`，或误填了 `https://api.qcode.cc/api`。Chat 条目一律写完整路径 `https://api.qcode.cc/openai/v1/chat/completions`；只有带 `"api": "openai-responses"` 的条目才只写到 `/openai/v1`。

### 返回 HTTP 400 `model_not_available_on_endpoint`

`claude-…` 型号被发到了 OpenAI 路径上，例如写进了 `models.json` 的条目，或 `CODEBUDDY_BASE_URL` 填成了 `https://api.qcode.cc/api`。Claude 型号只走 Anthropic 端点，请改用 GPT 或国产型号，或换 [Claude Code](/docs/getting-started/installation) 等支持 Anthropic 协议的工具。这个错误不代表密钥有问题。

### 请求 401

密钥必须是 `cr_` 开头、无空格。用环境变量引用时，检查变量是否真的导出：官方写明不存在的变量会保留原始占位符，结果是把 `${QCODE_API_KEY}` 这串字面量当密钥发出去。

### 要先登录腾讯账号吗

用这些模型不需要。2.182.0 实测中，`codebuddy -p` 通过 `models.json` 和通过 `CODEBUDDY_BASE_URL` 都在不登录的情况下返回了结果。

### 自定义模型会带腾讯平台身份信息吗

官方 CLI v2.180.0 发布说明：「自定义模型不再携带平台身份请求头」，即直连第三方端点时，身份信息不再随请求发往你自己配置的服务。

## 相关文档

- [WorkBuddy 自定义模型](/docs/ide/workbuddy) — 同一团队的办公 Agent，同样走 OpenAI Chat Completions
- [ZCode 自定义模型接入](/docs/ide/zcode) — 自定义服务商支持 Anthropic 与 OpenAI 协议，可用 Claude
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 三种协议、三个域名与 `BASE_URL` 对照
- [国产模型接入](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen 的型号 ID
- [工具兼容总览](/docs/ide/tool-compatibility) — 各工具支持的协议与是否能用 Claude
- 实时型号与单价：[qcode.cc/models](https://qcode.cc/models)