Qwen Code 终端 Agent：架构、安装与扩展机制

Qwen Code 的核心不是“在终端里聊天”，而是把模型推理、工具调用和项目执行放进同一个循环：模型读取需求后决定调用搜索、文件编辑、命令执行等工具，再根据工具结果继续推理，最终完成项目任务。因此，它与 Claude Code、Gemini CLI 属于相近的终端 Agent 产品层，和主要围绕当前文件提供补全的 IDE 工具并不相同；就现有资料而言，Qwen Code 更突出的项目主张是多协议、多模型及本地模型接入，而不是单纯生成一段代码。

GitHub 热点仓库 QwenLM/qwen-code 将它概括为“An open-source AI coding agent that lives in your terminal”。如果日常开发以终端、远程服务器和 Git 工作流为主，需要切换云端或本地模型，又希望审查 Agent 的执行过程，那么它值得进入工具评估清单；如果需求只是编辑器里的单文件补全，则这类 Agent 框架可能显得过重。

这次记录采用一条可复现的“安装—认证—修复任务—扩展接入”链路，而不是把功能清单直接当成实测结果。现有资料确认了 Node.js 版本要求、操作系统范围和主要配置方式，但没有提供某次本地终端的完整版本号与输出日志，因此本文不虚构一个看起来精确的 Qwen Code 版本号或测试耗时，而是明确区分“资料确认”“需要核验”和“验收标准”。正式记录时，运行环境至少应保存以下信息：

记录项	核验方式
操作系统	Windows 使用 ver，macOS/Linux 使用 uname -a
Node.js 版本	node -v
Qwen Code 版本	qwen --version
模型与服务商	记录 OPENAI_MODEL 及实际模型 ID
认证方式	标记 Qwen OAuth 或 API Key
项目状态	记录 git status --short 与测试退出码

主验收任务限定在一个函数 Bug：先让测试失败，再让 Agent 定位问题、修改一个源文件、运行测试并检查差异，最后用检查点和 Git 两种方式验证回滚。这样能同时观察项目读取、工具调用、修改范围和执行闭环，而不是只截取一段看起来流畅的回答。

它不是“会聊天的 CLI”：Qwen Code 怎么工作

从产品脉络看，Qwen Code 最初基于 Google Gemini CLI v0.8.2，从 v0.1 起停止同步上游，转向独立的多协议、多平台 Agent 框架发展。资料还将其概括为“框架与 Qwen 模型双开源、无厂商锁定”，这是项目方及转述文章提出的主张，不应被扩大理解为所有依赖、模型服务和扩展工具都天然没有锁定问题。

它与传统代码补全工具的差别主要在工作单元。IDE 补全通常围绕光标和当前文件提供候选，Qwen Code 则以完整工程为上下文，通过连续工具调用处理分析、修改、测试、审查和 Git 操作等任务；资料列举的应用范围还包括批量重构、漏洞检测、单元测试、工程文档和合并冲突处理。

用户需求
   ↓
Agent 会话与上下文管理
   ↓
模型推理
   ↓
工具调用：读取文件、搜索、编辑、执行命令……
   ↓
工具结果回填
   ↓
模型继续推理、调用下一项工具或结束任务

源码阅读不必从某个模型适配器开始。更有效的路线是顺着一次请求的完整生命周期，依次查看 CLI 入口、交互与会话层、模型及协议适配层、工具调用链、MCP 与子 Agent 接口，最后进入配置和权限层。具体目录名称应以 GitHub 当前版本为准，但逻辑上可以按下面几层理解：

逻辑层	主要职责
CLI 与交互层	接收命令、渲染交互、管理输入输出
Agent 循环层	协调用户输入、模型推理、工具执行和结果回填
模型适配层	对接 OpenAI、Anthropic、Gemini、Qwen 协议及本地服务
工具层	搜索、读取、编辑文件、运行测试和命令
扩展层	挂载 MCP、Skills、SubAgents、Hooks、LSP 等能力
配置与权限层	管理环境变量、项目设置、会话状态和执行确认

SubAgent 和 MCP 都参与 Agent 的任务执行。SubAgent 用于把复杂任务拆分给不同的执行角色，MCP 用于把外部数据源、API 和开发工具纳入工具集合；它们最终仍要回到 Agent 的推理—调用—反馈循环中。这也解释了为什么只比较聊天界面或模型回答质量，无法判断一个终端 Agent 是否真正适合工程开发。

