Codex Control Plane MCP

Codex Control Plane MCP

English | Русский

适用于长时间任务的可靠 Codex Desktop 自动化。

codex-control-plane-mcp 将 Codex Desktop 和 codex-app-server 转变为 MCP 客户端可以安全驱动的持久化工作进程。提交任务后，立即获得 operationId 或 workflowId，轮询直至工作完成；必要时批准 Plan Mode，然后读取最终报告。

该服务处理了那些轻量封装通常留给调用方的棘手环节：app-server 启动、线程和轮次创建、重试安全、重复提示词防护、Plan Mode、审批、本地历史记录、诊断和修复。

OpenClaw 和 Hermes 是一等客户端，但该服务也适用于任何需要 Codex Desktop 执行长时间任务、又不希望一次 MCP 调用持续数小时的本地编排器。

简要说明

MCP client / orchestrator
  -> submit a task or start a Plan Mode workflow
  <- receive operationId or workflowId immediately
  -> poll status
  -> answer approvals or approve the plan
  <- read final report, diagnostics, threadId, and turnId

由此可获得一份简单的约定：

• 不需要持续数小时的 MCP 调用；
• 客户端重试后不会产生重复的 Codex 轮次；
• 不会盲目提交任务后便不再跟进；
• 使用本地 SQLite 记录操作、工作流、轮次、钩子和诊断信息。

为什么不直接调用 Codex？

功能	轻量 Codex 封装	Codex Control Plane MCP
数小时的任务	阻塞／脆弱	持久化异步操作
客户端超时恢复	手动处理	可安全重试的 client_request_id
重复轮次防护	无	活跃提示词检测
Plan Mode 工作流	人工／手动处理	可轮询的工作流状态
审批和问题	阻塞／不透明	待处理交互 API
重启后恢复	临时处理	持久化的操作状态
诊断	仅日志	健康状态、诊断和修复工具

如需更详细的决策指南，请参阅 docs/THIN_WRAPPERS.md。

当前支持情况

• 完整实时目标：搭配 Codex Desktop 和 codex-app-server 的 Windows。
• Linux 和 macOS：目前仅进行协议检查。
• 本地优先：不适用于作为公共网络服务对外开放。

安全模型

这是面向受信任 Codex Desktop 环境的本地优先控制平面。

未经身份验证，请勿将其作为网络服务对外开放。

建议的首次运行安全配置：

• 对不受信任的代码仓库使用 read-only；
• 测试新工作流时使用 on-request 审批；
• Plan Mode 不会在 read-only 沙箱中运行。如果调用方请求 read-only，MCP 会将该轮次提升为 workspace-write，并在状态输出中报告 此调整；
• 妥善保护 state/、logs/、.env 和 .codex/。

功能

• 用于 Codex 写入操作的持久化异步队列。
• 安全重试的 client_request_id 处理。
• 检测活动的重复提示词。
• 使用 SQLite 租约和心跳处理相互竞争的 MCP 进程。
• 在 thread/start 或 turn/start 期间 MCP 重启后恢复。
• 持久化的 turn/steer，用于向活动轮次添加上下文，而不会创建第二个轮次。
• 持久化的 thread/fork，用于分支现有线程，可选择是否附带初始消息。
• 计划模式工作流：启动计划、轮询、批准、执行、读取最终报告。
• 计划模式的运行时最低要求：workspace-write；当 MCP 提升 read-only 请求的权限时，状态中会显示 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 数据库或转录文件。

安装

推荐方式：

pipx install codex-control-plane-mcp

或直接运行：

uvx codex-control-plane-mcp

从 GitHub 获取：

python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"

本地开发：

git clone https://github.com/aresyn/codex-control-plane-mcp.git
cd codex-control-plane-mcp
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q

MCP 客户端配置

安装后，生成配置：

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

最简 stdio 配置：

{
  "mcpServers": {
    "codex-control-plane": {
      "command": "codex-control-plane-mcp",
      "args": []
    }
  }
}

更多可直接复制粘贴的示例，涵盖 Claude Desktop、Cursor、VS Code 风格的 MCP 客户端、本地检出版本、已安装的软件包和中央工作进程模式，详见 examples/mcp-client-configs.md。

运行 MCP stdio 服务：

codex-control-plane-mcp

或将其作为模块运行：

py -m codex_control_plane_mcp.server

旧版 openclaw-codex-mcp 和 openclaw-codex-mcp-hooks 命令将在一个发布周期内继续作为兼容别名使用。

