QwenLM/qwen-code:3 万 star 的终端 AI 编程 Agent,Apache-2.0 全开源

QwenLM/qwen-code:3 万 star 的终端 AI 编程 Agent,Apache-2.0 全开源

一、先说个真实的场景

去年我接手一个烂摊子:一个跑了六年的单体服务,没有测试,没有文档,代码风格三种并存,接手的人换了一茬又一茬。

那天晚上我打开终端,准备手动翻目录结构。ls 出来 400 多个文件,grep 一个配置项要等好几秒。那一刻我特别想要一个东西:能读代码、能跑命令、能自己改文件改完还能自己看一眼 diff 的人。

同事指了指屏幕:” 你试试 Gemini CLI。”

后来 Gemini CLI 变成了我主力 coding agent。但用着用着总会碰到几件事让我不太舒服:

第一,它的默认模型链路跟 Google 强绑定,我给团队其他项目接 Anthropic 或者本地部署的模型,就得自己拿 API 拼。

第二,功能节奏。它每次发版都在动,而且动得很频繁 —— 我记不住哪个版本开始有了 Skills,哪个版本又开始支持 Plan Mode。

第三,扩展方式。它能接 MCP,但整个 harness 是黑盒的,你想改点核心行为就得去 fork。

后来 Qwen 团队 fork 了 Gemini CLI。有意思的是从 v0.1 开始,他们停止了和上游同步,走上独立开发。README 里写得很直白:

This project was originally based on Google Gemini CLI v0.8.2. Starting from Qwen Code v0.1, we stopped syncing with upstream and began independent development as a multi-protocol, multi-platform agent framework.

这句话的分量比看起来重得多。意味着它不是” 中文版 Gemini CLI”,而是一个独立框架了。

今天它长这样:GitHub 上 30731 stars、3555 forks,Apache-2.0,主语言 TypeScript,要求 Node.js 22 以上,2025 年 6 月 26 日创建,到 2026 年 11 月 17 日还在持续提交。

版本号目前是 0.28.0,仓库里同时躺着 v1.0.0-preview 和 v1.0.0-preview.1 两个 tag,nightly 构建也在跑(v0.27.4-nightly.20261116.xxx 这种形式)。

我花了两周时间把这套东西拆开看了一遍,想搞清楚三件事:它到底强在哪,哪些地方是过度设计,以及什么人才适合用它。


二、它是什么:一句话定义 + 关键数字

官方 README 的一句话定义是 “The open-source AI coding agent for your terminal, editor, desktop, browser, and chat.”—— 翻译成人话:一个跑在终端里的开源 AI 编程 Agent,同时提供编辑器插件、桌面应用、浏览器界面和 IM 聊天入口。

先把这堆数字摆出来:

指标 数值 来源
Stars 30731 GitHub API stargazers_count
Forks 3555 GitHub API forks_count
Open Issues 2435 GitHub API open_issues_count
License Apache-2.0 GitHub API license.spdx_id
主语言 TypeScript GitHub API language
Node 要求 >=22.0.0 package.json 的 engines
当前版本 0.28.0 package.json 的 version
创建时间 2025-06-26 GitHub API created_at
最近提交 2026-11-17 GitHub API pushed_at
仓库文件总数 16632 GitHub API 递归 tree
core 包工具数 118 packages/core/src/tools/ 下非测试 .ts 文件

package.json 里的 name 是 @qwen-code/qwen-code,type 是 module(纯 ESM),bin 指向 scripts/cli-entry.js—— 也就是说全局装完之后 qwen 这个命令就是入口。

有意思的是它的依赖关系。根 package.json 的 dependencies 只有三个:

1
2
3
4
5
{
"@testing-library/dom": "^10.4.1",
"ink": "7.0.3",
"simple-git": "^3.36.0"
}

对,就三个。ink 是 React 写的终端 UI 框架,simple-git 是 Git 操作的封装。其余全部塞进了 devDependencies(59 个)。

这个结构说明了一件事:它不是一个” 打包好卖” 的单体应用,而是一个 monorepo 仓库。你装的是发布出来的构建产物,但从源码角度看,所有东西都拆在 workspace 里。

它自己写的 topics 标签是 agentic, ai, ai-agent, ai-coding, cli, coding-agent, developer-tools, llm, mcp, qwen, terminal, typescript——agentic、mcp、coding-agent 这三个词,基本定义了它的定位。


三、monorepo 结构:20 个 package 是怎么切的

我用 GitHub 的递归 tree 接口把整个仓库拉下来数了一遍,一共 16632 个文件。packages/ 下面是这些:

1
2
3
4
5
6
7
8
packages/acp-bridge        packages/audio-capture     packages/browser-use
packages/channels packages/chrome-extension packages/cli
packages/core packages/cua-driver packages/desktop
packages/live-host packages/managed-agent-server
packages/mobile-mcp packages/mobile-shell packages/node-repl
packages/qwen-live packages/sdk-java packages/sdk-python
packages/sdk-typescript packages/vscode-ide-companion
packages/web-shell packages/web-templates packages/zed-extension

我挑几个关键的说。

packages/core —— 大脑。src/ 下面的结构大致是这样:

1
2
3
4
5
6
7
8
9
10
11
packages/core/src/
├── agents/ board.ts code-mode/ config/ confirmation-bus/
├── core/ # Agent Loop、Client、ContentGenerator,122 个条目
├── event-bus/ extension/ followup/ goals/ hooks/ ide/ ipc/
├── lsp/ # 语言服务器集成
├── managed-runtime/ mcp/ memory/ mods/ omni/ output/
├── permissions/ prompts/ providers/ qwen/ resources/
├── sandbox/ services/ # 169 个条目,服务层
├── skills/ subagent-runtime.ts subagents/ telemetry/
├── tools/ # 118 个工具
└── utils/

