企业官网建设流程全解析

1. 多 Agent 协作到底在解决什么问题？

先把话说在前面：把几个聊天窗口同时打开，互相贴来贴去，这不叫多 Agent 协作。真正的多智能体协作，是把一个大目标拆成若干可以独立规划、独立调用工具、独立验收的子任务，再让这些执行单元在一个明确的协议和状态模型下面把结果拼回一个完整交付物。OpenAI Codex 看起来是个编程助手，其实它内部已经跑了一套“任务拆解—逐步执行—结果验证”的循环，很多人直接叫它多智能体工作流的标准样本；而 Google 主导的 A2A（Agent2Agent）协议，则是想把这种协作能力从一个产品内部扩展到跨企业、跨厂商的 Agent 之间。

这篇文章我想系统聊两件事：Codex 这类工具内部是怎么组织多步协作的，以及 A2A 在企业服务里到底解决什么问题。同时我会把最近不少人遇到的 Codex 安装、配置、鉴权和模型不兼容问题一并整理出来，因为这些坑几乎都发生在“多 Agent 协作链路”的关键节点上，跳不过去。

1.1 单智能体的三个硬瓶颈

单个 Agent 看起来能聊天、能写代码、能调用工具，但真正扔给它一个“修完这个项目所有遗留 bug 并补上测试”的任务，它很容易在长链路里跑偏。原因是三个。

第一，上下文容量有限。一个大语言模型的上下文窗口再大，也就那么多 token，代码仓库、任务说明、历史操作记录、外部工具返回结果一旦叠加起来，很快就把窗口占满。你让一个 Agent 记住全程，它记不住，最聪明的做法是让它只关心当前这一步。

第二，工具能力的边界。单个 Agent 如果要同时操纵代码仓库、数据库、CI/CD 流水线、浏览器和内部业务系统，工具权限模型会非常复杂，任何一个工具返回的异常格式都可能中断链路。这也是为什么业界常用的思路不是“一个 Agent 干所有事”，而是“一个主管 Agent 分派，多个专业 Agent 分别干活”。

第三，错误恢复能力差。长链路任务里，越往后执行，前面遗留的小错误就会被放大。单个 Agent 往往缺少“回滚到上一步”“向另一个智能体确认”“把失败结果重新包装后再提交”的能力，最后只能整段重来。

协作的本质，其实就是为了解决这三个问题：拆小任务来绕开上下文限制，用专业分工来降低工具复杂度，用环节之间的反馈和验收来做错误恢复。

1.2 协作的最小闭环：拆分、执行、验证、合并

多 Agent 协作再花哨，落到地面就是四个动作：拆分、执行、验证、合并。

拆分不是简单把一句话变成几段话，而是把一个目标分解成彼此有依赖关系的子任务，并且明确每个子任务的输入、输出和验收标准。执行是每个子任务由一个执行单元负责，它可以调用自己的工具，只维护自己的工作上下文。验证判断这一步的产出是否符合预期，不符合就打回重做，符合才允许进入下一步。合并则是把各个子任务的结果按依赖关系拼装成最终交付物，这里最考验协议设计，因为每个子任务的产出格式、引用路径、状态标记必须能被其他子任务理解。

所有多 Agent 框架，不管名字叫编排器、协调器、主管还是 Routing Agent，底子都是这套闭环。Codex 之所以给人“好像在用多个 Agent”的感觉，就是因为它把这套闭环循环执行了很多轮。

1.3 内部编排与开放协议：Codex 和 A2A 是两条路线

这里有两种完全不同的工程路线。第一种是“内部编排”，比如 Codex，把拆分、执行、验证的逻辑全部内置在一个闭环进程里，用户只面对一个入口，Agent 内部如何分工你不用管，它自己管理状态、工具和上下文。这种路线体验好、上手快，适合个人和单团队场景，但跨系统协作时不通用，因为它的内部协议是私有的。

第二种是“开放协议”，比如 A2A。它不管你这个 Agent 内部是怎么实现的，只管两个不同 Agent 之间怎么发现彼此、怎么发任务、怎么传消息、怎么同步状态。它像给智能体们统一了口径，让 A2A 客户端可以调用任何遵循了 A2A 规范的服务端，哪怕对方的 Agent 是不同厂商做的。这条路线更适合企业环境，因为企业里天然有非常多的存量系统和供应商，统一接口是刚需。

理解了这两条路线的差异，后面看 Codex 和 A2A 就顺了：前者是“我怎么做好一个会协作的 Agent”，后者是“不同 Agent 之间怎么约定协作语言”。

