基于 Bash 预过滤与 LLM 智能分类的 Claude Code 会话监控方案，实现无人值守任务的错误检测、自动恢复与状态通知，提升自动化编码代理的可靠性。
说明：
## 核心用法
Claude Code Supervisor 是一套专为长时间运行的 Claude Code 会话设计的监控基础设施。它通过拦截 Claude Code 的生命周期钩子（Stop、Error、Notification），结合 Bash 预过滤与轻量级 LLM 智能分类，实现对代理状态的实时感知与自动干预。
部署流程简洁：运行安装脚本将钩子注入目标项目，配置 YAML 文件指定分类模型与通知后端，随后在 tmux 中启动 Claude Code 任务即可。系统会自动识别会话异常（API 错误、上下文耗尽、任务完成等），并通过用户自定义的通知渠道（OpenClaw、Webhook、ntfy 等）上报，支持自动”轻推”（nudge）恢复或人工升级处理。
## 显著优点
**分层架构降低开销**：Bash 预过滤层（Option D）先处理明显场景（如正常停止、瞬态 429 错误），仅将模糊情况提交 LLM 分类，大幅减少 API 调用成本与延迟。
**Harness 无关设计**：不绑定特定代理框架，通过可配置的 `notify.command` 适配任意通知后端，从个人脚本到企业级编排系统均可集成。
**双重保障机制**：除钩子驱动的主动监控外，独立的 Watchdog 脚本以纯 Bash 实现（零 LLM 依赖），定期检测进程存活状态，防止 Claude Code 崩溃、OOM 或账户限流导致的监控盲区。
**精细的状态分类**：LLM 分类器输出五种明确状态（FINE / NEEDS_NUDGE / STUCK / DONE / ESCALATE），为下游自动化决策提供结构化输入。
## 潜在缺点与局限性
**基础设施依赖**：强制要求 tmux 与 Claude CLI，Windows 原生环境支持有限；本地 LLM 选项（如 Ollama）虽可降低云 API 依赖，但增加了部署复杂度。
**配置门槛**：YAML 配置、状态文件管理、tmux socket 权限等环节需要用户具备一定运维经验，非技术用户上手成本较高。
**通知延迟风险**：Bash 预过滤虽提升效率，但极端情况下可能误判（如将”接近完成”误判为”正常工作中”），导致通知延迟或遗漏。
**权限边界模糊**：通过 `send-keys` 向 tmux 会话注入输入的操作，若目标会话被恶意劫持，可能造成命令注入风险（尽管此风险主要源于 tmux 本身的安全配置）。
## 适合的目标群体
– 需要夜间/无人值守运行 Claude Code 任务的开发者与团队
– 已采用 OpenClaw、n8n、Huginn 等代理编排框架的高级用户
– 追求自动化故障恢复、减少人工监控成本的工程团队
– 具备 Bash 与 tmux 基础、愿意投入配置时间的运维人员
## 使用风险
**配置注入风险**：`triage.command` 与 `notify.command` 执行用户配置的任意命令，若配置文件被篡改，可能导致恶意代码执行。建议将配置文件纳入版本控制并设置只读权限。
**tmux 会话安全**：共享 tmux socket 或宽松权限设置可能允许未授权进程注入输入。应确保 socket 文件权限为 600，并限制访问用户。
**LLM 服务依赖**：云 API（Claude Haiku）可能因限流、故障或成本超支失效；本地模型虽可降级，但需额外维护 Ollama 等服务。
**日志与隐私**：尽管设计为本地优先，但通知内容可能包含项目路径、错误摘要等信息，若配置 webhook 指向第三方服务，需评估数据出境合规性。
**资源占用**：长时间监控大量会话时，Watchdog 的轮询机制与 LLM 分类调用可能产生不可忽视的计算与 API 成本。
会员专属
