Codex CLI 可作为 MCP server 运行，让 OpenAI Agents SDK 通过两个工具（codex 启动会话、codex-reply 续接会话）调用它。本文通过"构建浏览器游戏"和"多角色软件开发流水线"两个完整示例，演示如何用 Python + Agents SDK 构建确定性、可审计的工程工作流。

通过 Agents SDK 使用 Codex

将 Codex 作为 MCP Server 运行

你可以将 Codex 作为 MCP server 启动，从其他 MCP 客户端（如 OpenAI Agents SDK）连接使用：

codex mcp-server

用 MCP Inspector 验证：

npx @modelcontextprotocol/inspector codex mcp-server

发送 tools/list 可以看到两个工具：

codex：启动新的 Codex 会话。支持的参数：

参数	类型	说明
prompt（必填）	string	初始用户 prompt
approval-policy	string	命令审批策略：untrusted、on-request、never
base-instructions	string	替代默认指令集
config	object	覆盖 config.toml 中的配置
cwd	string	会话工作目录
model	string	模型名称（如 o3、o4-mini）
sandbox	string	沙箱模式：read-only、workspace-write、danger-full-access

codex-reply：续接已有 Codex 会话。支持的参数：

参数	类型	说明
prompt（必填）	string	下一条用户消息
threadId（必填）	string	要续接的 thread ID

从 tools/call 响应的 structuredContent.threadId 获取 thread ID。

---

构建多 Agent 工作流

Codex CLI 暴露为 MCP server 后，配合 OpenAI Agents SDK 可以构建确定性、可审计的工作流——从单 agent 到完整软件交付流水线。

环境准备

需要：

• Codex CLI（本地安装，支持 npx codex）
• Python 3.10+
• Node.js 18+
• OpenAI API Key

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

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

初始化 MCP Server

创建 codex_mcp.py，将 Codex CLI 作为 MCP server 启动：

import asyncio

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())

运行验证：

python codex_mcp.py

---

单 Agent 工作流示例

用 Game Designer + Game Developer 两个 agent 构建一个浏览器游戏：

import asyncio
import os

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 and call the Game Developer 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())

---

多 Agent 工作流：五角色协作

包含 Project Manager、Designer、Frontend Developer、Backend Developer、Tester 五个角色的完整流水线。详细代码见 OpenAI Cookbook。

核心流程：

1. Project Manager 生成 REQUIREMENTS.md、TEST.md、AGENT_TASKS.md，然后移交 Designer
2. Designer 生成 /design/design_spec.md，移交 PM
3. PM 同时移交 Frontend Developer 和 Backend Developer
4. 两者完成后移交 Tester
5. Tester 写测试计划，移交 PM 验收

---

追踪工作流

Codex 自动记录每次 prompt、工具调用和移交的 trace。运行完成后，在 Traces 面板 查看执行时间线，点击每个步骤可看到 prompt、Codex MCP 调用、写入的文件和执行时长。

---

常见问题

Q: codex mcp-server 和 codex exec 有什么区别？

A: mcp-server 让 Codex 保持长期运行，接受来自 Agents SDK 的多次调用，适合多轮工作流；codex exec 是一次性执行，每次调用启动一个新会话，适合简单的 CI 任务。

Q: multi-agent 工作流中如何防止 agent 之间的混乱移交？

A: 在每个 agent 的 instructions 里明确指定只能移交给特定 agent（如 transfer_to_project_manager），并在 PM agent 里加入文件存在性检查作为"门控"条件，防止提前移交。

Q: 如何调试某个 agent 的行为？

A: 在 OpenAI Traces 面板查看该 agent 的每次 Codex MCP 调用详情；也可以在 Runner.run 返回后打印 result.final_output 查看最终输出。