本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/guides/agents-sdk

将 Codex 与 Agents SDK 一起使用

将 Codex 作为 MCP 服务器调用，以构建多智能体开发工作流

将 Codex 作为 MCP 服务器运行

你可以将 Codex 作为 MCP 服务器运行，并从其他 MCP 客户端连接到它（例如，使用 OpenAI Agents SDK MCP integration 构建的 agent）。

要将 Codex 作为 MCP 服务器启动，可以使用以下命令：

codex mcp-server

你也可以使用 Model Context Protocol Inspector 启动一个 Codex MCP 服务器：

npx @modelcontextprotocol/inspector codex mcp-server

发送一个 tools/list 请求以查看两个工具：

codex：运行一个 Codex 会话。接受与 Codex Config 结构体匹配的配置参数。codex 工具有以下属性：

Property	Type	Description
`prompt`（必需）	`string`	用于启动 Codex 对话的初始用户提示。
`approval-policy`	`string`	模型生成的 shell 命令的审批策略：`untrusted`、`on-request` 和 `never`。
`base-instructions`	`string`	用来替代默认指令的一组指令。
`config`	`object`	覆盖 `$CODEX_HOME/config.toml` 中配置的单独配置项。
`cwd`	`string`	会话的工作目录。如果是相对路径，则相对于服务器进程的当前目录解析。
`include-plan-tool`	`boolean`	是否在对话中包含 plan 工具。
`model`	`string`	可选的模型名称覆盖（例如，`o3`、`o4-mini`）。
`profile`	`string`	来自 `config.toml` 的配置 profile，用于指定默认选项。
`sandbox`	`string`	sandbox 模式：`read-only`、`workspace-write` 或 `danger-full-access`。

codex-reply：通过提供 thread ID 和 prompt 来继续一个 Codex 会话。codex-reply 工具有以下属性：

Property	Type	Description
`prompt`（必需）	string	用于继续 Codex 对话的下一条用户提示。
`threadId`（必需）	string	要继续的 thread 的 ID。
`conversationId`（已弃用）	string	`threadId` 的已弃用别名（为兼容性保留）。

在 tools/call 响应中，使用来自 structuredContent.threadId 的 threadId。审批提示（exec/patch）也会在其 params 负载中包含 threadId。

示例响应负载：

{
  "structuredContent": {
    "threadId": "019bbb20-bff6-7130-83aa-bf45ab33250e",
    "content": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."
  },
  "content": [
    {
      "type": "text",
      "text": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."
    }
  ]
}

请注意，现代 MCP 客户端通常只会在存在时将 "structuredContent" 作为工具调用结果返回，不过 Codex MCP 服务器也会返回 "content"，以便兼容较旧的 MCP 客户端。

创建多智能体工作流

Codex CLI 能做的远不止运行临时任务。通过将 CLI 作为一个 Model Context Protocol（MCP）服务器暴露出来，并使用 OpenAI Agents SDK 对其进行编排，你可以创建确定性、可审查的工作流，并且能够从单个 agent 扩展到完整的软件交付流水线。

本指南将带你完成与 OpenAI Cookbook 中展示的相同工作流。你将会：

将 Codex CLI 作为一个长期运行的 MCP 服务器启动，
构建一个专注的单智能体工作流，用于生成一个可玩的浏览器游戏，以及
编排一个具有交接、护栏和完整 trace 的多智能体团队，以便你之后可以审查。

开始之前，请确保你已经具备：

已在本地安装 Codex CLI，这样 npx codex 才能运行。
Python 3.10+ 和 pip。
Node.js 18+（npx 所需）。
已在本地存储一个 OpenAI API key。你可以在 OpenAI dashboard 中创建或管理 key。

为本指南创建一个工作目录，并将你的 API key 添加到 .env 文件中：

mkdir codex-workflows
cd codex-workflows
printf "OPENAI_API_KEY=sk-..." > .env

安装依赖

