名称： claude-code-supervisor
描述： >
监控运行在 tmux 中的 Claude Code 会话。使用 Claude Code 钩子配合 bash 预过滤（方案 D）和快速 LLM 分类，以检测错误、卡住的智能体及任务完成情况。与执行框架无关——适用于 OpenClaw、webhooks、ntfy 或任何通知后端。适用于以下场景：(1) 启动需要监控的长时间运行的 Claude Code 任务，(2) 为 API 错误或意外停止设置自动提醒，(3) 从后台编码智能体获取进度报告，(4) 在会话/上下文限制重置后继续工作。
要求：tmux, claude CLI。
元数据：
{
"openclaw":
{
"emoji": "👷",
"os": ["darwin", "linux"],
"requires": { "bins": ["tmux"], "anyBins": ["claude"] },
},
}
连接 Claude Code 生命周期钩子与你的智能体执行框架。
Claude Code (在 tmux 中)
│ 停止 / 错误 / 通知
▼
Bash 预过滤器 (方案 D)
│ 直接处理明显情况
│ 模糊情况向下传递
▼
快速 LLM 分类 (使用 claude -p 配合 Haiku，或本地 LLM)
│ 分类：FINE | NEEDS_NUDGE | STUCK | DONE | ESCALATE
│ FINE → 静默记录日志
▼
通知命令 (可配置)
│ openclaw wake, webhook, ntfy, 脚本等
▼
智能体执行框架决策 + 行动
│ 提醒 (向 tmux 发送按键)、等待、升级至人工处理
{baseDir}/scripts/install-hooks.sh /path/to/your/project
创建：
- .claude/hooks/supervisor/ — 钩子脚本与分类逻辑
- .claude/settings.json — 接入 Claude Code 生命周期
- .claude-code-supervisor.yml — 配置文件 (编辑此文件)
编辑 .claude-code-supervisor.yml：
triage:
command: "claude -p --no-session-persistence" # 或: ollama run llama3.2
model: "claude-haiku-4-20250414"
notify:
command: "openclaw gateway call wake --params" # 或: curl, ntfy, script
创建 ~/.openclaw/workspace/supervisor-state.json (或你的执行框架存放状态的位置)：
{
"sessions": {
"my-task": {
"socket": "/tmp/openclaw-tmux-sockets/openclaw.sock",
"tmuxSession": "my-task",
"projectDir": "/path/to/project",
"goal": "修复问题 #42",
"successCriteria": "测试通过，代码已提交",
"maxNudges": 5,
"escalateAfterMin": 60,
"status": "running"
}
}
}
SOCKET="/tmp/openclaw-tmux-sockets/openclaw.sock"
tmux -S "$SOCKET" new -d -s my-task
tmux -S "$SOCKET" send-keys -t my-task "cd /path/to/project && claude '修复问题 #42'" Enter
钩子会自动触发。分类器进行评估。你只会在需要时收到通知。
并非每个钩子事件都需要调用 LLM。Bash 首先捕获明显情况：
| 信号 | Bash 决策 | 需要 LLM 分类？ |
|---|---|---|
max_tokens |
总是需要关注 | ✅ 是 |
end_turn + shell 提示符返回 |
智能体可能已完成 | ✅ 是 |
end_turn + 无提示符 |
智能体正在工作中 | ❌ 跳过 |
stop_sequence |
正常情况 | ❌ 跳过 |
| 信号 | Bash 决策 | 需要 LLM 分类？ |
|---|---|---|
| API 429 / 速率限制 | 暂时性错误，会自行恢复 | ❌ 仅记录日志 |
| API 500 | 智能体可能卡住 | ✅ 是 |
| 其他工具错误 | 未知严重性 | ✅ 是 |
| 信号 | Bash 决策 | 需要 LLM 分类？ |
|---|---|---|
auth_* |
内部、暂时性 | ❌ 跳过 |
permission_prompt |
需要决策 | ✅ 是 |
idle_prompt |
智能体正在等待 | ✅ 是 |
LLM 返回以下结果之一：
| 判定 | 含义 | 典型操作 |
|---|---|---|
| FINE | 智能体工作正常 | 静默记录日志，不发送通知 |
| NEEDS_NUDGE | 暂时性错误，应继续 | 向 tmux 发送 "continue" |
| STUCK | 循环或未取得进展 | 尝试不同方法或升级处理 |
| DONE | 任务成功完成 | 向人工报告 |
| ESCALATE | 需要人工判断 | 附带上下文通知人工 |
唤醒事件以 cc-supervisor: 为前缀，后跟分类结果：
cc-supervisor: NEEDS_NUDGE | error:api_500 | cwd=/home/user/project | ...
cc-supervisor: DONE | stopped:end_turn:prompt_back | cwd=/home/user/project | ...
tmux -S "$SOCKET" send-keys -t "$SESSION" "continue — the API error was transient" Enter
关于何时提醒、何时升级以及静默时段，请参阅 references/escalation-rules.md。
钩子依赖于 Claude Code 处于活动状态。如果会话硬崩溃、达到账户限制或进程被 OOM 杀死，则钩子不会触发。看门狗负责捕获此类情况。
scripts/watchdog.sh 是一个纯 bash 脚本（不依赖 LLM 或 Claude Code），它：
1. 读取 supervisor-state.json 中所有 "running" 状态的会话
2. 检查：tmux socket 是否存活？会话是否存在？Claude Code 是否仍在运行？
3. 如果某物已死且没有钩子报告它 → 通过配置的命令发送通知
4. 在状态中更新 lastWatchdogAt 以进行跟踪
定时运行它。选择你喜欢的方式：
系统 cron：
*/15 * * * * /path/to/claude-code-supervisor/scripts/watchdog.sh
OpenClaw cron：
{
"schedule": { "kind": "every", "everyMs": 900000 },
"payload": { "kind": "systemEvent", "text": "cc-supervisor: watchdog — run /path/to/scripts/watchdog.sh and report" },
"sessionTarget": "main"
}
systemd 定时器、launchd，或任何在你的机器上周期性运行的工具。
看门狗故意设计得很简单——没有 LLM，没有复杂逻辑，只检查“进程是否还在？”。这意味着即使分类模型宕机、API 崩溃或你的账户达到限制，它也能工作。这是双重保险。
scripts/install-hooks.sh — 每个项目一键式设置scripts/hooks/on-stop.sh — 停止事件处理器，带 bash 预过滤scripts/hooks/on-error.sh — PostToolUseFailure 处理器，带 bash 预过滤scripts/hooks/on-notify.sh — 通知处理器，带 bash 预过滤scripts/triage.sh — LLM 分类 (由钩子为模糊情况调用)scripts/lib.sh — 共享的配置加载和通知函数scripts/watchdog.sh — 死会话检测器 (纯 bash，无 LLM 依赖)references/state-patterns.md — 终端输出模式匹配指南references/escalation-rules.md — 何时提醒、升级或等待的规则supervisor.yml.example — 配置示例