2. Codex 内部机制拆解：一个任务如何被拆开、执行、验证

Codex 最常见的形态是 Codex CLI，一个跑在终端里的交互式编程 Agent。给它一句“把这个项目里的登录模块重构一遍，再补上单元测试”，它不会一口气干完，而是会先读代码结构，拆出小目标，然后逐步修改、跑测试、看报错，反复迭代，直到任务完成或者它自己认为需要再确认。这个过程的内部机制，是理解多 Agent 协作的最好样本。

2.1 安装与初始化：第一步就把环境理顺

按官方流程，Codex CLI 一般通过 npm 安装。你需要有 Node.js 环境，版本尽量保持较新，然后执行：

npm install -g @openai/codex

装好后先验证版本：

codex --version

如果命令找不到，大概率是 npm 的全局 bin 目录没加入 PATH。这个问题在 Windows 桌面版上尤其常见，安装器界面提示成功，但终端里就是找不到codex命令，这时候去系统环境变量里补一下 npm 的全局路径即可。

初始化时，Codex 会要求登录 OpenAI 账号，或者提供 API Key。登录态和 API Key 是两种不同鉴权方式，后续引发的报错也不一样。登录态下，Codex 会自动带上你账号可用的模型；API Key 模式下，Codex 按实际消耗计费。很多“codex auth token is unavailable”的报错，就是两种模式混用导致的，后面第 5 章我会专门整理。

第一次跑起来，我建议先看一眼配置文件结构。Linux 和 macOS 上默认在~/.codex/config.toml，Windows 上在用户目录下的.codex文件夹里。一个最简配置大致长这样：

model = "gpt-5.6-sol" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY"

这段配置的意思很直白：默认模型是gpt-5.6-sol，默认服务商是openai，所有请求发到base_url对应的端点。如果你只用官方服务，这段配置不用动，但如果你后面想接第三方兼容接口，这里的每个字段都会成为排查重点。

2.2 理解 Codex 的循环：规划、工具调用、验证、重试

Codex 不是一次性把整段代码生成完就收工。它的工作方式更像一个循环，我把这个循环拆成四步。

第一步是规划。Codex 拿到你的自然语言指令后，先读一遍当前工作区的文件结构、关键文件内容，然后给自己列一个待办清单。这个清单不一定展示给用户，但确实存在于它的工作上下文里，后续每一步都会对照清单检查进度。

第二步是工具调用。Codex 会调用一系列内置工具，比如读取文件、写文件、执行 shell 命令、运行测试。这一步是整个循环里最像“多个 Agent 在干活”的地方，因为它每做一个小改动，都会把现场信息反馈给自己，就像一个绕过主线程的独立执行器。

第三步是验证。改动文件之后，Codex 一般会主动跑测试或检查语法，而不是傻等用户验收。测试通过，它才认为这个小目标完成；测试失败，它会把报错信息读进来，进入重试。

第四步是上下文管理。整个循环里，Codex 的上下文会不断膨胀，所以它内部会做摘要和裁剪，把已经完成且不再需要关注的操作记录压缩成长摘要，只保留最新状态和下一步计划。这一步是整个多智体协作里最容易被低估的环节，上下文管不好，任何 Agent 都会在后半段开始“失忆”。

这四步循环，本质上就是一个单 Agent 体内模拟出的多 Agent 协作闭环。Codex 内部无论拆出多少个子任务，最终都是靠着这套“规划—执行—验证—摘要”的节奏来维持稳定。

2.3 接入第三方 OpenAI 兼容接口，以 DeepSeek 为例

很多实操文章中会遇到“Codex 接第三方模型”“codex 接入 deepseek”这类需求。核心逻辑很简单：Codex 只要能把请求发到某个 OpenAI 兼容服务的端点，并且该端点能返回 Codex 认识的响应结构，它就可以作为模型后端。

在config.toml里再定义一个 provider，然后把默认模型切过去。我实测时用的一个通用配置模板：

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

然后把这个 key 放到环境变量里：

export DEEPSEEK_API_KEY="你的密钥"

接着重新打开终端，进入一个 git 项目目录，直接跑codex。如果所有配置都没问题，Codex 在对话里会显示当前模型是deepseek-chat，请求会发到 DeepSeek 的接口。

这里有一点必须提醒：不是所有 OpenAI 兼容服务都完整实现了 Codex 依赖的接口路径。有些服务方只提供传统对话补全接口，而 Codex 会调用/responses这类较新的接口，两边对不上就会出现类似“处理 Codex 端点请求失败”的报错。遇到这种问题，不是环境变量的问题，而是服务方的兼容层还不完整，建议优先看服务方文档是否声明支持 Codex 或 Responses API，而不要反复折腾配置。

