最近折腾多 Agent 协作的人，应该都被 Codex 刷屏了。作为一个既玩过多智能体框架、又在企业项目里落地过 Agent 服务的从业者，我对这个工具的走红并不意外，但我更关注的是它背后的协作机制，以及它和 A2A 这类企业级 Agent 互联协议之间的关系。这篇博文我想干一件事：把“多 Agent 协作到底靠什么”这个问题拆开，先看 Codex 内部是怎么组织一次复杂任务执行的，再给出一套从安装、配置到接入第三方模型的完整实操方案，最后延伸到 A2A 协议，聊聊企业服务场景下多 Agent 互联的规范和落地思路。

内容划分得很明确：想搞懂原理的人，重点看 Codex 的运行循环和协作要素；正在配置 Codex、经常遇到各种报错的人，可以直接跳到实操章节抄作业；做技术选型或者准备引入 Agent 服务的人，A2A 那部分值得认真读。我尽量用大白话把概念讲清楚，也会穿插一些自己踩过的坑和验证过的配置方案。

1. 多 Agent 协作的本质：单模型解决不了的事，才需要一群 Agent

1.1 从“一个 Agent 干活”到“一群 Agent 分工”

先说个很直接的观察：很多人以为多 Agent 协作是因为模型不够聪明，换一个更强的模型就行了。其实不完全是这样。单个模型即使能力再强，也受限于上下文窗口长度、单次推理深度和工具链的调用复杂度。你让一个模型一晚上把十几个文件改完、跑完测试、再写文档，它大概率在中间某个环节就把上下文“忘”了，或者因为任务太长而失去控制。

多 Agent 协作解决的不是“模型笨不笨”的问题，而是“工作怎么组织”的问题。就像一个人单兵作战和一个小团队协同作战的区别：一个人再厉害，也扛不住需要并行推进、持续验证的大型任务；而一个小组里有人拆需求、有人写代码、有人跑验证，每个人只负责一段清晰的小目标，整体效率和可控性都会好很多。

其实我可以打个更生活化的比方。你请一个全能型助手帮你策划一场线下活动，他既要写方案、又要对接场地、还要管物料清单，干到一半很可能就乱了；但如果你把任务拆给三个人，一个负责方案、一个负责场地、一个负责物料，每个人只盯着自己那一亩三分地，最后再合并结果，事情就清晰得多。多 Agent 协作干的正是这件事：把一个超大任务拆成若干个可独立运行、可验证的子任务，分给不同的 Agent 执行，再通过某种机制汇总结果。

1.2 多 Agent 协作的两种组织方式

目前主流的多 Agent 协作组织方式，总结下来就是两种，我分别说下适用场景。

第一种是编排式，也叫 orchestrator-worker 模式。有一个主控 Agent 负责拆任务、调度和汇总，其余子 Agent 按指令干活，子 Agent 之间一般不直接通信。这种模式优点是流程非常清晰、容易控制和追踪，适合那些步骤固定、目标明确的场景，比如自动化测试、批量数据处理、代码生成后的持续集成流程。缺点也很明显，主控 Agent 容易成为瓶颈，所有信息都汇聚到它那里，上下文压力比较大。

第二种是对等协作式，也叫 peer-to-peer 模式。没有绝对的主控，Agent 之间可以互相发现、协商、分工和交接任务，更像是几个平等的同事在讨论。这种模式适合探索性比较强、需求边界模糊的场景，比如做方案设计、调研分析这类开放性任务。它的缺点是结果不好预测，容易跑偏，需要设计较强的校验机制兜底。

在实际项目里，这两种方式经常混着用。我自己在做企业级 Agent 服务时，倾向于用编排式管住主流程，在个别探索性子任务里放开成对等协作，让几个 Agent 各自独立探索后把结果交回来，再由主控合并去重。这种混合模式在稳定性和灵活性之间找了一个平衡点。

1.3 协作的三大底层要素：任务分解、上下文传递、结果校验

不管用哪种组织方式，多 Agent 协作的底层都绕不开三件事。

第一是任务分解。把一个复杂目标拆成带依赖关系的子任务，这一步决定了整个协作的骨架。分解得好不好，直接影响后续每个 Agent 执行的效率。有个很务实的建议：每个子任务最好控制在“一个 Agent 能在一次会话里完成并验证”的粒度，不要拆到太细，否则 Agent 之间的通信成本会盖过执行收益。

