Qwen Code多代理开发指南：Claude Code与Codex子代理协作

引言

开发者同时使用多款AI编程助手，早已成为日常开发中的常见场景。但跨工具协作长期存在显著痛点：在不同AI工具之间迁移任务时，需要反复复述项目仓库背景、粘贴代码变更；当一个助手完成审查后，再将意见带回原始会话，极易出现上下文版本不一致的问题，导致前后讨论基于不同代码基线，最终产出无效结论。

Qwen Code 在9月17日的官方产品周报公布新能力：平台支持调用 Claude Code、Codex 作为外部子代理执行子任务，配套新增工作流调用、预算管控以及Goal长任务控制能力。这套能力的核心思路，是任务拆分、权限传递、结果核验全链路在一条可追踪的工作流内完成。这标志着AI编程工具的竞争，已经从单纯的代码生成能力，升级到多代理任务组织与工程流程编排层面。

在落地这套能力前，首先需要厘清一个关键边界：能够调用外部助手，不等于外部子代理可以无限制接入全部内部工作流。官方子代理文档明确标注了外部执行器的各类限制，只有理解这些约束，才能够搭建稳定可用的多代理架构，而不是只停留在看起来复杂、实际无法运行的概念设计。

Qwen Code：面向代码仓库的执行环境，而非单纯问答工具

Qwen Code 提供一套完整入口，用来完成模型交互、项目文件读取、工具调用与开发任务管理。新用户上手建议优先走官方入门流程，完成环境安装、模型服务配置、本地项目目录绑定，通过小型任务验证整套链路是否通畅。模型能够正确回答代码问题只是基础；可以定位项目文件、理解命令行执行状态、捕获并返回运行失败信息，才代表基础闭环已经搭建完成。

它和普通代码问答模型存在本质区别。问答类模型大多只输出文本层面的代码建议；而Qwen Code作为执行环境，直面真实项目文件、命令执行状态与运行报错。一次代码修复任务中，模型需要掌握当前代码基线、已完成的变更、测试入口，以及用户授权它修改的文件范围。这类上下文信息无法依靠模型临时猜测获取。

基于这个特性，初次使用不建议直接交付宽泛、模糊的大目标。推荐从小任务起步：让模型梳理项目启动流程、定位函数调用链，或是复现并分析单条测试失败案例。这类小任务可以验证三件核心事项：模型获取的项目上下文是否准确、代码执行位置是否符合预期、程序报错信息能否完整捕获。确认基础链路稳定之后，再启动长时间自主执行任务，整体收益会更加可控。

外部子代理：降低跨工具切换成本，明确职责分工

引入外部子代理之后，主会话可以把带有明确边界的子任务向外派发，例如模块代码审查、异常路径排查、备选实现方案设计，再收集外部助手返回的结果汇总处理。需要注意：原有账号体系、工具安装环境是调用前提，主会话的调度能力，并不会替代外部产品本身的身份认证与用量计费体系。

依据当前子代理文档，开发者可以在子代理定义中配置外部执行器。Codex采用单次任务返回结果的接入方式，默认权限为只读；Claude Code支持任务内部多轮交互。不同平台的环境适配存在差异，Windows环境下开发者需要按照文档配置WSL路径。选择哪一类外部执行器，应当匹配任务需求与本地环境，不能默认所有接入模式能力完全对等。

一套可行的分工范式：主会话负责定位问题、准备代码变更；外部子代理只负责校验修改内容，查找边界条件遗漏问题。向外派发的任务描述，需要附带仓库地址、目标文件清单、代码基准版本、关注问题与输出格式。如果只简单下发“全面审查代码”这类模糊指令，会扩大检索范围，产出大量和目标无关的建议，任务结束判定也会变得困难。

返回结果同样需要标准化规范。有效的审查意见，需要明确问题位置、触发条件、业务影响以及验证方案。单纯“存在潜在风险”“建议补充单元测试”这类泛化描述，无法直接纳入代码修复清单。主会话需要把可复现缺陷和代码风格建议区分开，再判断是否执行代码调整。

同时需要注意，多模型协作不等于自动获得独立交叉验证。如果两个助手读取同一份错误需求描述，或是两者都没有执行测试，它们有可能给出一致的错误结论。更合理的分工方式，是拆分不同助手的职责与证据来源：一个校验代码逻辑路径，另一个核查测试覆盖度，最终以程序运行结果、人工复审作为最终判定依据。

工作流、Skill、工具：三者的定位区分

在多代理文档里，Skill、工具、工作流三个概念经常一起出现，但三者职责完全不同。Skill代表完成一类任务所需要的方法与知识；工具负责实际读取、查询、修改文件或是执行命令；工作流定义多个步骤的组织方式，以及分支跳转、任务终止的触发条件。经验丰富的AI助手可以依靠Skill独立规划任务，而稳定可复用的团队流程，仍然需要显式的阶段结构。