3. A2A 企业服务：给不同厂商的智能体搭一座标准桥

如果说 Codex 解决的是“一个团队怎么把事情干完”，那 A2A 协议解决的是“不同团队、不同公司、不同技术栈的智能体怎么互相派活”。它由 Google 提出，后来移交给 Linux 基金会，目标很朴素：像 HTTP 之于网页那样，成为智能体之间互相通信的通用语义。

3.1 A2A 协议的关键构件

A2A 并不定义智能体内部怎么思考，只定义智能体之间如何交互。它有几个核心概念，理解这几个概念，就等于理解了一多半协议。

Agent Card，相当于智能体的“名片”。一个服务端智能体要暴露自己的能力，就先在一个标准路径发布自己的 Agent Card，里面写了它能干什么、支持什么技能、有哪些端点、鉴权方式是什么。A2A 客户端先取名片，再决定要不要调用。

Task，是协作的基本单元。客户端向服务端发起一个任务，服务端会返回一个任务对象，里面携带状态。任务不是一次性把答案吐出来，它的状态会经历pending、working、completed、failed、input-required这些阶段。这样设计的好处是，长任务可以异步执行，客户端随时可以回来查询进度。

Message 和 Part，负责内容传递。Message 里带有角色，Part 则是内容片段，可以是文本、文件、结构化数据等形式。这样做是刻意为之，让智能体能传递代码文件、表格、图片裁剪区域，而不是只能传一串纯文本。

传输层上，A2A 通常使用 HTTP 加 JSON-RPC 2.0 风格的调用方式，核心方法包括发送任务、查询任务、取消任务等。这套协议既支持短连接请求，也支持流式的消息推送。从工程角度看，A2A 保证了两个智能体即使语言不同、平台不同、内部实现天差地别，也能用一个约定好的信封和字段名完成沟通。

3.2 和 MCP 的边界：一个管工具，一个管协调

很多人会问，A2A 和 MCP 是不是重复了。其实它们分工完全不同。MCP（Model Context Protocol）解决的是“智能体怎么调用本地或远程工具”，它把文件系统、数据库、外部 API 包装成一个个工具接口，让大模型能够统一调用。A2A 解决的是“智能体怎么相互通信”，它对话的对象不是工具，而是另一个智能体。

用生活里的例子来类比：MCP 是给一个人配齐了各种工具箱和说明书，告诉他怎么使用扳手、螺丝刀；A2A 是定好了不同人之间怎么开会、怎么布置任务、怎么汇报结果。前者是智能体与工具之间的协议，后者是智能体与智能体之间的协议。

在企业系统里，这两层往往是叠加出现的。A2A 服务端内部可能接了好几个 MCP 工具，客户端把任务发给它，它再用 MCP 去调数据库和业务系统，最后把结果打包成 A2A 消息回给客户端。

3.3 为什么企业一定要标准化

企业环境里最不缺的就是系统异构。ERP、CRM、工单系统、审批流、内部知识库，来源不同、技术年代不同、接口格式五花八门。你想让智能体自动化处理一个跨部门跨系统的流程，比如“客户提交故障单后，自动查询订单信息、检查库存、发起退款审批、通知物流系统”，这时候每个步骤背后都可能是一个不同团队负责的智能体。

如果没有标准协议，你只能在代码层面把所有系统硬编码串起来，改一个系统就断一串链条，维护成本极高。有了 A2A，每个系统只需要实现一个 A2A 服务端，发布一张 Agent Card，让别的智能体通过标准方式发起任务和接收结果。这有点像是把“接口的沟通规范”从代码里抽离出来，变成了整个企业智能体生态的通用语言。

实际部署时，企业还会在 A2A 之上叠加身份认证、权限控制、审计日志和灰度发布等能力。A2A 协议本身不解决这些问题，但它提供了足够的接口约定，方便网关层统一接入，这也是它在企业服务里价值最大的地方。

4. 从零搭一个多智能体协作工作流

光说不练没有用。我建议你直接在本地搭建一个最小可用的多智能体协作闭环，用最小的成本把“拆分、执行、验证、合并”全部跑一遍。这里我分享一套我自己用过的组合：主管 + 执行者的架构。

4.1 主管与执行者的最小闭环设计

不要一上来就设计复杂的 DAG 任务依赖图，先用一个最简单的模式：有一个主管智能体负责拆解任务和汇总结果，有若干个执行智能体分别负责具体子任务，彼此之间通过一份 JSON 状态文件同步进度。

