认证

Qwen Code 支持两种认证方式。选择与你运行 CLI 方式相匹配的一种：

• Qwen OAuth（推荐）：在浏览器中使用你的 qwen.ai 账户登录。
• OpenAI 兼容 API：使用 API 密钥（OpenAI 或任何 OpenAI 兼容的提供商/端点）。

选项 1：Qwen OAuth（推荐且免费）👍

如果你想要最简单的设置并且正在使用 Qwen 模型，请使用此选项。

• 工作原理：首次启动时，Qwen Code 会打开浏览器登录页面。完成登录后，凭证将被缓存在本地，因此通常你无需再次登录。
• 要求：一个 qwen.ai 账户 + 网络访问权限（至少首次登录时需要）。
• 优势：无需管理 API 密钥，自动刷新凭证。
• 费用和配额：免费，配额为 每分钟 60 次请求 和 每天 2,000 次请求。

启动 CLI 并按照浏览器流程操作：

qwen

选项 2：OpenAI 兼容 API（API 密钥）

如果你想使用 OpenAI 模型或任何提供 OpenAI 兼容 API 的提供商（例如 OpenAI、Azure OpenAI、OpenRouter、ModelScope、阿里云百炼或自托管的兼容端点），请使用此选项。

推荐：编码计划（基于订阅）🚀

如果你希望为 qwen3-coder-plus 模型获得可预测的成本和更高的使用配额，请选择此方案。

• 工作方式：以固定月费订阅编码计划，然后配置 Qwen Code 使用专用端点和你的订阅 API 密钥。
• 要求：需要从 阿里云百炼  购买有效的编码计划订阅。
• 优势：更高的使用配额、可预测的月度成本、访问最新的 qwen3-coder-plus 模型。
• 费用与配额：根据计划而异（见下表）。

编程计划定价与配额

编程计划快速设置

当您在 CLI 中选择 OpenAI 兼容选项时，请输入以下值：

• API key: sk-sp-xxxxx
• Base URL: https://coding.dashscope.aliyuncs.com/v1
• Model: qwen3-coder-plus

注意: 编程计划 API key 的格式为 sk-sp-xxxxx，这与标准的阿里云 API key 不同。

通过环境变量配置

设置这些环境变量以使用 Coding Plan：

export OPENAI_API_KEY="your-coding-plan-api-key"  # 格式: sk-sp-xxxxx
export OPENAI_BASE_URL="https://coding.dashscope.aliyuncs.com/v1"
export OPENAI_MODEL="qwen3-coder-plus"

有关 Coding Plan 的更多详情，包括订阅选项和故障排除，请参阅完整的 Coding Plan 文档 。

其他兼容 OpenAI 的提供商

如果你正在使用其他提供商（OpenAI、Azure、本地 LLM 等），请使用以下配置方法。

通过命令行参数配置

 
# 仅 API 密钥
qwen-code --openai-api-key "your-api-key-here"
 
# 自定义基础 URL（兼容 OpenAI 的端点）
qwen-code --openai-api-key "your-api-key-here" --openai-base-url "https://your-endpoint.com/v1"
 
# 自定义模型
qwen-code --openai-api-key "your-api-key-here" --model "gpt-4o-mini"

通过环境变量配置

你可以在 shell 配置文件、CI 或 .env 文件中设置这些变量：

export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="https://api.openai.com/v1"  # 可选
export OPENAI_MODEL="gpt-4o"                        # 可选

使用 .env / .qwen/.env 持久化环境变量

Qwen Code 将自动从找到的第一个 .env 文件加载环境变量（变量不会在多个文件间合并）。

搜索顺序：

1. 从当前目录开始，向上遍历到 /：
   1. .qwen/.env
   2. .env
2. 如果没有找到，则回退到你的主目录：
   • ~/.qwen/.env
   • ~/.env

推荐使用 .qwen/.env 来将 Qwen Code 变量与其他工具隔离。某些变量（如 DEBUG 和 DEBUG_MODE）会从项目 .env 文件中排除，以避免干扰 qwen-code 的行为。

示例：

 
# 项目特定设置（推荐）
```bash
mkdir -p .qwen
cat >> .qwen/.env <<'EOF'
OPENAI_API_KEY="your-api-key"
OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"
EOF

# 用户全局设置（在所有地方都可用）
mkdir -p ~/.qwen
cat >> ~/.qwen/.env <<'EOF'
OPENAI_API_KEY="your-api-key"
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_MODEL="qwen3-coder-plus"
EOF

切换认证方式（无需重启）

在 Qwen Code UI 中运行：

/auth

非交互式/无头环境（CI、SSH、容器）

在非交互式终端中，通常无法完成 OAuth 浏览器登录流程。 通过环境变量使用 OpenAI 兼容的 API 方法：

• 至少设置 OPENAI_API_KEY。
• 可选地设置 OPENAI_BASE_URL 和 OPENAI_MODEL。

如果在非交互式会话中未设置这些变量中的任何一个，Qwen Code 将以错误退出。

安全注意事项

• 不要将 API 密钥提交到版本控制中。
• 优先使用 .qwen/.env 存放项目本地的密钥（并确保它不在 git 中）。
• 如果终端输出打印了用于验证的凭证，请将其视为敏感信息。