Claude Code 监督器

连接 Claude Code 生命周期钩子与您的代理框架之间的桥梁。

架构

Claude Code（在 tmux 中）
│ 停止 / 错误 / 通知
▼
Bash 预过滤器（选项 D）
│ 明显情况直接处理
│ 模糊情况传递下去
▼
快速 LLM 分类（使用 Haiku 的 claude -p，或本地 LLM）
│ 分类：正常 | 需要提示 | 卡住 | 完成 | 升级
│ 正常 → 静默记录
▼
通知命令（可配置）
│ openclaw 唤醒、webhook、ntfy、脚本等
▼
代理框架决策并执行
│ 提示（向 tmux 发送按键）、等待、升级给人类

快速开始

1. 将钩子安装到项目中

bash
{baseDir}/scripts/install-hooks.sh /path/to/your/project

创建：

• - .claude/hooks/supervisor/ — 钩子脚本 + 分类
• .claude/settings.json — 接入 Claude Code 生命周期
• .claude-code-supervisor.yml — 配置（编辑此文件）

2. 配置

编辑 .claude-code-supervisor.yml：

yaml
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, 脚本

3. 注册受监督的会话

创建 ~/.openclaw/workspace/supervisor-state.json（或您的框架保存状态的任何位置）：

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

4. 在 tmux 中启动 Claude Code

bash
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

钩子自动触发。分类进行评估。只有在必要时您才会收到通知。

预过滤器如何工作（选项 D）

并非每个钩子事件都需要 LLM 调用。Bash 首先捕获明显的情况：

on-stop.sh

信号	Bash 决策	LLM 分类？
maxtokens	总是需要关注	✅ 是
endturn + shell 提示符返回

代理可能已完成 | ✅ 是 |

on-error.sh

信号	Bash 决策	LLM 分类？
API 429 / 速率限制	临时性，会自行解决	❌ 仅记录
API 500

代理可能卡住 | ✅ 是 |

on-notify.sh

信号	Bash 决策	LLM 分类？
auth*	内部，临时性	❌ 跳过
permissionprompt

需要决策 | ✅ 是 |

分类结果

LLM 返回以下之一：

处理通知（供代理框架开发者使用）

唤醒事件以 cc-supervisor: 前缀开头，后跟分类：

cc-supervisor: 需要提示 | error:api_500 | cwd=/home/user/project | ...
cc-supervisor: 完成 | stopped:endturn:promptback | cwd=/home/user/project | ...

通过 tmux 发送提示

bash
tmux -S $SOCKET send-keys -t $SESSION 继续 — API 错误是临时性的 Enter

升级格式

请参阅 references/escalation-rules.md 了解何时提示、何时升级以及静默时段。

看门狗（谁来监视监视者？）

钩子依赖于 Claude Code 保持运行。如果会话硬崩溃、达到账户限制或进程被 OOM 杀死，则不会触发任何钩子。看门狗负责捕获这种情况。

scripts/watchdog.sh 是一个纯 bash 脚本（无 LLM，无 Claude Code 依赖），它：

1. 1. 读取 supervisor-state.json 中所有运行中的会话
2. 检查：tmux 套接字是否存活？会话是否存在？Claude Code 是否仍在运行？
3. 如果某些内容已死亡且没有钩子报告 → 通过配置的命令通知
4. 更新状态中的 lastWatchdogAt 用于跟踪

定时运行它。选择您的方式：

系统 cron：
bash
/15 * /path/to/claude-code-supervisor/scripts/watchdog.sh

OpenClaw cron：
json
{
schedule: { kind: every, everyMs: 900000 },
payload: { kind: systemEvent, text: cc-supervisor: watchdog — 运行 /path/to/scripts/watchdog.sh 并报告 },
sessionTarget: main
}

systemd 定时器、launchd 或任何在您的机器上定期运行的程序。

看门狗故意设计得简单 — 无 LLM，无复杂逻辑，只检查进程是否还在？这意味着即使分类模型宕机、API 熔断或您的账户达到限制，它也能工作。双重保险。

文件

• - scripts/install-hooks.sh — 每个项目一键设置
• scripts/hooks/on-stop.sh — 带 Bash 预过滤器的停止事件处理器
• scripts/hooks/on-error.sh — 带 Bash 预过滤器的 PostToolUseFailure 处理器
• 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 — 示例配置