CodeBuddy 自定义模型

CodeBuddy 用 models.json 接入 QCode.cc：CLI 2.182.0 实测 Chat 与 Responses 可用、无需登录，附 JSON 与环境变量。

需要 API Key？ 前往注册 →·端点与 Base URL →

最后核实：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 部分依据官方文档。

接入速览¶

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

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

用哪条协议¶

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

安装 CodeBuddy Code CLI¶

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

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

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

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 下载，只想用 IDE 可跳过本节。

配置 models.json¶

文件位置¶

官方写明两个级别：

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

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

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

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

{
  "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"]
}

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

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 在售的型号 ID，逐字符一致。Chat 条目还可以用 gpt-6.1-sol、deepseek-v4-pro、glm-5.3、kimi-k3、qwen3.8-max（见 国产模型）；Responses 条目用 GPT 型号。各模型单价见 https://qcode.cc/models。maxInputTokens、maxOutputTokens 与图片、推理等能力项，按所选模型的实际能力填写。

两种 url 规则¶

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

❌ 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 都可以」。

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

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

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

{
  "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（仅所有者可读写）。

字段表¶

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 环境变量¶

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

截至 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：

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 格式 的自测同一条）：

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 输入你的密钥，可以看到这次请求和应答的模型。

常见问题¶

配置未生效¶

官方排查清单：检查 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 等支持 Anthropic 协议的工具。这个错误不代表密钥有问题。

请求 401¶

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

要先登录腾讯账号吗¶

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

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

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

相关文档¶

• WorkBuddy 自定义模型 — 同一团队的办公 Agent，同样走 OpenAI Chat Completions
• ZCode 自定义模型接入 — 自定义服务商支持 Anthropic 与 OpenAI 协议，可用 Claude
• 接入点与 API 格式 — 三种协议、三个域名与 BASE_URL 对照
• 国产模型接入 — GLM / Kimi / DeepSeek / Qwen 的型号 ID
• 工具兼容总览 — 各工具支持的协议与是否能用 Claude
• 实时型号与单价：qcode.cc/models

企业团队版 →