Skip to Content
用户指南配置身份验证

身份验证

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、阿里云百炼，或自托管的兼容端点），请选择此选项。

快速开始（交互式，推荐用于本地使用）

当你在 CLI 中选择 OpenAI 兼容选项时，系统将提示你输入以下信息：

  • API 密钥
  • 基础 URL（默认值：https://api.openai.com/v1）
  • 模型（默认值：gpt-4o）

注意： CLI 可能会以明文形式显示密钥以供确认，请确保你的终端未被录制或共享。

通过命令行参数配置

 
# 仅指定 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 的行为。

示例：

 
# 项目特定设置（推荐）
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 中）。
  • 如果终端输出打印了用于验证的凭据，请将其视为敏感信息。
Last updated on
设置忽略文件