OpenClaw Watchdog | OpenClaw 守門犬

為 OpenClaw Gateway 提供 24/7 監控與自動恢復的輕量級守護進程。

Overview

OpenClaw Watchdog 是一個純 Bash 編寫的背景守護程式，專為 OpenClaw 設計。它持續監控 Gateway 服務狀態與配置文件的完整性，當檢測到異常時自動執行恢復流程，並通過 Discord Webhook 即時通知管理員。

解決的問題

問題	Watchdog 的解決方案
Gateway 進程崩潰	秒級檢測並自動重啟
配置語法錯誤導致啟動失敗	自動回退到上次健康配置
人工編輯配置時被覆蓋	智能 Debounce + 寬限期機制
無法及時得知系統異常	Discord 即時告警推送

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw Watchdog v3.0                    │
│                      (Bash Daemon)                           │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
   │  Config     │    │  Gateway    │    │  Discord    │
   │  Monitor    │    │  Monitor    │    │  Webhook    │
   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘
          │                   │                   │
          ▼                   ▼                   ▼
   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
   │ JSON Audit  │    │ systemctl   │    │  Alerts     │
   │ Backup Mgmt │    │  Status     │    │  (Embed)    │
   └─────────────┘    └─────────────┘    └─────────────┘

狀態機流程

┌─────────┐    JSON 無效    ┌─────────────┐   文件持續變動   ┌──────────┐
│  正常   │ ──────────────> │  Debounce   │ ──────────────> │  等待中  │
│ 監控中  │                 │   等待期    │   (重新計時)    │          │
└─────────┘                 └──────┬──────┘                 └────┬─────┘
     ▲                             │                             │
     │                             │ 文件穩定                    │
     │                             ▼                             │
     │                       ┌─────────────┐                     │
     │                       │  Grace 寬限 │                     │
     │                       │  (120s)     │                     │
     │                       └──────┬──────┘                     │
     │                              │                            │
     │                              │ 寬限期結束仍無效            │
     │                              ▼                            │
     │                       ┌─────────────┐                     │
     └────────────────────── │  自動回退   │ <───────────────────┘
         恢復正常            │  (Backup)   │    人工修復
                             └─────────────┘

狀態機流程

┌─────────┐    JSON 無效    ┌─────────────┐   文件持續變動   ┌──────────┐
│  正常   │ ──────────────> │  Debounce   │ ──────────────> │  等待中  │
│ 監控中  │                 │   等待期    │   (重新計時)    │          │
└─────────┘                 └──────┬──────┘                 └────┬─────┘
     ▲                             │                             │
     │                             │ 文件穩定                    │
     │                             ▼                             │
     │                       ┌─────────────┐                     │
     │                       │  Grace 寬限 │                     │
     │                       │  (120s)     │                     │
     │                       └──────┬──────┘                     │
     │                              │                            │
     │                              │ 寬限期結束仍無效            │
     │                              ▼                            │
     │                       ┌─────────────┐                     │
     └────────────────────── │  自動回退   │ <───────────────────┘
         恢復正常            │  (Backup)   │    人工修復
                             └─────────────┘

Core Features

1. Gateway 崩潰自動恢復

持續檢測 openclaw-gateway systemd 服務狀態，離線時立即重啟：

bash

systemctl --user is-active --quiet openclaw-gateway
# 若離線 → systemctl --user restart openclaw-gateway

2. 配置損壞自動回退

當 openclaw.json 出現 JSON 語法錯誤時：

進入 5 秒 Debounce（等待編輯完成）
進入 120 秒寬限期（給人工修復時間）
寬限期結束仍無效 → 自動回退備份配置
回退後重啟 Gateway

3. 智能 Debounce（防誤判）

針對人工編輯場景優化：

檢測到文件變動 → 暫停自動回退
文件停止變動後等待 5 秒（Debounce）
確認編輯完成後才開始寬限期計時
避免在修改到一半時強制還原

4. 健康配置自動備份

Gateway 運行正常時，自動備份當前配置：

bash

# 每次輪詢檢查，若配置有變化則更新備份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

5. Discord 即時告警

所有關鍵事件均推送 Discord Embed 消息：

