# 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 展示零成本。

## 安装

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

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

```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)。

## 测试

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