Qwen CLI 安装与使用完全指南：Qwen Code（2026）

摘要

• Qwen CLI(官方叫 Qwen Code）是阿里 Qwen 团队的开源终端编码智能体——Gemini CLI 的一个 fork,针对 Qwen 模型调过。装法:Node.js 22+ 上 npm install -g @qwen-code/qwen-code@latest。
• 多数攻略漏掉的大变化:Qwen OAuth 免费额度已于 2026-04-15 停止。 老的"每天 2000 次免费请求"不好使了——你现在得配一个 API provider。
• 配置就是把它指向任意 OpenAI 兼容端点,三个环境变量搞定:OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL。全部配置就这些。
• 一个端点能同时跑 Qwen *和* 别的模型。把 OPENAI_BASE_URL 指向 [Velokey](https://api.velokey.ai),就能用一把 key 让 Qwen Code 跑 qwen3.7-max、GPT、Claude 或 GLM。

Qwen CLI（Qwen Code）是什么？

Qwen CLI 是 Qwen Code 的通俗叫法——阿里 Qwen 团队做的开源 AI 编码智能体,跑在你的终端里。它读写你的代码库、执行命令、按智能体方式推进任务,形态跟 Claude Code、Gemini CLI 一样。事实上它就是从 Gemini CLI fork 来的,把提示词和解析器针对 Qwen 的模型调了。

装之前有两点值得知道。第一,包名叫 @qwen-code/qwen-code,所以"qwen cli""qwen-cli""qwen code cli"指的都是同一个工具。第二——这点绊倒不少人——它不锁死在 Qwen 自家服务器上。它说的是 OpenAI 兼容协议,所以你可以让它跑在 Qwen 的 API、OpenRouter、本地模型或网关上。这一点现在比以往更重要,因为免费那条路变了。

怎么安装 Qwen Code CLI？

在 Node.js 22 或更高版本上,用 npm 全局安装 Qwen Code:

npm install -g @qwen-code/qwen-code@latest
qwen --version

macOS 上也能用 Homebrew(brew install qwen-code),Linux 和 Windows 有独立安装包。安装时真正要紧的是这些:

如果装完出现 qwen: command not found,是你的 npm 全局 bin 目录没在 PATH 里——跑 npm config get prefix,把它下面的 /bin 加进 PATH。Linux 上全局安装报权限错,通常是要 sudo,或者更好——用 nvm 管理的 Node,这样全局安装不碰系统目录。

免费额度没了,现在怎么配 Qwen CLI？

你得用一个 OpenAI 兼容的 API key 来配 Qwen Code,因为 免费的 Qwen OAuth 额度已于 [2026-04-15 停止](https://github.com/QwenLM/qwen-code/issues/3203)——缓存的 token 可能还能撑一小会儿,但新登录会被拒。那个免费额度过去给每天 2000 次请求、每分钟 60 次;很多"免费用 Qwen Code"的教程还在照抄,现在都是错的。

当前的配置就是三个环境变量。设好、跑 qwen、在鉴权菜单里选 "OpenAI":

export OPENAI_API_KEY="你的_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"
qwen

想用配置文件?Qwen Code 读 ~/.qwen/settings.json(或项目级的 .qwen/settings.json),在里面把 model provider 定义一次:

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [{
        "id": "qwen3-coder-plus",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }]
    }
  },
  "security": { "auth": { "selectedType": "openai" } }
}

你现在的 provider 选项是:阿里云 ModelStudio 的 Coding Plan(固定月费订阅)、DashScope 的按 token 付费 API、OpenRouter、Fireworks,或任何别的 OpenAI 兼容端点。官方 auth 文档 列了当前这套——看它,别看旧博客,因为过时的恰恰就是这一块。

怎么让 Qwen CLI 用一个端点跑任意模型？

把 OPENAI_BASE_URL 指向一个网关,一把 key 就能让 Qwen Code 跑多个模型——不用逐家开账号来回倒。既然 Qwen Code 只要一个 OpenAI 兼容端点,Velokey 就能直接顶上:一把 key,同一个 base URL 触达 Qwen、GPT、Claude、GLM。

export OPENAI_API_KEY="sk-你的velokey密钥"
export OPENAI_BASE_URL="https://api.velokey.ai/v1"
export OPENAI_MODEL="qwen3.7-max"
qwen

实际好处是换后端不用重新鉴权。Qwen Code 是针对 Qwen 模型调的,所以 [qwen3.7-max](/model/qwen3.7-max) 是最自然的默认——但某个任务想换模型时,只改一个变量:

因为是走额度按 token 计费,没有单独的订阅,也没有每日请求墙——智能体实际用多少,你付多少。这笔账怎么算,见我们的 Claude API 价格指南;同样的按 token 逻辑也适用于 Qwen 和其余模型。

Qwen CLI 用不了？常见报错

Qwen CLI 的大多数失败是环境或鉴权问题,不是 bug——而且就那么几类原因。先 qwen --safe-mode 关掉你的自定义;如果问题消失,再一项项开回来找出元凶。

如果你的 key 存在某个网页工具里而不是环境变量里,会话丢了会抛出另一类错——见我们讲的 修复 "API key not found in cookies"。想看把 API key 接进一个客户端的完整流程,如何用 API key 调用一个模型 把这套配置讲清了。

常见问题

怎么安装 Qwen CLI？

在 Node.js 22 或更高版本上跑 npm install -g @qwen-code/qwen-code@latest,再 qwen --version 确认。macOS 上也可以 brew install qwen-code。如果撞 command not found,把你的 npm 全局 bin 目录(npm config get prefix 加 /bin)加进 PATH。

Qwen CLI 还免费吗？

内置那条路不再免费了——Qwen OAuth 免费额度已于 2026-04-15 停止。CLI 本身是开源、免费的,但你现在得配一个 API provider:阿里 ModelStudio 的 Coding Plan、DashScope 按 token 付费、OpenRouter,或任何你自己配 key 的 OpenAI 兼容端点。

怎么用自己的 API key 跑 Qwen CLI？

设三个环境变量——OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL——再跑 qwen,在鉴权菜单里选 "OpenAI"。你也可以在 ~/.qwen/settings.json 里定义一个 provider。base URL 指向你在用的那个 OpenAI 兼容 provider。

Qwen Code CLI 支持哪些模型？

Qwen Code 是针对 Qwen3-Coder 这类 Qwen 模型调的,但因为它说 OpenAI 兼容协议,所以能跑 OpenAI、Anthropic、Gemini、OpenRouter、Ollama 或 vLLM 的本地模型,以及网关。把 OPENAI_MODEL 设成你 provider 暴露的那个模型 ID 即可。

为什么 Qwen CLI 报 "command not found"？

你的 npm 全局 bin 目录没在 PATH 里。跑 npm config get prefix 找到安装前缀,把它下面的 /bin 子目录加进 PATH,重开 shell。这是装完最常见的错,跟工具本身没关系。

能让 Qwen CLI 跑网关而不是 Qwen 的 API 吗？

能。Qwen Code 接受任何 OpenAI 兼容端点,所以你可以把 OPENAI_BASE_URL 指向一个网关,用一把 key 触达多个模型。把 OPENAI_MODEL 设成你想要的模型——要最好的工具调用保真度就用 Qwen 模型,或按任务换别的模型。