这种模式我相信大多数人早期做原型时都用过。主管把任务拆成三份，写成task_1.json、task_2.json、task_3.json，每个文件里包含输入、上下文、期望产出和验收条件。执行者各自领取一份，处理完把结果写回同一个文件，再写一个status: completed标记。主管轮询所有文件的状态，全部完成后做合并。

这套方案的好处是每一步都可以肉眼检查。你不会被黑盒搞到崩溃，哪一步卡住，直接看那个文件就知道。缺点是状态同步不实时，只适合小规模实验。

4.2 用 Codex 做真实任务拆解

如果用 Codex 来扮演一个执行者，你可以这样操作。先在一个干净的项目目录里准备好一个明确的小任务，比如“把项目里所有 TODO 标记替换成带链接的 issue 引用”，然后给 Codex 一条非常带有验收标准的指令。

codex "清理当前仓库中的所有 TODO 和 FIXME 注释，生成一份清单，并给出修改方案，不要直接删代码"

我实测下来，Codex 会先识别出所有含 TODO 的文件，再逐文件读取上下文，最后给我一份修改计划，而不是直接一把梭全改。这时候你可以再让它“按计划执行，每个文件的改动量不超过 20 行”，它会进入逐文件修改、验证的循环。

这条流程的关键在于，你的验收标准越具体，Codex 表现得越像多个小 Agent 在分工。如果你只说“整理一下代码”，它只能给你一份泛泛的总结。多 Agent 协作里，下游执行者最需要的是清晰的边界。

4.3 用 FastAPI 实现一个最小 A2A 端点

如果你想让两个不同的 Agent 真正通过 A2A 协议通信，最省事的方法是先用 FastAPI 在本地起一个服务端，暴露一个标准的任务接口。

from fastapi import FastAPI, Request, JSONResponse app = FastAPI() @app.post("/a2a") async def a2a_endpoint(request: Request): payload = await request.json() method = payload.get("method") request_id = payload.get("id") if method == "tasks/send": params = payload.get("params", {}) task_id = params.get("id", "task-1") message = params.get("message", {}) parts = message.get("parts", []) # 这里把任务内容交给另一个 Agent 或代码逻辑处理 response = { "jsonrpc": "2.0", "id": request_id, "result": { "id": task_id, "status": { "state": "completed", "message": {"parts": [{"kind": "text", "text": "done"}]} } } } return JSONResponse(response) if method == "tasks/get": return JSONResponse({ "jsonrpc": "2.0", "id": request_id, "result": {"id": "task-1", "status": {"state": "completed"}} })

这个端点的结构并不复杂，但它已经体现出了 A2A 的核心素养：客户端发起任务，服务端返回任务状态，状态里有消息内容。两个不同的 Agent 只要都认这组字段，就能对接。实际企业部署里，你在这个端点背后可以接任意业务逻辑，前面再套一层身份认证和审计即可。

5. Codex 高频报错与排查手册

最近关于 Codex 的热度非常高，但热度越高的工具，卡在配置阶段的人越多。我把真正高频的几个报错整理成了一份排查手册，每一条都是实际遇到过的场景，希望能帮你少走弯路。

5.1 处理 Codex 端点响应时提示本地转发服务失败

这条报错完整场景通常是“cc switch local proxy failed while handling codex endpoint /responses”，翻译过来就是“在请求 Codex 的 /responses 接口时，本地转发服务出问题了”。

这类问题绝大多数出现在你用了第三方配置切换工具，并且给 Codex 配置了一个本地转发服务地址。请求先被转发到本地服务，再由它转发到真实模型服务。任一环节断掉，Codex 就会报这个错。排查顺序如下：

第一，确认本地转发服务是否真的在运行。很多时候是切换工具已经失效，但后台进程早就退出了。第二，检查配置里的 base_url 是否指向了错误端口，一个常见低级错误是填了被占用的端口，或者少写了一个路径。第三，看转发服务是否支持/responses这个接口。不少转发服务只兼容/chat/completions，Codex 依赖的新接口它接不住，这就不是 Codex 的问题，而是转发层没跟上。

最稳妥的做法是绕开本地转发层，直接在config.toml里把 base_url 指向官方接口地址，先确认 Codex 本体能正常工作，再排查本地服务的问题。不要在配置链路上堆太多中间层。

5.2 codex auth token is unavailable

这条报错表示 Codex 拿不到可用的认证令牌。

常见原因是登录态和 API Key 模式混用。你之前可能用 ChatGPT 账号登录过一次，后来又在环境变量里设置了 OPENAI_API_KEY，Codex 的信息源冲突了；或者反过来，你在环境变量里写了 key，但当前终端进程没有重新加载。