packages/cli —— 界面层。Ink 写的终端 UI,加上命令注册、non-interactive 模式、serve/daemon 子命令、i18n 等等。

packages/channels —— IM 通道,每个通道一个独立 package:aone、base、dingtalk、dws、email、feishu、github、gitlab、plugin-example、qqbot、telegram、wecom、weixin。

我数了一下,光 packages/cli/src/commands/ 下面就有 100 个命令实现文件。什么 /batch、/review、/board、/worktree、/channel、/daemon、/autofix-pr、/budget…… 我第一次点开这个目录的时候是有点震惊的。

packages/acp-bridge —— Agent Client Protocol 桥接。这个协议是让不同 coding agent 互相调用的标准,Claude Code、Codex 这些都能通过 ACP 接进来。

packages/sdk-typescript / sdk-python / sdk-java —— 三套 SDK。

pnpm workspace 的一个细节

它的 pnpm-workspace.yaml 里有一大段注释,写得非常有” 踩过坑” 的味道:

1
2
3
4
5
6
7
8
9
10
# Mirrors the workspaces list in package.json exactly; a new channel must be
# added to both files, the same as under npm. A glob here would let a
# channel join the pnpm layout silently while npm still ignores it.
packages:
- 'packages/*'
- 'packages/channels/aone'
# ...
- '!packages/desktop'
- '!packages/live-host'
- '!packages/mobile-shell'

