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 1,000 requests/day.

Start the CLI and follow the browser flow:

qwen

Or authenticate directly without starting a session:

qwen auth qwen-oauth

💳 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)  or Alibaba Cloud ModelStudio(intl) , 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 documentationBeijing intl .

Alibaba Cloud Coding Plan is available in two regions:

Interactive setup

You can set up Coding Plan authentication in two ways:

Option A: From the terminal (recommended for first-time setup)

# 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:

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

🚀 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:

{
  "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:

After saving the file, just run qwen — no interactive /auth setup needed.

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

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).

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:

{
  "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"
      }
    ]
  }
}

ModelConfig fields (each entry inside modelProviders):

For the full modelProviders schema and advanced options like generationConfig, customHeaders, and extra_body, see Model Providers Reference.

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:

 
# 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

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.

{
  "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 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:

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.

# 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:

qwen auth

You’ll see a selector with arrow-key navigation:

Select authentication method:

> Qwen OAuth - Free · Up to 1,000 requests/day · Qwen latest models
  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

Examples:

# 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.