---
title: "将 Codex 接入 Agents SDK"
description: "把 Codex 作为 MCP server 暴露给 OpenAI Agents SDK，用于可编排的软件工作流。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="Codex with Agents SDK" href="https://developers.openai.com/codex/guides/agents-sdk">
    官方 Codex MCP server 与 Agents SDK 编排指南。
  </Card>
  <Card title="MCP integration" href="/docs/codex/official/03-extensions/08-mcp-integration">
    先理解 MCP client/server 的基本边界。
  </Card>
  <Card title="Codex SDK" href="/docs/codex/official/06-team-integration/71-codex-sdk">
    如果只需要程序化调用 Codex，先比较 SDK 路径。
  </Card>
</Cards>

## 它解决什么

```mermaid
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：

```bash
codex mcp-server
```

用 MCP Inspector 检查：

```bash
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 自动交付。建议顺序：

1. 运行 `codex mcp-server`，确认能启动。
2. 用 Inspector 发 `tools/list`，确认看到 `codex` 和 `codex-reply`。
3. 用只读任务测试 `codex`。
4. 读取返回里的 `structuredContent.threadId`。
5. 用 `codex-reply` 继续同一任务。
6. 确认 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。

## 官方资料

- [Codex Agents SDK guide](https://developers.openai.com/codex/guides/agents-sdk)
- [OpenAI Agents SDK MCP integration](https://developers.openai.com/api/docs/guides/agents/integrations-observability#mcp)
