EudOnline/openclaw-watchdog
GitHub: EudOnline/openclaw-watchdog
一款面向生产环境的 OpenClaw 网关外部监控与自动恢复工具套件，通过分层健康检查、保守修复策略和事件追溯机制保障服务高可用。
Stars: 0 | Forks: 0
# OpenClaw Watchdog
[](https://github.com/EudOnline/openclaw-watchdog/releases/tag/v0.1.0)
[](LICENSE)
[](pyproject.toml)
一个面向生产环境的 OpenClaw 外部监控与恢复工具套件。
## 概要 (TL;DR)
OpenClaw Watchdog 旨在帮助运维人员安全、快速地恢复可用的 OpenClaw 对话路径。
它结合了：
- 跨进程、服务和对话就绪状态的健康检查
- 保守的恢复和面向回滚的工作流
- 面向运维人员的事件、报告和指标输出
- 源码优先部署，附带 `systemd --user` 示例单元
- 演练场景，用于在依赖实时主机上的更改之前进行验证
## 快速链接
- [发行说明](https://github.com/EudOnline/openclaw-watchdog/releases/tag/v0.1.0)
- [文档索引](docs/README.md)
- [兼容性与弃用](docs/compatibility-and-deprecations.md)
- [路线图](docs/roadmap.md)
- [常见问题 (FAQ)](docs/faq.md)
- [演练指南](rehearsal/README.md)
## 亮点
- 用于 OpenClaw 网关健康检查和补救的 **外部监控循环**
- **分层健康模型**：进程、服务探测和对话就绪状态
- **事件工作流**：包含排队、所有权、确认、备注和时间线
- 用于回滚、偏差检测和修复排序的 **安全防护**
- 用于 OpenClaw、Codex 和 OpenCode 切换流程的 **引导 / 回退辅助**
- 用于测试预期故障和恢复路径的 **演练场景**
- 用于在 Linux 上执行无人值守定时任务的 **Systemd 用户单元**
## 状态
本仓库是 **OpenClaw Watchdog** 独立的公开主页。
面向公众的接口现已在整个仓库中使用非 `v2` 名称。内部 Python 包名称仍保留为 `watchdog_v2`，以维护实现的稳定性，并避免在导入、演练工具和历史记录中造成不必要的变动。
## 仓库结构
```
watchdog_v2/ Python implementation
scripts/ CLI wrappers and install helpers
systemd/ sample user service + timer units
docs/ current guides, validation docs, and historical notes
config/ sanitized example env files
rehearsal/ fixtures, shims, scenarios, and test flows
```
## 需求
- Python 3.11+
- 目标机器上已安装 OpenClaw
- 如果需要使用提供的定时器单元，需要带有 `systemd --user` 的 Linux
- 监控或演练流程所使用的标准主机工具（取决于启用的功能）：
- `systemctl`
- `ss`
- `ps`
- `journalctl`
## 安装
### 选项 1：从克隆的仓库运行
```
git clone https://github.com/EudOnline/openclaw-watchdog ~/openclaw-watchdog
cd ~/openclaw-watchdog
cp config/openclaw-watchdog.env.example config/openclaw-watchdog.env
chmod +x scripts/openclaw-watchdog scripts/install-openclaw-watchdog-units.sh
```
快速完整性检查：
```
scripts/openclaw-watchdog --help
scripts/openclaw-watchdog check --env config/openclaw-watchdog.env
```
### 选项 2：Python 模块入口点
如果您是基于源码检出版本进行操作，也可以直接调用该包：
```
python3 -m watchdog_v2 --help
```
## 配置
从这里开始：
- `config/openclaw-watchdog.env.example`
重要的配置项包括：
- OpenClaw 配置路径和网关服务名称
- watchdog 状态 / 事件目录
- 重启和探测宽限期
- 服务级故障阈值
- 通知目标 / 渠道
- 备份 / 回滚行为
- Codex / OpenCode 回退设置
示例配置已经过有意清理。您必须设置适合您自己主机的值。
## 常用命令
```
# 一次 remediation pass
scripts/openclaw-watchdog run-once
# 不带 remediation 的健康检查
scripts/openclaw-watchdog check
# 人工状态摘要
scripts/openclaw-watchdog status --summary
# compact operator 报告
scripts/openclaw-watchdog report
# 检查 incident 队列
scripts/openclaw-watchdog incidents queue
# 显示单个 incident
scripts/openclaw-watchdog incidents show
# 启用维护模式
scripts/openclaw-watchdog maintenance on --reason "planned maintenance"
```
## 安装 systemd 用户单元
示例单元假设仓库位于 `~/openclaw-watchdog`。
```
git clone https://github.com/EudOnline/openclaw-watchdog ~/openclaw-watchdog
cd ~/openclaw-watchdog
cp config/openclaw-watchdog.env.example config/openclaw-watchdog.env
scripts/install-openclaw-watchdog-units.sh
systemctl --user enable --now openclaw-watchdog.timer
```
检查状态：
```
systemctl --user status openclaw-watchdog.timer
systemctl --user status openclaw-watchdog.service
```
## 演练与验证
本仓库包含一个演练工具，用于在不使用实时生产网关的情况下验证流程。
从这里开始：
- `docs/README.md`
- `rehearsal/README.md`
- `docs/live-acceptance-checklist.md`
- `docs/live-samples.md`
- `docs/compatibility-and-deprecations.md`
- `docs/roadmap.md`
- `docs/faq.md`
- `docs/history/MIGRATION-v2.md`（历史迁移说明）
## 设计说明
该 watchdog 基于以下原则设计：
1. **仅在收集证据后进行修复**
2. **优先选择可逆的更改**
3. **将进程健康与实际可用性分开**
4. **保留对运维人员可见的事件轨迹**
5. **支持分阶段自动化，而非盲目重启循环**
## 兼容性说明
- 规范的 CLI 包装器：`scripts/openclaw-watchdog`
- 规范的环境示例：`config/openclaw-watchdog.env.example`
- 规范的 systemd 单元：`systemd/openclaw-watchdog.service` 和 `systemd/openclaw-watchdog.timer`
- 内部 Python 包名称仍为 `watchdog_v2` 以保证实现稳定性
- 仅保留了已弃用的兼容性垫片 (shims) 用于迁移：
- `scripts/openclaw-watchdog-v2`
- `scripts/install-openclaw-watchdog-v2-units.sh`
- `scripts/openclaw-watchdog-v2-live-acceptance.sh`
- 历史迁移说明保留在 `docs/history/MIGRATION-v2.md` 中
- 另请参阅：[docs/compatibility-and-deprecations.md](docs/compatibility-and-deprecations.md)
## 安全
请**不要**发布实时的 `.env` 文件、事件包或特定于主机的状态转储。有关报告指南和仓库维护说明，请参阅 [SECURITY.md](SECURITY.md)。
## 贡献
欢迎贡献、错误报告和清理 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
本项目根据 MIT 许可证授权。请参阅 [LICENSE](LICENSE)。
标签：OpenClaw, Python, Systemd, 事件管理, 健康检查, 异常检测, 故障修复, 无后门, 服务探针, 灾难恢复, 生产环境, 看门狗, 系统恢复, 网关守护, 自动回滚, 运维工具包, 运维自动化, 高可用性