使用说明
子索引
Claude Code的MCP服务器使用OpenAI Codex作为子代理，具有失速检测和自动恢复功能。
为什么是subdex？
克劳德法典和食品法典委员会具有互补优势：
| 角色 | 克劳德代码 | 法典 |
|---|---|---|
| 类比 | 了解需求的产品经理 | 专注的技术专家 |
| 优势 | 规划、沟通、上下文理解 | 编码、调试、实现 |
| 最擅长 | 分解任务、编写规范、验证 | 编写代码、修复错误、重构 |
子索引 连接这两者，让Claude Code作为子代理协调Codex：
- Claude Code处理“什么”和“为什么”（需求、计划、验证）
- Codex处理“如何”（实现、调试）
这种组合比单独使用任何一种工具都能提供更好的结果。
特性
- 以流式进度运行Codex会话
- 自动失速检测（可配置超时）
- 停滞时自动恢复尝试
- 进度记录到
~/.claude/codex-logs/ - 通过以下方式支持线程延续
codex-reply
使用模式
在您的 CLAUDE.md 控制何时使用子索引：
模式1：完全子代理
所有代码修改都要经过子代码。克劳德只做分析、计划和验证。
## Subagent Mode: full-subagent
All code changes must go through `mcp__subcodex__run`:
- Claude: analyze, plan, write Codex Contract, verify results
- Subcodex: all file edits, code generation, refactoring
模式2：基于目录
不同的目录由不同的执行器处理。
## Subagent Mode: directory-based
| Scope | Executor |
|-------|----------|
| `apps/web/**/*` | Claude direct |
| `apps/api/**/*`, `packages/**/*` | subcodex |
| docs, config | Claude direct |
模式3：回退
克劳德处理了所有事情，但在失败时又回到了子索引。
## Subagent Mode: fallback
- Claude attempts all code changes directly
- After 2 failed attempts → automatically use subcodex
- Windows file lock errors → immediately use subcodex
安装
来自npm
npx subcodex-mcp
来源
git clone https://github.com/G0d2i11a/subcodex.git
cd subcodex
pnpm install
pnpm build
配置
添加到您的Claude Code MCP配置中(~/.claude.json):
{
"mcpServers": {
"subcodex": {
"command": "npx",
"args": ["-y", "subcodex-mcp"],
"env": {},
"type": "stdio"
}
}
}
或者为了当地发展：
{
"mcpServers": {
"subcodex": {
"command": "node",
"args": ["/path/to/subcodex/dist/index.js"],
"env": {},
"type": "stdio"
}
}
}
工具
run
启动新的食品法典委员会会议。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt |
string | Yes | 发送到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 | No | 检测到停滞前的不活动分钟数（默认值：5） |
maxRecoveryAttempts |
number | No | 挂起时的最大自动恢复尝试次数（默认值：2） |
reply
继续现有的Codex对话。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
threadId |
string | 是 | 前一个会话的线程ID |
prompt |
string | Yes | 下一个继续对话的提示 |
level |
string | 否 | 日志命名的执行级别 |
stallTimeoutMinutes |
number | No | 检测到停滞前的不活动分钟数（默认值：5） |
maxRecoveryAttempts |
number | No | 挂起时的最大自动恢复尝试次数（默认值：2） |
失速检测
服务器监控Codex会话的活动。如果在超时时间内没有收到任何事件：
- 将会话标记为已暂停
- 通过发送恢复提示尝试自动恢复
- 退回至
maxRecoveryAttempts时代 - 退货
TIMEOUT状态与needsUserInput: true如果所有恢复尝试都失败
处理 needsUserInput
当响应包含 needsUserInput: true，克劳德应该使用 AskUserQuestion 询问用户如何继续。将此规则添加到您的CLAUDE.md：
## Subcodex Stall Handling
When `mcp__subcodex__run` returns `needsUserInput: true`:
- Use AskUserQuestion to ask the user how to proceed
- Options: retry, skip current task, manual intervention
响应格式
{
"threadId": "abc123...",
"level": "L2",
"content": "Final response from 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
}
当停滞且恢复失败时：
{
"threadId": "abc123...",
"level": "L2",
"content": "",
"progressLog": "~/.claude/codex-logs/progress-L2-xxx-TIMEOUT.log",
"recovery": {
"attempted": true,
"attempts": 2,
"recovered": false,
"lastError": "Still stalled after recovery attempt"
},
"needsUserInput": true
}
结果级别
日志文件将使用结果级别后缀重命名：
PASS-成功（日志文件已删除）FAIL-命令或文件更改失败ERROR-发生异常TIMEOUT-停滞，恢复失败
需求
- Node.js 18+
- 已配置OpenAI Codex SDK凭据
许可证
麻省理工学院