注意最后三行是排除。packages/* 这个 glob 本来会把 desktop、live-host、mobile-shell 也吸进去,所以要显式 ! 掉。

下面还有一段更实在的:

1
2
3
4
5
6
# npm links every workspace package into the root node_modules; pnpm links
# one only where it is a declared dependency. The root package therefore
# declares, as file: devDependencies, the workspace packages that root-level
# code (integration-tests/, scripts/) imports, and .pnpmfile.mjs rewrites them
# to workspace:* like every other internal dependency.
nodeLinker: 'hoisted'

以及一段关于 patch-package 和 pnpm 硬链接冲突的解释 —— 默认情况下 pnpm 用硬链接,patch-package 改文件会破坏内容寻址存储的 sha512,导致后续所有 worktree 的 offline 安装挂掉。解法是把 packageImportMethod 设成 'clone-or-copy'。

还有内存问题的备注:

1
2
3
4
5
# packages/cli's `tsc --build` exhausts V8's default heap when a build runs
# through pnpm ... `npm run build` observed the same growth past 4 GB
# (#14823), so package scripts get headroom here rather than on the one
# entry point that happened to fail first.
nodeOptions: '--max-old-space-size=6144'

这段直接引用了 issue #14823。一个项目愿意在配置文件里把踩坑过程写成注释,说明维护者是认真在维护的。

顺带一提,overrides 段落长得吓人,把 glob、minimatch、qs、react、axios、typescript 全锁了版本,甚至锁了 brace-expansion 的 patch 版本(1.1.21 和 2.1.7—— 这俩是安全补丁)。


四、核心机制之一:Agent Loop 到底怎么转的

所有 coding agent 的骨架其实都一样:一个 while 循环,把对话 + 工具列表发给模型,模型返回 tool call,执行工具,把结果塞回对话,继续转。

Qwen Code 的核心实现在 packages/core/src/core/agent-loop.ts,配套的还有 coreToolScheduler.ts(工具调度)和 client.ts(会话管理)。我没法在这里贴完整源码,但可以从工具注册表 packages/core/src/tools/tools.ts 和 tool-registry.ts 看出它的设计。

工具是有分级的

118 个工具里,明显能分成几类:

1
2
3
4
5
6
7
8
9
10
文件类    read-file.ts  write-file.ts  edit.ts  notebook-edit.ts
readManyFiles.ts glob.ts glob-search.ts grep.ts ripGrep.ts ls.ts
执行类 exec.ts shell.ts execution-tool.ts
编排类 agent.ts fork-subagent.ts fork-profile.ts create-sub-session.ts
list-agents.ts send-message.ts task-create/list/update/stop.ts
team-create.ts team-delete.ts team-plan-approval.ts
记忆类 manage-memory.ts search-memory.ts memory-config.ts transcript-marker.ts
审核类 autofix-pr.ts autofix-pr-grants.ts report-findings.ts workflow.ts batch-task.ts
多模态 display-image.ts zoom-image.ts image-gen.ts html.ts artifact-tool.ts
外部能力 web-fetch.ts web-search.ts lsp.ts code-mode.ts tool-search.ts

两个细节值得说:

read-file.ts 和 edit.ts 是分开的 —— 读和写是两个独立工具,只读的那个可以被单独授权。

mcp-pool-* 这一串 说明它不是每次调用都新建 MCP 连接,而是有连接池、有 key、有事件、有重试:

1
2
3
4
mcp-client.ts  mcp-client-manager.ts  mcp-tool.ts
mcp-pool-entry.ts mcp-pool-events.ts mcp-pool-key.ts mcp-transport-pool.ts
mcp-retry.ts mcp-status.ts mcp-workspace-budget.ts
mcp-discovery-timeout.ts mcp-app-resource-limits.ts mcp-errors.ts

做过 MCP 集成的人都知道这有多重要 ——MCP server 冷启动慢,不池化的话每次工具调用都等三秒。

tool-search.ts 的存在说明它用了” 工具检索” 模式:工具太多的时候不一次性全塞给模型,而是先让模型搜目录再挑。118 个工具全塞进 context 是个灾难,这个设计是必要的。

多模态

1
2
3
4
5
6
display-image.ts
zoom-image.ts
image-gen.ts
html.ts
artifact-tool.ts
record-artifact.ts

外部能力

1
2
3
4
5
6
7
8
9
web-fetch.ts
web-fetch-preapproved.ts
web-search.ts
web-search-backend.ts
web-search-dashscope.ts
web-search-subscription.ts
lsp.ts
code-mode.ts
tool-search.ts

tool-search.ts 这个工具存在,说明它用了” 工具检索” 模式 —— 工具太多的时候不一次性全塞给模型,而是先让模型搜目录再挑。这个设计我认为是必要的,118 个工具全塞进 context 是个灾难。

Plan Mode 和审批模式

packages/core/src/config/approval-mode.ts 加一个 approval-modes.json,定义了四档:Plan Mode(只读地规划,不碰文件)、每次调用确认、自动编辑、Auto Mode(分类器驱动 classifier-driven)、以及 YOLO(全放开)。

classifier-driven 这个词值得注意:它意味着判断” 这个操作危不危险” 不是简单的路径白名单,而是有个分类器在看。配合 permissions/ 目录和 confirmation-bus/,整个审批链路是可审计的。

Sandbox 和 worktree

packages/core/src/sandbox/ 和 packages/core/src/tools/enter-worktree.ts / exit-worktree.ts 是两个独立的保护机制:

  • Sandbox —— 限制工具执行环境,仓库里有 Dockerfile,package.json 里有 test:integration:sandbox:docker 和 test:integration:sandbox:podman 两套集成测试
  • Worktree —— 隔离大范围编辑,用 Git worktree 开一个临时分支,改坏了直接扔

这两个配合起来是它的 Agent Arena / Agent Teams 能安全跑的基础。


五、核心机制之二:多 Agent 编排的三种模式

Qwen Code 的多 Agent 能力分三个层次,逐级递进。

1. SubAgents —— 最基础

README 里的描述:

delegate focused subtasks to specialized agents with their own context and toolsets, in the foreground or background.

关键是 “their own context and toolsets”。每个子 Agent 有独立的 context 和独立的工具集,主 Agent 通过委派来控制自己的上下文膨胀。

对应代码是 packages/core/src/subagents/ 和 subagent-runtime.ts。

我比较喜欢这个设计的原因:它不是把整个任务丢给一群 Agent 互相对话(那种做法 token 消耗是指数级的),而是保持了明确的层级关系。

2. Agent Teams —— 有共享状态

README:

a leader coordinates teammates that share a task list and exchange messages, with read-only investigators and an optional single worktree writer.

三个关键词:

  • leader —— 有个明确 leader,不是完全自治的对等网络
  • shared task list —— 共享任务列表,对应 task-create.ts / task-list.ts / task-update.ts
  • read-only investigators + optional single worktree writer —— 调查者只读,写入者最多一个

这个” 只允许一个写者” 的设计我认为是关键的。多个 Agent 同时改同一个文件,合并冲突是必然的。与其事后解决冲突,不如在架构上禁止。代码里对应 team-plan-approval.ts—— 写入前需要 plan 审批。

这个功能标记为 experimental。

3. Agent Arena —— 多模型竞速

README:

run the same task on multiple models in isolated Git worktrees, compare solutions side by side, and merge the winner.

这是我觉得最有意思的一个:同一个任务,扔给多个模型,每个模型在自己的 Git worktree 里独立干,然后并排对比,最后合并赢的那个。 “isolated Git worktrees” 保证互不干扰,”merge the winner” 保证有确定产出。

这实际上把” 多模型评测” 这件事从实验室拉进了日常工作流。你可以让 Qwen 3.7 Max、Claude Opus、Gemini 同时解一个 bug,然后挑最好的。同样标记为 experimental。

Dynamic Workflows —— 让模型写编排逻辑

README 的措辞是 “the model writes JavaScript workflows that orchestrate agents: parallel fan-out, verification passes, and resumable runs.”

注意:模型写 JavaScript 工作流。不是配置 DSL,是真的代码。好处是表达力无限(能写循环、能条件判断、能调 API),坏处是安全风险 —— 模型写的代码要能执行。所以它默认是 opt-in 的。


六、核心机制之三:Auto-Memory、Skills 和 QWEN.md

这是我觉得 Qwen Code 相比” 裸 Agent” 最有产品感的部分。

Auto-Memory

README 的措辞是 “the agent writes its own notes and recalls them across sessions; your QWEN.md and AGENTS.md briefings load automatically.”

关键词是 the agent writes its own notes。不是我手动维护一个记忆文件,是 Agent 自己写、自己召回。对应代码 packages/core/src/memory/ 和 packages/core/src/tools/manage-memory.ts / search-memory.ts。

Skills

内置 skills 有 /review、/batch、/bugfix 等,另外还有几个动态能力:

  • /learn —— 把文档或代码蒸馏成新 skill
  • Agent 自己生成 skill(opt-in)
  • /curator —— 维护 skill 库

packages/core/src/skills/ 是实现目录,.qwen/skills/ 是默认 skill 的存放位置(从 tree 里能看到 .qwen 这个顶层目录)。

packages/core/src/tools/skill.ts 和 skill-utils.ts 是运行时的支撑。

项目级约定文件

它会自动加载 QWEN.md 和 AGENTS.md。QWEN.md 是它自己生态的约定文件(相当于 CLAUDE.md),AGENTS.md 是现在越来越多工具通用的约定格式。

我注意到仓库根目录里同时躺着 AGENTS.md、CLAUDE.md、CONTRIBUTING.md、SECURITY.md—— 这个项目自己的开发也用 Agent 来做,README 里明确说了:

Qwen Code is actively iterating on itself — using its own agent and models to file issues, submit PRs, review code, and run tests.

而且仓库里有一个 .qwen/skills/qwen-code-claw/SKILL.md—— 让别的 Agent(Claude、Codex)通过 ACP 把任务委派给 Qwen Code。

packages/core/src/config/rulesDiscovery.ts 负责这套约定的发现逻辑。


七、快速上手:真实命令

以下命令全部来自 README 和 docs/users/qwen-serve.md。

安装

Linux /macOS 独立安装脚本:

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

Windows:

1
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

NPM(需要 Node.js 22+):

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

Homebrew(macOS / Linux):

1
brew install qwen-code

装完要重开终端,环境变量才生效。

跑起来

1
2
cd /path/to/your-project
qwen

进去之后执行 /auth,选 Qwen Account with Subscription 用 Plus/Pro 订阅登录,或者配一个自己的 provider API key。

然后可以直接说:

1
Explain this repository and show me where to start.

各入口怎么开

入口 命令 / 方式
终端 qwen
桌面端 下载 desktop-latest release(macOS/Windows/Linux)
浏览器 qwen serve --open(experimental)
VS Code / Zed / JetBrains 装对应插件
IM 通道 qwen channel start(Telegram / 钉钉 / 微信 / 企微 / 飞书 / QQ / 邮件 / GitHub)
无头模式 qwen -p "..."
SDK TypeScript / Python / Java
Daemon qwen serve

Daemon 模式

这个特性我单独用了一节讲,因为它是这套架构里比较独特的一块。

1
qwen serve --open

默认监听 http://127.0.0.1:4170,自带一个 Web Shell。

后台管理:

1
2
3
4
qwen daemon start
qwen daemon status
qwen daemon logs -f
qwen daemon stop

daemon 提供的核心价值是:浏览器、编辑器、SDK、自动化脚本可以共享同一个 agent session,不用每个客户端各起一个进程。

从 docs/users/qwen-serve.md 里能看到的能力:

  • SSE + Last-Event-ID 重连 —— 客户端掉线可以从断点续上(在 replay window 内)
  • 分页持久化 transcript —— GET /session/:id/transcript
  • 先到先得的权限审批 —— 多个客户端都看到审批请求,谁先答谁赢
  • 多工作区 —— 重复 --workspace 注册隔离的 runtime
  • 运行时控制 —— 改审批模式、开关工具、重启 MCP server、动态增删 MCP server,都不用重启 daemon

比如运行时控制的 API:POST /session/:id/approval-mode、POST /workspace/tools/:name/enable、POST /workspace/skills/:name/enable、POST /workspace/mcp/:server/restart、POST /workspace/mcp/servers、DELETE /workspace/mcp/servers/:name、POST /session/:id/recap。

最后一个 /recap 我觉得很实用 —— 一句话总结” 我上次做到哪了”,实现方式是跑一次独立的 side-query,用快模型,不污染主对话历史也不影响 SSE 流。

Python SDK 示例

README 里的官方示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import asyncio
from qwen_code_sdk import is_sdk_result_message, query


async def main() -> None:
result = query(
"Summarize the repository layout.",
{"cwd": "/path/to/project", "path_to_qwen_executable": "qwen"},
)
async for message in result:
if is_sdk_result_message(message):
print(message["result"])


asyncio.run(main())

三个 SDK 是独立发版的 —— 我查 release 列表的时候看到了 sdk-typescript-v0.1.35,和主版本 v0.28.0 的版本号是完全脱钩的。

Docker

仓库根目录有 Dockerfile。package.json 里有一堆容器相关的集成测试:

1
2
3
4
test:integration:sandbox:none
test:integration:sandbox:docker
test:integration:sandbox:podman
test:integration:hosted:sandbox:none

Makefile

仓库根有 Makefile,配合 package.json 里的 scripts 字段。

scripts 我数了一下有 130 多个条目,其中大量是 E2E 故障切换测试,名字长得很具体:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
test:e2e:managed-session-failover         test:e2e:managed-inflight-failover
test:e2e:managed-continuation-failover test:e2e:managed-big-output
test:e2e:managed-loop-skill test:e2e:managed-loop-fire
test:e2e:managed-harness-restart-failover
test:e2e:managed-harness-restart-inflight-failover
test:e2e:managed-harness-restart-continuation-failover
test:e2e:managed-continuation-frozen-owner-failover
test:e2e:managed-harness-restart-approval-allow / -deny / -cancel / -expiry
test:e2e:managed-harness-restart-approval-after-decision / -prepare / -result
test:e2e:managed-harness-restart-approval-finished-before-commit
test:e2e:managed-harness-restart-approval-sibling-approval
test:e2e:managed-harness-restart-approval-command-rewrite
test:e2e:managed-harness-restart-approval-after-earlier-tools
test:e2e:managed-harness-restart-approval-cleanup-failed
test:e2e:managed-harness-restart-approval-decision-reply-lost
test:e2e:managed-harness-restart-approval-admission-reply-lost
test:e2e:managed-harness-restart-approval-load-reply-lost
test:e2e:managed-harness-restart-approval-terminal-write-failed
test:e2e:managed-harness-restart-approval-terminal-closeout
test:e2e:managed-harness-restart-model-round-failover
test:e2e:managed-frozen-control-plane-failover

这一长串名字透露出一个信息:managed agent 的难点不是功能,而是故障恢复。

会话中断了怎么办?审批请求发出去了但回复丢了怎么办?harness 重启了但还有 inflight 的调用怎么办?模型一轮对话失败怎么 failover?

这些问题在成熟的 agent 系统里都会遇到。看名字猜,这个 daemon + managed-agent-server 的组合是被真实生产场景锤过的。

另外还有 test:terminal-bench、test:terminal-bench:oracle、test:terminal-bench:qwen—— 它接入了 Terminal-Bench 这个终端能力评测。


八、模型支持:多协议是它和 Gemini CLI 分家之后的正经理由

README 里:

Multi-protocol — Supports OpenAI, Anthropic, Gemini, and Qwen APIs. Any third-party provider or local model (Ollama / vLLM). Switch at runtime.

packages/core/src/providers/ 是实现目录,packages/core/src/core/contentGenerator.ts 是核心抽象。

值得注意的是,代码里保留了 Gemini CLI 的历史遗产 ——baseLlmClient.ts、GeminiChat、GeminiClient 这些命名还在(README 里也提到 “based on Google Gemini CLI v0.8.2”)。所以你能看出这个 fork 的起点在哪。

packages/core/src/core/ 下面还专门有 anthropic-reasoning.ts、anthropicContentGenerator/、deepseek-reasoning.ts、dashscope-source-config.ts。

DeepSeek 和 Anthropic 的 reasoning 支持是单独写的适配层 —— 说明这些不是简单换个 URL,而是要处理不同的 thinking/reasoning 参数格式。packages/core/src/core/contentGenerator.ts 存在专门的测试文件,说明多 provider 兼容是回归测试的重点区域。packages/core/src/config/models.ts 和 generate:model-catalog 脚本对应模型目录生成。


九、扩展机制:Hooks、MCP、LSP、Computer Use

Hooks

README:

run your own scripts at lifecycle events: before and after tool calls, session start and end, and more.

代码在 packages/core/src/hooks/ 和 packages/cli/src/hooks/。

工具调用前后都能挂自己的脚本 —— 这在” 跑测试前先跑 lint” 这类需求里特别有用。

MCP

packages/core/src/mcp/ 目录是我在这个仓库里看得最认真的部分之一,16 个文件覆盖了连接池、重试、资源限制、状态查询等:

1
2
3
4
5
mcp-client.ts  mcp-client-manager.ts  mcp-tool.ts
mcp-pool-entry.ts mcp-pool-events.ts mcp-pool-key.ts mcp-transport-pool.ts
mcp-retry.ts mcp-status.ts mcp-workspace-budget.ts mcp-discovery-timeout.ts
mcp-app-resource-limits.ts mcp-resource-content.ts mcp-session-config.ts
mcp-classifier-input.ts mcp-errors.ts

mcp-workspace-budget.ts 这个名字很有意思 —— 给每个工作区限制 MCP 资源占用。MCP server 可以是任意外部进程,不加预算的话一个坏掉的 server 能把你的机器拖垮。

mcp-discovery-timeout.ts —— 发现的超时。启动时扫所有 server 太慢会卡住。

LSP 集成

标记为 experimental + opt-in。支持 go-to-definition、references、diagnostics、code actions。

对应 packages/core/src/lsp/ 和 packages/core/src/tools/lsp.ts。

我一开始觉得这是个可有可无的功能,用了之后发现不是 ——Agent 改代码时,如果能拿到精确的引用信息,比让它 grep 整个仓库靠谱得多。grepReadTracking.ts 和 priorReadEnforcement.ts 这两个文件名暗示了一套” 先读后改” 的追踪机制,大概是在保证 Agent 改的是它真的看过的文件。

Computer Use / Browser Use

对应 packages/cua-driver/(CUDA 缩写 Computer Use driver)和 packages/browser-use/。

packages/browser-use/ 是独立的 package。浏览器自动化不是简单开个 headless Chrome 那么简单,涉及截图、DOM 树、坐标定位等等。

packages/node-repl/ 提供 Node REPL + SDK 的方式,让 Agent 可以在会话里直接执行 Node 代码并拿到结果。

Code Mode

packages/core/src/code-mode/ 和 packages/core/src/tools/code-mode.ts。

这个模式是:不给模型一堆细粒度工具,而是给一个” 写代码来调用工具” 的接口。类似 Anthropic 那套 Code Execution 思路。好处是 token 省,坏处是调试链路变长一层。

权限相关的细节

packages/core/src/tools/file-read-permission.ts —— 文件读取权限。

这个我得专门提一句,因为读文件和写文件不是一回事。很多 coding agent 的” 读” 是无限的(能读 .env、能读 SSH 私钥),写才有确认。这个设计把读也纳入了管控。

packages/core/src/tools/tool-output-size.ts、truncation.ts、tool-result-retention.ts、tool-result-boundary-diagnostics.ts —— 一整套工具输出管理。

大模型上下文有限,一个 grep 结果可能几万行。怎么截断、截断的时候保什么、诊断信息怎么传给模型,这是实际工程里最琐碎也最关键的部分。这几个文件说明它认真处理过。


十、SWE-bench Verified 上的成绩

README 有一张图和一段数字。实际数字在 docs/evaluation.md 里,我直接抄表:

Version Avg Score Pass Rate pass@3 pass^3
0.0.14 77.80% 84.6% 84.6% 69.2%
0.1.0 76.73% 84.6% 84.6% 68.0%
0.5.0 76.60% 83.0% 83.0% 68.4%
0.10.0 76.47% 84.4% 84.4% 67.4%
0.15.0 77.67% 84.6% 84.6% 68.6%
0.19.0 76.40% 85.0% 85.0% 65.8%
0.22.0 77.33% 84.4% 84.4% 68.0%

评测配置(docs/evaluation.md 里的表格):

配置项 值
数据集 princeton-nlp/SWE-bench_Verified,500 cases
试验次数 每版本 3 次,每版本 1500 jobs,共 7 个版本
模型 Qwen 3.7 Max
采样 temperature=1, top_p=0.95
思考 / 推理 interleaved_thinking=true, thinking_type=adaptive, reasoning_effort=high
上下文 / 输出限制 context_1m=true, model_context_length=1,000,000, max_tokens=64,000, model_max_tokens=65,535
Harness 限制 max_iterations=500, runtime_timeout_sec=7,200, agent_timeout_multiplier=3.0

我得说几句实话。

这组数字最值得注意的是它的稳定性,而不是它的绝对值。 七个版本从 0.0.14 一直到 0.22.0,平均分在 76.40% 到 77.80% 之间,跨度只有 1.40 个百分点。这说明 harness 的架构是稳的 —— 从一个只支持 Gemini 的 fork,到多协议、多平台、多 Agent 编排、118 个工具,它的核心 agent loop 没有崩。

但也要看清楚这个评测的边界:

  1. 全程用 Qwen 3.7 Max。 这测的是”Qwen Code 这套 harness 配 Qwen 自家模型的水平”,不是”Qwen Code 比别家 harness 强多少”。要横向比,得让 Claude Code 也用同一个模型跑一遍。

  2. max_iterations=500 和 runtime_timeout_sec=7200(两小时)非常宽松。 这是评测配置,不是产品默认。真实项目里你不会让 Agent 转 500 轮。

  3. 数据集会过拟合。 SWE-bench Verified 已经被刷了无数遍,模型对它太熟了。

  4. reasoning_effort=high + 100 万上下文 + 64k 输出。 这个配置对应的 token 成本相当高,别拿这个分数去推算” 用一次要多少钱”。

  5. 有意思的是 pass^3 在 65.8% 到 69.2% 之间。这是三次全对才算对的指标,比 pass@3 低了将近 15 个点 —— 说明同一个模型同一个框架,三次跑的结果方差不小。实际使用的启示是:别指望 Agent 每次都给出同样的解法。


十一、跟同类项目比:它到底站在哪

既然它出身 Gemini CLI,那就绕不开这几个人。

vs Gemini CLI

Qwen Code 的优势:

  • 多协议。 Gemini CLI 深度绑定 Google。Qwen Code 原生支持 OpenAI、Anthropic、Gemini、Qwen 四家协议,加上任意第三方 provider 和本地 Ollama /vLLM。
  • 架构独立性。 v0.1 之后不再跟上游同步,可以按自己的节奏和需求演进。这是双刃剑,下面细说。
  • 更细的多 Agent 能力。 SubAgents / Agent Teams / Agent Arena 三层,加上模型可写的 Dynamic Workflows。
  • 更多入口。 daemon 模式、11 个 IM 通道、桌面端、三套 SDK。
  • Qwen 模型深度适配。 100 万上下文、interleaved_thinking、adaptive reasoning 这些。

Gemini CLI 的优势:

  • 上游背书。 Google 的模型、基础设施、发布节奏是连贯的。
  • 生态成熟度。 官方文档、示例、社区讨论量。
  • 不用自己踩坑。 Qwen Code 从 0.x 走到 0.28,很多路是它自己蹚出来的。

vs Claude Code

Qwen Code 优势:

  • 完全开源 + Apache-2.0。 Claude Code 是闭源商业产品。你没法读它的实现、没法自己改、没法自托管审计。
  • 免费且不限量(用你自己的 provider)。 你自己买 API key,成本就只是 token。
  • 模型自由。 Claude Code 现在也支持第三方模型了,但它自己的 harness 依然是为 Claude 优化的。
  • 可自托管。 daemon 模式可以完全跑在内网。
  • Qwen 模型上的性价比。 如果本来就用通义千问,成本低一截。

Claude Code 优势:

  • 能力上限。 说实话,在复杂重构、长程任务上,Claude Code 的完成度目前还是更高。
  • 稳定性。 Anthropic 的产品化程度更高。
  • 生态与集成。 各种第三方工具默认优先适配 Claude Code。
  • 不用自己折腾。 Qwen Code 有 2435 个 open issue。

vs OpenCode

OpenCode 是另一款开源终端 coding agent,走的是” 极简 + 多 provider” 路线。Qwen Code 的重心明显在功能完备度上 ——118 个工具、20 个 package、100 个命令、11 个 IM 通道。OpenCode 更轻。

vs Cursor / Windsurf / Devin

Cursor、Windsurf 是 GUI 路线,不是同一个物种。Qwen Code 的 IDE 插件(VS Code / Zed / JetBrains)能部分覆盖这个场景,但底座还是终端。Devin 那种是云端托管的商业产品,卖的是” 结果” 不是” 工具”。Qwen Code 卖的是 harness,你自己掌控一切。

一句话总结对比

Qwen Code Gemini CLI Claude Code OpenCode
开源 ✅ Apache-2.0 ✅ 开源 ❌ 闭源 ✅ 开源
多 provider ✅ 四协议 + 本地 ❌ 偏 Google ⚠️ 有限 ✅
IM 通道 ✅ 11 个 ⚠️ 少 ⚠️ 少 ❌
多 Agent ✅ 三层 ⚠️ 有但较简 ⚠️ 有 ⚠️
SDK ✅ TS/Python/Java ⚠️ ⚠️ ⚠️
成熟度 中(0.28) 高 高 中

十二、真实局限:说点不好听的

我用了两周,有些地方必须吐槽。

1. 2435 个 open issue

这个数字对 30731 star 的项目来说不低。README 里也承认项目在”actively iterating on itself”—— 用 AI 批量提 issue 和 PR 是双刃剑,它能加速迭代,也能制造噪音。

2. 实验性功能太多了

我数了一下 README 里标 experimental 或 opt-in 的功能:Agent Teams、Agent Arena、Dynamic Workflows、qwen serve --open(Web UI)、daemon 模式整体、LSP 集成、Qwen Live(实时语音)。

接近一半的” 高级能力” 是实验性的。 这意味着你不能指望它们稳定,也不能指望文档准确。Agent Arena 我特别想用,但 experimental 标签就意味着接口随时会变。

3. Daemon 默认不安全 —— 这个必须点名

README 自己写了:

By default, the daemon listens on loopback without bearer authentication; any local process that can reach it can use the full API, including code execution.

翻译:默认情况下,daemon 不带认证,任何能连上它的本地进程都能用它完整 API,包括执行代码。 docs/users/qwen-serve.md 里的表述更狠 ——“Loopback is trusted by default”,任何能连上它的本地进程都拿到完整 API 权限,包括以 daemon 用户身份执行代码。

它给的缓解方案是设 QWEN_SERVER_TOKEN 加 --require-auth。非 loopback 监听会自动生成一个 128 位临时 bearer(22 个 URL-safe 字符)并在启动时打印一次。

另外还有 DNS rebinding 防护:loopback 绑定的 Host 头白名单只接受 daemon 自己的端口,所以 ssh -L 8080:localhost:4170 这种端口转换隧道会直接被 403 Invalid Host header 拒掉。

我觉得这个默认值可以理解(本地开发体验优先),但在共享机器上必须显式开认证。文档里那句”on shared or untrusted hosts, set QWEN_SERVER_TOKEN and use --require-auth“是认真的,不是客套。

/recap 端点还有一个自曝的坑,文档里原话:

Known limit — token-cost amplification: the route is a pure-cost endpoint (each call is an LLM side-query, no state benefit) and the daemon has no per-route rate limit in v1. On a no-token loopback default a buggy or malicious local client can spam it to burn tokens.

自己主动写” 这是个烧 token 的漏洞”,说明维护者靠谱,但问题确实存在。

4. 资源消耗不轻

118 个工具 + MCP 连接池 + 1M 上下文配置 + TypeScript monorepo 二十个包,本地跑起来的内存和 CPU 都不低。nodeOptions: '--max-old-space-size=6144' 这行配置就是证据 —— 构建过程需要 6GB 堆。评测配置里 max_iterations=500、runtime_timeout_sec=7200 也说明单次任务的资源上限很高。

5. 文档是英文优先

有 8 个语言版本:English、中文、Deutsch、français、日本語、Русский、português、한국어。但很多细节文档(比如 1392 行的 daemon 指南)我只看到英文版。中文用户能拿到 overview,但深入细节可能要读英文。

6. 依赖重

虽然根 dependencies 只有 3 个,但 devDependencies 有 59 个,overrides 锁了一长串安全补丁版本。想从源码跑起来的同学要准备好处理 pnpm 依赖树。

7. 版本号还在 0.x

0.28.0。同时 v1.0.0-preview 已经存在 —— 主线还在 0.x,1.0 在预览阶段。README 里专门有一段解释这个分裂:

Looking for Qwen Code 1.0 Preview? Get started here. The instructions below are for the main version.

1.0 Preview 是个独立的分支,把 Qoder 的 agent harness 能力和 Qwen Code 合并了。这意味着你装 npm install -g @qwen-code/qwen-code@latest 拿到的不是 1.0。这个信息藏得不算深,但对新手来说很容易装错。


十三、适合谁 / 不适合谁

适合

1. 想要完全开源、可审计、可自托管的团队 —— 这是最核心的价值。Apache-2.0,全代码可读,daemon 能跑在内网。金融、政企、涉密项目,这是硬门槛。

2. 需要多 provider 自由度的开发者 —— 公司买了 Claude API,但某些场景必须用国内模型;或者本地有 GPU 部署了 vLLM。Qwen Code 的多协议切换是原生的。

3. 想把 Agent 接进 IM 的团队 —— 11 个通道:Telegram、钉钉、微信、企微、飞书、QQ、邮件、GitHub、GitLab、DWS、Aone。对很多团队来说,” 在钉钉里 @ 机器人改个 bug” 比” 打开 IDE” 更自然。

4. 想做二次开发、做自己 Agent 产品的团队 —— 118 个工具的实现、20 个 package 的拆分、三套 SDK、ACP 协议支持,这是一堆现成的零件。

5. 中文用户 —— Qwen 模型本身的中文能力、8 语言文档、中文社区,都是加分项。

6. 喜欢折腾 harness 本身的人 —— Skills、Hooks、Dynamic Workflows、Agent Arena…… 如果你想深入理解 agent 编排怎么设计,这是很好的教材级代码库。

不适合

1. 只想” 有个能用的工具” 的普通用户

装是简单,但配置 provider、写 QWEN.md、理解 approval mode、理解 worktree…… 这些都有学习成本。不如用 Claude Code 或者 Cursor。

2. 追求稳定交付的生产团队(现在)

一半功能 experimental,2435 个 open issue,0.x 版本。做生产工具链的应该等 1.0 正式版。

3. 不愿意自己管 token 成本的人

多 Agent(尤其是 Agent Arena 同时跑多个模型)开销可以非常夸张。/recap 那种” 纯消耗无收益” 的端点它自己都写进文档了。

4. 团队协作场景下需要严格权限管控的人

默认 loopback 无认证、write 模式宽松。要严格管控得自己配 token、白名单、Sandbox,逐项做。

5. 只想写代码不想管工具链的人

如果你不享受调配置、研究 prompt、比较不同模型的输出风格,这套东西对你是负担。


十四、我的实际使用建议

如果你决定试,我建议这么开始:

第一周:只当普通 CLI 用

1
2
3
npm install -g @qwen-code/qwen-code@latest
cd your-project
qwen

先用 /auth 登录或者配好一个 provider。这一步什么都别开。 不要开 YOLO,不要开 Auto Mode,不要开 Agent Teams。先熟悉它的基本行为:它会读哪些文件、会跑什么命令、什么时候停下来问你。

第二周:写 QWEN.md

在项目根目录建 QWEN.md,写清楚项目结构、构建命令、测试命令、代码风格约定。这是投入产出比最高的一步 —— 我试过,写了 QWEN.md 之后 Agent 的行为质量有明显提升,因为它不再需要每次重新摸索” 这个项目怎么跑测试”。

第三周:开 Hooks

把 lint /typecheck 挂到工具调用前后。让 Agent 每次改完代码自动跑一遍检查,这个自动化对减少来回验证很有用。

第四周:试 SubAgents

先不要碰 Agent Teams 和 Agent Arena。SubAgents 是最可控的:给一个明确的小任务(比如” 把这个目录下的测试补全”),让它委派出去。

之后:按需开实验性功能

Agent Arena 我认为是这套东西里最值得投入的方向,但先等它接口稳定。

一定要配的东西

如果你要在共享机器上跑 daemon:

1
2
export QWEN_SERVER_TOKEN="$(openssl rand -base64 32)"
qwen serve --require-auth --hostname 0.0.0.0

非 loopback 监听时记得配 TLS—— 文档里明确说 “HTTP is unencrypted”。


十五、一些值得单独记下的细节

15.1 ACP 正在成为事实标准

搜索候选的时候我注意到 openclaw/openclaw 有 82908 stars,README 里写着 “The AI that really does things. Any OS. Any Platform. The lobster way. 🦞”—— 它比 qwen-code 还火。

不过 Qwen Code 的 README 里也提到了生态合作:”🦞 Qwen Code Claw — Let other agents (Claude, Codex, etc.) delegate coding tasks to Qwen Code via ACP.”

所以两个项目是在互相接壤的。ACP(Agent Client Protocol)正在成为一个事实标准 ——Claude Code、Codex、Qwen Code 都往这边靠。

15.2 生态周边

README 列了几个:Qwen Code Desktop(官方桌面应用,macOS/Windows/Linux)、AionUi(iOfficeAI 出的 CLI 工具 GUI 壳)、Gemini CLI Desktop(跨平台的桌面 / 网页 / 移动端 UI)、qwen-audio-agent(基于 ACP 的实时全双工语音前端,支持 barge-in 打断和本地唤醒词)。

15.3 一些维护痕迹

  • 根目录有 HOSTED_SHELL_UNICODE_E2E.md —— hosted shell 的 Unicode 端到端测试说明
  • 有 eslint-rules/ 目录和 eslint.legacy-core-barrel-imports.mjs、eslint.legacy-filenames.mjs —— 专门写了 ESLint 规则来禁止回退到老的 barrel import 和老文件名。这是有历史包袱的项目的典型痕迹,说明代码库经历过大规模重构
  • packages/core/src/services/ 下有 commitAttribution.ts、attributionTrailer.ts、branch-points.ts —— commit 归属追踪,配合 /autofix-pr 这类功能的基建
  • packages/core/src/config/agent-loop-rollout.ts —— agent loop 的渐进式发布(rollout),典型的” 先给 5% 用户开新逻辑”

关于包管理:它同时支持三种安装方式(curl 独立脚本、NPM、Homebrew),NPM 包名是 @qwen-code/qwen-code,作用域是 @qwen-code 而不是 @qwen;仓库里有独立发版的 sdk-typescript-v0.1.35,和主包版本号完全独立。


十六、总结

回到最开始那个烂摊子 —— 我最终在那个六年的单体服务上,用的就是 Qwen Code。

不是因为它最强。说实话,同一个任务我让 Claude Code 也做了一遍,Claude Code 的结果更漂亮一些。

我选它有三个原因:

第一,完全开源。 我得能给团队每个人解释” 它做了什么、为什么这么做”。读不了代码的东西,我不敢往生产里放。

第二,多 provider。 我们公司同时用着国内外几家模型,切换是刚需。

第三,它是一本活的教材。 我想搞明白” 多 Agent 到底怎么编排”、”agent loop 怎么设计”、” 工具输出怎么截断”—— 这些问题的答案都能在 packages/core/src/ 里找到。118 个工具、100 个命令、几十个故障切换测试,这套代码读过之后,我对 agent 系统的理解上了一个台阶。

它的缺点也很明显:功能杂、实验性东西多、默认配置有安全隐患、文档细节不如英文版全。这些我都写在第十二节了。

如果你需要一个今天就能上手的 coding agent,用 Claude Code 或者 Cursor。
如果你需要一个你能读懂、能改、能自托管、能在内网跑的 agent harness,Qwen Code 是目前最好的开源选择之一。

30731 这个数字背后是一个在持续迭代、每天发版、把复杂问题(故障恢复、权限、资源预算)都认真处理过的项目。对 Qwen 团队,我只有一句建议:1.0 正式版发布的时候,把 experimental 的那些功能也一起收敛一下。 现在这个状态,团队引入会有顾虑。


附:本文事实来源

所有数据来自以下可验证来源,写作时间 2026-11-18:

事实 来源
stars / forks / issues / license / language / topics GitHub API /repos/QwenLM/qwen-code
安装命令、命令列表、能力清单 仓库 README.md
SWE-bench 数据与配置 仓库 docs/evaluation.md
daemon 能力与安全说明 仓库 docs/users/qwen-serve.md
package 结构、依赖、scripts 仓库 package.json
workspace 划分与踩坑注释 仓库 pnpm-workspace.yaml
工具清单、core 目录结构 GitHub API recursive tree(共 16632 个文件)
版本与发布节奏 GitHub API /releases、/tags