CodeBuddy Custom Models with QCode

Add QCode.cc to CodeBuddy via models.json: Chat and Responses tested with CodeBuddy Code CLI 2.182.0, no sign-in needed; copy-ready JSON and env vars.

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-11-10 · 📄 Per official docs (CodeBuddy IDE 4.12.4, released 2026-11-06; CLI docs for v2.182.0) · ✅ QCode connection tested with CodeBuddy Code CLI 2.182.0 (2026-11-10)

Yes, CodeBuddy can use your own key: custom models go into models.json (user level ~/.codebuddy/models.json), and the official docs say "Currently only supports OpenAI interface format API". As of 2026-11-10, tested with CodeBuddy Code CLI 2.182.0: QCode works over OpenAI Chat Completions (url is the full path) and OpenAI Responses (url is the base), and the CLI uses these models without a Tencent account sign-in. The IDE steps follow the official docs.

At a glance¶

CodeBuddy is Tencent Cloud's AI coding tool. It comes in three forms: a plugin for VS Code and JetBrains IDEs, the standalone CodeBuddy IDE, and CodeBuddy Code, a command-line tool whose command is codebuddy. The sites are codebuddy.cn (mainland China) and codebuddy.ai (international); the custom-model file path is the same in both sets of docs. WorkBuddy, the office agent from the same team, shares its foundation; see WorkBuddy custom models.

QCode.cc is not affiliated with Tencent or CodeBuddy. UI and fields follow the build you installed.

Which protocol¶

These protocols work on QCode with GPT and the Chinese models. Claude models are served on the Anthropic endpoint, and CodeBuddy's custom models do not use that protocol. If you need Claude, use a tool that supports an Anthropic endpoint, such as Claude Code, ZCode or Qoder. The three protocols are compared in Endpoints & API Paths. In mainland China you can use asia.qcode.cc in place of api.qcode.cc; the path is unchanged and the same key works.

Install CodeBuddy Code CLI¶

The official installation guide lists this method (prerequisite: Node.js 18.20 or higher); it is the install used in the 2026-11-10 test:

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

Without Node.js, the guide also offers Homebrew and a native binary (Beta):

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

On Windows PowerShell use irm https://www.codebuddy.cn/cli/install.ps1 | iex. Check the install with codebuddy --version (the test used 2.182.0). The custom models below work without signing in to a Tencent account. For the IDE or the plugin, download from codebuddy.ai; skip this section if you only use the IDE.

Configure models.json¶

File locations¶

The docs describe two levels:

• User level: ~/.codebuddy/models.json, global, applies to all projects
• Project level: <project-root>/.codebuddy/models.json, higher priority than the user level

Merge priority is project level, then user level, then built-in defaults. A model with the same id is overridden; a model with a different id is appended. The IDE and the CLI read the same paths.

CLI: minimal models.json (✅ tested)¶

Save this as ~/.codebuddy/models.json. The first entry uses Chat Completions, the second Responses; the key comes from an environment variable:

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

Then export the key and send a one-line test to each model:

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

A reply of OK means the model works. The id is sent to QCode as the model name, so it must be a live id on qcode.cc/models, character for character. For Chat entries you can also use gpt-6.1-sol, deepseek-v4-pro, glm-5.3, kimi-k3 or qwen3.8-max (see Chinese Models); Responses entries take GPT ids. Per-model prices are on https://qcode.cc/models. Set maxInputTokens, maxOutputTokens and the image or reasoning flags to what the chosen model supports.

Two url rules¶

For Chat Completions (the default), the official wording is: "url field must be the complete interface path, typically ending with /chat/completions", with these incorrect examples:

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

With api set to openai-responses the rule flips. Official wording: "With api set to openai-responses, the model uses the OpenAI Responses API: requests go to {url}/responses", and "url takes the base URL; a trailing /responses is optional."

For Responses, https://api.qcode.cc/openai also passed the test; this page uses /openai/v1 so both entries share one base. The docs also say that only an api written explicitly in the model entry switches the protocol.

CodeBuddy IDE (📄 per official docs)¶

The IDE docs list the same file paths and the Chat fields. The IDE page describes apiKey as the "actual key value, not environment variable name", so write the key itself. A Chat entry for the IDE:

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

