# Qoder 接入 QCode

> **最后核实**：2026-11-10 · 📄 依据官方文档（Qoder 0.5.7 与 Qoder CLI 1.1.86，均于 2026-11-09 发布；文档于 2026-11-10 读取）

## 接入速览

| 项目 | 说明 |
|---|---|
| 它是什么 | Qoder 是一组编程智能体产品：新版 Qoder 桌面端、Qoder CLI（`qoder`）、Qoder IDE 与 JetBrains 插件。本文讲桌面端与 CLI。国际站 qoder.com（文档 docs.qoder.com），国内站 Qoder CN（文档 docs.qoder.cn） |
| 能否用自己的 Key | 能。官方自定义模型页写明，Qoder 支持通过 API 密钥接入第三方服务商的模型，其中包括自定义接口。适用版本：CLI 页写「适用版本：个人版」，桌面端更新日志写「个人版 BYOK」 |
| 配置位置 | 桌面端：**设置** → **模型** → **添加模型** → `供应商` → **自定义**。CLI：`/model` → **Custom** 页签 → **Add custom model...** |
| 协议 | **OpenAI Compatible**（再选 **Chat Completions API** 或 **Responses API**）· **Anthropic Compatible** |
| QCode 填写值 | Anthropic Compatible：`https://api.qcode.cc/api` · OpenAI Compatible：`https://api.qcode.cc/openai/v1` |
| 可用模型 | Claude ✅（Anthropic Compatible）· GPT ✅（OpenAI Compatible）· GLM / Kimi / DeepSeek / Qwen ✅（两种都行）· Gemini ❌（QCode 暂不提供 Gemini 模型） |
| 官方文档 | [自定义模型（国际站）](https://docs.qoder.com/zh/qoder/custom-models) · [自定义模型（Qoder CN）](https://docs.qoder.cn/qoder/custom-models) · [CLI 自定义模型](https://docs.qoder.com/zh/cli/custom-models) · [更新日志](https://changelog.qoder.com/zh/app) |

同一家族里的 Qoder IDE 是另一款产品，它的自定义模型页（docs.qoder.com/user-guide/chat/custom-models）只列预置服务商。自定义 Base URL 在新版 Qoder 桌面端（0.1.8 起，2026-09-05）与 Qoder CLI（个人版用户自 1.1.50 起在 `/model` 的 Custom 页统一配置，2026-09-11）里都能用，也就是本文讲的这两端。

## 走哪个协议

自定义接口有两种类型，其中 **OpenAI Compatible** 还要再选一次 API 类型。按模型家族选一行：

| Qoder 里的选项 | Base URL | 型号 ID（示例） |
|---|---|---|
| **Anthropic Compatible** | `https://api.qcode.cc/api` | `claude-sonnet-5-5`、`claude-opus-5-5`、`deepseek-v4.1-flash`、`glm-5.3` |
| **OpenAI Compatible** + **Chat Completions API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`、`deepseek-v4.1-flash`、`glm-5.3`、`kimi-k3`、`qwen3.8-max` |
| **OpenAI Compatible** + **Responses API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`、`gpt-6.1-terra` |

Claude 型号只走 Anthropic 协议，所以 `claude-…` 要放在 **Anthropic Compatible** 下；GPT 型号只走两条 OpenAI 协议；GLM / Kimi / DeepSeek / Qwen 两种都可以。完整对照见[接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)；型号 ID 以 [qcode.cc/models](https://qcode.cc/models) 为准，逐字照抄。

**Base URL 的写法。** Qoder 官方原话：「请填写模型服务商提供的准确 Base URL；Qoder 中展示的示例格式为 https://api.example.com/v1。」示例以 `/v1` 结尾，所以 OpenAI 两个选项填 QCode 以 `/v1` 结尾的地址；选 Responses API 时也这样填，QCode 的 `/openai/responses` 与 `/openai/v1/responses` 等价。Qoder 文档没有写 **Anthropic Compatible** 会在地址后拼哪段路径：先填 QCode 的 Anthropic 地址 `https://api.qcode.cc/api`（末尾不加斜杠）；若「校验并添加模型」不通过，改填 `https://api.qcode.cc/api/v1` 再校验一次。两种写法到的是 QCode 同一个接口 `/api/v1/messages`，差别只在 Qoder 自己补几段路径。

在亚洲或北美使用时，可把域名换成 `asia.qcode.cc` 或 `us.qcode.cc`，路径不变。

## 安装

从 [Qoder 下载页](https://qoder.com/zh/download)下载桌面端（macOS 12+、Windows 10+ 或 Linux）并登录。CLI 在同一页给出的安装命令：

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

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

Qoder CN 有自己的应用与文档（docs.qoder.cn）。请把你运行的版本与上面的版本对照。

## 配置

### 桌面端：设置 → 模型

以下步骤照官方自定义模型页的中文界面写法：

1. 进入**设置**，在左侧导航栏选择「模型」。
2. 点击「添加模型」。使用自定义接口时，打开 `供应商`，在「自定义」分组中选择 OpenAI Compatible 或 Anthropic Compatible。
3. 选择 OpenAI Compatible 时，继续选择 Chat Completions API 或 Responses API。
4. 填写「接口地址（Base URL）」、API Key 和至少一个 Model ID。如需为同一接口配置多个模型，点击「添加 Model ID」。
5. 按页面上的配置项设置模型能力：显示名称、上下文窗口（先选支持的值，再设「默认上下文窗口」）、视觉（模型支持图片输入时开启）、思考模式（模型支持推理时开启，再选思考强度）。
6. 点击「校验并添加模型」。官方说明：「Qoder 会验证连接，验证通过后保存模型。」
7. 在对话框中选择刚添加的模型。

接 QCode 要填的值（Key 占位 `cr_xxx`）：

| 字段 | Anthropic Compatible | OpenAI Compatible |
|---|---|---|
| 接口地址（Base URL） | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| API 类型 | — | Chat Completions API（GPT 也可选 Responses API） |
| API Key | `cr_xxx` | `cr_xxx` |
| Model ID | `claude-sonnet-5-5` | `gpt-6.1-sol` |

需要几种协议就各添加一次，每次填各自的地址。

**国际站与 Qoder CN 的差别。** 国际站文档列出的预置服务商是阿里云百炼、DeepSeek、智谱、Kimi、MiniMax、小米 MIMO、OpenAI、Google、OpenRouter；Qoder CN 文档列出阿里云百炼、DeepSeek、智谱、Kimi、MiniMax、小米 MIMO，没有 OpenAI、Google、OpenRouter。两边的自定义选项相同，都是 OpenAI Compatible 与 Anthropic Compatible，步骤也相同。

以后要换 Key，在「模型」面板里用「编辑」；「删除」会移除该模型。

### CLI：/model → Custom

1. 启动 Qoder CLI，输入 `/model`。
2. 切换到 **Custom** 页签。
3. 选择 **Add custom model...** 并按 Enter。
4. 按向导依次选择 Provider → 模型类型 → 具体模型，填写 API Key 等向导要求的信息。
5. 验证通过后配置自动保存，可立即切换。在 **Custom** 页签选中模型按 Enter 使用；选中后按 `d` 删除。

官方原话还有一句：「请通过 /model 的 Custom 向导配置 BYOK。不要在 settings.json 中手工配置 BYOK」。CLI 页没有列出向导的各字段；CLI 1.1.50 的更新日志写，个人版用户可在 /model 的 Custom 页统一配置和管理「自定义 URL 端点的 BYOK 模型」，Qoder 官方 X 账号的说法是填入 Base URL、Model ID 和 API Key。这些字段按上表的 QCode 值填写。

## 验证

1. 选中刚添加的模型，发一条短消息，例如 `ping`。
2. 打开 [probe.qcode.cc](https://probe.qcode.cc)，输入你的 QCode Key，确认请求带着该模型出现。
3. 不经过 Qoder 单独测 Key 与路径：

```bash
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"}]}'
```

## 排错

官方「添加模型失败如何处理」列了五项检查，对应到 QCode：

| 官方检查项 | 在 QCode 上 |
|---|---|
| 「Base URL 是否完整，所选兼容协议和 API 类型是否与接口匹配」 | Anthropic Compatible 填 `https://api.qcode.cc/api`（或 `https://api.qcode.cc/api/v1`，见上文）；OpenAI Compatible 填 `https://api.qcode.cc/openai/v1`，末尾不加 `/` |
| 「API Key 是否正确且无多余空格，是否已过期或被禁用」 | 重新粘贴 `cr_` 开头的 Key，不留空格 |
| 「Model ID 是否正确，服务商账户是否有权访问该模型」 | 从 [qcode.cc/models](https://qcode.cc/models) 复制 ID |
| 「服务商账户余额是否充足」 | 到 QCode 控制台查看余额 |
| 「网络连接是否正常」 | 路径不变，换 `asia.qcode.cc` 或 `us.qcode.cc` 试试 |

两条 QCode 侧的报错：`model_not_available_on_endpoint` 表示把 `claude-…` 加在了 OpenAI 选项下，改加到 **Anthropic Compatible**，这是协议选错，不是 Key 的问题；`Invalid API key` 才是 Key 的问题。

CLI 方面官方写：没有看到 Custom 页签或添加入口，要确认当前账号和版本已开通 BYOK；找不到某个 Provider 或模型，以 Custom 向导实时展示的目录为准。

## 已知限制

- 官方原文：「图片和视频生成暂不支持通过自带 API 密钥（BYOK）接入的模型。」
- 官方原文：自定义模型的费用由服务商 API 账户直接结算，「不占用 Qoder Credits」。Repo Wiki 使用固定模型，仍会消耗 Qoder Credits。
- Qoder 展示的 `https://api.example.com/v1` 只是格式示例；文档没有说明每种协议下 Qoder 会拼哪段路径，实际以「校验并添加模型」的结果为准。
- QoderWork 是另一个产品。它的模型页列的是旗舰（Premium）、高级（Advanced）、标准（Standard）三档以及 Qwen3.7-Max、Qwen3.7-Plus，截至 2026-11-10 没有自定义模型入口。Qoder 下载页写明 QoderWork 将于 2027 年 9 月 5 日正式停止运营，建议迁移到内置数据导入工具的 Qoder 桌面版。
- 「轻量」（Lite）模型档位按官方通知，于 2026 年 9 月 18 日 14:00（新加坡时间）从各端模型选择器下线。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族对照表
- [工具兼容总览](/docs/ide/tool-compatibility) — 各工具支持哪些协议
- [DeepSeek Harness](/docs/ide/deepseek-harness) — 另一个带自定义模型表单的工具
- [有道龙虾 LobsterAI](/docs/ide/lobsterai) — 自定义服务商同样支持 Anthropic 与 OpenAI 两种格式的桌面 Agent
- [国产模型接入](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen 的 ID 与路径
- [qcode.cc 上的 Qoder 自定义模型 BYOK 指南](https://qcode.cc/qoder-custom-model-byok-setup) — 时间线与背景