mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-04-28 19:52:02 +00:00
e90abf4c35
* docs: update quota exceeded alternatives to OpenRouter and Fireworks - Update README.md news section to recommend OpenRouter and Fireworks as primary alternatives, with ModelStudio as third option - Update retry.ts quota error message to include OpenRouter and Fireworks URLs for users whose OAuth quota has been exhausted Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(test): update retry test assertions to match new quota error message * docs: update free tier quota to 100 req/day with sunset notice and alternatives Update all references to reflect the Qwen OAuth free tier policy change: - 1,000 → 100 requests/day across code, i18n, and docs - Add 2026-04-15 sunset date everywhere - Guide users to OpenRouter, Fireworks AI, or ModelStudio in docs - Remove CHANGELOG.md --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Co-authored-by: tanzhenxin <tanzhenxing1987@gmail.com>
366 lines
16 KiB
Markdown
366 lines
16 KiB
Markdown
# Authentication
|
|
|
|
Qwen Code supports three authentication methods. Pick the one that matches how you want to run the CLI:
|
|
|
|
- **Qwen OAuth**: sign in with your `qwen.ai` account in a browser. Free with a daily quota.
|
|
- **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas.
|
|
- **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints.
|
|
|
|
## Option 1: Qwen OAuth (Free)
|
|
|
|
Use this if you want the simplest setup and you're using Qwen models.
|
|
|
|
- **How it works**: on first start, Qwen Code opens a browser login page. After you finish, credentials are cached locally so you usually won't need to log in again.
|
|
- **Requirements**: a `qwen.ai` account + internet access (at least for the first login).
|
|
- **Benefits**: no API key management, automatic credential refresh.
|
|
- **Cost & quota**: free, with a quota of **60 requests/minute** and **100 requests/day**. Note: the free tier will be discontinued on 2026-04-15. After that, consider switching to [OpenRouter](https://openrouter.ai), [Fireworks AI](https://app.fireworks.ai), or [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2840914_2&modelId=qwen3.6-plus) — run `qwen auth` to configure your new provider.
|
|
|
|
Start the CLI and follow the browser flow:
|
|
|
|
```bash
|
|
qwen
|
|
```
|
|
|
|
Or authenticate directly without starting a session:
|
|
|
|
```bash
|
|
qwen auth qwen-oauth
|
|
```
|
|
|
|
> [!note]
|
|
>
|
|
> In non-interactive or headless environments (e.g., CI, SSH, containers), you typically **cannot** complete the OAuth browser login flow.
|
|
> In these cases, please use the Alibaba Cloud Coding Plan or API Key authentication method.
|
|
|
|
## 💳 Option 2: Alibaba Cloud Coding Plan
|
|
|
|
Use this if you want predictable costs with diverse model options and higher usage quotas.
|
|
|
|
- **How it works**: Subscribe to the Coding Plan with a fixed monthly fee, then configure Qwen Code to use the dedicated endpoint and your subscription API key.
|
|
- **Requirements**: Obtain an active Coding Plan subscription from [Alibaba Cloud ModelStudio(Beijing)](https://bailian.console.aliyun.com/cn-beijing?tab=coding-plan#/efm/coding-plan-index) or [Alibaba Cloud ModelStudio(intl)](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index), depending on the region of your account.
|
|
- **Benefits**: Diverse model options, higher usage quotas, predictable monthly costs, access to a wide range of models (Qwen, GLM, Kimi, Minimax and more).
|
|
- **Cost & quota**: View Aliyun ModelStudio Coding Plan documentation[Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3005961)[intl](https://modelstudio.console.alibabacloud.com/?tab=doc#/doc/?type=model&url=2840914).
|
|
|
|
Alibaba Cloud Coding Plan is available in two regions:
|
|
|
|
| Region | Console URL |
|
|
| ---------------------------- | ---------------------------------------------------------------------------- |
|
|
| Aliyun ModelStudio (Beijing) | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |
|
|
| Alibaba Cloud (intl) | [bailian.console.alibabacloud.com](https://bailian.console.alibabacloud.com) |
|
|
|
|
### Interactive setup
|
|
|
|
You can set up Coding Plan authentication in two ways:
|
|
|
|
**Option A: From the terminal (recommended for first-time setup)**
|
|
|
|
```bash
|
|
# Interactive — prompts for region and API key
|
|
qwen auth coding-plan
|
|
|
|
# Or non-interactive — pass region and key directly
|
|
qwen auth coding-plan --region china --key sk-sp-xxxxxxxxx
|
|
```
|
|
|
|
**Option B: Inside a Qwen Code session**
|
|
|
|
Enter `qwen` in the terminal to launch Qwen Code, then run the `/auth` command and select **Alibaba Cloud Coding Plan**. Choose your region, then enter your `sk-sp-xxxxxxxxx` key.
|
|
|
|
After authentication, use the `/model` command to switch between all Alibaba Cloud Coding Plan supported models (including qwen3.5-plus, qwen3-coder-plus, qwen3-coder-next, qwen3-max, glm-4.7, and kimi-k2.5).
|
|
|
|
### Alternative: configure via `settings.json`
|
|
|
|
If you prefer to skip the interactive `/auth` flow, add the following to `~/.qwen/settings.json`:
|
|
|
|
```json
|
|
{
|
|
"modelProviders": {
|
|
"openai": [
|
|
{
|
|
"id": "qwen3-coder-plus",
|
|
"name": "qwen3-coder-plus (Coding Plan)",
|
|
"baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
|
|
"description": "qwen3-coder-plus from Alibaba Cloud Coding Plan",
|
|
"envKey": "BAILIAN_CODING_PLAN_API_KEY"
|
|
}
|
|
]
|
|
},
|
|
"env": {
|
|
"BAILIAN_CODING_PLAN_API_KEY": "sk-sp-xxxxxxxxx"
|
|
},
|
|
"security": {
|
|
"auth": {
|
|
"selectedType": "openai"
|
|
}
|
|
},
|
|
"model": {
|
|
"name": "qwen3-coder-plus"
|
|
}
|
|
}
|
|
```
|
|
|
|
> [!note]
|
|
>
|
|
> The Coding Plan uses a dedicated endpoint (`https://coding.dashscope.aliyuncs.com/v1`) that is different from the standard Dashscope endpoint. Make sure to use the correct `baseUrl`.
|
|
|
|
## 🚀 Option 3: API Key (flexible)
|
|
|
|
Use this if you want to connect to third-party providers such as OpenAI, Anthropic, Google, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted endpoint. Supports multiple protocols and providers.
|
|
|
|
### Recommended: One-file setup via `settings.json`
|
|
|
|
The simplest way to get started with API Key authentication is to put everything in a single `~/.qwen/settings.json` file. Here's a complete, ready-to-use example:
|
|
|
|
```json
|
|
{
|
|
"modelProviders": {
|
|
"openai": [
|
|
{
|
|
"id": "qwen3-coder-plus",
|
|
"name": "qwen3-coder-plus",
|
|
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
|
"description": "Qwen3-Coder via Dashscope",
|
|
"envKey": "DASHSCOPE_API_KEY"
|
|
}
|
|
]
|
|
},
|
|
"env": {
|
|
"DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
|
|
},
|
|
"security": {
|
|
"auth": {
|
|
"selectedType": "openai"
|
|
}
|
|
},
|
|
"model": {
|
|
"name": "qwen3-coder-plus"
|
|
}
|
|
}
|
|
```
|
|
|
|
What each field does:
|
|
|
|
| Field | Description |
|
|
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `modelProviders` | Declares which models are available and how to connect to them. Keys (`openai`, `anthropic`, `gemini`) represent the API protocol. |
|
|
| `env` | Stores API keys directly in `settings.json` as a fallback (lowest priority — shell `export` and `.env` files take precedence). |
|
|
| `security.auth.selectedType` | Tells Qwen Code which protocol to use on startup (e.g. `openai`, `anthropic`, `gemini`). Without this, you'd need to run `/auth` interactively. |
|
|
| `model.name` | The default model to activate when Qwen Code starts. Must match one of the `id` values in your `modelProviders`. |
|
|
|
|
After saving the file, just run `qwen` — no interactive `/auth` setup needed.
|
|
|
|
> [!tip]
|
|
>
|
|
> The sections below explain each part in more detail. If the quick example above works for you, feel free to skip ahead to [Security notes](#security-notes).
|
|
|
|
The key concept is **Model Providers** (`modelProviders`): Qwen Code supports multiple API protocols, not just OpenAI. You configure which providers and models are available by editing `~/.qwen/settings.json`, then switch between them at runtime with the `/model` command.
|
|
|
|
#### Supported protocols
|
|
|
|
| Protocol | `modelProviders` key | Environment variables | Providers |
|
|
| ----------------- | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
| OpenAI-compatible | `openai` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | OpenAI, Azure OpenAI, OpenRouter, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint |
|
|
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` | Anthropic Claude |
|
|
| Google GenAI | `gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | Google Gemini |
|
|
|
|
#### Step 1: Configure models and providers in `~/.qwen/settings.json`
|
|
|
|
Define which models are available for each protocol. Each model entry requires at minimum an `id` and an `envKey` (the environment variable name that holds your API key).
|
|
|
|
> [!important]
|
|
>
|
|
> It is recommended to define `modelProviders` in the user-scope `~/.qwen/settings.json` to avoid merge conflicts between project and user settings.
|
|
|
|
Edit `~/.qwen/settings.json` (create it if it doesn't exist). You can mix multiple protocols in a single file — here is a multi-provider example showing just the `modelProviders` section:
|
|
|
|
```json
|
|
{
|
|
"modelProviders": {
|
|
"openai": [
|
|
{
|
|
"id": "gpt-4o",
|
|
"name": "GPT-4o",
|
|
"envKey": "OPENAI_API_KEY",
|
|
"baseUrl": "https://api.openai.com/v1"
|
|
}
|
|
],
|
|
"anthropic": [
|
|
{
|
|
"id": "claude-sonnet-4-20250514",
|
|
"name": "Claude Sonnet 4",
|
|
"envKey": "ANTHROPIC_API_KEY"
|
|
}
|
|
],
|
|
"gemini": [
|
|
{
|
|
"id": "gemini-2.5-pro",
|
|
"name": "Gemini 2.5 Pro",
|
|
"envKey": "GEMINI_API_KEY"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
> [!tip]
|
|
>
|
|
> Don't forget to also set `env`, `security.auth.selectedType`, and `model.name` alongside `modelProviders` — see the [complete example above](#recommended-one-file-setup-via-settingsjson) for reference.
|
|
|
|
**`ModelConfig` fields (each entry inside `modelProviders`):**
|
|
|
|
| Field | Required | Description |
|
|
| ------------------ | -------- | -------------------------------------------------------------------- |
|
|
| `id` | Yes | Model ID sent to the API (e.g. `gpt-4o`, `claude-sonnet-4-20250514`) |
|
|
| `name` | No | Display name in the `/model` picker (defaults to `id`) |
|
|
| `envKey` | Yes | Environment variable name for the API key (e.g. `OPENAI_API_KEY`) |
|
|
| `baseUrl` | No | API endpoint override (useful for proxies or custom endpoints) |
|
|
| `generationConfig` | No | Fine-tune `timeout`, `maxRetries`, `samplingParams`, etc. |
|
|
|
|
> [!note]
|
|
>
|
|
> When using the `env` field in `settings.json`, credentials are stored in plain text. For better security, prefer `.env` files or shell `export` — see [Step 2](#step-2-set-environment-variables).
|
|
|
|
For the full `modelProviders` schema and advanced options like `generationConfig`, `customHeaders`, and `extra_body`, see [Model Providers Reference](model-providers.md).
|
|
|
|
#### Step 2: Set environment variables
|
|
|
|
Qwen Code reads API keys from environment variables (specified by `envKey` in your model config). There are multiple ways to provide them, listed below from **highest to lowest priority**:
|
|
|
|
**1. Shell environment / `export` (highest priority)**
|
|
|
|
Set directly in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or inline before launching:
|
|
|
|
```bash
|
|
|
|
# Alibaba Dashscope
|
|
export DASHSCOPE_API_KEY="sk-..."
|
|
|
|
# OpenAI / OpenAI-compatible
|
|
export OPENAI_API_KEY="sk-..."
|
|
|
|
# Anthropic
|
|
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
|
|
# Google GenAI
|
|
export GEMINI_API_KEY="AIza..."
|
|
```
|
|
|
|
**2. `.env` files**
|
|
|
|
Qwen Code auto-loads the **first** `.env` file it finds (variables are **not merged** across multiple files). Only variables not already present in `process.env` are loaded.
|
|
|
|
Search order (from the current directory, walking upward toward `/`):
|
|
|
|
1. `.qwen/.env` (preferred — keeps Qwen Code variables isolated from other tools)
|
|
2. `.env`
|
|
|
|
If nothing is found, it falls back to your **home directory**:
|
|
|
|
3. `~/.qwen/.env`
|
|
4. `~/.env`
|
|
|
|
> [!tip]
|
|
>
|
|
> `.qwen/.env` is recommended over `.env` to avoid conflicts with other tools. Some variables (like `DEBUG` and `DEBUG_MODE`) are excluded from project-level `.env` files to avoid interfering with Qwen Code behavior.
|
|
|
|
**3. `settings.json` → `env` field (lowest priority)**
|
|
|
|
You can also define API keys directly in `~/.qwen/settings.json` under the `env` key. These are loaded as the **lowest-priority fallback** — only applied when a variable is not already set by the system environment or `.env` files.
|
|
|
|
```json
|
|
{
|
|
"env": {
|
|
"DASHSCOPE_API_KEY": "sk-...",
|
|
"OPENAI_API_KEY": "sk-...",
|
|
"ANTHROPIC_API_KEY": "sk-ant-..."
|
|
}
|
|
}
|
|
```
|
|
|
|
This is the approach used in the [one-file setup example](#recommended-one-file-setup-via-settingsjson) above. It's convenient for keeping everything in one place, but be mindful that `settings.json` may be shared or synced — prefer `.env` files for sensitive secrets.
|
|
|
|
**Priority summary:**
|
|
|
|
| Priority | Source | Override behavior |
|
|
| ----------- | ------------------------------ | -------------------------------------------- |
|
|
| 1 (highest) | CLI flags (`--openai-api-key`) | Always wins |
|
|
| 2 | System env (`export`, inline) | Overrides `.env` and `settings.json` → `env` |
|
|
| 3 | `.env` file | Only sets if not in system env |
|
|
| 4 (lowest) | `settings.json` → `env` | Only sets if not in system env or `.env` |
|
|
|
|
#### Step 3: Switch models with `/model`
|
|
|
|
After launching Qwen Code, use the `/model` command to switch between all configured models. Models are grouped by protocol:
|
|
|
|
```
|
|
/model
|
|
```
|
|
|
|
The picker will show all models from your `modelProviders` configuration, grouped by their protocol (e.g. `openai`, `anthropic`, `gemini`). Your selection is persisted across sessions.
|
|
|
|
You can also switch models directly with a command-line argument, which is convenient when working across multiple terminals.
|
|
|
|
```bash
|
|
# In one terminal
|
|
|
|
qwen --model "qwen3-coder-plus"
|
|
|
|
# In another terminal
|
|
|
|
qwen --model "qwen3.5-plus"
|
|
```
|
|
|
|
## `qwen auth` CLI command
|
|
|
|
In addition to the in-session `/auth` slash command, Qwen Code provides a standalone `qwen auth` CLI command for managing authentication directly from the terminal — without starting an interactive session first.
|
|
|
|
### Interactive mode
|
|
|
|
Run `qwen auth` without arguments to get an interactive menu:
|
|
|
|
```bash
|
|
qwen auth
|
|
```
|
|
|
|
You'll see a selector with arrow-key navigation:
|
|
|
|
```
|
|
Select authentication method:
|
|
|
|
> Qwen OAuth - Free · 100 requests/day · Ending 2026-04-15
|
|
Alibaba Cloud Coding Plan - Paid · Up to 6,000 requests/5 hrs · All Alibaba Cloud Coding Plan Models
|
|
|
|
(Use ↑ ↓ arrows to navigate, Enter to select, Ctrl+C to exit)
|
|
```
|
|
|
|
### Subcommands
|
|
|
|
| Command | Description |
|
|
| ---------------------------------------------------- | ------------------------------------------------- |
|
|
| `qwen auth` | Interactive authentication setup |
|
|
| `qwen auth qwen-oauth` | Authenticate with Qwen OAuth |
|
|
| `qwen auth coding-plan` | Authenticate with Alibaba Cloud Coding Plan |
|
|
| `qwen auth coding-plan --region china --key sk-sp-…` | Non-interactive Coding Plan setup (for scripting) |
|
|
| `qwen auth status` | Show current authentication status |
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Authenticate with Qwen OAuth directly
|
|
qwen auth qwen-oauth
|
|
|
|
# Set up Coding Plan interactively (prompts for region and key)
|
|
qwen auth coding-plan
|
|
|
|
# Set up Coding Plan non-interactively (useful for CI/scripting)
|
|
qwen auth coding-plan --region china --key sk-sp-xxxxxxxxx
|
|
|
|
# Check your current auth configuration
|
|
qwen auth status
|
|
```
|
|
|
|
## Security notes
|
|
|
|
- Don't commit API keys to version control.
|
|
- Prefer `.qwen/.env` for project-local secrets (and keep it out of git).
|
|
- Treat your terminal output as sensitive if it prints credentials for verification.
|