多 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 开了一座“插座”，插上不同的工具它就多一项技能。比如接上数据库的 MCP，Agent 就能直接查表结构；接上 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 协议出现的意义。
A2A（Agent2Agent）是 Google 联合五十多家合作伙伴推出的开放协议，目的非常朴素——给不同的 Agent 定一套通用的“普通话”，让它们不管底层用什么模型、哪个厂商的框架，都能互相发现、互相调用、互相交付结果。你不需要知道对面的 Agent 是什么技术栈实现的，只要它宣称支持 A2A，你就能跟它协作。
这个标准化动作在企业服务里的价值被严重低估了。企业内部往往有几十个系统，每个系统将来都可能有一个或多个 Agent 在服务。如果每个 Agent 都用自己的私有接口，集成成本是指数级增长的。A2A 的价值，就是把“点对点集成”变成“接上协议即可对话”。
3.2 四大核心概念：Agent Card、Task、Artifact、Interaction
A2A 协议的核心概念只有四个，理解它们就等于掌握了协议的主干。
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，这里一并说清楚。MCP（Model Context Protocol）解决的是“Agent 调工具”的问题——一个 Agent 要访问数据库、文件系统、外部 API，通过 MCP 接入。A2A 解决的是“Agent 调 Agent”的问题——一个 Agent 要把任务转包给另一个 Agent 去完成。
用个粗浅的比喻：MCP 是给 Agent 装“手”，A2A 是给 Agent 配“电话”。前者处理的是人机交互层面上的工具调用，后者处理的是机机交互层面上的任务流转。两者层级不同，也不冲突。
实际落地顺序上，我建议先上 MCP 把单个 Agent 的工具生态丰富起来，然后再上 A2A 把多个 Agent 串起来。不要一上来就搞 A2A，Agent 本身的能力还没建起来，通了电话也没活可派。
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就完全自动执行。刚上手不要用never，Careful 一点没有坏处。
自定义 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 API，chat对应传统的 Chat Completions 接口。对接第三方服务商时，这个字段经常是成败的关键，后面会重点讲。
4.3 接入 DeepSeek 等第三方模型 Provider
Codex 的好处是支持自定义 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 | 登录凭据缺失或过期 | 重新执行登录流程，刷新 token |
| the 'gpt-5.6-sol' model is not supported when using codex with a chatgpt account | 当前账号套餐不支持该模型 | 换用账号支持的模型，或升级套餐 |
| unrecognized configuration setting | config.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 棋盘上的一个强力棋子，真正决定胜负的，是你给这些棋子设定的协作秩序。