排查时先做两件事。第一，询问当前环境变量是否存在冲突：

echo $OPENAI_API_KEY

第二，确认登录状态是否已过期。如果用的是 API Key 模式，优先把环境变量清干净，只保留一条认证路径。如果是登录态，执行重新登录，让 Codex 重新生成令牌。

还有一个隐藏触发点：有些用户把 API Key 写进了config.toml的某个字段里，以为这样能替代环境变量。Codex 官方推荐的是通过env_key指向环境变量，你直接硬编码 key 虽然能跑，但换环境后特别容易出问题。

5.3 指定模型在当前账号下不受支持

如果你看到类似“the 'gpt-5.6-sol' model is not supported when using codex with a chatgpt account”的提示，意思是配置里写的模型名，和当前登录账号能用的模型集合不一致。

这种情况往往发生在你从别处复制了一份配置，但自己的账号并不具备该模型的访问权限。排查思路很简单：先确认当前账号在官方界面里到底能用哪些模型，再检查本地配置里model字段是否被写死。如果是通过第三方兼容接口接入，就到对方服务商的控制台查模型名，比如 DeepSeek 用的就不是gpt-5.6-sol而是deepseek-chat之类。

还有一个小坑：某些工具会把缓存写进 Codex 的会话历史里，导致即使改了模型配置，下一次会话仍用旧的模型标识。这种情况重启终端、清理对应会话缓存，或者新建一个项目目录再试。

5.4 未识别的配置项和安装类问题

“codex is ignoring 1 unrecognized configuration setting”这类提示，说明你的config.toml里有一个 Codex 当前版本不认识的字段。最典型的原因是拼写错误，比如model_provder少写了一个字母 i，或者把旧版本的字段名照搬到了新版本。这时不要盲目删配置，先打开配置文件逐字段对比官方文档，再确认 Codex 版本是否需要升级。

安装类问题里，Windows 桌面板最常见的是“安装完打不开”“命令行找不到命令”。前者多半是缺少运行库或者安装路径带中文导致的，后者是 PATH 配置问题。我实际处理过几个安装失败案例，共同规律是安装日志信息太隐晦，直接查看安装日志比反复重新安装更有效。还有一种情况是本地 npm 缓存问题，卸载重装前先清理缓存，往往能解决一半问题。

6. 多 Agent 协作的隐形地基和个人体会

聊到这里，多 Agent 协作的核心其实已经清晰了：靠的从来不是“把任务丢给一堆模型”，而是任务如何拆分、状态如何传递、结果如何验证、异常如何收敛，以及不同的 Agent 之间有没有一套能互相理解的语言。Codex 用内置闭环证明了这条路行得通，A2A 则把这条路标准化，铺到企业服务的每一个角落里。

6.1 状态管理、可观测性和权限边界

我在实操中最大的感受是，三个要素决定了多 Agent 协作项目能不能从 demo 走向生产。

第一个是状态管理。无论是内部编排还是 A2A，每个任务都要有明确的输入、输出、状态标记。状态不清晰，整个协作链就是一团浆糊。第二个是可观测性。每一步 Agent 到底调了什么工具、为什么做出这个决定、在哪一层报错，都要能被追踪。很多项目失败不是模型不够强，而是出问题时你完全看不到内部发生了什么。第三个更关键，是权限边界。给每个执行单元最小权限是铁律，不能因为它是“AI”就绕开权限审批。企业里尤其要小心，一个具备数据库写权限的 Agent 一旦误操作，后果远比手工慢一点严重。

6.2 给初学者的三条经验

如果是第一次接触这块，我建议你把三个原则记下来。

第一，先跑通单 Agent，再上多 Agent。不要一上来就铺一个复杂的编排系统。Codex 单工具先把一个小仓库管明白，你再考虑让它作为某个执行者接入更大的流程。

第二，任务拆得越细，协作越稳。我在实际使用中发现，一个大模型在“只做一件事，且这件事边界清晰”的时候表现远好过“同时管五件事”。这个现象在多 Agent 协作里同样成立，每个执行者的任务边界清晰，整体成功率才会高。

第三，多 Agent 的收益，来自系统设计，而不是模型数量。我个人见过不少失败的多 Agent 项目，本质都是在同一个模型服务外面套了一个脚本，既没有上下文管理，也没有验证闭环，更谈不上协议。真正出成果的项目，几乎都是先把单个环节的准确率做上去，再通过协作把准确率复合叠加。工程上先求确定性，再谈智能性，这条路在 Agent 协作里始终不会错。