事件類型	顏色	說明
🐾 啟動通知	藍色	Watchdog 啟動時發送
⚠️ 配置編輯中	黃色	檢測到人工修改，暫停回退
✅ 配置已修復	綠色	人工修改完成，格式合法
⚠️ Gateway 崩潰恢復	黃色	Gateway 離線後自動重啟
🚨 配置自動恢復	紅色	寬限期結束，自動回退備份
🚨 Gateway 配置回退恢復	紅色	回退配置後重啟成功
💀 嚴重異常	深紅	回退後仍無法啟動，需人工介入

6. 零依賴設計

純 Bash 編寫，僅需系統自帶工具：

bash - 腳本執行
jq - JSON 解析驗證
curl - Discord Webhook 推送
systemctl - 服務管理

Installation

1. 下載與配置

bash

cd ~/projects/starsoup-infrastructure/openclaw-watchdog

# 複製環境配置模板
cp .env.example .env
nano .env

2. 編輯 .env

bash

# 必填：Discord Webhook URL
WATCHDOG_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# 選填：OpenClaw 配置路徑（預設 ~/.openclaw/openclaw.json）
# OPENCLAW_CONFIG_PATH="/home/tedwu/.openclaw/openclaw.json"

# 選填：輪詢間隔（秒，預設 15）
# WATCHDOG_CHECK_INTERVAL=15

# 選填：寬限期（秒，預設 120）
# WATCHDOG_GRACE_SEC=120

# 選填：Debounce 等待期（秒，預設 5）
# WATCHDOG_EDIT_DEBOUNCE_SEC=5

3. 一鍵部署

bash

bash install.sh

install.sh 會自動完成：

檢查依賴（jq, curl）
生成 systemd service 文件
啟用並啟動服務

4. 驗證狀態

bash

# 查看服務狀態
systemctl status openclaw-watchdog

# 查看實時日誌
journalctl -u openclaw-watchdog -f

Configuration Reference

.env 參數詳解

變數名稱	必填	預設值	說明
`WATCHDOG_WEBHOOK_URL`	✅ 是	-	Discord Webhook URL，用於發送告警
`OPENCLAW_CONFIG_PATH`	❌ 否	`~/.openclaw/openclaw.json`	監控的配置文件絕對路徑
`WATCHDOG_CHECK_INTERVAL`	❌ 否	`15`	輪詢檢查頻率（秒）
`WATCHDOG_GRACE_SEC`	❌ 否	`120`	配置異常後的寬限期（秒）
`WATCHDOG_EDIT_DEBOUNCE_SEC`	❌ 否	`5`	文件停止變動後的穩定等待期（秒）

調參建議

場景	建議調整
頻繁修改配置	增加 `GRACE_SEC` 到 300（5分鐘）
低資源環境	增加 `CHECK_INTERVAL` 到 30-60 秒
快速恢復需求	減少 `GRACE_SEC` 到 60 秒
遠程編輯（網絡延遲）	增加 `EDIT_DEBOUNCE_SEC` 到 10 秒

Workflow Details

正常運行時

每 15 秒循環：
  1. 檢查 openclaw.json 是否為有效 JSON
  2. 檢查 openclaw-gateway 是否運行中
  3. 若都正常 → 備份配置（如有變化）
  4. 等待 15 秒

配置異常時

檢測到 JSON 無效：
  1. 記錄異常時間戳
  2. 檢查文件是否在變動（mtime 變化）
     - 是 → 發送「編輯中」通知，暫停計時
     - 否 → 開始 5 秒 Debounce 計時
  3. Debounce 結束後開始 120 秒寬限期
  4. 寬限期結束仍無效：
     - 複製 .bak 覆蓋當前配置
     - 重啟 Gateway
     - 發送「自動恢復」通知

Gateway 崩潰時

檢測到 Gateway 離線：
  1. 嘗試重啟 Gateway
  2. 等待 5 秒確認狀態
  3. 若成功 → 發送「恢復」通知
  4. 若失敗 → 回退到備份配置
  5. 再次重啟
  6. 若仍失敗 → 發送「嚴重異常」通知（需人工介入）

Integration with Status Server

Watchdog 狀態可通過 Status Server 在 Homepage Dashboard 顯示：

yaml

# homepage/config/services.yaml
- Monitoring:
    - System Status:
        widget:
          type: customapi
          url: http://172.17.0.1:8222/status.json
          mappings:
            - field: watchdog
              label: Watchdog

Status Server 通過 systemctl is-active openclaw-watchdog 獲取 Watchdog 運行狀態。

Troubleshooting

查看日誌

bash

# 實時跟蹤
journalctl -u openclaw-watchdog -f

