# Qwen Code Setup

> **Last verified**: 2026-10-13 · 📄 Per official docs (Qwen Code 0.25.1)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (declared on the Anthropic side) · GPT ✅ · Chinese models ✅ (declared on the OpenAI-compatible side) · Gemini ❌ — QCode does not offer the Gemini series, so use Claude, GPT, or a Chinese model |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI-compatible: `https://api.qcode.cc/openai/v1` |
| Where to configure | The `modelProviders` setting in `~/.qwen/settings.json`; inside a session: `/auth`, `/model`, `/doctor` |
| Official docs | [Authentication](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/) · [Settings reference](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) |

Qwen Code is an open-source terminal coding assistant, published on npm as `@qwen-code/qwen-code`; this page was checked against version `0.25.1`. Its documentation sorts connecting "third-party providers such as OpenAI, Anthropic, Google, Azure OpenAI, OpenRouter, Requesty, ModelScope, or a self-hosted endpoint" under API Key authentication — that is the endpoint route QCode uses. The `modelProviders` setting declares which models exist and how to reach them, and `/model` switches between them at runtime.

## Which protocol

| Models you want | `modelProviders` key (auth type) | Base URL to enter |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT and Chinese models | `openai` | `https://api.qcode.cc/openai/v1` |

Qwen Code documents the protocol as part of the provider key: for built-in providers the key must be a valid auth type (`openai`, `anthropic`, `gemini`, `vertex-ai`). Each model entry is then identified by its protocol, its `id`, and its configured `baseUrl`.

🔴 **Never call Claude through the OpenAI-compatible base URL.** QCode's OpenAI endpoint rejects Claude model ids; the response reads `Model '<id>' is not available on this endpoint`. Claude is configured on the `anthropic` side with `https://api.qcode.cc/api`. GPT ids are not served on the Anthropic side either.

Type the base URL exactly as above: **no trailing slash**, and do not put the request path into the field — you enter the base, not `.../v1/messages` or `.../chat/completions`. If you use a regional node, the Anthropic base becomes `https://asia.qcode.cc/api` or `https://us.qcode.cc/api`; the key is the same one.

## Install

npm installation requires Node.js 22 or newer:

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

On macOS and Linux you can use Homebrew instead:

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

Then open a terminal in your project and start it:

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

Type `/help` in the welcome screen for the list of commands.

## Configure Claude (Anthropic side)

Qwen Code's recommended path is a single file, `~/.qwen/settings.json`. Every key below is taken verbatim from its documentation: `modelProviders` holds one array per auth type, an entry needs an `id`, and `name`, `baseUrl` and `generationConfig` are optional; `envKey` names the environment variable that carries the credential.

```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"
  }
}
```

What the four blocks do, in the words of the official table: `modelProviders` declares which models are available and how to connect to them; `env` stores API keys in `settings.json` as a fallback, with shell `export` and `.env` files taking precedence; `security.auth.selectedType` tells Qwen Code which protocol to use on startup; `model.name` is the default model activated at startup and must match one of your `id` values.

The Anthropic protocol also has an environment-variable form — Qwen Code lists `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` and `ANTHROPIC_MODEL` for it:

```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
```

You can also run `/auth` inside the CLI: its third top-level option, **Custom Provider**, is the documented entry for manually connecting "a local server, proxy, or unsupported provider", and it supports OpenAI, Anthropic, Gemini and other compatible endpoints.

> **About the Anthropic path.** The official Anthropic examples write `baseUrl` down to a `/v1` suffix (`"baseUrl": "https://api.anthropic.com/v1"`), and the documentation does not state how the Anthropic endpoint builds the request path from a base. So this page only states QCode's documented value: enter `https://api.qcode.cc/api` and nothing more. We do not claim a tested outcome for any other spelling.

## Configure GPT and Chinese models (OpenAI-compatible side)

The `openai` auth type is documented as covering not only OpenAI's own API but also any OpenAI-compatible endpoint, including aggregated providers — which is the endpoint QCode's GPT and Chinese models are served on. The official rule for a hosted gateway applies here: set `baseUrl` to the API's `/v1` root rather than the full chat path, because the SDK appends the request path itself. `https://api.qcode.cc/openai/v1` is that root.

