Codex Manager MCP

Disclaimer: This project is not affiliated with or endorsed by OpenAI. "OpenAI Codex" is a trademark of OpenAI. This tool merely wraps and manages the locally-installed Codex CLI using the user's own login; it does not bypass authentication, scrape, or redistribute any OpenAI proprietary content.

一个在 Claude Code 里管理本机 codex CLI 会话的 MCP 服务器。它直接 spawn codex exec 子进程并统一管理:启动、状态、消息、中途注入、停止、消息 hook、崩溃自动重启、外部会话采纳。

核心理念: 每个 codex 任务就是一个由本 manager 启动的 codex exec 进程。codex_run 是阻塞式工具调用,Claude Code 客户端会自动后台化超时的调用——因此每个运行中的 codex 任务自动成为 Claude Code 的原生后台任务,计入底部 "N background tasks",完成时任务通知唤醒 agent。UI 展示零成本。

安装

npm install          # 安装依赖
npm run build        # 编译到 dist/

配置到 Claude Code(.mcp.json 或 ~/.claude/settings.json):

{
  "mcpServers": {
    "codex-manager": {
      "command": "node",
      "args": ["~/codex-manager/dist/src/index.js"]
    }
  }
}

建议(唤醒/后台化): 启动 Claude Code 时设 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=1000,让 codex_run 约 1 秒后自动转入后台,完成时以任务通知唤醒 agent(无需等默认的 2 分钟)。

工具

工具	说明
codex_run	启动 codex 任务(镜像 codex exec 参数)。wait 默认 true(阻塞→自动后台化);wait:false 即发即弃。支持 resumeSessionId 续接。
codex_list	查询任务状态。ended:N 包含最近 N 个已结束任务(默认 0)。含 token 明细、耗时、退出码、最后消息等。
codex_messages	查询某任务消息。level/types/since/tail/limit/fromFile 过滤;fromFile 默认从磁盘会话文件读(权威);未指定 tail/limit 时默认最近 100 条。
codex_send	向运行中任务注入消息(codex exec resume),实现中途通信。
codex_stop	停止/杀死任务。
codex_hook	消息 hook 增/删/列。
codex_discover	扫描外部 codex 会话(只读,不含已采纳的)。
codex_adopt	把外部会话纳入本 manager 管理(纳入后可 send/messages/stop/hook)。

消息分级

codex_messages 的 level 取值:user / commentary(agent 实时评论)/ final(回合最终输出)/ reasoning / tool(工具调用)/ result(工具结果)/ event(会话事件)/ token(用量)。

Hook 示例

codex_hook add {pattern:"ERROR", match:"contains", level:"commentary"}
codex_hook add {pattern:"\\d{3} tokens", match:"regex", id:3}   # 仅任务3
codex_hook list
codex_hook remove {hookId:"..."}

命中后 hook 的 hitCount 递增。若命中消息属于阻塞中的 codex_run,完成通知会一并携带。

外部会话

1. codex_discover 列出近期外部会话(只读)。
2. codex_adopt {sessionId} 纳入管理 → 出现在 codex_list,可 send/messages/hook。
3. 未采纳的会话不能执行任何操作。

自动重启(失败重连)

• 启动失败或非正常退出(exit≠0)→ 1 分钟后自动重启,最多 maxAttempts(默认 3)次。
• 第 3 次仍失败 → 任务状态 failed + 通知。
• 单任务可覆盖:codex_run {..., maxAttempts:5}。

环境变量

变量	作用	默认
CODEX_MANAGER_STATE	状态文件路径	~/.codex-manager/state.json
CODEX_MANAGER_CODEX_PATH	显式指定 codex 可执行文件(否则自动解析)	自动解析
CODEX_MANAGER_CODEX_WINDOWS_HIDE	设为 1 用 CREATE_NO_WINDOW 隐藏 codex 窗口(仅无控制台环境需要;正常终端下保持关闭,否则其子进程反而会各自弹黑窗)	关闭
CODEX_MANAGER_CHANNELS	设为 1 启用 claude/channel 推送(需以 --dangerously-load-development-channels server:codex-manager 启动 Claude Code)	关闭
CODEX_HOME	codex 配置/会话目录(若非常规位置)	~/.codex

可选增强

• 状态行:scripts/statusline.mjs 输出 n codex,配置 statusLine + refreshInterval:2。codex 任务本身会被自动计入底部后台任务计数,通常无需此脚本。
• /codex 页面:commands/codex.md 是 prompt 型斜杠命令,让 Claude 渲染任务状态页。
• Channels 推送:完成/hook 命中事件主动唤醒 agent(需 CODEX_MANAGER_CHANNELS=1 + 启动 flag,research preview)。

测试

npm test                                   # 单元测试(vitest)
CODEX_MANAGER_INTEGRATION=1 node scripts/smoke-integration.mjs   # 真实 codex 端到端(消耗少量 token)