# 最近 100 行
journalctl -u openclaw-watchdog -n 100

# 今天所有日誌
journalctl -u openclaw-watchdog --since today

常見問題

問題	原因	解決方案
Watchdog 未啟動	依賴缺失	`sudo apt install jq curl`
Webhook 未收到通知	URL 錯誤	檢查 `.env` 中的 `WATCHDOG_WEBHOOK_URL`
配置被意外回退	寬限期過短	增加 `WATCHDOG_GRACE_SEC`
編輯時反覆觸發告警	Debounce 過短	增加 `WATCHDOG_EDIT_DEBOUNCE_SEC`
備份未生成	權限問題	檢查 `~/.openclaw/` 目錄權限

手動測試

bash

# 測試 Discord Webhook
curl -X POST -H "Content-Type: application/json" \
  -d '{"content":"Test from Watchdog"}' \
  $WATCHDOG_WEBHOOK_URL

# 測試配置驗證
jq . ~/.openclaw/openclaw.json > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

# 測試 Gateway 狀態
systemctl --user is-active openclaw-gateway

File Structure

openclaw-watchdog/
├── watchdog.sh           # 主守護進程腳本
├── install.sh            # 一鍵部署腳本
├── .env.example          # 環境變數模板
├── .env                  # 實際配置（不提交到 git）
├── .gitignore            # 忽略 .env
├── LICENSE               # MIT License
└── README.md             # 項目 README（GitHub 用）

與 starsoup-infrastructure 的關係

starsoup-infrastructure/
├── openclaw-watchdog/          # 本組件
│   ├── watchdog.sh
│   └── install.sh
├── scripts/
│   ├── status-server.py        # 暴露 Watchdog 狀態給 Homepage
│   └── generate-status.py
├── status-server.service       # Status Server 的 systemd 配置
└── docs/
    ├── status-server.md        # Status Server 文檔
    └── openclaw-watchdog.md    # 本文檔

Version History

v3.0 (2026-03-19)

重大改進：

🛡️ Gateway 崩潰回退：Gateway 啟動失敗時自動回退配置
🧠 智能 Debounce：檢測人工編輯，避免誤判
🔔 啟動通知：Watchdog 啟動時發送 Discord 通知
⏱️ 優化時機：備份只在 Gateway 正常運行時執行

提交：380b94d

v2.x (早期版本)

基礎 Gateway 監控
配置 JSON 驗證
自動備份與回退
Discord 告警

References

Last updated: 2026-05-05Component: openclaw-watchdog v3.0Maintainer: starsoup

OpenClaw Watchdog | OpenClaw 守門犬 ​

Overview ​

解決的問題 ​

Architecture ​

狀態機流程 ​

狀態機流程 ​

Core Features ​

1. Gateway 崩潰自動恢復 ​

2. 配置損壞自動回退 ​

3. 智能 Debounce（防誤判） ​

4. 健康配置自動備份 ​

5. Discord 即時告警 ​

6. 零依賴設計 ​

Installation ​

1. 下載與配置 ​

2. 編輯 .env ​

3. 一鍵部署 ​

4. 驗證狀態 ​

Configuration Reference ​

.env 參數詳解 ​

調參建議 ​

Workflow Details ​

正常運行時 ​

配置異常時 ​

Gateway 崩潰時 ​

Integration with Status Server ​

Troubleshooting ​

查看日誌 ​

常見問題 ​

手動測試 ​

File Structure ​

與 starsoup-infrastructure 的關係 ​

Version History ​

v3.0 (2026-03-19) ​

v2.x (早期版本) ​

References ​

OpenClaw Watchdog | OpenClaw 守門犬

Overview

解決的問題

Architecture

狀態機流程

狀態機流程

Core Features

1. Gateway 崩潰自動恢復

2. 配置損壞自動回退

3. 智能 Debounce（防誤判）

4. 健康配置自動備份

5. Discord 即時告警

6. 零依賴設計

Installation

1. 下載與配置

2. 編輯 .env

3. 一鍵部署

4. 驗證狀態

Configuration Reference

.env 參數詳解

調參建議

Workflow Details

正常運行時

配置異常時

Gateway 崩潰時

Integration with Status Server

Troubleshooting

查看日誌

常見問題

手動測試

File Structure

與 starsoup-infrastructure 的關係

Version History

v3.0 (2026-03-19)

v2.x (早期版本)

References