安装 Qwen Code，选好认证方式

本课目标

• 用官方一键脚本或 npm 装好 Qwen Code，确认 qwen --version 能输出版本号
• 看懂首次启动时 /auth 菜单里的五种认证方式，选出适合自己的那一种
• 用 ~/.qwen/settings.json 写好阿里云百炼的 API Key 配置，脚本和 CI 里也能直接用

前置条件

• Linux 或 macOS 终端（Windows 用 PowerShell，命令见第 1 步）
• 一个想让智能体帮忙的代码目录，最好已经 git init，方便随时 git diff 查看改动
• 以下任选其一：千问账号的 Plus / Pro 订阅、千问 AI 平台或百炼的 API Key、百炼 Coding Plan / Token Plan；暂时都没有也能先做完安装，第 2 课教你用本地模型免费跑通

第 1 步：安装 Qwen Code

官方首推独立安装包，脚本会自带运行时，不要求本机先装 Node.js。Linux / macOS 执行：

BASE=https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation
curl -fsSL "$BASE/install-qwen-standalone.sh" | bash

Windows PowerShell 执行：

$base = "https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation"
irm "$base/install-qwen-standalone.ps1" | iex

两条命令和官方文档里的一行写法等价，只是先把下载目录存进变量，避免一行太长。

对照结果（测试机实跑，进度条已省略）：

Installing Qwen Code version: 0.27.3

INFO: Downloading qwen-code-linux-x64.tar.gz
Successfully added qwen to $PATH in ~/.bashrc

Qwen Code 0.27.3 installed successfully, to start:

source ~/.bashrc  # Load new PATH (or open a new terminal)
cd <project>  # Open directory
qwen          # Run command

脚本把程序装在 ~/.local 下，并把 PATH 写进 ~/.bashrc。照提示执行 source ~/.bashrc，或者新开一个终端。

如果你已经有 Node.js 22 或更高版本，也可以用 npm 安装：

node -v
npm install -g @qwen-code/qwen-code@latest

macOS / Linux 上装了 Homebrew 的，还可以用 brew install qwen-code。

第 2 步：确认版本

qwen --version

对照结果：

0.27.3

用 npm 安装、而本机 Node.js 是 24 版时，每条 qwen 命令前会多出一行警告，内容是建议升级到 Node.js 26.12.1。它不影响使用，后文的对照结果里省略了这一行。

第 3 步：先看看没配认证时会怎样

进入你的项目目录，用无头模式问一句：

cd /path/to/your-project
qwen "hello"
echo "exit=$?"

对照结果（原文是一整行，这里按单词折了行）：

No auth type is selected. Please configure an auth type
(e.g. via settings or `--auth-type`) before running in
non-interactive mode.
exit=1

说明安装没问题，只是还没告诉 Qwen Code 该连哪家模型。

第 4 步：交互式选择认证方式

在项目目录里直接运行 qwen 进入交互界面，首次启动会弹出认证菜单；以后想换，随时输入 /auth。按官方文档，菜单的五个一级选项是：

• Qwen Account with Subscription：用千问账号登录（Qwen OAuth），消耗 chat.qwen.ai 的 Plus 或 Pro 订阅额度，要走浏览器授权，不适合 CI
• QwenCloud：官方推荐。子菜单里选 Token Plan（月度额度）或 Standard API Key（按量付费），再明确选平台：中国区是「千问AI平台」，国际区是 QwenCloud
• Alibaba ModelStudio：阿里云百炼，子菜单有 Coding Plan、Token Plan、Standard API Key 三种
• Third-party Providers：内置的第三方厂家，如 DeepSeek、Kimi、MiniMax、Z.AI、ModelScope、OpenRouter 等，填 API Key 即可
• Custom Provider：自己填地址，接本地服务、代理或兼容 OpenAI / Anthropic / Gemini 协议的接口

认证完成后，在会话里输入 /doctor 可以检查当前认证和环境，输入 /model 可以在已配置的模型之间切换。

第 5 步：用 settings.json 写死配置（脚本和 CI 用）

浏览器登录在服务器和 CI 里走不通，官方给的做法是直接写 ~/.qwen/settings.json。下面是官方文档里百炼（DashScope）API Key 的完整示例，把 sk-xxxxxxxxxxxxx 换成你自己的 Key：

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

四个字段各管一件事：

• modelProviders：声明有哪些模型、怎么连。键名 openai 表示走 OpenAI 兼容协议
• env：顺手存 Key，优先级最低，命令行 export 和 .env 文件都会覆盖它
• security.auth.selectedType：启动时用哪种协议，写了它就不用再跑 /auth
• model.name：默认模型，必须等于 modelProviders 里某一项的 id

保存后再执行第 3 步的 qwen "hello"，就能拿到模型回复。

如果你买的是百炼 Coding Plan，官方给的环境变量写法是：

export BAILIAN_CODING_PLAN_API_KEY="sk-sp-xxxxxxxxx"
export OPENAI_BASE_URL="https://coding.dashscope.aliyuncs.com/v1"
export OPENAI_MODEL="qwen3-coder-plus"

注意：BAILIAN_CODING_PLAN_API_KEY 这类厂家专用变量，要在 settings.json 里有一项把它声明为 envKey 才生效；只想靠环境变量选中 OpenAI 兼容认证，就改为导出 OPENAI_API_KEY。

常见坑

• 找不到 qwen 命令：独立安装包把 PATH 写进了 ~/.bashrc，当前终端要先 source ~/.bashrc 或者重开；zsh 用户检查 ~/.zshrc
• qwen auth 不能用了：这个子命令已经移除。测试机上执行 qwen auth status，只会打印一段迁移说明，最后一行是 Check auth status → /doctor。交互式用 /auth，脚本里用环境变量或 settings.json
• Coding Plan 地址填错：Coding Plan 的专用地址是 https://coding.dashscope.aliyuncs.com/v1（国际区是 coding-intl），和普通百炼的 compatible-mode/v1 不是同一个
• Key 明文泄露：settings.json 的 env 是明文。官方建议把 Key 放进项目的 .qwen/.env 并加进 .gitignore，不要提交到仓库
• npm 装完报 Node 版本问题：npm 方式要求 Node.js 22 及以上，版本太低时改用第 1 步的独立安装包

小结

到这里 Qwen Code 已经装好，你也知道了五种认证方式各自适合什么场景，并能用一份 settings.json 让它在无人值守的环境里直接启动。下一课不用任何付费 Key，用本地模型把对话和无头模式跑一遍。

参考来源

https://github.com/QwenLM/qwen-code

https://github.com/QwenLM/qwen-code/blob/main/docs/users/quickstart.md

https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/auth.md

https://qwenlm.github.io/qwen-code-docs/zh/users/overview