星枢 AI 开源项目趋势分析 查看项目

Python · 项目报告

aresyn/codex-control-plane-mcp

Durable MCP control plane for long-running Codex Desktop tasks

已完成 打开 GitHub
A
214星标
4Fork
7Issue
Apache-2.0许可证

分析结果

项目分析

codex-control-plane-mcp 是一个面向 Codex Desktop 的本地 MCP 控制平面，用 Python 编写，核心目标是让长时间运行的 Codex 任务变得可恢复、可轮询、可审计、可并发管理。它将 Codex Desktop 与 codex-app-server 包装成一个“耐久 worker”，MCP 客户端提交任务后立即获得 operationId 或 workflowId，然后通过轮询获取状态、处理审批、读取最终报告，而不是让一次 MCP 调用阻塞数小时。项目特别适合 OpenClaw、Hermes 或自研本地 Agent 编排器调用 Codex Desktop 执行复杂开发任务。

适用领域 AI Agent 编排 / MCP Server / OpenAI Codex Desktop 自动化 / 长任务调度 / 本地开发者工具 / 工作流控制平面 / 代码生成与代码审查 / 任务队列与状态持久化 / Agentic Workflow / 本地自动化运维
配置难度 中高。对于熟悉 MCP、Codex Desktop 和本地 Agent 编排的开发者，安装和基础使用并不复杂；但如果要稳定使用 central worker、多客户端队列、Plan Mode 审批、资源锁、并发控制和诊断修复能力，需要较强的工程化配置和排障能力。
商业价值 未知
01

技术亮点

  • 解决 MCP 调用长时间阻塞问题：任务提交后立即返回 operationId 或 workflowId。
  • 支持持久化异步队列，适合多小时 Codex 任务。
  • 支持 client_request_id，客户端超时重试时不会重复创建 Codex turn。
  • 内置重复 prompt 检测，降低重复执行风险。
  • 本地 SQLite 记录 operations、workflows、turns、hooks、diagnostics 等状态。
  • 支持 Plan Mode 工作流：启动计划、轮询、审批、执行、读取最终报告。
  • 支持 pending approvals 和 questions 的可轮询状态。
  • 支持 turn interrupt，可按 threadId、turnId、operationId 或 workflowId 中断任务。
  • 支持 central worker 模式，适合多个 MCP 客户端共享同一个 Codex 执行环境。
  • 提供 worker、queue、concurrency、operation status 等丰富状态查询工具。
  • 支持线程 fork、thread lifecycle 管理、archive、unarchive、compaction。
  • 支持 code review workflow，通过 app-server review/start 执行并捕获最终报告。
  • 支持 output_schema，用于结构化最终报告。
  • 支持图片输入，包括本地图片和 URL 图片，且状态输出中只保留安全元数据。
  • 提供健康检查、诊断、issue analysis 和 dry-run repair 工具。
  • 不直接修改 Codex 内部 SQLite 数据库或 transcript 文件，写操作通过 codex-app-server 进行。
  • Apache-2.0 许可证，便于商业项目采用。
02

目标用户

  • 使用 Codex Desktop 的高级开发者
  • 构建本地 AI Agent 工作流的开发者
  • 需要把 Codex 接入 MCP 客户端的团队
  • 使用 OpenClaw 或 Hermes 的用户
  • 希望让 Codex 执行长时间代码修改、重构、审查任务的工程团队
  • 需要本地优先、可恢复、可审计 Agent 执行环境的开发工具团队
  • 希望避免 MCP 长连接超时和重复提交问题的自动化系统开发者
03

配置要求

  • 主要完整支持环境是 Windows，并且需要安装 Codex Desktop 和 codex-app-server。
  • Linux 和 macOS 当前主要是协议级检查，不是完整 live target。
  • 需要 MCP 客户端通过 stdio 方式连接该 server。
  • 需要配置本地 SQLite 状态库，例如 CODEX_MCP_STATE_DB 或 init 命令中的 --state-db。
  • 需要配置 projects root，例如 --projects-root C:\Users\you\Projects。
  • 建议所有 MCP 客户端共享同一个 CODEX_HOME 和 CODEX_MCP_STATE_DB。
  • 如果使用 central worker 模式，客户端应设置 CODEX_MCP_EXECUTION_MODE=client，单独启动一个 codex-control-plane-mcp-worker。
  • worker 模式可设置 CODEX_MCP_EXECUTION_MODE=worker。
  • 可配置全局、项目、agent、thread 级别并发限制，例如 CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL、CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT。
  • 写操作可通过 resource_keys 声明资源锁粒度，避免同项目写任务过度串行或产生冲突。
  • 如需 hook 历史记录，可运行 codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3。
  • 安装或修改 hooks 后需要重启 Codex。
  • 项目强调 local-first，不建议直接暴露为公网服务；如果必须暴露，需要自行增加认证和访问控制。
  • 建议首次运行不可信仓库时使用 read-only sandbox，并使用 on-request approval 流程。
04

适用场景

  • 提交一个长时间运行的 Codex 代码修改任务，并通过 operationId 轮询状态
  • 将 Codex Desktop 接入 MCP 客户端，作为本地可控的代码执行 worker
  • 在 Plan Mode 下生成计划、人工审批计划、再执行计划
  • 执行长时间代码重构、修复、测试补全、代码审查任务
  • 在多个 MCP 客户端之间通过 central worker 模式共享同一个 Codex 执行资源
  • 防止客户端重试导致重复创建 Codex turn
  • 对运行中的 Codex turn 添加 steer 上下文，而不是新建重复任务
  • fork Codex 线程并在分支中继续执行不同方案
  • 捕获审批请求、问题、最终报告、诊断信息并写入本地 SQLite
  • 查询 worker 状态、队列状态、并发槽位和资源锁冲突
  • 通过本地 hook 记录 Codex 可见进度、最终回答和 turn 状态
05

部署与配置

  • 确保运行环境满足 Python 3.11+。
  • 推荐使用 pipx 安装：pipx install codex-control-plane-mcp
  • 也可以直接使用 uvx 运行：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
  • Windows PowerShell 激活环境：.\.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
  • 将生成的 JSON 配置复制到 MCP 客户端配置中。
  • 启动 MCP stdio server：codex-control-plane-mcp
  • 或以模块方式启动：py -m codex_control_plane_mcp.server
06

风险与注意事项

  • 完整 live 支持主要面向 Windows；Linux/macOS 当前能力有限。
  • 强依赖 Codex Desktop 和 codex-app-server，本身不是独立代码执行引擎。
  • 属于本地优先工具，不适合作为无认证公网服务暴露。
  • 需要理解 MCP、Codex Desktop、Plan Mode、worker 模式、SQLite 状态库等概念，上手门槛较高。
  • 多客户端或多 worker 场景下需要正确配置共享 CODEX_HOME、CODEX_MCP_STATE_DB、资源锁和并发限制，否则可能出现调度混乱。
  • 对不可信仓库执行 workspace-write 或 danger-full-access 有安全风险，需要谨慎配置 sandbox 和 approval policy。
  • 项目星标数量尚可但 fork 数较少，生态和社区成熟度仍需观察。
  • README 中强调本地可信环境，企业生产化部署需要额外的认证、审计、隔离和权限控制。
  • hook 会记录 prompts、可见进度、最终回答和 turn 状态到本地 SQLite，需要妥善保护 state、logs、.env、.codex 等目录。

历史记录

热榜历史快照

2026-06-21 第30名 新收录 · github_search