用途:在任意 agent 会话中,通过已注册的 codex MCP server 调用 Codex 工具,把实现类任务委派给 Codex,或与 Codex 进行多轮对话。MCP server 启动命令为 codex mcp-server。
主要能力:提供两个核心工具。codex 用于启动新的 Codex 会话并返回 threadId;codex-reply 用于继续已有会话,需要传入 threadId。常见场景包括:一次性任务(分析、问答)用 codex,参数 prompt、sandbox: read-only;写文件或实现代码用 codex,参数 prompt、approval-policy: never、sandbox: workspace-write;多轮对话(追问、修改)用 codex-reply,参数 threadId、prompt;还可通过 model、profile、config 指定模型或配置,通过 cwd 切换工作目录。模型方面,o3 适合最强推理与复杂任务,o4-mini 适合快速均衡的日常任务,也可使用 Codex 本地配置的默认模型。
使用方式:Codex MCP 工具是请求-响应模式,必须 await 工具返回值再继续。响应优先读取 structuredContent,旧版客户端降级读取 content[0].text;多轮会话需保存首次响应的 structuredContent.threadId。响应为空或工具报错时,应停止并报告给调用方。
限制与固定规则:MCP server 须已在 agent config 注册,key 为 codex-cli;每次工具调用必须等待响应完成后再继续;需要写文件时必须同时设置 approval-policy: never 和 sandbox: workspace-write;多轮会话必须保存 threadId;sandbox: danger-full-access 会赋予完整系统权限,仅在用户明确授权时使用。完整参数说明见 references/tool-specs.md。