Add Router One models to CodeBuddy with models.json

Where models.json lives, and which CodeBuddy product reads it

CodeBuddy merges up to two files over its built-in configuration: a project file overrides a user file for entries with the same id, and a project availableModels list replaces the user one instead of merging. Both files reload about one second after you save, and models added this way carry a custom tag in the model list. The CLI and the IDE read the same paths but differ in one field: the CLI resolves ${VAR} references in apiKey and url when it starts, while the IDE documentation says apiKey takes the key value itself, not an environment variable name. Install the CLI with npm install -g @tencent-ai/codebuddy-code (Node.js 18.20 or newer), create a dedicated Router One key with a maxSpend cap, and copy chat model IDs from /models.

Add a Router One entry to models.json: url is the full /v1/chat/completions path

Add one entry per Router One model under models: id is the exact catalog ID, url is https://api.router.one/v1/chat/completions, and apiKey is the dedicated key (in the CLI, a reference such as ${ROUTER_ONE_API_KEY} keeps it out of the file). Set maxInputTokens and maxOutputTokens yourself, set supportsToolCall and supportsImages to true only where the model page lists tool calling and image input, and leave temperature out. Save the file; in the CLI, start with codebuddy --model anthropic/claude-sonnet-5 or pick the model in /model, and in the IDE choose it from the model dropdown. This example pairs a main model with a cheaper lite model for background work (see the relatedModels section below):

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

What the url field accepts

CodeBuddy's documentation requires url to be the full request path, usually ending in /chat/completions, and lists base URLs such as https://api.openai.com/v1 as wrong examples. The CodeBuddy Code 2.158.0 source normalizes a custom model's url so that it ends in exactly one /chat/completions, trimming a trailing slash or a repeated suffix first; it does not add /v1, so the host root alone, https://api.router.one, becomes https://api.router.one/chat/completions, which is not a documented Router One endpoint. Since 2.155.0, a custom model without a url fails before any request is sent and asks you to fill it in, instead of going to CodeBuddy's own gateway. Only the OpenAI API format is supported, which is all Router One needs: every chat model in the catalog, including Claude, GPT, Gemini, Grok and DeepSeek IDs, is served on POST /v1/chat/completions. Image-generation IDs such as gpt-image-2 are not chat models, so leave them out of models.json.

Background and subagent requests: set relatedModels

CodeBuddy Code switches models inside a session: the lite variant handles background extraction and summaries and serves the Agent tool when it asks for lite, and the reasoning variant handles deep reasoning. Built-in subagents such as Explore are declared to use lite. Per CodeBuddy's docs, custom models from models.json do not inherit the product's defaultRelatedModels: if your main model declares no relatedModels and no environment variable or variantModels setting overrides them, lite and reasoning fall back to the main model, so those background and Explore requests all run and bill at its rate. Point relatedModels.lite at a cheaper Router One ID defined in the same file, such as anthropic/claude-haiku-4.5, whose model page lists tool calling. The same mapping can come from CODEBUDDY_SMALL_FAST_MODEL (lite) and CODEBUDDY_BIG_SLOW_MODEL (reasoning), which take precedence, or from /model:lite and /model:reasoning, which save variantModels in settings.json; CODEBUDDY_CODE_SUBAGENT_MODEL overrides the model of every built-in subagent. The docs mark the subagent, vision and longContext variants as reserved and not yet used. After a session, Dashboard → Logs shows each request's model, tokens, cost, status, total time and, for streamed requests that produced output, time to first token (TTFT), so you can see how many requests ran on the lite model.

Token limits, temperature and capability flags

These fields shape every request CodeBuddy sends for the model:

• maxInputTokens: the context window CodeBuddy Code compacts against. Per its changelog, a custom model without it falls back to a default auto-compact window, 200k tokens since 2.98.0. Set a value at or below the model page's context window (1,048,576 tokens for anthropic/claude-sonnet-5, 200,000 for anthropic/claude-haiku-4.5); a larger value lets each request carry more billed input before compaction.
• maxOutputTokens: a per-request output cap you choose. Since 2.119.1, CodeBuddy Code no longer fills in its built-in catalog's ceiling as the per-request limit when a custom model has none, so set the cap you want.
• temperature: leave it out. Since 2.128.0, CodeBuddy sends no temperature for a custom model that has none configured, which avoids 400 errors from models such as GPT-5 that accept only their default.
• supportsToolCall and supportsImages: set them to true only when the model page lists tool calling and image input. Prefer IDs whose page lists tool calling; for other IDs, test one tool call first.

Which model ID should CodeBuddy send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in CodeBuddy. A catalog listing does not mean the client can use every feature of that model. Give each client or application a dedicated API key with a maxSpend cap.

Which API protocol is CodeBuddy using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the CodeBuddy call in your request trace

Send a simple text request from CodeBuddy, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