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 是什么
它是一款在终端中运行的开源编程智能体,能读取你的仓库、编辑文件并执行命令。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。文档列出了五个顶层选项:
- Qwen Account with Subscription:通过浏览器登录,需要 Plus 或 Pro 订阅。
- QwenCloud:Token Plan,或按量付费的 Standard API Key。
- Alibaba ModelStudio:Coding Plan、Token Plan 或 Standard API Key。
- Third-party Providers:内置列表,包括 DeepSeek、Kimi、OpenRouter 等,使用 API 密钥。
- 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: 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 日。





写评论