The IDE field table has no api field, so Responses entries are for the CLI. If you use the IDE and the CLI with the same ~/.codebuddy/models.json, write the key itself in every entry; the CLI accepts a literal key too. The official advice: do not commit a models.json that holds a real key to version control, and set the file permissions to 600 (owner read/write only).

Field table¶

The CLI page adds three fields: api (request protocol; openai-responses switches to the Responses API), temperature (sampling temperature, 0-2) and relatedModels (which model id to use for scenarios such as lite and reasoning). The top-level availableModels is an array of strings; only the ids listed there appear in the dropdown, and an empty or missing array shows all models.

Reference environment variables with ${VAR_NAME} (CLI)¶

The CLI page says the apiKey and url fields support the reference syntax ${VAR_NAME}; the apiKey reference in the block above passed the test. Official notes: environment variables are resolved when the CLI starts; if an environment variable doesn't exist, the original placeholder is retained, which makes the API call fail.

Hot reload¶

Per the docs, config files support hot reload: changes are detected automatically with a 1-second debounce, for both models.json files above.

CLI environment variables¶

The official environment-variable page lists three variables relevant to third-party models:

As of 2026-11-10, tested with CodeBuddy Code CLI 2.182.0: CODEBUDDY_BASE_URL takes an OpenAI Chat Completions base, and the CLI appends /chat/completions to it. Set it to https://api.qcode.cc/openai/v1 and choose a GPT or Chinese model; this route needs no 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

Keep CODEBUDDY_BASE_URL on /openai/v1: with https://api.qcode.cc/api the request goes to /api/chat/completions and QCode answers HTTP 400.

Verify¶

First confirm that QCode's OpenAI path works from your network (the same probe as in Endpoints & API Paths):

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 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix

Then:

1. CLI: run the codebuddy -p tests above; OK means it works. For an interactive session, start codebuddy --model deepseek-v4-flash.
2. IDE: open the model dropdown. The docs say models added through models.json are tagged custom automatically, which helps you spot and filter them. Send a short message to the new model.
3. Enter your key at probe.qcode.cc to see the request and the model that answered.

Troubleshooting¶

The config does not take effect¶

The official checklist: check that the JSON is valid; confirm the file path; read the logs to see whether the config was loaded; confirm that the API key in the environment variable is set. Hot reload has a 1-second debounce, so make sure the file is actually saved to disk.

The model is missing from the dropdown¶

Per the docs: check that the model ID is listed in availableModels, and that the models config is correct. A project-level availableModels completely overrides the user-level one with no merging. The official troubleshooting list names "id, name, provider" as required fields, while the field table marks only id as required and calls the field vendor; filling in id, name and vendor covers both.

HTTP 404¶

The url of a Chat entry does not reach /chat/completions, or it is https://api.qcode.cc/api. Chat entries always use the full path https://api.qcode.cc/openai/v1/chat/completions; only entries with "api": "openai-responses" stop at /openai/v1.

HTTP 400 model_not_available_on_endpoint¶

A claude-… id was sent to an OpenAI path, for example through a models.json entry or through CODEBUDDY_BASE_URL set to https://api.qcode.cc/api. Claude models are served only on the Anthropic endpoint; use a GPT or Chinese model here, or switch to a tool such as Claude Code. This error does not mean the key is bad.

HTTP 401¶

The key must start with cr_ and have no spaces. With an environment-variable reference, check that the variable is really exported: the docs say a missing variable keeps the original placeholder, so the literal ${QCODE_API_KEY} is sent as the key.

Do I need to sign in to a Tencent account?¶

Not for these models. In the 2.182.0 test, codebuddy -p answered through models.json and through CODEBUDDY_BASE_URL without any sign-in.

Does a custom model send Tencent platform identity headers?¶

The official CLI v2.180.0 release notes say custom models no longer carry platform identity request headers: when a custom model connects directly to a third-party endpoint, identity information is no longer sent to the service you configured.

Related¶

• WorkBuddy custom models — the office agent from the same team, also on OpenAI Chat Completions
• ZCode — custom providers on the Anthropic and OpenAI protocols, including Claude
• Endpoints & API Paths — three protocols, three domains, BASE_URL map
• Chinese Models — GLM / Kimi / DeepSeek / Qwen model ids
• Tool Compatibility Overview — protocols per tool and whether Claude works
• Live ids and prices: qcode.cc/models

Enterprise →