第二是上下文传递。子 Agent 不是凭空干活的，它需要知道自己要做什么、输入是什么、输出给谁、有什么约束。这里就要靠共享状态、消息队列和产物物化来传递上下文。所谓的产物物化，就是把上一个 Agent 的输出落地成文件、数据库记录或标准化消息，而不是靠内存里飘着的变量，这样即使某个节点挂了，整个流程还能恢复。

第三是结果校验。多 Agent 协作最忌讳的就是“各干各的，最后没人检查”。每个子 Agent 的输出都应该有明确的验收标准，比如代码能编译、测试能通过、数据格式合法。没有校验环节的多 Agent 流程，本质上只是在制造混乱。

我见过很多翻车案例，都是因为任务分解做得很粗，上下文靠“口头禅式”的聊天记录传，结果校验干脆没有，最后整个流程跑完根本不知道哪个环节出了问题。协作的可靠性不是靠模型自觉，而是靠机制设计。

2. Codex 内部机制拆解：一个 Agent 是怎么把活干完的

2.1 Codex 到底是什么：CLI 工具、桌面版与它的定位

很多人第一次接触“Codex”这个词，误以为它只是 ChatGPT 内置的一个代码助手。其实 Codex 是 OpenAI 推出的一个独立编程 Agent 工具，提供了命令行版本（CLI）和桌面版应用，定位是“能在你的终端里自主完成编程任务的智能体”。

它和普通代码补全工具最大的区别是：补全工具只在你敲代码时给建议，而 Codex 会自己拆解你给的目标，自主执行命令、读写文件、运行测试，甚至在出错时自己调试并重试。换句话说，它不是一个被动回答问题的模型接口，而是一个具备“计划-执行-观察-修正”闭环的主动智能体。

CLI 版适合研发人员，可以接进现有终端流程里；桌面版更像一个可视化工作台，能看到整个执行过程。我的建议是，初学者先从桌面版入手，界面直观、能看清每一步在干嘛；熟练之后回到 CLI，脚本化和自动化会更方便。

2.2 核心运行循环：Plan → Act → Observe → Repeat

Codex 的内部机制，本质上就是一个经典的 Agent 循环：规划、执行、观察、再规划。

用户给一个目标之后，Codex 会先让模型推理，生成一份行动计划，比如要读取哪些文件、要修改什么、要执行什么命令来验证。然后它进入执行阶段，在沙箱环境中运行命令、编辑文件。执行完它会观察输出，比如查看命令返回结果、读取测试报告、检查文件状态，把这些新信息反馈给模型，让它判断任务是否完成。如果没完成，就进入下一轮规划，做修正和补充。

这个循环看起来简单，却是 Agent 能力和普通模型 API 之间的分水岭。普通模型 API 一次性输入输出就结束了，而 Codex 是一个持续迭代的过程，每一轮执行结果都会成为下一步决策的依据。我在实际使用中感受很明显：给它一个稍微有点复杂的改造任务，它经常要循环五六轮甚至十几轮，期间不断根据报错调整方案，直到所有验证通过。

2.3 沙箱、审批与上下文管理：Codex 避免翻车的手段

强大的自主执行能力意味着风险也大。Codex 为了避免一个 Agent 在系统里乱跑乱改，内置了几层保护机制。

第一层是沙箱。CLI 版在本地执行危险命令时会在隔离环境中运行，系统级操作会被拦截；桌面版同样有沙箱机制，避免 Agent 对系统造成不可逆的破坏。这对应到多 Agent 协作里特别重要：如果每个子 Agent 都能随意改环境，那整个系统就没法稳定运行了，沙箱让每个 Agent 的活动边界变得可控。

第二层是审批。Codex 在默认配置下，遇到敏感操作或者修改关键文件时会向用户请求确认。这个机制在企业场景里尤其有用，相当于一条人工审批闸门，防止 Agent 在无人看管的情况下做出危险动作。实际使用中建议你保留这个控制点，不要为了方便全部放开。

第三层是上下文管理。Codex 在每轮循环中只会把必要的新信息喂回模型，而不是一股脑塞所有历史，这样能在有限上下文窗口内保持核心任务信息不被淹没。这个设计是很多自研 Agent 容易忽视的：上下文不是越长越好，而是越聚焦越好。

