# 用 models.json 把 Router One 模型添加到 CodeBuddy

> https://router.one/zh/integrations/codebuddy 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-27

CodeBuddy（腾讯云代码助手）的 CodeBuddy Code 命令行工具和 CodeBuddy IDE 都从 models.json 读取自定义模型。每个条目写明模型 ID、API 密钥和 url；url 必须是完整的接口路径，自定义模型目前只支持 OpenAI 接口格式。把 url 设为 https://api.router.one/v1/chat/completions、id 设为 Router One 目录中的模型 ID，CodeBuddy 就会用你的 Key 把这个模型的请求发到 Router One：目录中的全部对话模型（包括 Claude 与 GPT）都通过这个端点提供。按 CodeBuddy Code 2.158.0（2026-09-24 发布）与 CodeBuddy 的 models.json 文档核对（2026-09-27）。

## models.json 放在哪里，哪些 CodeBuddy 产品会读取

CodeBuddy 会把最多两个文件合并到内置配置之上：id 相同的条目以项目级文件为准；项目级的 availableModels 会整体替换用户级列表，不做合并。两个文件保存后约 1 秒自动重新加载，通过 models.json 添加的模型在列表中带 custom 标签。CLI 与 IDE 读取的路径相同，但有一个字段不同：CLI 启动时会解析 apiKey 与 url 中的 ${VAR} 环境变量引用，而 IDE 文档写明 apiKey 要填实际的密钥值，不能填环境变量名。CLI 用 npm install -g @tencent-ai/codebuddy-code 安装（需要 Node.js 18.20 或更高版本）；再在控制台创建一把专用、设了 maxSpend 的 Router One Key，并从 /models 复制对话模型 ID。

| 文件 | 作用范围 | 读取的产品 |
| --- | --- | --- |
| ~/.codebuddy/models.json | 用户级：适用于所有项目 | CodeBuddy Code 与 CodeBuddy IDE |
| <项目根目录>/.codebuddy/models.json | 项目级：覆盖用户级中 id 相同的条目 | CodeBuddy Code 与 CodeBuddy IDE |

## 在 models.json 中添加 Router One 模型：url 填完整接口路径

在 models 下为每个 Router One 模型添加一个条目：id 填精确的目录 ID，url 填 https://api.router.one/v1/chat/completions，apiKey 填专用 Key（在 CLI 中可以写成 ${ROUTER_ONE_API_KEY} 这样的引用，避免把密钥明文写进文件）。maxInputTokens 和 maxOutputTokens 由你自己设定；只有模型详情页列出工具调用和图片输入时，才把 supportsToolCall、supportsImages 设为 true；不要写 temperature。保存文件后，在 CLI 中用 codebuddy --model anthropic/claude-sonnet-5 启动，或在 /model 中选择；在 IDE 中从模型下拉列表里选择。下面的示例为主模型搭配了一个更便宜的 lite 模型来处理后台请求（见下文 relatedModels 一节）：

`models.json`

```json
{
  "models": [
    {
      "id": "anthropic/claude-sonnet-5",
      "name": "Claude Sonnet 5 (Router One)",
      "url": "https://api.router.one/v1/chat/completions",
      "apiKey": "sk-your-router-one-key",
      "maxInputTokens": 200000,
      "maxOutputTokens": 16000,
      "supportsToolCall": true,
      "supportsImages": true,
      "relatedModels": { "lite": "anthropic/claude-haiku-4.5" }
    },
    {
      "id": "anthropic/claude-haiku-4.5",
      "name": "Claude Haiku 4.5 (Router One)",
      "url": "https://api.router.one/v1/chat/completions",
      "apiKey": "sk-your-router-one-key",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8000,
      "supportsToolCall": true,
      "supportsImages": true
    }
  ]
}
```

## url 字段该怎么填

CodeBuddy 文档要求 url 是完整的接口路径，一般以 /chat/completions 结尾，并把 https://api.openai.com/v1 这类基础地址列为错误示例。CodeBuddy Code 2.158.0 的源码会规范化自定义模型的 url：先去掉末尾的斜杠和重复的后缀，再保证它只以一个 /chat/completions 结尾；它不会补 /v1，所以只填主机根地址 https://api.router.one 会变成 https://api.router.one/chat/completions，这不是 Router One 文档中的端点。自 2.155.0 起，没有配置 url 的自定义模型会在发出请求前直接报错并提示补全，而不是发往 CodeBuddy 自己的平台网关。自定义模型只支持 OpenAI 接口格式，这对 Router One 已经足够：目录中的全部对话模型，包括 Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID，都通过 POST /v1/chat/completions 提供。gpt-image-2 这类图片生成 ID 不是对话模型，不要加进 models.json。

## 后台与子代理请求：设置 relatedModels