执行模式方面，资料确认 Qwen Code 提供 Plan、Default、Auto-edit、YOLO 四种模式，但没有给出一张跨版本通用的权限对照表。实际使用可以按风险递增来分配：

模式	建议用途	本次测试中的约束
Plan	理解陌生项目、先讨论方案	只要求分析与修改计划
Default	普通缺陷修复	逐项检查文件修改和测试结果
Auto-edit	范围明确的重复性修改	先限定目录和文件类型
YOLO	批量、低风险、可丢弃环境中的任务	不接触生产凭据和重要分支

这里的划分是操作建议，不是对当前版本确认逻辑的硬性描述。不同版本可能调整自动执行范围，真实边界仍应以启动参数、权限提示和仓库中的当前配置说明为准。

资料转述的 SWE-bench Verified 77.8% 反映的是特定模型、提示、工具和评测条件下的结果。这类 benchmark 可以帮助判断项目上限，却不能替代本地验证：工程语言、依赖安装方式、测试质量、上下文长度、模型稳定性和权限策略，都会改变真实结果。评估 Qwen Code 时，更值得记录的是它在你的仓库里能否稳定定位问题、修改范围是否可控、失败后能否解释和恢复。

从零跑通：安装、认证与第一个项目任务

资料给出的环境边界是 Node.js 20 或以上；操作系统范围包括 Windows 10/11、macOS 10.15+、Ubuntu 20.04+ 和 Debian 10+。版本要求可能随发行版变化，正式安装前应以当前 npm 包和仓库声明为最终依据。

环境	资料列出的支持范围	建议的验证命令
Windows	Windows 10/11	node -v、npm -v
macOS	macOS 10.15 及以上	node -v、npm -v
Ubuntu	Ubuntu 20.04 及以上	node -v、npm -v
Debian	Debian 10 及以上	node -v、npm -v

普通使用者优先走 npm 全局安装，资料也将这种方式列为推荐路径：

node -v
npm -v
npm i -g @qwen-code/qwen-code
qwen --version

需要阅读、修改或跟踪源码时，再走仓库安装路径：

git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .
qwen --version

安装完成后如果出现“找不到 qwen”，首先排查 npm 全局可执行目录是否已经进入 PATH，而不是立即重复安装：

npm config get prefix

Windows 可以进一步检查：

where.exe qwen

macOS 和 Linux 可以检查：

command -v qwen

通常需要把 npm 全局可执行文件目录加入 PATH：Unix 环境常见位置是 <npm prefix>/bin，Windows 常见位置是 <npm prefix> 本身。权限错误、Node.js 版本过低和依赖安装失败是三类不同问题，不应混在一起处理。前者应调整 npm 目录所有权或 PATH，第二种需要升级运行时，第三种则应回到源码目录检查 npm 的具体报错。没有必要用全局提权掩盖目录权限设计问题。

首次启动执行：

qwen

资料记录了一种 OAuth 认证路径：选择 Qwen OAuth，使用通义千问账号扫码登录，并获得每日免费额度。这条路径适合先体验，但免费额度、入口位置和账户限制可能调整，应以实际账户页面为准。已经拥有模型服务密钥、需要固定模型版本或使用第三方兼容服务时，则选择 API Key 模式更便于复现。

教程中常见的三项环境变量是 OPENAI_API_KEY、OPENAI_BASE_URL 和 OPENAI_MODEL。阿里云百炼的国内兼容地址示例如下：

# 项目根目录 .env，或项目目录 .qwen/.env
OPENAI_API_KEY="你的-api-key"
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_MODEL="qwen3-coder-plus"

国际服务地址示例为：

OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"

这些变量名反映的是 OpenAI-compatible 接口的接入方式，不代表只能使用 OpenAI 模型。Qwen Code 资料列出的模型适配范围包括 OpenAI、Anthropic、Gemini、Qwen 四类协议，以及 Ollama、vLLM 等本地模型运行时切换。接入本地模型时，应同步核对模型 ID、上下文长度、工具调用格式、输出稳定性和资源占用，不能只确认接口能够返回文本。

Base URL 是最容易出现“能鉴权但请求失败”的地方。不同服务商的路径规则不能混用，例如参考教程明确要求其所使用的兼容地址带上 /v1，而另一类客户端可能采用不同的 Base URL 规则。配置时应优先查看所选服务商的文档，不要直接复制另一家教程的地址；同时注意模型名称必须与服务商实际暴露的模型 ID 完全一致。