Agents SDK 负责处理 Codex、交接和 trace 之间的编排。安装最新的 SDK 包：

python -m venv .venv
source .venv/bin/activate
pip install --upgrade openai openai-agents python-dotenv

激活虚拟环境可以让 SDK 依赖与系统其余部分保持隔离。

将 Codex CLI 初始化为 MCP 服务器

首先，将 Codex CLI 转换为一个 Agents SDK 可调用的 MCP 服务器。该服务器暴露两个工具（codex() 用于开始对话，codex-reply() 用于继续对话），并在多个 agent 轮次之间保持 Codex 存活。

创建一个名为 codex_mcp.py 的文件，并添加以下内容：

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
        },
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        print("Codex MCP server started.")
        # 下一节将添加更多逻辑。
        return

if __name__ == "__main__":
    asyncio.run(main())

运行一次该脚本，以验证 Codex 是否成功启动：

python codex_mcp.py

脚本会在打印 Codex MCP server started. 后退出。在接下来的部分中，你将会在更丰富的工作流中复用同一个 MCP 服务器。

构建单智能体工作流

让我们从一个范围明确的示例开始，使用 Codex MCP 交付一个小型浏览器游戏。该工作流依赖两个 agent：

Game Designer：为游戏撰写简要说明。
Game Developer：通过调用 Codex MCP 来实现游戏。

使用以下代码更新 codex_mcp.py。它保留了上面的 MCP 服务器设置，并添加了这两个 agent。

from dotenv import load_dotenv

from agents import Agent, Runner, set_default_openai_api
from agents.mcp import MCPServerStdio

load_dotenv(override=True)
set_default_openai_api(os.getenv("OPENAI_API_KEY"))

async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
        },
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        developer_agent = Agent(
            name="Game Developer",
            instructions=(
                "You are an expert in building simple games using basic html + css + javascript with no dependencies. "
                "Save your work in a file called index.html in the current directory. "
                "Always call codex with \"approval-policy\": \"never\" and \"sandbox\": \"workspace-write\"."
            ),
            mcp_servers=[codex_mcp_server],
        )

        designer_agent = Agent(
            name="Game Designer",
            instructions=(
                "You are an indie game connoisseur. Come up with an idea for a single page html + css + javascript game that a developer could build in about 50 lines of code. "
                "Format your request as a 3 sentence design brief for a game developer and call the Game Developer coder with your idea."
            ),
            model="gpt-5",
            handoffs=[developer_agent],
        )

        await Runner.run(designer_agent, "Implement a fun new game!")

if __name__ == "__main__":
    asyncio.run(main())

执行该脚本：

python codex_mcp.py

Codex 将读取设计师的简述，创建一个 index.html 文件，并将完整游戏写入磁盘。在浏览器中打开生成的文件即可体验结果。每次运行都会生成不同的设计，包含独特的玩法变化和打磨细节。

扩展为多智能体工作流

现在将单 Agent 设置改造成一个可编排、可追踪的工作流。系统新增了：

Project Manager：创建共享需求、协调交接，并执行护栏约束。
Designer、Frontend Developer、Server Developer 和 Tester：每个角色都有范围明确的指令和输出文件夹。

创建一个名为 multi_agent_workflow.py 的新文件：

from dotenv import load_dotenv

from agents import (
    Agent,
    ModelSettings,
    Runner,
    WebSearchTool,
    set_default_openai_api,
)
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
from agents.mcp import MCPServerStdio
from openai.types.shared import Reasoning

load_dotenv(override=True)
set_default_openai_api(os.getenv("OPENAI_API_KEY"))

