Authentication

Overview

Qwen Code supports two authentication methods, each suited for different use cases:

Qwen OAuth

Recommended for most users

Sign in with your qwen.ai account
1,000 free requests per day
No API key management required
Browser-based authentication flow

API Key

For advanced users and production

Use your own API keys
Support for multiple providers
Full control over models and quotas
Works in headless environments

You can switch between authentication methods at any time using the /auth command.

Qwen OAuth (Recommended)

Qwen OAuth is the easiest way to get started with Qwen Code. Sign in once and get immediate access to AI-powered coding assistance.

Features

Free tier: 1,000 requests per day at no cost
No API keys: No need to manage API keys or billing
Auto-refresh: Credentials refresh automatically
Secure: OAuth 2.0 standard with token encryption

Setup

Launch Qwen Code

Start Qwen Code from your terminal:

qwen

Run auth command

Type the auth command:

qwen> /auth

Select Qwen OAuth

Choose Qwen OAuth from the authentication options menu.

Complete browser flow

A browser window opens automatically
Sign in with your qwen.ai account (or create a new account)
Authorize Qwen Code to access your account
You’ll be redirected to a success page
Return to your terminal—authentication is complete!

✓ Authentication successful!
✓ Signed in as: [email protected]
✓ Free tier: 1,000 requests/day remaining

Usage in Production

Qwen OAuth requires interactive browser access. In non-interactive environments (CI/CD, Docker containers, SSH sessions without X11), use API key authentication instead.

Environments where OAuth won’t work:

Continuous Integration (CI/CD) pipelines
Docker containers without display
SSH sessions without X11 forwarding
Headless servers
Automated scripts

For these scenarios, use API Key authentication.

Credential Storage

OAuth credentials are stored securely:

Location: ~/.qwen/auth/oauth-tokens.json
Encryption: Tokens are encrypted at rest
Auto-refresh: Access tokens refresh automatically before expiration
Privacy: Never shared or sent to third parties

Checking Your Usage

Check remaining requests at any time:

qwen> /stats

Output:

Session Statistics
──────────────────────────────────────
Provider:        Qwen OAuth
Model:           qwen3.5-plus
Requests today:  247 / 1,000
Tokens used:     45,892
Session time:    1h 23m

Signing Out

To sign out and clear credentials:

qwen> /auth
# Select "Sign Out" or choose a different authentication method

Or manually remove credentials:

rm -rf ~/.qwen/auth/

API Key Authentication

API key authentication gives you full control over which AI provider and model to use. It’s ideal for:

Production deployments
CI/CD pipelines
Custom model configurations
Team environments with shared API keys
Users who want to use their own API quotas

Supported Providers

Qwen Code supports multiple AI providers through API key authentication:

OpenAI-Compatible
Anthropic
Google GenAI

Providers:

Alibaba Cloud Dashscope (Qwen models)
Alibaba Cloud Bailian Coding Plan
OpenAI (GPT models)
OpenRouter (multiple models)
Any OpenAI-compatible API

Required:

API key
Base URL (if not using OpenAI directly)
Model ID

Providers:

Anthropic (Claude models)

Required:

Anthropic API key
Base URL
Model ID (e.g., claude-sonnet-4-20250514)

Providers:

Google Gemini (via GenAI API)
Vertex AI

Required:

Google API key
Model ID (e.g., gemini-2.5-pro)

Quick Setup with settings.json

The recommended way to configure API key authentication is using ~/.qwen/settings.json:

Create settings file

Create or edit ~/.qwen/settings.json in your home directory:

mkdir -p ~/.qwen
nano ~/.qwen/settings.json

Add configuration

Example for Qwen models via Dashscope:

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

Get your API key

Dashscope: Get key from Alibaba Cloud Dashscope
OpenAI: Get key from OpenAI Platform
Anthropic: Get key from Anthropic Console
Google: Get key from Google AI Studio

Start Qwen Code

qwen

Your configuration takes effect automatically.

Configuration Fields

Field	Description
`modelProviders`	Define available models per protocol (`openai`, `anthropic`, `gemini`)
`modelProviders[].id`	Model ID sent to the API (e.g., `qwen3-coder-plus`, `gpt-4o`)
`modelProviders[].name`	Display name shown in model selection
`modelProviders[].baseUrl`	API endpoint URL (required for non-default endpoints)
`modelProviders[].envKey`	Environment variable name that holds the API key
`modelProviders[].description`	Optional description shown in model selection
`env`	Fallback place to store API keys (prefer environment variables for security)
`security.auth.selectedType`	Default auth protocol: `openai`, `anthropic`, `gemini`, `vertex-ai`, `qwen-oauth`
`model.name`	Default model to use on startup

Example Configurations

Alibaba Cloud Bailian Coding Plan

Higher quotas with a fixed monthly subscription:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.5-plus",
        "name": "qwen3.5-plus (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "qwen3.5-plus with thinking enabled",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      },
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY"
      }
    ]
  },
  "env": {
    "BAILIAN_CODING_PLAN_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus"
  }
}

Get your API key from Alibaba Cloud Bailian.

Multiple Providers (OpenAI + Anthropic + Gemini)

Configure multiple providers and switch between them:

{
  "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",
        "baseUrl": "https://api.anthropic.com"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.5-pro",
        "name": "Gemini 2.5 Pro",
        "envKey": "GEMINI_API_KEY"
      }
    ]
  },
  "env": {
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxx",
    "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxxx",
    "GEMINI_API_KEY": "AIzaxxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-4o"
  }
}

Switch between models during a session:

