多 Agent 协作到底靠什么这个问题我在不同团队里被反复问起。有人说是模型能力有人说是提示词工程但真正从 Codex 的日常使用到 A2A 企业协议的落地我得出的结论是单点的 Agent 机制是地基通信协议是骨架编排与治理才是让多 Agent 真正协作起来的关键。这篇文章就沿着这三层展开先拆 Codex 内部的工作机制再讲多 Agent 协作的架构选择然后解读 A2A 协议在企业服务中的价值最后附上 Codex 配置与排障的完整实操记录。适合正在做 Agent 开发、想用 Codex 提效、或者准备在企业里搞多 Agent 平台的读者。1. 单点能力是地基Codex 内部机制到底解决了什么问题1.1 从“能聊天”到“能干活”Agent 的关键是闭环很多人分不清“聊天机器人”和“Agent”的区别。举个例子你就懂了。你让普通 ChatGPT“看看这个项目的 bug 在哪”它能做的只有一件事读你贴进去的代码片段然后凭经验猜。但 Codex 不一样你把它启动在项目目录里它自己会去读配置文件、翻源代码、跑测试、看报错日志改完代码后还会再跑一遍验证。这个闭环——感知、决策、行动、验证——就是 Agent 和聊天机器人的本质差异。Codex 的底层其实不是一个模型而是一个“循环”。每个循环里模型先决定下一步动作比如“读取 config 文件”或“执行 npm test”然后 Codex 的运行时把这个动作翻译成真实的 shell 命令或文件操作执行后把结果喂回上下文模型再根据新信息调整计划。这个过程不断迭代直到任务完成或者需要人工介入。这个设计里最值得注意的是“权限”和“验证”的平衡。Codex 默认是半自动模式它执行 shell 命令和修改文件之前都会要求你确认一次。这就是所谓的“人在环上”设计。你可以把确认全部关掉让它完全自主但说实话遇到删表、强制推送这类破坏性命令的时候保留一档确认能救你一命。1.2 Codex 落地所需的四大核心机制拆开看Codex 能干活靠四件事第一项目上下文的自动注入。Codex 启动时会读取项目根目录的 AGENTS.md 文件。这个文件是给 Agent 看的“操作手册”你可以写上“本项目用 pnpm 不用 npm”“改前端代码前必须跑 lint”“数据库迁移脚本在 db/migrations 目录下”。这些指令会注入到每次会话的系统提示词里Agent 就不会犯低级错误。第二工具调用层。Codex 内置了读写文件、执行 shell 命令、列目录、访问网络等工具通过函数调用来驱动。它相当于给模型配了一套“手”。没有这层工具调用模型再聪明也只能回答不能干活。第三会话与状态管理。Codex 会把整个操作历史保留在上下文里长任务拆成多轮每轮的结果都会成为下一轮的输入。它还有断点续跑能力中断之后能接着原会话继续不会从头再来。第四外部工具的组合能力。通过 MCP 协议Codex 可以连接外部数据源、API、知识库。MCP 就像是给 Agent 开了一座“插座”插上不同的工具它就多一项技能。比如接上数据库的 MCPAgent 就能直接查表结构接上 Jira 的 MCP它就能拉取工单信息。这里多说一句 AGENTS.md。很多团队用不出效果是因为写得敷衍。如果你只写“好好写代码”Agent 基本等于没引导。我通常会在 AGENTS.md 里写清楚编码规范、禁止事项、常用命令、测试要求。比如“提交代码前必须通过 pnpm lint 和全部单测”。规则越具体Agent 越像熟悉团队规矩的老同事犯错的概率成倍降低。1.3 单 Agent 的天花板为什么我们需要协作Codex 单用已经很能打了但单 Agent 有明确的天花板。首先是上下文窗口的物理限制。一个大型项目的全部信息根本塞不进一次上下文单 Agent 处理复杂代码库时会出现“记了这头忘了那头”。其次是角色固化问题。一个 Agent 很难同时当好“写代码的”和“审代码的”让它写代码时思路活跃让它审视自己的产出时又容易惯性认同。第三是没有并行能力。一个长任务只能串行推进不能在多个方向上同时调查。所以行业里开始搞多 Agent。但多 Agent 协作不是“把任务丢给多个 Agent 各干各的”而是需要一套完整的协作规则。这套规则才是真正决定协作质量的东西。2. 多 Agent 协作的三种架构与协作三板斧2.1 编排者模式、流水线模式、协商模式怎么选多 Agent 协作的架构目前主流有三类各自适用的场景差别很大。**编排者模式Orchestrator-Worker**是目前最常见的一种。一个主导 Agent 当“项目经理”负责拆解任务、分配任务、汇总结果多个工作 Agent 当“执行者”各自认领一块任务。优点是好控制、职责清晰、容易对齐进度缺点是主导 Agent 容易成为瓶颈任务量一上来它处理不了那么多上下文。**流水线模式Pipeline**适合流程化的任务比如数据分析场景一个 Agent 负责拉取数据一个负责清洗一个负责建模一个负责出报告。每个环节只做一件事做完交给下家。优点是结构简单、性能好、每个 Agent 的上下文负担小缺点是一旦中间环节出错整条流水线都得回退。**协商模式Swarm**是自由度最高也最难落地的。多个 Agent 地位平等没有统一指挥官靠互相沟通、协商、投票来推进任务。优点是灵活性高、能处理复杂的开放性问题缺点是结果不可控、调试极其困难现阶段大多停留在实验阶段。对企业落地我的建议很直接先做编排者模式。它最容易实现也最容易在出问题时定位责任。等跑顺了再把某些子流程改成流水线模式做并行优化。2.2 协作三板斧之一角色分工多 Agent 协作最容易忽略的是“角色设计”。这里的角色不是简单改个 System Prompt 的称呼而是要给每个 Agent 配置不同的工具集、不同的上下文范围、不同的决策权限。举个例子一个写代码的多 Agent 团队至少要有三个角色规划者负责拆任务、排优先级、执行者负责写代码、评审者负责代码审查和测试。规划者不需要有写代码的工具权限评审者要有跑测试的权限但没有改代码的权限。这样设计的好处很明显——权限即角色能力边界清晰出了问题不会被推诿成“Agent 自己乱改了一通”。角色分工还有一个容易被忽略的维度不同 Agent 用不同模型。规划者可以用思考能力强的模型执行者可以用写代码强的模型评审者可以用擅长挑错的模型。不要再把所有 Agent 绑死在同一个模型上成本高而且效果不是最优。2.3 协作三板斧之二通信协议角色分配好了Agent 之间怎么说话这是第二个核心问题。目前主流的通信方式有两类一类是“共享上下文”模式。所有 Agent 把状态写到一个共享空间比如同一个文件、同一个消息队列通过读写这个空间来获取彼此的进展。这种方式实现简单适合少量 Agent 的场景但 Agent 一多共享空间就会变成一团乱麻读写冲突不断。另一类是“标准化协议”模式。Agent 之间通过明文定义的协议消息来沟通比如“任务请求”“进度回报”“结果交付”。每个消息有确定的格式和语义接收方程序化解析处理。这就是 A2A 协议做的事情后面会详细展开。我的经验是两三个 Agent 的小团队共享上下文就够了超过五个 Agent不上协议一定乱。别高估 Agent 的“心智化能力”它们不是人不会默契配合一切沟通都需要显式的、结构化的约定。2.4 协作三板斧之三共享状态与记忆第三个关键问题是记忆。多 Agent 协作最大的坑是每个 Agent 都只有自己对话窗口里的那点信息彼此不共享上下文。结果就是 A 改了配置B 不知道C 修了接口D 还按旧参数写代码。解决思路是建立一个“团队级记忆层”。常见做法是把任务状态、变更记录、决策日志都写到外部存储里每个 Agent 在关键节点强制读取和更新。Git 仓库本身就可以当这个记忆层每个 Agent 改动后提交其他人拉最新代码再开工天然解决了一部分上下文不同步的问题。还有一个技巧是“结构化汇报”。要求每个 Agent 在完成任务后用固定格式输出做了什么、改了哪些文件、有没有测试、还有哪些待办。这样一来后续 Agent 不必重新读全部历史只需要扫一眼汇报就能接上手。这个习惯能省掉你一半以上的多 Agent 调试时间。3. A2A 协议拆解企业级 Agent 互通的“普通话”3.1 A2A 要解决什么问题聊完架构和协作三板斧你会发现一个尴尬的事实上面说的协作方式都是“家规”每个团队自己一套。你家的 Agent 用 JSON 文件通信我家的用消息队列两边要协作怎么办这就是 A2A 协议出现的意义。A2AAgent2Agent是 Google 联合五十多家合作伙伴推出的开放协议目的非常朴素——给不同的 Agent 定一套通用的“普通话”让它们不管底层用什么模型、哪个厂商的框架都能互相发现、互相调用、互相交付结果。你不需要知道对面的 Agent 是什么技术栈实现的只要它宣称支持 A2A你就能跟它协作。这个标准化动作在企业服务里的价值被严重低估了。企业内部往往有几十个系统每个系统将来都可能有一个或多个 Agent 在服务。如果每个 Agent 都用自己的私有接口集成成本是指数级增长的。A2A 的价值就是把“点对点集成”变成“接上协议即可对话”。3.2 四大核心概念Agent Card、Task、Artifact、InteractionA2A 协议的核心概念只有四个理解它们就等于掌握了协议的主干。Agent Card相当于 Agent 的“名片”。它是一个 JSON 文件描述了 Agent 的名称、能力、接口地址、认证方式。客户端拿到 Agent Card就能知道这个 Agent 能干什么、怎么调用。这跟微服务架构里的服务注册中心逻辑很像只不过注册的是 Agent 而不是微服务。Task是工作单元。一个 Agent 调用另一个 Agent本质上是创建了一个 Task。Task 有完整的生命周期submitted、working、input-required、completed、failed、canceled。这个模型保证了“长任务”可以被追踪和恢复不会因为连接中断就丢失进度。Artifact是任务产出物。Task 执行完产生的结果以 Artifact 的形式交付可以是文本、文件、结构化数据。Artifact 有明确的元数据比如文件名、类型、大小方便后续 Agent 识别和使用。Interaction是消息交换的载体。A2A 基于 JSON-RPC 2.0 通信每条消息有固定的结构和类型。这种结构化消息比“自然语言对话”更适合程序解析也是 A2A 能落地的关键——它不指望两个 Agent 靠“读懂人话”来协作而是靠机器可解析的消息。这四个概念合起来就构成了一套完整的 Agent 协作语义名片Agent Card负责“找对人”任务Task负责“派活”产出物Artifact负责“交活”消息Interaction负责“把话说清楚”。3.3 A2A 和 MCP 到底什么关系很多人分不清 A2A 和 MCP这里一并说清楚。MCPModel Context Protocol解决的是“Agent 调工具”的问题——一个 Agent 要访问数据库、文件系统、外部 API通过 MCP 接入。A2A 解决的是“Agent 调 Agent”的问题——一个 Agent 要把任务转包给另一个 Agent 去完成。用个粗浅的比喻MCP 是给 Agent 装“手”A2A 是给 Agent 配“电话”。前者处理的是人机交互层面上的工具调用后者处理的是机机交互层面上的任务流转。两者层级不同也不冲突。实际落地顺序上我建议先上 MCP 把单个 Agent 的工具生态丰富起来然后再上 A2A 把多个 Agent 串起来。不要一上来就搞 A2AAgent 本身的能力还没建起来通了电话也没活可派。3.4 企业落地的典型场景与注意事项A2A 在企业服务里的落地场景目前最典型的几个跨系统任务编排。比如客服 Agent 发现问题自动创建一个 Task 派给订单系统的 Agent 去查订单状态再派给库存系统的 Agent 查库存最后汇总结果回复客户。整个过程是结构化消息驱动的比让一个 Agent 去调多个系统 API 要干净得多。Agent 能力市集。企业把各个部门沉淀的 Agent 能力通过 Agent Card 暴露出来其他部门只需要“读名片、建任务”就能使用。这相当于把 Agent 变成了企业内部可复用的服务边际成本几乎为零。复杂流程的人机协同。A2A 支持“input-required”状态意味着 Task 在关键节点可以停下来等人处理。这对于需要审批的流程非常合适——Agent 跑完自己的部分挂起任务等人工确认通过后再继续。企业落地 A2A 有三条注意事项都是我见过的真实教训认证授权必须先行。Agent Card 里不写清楚认证方式等于把你企业的能力裸奔在内部网络上。任务超时和重试机制要提前设计。Agent 之间调用跟程序调用不同单个 Agent 可能因为上下文耗尽、模型超时等原因长期无响应你需要超时兜底。日志和可观测性不能省。多 Agent 协作一旦出问题定位难度是单 Agent 的数倍。每个 Task 的流转状态、每次 Interaction 的内容都要留痕。4. 实操Codex CLI 从零配置到位前面讲的都是机制层面的东西这一节我们回到 Codex 本身把环境配置和第三方模型接入的完整流程跑一遍。这部分是我最近实操最多的地方踩过的坑全部记录下来。4.1 安装 Codex CLI 与登录初始化Codex CLI 的安装方式比较直接前提是你本机已经有 Node.js 环境。安装命令本质上是拉取 npm 包装完之后运行一次版本检查确认安装成功。装好之后最关键的一步是登录Codex 需要认证才能调用模型服务。如果你遇到“codex auth token is unavailable”之类的报错基本就是认证缺失或者 token 失效了。解决思路很固定重新走一遍登录流程让它重新写入认证凭据。登录成功后Codex 会在用户目录下生成配置文件也就是我们接下来要重点折腾的 config.toml。4.2 config.toml 核心配置详解Codex 的行为配置集中在 config.toml 里。这个 TOML 文件是 Codex 的“总开关”从默认模型、审批策略到自定义 Provider 全在这里。# ~/.codex/config.toml model gpt-5.4 model_provider openai approval_policy on-request最上面三行是三个最常用的全局配置model指定默认模型model_provider指定使用哪一家服务商approval_policy控制审批策略。on-request表示关键操作需要确认如果改成never就完全自动执行。刚上手不要用neverCareful 一点没有坏处。自定义 Provider 的配置块长这样[model_providers.openai] name OpenAI base_url https://api.openai.com env_key OPENAI_API_KEY wire_api responses这里的wire_api有两个可选值responses和chat。responses对应 OpenAI 新一代的 Responses APIchat对应传统的 Chat Completions 接口。对接第三方服务商时这个字段经常是成败的关键后面会重点讲。4.3 接入 DeepSeek 等第三方模型 ProviderCodex 的好处是支持自定义 Provider因此可以接入 DeepSeek 这类兼容 OpenAI 接口格式的第三方模型服务。我实际配置过流程很简单核心就是三个字段的组合。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配置好之后需要先设置环境变量DEEPSEEK_API_KEY指向你从服务商那里申请的密钥然后启动 Codex它会自动读取配置并连到 DeepSeek 的接口上。这里要特别提醒一个容易翻车的地方wire_api必须和服务商实际支持的接口格式匹配。DeepSeek 目前兼容的是 OpenAI 的 Chat Completions 格式所以wire_api一定要填chat如果你照抄 OpenAI 的配置填了responses调用时会直接报错最常见的提示就是“model not supported”或者请求格式不匹配。另外并非所有模型都支持 Codex 的全部能力。Codex 的很多功能是和模型能力绑定在一起的比如函数调用、长上下文、特定输出格式。接入第三方模型时如果发现 Agent 的某些行为不正常先别怀疑配置去查一下这个模型对函数调用的支持程度。4.4 本地 API 网关工具ccswitch的配置与避坑很多人为了让 Codex 在不同模型服务商之间灵活切换会引入本地 API 路由网关类的工具这类工具的作用是在本地起一个代理端点Codex 的请求先发到本地再由工具转发到你配置的目标服务商。它本质上是一个“流量分发层”配置管理多个服务商的密钥和路由规则。这类工具用得多了最典型的一个报错是cc switch local proxy failed while handling codex endpoint /responses. provided basic auth token is empty.这个报错的信息量挺大。/responses是 OpenAI Responses API 的端点路径说明 Codex 正在按responses格式发起请求而工具在转发时发现认证信息是空的。出现这种情况优先排查三件事本地网关是否处于启动状态。很多时候是工具没启动Codex 请求打到本地点不通。配置里目标 Provider 的 API Key 是否存在。认证书为空大概率是环境变量没加载。wire_api配置是否匹配。如果你的目标是接 DeepSeek但 Codex 侧还配置成responses网关转发时就会找不到对应的端点处理逻辑。从我踩坑的经验看这类本地网关问题九成是配置组合不一致导致的而不是工具本身坏了。排查思路就是顺着请求链路一步步走Codex 发出什么格式的请求 → 网关按什么规则转发 → 目标服务商认不认这套格式。5. 高频报错排查实录Codex 跑不起来怎么办5.1 高频报错速查表把这段时间我遇到的高频报错整理成一个速查表照着排查能省很多时间。报错信息根本原因解决方案codex auth token is unavailable登录凭据缺失或过期重新执行登录流程刷新 tokenthe gpt-5.6-sol model is not supported when using codex with a chatgpt account当前账号套餐不支持该模型换用账号支持的模型或升级套餐unrecognized configuration settingconfig.toml 里有拼写错误或不支持的配置项对照官方文档核对配置项拼写local proxy failed while handling codex endpoint /responses本地网关转发失败或认证信息为空检查网关状态、API Key、wire_api 组合model not supported模型名写错或服务商不支持确认模型 ID 与文档一致检查 Provider 的型号列表connection refused本地端口占用或网关未启动重启网关确认端口监听正常5.2 排查模型适配问题的完整思路围绕“模型不支持”这类报错我想展开多说几句。很多新手看到 model not supported 就以为模型不支持实际上根因往往不是模型本身而是配置链路里的某个环节不匹配。完整排查思路应该是四步走。第一步确认模型名称跟服务商文档里的一致——不少服务商为了贴近 OpenAI 生态会提供兼容别名但别名不等于正式模型 ID。第二步确认账号权限——有些模型只在特定套餐下开放比如报错里提到的 gpt-5.6-sol就是账号类型和模型不匹配的典型场景。第三步检查 wire_api——请求走 Responses 还是 Chat Completions服务商支持哪套两边必须对齐。第四步看请求日志——把 Codex 实际发出的请求打到本地日志里看是 URL 不对、格式不对还是认证不对一目了然。5.3 从单 Agent 到多 Agent 的落地路径建议最后聊点从工具使用到方案落地的经验。如果你看完前面的内容准备从单 Agent 往多 Agent 走我给你一个稳妥的路径参考第一阶段把单个 Codex 用好。先把 AGENTS.md 写好、审批策略定明白、第三方模型接入跑通让它稳定产出。单 Agent 还没有稳定之前不要碰多 Agent——地基不牢上层一定塌。第二阶段用两三个 Agent 做角色分工实验。比如让一个 Codex 写代码另一个负责审查和补充测试中间用 Git 分支隔离工作区。这个阶段你会真正感受到“通信协议”和“共享状态”两个问题的紧迫性。第三阶段引入协议标准化。如果你的 Agent 数量超过五个或者涉及不同系统的能力调用这时候就值得引入 A2A 或者类似的机制了。把每个 Agent 的能力用 Agent Card 暴露出来任务流转用标准化的 Task 语义整个系统的可维护性会上一个台阶。我个人在实际操作中最深刻的体会是多 Agent 协作不是技术问题而是组织问题。你把角色、协议、状态管理三个层面的规则定清楚协作自然顺规则模棱两可模型再强也白搭。Codex 单点再能打也只是多 Agent 棋盘上的一个强力棋子真正决定胜负的是你给这些棋子设定的协作秩序。