Qwen Code 安装与使用教程:开源终端编程智能体

一步步教你安装 Qwen Code、连接模型(包括本地模型),并安全地使用 Plan Mode 和操作审批,内容均来自项目官方文档。

Graphic of a code card showing a terminal command to install Qwen Code, the open-source terminal coding agent.

Qwen Code 最初是基于 Google Gemini CLI 构建的项目,如今它自己在 GitHub 上已有超过 30,000 颗星。README 写道,项目最初基于 Gemini CLI v0.8.2,从 v0.1 起不再与上游同步,逐渐发展成一个独立的、支持多种协议的编程智能体。

要点速览

  • Qwen Code 是一款面向终端的开源编程智能体,采用 Apache-2.0 许可证,最初是 Gemini CLI 的分支。
  • 可以用独立安装脚本、npm(需 Node.js 22 或更高版本)或 Homebrew 安装,然后运行 /auth 连接模型。
  • 文档中没有任何登录方式被描述为免费,想零成本使用,就接入本地的 Ollama、vLLM 或 LM Studio 服务器。
  • 面对新代码库,先用只读的 Plan Mode,用 /diff 审查改动,用 /restore 回滚。

本教程介绍如何安装 Qwen Code、登录(或接入免费的本地模型),并在真实项目中安全使用。以下内容全部来自项目在 GitHub 上的 README 和文档,核对时间为 2026 年 11 月 15 日。本文没有实际运行这些命令,请先在一个临时文件夹里试用。

准备工作

  • macOS、Linux 或 Windows 上的终端
  • 如果选择 npm 安装,需要 Node.js 22 或更高版本
  • 一个用来试用的代码项目(最好是备用仓库)
  • 付费使用或自行托管模型的方式:Qwen 订阅、API 密钥或本地模型服务器
Qwen Code 的五种登录方式示意图,从 Qwen Account 到自定义本地模型提供商

Qwen Code 是什么

它是一款在终端中运行的开源编程智能体,能读取你的仓库、编辑文件并执行命令。GitHub 显示其许可证为 Apache-2.0,README 称它支持 OpenAI、Anthropic、Gemini 和 Qwen 的 API,也支持任何第三方提供商或 Ollama、vLLM 等本地模型。截至 2026 年 11 月 15 日,最新发布标签为 v0.27.4。

项目还公布了自己的基准测试成绩:在 SWE-bench Verified 上,七个 Qwen Code 版本使用同一个 Qwen 3.7 Max 模型,平均得分在 76.40% 到 77.80% 之间。这是维护者自己的评测,并非独立测试。

数字速览

30,000GitHub 星标(超过)

77.80%自报最高 SWE-bench 平均分

v0.27.4最新发布标签

分步操作

1. 安装

README 给出了三种方式。第一种是适用于 Linux 和 macOS 的一行安装命令:

终端
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

把脚本直接通过管道交给 shell 执行,需要你信任它的来源。该安装脚本托管在阿里云的存储地址上,如果你更放心其他方式,可以改用 npm 或 Homebrew:

终端
npm install -g @qwen-code/qwen-code@latest

或者在 macOS 和 Linux 上使用 Homebrew:

终端
brew install qwen-code

README 为 Windows 用户提供了 PowerShell 安装脚本。使用独立安装脚本后,请重启终端,让环境变量生效。

2. 在项目中启动

终端
cd ~/projects/my-app
qwen

你应该会看到一个交互式终端会话。README 还提到一个 “1.0 Preview” 分支,但这里的说明针对主版本。

3. 登录或连接模型

输入 /auth。文档列出了五个顶层选项:

  1. Qwen Account with Subscription:通过浏览器登录,需要 Plus 或 Pro 订阅。
  2. QwenCloud:Token Plan,或按量付费的 Standard API Key。
  3. Alibaba ModelStudio:Coding Plan、Token Plan 或 Standard API Key。
  4. Third-party Providers:内置列表,包括 DeepSeek、Kimi、OpenRouter 等,使用 API 密钥。
  5. Custom Provider:本地服务器、代理或尚未支持的提供商。

当前文档中,这些选项都没有被描述为免费。想保持零成本,就使用本地模型。文档显示,Ollama、vLLM 和 LM Studio 可通过兼容 OpenAI 的地址接入。服务器端的配置可参考我们的用 Ollama 运行 AI 模型教程。然后参照文档自带的示例,在 ~/.qwen/settings.json 保存一份配置:

代码
{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "your-model-name",
        "name": "My local model",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "your-model-name" }
}

把 your-model-name 换成你的服务器显示的确切模型名称。文档说明 model.name 必须与某个 id 值一致。保存后运行 qwen。

4. 提出第一个问题

README 建议先用一个安全的只读提示词开始:

代码
Explain this repository and show me where to start.

然后运行 /init,文档称它会分析当前目录并创建初始上下文文件。Qwen Code 会自动加载你的 QWEN.md 和 AGENTS.md 说明文件。如果你已经在用技能文件,我们的 Claude Code 智能体技能教程解释了其中的思路,而 Qwen Code 的文档中也列出了它自己的 /skills 面板。

5. 决定给它多大权限

Qwen Code 有五种权限模式:Plan、Ask Permissions、Auto-Edit、Auto 和 YOLO。按 Shift+Tab(Windows 上为 Tab)可在它们之间切换。文档称 Auto 是开箱即用的默认模式,在这种模式下由分类器批准安全操作、拦截高风险操作;但同一页面又把 Ask Permissions 称为初始模式,所以请查看状态栏确认。面对新代码库,先进入 Plan Mode:

代码
/plan refactor the settings page

Plan Mode 是只读的,不会编辑或执行任何内容。输入 /plan exit 即可恢复之前的模式。按照文档的建议,YOLO 只用于你信任的项目。

6. 审查与撤销

用 /diff 打开未提交改动的交互式查看器。如果某一步出了问题,/restore 会列出检查点,并把项目文件恢复到某次工具调用之前的状态。

7. 在脚本中使用

README 称无头模式可在脚本和 CI 中运行:

终端
qwen -p "Summarize the repository layout."
流程图:安装 Qwen Code、连接模型、在只读模式下规划并审查改动

常见错误与解决方法

  • qwen: command not found.按照 README 的说明,安装后重启终端。如果用 npm 安装,请确认 Node.js 版本为 22 或更高。
  • 浏览器登录无法使用。在 CI 或无人值守的容器中,认证文档建议改用基于 API 密钥的方式,并通过环境变量配置。
  • qwen auth 没有作用。这个命令已被移除。请先运行 qwen,再输入 /auth。运行 /doctor 可检查当前的认证状态。
  • 本地模型超时。确认 baseUrl 以 /v1 结尾,且服务器正在运行。对于较慢的服务器,文档介绍了 streamIdleTimeoutMs 设置。
  • 不确定守护进程是否安全。如果你使用 qwen serve 或 qwen daemon start,请注意 README 说它默认在 loopback 上监听,且没有 bearer 认证,因此任何能访问它的本地进程都可以使用完整 API,包括执行代码。在共享主机上,请设置 QWEN_SERVER_TOKEN 并使用 --require-auth。

你知道吗?

qwen serve 守护进程默认在 loopback 上监听,且没有 bearer 认证,因此任何能访问它的本地进程都可以使用完整 API,包括执行代码。在共享主机上,请设置 QWEN_SERVER_TOKEN 并使用 –require-auth。

值得一试吗?

如果你喜欢 Claude Code 或 Gemini CLI 的工作方式,又想要一个能接入自己模型的工具,Qwen Code 只需简单安装就能用上。从 Plan Mode 开始,随时准备好一个 Git 提交,在亲自试用之前,把基准测试数据当作维护者的自报成绩来看待。

常见问题

Qwen Code 免费吗?

工具本身在 Apache-2.0 许可证下开源,但当前文档中 /auth 的登录选项都没有被描述为免费。想零成本使用,可通过 Ollama、vLLM 或 LM Studio 接入本地模型。

如何安装 Qwen Code?

README 给出了三种方式:适用于 Linux 和 macOS 的一行独立安装命令;在 Node.js 22 或更高版本下运行 npm install -g @qwen-code/qwen-code@latest;或者 brew install qwen-code。Windows 用户可使用 PowerShell 安装脚本。安装后请重启终端。

Qwen Code 能通过 Ollama 使用本地模型吗?

可以。保存一个 ~/.qwen/settings.json,把兼容 OpenAI 的提供商指向 http://localhost:11434/v1,并确保 model.name 与该提供商的某个 id 值一致。然后运行 qwen。

Qwen Code 的 Plan Mode 是什么?

Plan Mode 是五种权限模式之一,属于只读模式,不会编辑或执行任何内容。输入 /plan 加上你的任务即可启动,输入 /plan exit 返回之前的模式。

小测验

Qwen Code 最初基于哪个项目?

  • Claude Code
  • Gemini CLI
  • Ollama

README 称它最初基于 Gemini CLI v0.8.2。

哪种模式是只读的?

  • Plan
  • YOLO
  • Auto-Edit

文档称 Plan Mode 不编辑、不执行任何内容。

哪个命令能把项目文件恢复到检查点?

  • /diff
  • /init
  • /restore

/restore 会列出检查点,并把文件恢复到某次工具调用之前的状态。

资料来源

链接最后核对于 2026 年 11 月 15 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。