MCP server for running OpenAI Codex as a subagent with stall detection and auto-recovery
npm install subcodex-mcp~/.claude/codex-logs/
codex-reply 支持会话续接
CLAUDE.md 中配置,控制何时使用 subcodex:
markdown
Subagent Mode: full-subagent
所有代码修改必须通过 mcp__subcodex__run:
- Claude:分析、规划、编写 Codex Contract、验证结果
- Subcodex:所有文件编辑、代码生成、重构
`
$3
不同目录由不同执行者处理。
`markdown
Subagent Mode: directory-based
| 范围 | 执行者 |
|------|--------|
| apps/web/*/ | Claude 直接执行 |
| apps/api//, packages// | subcodex |
| 文档、配置 | Claude 直接执行 |
`
$3
Claude 处理所有任务,失败时降级到 subcodex。
`markdown
Subagent Mode: fallback
- Claude 直接尝试所有代码修改
- 失败 2 次后 → 自动使用 subcodex
- Windows 文件锁错误 → 立即使用 subcodex
`
安装
$3
`bash
npx subcodex-mcp
`
$3
`bash
git clone https://github.com/G0d2i11a/subcodex.git
cd subcodex
pnpm install
pnpm build
`
配置
添加到 Claude Code MCP 配置 (~/.claude.json):
`json
{
"mcpServers": {
"subcodex": {
"command": "npx",
"args": ["-y", "subcodex-mcp"],
"env": {},
"type": "stdio"
}
}
}
`
或本地开发:
`json
{
"mcpServers": {
"subcodex": {
"command": "node",
"args": ["/path/to/subcodex/dist/index.js"],
"env": {},
"type": "stdio"
}
}
}
`
工具
$3
启动新的 Codex 会话。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| prompt | string | 是 | 发送给 Codex 的提示词 |
| cwd | string | 否 | 会话的工作目录 |
| model | string | 否 | 模型覆盖(如 'gpt-5.2') |
| sandboxMode | string | 否 | read-only、workspace-write 或 danger-full-access |
| approvalPolicy | string | 否 | never、on-request、on-failure 或 untrusted |
| level | string | 否 | 执行级别:L1、L2、L3、L4(用于日志命名) |
| stallTimeoutMinutes | number | 否 | 检测卡顿的超时分钟数(默认:5) |
| maxRecoveryAttempts | number | 否 | 卡顿时最大自动恢复次数(默认:2) |
$3
继续现有的 Codex 会话。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| threadId | string | 是 | 上一次会话的线程 ID |
| prompt | string | 是 | 继续会话的下一个提示词 |
| level | string | 否 | 日志命名的执行级别 |
| stallTimeoutMinutes | number | 否 | 检测卡顿的超时分钟数(默认:5) |
| maxRecoveryAttempts | number | 否 | 卡顿时最大自动恢复次数(默认:2) |
卡顿检测
服务器监控 Codex 会话的活动。如果在超时时间内没有收到事件:
1. 标记会话为卡顿
2. 发送恢复提示尝试自动恢复
3. 最多重试 maxRecoveryAttempts 次
4. 如果所有恢复尝试都失败,返回 TIMEOUT 状态和 needsUserInput: true
$3
当响应包含 needsUserInput: true 时,Claude 应使用 AskUserQuestion 询问用户如何继续。在 CLAUDE.md 中添加此规则:
`markdown
Subcodex 卡顿处理
当 mcp__subcodex__run 返回 needsUserInput: true 时:
- 使用 AskUserQuestion 询问用户如何继续
- 选项:重试、跳过当前任务、手动干预
`
响应格式
`json
{
"threadId": "abc123...",
"level": "L2",
"content": "Codex 的最终响应",
"progressLog": "~/.claude/codex-logs/progress-L2-xxx-PASS.log",
"stats": {
"totalItems": 10,
"commands": 3,
"fileChanges": 2,
"mcpCalls": 0,
"usage": {
"input_tokens": 1000,
"output_tokens": 500
}
},
"filesModified": ["create: src/foo.ts", "modify: src/bar.ts"],
"recovery": {
"attempted": false
},
"needsUserInput": false
}
`
卡顿且恢复失败时:
`json
{
"threadId": "abc123...",
"level": "L2",
"content": "",
"progressLog": "~/.claude/codex-logs/progress-L2-xxx-TIMEOUT.log",
"recovery": {
"attempted": true,
"attempts": 2,
"recovered": false,
"lastError": "恢复尝试后仍然卡顿"
},
"needsUserInput": true
}
`
结果级别
日志文件以结果级别后缀重命名:
- PASS - 成功(日志文件删除)
- FAIL - 命令或文件修改失败
- ERROR - 发生异常
- TIMEOUT` - 卡顿且恢复失败