最近折腾多 Agent 协作的人应该都被 Codex 刷屏了。作为一个既玩过多智能体框架、又在企业项目里落地过 Agent 服务的从业者我对这个工具的走红并不意外但我更关注的是它背后的协作机制以及它和 A2A 这类企业级 Agent 互联协议之间的关系。这篇博文我想干一件事把“多 Agent 协作到底靠什么”这个问题拆开先看 Codex 内部是怎么组织一次复杂任务执行的再给出一套从安装、配置到接入第三方模型的完整实操方案最后延伸到 A2A 协议聊聊企业服务场景下多 Agent 互联的规范和落地思路。内容划分得很明确想搞懂原理的人重点看 Codex 的运行循环和协作要素正在配置 Codex、经常遇到各种报错的人可以直接跳到实操章节抄作业做技术选型或者准备引入 Agent 服务的人A2A 那部分值得认真读。我尽量用大白话把概念讲清楚也会穿插一些自己踩过的坑和验证过的配置方案。1. 多 Agent 协作的本质单模型解决不了的事才需要一群 Agent1.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 → RepeatCodex 的内部机制本质上就是一个经典的 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 SwitchCodex 默认连接 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 配置过程中还有几个高频报错我整理成速查表报错信息原因解法auth token is unavailable没有设置 API 密钥或密钥读取失败检查env_key对应的环境变量是否正确设置重启终端再试the gpt-5.6-sol model is not supported when using codex with a chatgpt account使用 ChatGPT 账号直连时Codex 只允许官方指定模型第三方/私人配置的模型名不被支持换成配置好的第三方模型提供商或使用官方已开放的模型名codex is ignoring 1 unrecognized configuration settingconfig.toml里写了未知配置项检查配置项拼写参考 Codex 文档逐项比对清理这里我想重点提示一下认证方式。如果你用的是 ChatGPT 账号体系Codex 的认证逻辑和模型可选范围都会受限带gpt-5.6-sol这类报错就是典型表现。如果你希望更自由地切换模型建议直接改用 API 密钥方式对接模型服务商这样配置和权限控制都更透明也更适合企业里的集中管理。配套命令上验证密钥是否生效我一般用export DEEPSEEK_API_KEYyour-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、ArtifactA2A 协议定义了四个核心对象理解它们你就能看懂协议的大半。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 报错速查表这一节我把前面零散提到的报错汇总成一张表方便你直接对着排查。报错或现象最常见原因操作顺序cc switch local proxy failed while handling codex endpoint /responsesCC Switch 本地转发服务未启动、端口占用、接口格式不匹配先重启转发服务再查端口和密钥最后核对接口格式auth token is unavailable密钥没设置或环境变量没加载确认env_key对应变量重启终端the gpt-5.6-sol model is not supported...认证方式和模型不匹配改用第三方模型提供商配置codex is ignoring N unrecognized configuration setting配置项拼写或字段错误逐个比对配置文档清理未知字段刚配置完模型但请求全部超时base_url 填错或网络不通用 curl 手动请求模型接口验证5.2 我的几条配置心得与避坑经验这些经验都是在实际项目里折腾出来的写出来给你避坑。第一先跑通最小闭环再接复杂工具。我的习惯是刚装好 Codex 时先只用官方默认配置跑一个最简单的任务比如让它创建一个 Python 脚本确认整个链路是通的。然后再去动模型接入、再上 CC Switch。很多人一上来就同时改模型、改代理配置、改工作目录出了问题根本分不清是哪一层的问题这是浪费时间的最大来源。第二配置文件一定要纳入版本管理。~/.codex/config.toml里包含模型地址、密钥引用、默认参数这些都是环境的关键信息。我建议把它加到团队的仓库里至少要有注释清晰的模板。我踩过一次坑本地配置跑得很顺换了一台机器重新配发现漏了一个环境变量整整卡了半天。第三沙箱不要随便关。有人觉得 Codex 每步都问很烦就把审批和沙箱全关了让 Agent 全自动跑。短时间看确实高效但一旦 Agent 改错一个配置文件或者执行了一条危险命令代价远大于手动确认几秒钟的成本。我的做法是保留审批只在明确可信的任务里临时放宽。第四注意 token 消耗。Codex 这种带计划-执行-观察循环的 Agent调用量远大于单次问答。跑一个复杂任务可能消耗大量 token。特别是接第三方模型时你选的模型规格决定了单次调用的成本建议先用小体量模型验证流程确认可靠了再切换强大模型。第五不要盲改模型名。很多报错都是因为配置文件里的模型名和模型服务商实际支持的名字不一致。你配 DeepSeek 就写 DeepSeek 开放接口里真实存在的模型名配其他服务商也一样先查文档再填配置别拍脑袋写一个看起来像的。最后说一点我对多 Agent 协作的体会。工具和协议都在快速演进但核心问题从来不是谁的 Agent 更多、谁的工具更花哨而是任务分解是否清晰、上下文的传递是否可靠、结果有没有被认真校验。Codex 让我看到单智能体闭环能做到什么程度A2A 让我看到跨 Agent 协作该往什么方向走。对我们做技术和做架构的人来说把这两件事想明白比追着新工具跑要重要得多。