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

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。

在 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": [
    {
      "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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题