```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"
  }
}
```

Only `/model` exposes non-default auth types, so add the models you want to the array and pick them there. Model ids come from the QCode catalog: `gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-terra`, or a Chinese id such as [`glm-5.3`](/docs/usage/cn-models), [`deepseek-v4.1-flash`](/docs/usage/cn-models) or `qwen3.8-max`.

The environment-variable form uses the three variables Qwen Code lists for this protocol:

```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
```

## Verify

Ask the CLI what it sees:

```text
/doctor
/model
```

`/doctor` is the documented way to check your current configuration at any time; in the quickstart command table its line reads "Check current authentication and environment". `/model` opens the picker over the entries you declared, and switching takes effect without a restart — `modelProviders` edits in `settings.json` are picked up by a running interactive session, but you need to reopen `/model` to see them.

Then check the endpoint itself, independently of the CLI. The Anthropic Messages request carries the key in `x-api-key` and a version in `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"}]}'
```

This page was assembled from documentation, and we hold no test key, so no response from that request is claimed here. If curl works and the CLI does not, the difference is in your `~/.qwen/settings.json`; if curl fails, the base URL or the key is the problem — continue with [Troubleshooting](/docs/reference/troubleshooting).

## Troubleshooting / Known limitations

| Symptom | What it means | What to do |
|---|---|---|
| A Claude id fails on the OpenAI-compatible base URL | QCode serves Claude only over the Anthropic protocol | Move that model into the `anthropic` array and set its `baseUrl` to `https://api.qcode.cc/api` |
| `security.auth.apiKey` or `security.auth.baseUrl` in your config | Both settings are documented as Deprecated, with the note to migrate to `modelProviders` (`envKey` for the first one) | Drop them and declare the model under `modelProviders` |
| `wireApi` set on an Anthropic entry | The docs list this as a configuration error: `wireApi` is an OpenAI-side field | Remove it from Anthropic entries |
| `extra_body` seems to do nothing | It is only supported for the OpenAI-compatible providers `openai` and `qwen-oauth`; the docs state it is ignored for Anthropic and Gemini providers | For provider models the documented place for it is `modelProviders[].generationConfig.extra_body` |
| `model.name` has no effect | It must match one of the `id` values in your `modelProviders` | Use a declared `id`, or pick the model with `/model` |
| The model you want is not in the picker | Non-default auth types are only exposed through `/model`, and Anthropic models must be defined via `modelProviders` | Add the entry to `~/.qwen/settings.json`, then reopen `/model` |

Further points worth knowing:

- **Gemini**: Qwen Code can be configured for the `gemini` auth type, but QCode does not offer the Gemini series — use Claude, GPT, or a [Chinese model](/docs/usage/cn-models).
- **Not on offer**: QCode does not offer `gpt-6-luna` or `gpt-5.6-luna`; choose another GPT model such as `gpt-6.1-sol`, `gpt-6-sol` or `gpt-5.6-terra`. Which model fits which task is covered in [Choosing a model](/docs/usage/model-selection).
- **Restart semantics**: `modelProviders` changes are picked up by a running session, while `providerProtocol` is read once at startup and requires a restart.
- **No credential flags on this page**: the official pages spell the OpenAI base-URL flag two different ways, so configure credentials only through `~/.qwen/settings.json` or environment variables.
- **Base URL hygiene**: no trailing slash, and never type the request path into `baseUrl`.
- **Cost**: billing is per token; per-model rates are listed on [qcode.cc/models](https://qcode.cc/models). This page states no prices.

## Related

- [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths) — which protocol serves which model family
- [Tool compatibility](/docs/ide/tool-compatibility) — other coding tools that speak Anthropic or OpenAI-compatible protocols
- [OpenCode setup](/docs/ide/opencode) — another terminal CLI on the same two endpoints
- [Chinese models](/docs/usage/cn-models)
- [Choosing a model](/docs/usage/model-selection)
- [Troubleshooting](/docs/reference/troubleshooting)