项目快照：QwenLM/qwen-code，约 27,918 个 Star，3,052 个 Fork；最新推送时间 2026-09-17T13:25:58Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/QwenLM/qwen-code · https://qwenlm.github.io/qwen-code-docs/en/users/overview

qwen-code 从代码、运行环境到实践流程的项目封面
qwen-code 的项目能力与实践流程示意。

项目速览（TL;DR）

qwen-code 是一个以 TypeScript 开发、运行于终端及多种交互入口中的开源 AI 编码代理（AI Coding Agent）。项目采用 Apache-2.0 许可证，默认分支为 main；给定仓库快照显示其获得 27,918 个 Star 和 3,052 个 Fork。

  • 主要入口：在项目目录执行 qwen，通过交互式会话分析代码仓库或处理开发任务。
  • 模型接入：README 明确列出 OpenAI、Anthropic、Gemini 和 Qwen API，并支持第三方提供商以及 Ollama、vLLM 本地模型。
  • 代理能力：README 列出自动记忆（Auto-Memory）、自动技能（Auto-Skills）、子代理（SubAgents）、代理团队（Agent Teams）和模型上下文协议（Model Context Protocol，MCP）。各能力的精确触发规则未出现在给定资料中，应以最新文档为准。
  • 运行要求：NPM 安装路径要求 Node.js 22 或更高版本；包管理元数据指定 pnpm@11.24.0，发布包版本为 0.24.0。
  • 工程形态：仓库采用工作区（Workspace）组织多个包，包含终端主体、聊天渠道、TypeScript SDK、Python SDK相关测试、浏览器扩展测试以及外部上下文集成。

“The open-source AI coding agent for your terminal, editor, desktop, browser, and chat.”

来源：README

定位与目标用户

该项目的核心定位不是单一代码补全插件，而是能够从终端启动、接入模型提供商并参与仓库级开发流程的代理框架。README 还将其覆盖范围扩展到编辑器、桌面端、浏览器和聊天渠道。

面向仓库任务的交互方式

最小使用路径是在代码仓库目录执行 qwen，随后输入自然语言任务。README 给出的示例是要求代理解释当前仓库并指出开始阅读代码的位置，这表明终端会话会以当前项目作为工作上下文。

官方资料没有给出上下文收集范围、忽略文件规则、最大文件数量或上下文窗口限制。涉及大型单体仓库、二进制资产或敏感目录时，应先查阅最新设置参考，并在隔离副本中验证文件访问边界。

多入口而非单终端

README 明确列出终端、IDE 插件、桌面应用、Web UI、SDK 和聊天集成。仓库工作区进一步出现 Telegram、微信、钉钉、企业微信、飞书、QQ Bot、GitHub、GitLab 和 DWS 等渠道目录，说明项目通过独立包拆分部分接入层。

给定资料没有提供每个入口的发布状态、功能对齐情况、平台要求或部署步骤。不能据此认定所有入口都与终端功能完全一致，也不能认定所有渠道均已达到相同稳定级别。

核心功能

Qwen Code 的功能边界可分为代理编排、模型协议接入和多端渠道三部分。README 给出了能力名称，但没有公开到函数签名、状态机或每项功能的完整触发条件，因此下文区分已确认事实与缺失信息。

自动记忆、自动技能与动态工作流

README 将自动记忆和自动技能列为开箱即用的代理能力，并以“Dynamic workflows, zero setup”描述其使用目标。已知输入来自用户会话和当前项目上下文；记忆的存储位置、保留期限、作用域、清理方式以及技能选择算法未出现在给定资料中。

因此，不能把自动记忆等同于永久保存，也不能假定其内容仅留在本机。若项目包含商业秘密或个人信息，应先从官方配置文档确认数据流，再决定是否启用相关能力。

子代理与代理团队

子代理和代理团队用于表达多代理分工能力，README 将两者列在代理能力清单中。其内部任务如何拆分、是否并行执行、如何聚合结果、失败后是否重试以及资源上限均未由给定资料说明。

