在实际的软件工程协作中，ClaudeCode 已经从单纯的终端问答工具，变成能够独立读取文件、执行命令、修改代码、提交结果的命令行智能体。单个智能体处理中型任务时表现稳定，但一旦任务跨多个模块，比如一个项目既要实现登录认证，又要做报表模块，还要保证两边的接口约定一致，单个代理很容易在长上下文里丢失约束。多智能体编程的思路，是把一个完整需求拆成多个边界清晰的子任务，由多个 ClaudeCode 子代理分别完成，再由总控程序统一调度、汇总和审查。本文围绕这条主线，先讲清楚多智能体的四种交互模式，再给出 ClaudeCode 的安装和配置方法，最后用一个 Python 编排脚本演示如何并行驱动多个子代理，并整理常见问题和生产环境注意事项。
1. 多智能体编程解决的是单个 ClaudeCode 处理不了的问题
1.1 单智能体在完整需求前先碰到三个瓶颈
很多团队刚开始使用 ClaudeCode 时，习惯把整个需求一次性丢给一个会话，让它在同一个上下文里完成分析、编码、测试和修复。表面上效率很高，实际推进到一定规模后，三个问题会依次暴露。
第一个是长上下文带来的约束丢失。模型在数千字的需求里还能记住接口命名规则，但当对话推进到十几个文件后，最早约定的公共规范经常被遗忘。比如一开始说好所有模块不引入第三方框架，后面的子模块可能还是会自作主张加依赖。
第二个是修改面过大导致回归失控。单个智能体同时改认证、报表、工具类三个部分，任何一个改动都可能影响其他部分，但它很难在同一个会话里做完整的回归验证。最后只能依赖人工 review，等于把模型省下的时间又还了回去。
第三个是角色冲突。需求分析、编码实现、代码审查如果由同一个智能体完成，它很容易偏向自己写出来的方案，缺少客观交叉验证。尤其是在生成代码之后，让它自己检查自己，通常只能发现语法级问题，发现不了设计级缺陷。
1.2 多智能体编程的三个收益
把任务拆给多个 ClaudeCode 子代理，核心收益有三个。
第一是责任隔离。每个子代理只读自己相关的那部分需求，只写自己负责的目录，上下文更短、更集中，约束不容易丢失。第二是并行执行。如果子任务之间没有强依赖，可以同时启动多个claude进程，整体耗时从串行相加变成并行取最大值。第三是可审查。每个子代理结束时输出一份独立报告，总控智能体基于这些报告做集成审查，审查对象是明确的产物，而不是一个长对话里模糊的“之前说过的约定”。
1.3 前置条件和本文目标
开始之前，需要准备以下环境：
- Node.js 18 或更高版本，ClaudeCode 以 npm 包形式分发。
- 一个可用的 Anthropic 兼容 API Key，或者一个提供 Anthropic 兼容协议的服务网关。
- 基础的 Python 3 环境，用于编写编排脚本。
- 能在终端里稳定运行命令的操作系统，Windows、macOS、Linux 均可，Windows 下建议使用 Windows Terminal。
本文会带你完成三件事：理解多智能体的四种交互模式，完成 ClaudeCode 的安装和免交互配置，最后用 Python 脚本并行驱动两个子代理实现一个最小项目，并处理结果汇总和交叉检查。
2. 多智能体的四种交互模式，先理解再实践
多智能体系统业界并没有唯一标准分类，但在工程实践里，比较常见的分类可以归纳为四种模式：流水线模式、广播并行模式、中心化编排模式、去中心化协商模式。ClaudeCode 本身不限定只能使用某一种，它提供的是命令行进程和文件系统，四种模式都可以通过脚本组合出来。
2.1 流水线模式：任务按顺序传递
流水线模式的核心是“上一个智能体的输出是下一个智能体的输入”。适合天然有先后顺序的任务，比如先做代码生成，再做静态检查，再做测试补充，最后生成发布说明。
在 ClaudeCode 场景下，流水线模式通常这样组织：子代理 A 把产物写到指定目录，脚本检查产物存在后，把产物路径传入子代理 B 的 prompt。如果中间某一步失败，整个流程暂停，避免把错误结果往后传。
claude -p "读取 requirements/design.md，生成骨架代码到 src/generated，并输出实现说明" --allowedTools "Read,Write,Edit" --output-format json claude -p "读取 src/generated 下的代码，找出不符合规范的地方并修复" --allowedTools "Read,Write,Edit" --output-format json这种模式实现成本低，问题也一目了然：全链路耗时等于所有子代理耗时之和，且上游的约束错误会一路传导到下游。
2.2 广播并行模式：多个智能体同时处理
广播模式把同一份任务说明同时交给多个智能体处理，它们彼此独立，最后再由一个汇总程序选择或合并结果。适合方案选型、代码审查、风险分析这类需要多个视角的场景。
比如要求三个子代理分别给出用户权限模块的设计方案，每个智能体可以从简单令牌、RBAC、ABAC 三个不同方向展开。汇总阶段不是简单取交集，而是按需求约束逐条对比，选出满足约束最多的方案，或者把不同方案的优点合并成最终设计。
这种模式的代价是需要额外的结果去重和投票逻辑。如果汇总程序只是简单拼接所有输出，最终结果会严重冗余，主代理在审查时反而更累。
2.3 中心化编排模式：主代理统一调度
中心化编排模式，也叫调度者-执行者模式，是最适合模块化开发的一种方式。一个主代理负责拆解任务、分配子任务、收集结果、评估产出。子代理只负责执行，不负责整体决策。
这种模式天然贴合软件工程的模块划分。主代理先读公共需求和项目结构，把任务拆成“认证模块”“报表模块”“工具类模块”，然后为每个模块启动一个子代理。子代理完成后，主代理做交叉审查，检查模块之间接口是否一致，再决定是否需要返工。
中心化模式的优点是控制力强，缺点是主代理的压力集中。任务拆解质量直接决定整个流程的成败，主代理如果漏掉了一个关键约束，所有子代理都会沿着错误的拆解方向执行。
2.4 去中心化协商模式：角色间动态协作
去中心化协商模式让多个智能体分别扮演不同角色，在公共的沟通空间里交换意见、互相提问、逐步收敛。比如一个智能体扮演架构师，一个扮演后端开发者，一个扮演测试工程师，围绕同一份需求反复讨论。
这种模式在 ClaudeCode 里实现成本较高。每个claude进程上下文相互隔离，协商内容必须通过共享文件系统传递，比如约定一个conversation/目录，每个角色把意见写入自己的文件，再让其他角色读取。实现不好容易发散，一个问题讨论十几轮还收不了场。
2.5 四种模式对比与选型
| 模式 | 协作方式 | 适用场景 | 优点 | 主要挑战 | 实现成本 |
|---|---|---|---|---|---|
| 流水线 | 串行 | 数据处理、分阶段构建 | 结构清晰，便于定位失败环节 | 整体耗时长，上游错误传导 | 低 |
| 广播并行 | 并行 | 方案选型、多视角审查 | 横向扩展容易，视角丰富 | 结果冗余，需要投票或合并逻辑 | 中 |
| 中心化编排 | 主从 | 模块化开发、任务拆解 | 控制力强，适合工程流程 | 主代理决策压力大 | 中 |
| 去中心化协商 | 动态协作 | 复杂方案研讨、评审 | 灵活性高，能暴露冲突 | 容易发散，收敛困难 | 高 |
对于第一次实践多智能体编程的团队，建议从中心化编排模式入手，因为它的任务边界最符合日常开发习惯，也最容易用文件目录和退出码来验证。
3. 环境准备：安装 ClaudeCode 并完成基础配置
3.1 安装前提
在安装之前，可以先检查本机环境。不同环境的主要差异在于 Node.js 的安装方式和 npm 全局目录的写权限。
| 检查项 | 推荐要求 | 说明 |
|---|---|---|
| Node.js | 18 或更高 | ClaudeCode 通过 npm 分发，Node 版本过低会安装失败 |
| npm | 与 Node 配套即可 | Windows 上注意 npm 全局路径是否在 PATH 中 |
| 操作系统 | Windows / macOS / Linux | Windows 建议使用 Windows Terminal 作为交互终端 |
| API Key | 官方账号或兼容网关 | 多智能体并行场景对并发额度有要求，测试账号容易触发限流 |
在麒麟这类国产 Linux 系统上，安装思路和普通 Linux 一致，关键是先把 Node.js 装好。推荐用 nvm 或系统包管理器安装 LTS 版本，避免用编译源码的方式浪费时间。
node -v npm -v如果node和npm都能正常输出版本号，再执行 ClaudeCode 的全局安装。
3.2 安装与版本验证
ClaudeCode 的 npm 包名是@anthropic-ai/claude-code，终端命令是claude。
npm install -g @anthropic-ai/claude-code claude --version安装完成后，执行claude --version能输出版本号，说明核心安装成功。如果提示claude: command not found，通常是 npm 全局目录没有加入 PATH。可以先执行npm root -g查看全局目录，再把它加入 shell 的 PATH 配置。
npm root -g # 例如输出 /usr/local/lib/node_modules # 则在 ~/.bashrc 或 ~/.zshrc 中加入： export PATH="/usr/local/bin:$PATH" source ~/.bashrc3.3 API 配置和第三方模型接入
ClaudeCode 默认读取ANTHROPIC_API_KEY环境变量作为认证凭证。本地开发时，可以把变量写入 shell 配置文件，避免每次启动都手动 export。
export ANTHROPIC_API_KEY="你的API密钥"多智能体并行场景下，每个子代理进程都会读取同一份环境变量。如果直接在代码里写死密钥，存在被提交进 Git 仓库的风险。推荐统一从环境变量读取，并在编排脚本里透传给子进程。
除了官方 API，社区里还有一种常见做法，通过 Anthropic 兼容协议接入第三方模型服务。以 DeepSeek 为例，它的开放平台提供了兼容 Anthropic 消息格式的接入地址，配置方式如下：
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek密钥"具体路径和参数以服务方当前文档为准。接入后如果提示模型不存在，可以主动通过--model参数指定服务方提供的模型名，例如deepseek-chat或deepseek-reasoner。要注意的是，不同模型的上下文窗口大小差异很大，ClaudeCode 默认会携带项目上下文，第三方模型如果窗口较小，需要控制项目的无关文件数量。
3.4 权限确认与免交互设置
ClaudeCode 默认在每次执行命令、写文件之前要求确认，这是防止智能体误操作的安全机制。但在脚本编排多智能体时，无法每步都人工点确认。常见的解决方案有两种，安全性不同。
第一种是在非交互模式下使用允许命令白名单。-p参数表示一次性执行任务，--allowedTools用于限制子代理可以使用的工具：
claude -p "完成某个任务" --allowedTools "Read,Write,Edit,Bash" --output-format json第二种是使用--dangerously-skip-permissions，跳过所有权限确认。这个参数只建议用在完全可信任的隔离环境或 CI 沙箱里，生产环境如果无差别跳过权限校验，等于把文件删除、网络请求等危险操作全部开放给模型。
注意：
--dangerously-skip-permissions的命名本身就说明风险。真实项目里优先用白名单方式，只放行任务必须的工具，Bash 类操作要尽量约束到具体命令。
交互式会话中还可以用/permissions命令动态调整权限策略，也可以在~/.claude/settings.json中配置默认规则。下面是一个示例，实际字段以当前版本claude --help和官方文档为准：
{ "permissions": { "allow": [ "Read", "Write", "Edit", "Bash(npm test)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)" ] } }配置里要写清楚允许哪些工具、拒绝哪些危险命令。这样既能减少点击确认的频率，又不会把安全检查全部关掉。
4. 最小实践：用 Python 编排 ClaudeCode 并行子代理
这一节用一个最小可运行案例，演示中心化编排模式。两个子代理分别实现认证模块和报表模块，脚本用 Python 的 asyncio 并发启动两个claude进程，最后用一个只读审查代理检查公共约定是否被遵守。
4.1 项目结构和任务说明
项目目录刻意保持精简，重点是体现“任务拆解、并行执行、产物汇总”三个环节。
multi-agent-demo/ ├── requirements/ │ ├── spec-common.md # 公共约定 │ ├── spec-auth.md # 认证模块需求 │ └── spec-report.md # 报表模块需求 ├── scripts/ │ ├── orchestrator.py # 并行调度多个子代理 │ └── reviewer.sh # 交叉审查命令 ├── src/ │ ├── auth/ # 子代理 auth-agent 的输出目录 │ └── report/ # 子代理 report-agent 的输出目录 └── output/ # JSON 结果落盘目录公共约定文件是所有子代理都必须先读的约束。它不需要很长，但必须把跨模块的关键规则写清楚。
# 公共约定 - 不引入第三方框架，只使用标准库 - 代码注释使用中文 - 每个模块必须输出 AGENT_REPORT.md - 模块间默认通过函数调用交互，不要使用全局变量认证模块的需求说明文件长这样：
# 认证模块需求 - 提供 login(username, password) 函数 - 校验失败抛出自定义异常 AuthError - 成功后返回 token，有效期 2 小时 - 输出文件：src/auth/auth.py、src/auth/AGENT_REPORT.md报表模块的需求说明文件类似，只是功能不同，同时注明它不依赖认证模块的实现细节，只依赖一个get_current_user()函数签名。
4.2 并行编排脚本
orchestrator.py的核心逻辑是：为每个子代理构造 prompt，启动一个claude -p子进程，用asyncio.gather并发等待所有进程结束，最后把每个子代理的结构化输出打印出来。
import asyncio import json import os API_KEY = os.environ.get("ANTHROPIC_API_KEY", "") AGENTS = [ { "name": "auth-agent", "spec": "requirements/spec-auth.md", "target": "src/auth", }, { "name": "report-agent", "spec": "requirements/spec-report.md", "target": "src/report", }, ] def build_env(): env = os.environ.copy() env["ANTHROPIC_API_KEY"] = API_KEY return env async def run_agent(agent: dict) -> dict: spec = agent["spec"] target = agent["target"] prompt = ( f"你是 {agent['name']}。" f"请先阅读公共约定 requirements/spec-common.md，再阅读 {spec}。" f"在 {target} 下实现需求，并在该目录写入 AGENT_REPORT.md，" f"说明完成了哪些文件、依赖了哪些模块、遗留哪些问题。" ) cmd = [ "claude", "-p", prompt, "--allowedTools", "Read,Write,Edit,Bash", "--output-format", "json", ] proc = await asyncio.create_subprocess_exec( *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, env=build_env(), cwd=os.getcwd(), ) stdout, stderr = await proc.communicate() return { "name": agent["name"], "code": proc.returncode, "stdout": stdout.decode(), "stderr": stderr.decode(), } async def main(): results = await asyncio.gather(*(run_agent(a) for a in AGENTS)) for r in results: print(f"=== {r['name']} exit={r['code']} ===") if r["stderr"]: print("STDERR:", r["stderr"][:500]) if r["stdout"]: try: data = json.loads(r["stdout"]) print("RESULT:", data.get("result", "")[:800]) except json.JSONDecodeError: print("RAW:", r["stdout"][:800]) if __name__ == "__main__": asyncio.run(main())这段脚本有几个关键设计和取舍需要理解。
-p参数让claude以非交互方式运行，这是脚本编排的前提。如果省略-p，用户会进入交互式会话，编排脚本无法自动结束。
--output-format json让结果以 JSON 形式输出，脚本可以解析result字段，而不是从一大段终端文本里人工提取。
--allowedTools限定子代理只能使用 Read、Write、Edit、Bash 四类工具，既保证它能完成编码任务，又从工具层面压低了误操作风险。
asyncio.create_subprocess_exec直接创建子进程，不经过 shell，避免命令注入类问题，同时配合asyncio.gather实现真正的并发执行。
4.3 交叉审查与结果验证
两个模块都完成后，需要有一个独立的审查步骤。这里用第三个只读代理完成交叉检查，它不写任何代码，只允许 Read 工具：
claude -p "请阅读 requirements/spec-common.md，再阅读 src/auth/AGENT_REPORT.md 和 src/report/AGENT_REPORT.md，检查两个模块是否满足公共约定，输出不满足项清单。" \ --allowedTools "Read" \ --output-format json也可以把这步封装成reviewer.sh，方便在 CI 里复用。审查代理的产出是一份问题清单，人工只需要关注这份清单，不用再从头读两个模块的完整代码。
运行整个流程：
python scripts/orchestrator.py正常情况下的输出类似：
=== auth-agent exit=0 === RESULT: 已完成 login 函数和 token 签发，文件：auth.py、AGENT_REPORT.md === report-agent exit=0 === RESULT: 已完成报表聚合逻辑，文件：report.py、AGENT_REPORT.md验证成功的关键标准有三个：两个子代理的退出码都是 0；src/auth和src/report目录下都生成了 AGENT_REPORT.md；审查代理没有报告违反公共约定的项。
4.4 有依赖关系时改为流水线
如果两个任务存在强依赖，比如报表模块必须等认证模块的接口确定后才能开发，就不能用并行模式。这时候把编排脚本改成顺序执行即可：先运行 auth-agent，确认退出码为 0，再把src/auth/AGENT_REPORT.md的路径作为参数拼进 report-agent 的 prompt 中，让第二个子代理在明确接口签名的基础上继续开发。
这四种模式的切换，在脚本层面只是控制并发和顺序的差异，ClaudeCode 本身不需要改动。掌握这一点，多智能体编程的骨架就已经建立了。
5. 常见问题与排查链路
多智能体编程的报错，很多时候不是算法问题，而是环境、权限、上下文配置没有对齐。下面四类问题出现频率最高。
5.1 安装和启动类问题
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
claude: command not found | npm 全局目录不在 PATH | npm root -g、echo $PATH | 把全局 bin 目录加入 PATH，或直接使用npx claude |
| Windows 提示与当前系统不兼容 | Node 版本过旧或系统组件缺失 | node -v查看版本 | 升级 Node，改用 Windows Terminal，Windows 上优先考虑 WSL 环境 |
| 安装报 EACCES 权限错误 | npm 全局目录无写权限 | 查看安装日志中的路径 | 使用 nvm 管理 Node，避免用 sudo 强行安装全局包 |
5.2 认证和模型接入类问题
常见现象是启动后立刻报 401、403 或模型不存在。
- 401 Unauthorized：
ANTHROPIC_API_KEY未设置或密钥无效。执行env | grep ANTHROPIC检查环境变量，确认不是多个 shell 配置文件互相覆盖。 - 404 路由错误：接入第三方兼容网关时，
ANTHROPIC_BASE_URL缺少正确路径。比如 DeepSeek 兼容端点需要完整路径，不能只写到域名根路径，具体以服务方文档为准。 - 模型不存在：第三方网关的模型名与默认值不匹配。用
--model显式指定服务方提供的模型名，再检查模型名拼写是否包含版本后缀。 - 上下文长度不足：第三方模型窗口小于 ClaudeCode 默认发送的项目上下文。精简项目目录，保持
CLAUDE.md内容精炼，必要时用 ignore 配置排除无关文件。
5.3 权限确认频繁弹出问题
多智能体场景下，每个子进程都会触发确认，如果交互式运行会非常痛苦。优先检查三处。
先在交互式会话里执行/permissions查看当前权限状态，确认是否处于默认的逐条确认模式。再看非交互命令是否带了白名单参数：
claude -p "任务描述" --allowedTools "Read,Write,Edit,Bash" --output-format json最后检查~/.claude/settings.json，确认是否需要把高频操作加入permissions.allow。
注意：不要为了省事直接使用
--dangerously-skip-permissions跑在真实项目目录上。尤其是包含数据库、支付、外部接口调用的仓库，建议先在隔离的 git 分支或容器环境里验证，再决定是否放宽权限。
5.4 多智能体上下文隔离问题
这是多智能体编程最容易踩的坑。每个claude进程是独立会话，子代理 A 做了什么，子代理 B 完全不知道。具体表现是：两个模块都成功生成，但 A 引用的函数名和 B 的实现对不上，集成时接口报错。
出现这类问题，先看公共约定文件是否真的被所有子代理读取。再检查每个子代理是否写了 AGENT_REPORT.md，报告里如果没交代对外接口签名，说明 prompt 的任务说明不够明确。最终解决方案是统一在任务说明里强制要求：必须输出接口签名、依赖清单和遗留问题。
5.5 多智能体排查顺序建议
遇到问题时，按下面的顺序排查，能快速缩小范围。
- 环境变量是否正确：
env | grep ANTHROPIC，确认 Key、Base URL、Token 都已设置。 - 单独运行最小任务：
claude -p "输出 hello" --output-format json，确认基础调用能通。 - 单独运行一个子代理：只保留
AGENTS列表里的第一项，确认单代理能完成任务。 - 再增加到两个并行代理：观察是否出现限流、并发冲突。
- 最后做交叉审查：重点看公共约定是否被遵守，接口是否对齐。
前两步能过滤掉大部分环境问题，第三步能过滤掉 prompt 设计问题，第四步才是真正的多智能体并发问题。
6. 生产环境最佳实践与扩展方向
6.1 学习环境与生产环境的差异
在本地跑通一套多智能体脚本，和生产环境稳定运行是两回事。主要差异集中在权限、并发、安全和可观测性。
| 维度 | 学习环境 | 生产环境 |
|---|---|---|
| API Key | 个人测试密钥 | 独立账号，通过密钥管理服务注入 |
| 权限策略 | 允许通配 Bash | 白名单命令，危险操作走人工审批 |
| 并发数量 | 2 到 3 个子代理 | 按 API 配额设计并发，增加队列和重试 |
| 结果输出 | 控制台打印 | JSON 落盘，结构化日志归档 |
| 代码安全 | 公开代码即可 | 私有仓库，禁止子代理上传或外发敏感信息 |
| 失败处理 | 失败后手动重跑 | 自动重试、失败预案、产物回滚 |
生产环境的编排脚本还要补充超时控制，防止某个子代理长时间不返回。asyncio 的wait_for可以给每个子进程设置超时时间，超时后主动 kill 进程并记录失败原因。
6.2 发布前的检查清单
多智能体生成的代码进入代码库之前，建议逐项确认以下内容：
- 每个子代理是否都生成了 AGENT_REPORT.md，报告是否包含接口签名和遗留问题。
- 公共约定是否被所有模块遵守，包括命名规范、目录结构、依赖限制。
- 是否执行了独立的交叉审查，审查代理的结论是否被人看过。
- 代码是否通过本地的 lint、单测和构建，而不是只看模型自述“已完成”。
- 环境变量和密钥是否已经在代码和日志中清理干净。
- 是否存在子代理执行过危险命令的记录，权限日志是否保留。
这个清单可以固化成脚本，放在编排流程的最后一步自动执行，人工只负责处理异常项。
6.3 从脚本到平台，以及工具选型边界
当前这套 Python 编排方案适合中小项目。任务数量增多后，脚本的短板会逐渐暴露：没有任务队列、没有失败重试、没有日志检索、没有状态可视化。下一步可以考虑引入支持 Anthropic 兼容协议的开源 Agent 框架，或者把 ClaudeCode 作为执行引擎接到团队的 CI 流水线上。
如果团队同时也在对比其他终端编程工具，可以从使用体验角度做区分。下表只列出常见差异，具体以各工具当前文档为准：
| 工具 | 典型形态 | 模型来源 | 适合的集成方式 |
|---|---|---|---|
| ClaudeCode | Anthropic 官方 CLI，npm 全局包 | 默认 Anthropic API，可配兼容网关 | 脚本编排、CI 自动化 |
| Codex | OpenAI 的 CLI 编程工具 | OpenAI 系列模型 | 面向 OpenAI 模型的自动化流程 |
| OpenCode | 社区开源终端编程工具 | 可配置多种模型网关 | 需要改源码或深度定制时 |
IDE 集成方面，Trae、IDEA 等编辑器的相关插件本质上仍然是把claude命令行作为后端引擎，界面上做得更友好，核心能力还是 CLI 进程。多智能体编排如果需要图形化管理，也可以考虑在 Web 平台上展示任务状态和产物列表，但执行层保持一致，便于复用已经验证过的脚本。
ClaudeCode 多智能体编程真正的难点，不是把并发脚本跑起来，而是让多个智能体的产出在约定层面收敛。建议从两个模块的最小项目开始，跑通并行执行、产物归档和交叉审查三个环节，再逐步增加任务数量。下一步可以尝试在 GitHub Actions 里定时触发这套流程，把多智能体审查接入日常代码提交，让这类实践从一次性实验变成团队可复用的工程能力。
