Qoder Setup with QCode (BYOK)

Add QCode to Qoder's custom model settings: OpenAI Compatible (Chat Completions or Responses) for GPT and Chinese models, Anthropic Compatible for Claude.

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

Last verified: 2026-11-10 · 📄 Per official docs (Qoder 0.5.7 and Qoder CLI 1.1.86, both released 2026-11-09; the docs were read on 2026-11-10)

At a glance¶

Qoder IDE, a separate product in the same family, has its own custom models page (docs.qoder.com/user-guide/chat/custom-models) that lists preset providers only. Custom Base URLs are available in the Qoder desktop app (since 0.1.8, 2026-09-05) and in Qoder CLI, where personal edition users manage them from the Custom page in /model (since 1.1.50, 2026-09-11); this page covers those two.

Which protocol¶

The custom endpoint form offers two provider types, and OpenAI Compatible has a second choice for the API type. Pick the row that matches the model family:

Claude models only work on the Anthropic protocol, so put claude-… IDs behind Anthropic Compatible; GPT models only work on the two OpenAI protocols. The four Chinese families work on both. See Endpoints & API Paths for the full table, and copy model IDs from qcode.cc/models character for character.

Base URL form. Qoder's own words: "enter the exact Base URL supplied by the model service. Qoder displays https://api.example.com/v1 as an example format." That example ends in /v1, so for the OpenAI choices enter the QCode URL that ends in /v1. For the Responses API choice this works because QCode serves /openai/responses and /openai/v1/responses identically. The Qoder docs do not say which path Qoder appends for Anthropic Compatible. Start with QCode's Anthropic base URL https://api.qcode.cc/api (no trailing slash). If Validate and add model fails, enter https://api.qcode.cc/api/v1 and validate again: both reach the same QCode endpoint /api/v1/messages, and the only difference is how many path segments Qoder adds itself.

In Asia or North America you can swap the domain for asia.qcode.cc or us.qcode.cc; the paths stay the same.

Install¶

Download the desktop app from the Qoder download page (macOS 12+, Windows 10+ or Linux) and sign in. For the CLI the same page lists:

# macOS / Linux
curl -fsSL https://qoder.com/install | bash

# Windows PowerShell
irm https://qoder.com/install.ps1 | iex

Qoder CN has its own app and docs at docs.qoder.cn. Check the version you run against the versions above.

Configure¶

Desktop: Settings → Models¶

These are the steps from the official custom models page, in the interface wording of the English docs:

1. Open Settings, then select Models in the left navigation.
2. Click Add model. For a custom endpoint, open Provider and select OpenAI Compatible or Anthropic Compatible under Custom.
3. For OpenAI Compatible, select Chat Completions API or Responses API.
4. Enter the Base URL, your API key and at least one Model ID. To configure more models for the same endpoint, click Add Model ID.
5. Configure the capabilities the page lists: Display name, Context window (choose the supported values, then a Default context window), Vision (turn it on when the model accepts images) and Thinking (turn it on when the model supports reasoning, then pick its effort levels).
6. Click Validate and add model. "Qoder validates the connection and saves the model after validation succeeds."
7. Select the new model in the chat interface.

Values to enter for QCode (key placeholder cr_xxx):

Add one entry per protocol you need; each entry takes its own Base URL.

Global and CN differences. The preset providers listed on the global page are Alibaba Cloud Model Studio, DeepSeek, Z.ai, Kimi, MiniMax, Xiaomi MIMO, OpenAI, Google and OpenRouter. The CN page lists Alibaba Cloud Model Studio, DeepSeek, Zhipu, Kimi, MiniMax and Xiaomi MIMO, without OpenAI, Google and OpenRouter. Both list the same two custom providers, OpenAI Compatible and Anthropic Compatible, and the same steps.

To change a key later, use the Edit action in the Models panel; Delete removes the model.

CLI: /model → Custom¶

1. Start Qoder CLI and enter /model.
2. Switch to the Custom tab.
3. Select Add custom model... and press Enter.
4. Follow the wizard: "Provider → model type → model", then enter the API key and any other information it asks for.
5. After validation succeeds the configuration is saved automatically and the model can be selected at once. Select it from the Custom tab; press d on a model there to delete it.

The official page also says: "Do not configure BYOK manually in settings.json; the available providers, models, and credential fields are determined by the BYOK catalog available to the current account." The CLI page does not list the wizard fields. The CLI 1.1.50 release note says personal edition users can configure BYOK models "with custom URL endpoints from the Custom page in /model", and the official Qoder account on X described it as entering a Base URL, Model ID and API key. Use the QCode values from the table above for those fields.

Verify¶

1. Select the model you added and send a short message such as ping.
2. Open probe.qcode.cc, enter your QCode key and check that the request shows up with that model.
3. To test the key and path without Qoder:

KEY="cr_your_key"

# OpenAI Compatible, Chat Completions API
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-6.1-sol","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

# Anthropic Compatible
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

Troubleshooting¶

The official FAQ for adding a model that fails lists five checks. They map to QCode like this:

Two QCode-specific messages: model_not_available_on_endpoint means a claude-… ID was added under an OpenAI choice, so add it under Anthropic Compatible instead; it is a protocol mismatch, not a key problem. Invalid API key is a key problem.

For the CLI the official page says: if the Custom tab or the add entry is missing, confirm that BYOK is available for the current account and plan; if a provider or model is missing, the wizard's live catalog is the source of truth.

Known limitations¶

• Official: "Image and video generation are currently unavailable when using models connected with your own API key (BYOK)."
• Official: custom model fees are billed to your provider API account and "do not use Qoder Credits". Repo Wiki uses a fixed model and still consumes Qoder Credits.
• Qoder displays the example https://api.example.com/v1 only as a format; the docs do not describe which path Qoder appends for each protocol, so the result of Validate and add model is the final word.
• QoderWork is a separate product. Its models page lists the tiers Premium, Advanced and Standard plus Qwen3.7-Max and Qwen3.7-Plus, with no custom model entry as of 2026-11-10. The Qoder download page says QoderWork will cease operations on September 5, 2027, and recommends moving to Qoder Desktop, which includes data import tools.
• The Lite model tier was removed from the model selector on 18 September 2026 at 14:00 Singapore time (UTC+8), per the official notice.

Related¶

• Endpoints & API Paths — protocol × model-family table
• Tool Compatibility Overview — which tools speak which protocol
• DeepSeek Harness — another tool with a custom model form
• LobsterAI — a desktop agent whose custom providers also take Anthropic and OpenAI formats
• Chinese Models — GLM / Kimi / DeepSeek / Qwen IDs and paths
• Qoder custom model BYOK guide on qcode.cc — dates and background

Enterprise →