举个例子，版本发布前的标准化操作：整理代码变更、执行测试、生成文档说明、核对版本号。这套固定顺序可以保存为工作流。它的价值，在于复用预先约定好的步骤，省去每次重复说明流程的成本。命名后的工作流支持直接调用，也可以扩展自定义流程。但安装流程模板不代表适配所有仓库，项目自身的构建命令、分支规范、验收标准，依然需要单独补齐。

新版本增加了执行前结构预览功能，开发者可以提前查看任务拆分方案、并行分支与循环节点。这份预览内容应当作为人工审阅对象。如果一份简单文档整理任务，被拆分为多层循环与大量子任务，说明流程存在过度设计。增加协作节点，有时只会提升上下文传递、结果汇总的开销，并不会带来效率提升。

开发者不要混淆外部执行器和内部代理的配置项。当前文档标注，外部执行器在模型覆盖范围、可用工具列表、钩子函数、团队与工作流能力上都存在限制。文档中的协作示意图，不能理解为外部助手可以直接嵌入任意工作流节点。落地实施时，需要查阅当前版本支持的执行模式，再选择主会话派发或是内部流程调用。

可靠的工作流本质上类似一份任务合同：写明输入数据、允许访问资源范围、每一步交付物、终止触发条件。缺少这些约束，再美观的可视化流程，也无法阻止任务范围持续膨胀，出现越权操作。

预算、轮数与时间：三类资源约束的作用

长任务的资源消耗，不能只看模型输出的token文本量。读取文件、传递上下文、调用子代理、结果校验、反复修复，都会持续消耗资源。为工作流设置token预算，能够帮助系统在资源上限内调度任务，但预算不能当作跨服务商统一结算账单。

Goal模块面向持续迭代的目标任务，官方文档定义了目标持续执行与管控方式。本次更新新增轮数上限、活跃时长上限。轮数管控限制推理回合，时间限制控制实际运行时长，token约束控制模型处理的数据量。三类约束相互关联，但不能直接互相换算。

举一个工程场景案例：让助手排查间歇性测试失败。可以设定流程，先整理复现路径，再在轮数与时间上限内开展尝试。到达资源边界时，任务需要交付已经排除的诱因、待验证假设，以及下一步可执行的实验方案。就算问题没有当场修复，也会留存可继续推进的成果，而不是只返回一句“任务处理中”。

终止条件最好同时包含业务任务条件与资源条件。“找到可复现缺陷并且完成针对性验证”属于任务条件；“达到最大轮数或者运行超时”属于资源条件。只设置资源上限，任务可能在无效中间状态强制停止；只依靠业务条件，则可能在错误假设上持续消耗资源。两类条件组合设计，更贴合真实项目场景。

任务恢复也需要明确校验逻辑。重启任务前，要确认仓库与依赖是否变更，之前得出的结论是否仍然有效，再沿用已有证据。如果直接在旧会话继续执行，但测试环境已经发生变化，前面排查得到的结论很可能失效。

Worktree与沙箱：隔离机制的不同作用，不可互相替代

多任务同时修改同一仓库时，工作目录隔离至关重要。Git Worktree能够在独立目录检出分支，并行开展工作，降低文件互相覆盖的风险。Qwen Code Worktree文档提供对应的使用路径，适合并行开发与独立代码审查。但它不会自动为任务生成独立数据库、缓存或者外部服务。

典型场景：两个独立工作区连接同一个测试数据库，仍然会修改同一份业务数据；多个开发服务绑定固定端口，也会产生端口冲突。文件隔离只是防护的第一层，端口、服务、凭证、测试数据，都需要在流程设计时做好隔离。

沙箱机制管控另一类边界：进程可以访问哪些文件、调用哪些系统资源。Qwen Code新增Linux bwrap后端，可在配置范围内限制输入输出。但沙箱只能约束操作系统层面权限，无法判断业务逻辑是否正确，也不能消除模型本身的逻辑错误。

推荐落地顺序：先用只读模式分析代码，确认修改范围；在隔离工作区执行变更；完成修改后，在独立沙箱验证运行结果，再对比差异提交合并。外部子代理优先配置只读权限，仅在必要场景放开修改权限。权限隔离可以分层控制风险，不要因为开启安全模式，就默认所有进程完全受到保护。

小型代码修复流程，搭建适合自身的使用范式

新手可以从简单任务起步，例如修复接口空参数返回错误状态码。第一步先保存当前代码基线，明确预期行为与复现步骤，交给主会话定位相关代码与测试用例。这个阶段目标是产出简短诊断：问题发生位置、触发条件、验证方案。