中央工作进程模式

默认的 inline 模式仍然是最简单的设置：一个 MCP 进程即可提交并执行操作。对于 OpenClaw、Hermes，或任何使用多个 MCP 客户端的设置，请改用中央工作进程。

建议的本地架构：

• 每个 MCP 客户端都使用相同的 CODEX_HOME 和 CODEX_MCP_STATE_DB；
• OpenClaw 网关条目以 CODEX_MCP_EXECUTION_MODE=client 运行；
• 一个长期运行的 codex-control-plane-mcp-worker 进程负责管理 codex-app-server、租约、队列槽位和资源锁；
• 客户端调用 codex_submit_task，然后轮询状态。它们不会自行执行排队中的操作。

工作进程命令：

$env:CODEX_MCP_EXECUTION_MODE = "worker"
codex-control-plane-mcp-worker

安全观察模式，适用于切换正在运行的网关之前：

codex-control-plane-mcp-worker --observe

并发默认值：

CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4
CODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1
CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1
CODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8

对于同一项目中的写入轮次，请将 resource_keys 传递给 codex_submit_task。若不传递，workspace-write 和 danger-full-access 轮次会锁定整个项目以进行写入。使用互不重叠的键时，工作进程可以并行运行多个写入轮次。

新增的状态工具：

• codex_get_worker_status
• codex_get_queue_status
• codex_get_concurrency_status
• codex_get_worker_command_status

codex_get_operation_status 还会返回 queueState、workerState、slotState 和 resourceLockState。运行中的轮次具有 slotState.claimed=true，以及包含工作进程 ID、槽位类型和认领时间的 slotClaim。codex_get_queue_status 会分别显示排队中的工作、运行中的轮次操作、辅助操作、活动轮次槽位和锁冲突。

当工作流正在等待可用容量时，codex_get_workflow_status 会在 workflowOperationQueueState 中反映嵌套操作的队列状态。槽位紧张时使用 nextRecommendedAction="wait_for_worker_slot"；写入锁冲突时使用 nextRecommendedAction="wait_for_resource_lock"。返回任一操作时，都不要为相同工作创建另一个操作。

首次设置

管理辅助工具可以生成更完整的客户端配置、安装钩子并运行协议冒烟测试：

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

该命令会输出一个 JSON 代码块，供你复制到 MCP 客户端配置中。它不会输出机密或私有提示词。

你也可以只安装 Codex 钩子：

codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3
codex-control-plane-mcp-hooks status
codex-control-plane-mcp-hooks doctor

安装程序会备份 ~/.codex/hooks.json，将其处理程序与现有钩子合并，将 stateDb 保存为绝对路径，并把提示词、可见的 Agent 进度文本、最终答案和轮次状态写入 MCP 状态数据库。默认不会记录工具调用和命令输出。安装或更改钩子后，请重启 Codex。

对于通过 codex-app-server 启动的轮次，服务器会将已接受的提示词、可见的助手消息和轮次状态同步到同一个 SQLite 历史记录中。即使 app-server 本身不执行用户钩子，也能确保搜索和状态读取保持实用。

主要工作流

提交持久化任务：

codex_submit_task
  -> operationId
codex_get_operation_status(operationId)
  -> queued / running / waiting_for_approval / completed / failed

调用方在传输超时后重试时，请使用相同的 client_request_id。重试会返回现有操作，而不是创建另一个轮次。

附加屏幕截图或其他图像证据：

codex_submit_task(
  operation_type="start_chat",
  message="Analyze this screen.",
  input_items=[
    {"type": "localImage", "path": ".\\screens\\error.png", "detail": "low"},
    {"type": "image", "url": "https://example.com/screenshot.png", "detail": "high"}
  ]
)

图像输入仅适用于会启动新轮次的操作类型：start_chat、send_message、execute_plan，以及包含初始消息的 fork_thread。MCP 会将路径或 URL 发送给 codex-app-server，但操作状态和诊断信息只会返回安全元数据，例如类型、详情、大小、扩展名和哈希值。公开状态载荷中不会存储二进制图像内容、原始 URL 或完整的本地图像路径。

引导活动轮次：

