Authentication

Qwen Code supports two authentication methods. Pick the one that matches how you want to run the CLI:

• Qwen OAuth (recommended): sign in with your qwen.ai account in a browser.
• API-KEY: use an API key to connect to any supported provider. More flexible — supports OpenAI, Anthropic, Google GenAI, Alibaba Cloud Bailian, and other compatible endpoints.

👍 Option 1: Qwen OAuth (recommended & 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

🚀 Option 2: API-KEY (flexible)

Use this if you want more flexibility over which provider and model to use. Supports multiple protocols and providers, including OpenAI, Anthropic, Google GenAI, Alibaba Cloud Bailian, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted compatible endpoint.

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.

Option1: Coding Plan（Aliyun Bailian）

Use this if you want predictable costs with higher usage quotas for the qwen3-coder-plus model.

• 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 Bailian .
• Benefits: Higher usage quotas, predictable monthly costs, access to the latest qwen3-coder-plus model.
• Cost & quota: View Alibaba Cloud Bailian Coding Plan documentation .

Enter qwen in the terminal to launch Qwen Code, then enter the /auth command and select API-KEY

After entering, select Coding Plan:

Enter your sk-sp-xxxxxxxxx key, then use the /model command to switch between all Bailian 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 Coding Plan 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 Bailian 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"
  }
}

Option2: Third-party API-KEY

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.

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-coder-next"

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.