用途
codex-control-plane-mcp 是为长时间运行的 Codex Desktop 任务提供可靠自动化的持久 MCP 控制平面。它把 Codex Desktop 和 codex-app-server 转变为一个可由 MCP 客户端安全驱动的持久 worker。
其核心契约是：提交任务后立即返回 operationId 或 workflowId，之后轮询直到工作完成，必要时批准 Plan Mode，最后读取最终报告。这避免了数小时的 MCP 调用、客户端重试后的重复 Codex 回合、盲目的即发即弃任务提交，并提供操作、工作流、回合、钩子和诊断的本地 SQLite 记录。
主要能力
- 持久异步队列，用于 Codex 写操作。
- 重试安全的 client_request_id 处理。
- 活动重复提示检测。
- SQLite 租约与心跳，协调竞争的 MCP 进程。
- 在 thread/start 或 turn/start 期间 MCP 重启后的恢复。
- 持久 turn/steer，在不创建第二个回合的情况下为活动回合添加上下文。
- 持久 thread/fork，用于分支现有线程，可带或不带初始消息。
- Plan Mode 工作流：启动计划、轮询、批准、执行、读取最终报告。Plan Mode 运行时下限为 workspace-write，当 MCP 提升只读请求时，状态中会返回 runtimePolicyAdjusted。
- 通过 app-server review/start 进行代码审查工作流，支持轮询和最终报告捕获。
- 使用 output_schema 的结构化最终报告。
- 线程生命周期工具：归档、取消归档和可轮询的压缩。
- 与 Codex Desktop 线程目标同步的工作流目标。
- 通过 turn/start 启动的回合支持图像和本地图像输入。
- 将待处理的审批和问题暴露为可轮询的 MCP 状态。
- 按 threadId / turnId、operationId 或 workflowId 中断回合。
- 运行时清单：模型、权限配置、沙箱就绪状态、钩子、技能、提供方功能、账户状态、使用量区间、速率限制状态和支持的 app-server 方法。
- 健康检查、诊断、问题分析和干运行修复。
- MCP 拥有的钩子历史存储于 SQLite，用于搜索、摘要和回退读取。
- 经过脱敏的 app-server 进度日志，包含增量、警告、模型重路由和令牌使用。
- 结构化 MCP 错误，供自动化代码分支处理。
写操作和控制操作通过 codex-app-server 执行。服务器不会修改 Codex 内部 SQLite 数据库或转录文件。
使用方式
当前完整实时目标为 Windows 上的 Codex Desktop 和 codex-app-server；Linux 和 macOS 目前仅支持协议检查。这是本地优先的控制平面，不应在未认证的情况下作为网络服务暴露。
推荐首次运行姿态：对不受信任的仓库使用只读；测试新工作流时使用按需审批；Plan Mode 从不在只读沙箱下运行，如果调用方请求只读，MCP 会将该回合提升为 workspace-write 并在状态输出中报告调整；保持 state/、logs/、.env 和 .codex/ 私有。
安装后生成配置，并以 stdio 模式运行 MCP 服务器。旧的 openclaw-codex-mcp 和 openclaw-codex-mcp-hooks 命令在下一个发布线中仍作为兼容别名保留。
默认内联模式下，一个 MCP 进程可以提交并执行操作。对于 OpenClaw、Hermes 或任何有多个 MCP 客户端的设置，建议使用中央 worker：所有 MCP 客户端使用相同的 CODEX_HOME 和 CODEX_MCP_STATE_DB；OpenClaw 网关条目以 CODEX_MCP_EXECUTION_MODE=client 运行；一个长期运行的 codex-control-plane-mcp-worker 进程拥有 codex-app-server、租约、队列槽和资源锁；客户端调用 codex_submit_task，然后轮询状态，不自行执行排队操作。
管理助手可生成更完整的客户端配置、安装钩子并运行协议冒烟测试。安装器会备份 ~/.codex/hooks.json，将其处理程序与现有钩子合并，存储 stateDb 为绝对路径，并将提示、可见代理进度文本、最终答案和回合状态写入 MCP 状态数据库。默认不记录工具调用和命令输出。安装或更改钩子后重启 Codex。
通过 codex-app-server 启动的回合，服务器会将接受的提示、可见助手消息和回合状态镜像到同一 SQLite 历史中。
适用场景
适用于需要让 Codex Desktop 执行长时间运行任务的本地编排器，例如 OpenClaw、Hermes 或任何多 MCP 客户端设置。支持提交持久任务、附加截图或其他图像证据、引导活动回合、在线程分支中立即开始工作、管理线程生命周期、请求结构化最终报告、驱动 Plan Mode、将工作流目标镜像到 Codex Desktop、运行 Codex 代码审查、处理审批和问题，以及启动诊断和修复。
在编排前或重连后，使用 codex_get_runtime_capabilities 获取运行时能力。它会在需要时启动 MCP 拥有的 app-server，调用短时尽力而为的清单方法，并返回缓存五分鐘的快照。在客户端模式下，客户端进程不会为实时清单启动自己的 app-server；当存在被动 worker 管理的快照时返回该快照。使用 refresh=true 可绕过缓存。
限制
- 当前完整实时支持仅限 Windows 与 Codex Desktop 和 codex-app-server；Linux 和 macOS 为协议检查。
- 本地优先，不打算作为公共网络服务暴露，未认证不得暴露为网络服务。
- 写和控制操作通过 codex-app-server 进行，不修改 Codex 内部 SQLite 数据库或转录文件。
- 公共状态负载是代理安全的，不包含完整提示、完整指令、原始标题、原始图像 URL/路径、精确令牌计数、原始命令输出或私有路径。
- MCP 不提取隐藏的思维链，也不在最终报告中存储原始工具负载或命令输出。
- 公共 thread/delete 有意未暴露。
- 图像输入仅对启动新回合的操作类型接受。
- output_schema 对象模式必须使用 Codex 要求的严格形式，将 additionalProperties 设为 false。
- Plan Mode 从不在只读沙箱下运行。
- 若 agentGuidance.loopGuard.allowed=false，应停止自动恢复，收集诊断并询问人类；不要在超时后创建新的 client_request_id，除非指导明确要求启动替换工作流。
- codex_health_summary 默认关于当前就绪状态；陈旧或孤立行在 historicalDebt 中报告，但不影响当前健康判断。
- 具体收费、价格、平台支持细节暂未提供。