从使用角度看，触发入口仍是 Qwen Code 会话；依赖项至少包括已配置的模型提供商。官方仓库未提供任务调度协议、并发级别和成本控制数据，建议以最新 README 和设置参考为准。

MCP 接入

README 明确表示项目支持 MCP，说明代理能够围绕该协议扩展外部上下文或工具。仓库工作区还包含 integrations/external-context 和 integrations/external-context-mem0，但给定资料没有说明它们与 MCP 的具体映射关系。

MCP 服务的配置格式、鉴权字段、工具授权模型、超时和返回结构均未提供。部署前不应凭经验编写配置，应直接核对官方设置参考中的现行字段。

多模型协议与运行时切换

README 声明支持 OpenAI、Anthropic、Gemini 和 Qwen API，也允许接入第三方提供商或 Ollama、vLLM 本地模型，并支持运行时切换。已知配置入口是会话内的 /auth，输入包括提供商选择和 API 密钥。

不同协议之间的请求转换、工具调用兼容范围、流式响应行为和模型名称映射没有出现在给定资料中。在云端模型需要外发代码的场景选择对应 API；在明确要求本地推理且已部署 Ollama 或 vLLM 的场景，可评估本地模型路径，但两条路径的功能一致性没有官方数据支持。

系统架构与关键模块

根据 package.json，项目采用 ECMAScript 模块（ECMAScript Modules，ESM）和多工作区仓库结构。现有资料足以确认包边界和构建入口，但不足以还原完整调用链。