2.4 Codex 里的“多 Agent 影子”：子任务、skill 与并发进程

严格来说，Codex 本身默认是一个单 Agent 在工作，但它在架构上已经表现出强烈的多 Agent 协作影子。

最明显的一点是它对复杂任务的处理。当 Codex 接到一个大目标时，它会自己在内部把目标拆成多个可执行子步骤，并在不同轮的循环里专注于不同的子任务，这就相当于用“时间片轮转”的方式模拟了多个职责分离的 Agent。同时，Codex 支持 skill 机制，可以把特定领域的操作流程封装成技能包，按需加载，这种设计很像多 Agent 协作体系里的“专家 Agent”。

社区里也已经出现了基于 Codex 的并发工作流方案，通过同时启动多个 Codex 进程，每个进程处理拆分开的子任务，再用主进程汇总结果。这其实就是把 Codex 这种能力很强的单 Agent，外挂成一个多 Agent 调度系统。我实操下来的体会是：Codex 单实例的闭环能力已经足够胜任大多数任务，真正需要多实例并发的场景通常是大规模改造，那时候调度和汇总的复杂度会明显上升。

3. 实操：装好 Codex、接上 DeepSeek，跑通第一个任务

3.1 安装与初始化：五分钟起跑

先说 CLI 的安装方式。我的环境是 macOS，直接用 npm 全局安装就行，如果你已经配好 Node.js，一条命令就解决：

npm install -g @openai/codex

安装完成后，需要给 Codex 配置认证信息。它默认会找环境变量里的 API 密钥，也可以写在配置文件里。我建议用配置文件方式管理，因为接第三方模型时还要改模型地址，集中管理会省心很多。Codex 的配置文件在~/.codex/config.toml，没有就自己创建一个。

桌面版直接从官网下载对应系统的安装包即可，安装过程没什么特殊之处。需要注意的是，桌面版和 CLI 版读取的是同一套配置目录，所以你在 CLI 里配好的模型和密钥，桌面版基本也能用，这是减少重复折腾的好办法。

3.2 接入第三方模型的两种姿势：改 base_url 与用 CC Switch

Codex 默认连接 OpenAI 的服务。但实际项目里，我们经常需要接入其他模型服务商，比如 DeepSeek。社区里最常用的方案有两种。

第一种是直接改配置。在~/.codex/config.toml里配置一个自定义模型提供商，把 base_url 指向 DeepSeek 的接口地址，再把 API 密钥环境变量设置好。我验证过一套可用的配置，核心内容是这样：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

这里面wire_api = "chat"是关键。Codex 默认走的是 responses 接口协议，但很多第三方模型服务商提供的是 chat completions 格式，这里必须按实际接口格式来选。你如果用 DeepSeek，就设成 chat；如果接的服务商提供了兼容 responses 的接口，再设成 responses。接错协议格式会直接导致请求失败。

第二种是借助 CC Switch。CC Switch 是一个社区里的模型切换管理工具，用来统一管理不同模型服务商的接入配置，减少手动改配置文件的次数。它本质上是一个本地配置整理器，把各家模型的地址、密钥、格式管理在一个界面上，Codex 读取它生成的配置即可。很多报错的根源不在 Codex 本身，而是 CC Switch 生成的配置和 Codex 的预期对不上，这点后面细说。

3.3 “cc switch local proxy failed”排查：报错为什么会发生

这个报错被动辄碰到，完整信息是：

cc switch local proxy failed while handling codex endpoint /responses. provider ...

我第一次看到也懵了一下。这里需要先解释一下“local proxy”的含义：它指的是 CC Switch 在本机启动的一个本地 API 转发服务，作用是把 Codex 发出的请求转发到你所选的模型服务商地址。这个转发服务本身是一个普通的开发调试组件，不属于任何网络工具。当报错说 “local proxy failed”，意思是这个本地转发服务在处理 Codex 发往/responses路径的请求时失败了。

我给你一个排查链路，按顺序走基本能定位。

第一步，确认 CC Switch 的本地转发服务是否正常启动。很多时候是服务没起来，或者崩溃了，重新启动一下就好。

第二步，确认端口没有被占用。CC Switch 默认会监听某个本地端口，如果端口被其他服务占用了，转发就会失败，改一个端口即可。