CodeBuddy Code 在一次会话中会按场景切换模型：lite 变体处理后台提取、摘要等轻量请求，Agent 工具请求 lite 时也用它；reasoning 变体处理需要深度思考的推理。Explore 等内置子代理声明使用 lite。按 CodeBuddy 文档，通过 models.json 添加的自定义模型不会继承产品内置的 defaultRelatedModels：如果主模型没有声明 relatedModels，也没有环境变量或 variantModels 覆盖，lite 和 reasoning 都会回退到主模型，这些后台请求和 Explore 请求都会按主模型的价格计费。把 relatedModels.lite 指向同一文件中定义的一个更便宜的 Router One ID，例如详情页列出工具调用的 anthropic/claude-haiku-4.5。同样的映射也可以用优先级更高的 CODEBUDDY_SMALL_FAST_MODEL（lite）和 CODEBUDDY_BIG_SLOW_MODEL（reasoning）设置，或用 /model:lite、/model:reasoning 保存到 settings.json 的 variantModels；CODEBUDDY_CODE_SUBAGENT_MODEL 会统一覆盖所有内置子代理的模型。文档注明 subagent、vision、longContext 三个变体目前预留、尚未启用。会话结束后，可以在控制台 → 日志中按模型查看每个请求的 Token、花费、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT），确认有多少请求走了 lite 模型。

## Token 上限、temperature 与能力标记

这几个字段决定 CodeBuddy 为该模型发出的每个请求：

- maxInputTokens：CodeBuddy Code 自动压缩上下文时参照的窗口。按其更新日志，未配置时自定义模型会退回默认的自动压缩窗口，自 2.98.0 起为 200k tokens。请填不超过模型详情页上下文窗口的值（anthropic/claude-sonnet-5 为 1,048,576 tokens，anthropic/claude-haiku-4.5 为 200,000）；值越大，压缩前每次请求可带的计费输入越多。
- maxOutputTokens：你自己设定的单次输出上限。自 2.119.1 起，自定义模型没有配置这一项时，CodeBuddy Code 不再把内置目录中的能力上限当作每次请求的额度，所以请按需填写。
- temperature：不要写。自 2.128.0 起，自定义模型未配置 temperature 时 CodeBuddy 不再发送该字段，可避免 GPT-5 等只接受默认值的模型返回 400。
- supportsToolCall 与 supportsImages：只有模型详情页列出工具调用和图片输入时才设为 true。优先选详情页列出工具调用的 ID；其他 ID 先试一次工具调用。

## CodeBuddy 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 CodeBuddy 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

## CodeBuddy 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在请求日志里核对 CodeBuddy 的调用

先在 CodeBuddy 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### CodeBuddy 能用 Router One 的 Anthropic Messages 端点调用 Claude 吗？

通过 models.json 不能。CodeBuddy 文档写明，自定义模型目前只支持 OpenAI 接口格式，url 要填完整的 /chat/completions 路径。这对 Claude 已经够用：Router One 在 POST /v1/chat/completions 上提供 anthropic/claude-sonnet-5 等 Claude 系列 ID，也提供 GPT、Gemini、Grok 与 DeepSeek 的 ID。Router One 的 Messages 端点 POST https://api.router.one/v1/messages 面向 Claude Code 这类基于 Anthropic 格式的客户端。

### 能不能用 CODEBUDDY_BASE_URL 和 CODEBUDDY_API_KEY 代替 models.json？

本指南不采用这种方式，因为环境变量文档没有明确协议和路径格式：CODEBUDDY_BASE_URL 被描述为覆盖 API 端点地址，一个示例用以 /v1 结尾的地址，另一个标注为 Anthropic 协议的 DeepSeek 示例则用主机根地址。models.json 对格式和 url 字段都有明确说明，是接入 Router One 更可靠的方式。模型相关的设置仍可配合使用：用 codebuddy --model 选择 models.json 中定义的主模型，用 CODEBUDDY_SMALL_FAST_MODEL、CODEBUDDY_BIG_SLOW_MODEL 覆盖 lite 与 reasoning 变体。

### Router One 的模型没出现在 CodeBuddy 的模型列表里，应该查什么？

先检查 JSON 语法和文件路径，再看 availableModels：设置之后只显示其中列出的 ID，而且项目级列表会整体替换用户级列表。项目级文件中 id 相同的条目会覆盖用户级条目。在 CLI 中，apiKey 或 url 引用的环境变量如果没有设置，会保留原始占位符，导致请求失败；在 IDE 中，apiKey 必须是密钥本身。保存后约 1 秒生效。如果模型已显示但请求返回 401，请重新复制 Key；返回 400 并提示 must be called via，说明这个 ID 不在 Chat Completions 上提供，请换一个详情页列出 POST /v1/chat/completions 的 ID。

### CodeBuddy 能通过网关用哪些模型？

选用当前目录中同时支持 CodeBuddy 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到控制台 → 日志核对这条请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- CodeBuddy 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- Claude Code 国内配置：使用 Anthropic 格式的客户端：https://router.one/zh/claude-code-china
- Qwen Code 接入：可自填 base URL 的终端 Agent：https://router.one/zh/integrations/qwen-code
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- CodeBuddy Code 官方文档：models.json 配置指南：https://www.codebuddy.ai/docs/zh/cli/models
- CodeBuddy IDE 官方文档：models.json 配置指南：https://www.codebuddy.cn/docs/ide/Features/models
- CodeBuddy Code 官方文档：环境变量：https://www.codebuddy.cn/docs/cli/env-vars
- CodeBuddy Code 官方文档：安装指南：https://www.codebuddy.ai/docs/zh/cli/installation
- 统一 LLM API 网关概览：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/codebuddy
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md