# Qwen Code 接入

> **最后核实**：2026-10-13 · 📄 依据官方文档（Qwen Code 0.25.1）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（写在 Anthropic 侧）· GPT ✅ · 国产模型 ✅（写在 OpenAI 兼容侧）· Gemini ❌（QCode 暂不提供 Gemini 系列，请使用 Claude、GPT 或国产模型） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI 兼容：`https://api.qcode.cc/openai/v1` |
| 配置位置 | `~/.qwen/settings.json` 里的 `modelProviders`；会话内用 `/auth`、`/model`、`/doctor` |
| 官方文档 | [认证](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/) · [设置参考](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) |

Qwen Code 是开源的终端编码助手，npm 包名 `@qwen-code/qwen-code`，本页按 `0.25.1` 版本核对。官方文档把「连 OpenAI、Anthropic、Google、Azure OpenAI、OpenRouter、Requesty、ModelScope 或自建端点这类第三方提供商」归在 API Key 认证下——QCode 走的就是这一条。`modelProviders` 声明有哪些模型、怎么连，运行时用 `/model` 切换。

## 用哪条协议

| 想用的模型 | `modelProviders` 的键（auth type） | 填的 Base URL |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT 与国产模型 | `openai` | `https://api.qcode.cc/openai/v1` |

官方把协议写在提供商的键上：内置提供商的键必须是合法的 auth type（`openai`、`anthropic`、`gemini`、`vertex-ai`）。每条模型由它的协议、`id` 和配置的 `baseUrl` 三者共同确定。

🔴 **不要用 OpenAI 兼容端点调 Claude。** QCode 的 OpenAI 端点会拒绝 Claude 模型，返回形如 `Model '<id>' is not available on this endpoint` 的报错。Claude 一律写在 `anthropic` 侧、Base URL 用 `https://api.qcode.cc/api`。GPT 模型也不能走 Anthropic 侧。

Base URL 照上表原样填：**结尾不要带斜杠**，也不要把请求路径写进输入框——填的是 base，不是 `.../v1/messages` 或 `.../chat/completions`。要用区域节点时，Anthropic 侧换成 `https://asia.qcode.cc/api` 或 `https://us.qcode.cc/api`，key 还是同一把。

## 安装

npm 安装要求 Node.js 22 或更高：

```bash
npm install -g @qwen-code/qwen-code@latest
```

macOS 与 Linux 也可以直接用 Homebrew：

```bash
brew install qwen-code
```

然后在项目目录里打开终端启动：

```bash
cd /path/to/your-project
qwen
```

在欢迎界面输入 `/help` 可以看可用命令清单。

## 配置 Claude（Anthropic 侧）

官方推荐的做法是集中写一个文件：`~/.qwen/settings.json`。下面用到的字段名都照抄官方原文：`modelProviders` 每个 auth type 对应一个数组，每条模型必须有 `id`，`name`、`baseUrl`、`generationConfig` 可选，`envKey` 写存放凭据的环境变量名。

```json
{
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-sonnet-5",
        "name": "claude-sonnet-5",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.qcode.cc/api"
      }
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "cr_your_qcode_key"
  },
  "security": {
    "auth": {
      "selectedType": "anthropic"
    }
  },
  "model": {
    "name": "claude-sonnet-5"
  }
}
```

这四个块各自的作用，官方字段表写得很清楚：`modelProviders` 声明有哪些模型、怎么连；`env` 把 API Key 存在 `settings.json` 里作为兜底，shell 的 `export` 与 `.env` 文件优先级更高；`security.auth.selectedType` 告诉 Qwen Code 启动时用哪条协议；`model.name` 是启动时激活的默认模型，必须等于你写的某个 `id`。

Anthropic 这一档也支持环境变量写法，官方列的三个变量是 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`：

```bash
export ANTHROPIC_API_KEY="cr_your_qcode_key"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_MODEL="claude-sonnet-5"
qwen
```

也可以在 CLI 里运行 `/auth`：它的第三个顶级选项 **Custom Provider**，官方说明就是用来手动连「本地服务、代理，或不受支持的提供商」，支持 OpenAI、Anthropic、Gemini 及其他兼容端点。

> **关于 Anthropic 侧的路径。** 官方 Anthropic 示例把 `baseUrl` 写到 `/v1` 这一层（`"baseUrl": "https://api.anthropic.com/v1"`），而 Anthropic 这个端点如何从 base 拼出请求路径，官方没有说明。所以本页只给 QCode 文档里的值：base 填 `https://api.qcode.cc/api`，到此为止；其它写法我们没有实测结论，也不建议你照抄。

## 配置 GPT 与国产模型（OpenAI 兼容侧）

官方对 `openai` 这一档的说明是：它不仅支持 OpenAI 官方 API，也支持任何 OpenAI 兼容端点，包括聚合类提供商——QCode 的 GPT 与国产模型就在这个端点上。指向托管网关时官方有明确规则：`baseUrl` 填 API 的 `/v1` 根，不要写完整的 chat 路径，请求路径由 SDK 自己拼。`https://api.qcode.cc/openai/v1` 就是这个根。