第三步，确认你选的模型提供商配置是否正确。这里最容易出问题的是接口格式不匹配。比如你在 CC Switch 里选了只支持 chat 格式的服务商，但 Codex 仍然按 responses 格式去请求，转发服务就会报错。解决方案是确认服务商是否提供 responses 兼容接口，没有的话就用 wire_api = "chat" 的配置路径。

第四步，确认 API 密钥是否有效。密钥无效时，转发服务会收到鉴权错误，同样表现为转发失败。特别是刚换了模型服务商，旧的密钥失效了没注意，这个问题很常见。

你可以先用 curl 手动请求一次模型接口，确认密钥和地址本身没问题，再让 Codex 走一遍，这样能把问题快速定位在“配置层”还是“服务层”。

3.4 其他三个高频报错速查

除了 CC Switch 的转发报错，Codex 配置过程中还有几个高频报错，我整理成速查表：

这里我想重点提示一下认证方式。如果你用的是 ChatGPT 账号体系，Codex 的认证逻辑和模型可选范围都会受限，带gpt-5.6-sol这类报错就是典型表现。如果你希望更自由地切换模型，建议直接改用 API 密钥方式对接模型服务商，这样配置和权限控制都更透明，也更适合企业里的集中管理。

配套命令上，验证密钥是否生效我一般用：

export DEEPSEEK_API_KEY="your-key-here" curl -X POST "https://api.deepseek.com/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hello"}]}'

能正常返回，再回过头检查 Codex 的配置。

4. 从 Codex 走向 A2A：企业级多 Agent 服务协议到底规范了什么

4.1 A2A 出现的背景：Agent 孤岛与互操作需求

讲完 Codex 这种单智能体工具的实操，我们把视野放到企业级场景。企业里一旦开始大规模使用 Agent，很快就会遇到一个尴尬局面：A 团队用 Codex 做代码任务，B 团队用一个自研 Agent 做数据处理，C 团队采购了某厂商的客服 Agent，它们各自都很好用，但彼此之间完全没法协作，因为每个 Agent 的接口、数据格式、交互方式都是自己定义的。这就是所谓的 Agent 孤岛。

A2A 协议就是为了解决这个问题而出现的，全称是 Agent2Agent。它在 2025 年发布，目标很明确：为不同厂商、不同团队开发的 Agent 提供一套统一的通信和协作标准，让它们能够互相发现、交互和协同完成任务。项目后来由 Linux 基金会托管，意味着它走的是开放中立路线，不绑定某一家云厂商。

这对企业服务来说意义很大。过去你想让两个 Agent 协作，得为它们写专用的适配器，每接一个新的 Agent 就要再写一套胶水代码，成本极高。有了统一协议之后，理论上任何符合规范的 Agent 都能互相协作，就像不同品牌的 USB 设备插到标准接口上就能用一样。

4.2 A2A 的核心对象：Agent Card、Task、Message、Artifact

A2A 协议定义了四个核心对象，理解它们你就能看懂协议的大半。

Agent Card 相当于每个 Agent 的“名片”，声明这个 Agent 叫什么、能做什么、接收什么输入、返回什么格式。其他 Agent 拿到这张卡片就能判断“这个活该不该找它”以及“怎么找它”。

Task 是协议里的任务单元，描述一个 Agent 需要完成的某件事。Task 有完整的生命周期，包括提交、执行中、等待补充输入、完成、取消、失败等状态。对比着看，Codex 的一轮轮循环其实也是在维护一个隐性任务状态机，只是它是内部的；而 A2A 把这个状态机标准化成可对外通信的协议。

Message 是 Agent 之间传递的消息，包含发送方、接收方、内容和格式声明。Artifact 是任务执行产生的产物，比如文件、代码片段、数据结果。Artifact 是可以被其他 Agent 引用的，这就解决了我在第一章强调的“结果校验”和“产物物化”问题。

你可以这样理解：如果把多个 Agent 协作比作一个项目组，Agent Card 是简历，Task 是任务书，Message 是工作沟通记录，Artifact 是交付物。这四样东西齐了，协作就有了基础。

4.3 A2A 的工作流：发现能力、委托任务、流式返回

A2A 协议下，一次典型的跨 Agent 协作是这样走通的。

首先是发现。一个 Agent 需要帮助时，通过 Agent Card 目录查询其他 Agent 的能力，找到合适的协作对象。这一步很关键，相当于让 Agent 具备“知道谁能干什么”的能力，而不是非要人工提前写死协作链路。