第二阶段执行代码修改，要求改动保持局部化，保留原有正常分支。测试用例需要覆盖原始失败场景和相近正常场景。测试失败时优先读取报错信息，区分问题类型：代码缺陷、测试用例错误或是环境准备异常，不必反复生成大量断言。

第三阶段引入独立审查。派发任务给只读权限的外部子代理，让助手检查边界条件、兼容性与异常处理。任务指令附带基线版本、修改范围，要求只输出可验证问题。主会话根据审查报告补充验证、修正代码，最终输出差异文件与测试结果。

这套流程尽量保持精简。只有多个互不依赖模块可以并行推进时，才增加并行子任务；只有相同顺序需要反复执行，才保存为工作流。自动化是为了解决重复需求，不能为了使用新功能，人为增加多余步骤。

对于团队协作场景，流程要明确最终验收责任人。AI助手可以完成代码分析、验证执行，但发布风险、需求取舍、用户体验判定，依然需要项目负责人决策。交付文档重点写明：修复内容、验证方式、剩余边界风险，远比长篇AI工作记录更有价值。

给多代理的任务：编写清晰的任务合同

一份可分发的任务说明，包含五大要素：目标、已有事实、允许范围、交付物、停止条件。目标定义待解决问题；已有事实避免重复调研；允许范围管控修改权限；交付物规范结果汇总格式；停止条件定义任务失败、超时的处理方式。清晰的任务合同，远比给代理起不同角色名称更影响协作质量。

以代码审查任务举例，可以这样定义指令：核查分页参数修改是否影响最后一页查询结果；仅读取指定文件，不修改代码；每条缺陷写明触发路径、文件位置与验证方法；没有确认问题时，需要明确说明。这种描述方便助手产出可验证结论，减少泛化建议被当成严重缺陷。

如果任务涉及文件修改，需要补充文件归属与接口约定。两个任务同时编辑同一份核心配置，即使处于独立工作区，合并时依然会产生冲突。可以指定主会话负责接口定义，另一个代理等待接口确认之后再落地实现。

上下文不是越多越好。向每个执行器传递精简的历史变更、当前基线、确定结论，保留原始证据用于核对，不需要附带全部无关历史对话。过度传递上下文，会增加理解成本，还可能引入过时信息，干扰判断。

同时要规避无限循环审查。一个助手提出修改，第二个助手执行修改，第三个再次提出新偏好，流程会持续往复。可以设置终止规则：只有可复现缺陷或者明确需求缺陷，才继续迭代；当连续多轮没有新增有效问题，直接进入最终验收。停止的判定依据是任务质量，不是模型能否继续对话。

这类约束规则，对单代理任务同样适用。即便不接入外部执行器，清晰的输入边界、验收标准，也会让AI编程任务更容易稳定落地。多代理只是放大问题解决能力，并没有改变软件开发需要明确需求与验证的底层逻辑。

评估多代理架构是否真正带来收益

判断多代理是否提升效率，可以对照单代理模式，在同类任务中对比指标：总耗时、人工介入时长、最终确认缺陷数量、代码回滚次数、资源成本。如果分工方案能够发现更多真实缺陷，并且降低人工复核工作量，就具备保留价值；如果只是产出更多文字与意见，没有实质收益，就不需要继续使用。

需要重点关注上下文切换开销。每次把任务移交另一个助手，都要重新组织背景；每次接收返回结果，都要核对代码基线。任务体量太小，协作开销会超过执行收益；任务体量过大，边界模糊，容易出现重复工作。适合派发的子任务，应当输入清晰、输出明确、可以独立验收。

在多模型调用架构中，开发者会统一对接不同模型服务，通过网关统一管理请求。koalaapi作为API gateway，可以集中管理多模型接入请求，统一处理鉴权、限流，简化多代理场景下多模型服务的调度管理。

总结

Qwen Code 本次更新的核心价值，是将AI代码助手从“写代码”升级为“管理一段开发流程”。外部子代理、工作流、Goal任务、Worktree目录隔离、沙箱权限管控，分别解决不同维度的问题，组合使用时必须遵守各自的能力边界。搭建多代理系统，优先把单个任务做到可验证、可恢复，再逐步扩大自动化范围。直接搭建庞大的多代理团队，更容易遇到稳定性问题，很难拿到预期收益。

AI多代理编程工作流不是简单堆叠多个模型，而是一套工程约束体系。任务拆分、权限隔离、资源预算、结果核验、终止条件，每一环都会影响整套系统的稳定性。落地过程中，要区分模型能力和环境隔离能力，不要高估多代理的自动协作能力，用明确任务合同约束每一个子任务，才可以发挥这套新能力的价值。

了解更多：https://koalaapi.com