介绍
# Claude Code Supervisor
连接 Claude Code 生命周期挂钩与您的 agent 驱动程序的桥梁。
## 架构
``` Claude Code (in tmux) │ Stop / Error / Notification ▼ Bash pre-filter (Option D) │ obvious cases handled directly │ ambiguous cases pass through ▼ Fast LLM triage (claude -p with Haiku, or local LLM) │ classifies: FINE | NEEDS_NUDGE | STUCK | DONE | ESCALATE │ FINE → logged silently ▼ Notify command (configurable) │ openclaw wake, webhook, ntfy, script, etc. ▼ Agent harness decides + acts │ nudge (send-keys to tmux), wait, escalate to human ```
## 快速开始
### 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" # or: ollama run llama3.2 model: "claude-haiku-4-20250414"
notify: command: "openclaw gateway call wake --params" # or: curl, ntfy, script ```
### 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": "Fix issue #42", "successCriteria": "Tests pass, committed", "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 'Fix issue #42'" Enter ```
挂钩自动触发。分诊进行评估。仅在必要时向您发出通知。
## 预过滤器的工作原理（选项 D）
并非每个挂钩事件都需要 LLM 调用。Bash 首先捕获明显的情况：
### on-stop.sh | 信号 | Bash 决策 | LLM 分诊？ | |--------|--------------|-------------| | `max_tokens` | 总是需要关注 | ✅ 是 | | `end_turn` + 返回 shell 提示符 | Agent 可能已完成 | ✅ 是 | | `end_turn` + 无提示符 | Agent 正在工作中 | ❌ 跳过 | | `stop_sequence` | 正常 | ❌ 跳过 |
### on-error.sh | 信号 | Bash 决策 | LLM 分诊？ | |--------|--------------|-------------| | API 429 / rate limit | 暂时性，会解决 | ❌ 仅记录 | | API 500 | Agent 可能卡住 | ✅ 是 | | 其他工具错误 | 严重程度未知 | ✅ 是 |
### on-notify.sh | 信号 | Bash 决策 | LLM 分诊？ | |--------|--------------|-------------| | `auth_*` | 内部，暂时性 | ❌ 跳过 | | `permission_prompt` | 需要决策 | ✅ 是 | | `idle_prompt` | Agent 等待中 | ✅ 是 |
## 分诊分类
LLM 返回以下结果之一：
| 结论 | 含义 | 典型操作 | |---------|---------|----------------| | **FINE** | Agent 工作正常 | 静默记录，不通知 | | **NEEDS_NUDGE** | 暂时性错误，应继续 | 向 tmux 发送 "continue" | | **STUCK** | 循环或无进展 | 尝试不同方法或上报 | | **DONE** | 任务成功完成 | 向人类报告 | | **ESCALATE** | 需要人类判断 | 带上下文通知人类 |
## 处理通知（供 agent 驱动程序开发者使用）
唤醒事件带有前缀 `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 轻推
```bash 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 套接字是否存活？会话是否存在？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 — run /path/to/scripts/watchdog.sh and report" }, "sessionTarget": "main" } ```
**systemd 计时器、launchd，或在您的机器上定期运行的任何工具。**
看门狗 deliberately 是“笨”的——没有 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` — 配置示例