Claude代码监督器

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

架构

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. 在项目中安装钩子

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

创建：

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

2. 配置

编辑.claude-code-supervisor.yml：

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（或您的框架保存状态的任意位置）：

{
  "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代码

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

on-error.sh

on-notify.sh脚本

分类类别

LLM返回以下之一：

处理通知（供代理框架作者参考）

唤醒事件到达时带有前缀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推动

tmux -S "$SOCKET" send-keys -t "$SESSION" "continue — the API error was transient" Enter

升级格式

参见参考资料/escalation-rules.md关于何时进行提醒、何时升级处理以及静默时段的规定。

看门狗机制（谁来监督监督者？）

钩子功能依赖于Claude Code处于活跃状态。如果会话发生硬崩溃、达到账户限制，或者进程因内存不足被终止，则所有钩子都不会触发。看门狗机制负责捕捉此类情况。

脚本文件：scripts/watchdog.sh这是一个纯bash脚本（无需LLM，不依赖Claude Code），其功能包括：

1. 读取supervisor-state.json文件获取所有"运行中"的会话信息
2. 检查项目：tmux套接字是否存活？会话是否存在？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 timer、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— 示例配置