然后就是委托任务。请求方创建一个 Task，附上任务说明和必要数据，发给目标 Agent。目标 Agent 接收后会更新 Task 状态，开始执行。执行过程中如果需要更多信息，它会通过消息请求补充输入，双方完成多轮交互。这和我们人类协作里“我去问一下需求细节”是一个道理。

最后是流式返回。目标 Agent 在完成过程中以流式方式持续推送状态更新和部分产物，而不是等全部做完才一次性返回。这对于耗时比较长的 Agent 任务来说体验差异巨大，请求方可以实时感知进度，也能在早期发现任务可能跑偏，及时介入修正。

4.4 企业落地怎么看：A2A 与 Codex 式智能体如何配合

聊到落地，我给一个清晰的判断框架：Codex 这种工具解决的是“单个 Agent 如何把活干好”，A2A 解决的是“多个 Agent 之间如何握手协作”。两者不只是替代关系，更像内功和招式的配合——Codex 能把内部执行做好，而 A2A 能让这些 Agent 与企业里其他系统、其他厂商的 Agent 形成协作网络。

企业在做技术选型时，我建议先小步试点。可以从一个最小的场景切入，比如让现有平台团队的一两个 Agent 通过 A2A 协议接入到企业内部的 Agent 注册目录里，跑通一个跨团队的自动化流程。先验证：Agent 卡片的发现机制好不好用、任务状态同步是否顺畅、异常恢复是否可控。小范围跑顺了再逐步扩大接入范围。

还有一个容易被忽略的点：治理和安全边界。多 Agent 协作一旦跨出单个团队，就必须有明确的权限模型。A2A 本身定义了消息格式和交互流程，但企业落地还要结合自己的身份认证和审计体系，确保一个 Agent 不能随便调用另一个 Agent 的危险能力。说白了，规范解决了“听得懂”的问题，但“能不能做这件事”要靠企业管理层去约束。

5. 高频报错速查表与我的配置心得

5.1 报错速查表

这一节我把前面零散提到的报错汇总成一张表，方便你直接对着排查。

5.2 我的几条配置心得与避坑经验

这些经验都是在实际项目里折腾出来的，写出来给你避坑。

第一，先跑通最小闭环再接复杂工具。我的习惯是：刚装好 Codex 时，先只用官方默认配置跑一个最简单的任务，比如让它创建一个 Python 脚本，确认整个链路是通的。然后再去动模型接入、再上 CC Switch。很多人一上来就同时改模型、改代理配置、改工作目录，出了问题根本分不清是哪一层的问题，这是浪费时间的最大来源。

第二，配置文件一定要纳入版本管理。~/.codex/config.toml里包含模型地址、密钥引用、默认参数，这些都是环境的关键信息。我建议把它加到团队的仓库里，至少要有注释清晰的模板。我踩过一次坑：本地配置跑得很顺，换了一台机器重新配，发现漏了一个环境变量，整整卡了半天。

第三，沙箱不要随便关。有人觉得 Codex 每步都问很烦，就把审批和沙箱全关了，让 Agent 全自动跑。短时间看确实高效，但一旦 Agent 改错一个配置文件或者执行了一条危险命令，代价远大于手动确认几秒钟的成本。我的做法是保留审批，只在明确可信的任务里临时放宽。

第四，注意 token 消耗。Codex 这种带计划-执行-观察循环的 Agent，调用量远大于单次问答。跑一个复杂任务可能消耗大量 token。特别是接第三方模型时，你选的模型规格决定了单次调用的成本，建议先用小体量模型验证流程，确认可靠了再切换强大模型。

第五，不要盲改模型名。很多报错都是因为配置文件里的模型名和模型服务商实际支持的名字不一致。你配 DeepSeek 就写 DeepSeek 开放接口里真实存在的模型名，配其他服务商也一样，先查文档再填配置，别拍脑袋写一个看起来像的。

最后说一点我对多 Agent 协作的体会。工具和协议都在快速演进，但核心问题从来不是谁的 Agent 更多、谁的工具更花哨，而是任务分解是否清晰、上下文的传递是否可靠、结果有没有被认真校验。Codex 让我看到单智能体闭环能做到什么程度，A2A 让我看到跨 Agent 协作该往什么方向走。对我们做技术和做架构的人来说，把这两件事想明白，比追着新工具跑要重要得多。