codex_submit_task(operation_type="steer_turn", thread_id=..., expected_turn_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the target turn until completed / failed / interrupted

仅当目标轮次处于活动状态时才使用 steer_turn。对于已完成的线程，请改用 send_message。

分叉线程：

codex_submit_task(operation_type="fork_thread", source_thread_id=...)
  -> operationId
codex_get_operation_status(operationId)
  -> completed, threadId=<forkedThreadId>

立即在分叉中开始工作：

codex_submit_task(operation_type="fork_thread", source_thread_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the first turn in the forked thread

对于可安全重试的分叉请求，请使用 client_request_id。如果不提供，每次调用都会被视为新的分叉请求。操作状态中的 threadId 是分叉后的线程；源线程会在 forkState.sourceThreadId 中报告。

管理线程生命周期：

codex_archive_thread(thread_id)
  -> completed
codex_unarchive_thread(thread_id)
  -> completed
codex_start_thread_compaction(thread_id)
  -> actionId
codex_get_thread_compaction_status(actionId)
  -> running / completed / unknown_after_app_server_exit

归档和取消归档是针对 app-server thread/archive 和 thread/unarchive 的审计操作。在线程有正在进行的轮次或待处理交互时，这些操作会拒绝执行。由于 thread/compact/start 是异步的，压缩使用独立的轻量级 actionId。有意不公开 thread/delete。

请求结构化最终报告：

codex_submit_task(operation_type="start_chat", message=..., output_schema={...})
codex_approve_plan(workflowId, output_schema={...})
  -> operationId / executionOperationId
codex_get_operation_status(operationId)
codex_get_workflow_status(workflowId)
  -> finalReport.text + finalReport.structured

output_schema 会传递给 app-server turn/start，并通过状态输出中的架构哈希进行跟踪。对象架构必须使用 Codex 要求的严格形式： 将 additionalProperties 设为 false。MCP 会将助手的最终消息存储为可读文本，然后在 Codex 返回有效 JSON 时，将 JSON 对象输出解析到 finalReport.structured 中。纯文本仍然有效，并保留在 finalReport.text 中。

MCP 不会提取隐藏的思维链，也不会在最终报告中存储原始工具负载或命令输出。

驱动计划模式：

codex_start_plan_workflow
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_plan / review_plan / execute_plan
codex_approve_plan(workflowId)
  -> executionOperationId
codex_get_workflow_status(workflowId)
  -> finalReport

计划模式有最低运行时要求。公开的默认写入策略仍为 read-only 和 on-request，但计划模式在 Windows 上需要可写工作区。如果调用方或服务默认策略解析为 read-only，MCP 会向 codex-app-server 发送 workspace-write，并在工作流和操作状态中返回 requestedSandbox、 effectiveSandbox 和 runtimePolicyAdjusted。

当客户端具有工作流目标时，将其同步到 Codex Desktop：

codex_start_plan_workflow(goal="Review the migration plan", goal_completion_action="clear")
codex_get_workflow_status(workflowId, refresh_live_goal=true)
  -> threadGoal.syncState + threadGoal.currentGoal

只有客户端传入 goal 时，MCP 才会写入线程目标。默认情况下，托管目标会在完成后执行 clear。如果工作流结束后仍应显示该目标，请使用 set_complete 或 leave。常规工作流轮询是被动的；只有在希望 MCP 调用实时 app-server 目标方法时，才使用 refresh_live_goal=true。

运行 Codex 代码审查：

codex_start_review_workflow(thread_id=..., target_type="base_branch", base_branch="main")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_review / read_review_report

或者让 MCP 为本地检出创建服务线程：

codex_start_review_workflow(cwd=..., target_type="uncommitted_changes")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> reviewThreadId + reviewTurnId + finalReport

审查工作流本身不会写入文件。它们会在选定的 Codex 沙箱和审批策略下运行。当调用方可能在传输超时后重试启动请求时，请使用 client_request_id。

处理审批和问题：

codex_list_pending_interactions
codex_answer_pending_interaction

使用以下命令启动诊断：

codex_get_runtime_capabilities
codex_health_summary
codex_collect_diagnostics
codex_analyze_issue
codex_repair_issue

修复操作默认使用 dry_run=true。

如果 MCP 检测到阻塞、失败状态、过期运行、待处理交互、重复提示、身份验证问题、速率限制或不安全的恢复循环，状态和诊断工具也会返回 agentGuidance 和 agentGuidanceText。Agent 在决定重试或停止之前，应遵循 agentGuidance.instructions。如果 agentGuidance.loopGuard.allowed=false，请停止自动恢复、收集诊断信息并询问人工人员。超时后不要创建新的 client_request_id，除非指导明确要求启动替代工作流。

对于损坏的计划模式工作流，请使用 retry_workflow_with_runtime_policy。该工具会使用所选沙箱和审批策略创建新工作流，通过 workflowRetryState 将其关联到旧工作流，但不会恢复旧的终止轮次。

默认情况下，codex_health_summary 反映当前就绪状态。旧的过期或孤立记录会报告在 historicalDebt 中，但如果工作进程、队列和 app-server 当前运行正常，这些记录不会导致新的编排看起来已损坏。请使用有针对性的清理来处理这些问题，而不是阻止新工作。

状态负载现在会分别显示新鲜度信号：

• operationRowAgeSeconds：持久化操作记录的存续时间；
• turnFreshness.lastProgressAgeSeconds：上次轮次进度事件的存续时间；
• workerFreshness.heartbeatAgeSeconds：工作进程心跳的存续时间；
• stalenessMeaning="operation_row_age"：兼容字段 stalenessSeconds 所表示的含义。 公开状态载荷对 Agent 是安全的。操作和工作流状态返回的是 requestSummary，而非原始的 request；其中包含 ID、运行时策略、调度意图、输入项状态、输出架构哈希、资源键和文本哈希。它不包含完整提示词、完整指令、原始标题、原始图像 URL/路径、精确的 token 数量、原始命令输出或私有路径。请使用你自己存储的任务文本和 requestSummary.*.sha256 进行关联。

codex_get_queue_status 仅在确有排队工作因槽位限制而受阻时，才会建议 wait_for_worker_slot。如果有正在运行的轮次，但 queueSummary.queued == 0，则队列操作为 none。

运行时能力

在编排之前或重新连接之后，使用 codex_get_runtime_capabilities。如有需要，它会启动 MCP 拥有的 app-server，调用简短的尽力而为清单方法，并返回缓存 5 分钟的快照。

在 client 模式下，客户端进程不会启动自己的 app-server 来获取实时清单。若存在由 Worker 管理的被动快照，它会返回该快照。设置 refresh=true 后，它会将一条 Worker 命令加入队列并返回 refreshCommandId；轮询 codex_get_worker_command_status 可读取刷新的清单。

响应包括：

• 模型数量、默认模型、隐藏标志、输入模态、推理力度和服务层级数量；
• 按 id 和 description 列出的权限配置；
• Windows 沙盒就绪状态；
• Web 搜索、图像生成和命名空间工具的提供方能力；
• Hook 和技能数量，不含原始 Hook 命令或绝对技能路径；
• 已脱敏的帐户状态、粗略使用量区间和运行状态的速率限制信息；
• 受支持的 app-server 架构方法，以及精简的来源、版本和哈希。

帐户清单可安全地展示给编排器。它会报告 Codex 是否已通过身份验证、帐户和套餐类型、是否存在电子邮件、使用量数据是否可用，以及是否存在可见的速率限制或额度问题。它不会返回原始电子邮件、帐户标识符、额度余额、支出限额、精确已用支出、每日使用量分桶或精确的 token 数量。

如果某个清单方法超时或失败，该工具仍会返回 ok=true，并将 runtimeCapabilities.status="partial"，同时在 methodResults 中提供机器可读的警告。设置 refresh=true 可绕过缓存。codex_health_summary 会从上次收集的快照中显示一小部分 runtimeCapabilities 内容，并且不会自行启动 app-server。如果客户端不需要帐户、使用量或速率限制状态，请传入 include_account=false。

进度日志

默认情况下，codex_get_turn_status 和 codex_get_operation_status 会包含精简的 progressEvents 块。它会记录 app-server 可见的进度，例如助手文本增量、计划增量、推理摘要文本、token 使用量、模型重路由和警告。

该日志有助于编排和故障排查，但不会提取隐藏的思维链。默认情况下，它也不会存储原始工具载荷、命令输出或完整的统一差异。差异事件会精简为安全的计数，例如变更行数和差异大小。

如果客户端需要旧版的纯消息状态结构，请使用 progress_events=0。使用 progress_max_chars 可限制返回的进度文本长度。

公开状态以粗略区间而非精确的 token 数量返回 token 使用量。原始审计界面可能会为调试保留经过脱敏的事件载荷，但编排器应将 tokenUsage.totalTokensBand 及相关区间字段视为公开接口约定。

工具概览

稳定的编排工具：

• codex_submit_task
• codex_get_operation_status
• codex_start_plan_workflow
• codex_start_review_workflow
• codex_get_workflow_status
• codex_approve_plan
• codex_list_pending_interactions
• codex_answer_pending_interaction
• codex_interrupt_turn
• codex_archive_thread
• codex_unarchive_thread
• codex_start_thread_compaction
• codex_get_thread_compaction_status
• codex_get_runtime_capabilities
• codex_health_summary
• codex_collect_diagnostics
• codex_repair_issue

兼容性和读取工具：

• codex_start_chat
• codex_send_message
• codex_execute_plan
• codex_list_projects
• codex_list_project_chats
• codex_list_active_chats
• codex_search_chats
• codex_get_chat_status
• codex_get_chat
• codex_get_turn_status
• codex_restart_app_server
• codex_get_app_server_status
• codex_get_diagnostic_logs
• codex_analyze_issue

新客户端应使用持久化操作和工作流。低级写入工具仍可用于兼容。

读取和诊断调用受到限制，以适用于 Agent 循环。codex_list_projects 默认返回精简的缓存输出；codex_search_chats 可以返回 timeBudgetExhausted=true，而不是阻塞等待完整刷新；聊天读取 优先采用已跟踪的轮次和钩子历史记录，然后才回退到旧版 KB。诊断采用 范围优先方式：scopedFindings 决定下一步操作，而 backgroundFindings 则提供历史背景。

有关架构、错误格式、稳定工具组和版本控制规则，请参阅 docs/API_CONTRACT.md。

结果约定

每个工具都声明 outputSchema，并返回 MCP structuredContent。

成功：

{"ok": true}

领域或工具错误：

{
  "ok": false,
  "error": {
    "code": "CODEX_ERROR_CODE",
    "message": "Human readable message",
    "details": {},
    "retryable": false
  }
}

启动时和重新连接时调用 codex_health_summary。version 块 包含 serverName、serverVersion、contractVersion、toolSurfaceHash、 guideHash、guideVersion、推荐的启动工具和写入工具，以及 稳定工具列表和兼容工具列表。

Agent 无需阅读此 README 即可了解操作约定。 tools/list 包含：

• codexMcpGuide：精简的机器可读指南，涵盖功能、流程、 全局规则和运行时限制；
• toolGroups：按优先顺序排列的首选工具组；
• recommendedStartupTool="codex_health_summary"；
• recommendedPrimaryWriteTool="codex_submit_task"。

每个工具还带有 annotations.codexMcp，其中包含其角色、 后续工具、幂等规则、被动读取标记和 mayStartTurn 标记。如果客户端库会隐藏顶层的 tools/list 字段，请调用 codex_get_agent_contract(detail="compact") 或 codex_get_agent_contract(detail="full", include_examples=true)。

配置

配置可以来自环境变量，也可以来自由 CODEX_CONTROL_PLANE_MCP_CONFIG 指定的 JSON 文件。旧名称 OPENCLAW_CODEX_MCP_CONFIG 仍可用作回退值。

常用变量：

• CODEX_HOME：Codex 主目录。默认为 %USERPROFILE%\.codex。
• CODEX_PROJECTS_ROOT：目录和读取工具扫描的项目根目录。
• CODEX_ALLOWED_ROOTS：以分号分隔的路径允许列表。
• CODEX_PROJECTS_REGISTRY：可选的 JSON 项目注册表。
• CODEX_MCP_STATE_DB：本地 MCP 状态数据库。
• CODEX_CONTROL_PLANE_MCP_LOG：日志文件路径。
• CODEX_MCP_HOOK_HISTORY_ENABLED：启用 SQLite 钩子历史记录。默认为 true。
• CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS：每条消息的钩子捕获字符数上限。
• CODEX_KB_HISTORY_PROJECTS_ROOT：可选的旧版标准化知识库历史记录根目录。
• CODEX_BINARY_PATH：可选的显式 Codex 二进制文件路径。
• CODEX_MCP_DEFAULT_SANDBOX：默认写入沙盒。默认为 read-only。
• CODEX_MCP_DEFAULT_APPROVAL_POLICY：默认写入审批策略。默认为 on-request。
• CODEX_MCP_DEFAULT_MODEL：传递给 app-server 的默认 Codex 模型。
• CODEX_MCP_DEFAULT_EFFORT：默认工作力度级别。
• CODEX_MCP_MAX_IMAGE_INPUT_ITEMS：每次 codex_submit_task 的图像附件数上限。默认为 10。
• CODEX_MCP_MAX_IMAGE_INPUT_BYTES：单个本地图像输入的字节数上限。默认为 20000000。
• CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS：报告回合停滞的不活动阈值。默认为 900。
• CODEX_MCP_STALLED_TURN_ACTION：回合停滞时的处理策略。默认为 diagnose_only。
• CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS：待处理交互的超时时间。
• DEEPSEEK_ENV_PATH：DeepSeek 摘要设置的可选 .env 文件。
• DEEPSEEK_SUMMARY_ENABLED：启用或禁用远程摘要调用。

写入策略的值是默认值，而非硬性限制。受信任的工作流需要不同设置时，客户端调用可以显式传入 sandbox 或 approval_policy。

纯透传行为的例外是计划模式：在 Windows 上，read-only 对计划模式而言限制过严，因此会提升为 workspace-write。限制更宽松的单次调用值（如 workspace-write）会原样传递。

示例：

$env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) "examples\codex-control-plane-mcp.config.json"
$env:CODEX_MCP_DEFAULT_SANDBOX = "read-only"
$env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = "on-request"
py -m codex_control_plane_mcp.server

参见 examples/codex-control-plane-mcp.config.json。

可靠性模型

此服务针对常见的本地编排故障而构建：

• 提交任务后 MCP 客户端超时。
• 使用相同的 client_request_id 重复提交。
• 未提供幂等键，但提示词相同且仍处于活动状态时重复提交。
• 在 app-server 的 thread/start 与 turn/start 之间重启 MCP 进程。
• 两个 MCP 进程共享同一个 SQLite 状态数据库。
• 回合进行期间 app-server 退出。
• 待处理审批关联到旧的 app-server 代次。
• app-server 或转录记录存在缺口，但钩子历史记录仍捕获了提示词、可见的 Agent 文本、最终答复和完成状态。

这些情况会保存在持久化的操作、工作流、回合、钩子和待处理交互状态中。终止状态均有明确标记。 unknown_after_app_server_exit 不会被视为成功。

安全

• 实时冒烟测试提示词必须包含 MCP LIVE TEST / DO NOT MODIFY FILES。
• 修复操作默认使用 dry_run=true。
• 强制重启 app-server 可能会将活动回合标记为未知或孤立。建议优先使用 restart_app_server_idle。

检查

快速本地检查：

python -m pytest -q
python -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts
git diff --check

仅协议 MCP 冒烟测试：

python .\scripts\mcp_live_smoke.py --scenario protocol

使用真实 Codex Desktop/app-server 进行安全的在线冒烟测试：

python .\scripts\mcp_live_smoke.py --scenario safe-operation --cwd <PROJECT_ROOT>

完整在线回归测试：

python .\scripts\mcp_live_smoke.py --scenario full --safe-restart --cwd <PROJECT_ROOT>

用于开发和长时间在线测试的外部 MCP 客户端：

python .\scripts\external_mcp_client.py daemon-start
python .\scripts\external_mcp_client.py daemon-restart-mcp --reason after_code_change
python .\scripts\external_mcp_client.py run-live-test --scenario full --archive-report

如果需要将当前检出版本作为真实 MCP 客户端进行测试，且不重启 Codex Desktop，请使用外部客户端。它会运行独立的守护进程，维护自己的 MCP stdio 子进程，并且在代码更改后只重启该子进程。在线测试发现的问题会写入 corrective_action_plan.md；之前的报告可以使用 --archive-report 归档。

请参阅 docs/EXTERNAL_MCP_CLIENT.md，了解守护进程命令和可用的在线测试场景。

请参阅 docs/RELEASE_CHECKLIST.md。有关公开发布的定位，请参阅 docs/PUBLICATION_GUIDE.md。

打包

在本地构建：

python -m pip install build
python -m build

该 wheel 包含 MCP 服务、钩子安装程序、管理辅助工具，以及打包的 Codex 钩子模块。

常规安装方式如下：

pipx install codex-control-plane-mcp

或：

uvx codex-control-plane-mcp

贡献

在提交包含诊断信息的问题前，请阅读 CONTRIBUTING.md 和 SECURITY.md。

适用于此仓库的 GitHub 主题：

python、mcp、mcp-server、model-context-protocol、openai-codex、 codex、codex-desktop、agent-tools、ai-agents、developer-tools、 automation、orchestration、agentic-workflows、long-running-tasks、 openclaw、hermes、hermes-agent。