Codex-Control-MCP

# Codex-Control-MCP 0.2.0

Codex-Control-MCP 是本机/远端执行基础设施 MCP。它通过已安装的官方 Codex Runtime 提供 Shell、文件、Git、长任务会话、Browser、Computer Use，以及 0.2.0 新增的可恢复任务、多主机路由、动态 MCP 和 Skill 生命周期管理。

当前架构

• Codex-Control-MCP：47 个顶层工具。只负责执行基础设施，不内置 DirectorDesk 或 Grok 媒体工具。

• DirectorDesk-MCP：独立 stdio MCP，原 17 个 director_* 场景工具通过本机 DirectorDesk /director bridge 调用；另加 director_host_task 非执行宿主任务接口（合计 18）。它仅 inspect/prepare/get/cancel，不会调用 ChatGPT 原生工具或生成图片，见 C:\path\to\DirectorDesk-MCP\README.md。

• Grok-MCP：独立 stdio MCP，3 个媒体工具：grok_image_generate、grok_image_edit、grok_video_generate。

• Dynamic MCP：Codex-Control-MCP 通过 mcp_manage / mcp_tool_search / mcp_tool_inspect / mcp_tool_call 按需发现和调用独立 MCP。第三方工具不再静态塞进 Core。

生产公网地址：https://codex-control.aiwsb.site/mcp

生产 Core：http://127.0.0.1:8774/mcp，需要 owner Bearer 或 OAuth。Cloudflare tunnel 直接指向 8774。旧 8767 DirectorDesk 聚合网关已退役。

Related MCP server: ChatGPT Codex Bridge

0.2.0 新基础设施

Recoverable Task Runtime

task_manage 支持：create / list / get / checkpoint / block / resume / final_review / complete。

任务保存在 %USERPROFILE%\.codex-control-mcp\state\recoverable-tasks.sqlite3，使用 SQLite WAL。任务记录 goal、steps、completion conditions、checkpoint、blocker、revision、event history 和 final review。只有全部步骤完成且 final review 为 pass 后才能 complete。

Multi-Host

• host_manage

• host_exec

• host_files

• host_route

支持 local / mcp / ssh / docker。优先使用远端 Codex-Control-MCP MCP 节点，没有节点时可使用 SSH；Docker 用于本机容器路由。

Dynamic MCP

• mcp_manage：register / update / list / get / enable / disable / refresh / remove

• mcp_tool_search

• mcp_tool_inspect

• mcp_tool_call

支持 stdio 与 streamable HTTP。第三方 MCP schema 会缓存，并在调用前用 JSON Schema 校验参数。

当前正式注册：

• director → DirectorDesk-MCP，18 tools（17 场景工具 + 1 非执行宿主任务工具）

• grok → Grok-MCP，3 tools

Skill 生命周期

skill_package 支持 validate / install / activate / rollback / uninstall / list / inspect，支持本地目录、ZIP 和 Git URL，提供 SHA-256 校验、stable/development/canary/pinned 通道、版本激活与回滚。

源码生产方式

从 0.2.0 起，日常开发和生产默认都直接运行源码，不再为每次更新执行 PyInstaller 打包。

cd 'C:\path\to\Codex-Control-MCP'
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m pytest -q -m "not integration"

生产计划任务 Codex-Control-MCP-OnDemand 直接运行：

C:\path\to\Codex-Control-MCP\.venv\Scripts\python.exe
-m codex_control_mcp --home %USERPROFILE%\.codex-control-mcp serve --transport streamable-http

HTTPS 计划任务 Codex-Control-MCP-HTTPS-OnDemand 同样使用该 venv 运行 tunnel。

正常更新流程：

修改源码 → pytest → 独立控制器重启源码 Core → MCP/能力验收 → 再固化已验证 LKG

只有明确需要向没有 Python 环境的外部机器分发时，才单独考虑构建二进制。仓库中的旧打包脚本仅作为历史工具保留，不属于默认发布流程。

自动恢复

Codex-Control-MCP-Watchdog 每分钟及用户登录时运行。连续两个真实周期观察到 8774 无监听才请求独立 Codex-Control-MCP-Core-Controller：

1. 正式 Codex-Control-MCP-OnDemand：editable 源码冷启动。

2. Codex-Control-MCP-Core-Current：独立任务直接运行当前源码。

3. Codex-Control-MCP-Core-LKG：独立任务设置 LKG 的 PYTHONPATH 后运行。

4. 每条候选必须验证实际 8774 监听、对应 service.json PID、认证 MCP initialize/version 和 47 工具；任务显示 Running 不等于通过。

