Qwen Code 上手：开源平价 CLI 编程 Agent

有人问：我预算有限，又不想所有东西都跑在境外服务器上，有没有类似 Claude Code 但更便宜、更可控的选择？

答案是有的——Qwen Code。阿里通义千问团队把这个工具做成了开源的，代码放在 GitHub 上，默认可以接 Qwen 系列模型，也可以接任何兼容 OpenAI 接口格式的端点。如果你关心成本、关心数据走向、或者想在私有环境里用，它值得认真看一下。

这篇就帮你从零跑通：装好、配上模型、完成第一个任务、知道坑在哪。

---

Qwen Code 是什么

Qwen Code 是一个命令行 AI 编程 Agent，和 Claude Code 是同类工具：你在终端里启动它，它能读你项目的文件、写代码、执行命令、解读报错、提 git commit。

它的背景是阿里云通义千问团队，2025 年底开源发布，代码托管在 GitHub（QwenLM/qwen-code）。和闭源工具不同，你可以翻它的源码，甚至在自己服务器上部署一套完全私有的工作流。

核心特点：

• 开源：MIT 协议，可自托管、可二次开发
• 多模型后端：默认接 Qwen 系列，也支持任何兼容 OpenAI Chat Completions 格式的接口（本地 Ollama、第三方代理、DeepSeek 等）
• 中文友好：Qwen 模型本来就是强中文的，指令、注释、commit 信息写中文效果比大多数境外模型要好
• 成本可控：通义千问 API 的定价通常比 Claude API 低一个档次，预算敏感的场景有优势

---

和 Claude Code 有什么实际不同

同样是命令行编程 Agent，但两者的差异是真实的，不是参数上的细节：

维度	Qwen Code	Claude Code
是否开源	是，MIT	否，闭源
默认模型	Qwen 系列（国产）	Claude 系列（Anthropic）
能否对接其他模型	可以，只要接口兼容	官方只支持 Claude
成本	通义 API 相对低价	Claude API 相对高价
中文指令质量	强	强，但英文场景更优化
代码推理深度	和模型版本强相关	整体较强，稳定性高
数据走向	可对接国内端点或私有部署	发往 Anthropic 服务器

什么时候选 Qwen Code：预算敏感、项目指令以中文为主、需要对接私有模型或国内合规要求。

什么时候还是用 Claude Code：你习惯 Claude 的代码推理风格，或者项目本身是英文环境，稳定性优先。

两者的选型全景可以看 2.1 工具全景节，不同工具的定位差异写得比较清楚。

---

安装与配置

前置条件：Node.js

Qwen Code 是 npm 包，需要 Node.js 18 或更高版本。先检查：

node --version
npm --version

输出类似 v20.x.x 就满足条件。如果版本低于 18，去 Node.js 官网 下载 LTS 版覆盖安装。版本不对是新手最常见的安装失败原因之一。

安装 Qwen Code

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

全局安装，装完后 qwen 命令在任何路径都能用。网络情况正常的话 1-3 分钟完成。

验证安装：

qwen --version

看到版本号说明安装成功。如果提示命令找不到，检查 npm 全局目录是否在 PATH 里（见后面故障排查表）。

注意：具体的包名和命令，请以 官方 GitHub 仓库 的说明为准（截稿 2026-06），正式包名可能随版本调整。

配置模型与 API Key

这一步是和 Claude Code 差异最大的地方：Qwen Code 支持多个后端，你需要告诉它用哪个。

方式一：使用通义千问官方 API

先去 阿里云模型服务灵积平台 开通服务并获取 API Key，然后设置环境变量：

# Linux / Mac
export DASHSCOPE_API_KEY="你的Key"

# Windows PowerShell
$env:DASHSCOPE_API_KEY = "你的Key"

启动时指定模型（具体可用模型名以官方文档为准）：

qwen --model qwen-coder-plus

方式二：接兼容 OpenAI 格式的端点

如果你想接 DeepSeek 或其他兼容接口：

export OPENAI_API_KEY="你的Key"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"
qwen --model deepseek-coder

方式三：配置文件

Qwen Code 支持在项目根目录放配置文件（通常是 .qwen/config.json 或类似路径），把模型、端点、Key 写进去，不用每次手动设置环境变量。具体格式以官方仓库 README 为准——配置字段可能随版本更新。

---

跑通第一个任务

配置好后，cd 进你的项目目录（不要在空文件夹里用，没有上下文它发挥不出来），启动：

cd 你的项目路径
qwen

你会进入交互模式，看到类似这样的提示符：

Qwen Code vx.x.x
> 

你应该看到什么

在 > 后输入第一个任务：

> 帮我看一下这个项目的目录结构，然后写一个简单的工具函数用来格式化日期，加上测试

正常情况下，Qwen Code 会：

1. 扫描当前目录，列出它读到的文件结构
2. 告诉你它计划新建哪些文件
3. 等你确认（或者根据权限设置直接执行）
4. 写文件，然后展示内容

写完后去目录里实际看一眼文件是否创建——不要只看终端输出，养成核查文件的习惯，这样你对 Agent 实际行为的感知才是真实的。

让它跑一下测试