```json
{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-6.1-sol",
        "name": "gpt-6.1-sol",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.qcode.cc/openai/v1"
      },
      {
        "id": "deepseek-v4.1-flash",
        "name": "deepseek-v4.1-flash",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.qcode.cc/openai/v1"
      }
    ]
  },
  "env": {
    "OPENAI_API_KEY": "cr_your_qcode_key"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-6.1-sol"
  }
}
```

非默认的 auth type 只有通过 `/model` 才会露出来，所以把要用的模型都写进数组，再在那里选。模型 ID 取 QCode 在售的写法：`gpt-6.1-sol`、`gpt-6-sol`、`gpt-5.6-terra`，或 [`glm-5.3`](/docs/usage/cn-models)、[`deepseek-v4.1-flash`](/docs/usage/cn-models)、`qwen3.8-max` 这类国产 ID。

环境变量写法用官方为这一档列的三个：

```bash
export OPENAI_API_KEY="cr_your_qcode_key"
export OPENAI_BASE_URL="https://api.qcode.cc/openai/v1"
export OPENAI_MODEL="gpt-6.1-sol"
qwen
```

## 验证

先问 CLI 自己看到了什么：

```text
/doctor
/model
```

`/doctor` 是官方给的自检入口——「随时用它检查当前配置」，快速上手表格里它的说明是「检查当前认证与环境」。`/model` 打开你声明过的条目；改 `modelProviders` 不必重启，官方写明 `settings.json` 里的 `modelProviders` 会被运行中的交互会话读到，但需要重开 `/model` 才能看到新条目。

再脱离 CLI 单独验端点。Anthropic Messages 请求把 key 放在 `x-api-key`，版本放在 `anthropic-version`：

```bash
KEY="cr_your_qcode_key"
curl -X POST 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","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

本页内容取自文档，我们手上没有测试 key，因此不声称这条请求返回了什么。curl 通、CLI 不通，问题在你的 `~/.qwen/settings.json`；curl 就不通，先查 Base URL 与 key，再按[故障排查](/docs/reference/troubleshooting)的顺序继续。

## 已知限制与排查

| 现象 | 含义 | 怎么办 |
|---|---|---|
| Claude ID 在 OpenAI 兼容 Base URL 上失败 | QCode 只在 Anthropic 协议上提供 Claude | 把这条模型移到 `anthropic` 数组，`baseUrl` 用 `https://api.qcode.cc/api` |
| 配置里还留着 `security.auth.apiKey` 或 `security.auth.baseUrl` | 官方把这两项标为已废弃，说明要迁到 `modelProviders`（前者改用 `envKey`） | 删掉它们，改在 `modelProviders` 里声明模型 |
| 在 Anthropic 条目上写了 `wireApi` | 官方原文把这种情况列为配置错误：`wireApi` 是 OpenAI 侧字段 | 从 Anthropic 条目里去掉 |
| `extra_body` 不起作用 | 官方说明它只对 `openai`、`qwen-oauth` 这两档有效，对 Anthropic、Gemini 提供商会被忽略 | provider 模型的官方写法是把它写在 `modelProviders[].generationConfig.extra_body` |
| `model.name` 不生效 | 它必须等于 `modelProviders` 里的某个 `id` | 用一个已声明的 `id`，或用 `/model` 选 |
| 选择器里没有想要的模型 | 非默认 auth type 只通过 `/model` 暴露，Anthropic 模型必须写在 `modelProviders` 里 | 先在 `~/.qwen/settings.json` 加条目，再重开 `/model` |

另外几点：

- **Gemini**：Qwen Code 本身可以配 `gemini` 这一档，但 QCode 暂不提供 Gemini 系列，请使用 [Claude、GPT 或国产模型](/docs/usage/cn-models)。
- **暂不提供**：QCode 暂不提供 `gpt-6-luna`、`gpt-5.6-luna`，请改用 `gpt-6.1-sol`、`gpt-6-sol`、`gpt-5.6-terra` 等其它 GPT 模型。哪个任务该用哪个模型，见[模型怎么选](/docs/usage/model-selection)。
- **重启语义**：`modelProviders` 的改动会被运行中的会话读到；`providerProtocol` 只在启动时读一次，改了要重启。
- **本页不用命令行 flag 配凭据**：官方两处页面对 OpenAI base URL 那个 flag 的拼写并不一致，凭据只走 `~/.qwen/settings.json` 或环境变量。
- **Base URL 的写法**：结尾不带斜杠，也不要把请求路径本身填进 `baseUrl`。
- **费用**：按 token 计费，各模型单价见 [qcode.cc/models](https://qcode.cc/models)。本页不写价格数字。

## 相关文档

- [接入点与 API 路径](/docs/getting-started/endpoints-and-api-paths)：哪个模型族走哪条协议
- [工具兼容总览](/docs/ide/tool-compatibility)：其它支持 Anthropic 或 OpenAI 兼容协议的工具
- [OpenCode 接入](/docs/ide/opencode)：同样用这两个端点的另一个终端 CLI
- [国产模型接入](/docs/usage/cn-models)
- [模型怎么选](/docs/usage/model-selection)
- [故障排查指南](/docs/reference/troubleshooting)