5. 控制器有独立进程寿命、唯一请求 ID 队列、操作系统字节锁、有限超时、确定退出码和恢复报告。maintenance.lock.guard 是永久互斥文件，不是维护中标志；只有被进程持有的锁才生效，不能因一个遗留空 maintenance.lock 无限停掉 watchdog。

6. HTTPS 恢复另行保守判定：活着的 cloudflared 不因 Core 502 被重启；配置保持 protocol: http2、origin 127.0.0.1:8774，不添加错误的 edge-ip-version: 4。

安装/更新调度配置（管理员 PowerShell；安装会备份原任务，不主动重启服务）：

.\scripts\Install-Core-RecoveryTasks.ps1 -Apply

正常重载只提交请求，不从 Core 派生一个负责拉回自己的控制器：

.\scripts\Request-Core-Restart.ps1

旧 state/final-core-reload.ps1 已改为上述提交入口的兼容包装，不再直接停止 Core。提交成功只代表 accepted，最终结果读 %USERPROFILE%\.codex-control-mcp\state\core-controller-report.json，并实调公网 MCP。

退出码：0 已启动/已健康；10 另一控制器持锁；21 旧端口未释放；22 无监听但存在其他活源码 host；30 三条候选全部失败；40 配置/内部错误。失败不会冒充回滚成功。

正式任务具备 AtStartup/AtLogon，使用用户交互式会话，不保存用户密码或改用 S4U。已验真实冷启动；未通过注销或重启 Windows 验证登录/开机，不宣称无人登录前可用。

当前 LKG：%USERPROFILE%\.codex-control-mcp\state\lkg-0.2.0。

独立组件

DirectorDesk-MCP

源码：C:\path\to\DirectorDesk-MCP

独立 bridge key：%USERPROFILE%\.director-desk-mcp\state\bridge.key。不再依赖旧 director-desk-gateway 目录。

Grok-MCP

源码：C:\path\to\Grok-MCP

Grok-MCP 不复制 API Key；通过 GROK_MCP_CREDENTIAL_PATH 引用现有 Windows DPAPI 凭据文件，密钥不进入 Dynamic MCP 注册表返回值。

验收基线

2026-09-10 最后回归与当前边界（详细结果以 evidence/architecture-0.2.0-final.json 为准，不能只看本表当全绿）：

• Core 非集成回归：240 passed，18 integration deselected

• Core 顶层工具：47

• 静态 grok_*：0

• DirectorDesk-MCP：17 tools，director_read 实调成功

• Grok-MCP：3 tools，独立生图实调成功

• 公网 OAuth metadata/challenge 正常

• 公网 MCP：47 tools，bridge_version=0.2.0

• Dynamic MCP：director=17 ready，grok=3 ready

• Grok-MCP 回归：12 passed；DirectorDesk-MCP 回归：1 passed。

• Recoverable Task、Multi-Host local/MCP/file roundtrip、Skill 生命周期真实生产验收通过；SSH/Docker 只验协议/路由契约，不冒充真实远端执行。

• Browser 的 start/snapshot/fill/click/press/scroll/navigate/close 已真实通过；测试仅使用隔离页并关闭临时 HTTP server。

• Proxy PASS 要求官方 Codex command/exec 子进程继承代理，实际 CONNECT 到 127.0.0.1:7897，经系统信任库完成 TLS 证书验证并取得 HTTPS 成功响应，不能拿裸 HTTPS 200 推断代理链路。

• Computer Use 返回成功不等于真实输入成功；失败会撤销旧 verified，type 必须观察到输入后文本才累计已验证动作。本轮发现官方 CUA 的输入/窗口激活问题，不能据此前虚假的计数报 healthy。

• Grok 改图冷却后仍返回 HTTP 502，状态未知。POST 不自动重放；超时和断连也标为 execution_state_unknown，GET/status 允许有限重试。已保存脱敏上游响应；真实部署源站日志仍缺失，不能推测已经修好。生图/视频历史有效产物保留，不重复消费生成额度。

• 旧 director-desk-gateway 空目录仍被现有 DirectorDesk 工作目录持有，已登记下次 Windows 重启删除；没有为了删空目录重启用户服务。

LKG 与证据范围

scripts/freeze_source_lkg.py 可生成独立源码候选、隔离导入核对 0.2.0/47 工具/无静态 Grok 或 Director/默认 8774，并写 UTF-8 manifest 与逐文件 SHA256。默认只生成候选；只有验收范围明确且通过后才使用 --activate。快照不包含凭据，不等于把未通过的外部 GUI/Grok 能力认证为通过，packaging_required=false。