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 分钟)。

Related MCP server: Claude Code MCP

工具

消息分级

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}。

环境变量

可选增强

• 状态行: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)