层次或模块 资料中的依据 可确认职责 未提供的信息
命令行入口 qwen、scripts/start.js 从终端启动交互会话 命令解析器、会话状态机与工具调度实现
工作区包 packages/* 承载仓库内多个功能包 各包的完整清单与稳定性等级
渠道基础层 packages/channels/base 为聊天渠道提供基础包 抽象接口和扩展契约
聊天与平台渠道 telegram、weixin、dingtalk、wecom、feishu、qqbot、github、gitlab、dws 按平台拆分集成包 各渠道部署参数、权限范围与消息格式
外部上下文 integrations/external-context、integrations/external-context-mem0 提供外部上下文相关集成 数据模型、同步策略与持久化边界
SDK 测试面 integration-tests/sdk-typescript、packages/sdk-python 验证 TypeScript SDK 集成及 Python SDK 测试 公开接口签名和版本兼容矩阵
沙箱构建 scripts/build_sandbox.js、QWEN_SANDBOX 构建并测试 Docker 或 Podman 沙箱路径 生产环境隔离保证、资源配额与网络策略

packages/desktop-shell 和 packages/live-host 被工作区配置显式排除，这只表示它们不在当前 workspaces 匹配范围内，不能据此判断对应功能已废弃。桌面端仍被 README 列为可用界面，具体构建方式应以该目录和最新文档为准。

依赖与运行环境

NPM 安装的明确前提是 Node.js 版本不低于 22.0.0，项目源码以 TypeScript 为主要语言并使用 ESM。源码开发和容器构建还依赖包管理、编译工具及若干系统命令。

  • Node.js：package.json 的 engines.node 为 >=22.0.0。
  • 包管理器：元数据固定为 pnpm@11.24.0，同时仓库脚本大量使用 npm run 和 NPM 工作区命令。
  • 模块格式：type 字段为 module，表示 Node.js 包采用 ESM 语义。
  • 构建阶段：Dockerfile 基于摘要固定的 node:22-slim，安装 Python 3、Make、G++ 和 Git 后执行依赖安装、构建、打包。
  • 容器运行阶段：镜像包含 Python 3、Git、GitHub CLI、curl、jq、ripgrep、rsync、进程检查和网络诊断等工具。

官方资料没有给出最低内存、磁盘容量、CPU 架构矩阵、GPU 要求、Windows 子系统要求或浏览器版本范围。规划开发机和部署资源时不能引用未经仓库验证的容量数据。

快速开始：安装、运行与验证

最小闭环由全局安装、在项目目录启动、通过 /auth 配置提供商以及提交一条仓库分析请求组成。以下路径直接取自 README，并选择便于检查的 NPM 安装方式。

第一步：检查 Node.js 并安装

Bash
# 确认 Node.js 满足 >=22.0.0
node --version

# 从 npm 安装 README 指定的发布包
npm install -g @qwen-code/qwen-code@latest

# 验证命令已进入 PATH
command -v qwen

command -v qwen 仅验证命令是否可被当前 Shell 找到，不代表模型鉴权已经完成。如果安装后找不到命令，应检查 NPM 全局可执行目录是否位于 PATH 中。

第二步：进入测试仓库并启动

Bash
cd /path/to/your-project
qwen

请把 /path/to/your-project 替换为本机已获授权的测试项目目录。首次评估时应使用不包含生产凭据、客户数据和未公开代码的副本。

第三步：配置与功能验证

Text
/auth
Explain this repository and show me where to start.

/auth 用于配置提供商和 API 密钥；README 没有给出可直接粘贴的密钥字段名，因此不应虚构环境变量。若交互界面要求输入密钥，应使用测试用途的 <你的-API-KEY>，并确保该值不进入 Git 历史、终端录屏或共享日志。

验证结果应至少包含对当前仓库的解释，且没有启动错误。官方资料未定义固定输出文本、响应时间或准确率阈值，因此不能用特定措辞或延迟作为兼容性标准。

其他安装路径

README 还提供独立安装脚本和 Homebrew 两条路径。远程脚本会直接进入 Shell 执行，重视供应链审计的团队应先下载并审阅内容，再在隔离环境运行。

Bash
# Linux / macOS：README 提供的独立安装命令
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

# macOS / Linux：Homebrew 安装
brew install qwen-code
Text
# Windows：README 提供的独立安装命令
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

README 要求独立安装完成后重启终端，使环境变量生效。给定资料没有提供脚本校验和、签名验证命令、卸载命令或离线安装流程，受控网络环境应以最新官方安装说明为准。

配置说明

给定资料没有包含完整用户配置文件样例，但 package.json、Dockerfile 和测试脚本公开了若干真实字段。下表区分项目元数据、镜像构建参数和测试环境变量，不能把它们全部视为终端用户配置。

字段名 类型 默认值或资料值 作用
engines.node 字符串 >=22.0.0 声明 NPM 安装和运行所需的 Node.js 版本范围。
type 字符串 module 指定包使用 ESM 模块解析方式。
packageManager 字符串 pnpm@11.24.0+sha512.bd27e345e976dcb0be0b7a1228217b049a817e21b1f355c90dbe7dc46671895a8bc1e6d06c24554505ea93ea0b45f489a27ec1bfbc8de6a9659fca0f16fa0000 固定开发所用 pnpm 版本及完整性标识。
config.sandboxImageUri 字符串 ghcr.io/qwenlm/qwen-code:0.24.0 记录当前包版本对应的沙箱镜像地址。
SANDBOX_NAME Docker 构建参数 qwen-code-sandbox 在 Dockerfile 中为运行镜像设置沙箱名称。
CLI_VERSION_ARG Docker 构建参数 未提供 构建时传入 CLI 版本，并写入镜像中的 CLI_VERSION。
NPM_CONFIG_PREFIX 环境变量 /usr/local/share/npm-global 在 Dockerfile 中指定全局 NPM 包安装目录。
QWEN_SKIP_PREPARE 环境变量 Docker 构建步骤中设为 1 阻止 npm ci 的 prepare 阶段重复执行构建和打包。
QWEN_SANDBOX 环境变量 全局默认值未提供 集成测试脚本分别使用 false、docker 和 podman 选择沙箱模式。
DEBUG 环境变量 调试脚本中设为 1 配合 node --inspect-brk 启动调试流程。

用户侧提供商、模型名、API 地址、密钥存储和 MCP 服务配置没有出现在给定文件片段中。应通过会话内 /auth 和官方设置参考完成配置，不应根据其他项目的字段名进行类推。

进阶用法

仓库脚本覆盖源码开发、构建、打包、工作区测试、集成测试和沙箱测试。以下命令适用于已克隆源码且依赖已正确安装的开发环境，不是全局安装用户的必需步骤。

构建与本地启动

Bash
# 构建全部工作区
npm run build

# 构建后启动
npm run build-and-start

# 构建主体、沙箱和 VS Code 配套组件
npm run build:all

build 通过 scripts/build.js 执行，并把 Node.js 最大旧生代内存设置为 4096 MB。该数值是构建脚本参数，不等于生产运行时的最低内存要求。

测试不同沙箱路径

Bash
# 不使用沙箱运行集成测试
npm run test:integration:sandbox:none

# 使用 Docker 路径运行集成测试
npm run test:integration:sandbox:docker

# 使用 Podman 路径运行集成测试
npm run test:integration:sandbox:podman

项目还提供 test:integration:all 顺序执行三条路径，并提供 TypeScript SDK、CLI 和 Python SDK 的独立测试命令。脚本存在不等于测试在任意宿主机上均可直接通过；Docker、Podman、Python 和相关依赖仍需由执行环境提供。

容器构建与交付

Dockerfile 使用双阶段构建，将源码编译和运行环境分开，并通过摘要固定基础镜像。最终镜像默认执行 qwen，但资料没有给出官方容器启动命令、挂载策略或端口。

Text
FROM docker.io/library/node:22-slim@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS builder

RUN QWEN_SKIP_PREPARE=1 npm ci \
  && npm run build \
  && npm run bundle \
  && npm run prepare:package \
  && cd dist && npm pack

CMD ["qwen"]

构建阶段把打包后的 .tgz 复制到运行阶段并执行全局安装，随后清理 NPM 缓存和临时包。Dockerfile 未声明 EXPOSE，因此不能从现有资料推导任何服务端口；若使用 qwen serve 一类能力，应先查阅对应版本文档。

可观测性与运维

当前资料能确认调试开关、详细测试输出和若干诊断工具，但没有定义生产级指标、追踪协议或日志保留策略。运维设计应把“仓库中存在调试能力”和“已提供完整可观测平台”严格区分。

  • Node.js 调试：npm run debug 设置 DEBUG=1，并通过 node --inspect-brk scripts/start.js 启动。
  • 端到端测试输出：test:e2e 设置 VERBOSE=true 和 KEEP_OUTPUT=true，随后运行无沙箱集成测试。
  • 容器诊断工具：运行镜像包含 curl、dnsutils、jq、procps、lsof 和 socat。
  • 测试框架：脚本明确使用 Vitest；Python SDK 测试使用 pytest。

官方仓库未提供 Prometheus 指标、OpenTelemetry 配置、健康检查端点、日志格式、审计日志字段、轮转策略、告警阈值、SLA 或容量基准。需要这些能力的团队应在试运行阶段自行验证，并避免把调试输出直接记录到包含密钥或源码的集中日志。

安全与合规边界

编码代理会接触源码、用户提示和模型凭据，并可通过多种外部提供商处理请求，因此安全评估必须覆盖文件、网络、身份和日志边界。以下建议只面向自有或明确授权的代码仓库与测试环境。

  1. 限定授权目录：首次运行应位于专用测试副本，不要从包含主目录凭据、生产密钥或客户数据的上级目录启动。
  2. 控制模型数据流：使用 OpenAI、Anthropic、Gemini、Qwen 或其他远程 API 前，应核对组织的数据处理要求。README 只确认协议支持，没有说明各提供商的数据保留条款。
  3. 保护认证信息：通过 /auth 输入的 API 密钥不应写入仓库、构建日志或聊天记录。密钥实际存储路径、加密方式和轮换流程未在给定资料中说明。
  4. 审查聊天渠道：Telegram、微信、钉钉、企业微信、飞书和 QQ Bot 等入口涉及第三方平台。启用前应核对机器人权限、群成员范围、消息留存和跨境数据要求。
  5. 验证沙箱边界：仓库提供 Docker、Podman 和无沙箱测试模式，但资料没有承诺沙箱能够抵御任意恶意代码。处理不可信仓库时，应采用额外的主机、网络和凭据隔离。
  6. 人工复核变更：README 提到项目使用代理和模型提交议题、拉取请求、评审代码和运行测试，但这不构成自动生成结果正确或安全的保证。合并前仍需执行代码评审和测试。

不得把项目用于未授权系统的代码访问、凭据获取、账号控制或规避平台检测。官方资料没有提供 GDPR、等保、SOC 2、ISO 认证、数据驻留或审计合规声明，涉及强监管数据时应由组织的法务与安全团队独立评估。

许可证与商用条款

仓库采用 Apache License 2.0。该许可证允许在满足条款的前提下使用、复制、修改、制作衍生作品、公开展示、再许可和分发，也允许商业使用。

  • 分发源码或目标形式时，应向接收者提供 Apache-2.0 许可证副本。
  • 修改文件后，应以显著方式说明相关文件已被修改。
  • 分发时应保留源码中与版权、专利、商标及署名有关的有效声明，但不包括与衍生作品无关的声明。
  • 若仓库分发物包含 NOTICE 文件，衍生作品的分发还需按许可证要求处理其中的署名内容；给定资料没有展示该文件是否存在。
  • 许可证包含贡献者授予的专利许可，并规定在特定专利诉讼情形下终止相关专利许可。
  • Apache-2.0 不等同于商标授权，也不构成质量、适销性或特定用途保证。

商业产品可以集成、修改或再分发该项目，但仍需履行许可证和适用法律要求。有关第三方依赖许可证、模型权重许可、模型服务条款和品牌使用权的结论不能仅由主仓库许可证推出，最终以仓库 LICENSE、依赖清单及所选模型提供商条款为准。

局限性与已知限制

给定资料展示了较宽的产品边界，但缺少稳定性、性能和兼容性承诺。评估时应把未公开的信息视为待验证项，而不是默认具备。

  • 性能数据缺失：没有 Benchmark、首字延迟、吞吐量、并发上限、上下文规模或大型仓库测试数据。
  • 接口细节缺失：没有完整 SDK 签名、HTTP 路由定义、协议兼容矩阵和版本迁移说明。
  • 代理行为边界缺失：自动记忆、自动技能、子代理和代理团队的触发规则、资源上限及失败恢复机制未在资料中说明。
  • 多端一致性未知：README 列出终端、编辑器、桌面端、浏览器和聊天入口，但没有功能对照表。
  • 安全保证缺失：存在沙箱构建与测试路径，但没有隔离等级、威胁模型、漏洞响应时限或安全认证信息。
  • 运维承诺缺失：没有 SLA、长期支持版本、发布周期、回滚窗口或兼容支持期限。
  • Windows 细节有限：README 给出 PowerShell 安装命令，但未提供完整 Windows 版本矩阵和 Shell 兼容说明。

项目 README 明确表示 Qwen Code 正在积极迭代。版本升级前应检查发布说明、配置变更和测试结果；官方仓库未提供上述缺失项时，建议以最新 README 为准。

适合谁

是否采用该项目，应由现有运行环境、模型接入方式和部署入口决定。以下信号能够直接用于初步筛选。

  • Node.js 环境已达到 22 或更高版本：团队能够满足明确的运行前提，并接受 TypeScript、ESM 和工作区结构。
  • 需要终端内仓库交互：工作流以本地项目目录为中心，希望通过 qwen 会话完成代码理解或代理任务。
  • 需要切换模型提供商：现有系统使用 README 列出的 OpenAI、Anthropic、Gemini、Qwen API，或已经部署 Ollama、vLLM。
  • 需要多渠道扩展：团队计划把编码代理接入 IDE、桌面端、Web、SDK 或仓库中列出的聊天与协作渠道，并愿意分别验证每个包。
  • 具备源码审计与测试能力：团队能够运行工作区测试、集成测试和沙箱测试，并对代理生成的变更进行人工评审。

不适合谁

如果采购或上线前提依赖资料中尚未提供的保证，应暂缓进入生产环境。以下任一条件成立时，需要先补充验证或选择已有明确承诺的方案。

  • 运行环境无法升级到 Node.js 22：NPM 包元数据已经给出硬性版本范围，不应假设旧版 Node.js 可兼容。
  • 要求现成的生产级 SLA：仓库资料没有响应时间、可用性、支持期限或事故响应承诺。
  • 要求可证明的强隔离：虽然仓库包含 Docker 和 Podman 测试路径，但没有给出沙箱安全等级或正式威胁模型。
  • 禁止任何代码或提示离开内网：远程 API 路径涉及外部服务；除非已完成本地 Ollama 或 vLLM 路径验证，并确认全部外部调用均被关闭。
  • 必须预先获得完整合规证明：资料没有提供数据驻留、隐私认证、审计报告或监管合规承诺。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应从运行时版本、命令路径、鉴权和项目目录开始，再进入源码构建或沙箱问题。不要用删除整个环境或关闭安全控制作为首选处理方式。

安装后执行 qwen 提示命令不存在

先运行 node --version 和 npm prefix -g，确认 Node.js 满足 >=22.0.0，并检查全局可执行目录是否进入 PATH。若使用独立安装脚本，README 要求重启终端以使环境变量生效。

启动后无法调用模型

在会话内执行 /auth，重新核对提供商和 API 密钥。官方资料没有给出错误码表、代理服务器字段或密钥环境变量名，应转到认证指南核对当前版本要求。

在错误目录中启动，代理无法理解目标仓库

退出会话，使用 cd /path/to/your-project 进入目标项目根目录后重新执行 qwen。README 的快速开始明确把进入项目目录作为启动前置步骤。

源码构建期间内存不足

build 脚本已经设置 NODE_OPTIONS="--max-old-space-size=4096"。若仍然失败，官方仓库未提供更高数值或最低物理内存要求，不应直接把任意数值写入生产配置；应保留完整日志并核对当前提交的构建说明。

Docker 或 Podman 集成测试失败

先分别运行 test:integration:sandbox:none、test:integration:sandbox:docker 和 test:integration:sandbox:podman，以区分主体测试与容器运行时问题。仓库还提供 test:integration:all，但没有给出 Docker 或 Podman 的最低版本。

如何确认当前资料对应的软件版本

给定 package.json 的版本为 0.24.0，沙箱镜像标签也为 0.24.0。由于项目持续迭代，安装 @latest 获得的版本不保证仍是该版本，应检查本机安装结果并对照对应发布资料。

是否可以完全离线使用

README 列出 Ollama 和 vLLM 本地模型支持，但没有提供完整离线部署流程，也没有声明启动、更新或扩展是否会访问网络。严格离线环境必须自行抓取网络请求并审计依赖，官方仓库未提供该信息，建议以最新 README 为准。

是否有固定服务端口

给定 Dockerfile 没有 EXPOSE 指令，资料也没有列出端口。不能为 CLI、Web UI、SDK 或测试服务编造默认端口，应按对应版本的启动文档配置。

项目地址与资源

以下资源均来自给定仓库资料，可用于核对安装、认证、设置和包版本。版本变化时，应优先以仓库默认分支及对应版本文档为准。