qwen> /model
# Select from: GPT-4o, Claude Sonnet 4, Gemini 2.5 Pro

Enable Thinking Mode (qwen3.5-plus)

For supported models with extended reasoning:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.5-plus",
        "name": "qwen3.5-plus (thinking)",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3.5-plus"
  }
}

Environment Variables

For better security, set API keys via environment variables instead of storing them in settings.json:

# Add to ~/.bashrc or ~/.zshrc
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

Never commit API keys to version control. Use environment variables or .env files (added to .gitignore).

Priority Order

Qwen Code checks for API keys in this order (highest to lowest priority):

Environment variables (from your shell or .env file)
Custom envKey (defined in modelProviders[].envKey)
settings.json env field (fallback, lowest priority)

Example:

// In settings.json, define envKey
{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "envKey": "DASHSCOPE_API_KEY",  // Qwen Code will look for this env var
        ...
      }
    ]
  }
}

# Set the environment variable
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxx"
qwen

Switching Authentication Methods

You can change authentication methods at any time:

Run /auth command

qwen> /auth

Select new method

Choose from:

Qwen OAuth
OpenAI-compatible API
Anthropic API
Google GenAI
Vertex AI

Complete setup

Follow the prompts to configure the new authentication method.

Project-Specific Configuration

Override global settings for specific projects by creating .qwen/settings.json in your project root:

cd your-project/
mkdir .qwen
nano .qwen/settings.json

Project settings override global settings:

{
  "security": {
    "auth": {
      "selectedType": "anthropic"
    }
  },
  "model": {
    "name": "claude-sonnet-4-20250514"
  }
}

Now this project always uses Claude, while other projects use your global defaults.

Use project-specific settings to configure different models for different types of projects (e.g., Claude for research, Qwen for coding).

Validation

Qwen Code validates your authentication configuration on startup:

✓ Authentication: API Key (OpenAI-compatible)
✓ Model: qwen3-coder-plus
✓ Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
✓ API Key: Found (DASHSCOPE_API_KEY)

If validation fails, you’ll see helpful error messages:

✗ Authentication failed
✗ DASHSCOPE_API_KEY environment variable not found

Please set the API key:
  export DASHSCOPE_API_KEY="your-api-key"

Or add it to ~/.qwen/settings.json

Troubleshooting

OAuth browser doesn't open

Solutions:

Manually open the URL shown in the terminal
Check if your BROWSER environment variable is set correctly
Try running qwen from a different terminal emulator
Use API key authentication in headless environments

API key not found

Solutions:

Verify the environment variable name matches envKey in settings
Check if the variable is exported: echo $DASHSCOPE_API_KEY
Restart your terminal after adding to .bashrc/.zshrc
Use absolute paths for .env files

Invalid API key error

Solutions:

Verify the API key is correct (no extra spaces)
Check if the key has expired
Ensure you have sufficient quota/credits
Verify the key has permissions for the model you’re using

Wrong model provider

Solutions:

Check security.auth.selectedType in settings.json
Ensure the model ID matches the provider protocol
Use /model to switch models during a session
Verify baseUrl matches your provider’s API endpoint

Rate limit exceeded

Solutions:

For Qwen OAuth: Wait until your daily quota resets (midnight UTC)
For API keys: Check your provider’s rate limits
Use /compress to reduce token usage
Switch to a different model or provider with /model

Security Best Practices

Use Environment Variables

Store API keys in environment variables or .env files, never in settings.json committed to git.

Rotate Keys Regularly

Rotate API keys periodically, especially after team member changes.

Limit Key Scope

Use API keys with minimal required permissions. Avoid admin or billing access.

Use .gitignore

Add .env and settings.json files containing secrets to .gitignore.

The ~/.qwen/settings.json file in your home directory should be kept private. Never commit it to version control.

Next Steps

Quick Start

Complete your first AI-assisted coding session

Model Providers

Learn more about configuring multiple providers

Environment Variables

Full reference for environment variable configuration

Settings Reference

Complete settings.json documentation

Getting Started

Core Features

Configuration

IDE Integration

Advanced

Overview

Qwen OAuth

API Key

Qwen OAuth (Recommended)

Features

Setup

Usage in Production

Credential Storage

Checking Your Usage

Signing Out

API Key Authentication

Supported Providers

Quick Setup with settings.json

Configuration Fields

Example Configurations

Environment Variables

Priority Order

Switching Authentication Methods

Project-Specific Configuration

Validation

Troubleshooting

Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Limit Key Scope

Use .gitignore

Next Steps

Quick Start

Model Providers

Environment Variables

Settings Reference

Getting Started

Core Features

Configuration

IDE Integration

Advanced

​Overview

Qwen OAuth

API Key

​Qwen OAuth (Recommended)

​Features

​Setup

​Usage in Production

​Credential Storage

​Checking Your Usage

​Signing Out

​API Key Authentication

​Supported Providers

​Quick Setup with settings.json

​Configuration Fields

​Example Configurations

​Environment Variables

​Priority Order

​Switching Authentication Methods

​Project-Specific Configuration

​Validation

​Troubleshooting

​Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Limit Key Scope

Use .gitignore

​Next Steps

Quick Start

Model Providers

Environment Variables

Settings Reference

Overview

Qwen OAuth (Recommended)

Features

Setup

Usage in Production

Credential Storage

Checking Your Usage

Signing Out

API Key Authentication

Supported Providers

Quick Setup with settings.json

Configuration Fields

Example Configurations

Environment Variables

Priority Order

Switching Authentication Methods

Project-Specific Configuration

Validation

Troubleshooting

Security Best Practices

Next Steps