建议将密钥文件排除在版本控制之外：

.env
.qwen/.env

检查点与会话限制则放在用户级 ~/.qwen/settings.json 或项目级 .qwen/settings.json 中。资料给出的配置示例如下：

{
  "checkpointing": {
    "enabled": true
  },
  "maxSessionTurns": 50
}

也可以通过启动参数启用检查点：

qwen --checkpointing

完成修改后，可以按当前版本提供的入口列出并恢复检查点：

/restore
/restore <checkpoint_name>

检查点适合撤销一次 Agent 操作链中的状态变化，但不能替代 Git。重要任务开始前仍应创建分支或提交，并用 git diff 检查实际改动：

git switch -c qwen-code/smoke-test
git status --short
git diff --check
git diff

主验收任务采用一个不依赖第三方测试框架的 Node.js 示例。sum.js 中故意保留一个忽略累加值的缺陷：

// sum.js
function sum(values) {
  return values.reduce((total, value) => total + 0, 0);
}

module.exports = { sum };

测试文件保持正确，不允许 Agent 为通过测试而修改断言：

// sum.test.js
const test = require('node:test');
const assert = require('node:assert/strict');
const { sum } = require('./sum');

test('sum adds values', () => {
  assert.equal(sum([1, 2, 3]), 6);
});

首次执行的验收标准是测试失败，核心差异应指向实际值 0 与期望值 6：

node --test

Expected values to be strictly equal:

0 !== 6

启动 Qwen Code 后，下一条任务应明确范围：

请分析 sum.js 和 sum.test.js，定位 sum([1, 2, 3]) 返回 0 的原因。
只允许修改 sum.js，不要修改测试文件，不要安装依赖。
修改后运行 node --test，并汇总修改文件、执行命令和测试结果。
不要执行 git commit、push、reset 或删除命令。

这个提示词同时约束了修改范围、禁止事项和验收步骤。正确修改应只触及 sum.js：

-  return values.reduce((total, value) => total + 0, 0);
+  return values.reduce((total, value) => total + value, 0);

再次运行测试后，验收基线为：

node --test

# Subtest: sum adds values
ok 1 - sum adds values
# pass 1
# fail 0

不同 Node.js 版本的 TAP 排版可能不同，判断依据是测试退出码为零、pass 1、fail 0，并且 git diff 中没有测试文件变化。正式测试记录还应保留 Agent 的工具调用摘要、完整测试输出和最终差异；预期输出只能作为验收标准，不能冒充未提供的现场日志。

常见问题可以按症状处理：

症状	优先检查
找不到 qwen	npm 全局目录、PATH、安装是否真正完成
提示 Node.js 版本不符	node -v 与当前包要求
鉴权失败	密钥是否过期、是否包含多余空格、认证方式是否匹配
模型不存在	OPENAI_MODEL 是否为服务商实际模型 ID
请求路径错误	OPENAI_BASE_URL 是否符合该服务的 /v1 等规则
Agent 修改后需要撤回	先看 /restore，再用 git diff 和 git restore 核对
非交互任务参数变化	通过 qwen --help 检查当前 headless 选项

资料也提到 headless 修复任务，以及远程开发场景，但不建议从第三方文章复制一个可能已经变化的命令行参数。更稳妥的做法是先用 qwen --help 确认当前版本暴露的非交互入口，再把任务提示、允许目录、输出格式和失败退出条件固定下来。

密钥方面，应使用最小权限凭据，不在对话、提交记录或截图中暴露完整值。删除、覆盖、部署、强制推送等命令应保留人工确认；即使启用自动编辑模式，也应先在临时仓库或隔离环境中验证。

能力怎么扩展：MCP、Skills 与子 Agent

资料列出的扩展体系包括 Auto-Memory、Auto-Skills、SubAgents、Agent Teams、MCP、Hooks、LSP，以及 /review、/batch、/loop、/bugfix 等内置 Skills[1]。这些名称很容易混淆，实际可以按“增加流程、拆分工、接入工具、增加约束、增强语义”五类理解：

