官方教程中文版团队与集成
将 Codex 接入 Agents SDK
把 Codex 作为 MCP server 暴露给 OpenAI Agents SDK，用于可编排的软件工作流。
Codex 可以作为 MCP server 运行，其他 MCP client 可以连接它。官方示例里，一个常见做法是用 OpenAI Agents SDK 编排多个 agent，再让其中某个 agent 调用 Codex 完成代码任务。
这不是新手第一天必须掌握的功能。它适合你已经能稳定使用 Codex CLI，并希望把 Codex 放进更大的自动化工作流里。
先理解它解决什么问题
本地使用 Codex 时，你是直接和 Codex 对话。接入 Agents SDK 后，你可以让上层 agent 做分工：
- 一个 agent 负责拆需求。
- 一个 agent 负责调用 Codex 实现。
- 一个 agent 负责审查结果。
- SDK 负责 handoff、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。它是继续同一段 Codex 工作的关键，不要用已经废弃的 conversationId 做新实现。
调用 Codex 时要传清楚边界
codex 工具最重要的输入不是“写什么代码”，而是边界：
prompt：任务本身。cwd：在哪个目录工作。sandbox：能不能写文件。approval-policy：什么时候需要批准。model或profile：使用哪套默认配置。
如果这些不清楚，上层 agent 会把一个模糊任务交给 Codex，结果就会变得不可控。
第一次怎么试
不要一开始就做多 agent 自动交付。建议顺序：
- 先运行
codex mcp-server，确认能启动。 - 用 Inspector 发
tools/list，确认能看到codex和codex-reply。 - 用只读任务测试
codex。 - 读取返回里的
structuredContent.threadId。 - 用
codex-reply继续同一任务。
只要这条链路跑通，再接 Agents SDK。
Agents SDK 编排的正确心态
不要把所有 agent 都设计成“会写代码”。更稳的分工是：
- Planner：只拆任务，不改代码。
- Implementer：调用 Codex 做最小实现。
- Reviewer：检查 diff、测试和风险。
这和手动使用 Codex 的经验一致：先计划，再动手，再复核。SDK 只是把这个流程变成可运行的程序。
安全边界
把 Codex 接入 SDK 后，风险会增加，因为触发 Codex 的不再是你手动输入的每一句话，而可能是另一个 agent 的输出。
建议：
- 默认使用
workspace-write，不要默认danger-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。
如果你只能得到一次性结果，不能继续 session，优先检查 threadId 是否被正确保存和传回。
参考官方文档：
© OpenAI
最近更新：2026年5月4日