async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={"command": "npx", "args": ["-y", "codex", "mcp"]},
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        designer_agent = Agent(
            name="Designer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "你是 Designer。\n"
                "你唯一的事实来源是来自 Project Manager 的 AGENT_TASKS.md 和 REQUIREMENTS.md。\n"
                "不要假设任何其中未写明的内容。\n\n"
                "你可以使用互联网获取额外指导或进行研究。"
                "交付物（写入 /design）：\n"
                "- design_spec.md – 按 AGENT_TASKS.md 的要求，用单页描述 UI/UX 布局、主要界面和关键视觉说明。\n"
                "- wireframe.md – 如果有指定，则提供一个简单的文本或 ASCII 线框图。\n\n"
                "保持输出简短且便于实现。\n"
                "完成后，使用 transfer_to_project_manager 交接给 Project Manager。"
                "创建文件时，调用 Codex MCP 并使用 {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}。"
            ),
            model="gpt-5",
            tools=[WebSearchTool()],
            mcp_servers=[codex_mcp_server],
        )

        frontend_developer_agent = Agent(
            name="Frontend Developer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "你是 Frontend Developer。\n"
                "阅读 AGENT_TASKS.md 和 design_spec.md。严格按其中描述进行实现。\n\n"
                "交付物（写入 /frontend）：\n"
                "- index.html – 主页面结构\n"
                "- styles.css 或内联样式（如果有指定）\n"
                "- main.js 或 game.js（如果有指定）\n\n"
                "遵循 Designer 的 DOM 结构，以及 Project Manager 提供的任何集成点。\n"
                "不要添加提供文档之外的功能或品牌元素。\n\n"
                "完成后，使用 transfer_to_project_manager_agent 交接给 Project Manager。"
                "创建文件时，调用 Codex MCP 并使用 {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}。"
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        backend_developer_agent = Agent(
            name="Backend Developer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "你是 Backend Developer。\n"
                "阅读 AGENT_TASKS.md 和 REQUIREMENTS.md。实现其中描述的后端端点。\n\n"
                "交付物（写入 /backend）：\n"
                "- package.json – 如果有要求，包含 start 脚本\n"
                "- server.js – 严格按规范实现 API 端点和逻辑\n\n"
                "保持代码尽可能简单且可读。不使用外部数据库。\n\n"
                "完成后，使用 transfer_to_project_manager_agent 交接给 Project Manager。"
                "创建文件时，调用 Codex MCP 并使用 {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}。"
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        tester_agent = Agent(
            name="Tester",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "你是 Tester。\n"
                "阅读 AGENT_TASKS.md 和 TEST.md。验证其他角色的输出是否满足验收标准。\n\n"
                "交付物（写入 /tests）：\n"
                "- TEST_PLAN.md – 按要求提供手动检查项或自动化步骤的项目符号列表\n"
                "- test.sh 或一个简单的自动化脚本（如果有指定）\n\n"
                "保持最小化且易于运行。\n\n"
                "完成后，使用 transfer_to_project_manager 交接给 Project Manager。"
                "创建文件时，调用 Codex MCP 并使用 {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}。"
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        project_manager_agent = Agent(
            name="Project Manager",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                """
                你是 Project Manager。

                目标：
                将输入的任务列表转换为团队执行所依据的三个项目根目录文件。

                交付物（写入项目根目录）：
                - REQUIREMENTS.md：对产品目标、目标用户、关键功能和约束条件的简明总结。
                - TEST.md：带有 [Owner] 标签（Designer、Frontend、Backend、Tester）和清晰验收标准的任务列表。
                - AGENT_TASKS.md：每个角色一个章节，包含：
                  - 项目名称
                  - 所需交付物（确切文件名及用途）
                  - 关键技术说明和约束

                过程：
                - 用尽量少且合理的假设来消除歧义。要足够具体，使每个角色无需猜测即可行动。
                - 使用 Codex MCP 创建文件，并使用 {"approval-policy":"never","sandbox":"workspace-write"}。
                - 不要创建文件夹。只创建 REQUIREMENTS.md、TEST.md、AGENT_TASKS.md。

                交接（以必需文件为门禁）：
                1) 创建完上述三个文件后，使用 transfer_to_designer_agent 交接给 Designer，并附上 REQUIREMENTS.md 和 AGENT_TASKS.md。
                2) 等待 Designer 生成 /design/design_spec.md。继续前先验证该文件存在。
                3) 当 design_spec.md 存在时，并行交接给以下两个角色：
                   - Frontend Developer，使用 transfer_to_frontend_developer_agent（提供 design_spec.md、REQUIREMENTS.md、AGENT_TASKS.md）。
                   - Backend Developer，使用 transfer_to_backend_developer_agent（提供 REQUIREMENTS.md、AGENT_TASKS.md）。
                4) 等待 Frontend 生成 /frontend/index.html，且 Backend 生成 /backend/server.js。验证两个文件都存在。
                5) 当两者都存在后，使用 transfer_to_tester_agent 交接给 Tester，并提供所有先前的工件和输出。
                6) 在当前步骤所需文件存在之前，不要进入下一次交接。如果缺少某项，要求对应 Agent 提供并重新检查。

                PM 职责：
                - 协调所有角色，跟踪文件完成情况，并执行上述门禁检查。
                - 不要用状态更新作答。只需持续交接给下一个 Agent，直到项目完成。
                """
            ),
            model="gpt-5",
            model_settings=ModelSettings(
                reasoning=Reasoning(effort="medium"),
            ),
            handoffs=[designer_agent, frontend_developer_agent, backend_developer_agent, tester_agent],
            mcp_servers=[codex_mcp_server],
        )

        designer_agent.handoffs = [project_manager_agent]
        frontend_developer_agent.handoffs = [project_manager_agent]
        backend_developer_agent.handoffs = [project_manager_agent]
        tester_agent.handoffs = [project_manager_agent]

        task_list = """
Goal: Build a tiny browser game to showcase a multi-agent workflow.

High-level requirements:
- Single-screen game called "Bug Busters".
- Player clicks a moving bug to earn points.
- Game ends after 20 seconds and shows final score.
- Optional: submit score to a simple backend and display a top-10 leaderboard.

Roles:
- Designer: create a one-page UI/UX spec and basic wireframe.
- Frontend Developer: implement the page and game logic.
- Backend Developer: implement a minimal API (GET /health, GET/POST /scores).
- Tester: write a quick test plan and a simple script to verify core routes.

Constraints:
- No external database—memory storage is fine.
- Keep everything readable for beginners; no frameworks required.
- All outputs should be small files saved in clearly named folders.
"""

        result = await Runner.run(project_manager_agent, task_list, max_turns=30)
        print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

运行脚本并查看生成的文件：

python multi_agent_workflow.py
ls -R

项目经理 agent 会编写 REQUIREMENTS.md、TEST.md 和 AGENT_TASKS.md，然后协调 designer、frontend、server 和 tester agents 之间的交接。每个 agent 都会先在自己的文件夹中编写其职责范围内的产物，然后再将控制权交还给项目经理。

跟踪工作流

Codex 会自动记录 traces，用于捕获每一次 prompt、工具调用和交接。多 agent 运行完成后，打开 Traces dashboard 以检查执行时间线。

高层级 trace 突出了项目经理在继续推进之前如何验证交接。点击各个单独步骤可查看 prompts、Codex MCP 调用、写入的文件以及执行时长。这些细节使你可以直接审计每一次交接，并理解该工作流是如何一轮一轮演进的。
这些 traces 使你可以轻松调试工作流中的小问题、审计 agent 行为，并随着时间推移衡量性能，而无需额外的监测埋点。

将 Codex 作为 MCP 服务器运行

创建多智能体工作流

安装依赖​

将 Codex CLI 初始化为 MCP 服务器​

构建单智能体工作流​

扩展为多智能体工作流​

跟踪工作流​

安装依赖

将 Codex CLI 初始化为 MCP 服务器

构建单智能体工作流

扩展为多智能体工作流

跟踪工作流