能力	主要解决的问题	注意事项
内置 Skills	提供可复用的任务入口与执行步骤	适合审查、批处理、循环和缺陷修复等固定流程
Auto-Skills	按项目上下文自动发现或加载技能	具体发现规则以当前版本实现为准
SubAgents	将复杂任务拆分给专门角色	更适合边界明确、可独立交付的子任务
Agent Teams	组织多个 Agent 协作	需要关注任务重复、上下文成本和结果汇总
MCP	接入外部数据源、API 和开发工具	外部 Server 可能执行真实操作
Hooks	在执行生命周期中增加检查或约束	应优先用于阻断危险动作和记录审计信息
LSP	增强代码语义、跳转和诊断能力	与 MCP 的“接入工具”职责不同
模型适配层	在不同协议和本地模型之间切换	切换后需重新验证工具调用与上下文限制

Skill 与 SubAgent 主要按职责区分。Skill 更像一份可重复调用的操作规程，把步骤、检查项和输出格式固定下来；SubAgent 更适合承担一个边界清晰的子任务，例如分别检查安全风险和测试覆盖，再由主 Agent 汇总。使用 /review 可以观察前一种模式，使用 SubAgents 则要额外观察子任务是否越界、重复调用工具或遗漏最终验证。

MCP 解决的是另一个问题：Agent 本身已有的搜索、编辑和命令工具无法天然访问外部系统。MCP 把外部服务暴露为可发现、可调用的工具，适合接入文档库、Issue 系统、数据库或专有开发服务。下面是一个最小的文件读取示例，结构遵循常见 mcpServers 配置，但字段与包名仍应与当前仓库的 schema 核对：

{
  "mcpServers": {
    "fixture-reader": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/to/qwen-code-smoke/fixture"
      ],
      "timeout": 30000
    }
  }
}

这个 Server 指向的是一次性测试目录，而不是用户主目录或整个项目。文件类 MCP Server 往往同时具备读写能力，因此缩小根目录只是第一层限制，不能等同于只读授权。

验证过程可以分成五步。首先确认 Server 能否独立启动，其次检查 Qwen Code 是否发现工具，再核对工具名称与参数 schema，然后发起一次受控读取，最后处理超时和权限错误。不要一开始就要求 Agent 批量读取全部文件。

进入交互界面后，可以先执行不产生副作用的发现请求：

请只列出当前已发现的 MCP Server、tool 名称和参数 schema。
不要调用任何工具，不要读取文件。

确认工具列表后，再请求一个范围明确的调用：

请调用 fixture-reader 读取 fixture/notes.md，只返回前 20 行。
不要修改、创建或删除任何文件。

扩展测试至少应记录以下结果：

验收项	应记录的内容
Server 启动	命令、退出状态、错误输出
工具发现	Server 名称、tool 名称、参数 schema
真实调用	输入参数、返回结果、超时情况
失败重试	首次错误、修正方式、重试结果
权限提示	是否要求信任、确认或扩大目录范围
上下文开销	工具 schema 和返回结果占用的对话空间

内置 Skill 与 MCP 的作用不同：/review 改善的是“按什么步骤审查”，MCP 改善的是“能够审查什么数据”。前者失败时通常缺少上下文或任务规程，后者失败时则可能来自 Server 未启动、工具未发现、参数错误、超时或权限拒绝。扩展实际改变任务流程后，才算完成扩展验证，而不只是配置文件被成功解析。

Qwen Code 的模型层可以替换。切换模型时还需验证工具调用和上下文限制：同一个 MCP 工具在不同模型上的调用格式可能不同，长上下文中的参数稳定性也可能变化。建议每次切换后至少重跑一次“读取文件—修改文件—执行测试—检查 diff”链路。

终端之外，资料还提到 IDE 插件、Desktop、Daemon、SDK、IM 机器人以及 headless 修复任务等形态。这些更适合作为外围集成方向，而不是默认视为当前版本全部可用的稳定能力。实际采用前应检查对应仓库、文档和发布状态，尤其要验证身份认证、进程生命周期、远程访问范围及故障恢复。

使用扩展时，主要风险仍在执行权限上。MCP Server、外部脚本和 Hooks 都可能执行真实操作，合理的顺序是先使用只读权限、严格参数校验、命令白名单和隔离目录，再逐步开放写入能力；不可信的 Server 不应自动信任，密钥也不应通过扩展参数明文传递。我的判断是，Qwen Code 的使用门槛主要不在安装，而在模型接入、工具权限与可回滚机制能否形成完整闭环；提示词数量并不是关键。