> 帮我跑一下刚才写的测试

它会读 package.json 找测试命令，然后展示要执行的命令等你确认，再把输出展示给你。如果测试通过，你会看到绿色的通过信息；如果报错，直接说"修一下这个报错"，它会读错误内容改代码。

提一个 commit

> 帮我把刚才的改动提一个 commit，信息写清楚做了什么

Qwen Code 会生成 commit 信息展示给你，确认后执行 git commit。你可以说"改成中文"让它重新生成。

---

适合谁用 Qwen Code

以下几类场景，Qwen Code 值得优先考虑：

预算敏感的个人开发者：通义 API 的定价比 Claude API 明显低，同样的工作量花费差距可以很显著，尤其是长时间重度使用场景。

中文代码注释和文档为主的项目：Qwen 模型在中文语境下的代码注释、文档生成、commit 信息质量通常很好，不用担心生成一堆蹩脚的翻译腔英文。

需要私有化或合规部署：开源意味着你可以在内网服务器上跑一套自己的推理服务，Qwen Code 对接本地端点，数据不出内网。

想对接多种模型做对比：同一套代码习惯，切换不同模型端点看效果差异，比维护多套工具链省事。

对 Claude Code 好奇但不想一上来就充值的：Qwen Code 接 Dashscope 的免费额度可以先试手感，确认自己用得上再决定要不要用付费模型。

---

新手常见坑

坑 1：Node 版本太旧安装能过但运行崩

npm install 不会报 Node 版本错误，但启动时会崩，报错信息往往不直接说是版本问题。先确认 node --version 在 18 以上再装。

坑 2：环境变量设了但 Qwen Code 不认

Windows 上 PowerShell 和 cmd 设置环境变量的语法不同，而且设了之后不重开终端不生效。遇到"API Key 无效"类报错，先确认：关掉当前终端，新开一个，再 echo $DASHSCOPE_API_KEY 看看值在不在。

坑 3：在空目录启动然后觉得它不好用

Qwen Code 和 Claude Code 一样，能力强烈依赖当前目录的上下文。在空文件夹里启动，它只能做和项目无关的通用问答，体现不出 Agent 的价值。一定要 cd 进真实项目再启动。

坑 4：模型名写错导致请求失败

通义模型的名字有几个版本（qwen-coder-plus、qwen-coder-turbo 等），拼错一个字符就返回"模型不存在"。建议直接复制官方文档里的模型 ID，不要手打。

坑 5：把 API Key 写进了代码库

配置文件里的 Key 如果提交到 git，一旦推到公开仓库就泄露了。正确做法是用环境变量，或者把配置文件加进 .gitignore。

---

故障排查表

症状	原因	解法
qwen: command not found	npm 全局目录不在 PATH	npm config get prefix 取路径，加进 PATH，重开终端
Error: Node.js version x is not supported	Node 版本低于 18	去官网下 LTS 覆盖安装
401 / Authentication failed	API Key 未设置或设置错误	新开终端，echo $DASHSCOPE_API_KEY 确认值存在且完整
模型名无效 / Model not found	模型 ID 拼写有误	复制官方文档里的完整模型 ID，不要手打
请求超时 / Connection timeout	网络问题，或境外端点访问受限	检查网络；若用境外端点考虑代理；国内端点一般不受影响
文件没改但终端说改了	Agent 在沙箱里生成了内容但未实际写入	检查权限设置，或在对话里明确说"写入文件"
commit 失败，提示没有 staged 内容	文件改了但没 git add	让它"先 add 所有改动再 commit"

---

常见问题

Q：Qwen Code 完全免费吗？

工具本身开源免费，但背后调用的模型 API 按 Token 计费。通义千问 Dashscope 有新用户免费额度，具体额度以阿里云官方说明为准（截稿 2026-06）。用本地模型（如 Ollama）则推理本身不另外计费。

Q：我能不能同时装 Claude Code 和 Qwen Code？

完全可以，两个工具互不干扰，命令名不一样（claude vs qwen）。很多人两个都装，按项目性质和预算决定用哪个。选型思路可以参考 如何按任务和预算调模型。

Q：Qwen Code 能用 GPT-4 或其他非 Qwen 模型吗？

只要接口兼容 OpenAI Chat Completions 格式，理论上可以。设置 OPENAI_BASE_URL 和对应的 Key，再指定模型名就行。具体支持情况以官方仓库最新 README 为准。

Q：用 Qwen Code 发给 Qwen 的数据会被存储吗？

调用通义 API 的隐私政策以阿里云官方说明为准。如果数据敏感，可以选择本地推理（Ollama + 开源模型），数据不出本机。

Q：Qwen Code 和直接问通义千问聊天界面有什么区别？

聊天界面是独立对话，不读你的文件，不执行命令，不改代码。Qwen Code 持续运行在你的项目里，能直接操作文件系统和 git，是真正的"在你机器上干活"。

---

这篇覆盖了 Qwen Code 从装好到跑通第一个任务的全流程，以及和 Claude Code 的关键差异。如果你还没看 Claude Code 的上手流程，建议对照着看 2.2 Claude Code 上手第一个项目——两篇放一起，选型判断会更清楚。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。