将 Codex 接入 Agents SDK

Codex 可以作为 MCP server 运行，其他 MCP client 可以连接它。常见做法是用 OpenAI Agents SDK 编排多个 agent，再让其中一个 agent 调用 Codex 完成代码任务。

这不是新手第一天必须掌握的功能。先把 Codex CLI、sandbox、approval 和 diff review 用稳，再把它放进自动化编排。

Codex with Agents SDK

官方 Codex MCP server 与 Agents SDK 编排指南。

MCP integration

先理解 MCP client/server 的基本边界。

Codex SDK

如果只需要程序化调用 Codex，先比较 SDK 路径。

它解决什么

flowchart LR
    Planner["Planner agent"] --> SDK["Agents SDK"]
    SDK --> CodexMCP["Codex MCP server"]
    CodexMCP --> Repo["repo task"]
    Repo --> Reviewer["Reviewer agent / human review"]

本地使用 Codex 时，你直接和 Codex 对话。接入 Agents SDK 后，上层 agent 可以分工：

Planner：拆需求，不改代码。
Implementer：调用 Codex 做最小实现。
Reviewer：检查 diff、测试和风险。
SDK：负责 handoff、guardrails、trace 和流程编排。

Codex 在这里不是聊天窗口，而是可以被其他 agent 调用的代码执行能力。

什么时候值得用

适合：

可重复的软件交付流程。
需要完整 traces 方便复盘。
多个 agent 需要明确分工。
已经能管理 sandbox、approval、working directory。

不适合：

只是让 Codex 修一个 bug。
还不熟悉 MCP。
不清楚 Agents SDK 的 handoff 和工具调用模型。
没有测试和回滚机制。

Codex MCP server 暴露什么

启动 Codex MCP server：

codex mcp-server

用 MCP Inspector 检查：

npx @modelcontextprotocol/inspector codex mcp-server

tools/list 会看到两个核心工具：

codex：开始一个新的 Codex session。
codex-reply：用 threadId 继续已有 session。

新实现要保存 threadId。官方保留 conversationId 作为兼容别名，但新流程不要依赖它。

调用时传清边界

codex 工具最重要的输入不是“写什么代码”，而是边界：

prompt：任务本身。
cwd：在哪个目录工作。
sandbox：能不能写文件，能碰到哪里。
approval-policy：什么时候需要批准。
model 或 profile：使用哪套配置。
config：本次调用覆盖哪些配置。

如果这些不清楚，上层 agent 会把模糊任务交给 Codex，结果不可控。

第一次怎么试

不要一开始就做多 agent 自动交付。建议顺序：

运行 codex mcp-server，确认能启动。
用 Inspector 发 tools/list，确认看到 codex 和 codex-reply。
用只读任务测试 codex。
读取返回里的 structuredContent.threadId。
用 codex-reply 继续同一任务。
确认 trace 里能看到 Codex 调用和结果。

这条链路跑通，再接 Agents SDK。

编排心态

不要把所有 agent 都设计成“会写代码”。更稳的分工是：

Planner 只拆任务，不碰文件。
Implementer 只调用 Codex 做最小实现。
Reviewer 只检查 diff、测试和风险。

这和手动使用 Codex 的经验一致：先计划，再动手，再复核。SDK 只是把这个流程变成可运行的程序。

安全边界

接入 SDK 后，风险会增加，因为触发 Codex 的可能是另一个 agent 的输出。

建议：

默认使用 read-only 或 workspace-write，不默认 full access。
自动流程里保留审批或可审查 trace。
cwd 必须明确，避免 Codex 在错误目录工作。
实现 agent 只做小任务，复杂需求先由 planner 拆分。
运行后必须检查 diff 和测试结果。

常见坑

没保存 threadId，导致每次调用都像新会话。
cwd 传错，Codex 在错误项目里工作。
自动流程默认给太高权限。
planner、implementer、reviewer 职责混在一起。
只看 SDK trace 是否成功，不看实际 diff 和测试结果。

第一次接入时，把目标压到很小：能启动、能列工具、能发一次只读任务、能用同一个 threadId 继续。

验收清单

MCP server 能稳定启动。
tools/list 能看到两个 Codex 工具。
codex 调用能返回结果和 threadId。
codex-reply 能继续同一 session。
Agents SDK trace 中能看到 handoff 和 Codex 调用。
生成的代码改动可以被测试和 review。