Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
cdccebc5cb | ||
|
|
ae7c5af69d | ||
|
|
05feb92907 |
443
README.md
443
README.md
@@ -1,197 +1,360 @@
|
||||
# watchdog-discord-route
|
||||
|
||||
Portable OpenClaw skill bundle for the **watchdog-b owner-facing Discord route**.
|
||||
> **繁體中文 / English bilingual README (same file)**
|
||||
|
||||
This repo packages the scripts, env example, systemd user units, and skill documentation needed to install, verify, and repair the path:
|
||||
這個 repo 是一個可攜式 OpenClaw skill bundle，用於打通並驗證 **watchdog-b → owner-facing Discord** 回報鏈路。
|
||||
|
||||
`watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive`
|
||||
This repo is a portable OpenClaw skill bundle to deliver and verify the **watchdog-b → owner-facing Discord** reporting route.
|
||||
|
||||
## Quick install (shortest path)
|
||||
---
|
||||
|
||||
Run from inside this repo:
|
||||
## TL;DR 最短安裝（建議） / Quick Install (recommended)
|
||||
|
||||
### 1) 安裝 bundle + 建立設定檔 / Install + create config
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example
|
||||
mkdir -p ~/.config/openclaw && cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
|
||||
```
|
||||
|
||||
### 2) 設定 Discord 目標（必要） / Set Discord target (required)
|
||||
|
||||
把 `WATCHDOG_B_OWNER_REPORT_TARGET` 改成真的 channel id（不要留 placeholder）：
|
||||
|
||||
Replace `WATCHDOG_B_OWNER_REPORT_TARGET` with a real channel id (do not keep the placeholder):
|
||||
|
||||
```bash
|
||||
sed -i 's#^WATCHDOG_B_OWNER_REPORT_TARGET=.*#WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID#' ~/.config/openclaw/watchdog-b.env
|
||||
./scripts/bootstrap_watchdog_bundle.sh && systemctl --user daemon-reload && systemctl --user enable --now openclaw-watchdog-b.timer
|
||||
```
|
||||
|
||||
Replace `YOUR_DISCORD_CHANNEL_ID` with the real target before enabling the timer.
|
||||
|
||||
## Install flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Clone or unpack watchdog-discord-route] --> B[Run install_watchdog_bundle.sh --install-env-example]
|
||||
B --> C[Create ~/.config/openclaw/watchdog-b.env from example]
|
||||
C --> D[Set WATCHDOG_B_OWNER_REPORT_TARGET]
|
||||
D --> E[Run bootstrap_watchdog_bundle.sh]
|
||||
E --> F{Bootstrap passes?}
|
||||
F -- no --> G[Fix config/runtime/path issues and rerun bootstrap]
|
||||
G --> E
|
||||
F -- yes --> H[systemctl --user daemon-reload]
|
||||
H --> I[Enable/start openclaw-watchdog-b.timer]
|
||||
I --> J[Optional: run verify_watchdog_b_e2e.sh]
|
||||
```
|
||||
|
||||
## What this is for
|
||||
|
||||
Use this bundle when you need to:
|
||||
|
||||
- install watchdog-b on another OpenClaw host
|
||||
- verify end-to-end owner-facing Discord delivery
|
||||
- repair broken `owner_report_*` routing
|
||||
- refresh the live bundle under `scripts/watchdog-b/`
|
||||
- enable the `systemd --user` timer for watchdog-b
|
||||
|
||||
## What is included
|
||||
|
||||
### Skill docs
|
||||
- `SKILL.md`
|
||||
|
||||
### Scripts
|
||||
- `scripts/check_openclaw_state.sh`
|
||||
- `scripts/run_watchdog_b.sh`
|
||||
- `scripts/notify_watchdog_b.py`
|
||||
- `scripts/verify_watchdog_b_e2e.sh`
|
||||
- `scripts/owner_report_consumer.py`
|
||||
- `scripts/owner_report_producer.py`
|
||||
- `scripts/owner_report_driver.py`
|
||||
- `scripts/install_watchdog_bundle.sh`
|
||||
- `scripts/bootstrap_watchdog_bundle.sh`
|
||||
- `scripts/openclaw_runtime_probe.py`
|
||||
- `scripts/watchdog-b.env.example`
|
||||
|
||||
### systemd --user units
|
||||
- `scripts/openclaw-watchdog-b.service`
|
||||
- `scripts/openclaw-watchdog-b.timer`
|
||||
|
||||
### References
|
||||
- `references/watchdog-b-readme.md`
|
||||
- `references/owner-reporting-system.md`
|
||||
- `references/owner-report-operator-manual.md`
|
||||
|
||||
## Recommended install order
|
||||
|
||||
Run from inside this repo:
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example
|
||||
mkdir -p ~/.config/openclaw
|
||||
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
|
||||
```
|
||||
|
||||
Then edit at least:
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
|
||||
```
|
||||
|
||||
Then validate:
|
||||
### 3) Bootstrap（通過後才開 timer） / Bootstrap (enable timer only after pass)
|
||||
|
||||
```bash
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
Only after bootstrap passes:
|
||||
|
||||
```bash
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now openclaw-watchdog-b.timer
|
||||
```
|
||||
|
||||
## Quick update / refresh on a host
|
||||
|
||||
If you already have the repo or bundle and just want to refresh the live install:
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
## End-to-end verification
|
||||
|
||||
Run:
|
||||
### 4)（可選）跑 E2E 驗證 / (Optional) run E2E verification
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/scripts/watchdog-b
|
||||
./verify_watchdog_b_e2e.sh
|
||||
```
|
||||
|
||||
Minimum success evidence:
|
||||
---
|
||||
|
||||
- pending owner report created
|
||||
- report moved to `~/.clawteam/owner-reports/sent/`
|
||||
- Discord send returns success / message id
|
||||
- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`
|
||||
## 安裝流程圖 / Install Flow
|
||||
|
||||
Useful verification files:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[取得 repo / bundle] --> B[install_watchdog_bundle.sh --install-env-example]
|
||||
B --> C[建立 ~/.config/openclaw/watchdog-b.env]
|
||||
C --> D[設定 WATCHDOG_B_OWNER_REPORT_TARGET]
|
||||
D --> E[bootstrap_watchdog_bundle.sh]
|
||||
E --> F{Bootstrap 通過?}
|
||||
F -- 否 / No --> G[修正 env/runtime/path 後重跑 bootstrap]
|
||||
G --> E
|
||||
F -- 是 / Yes --> H[systemctl --user enable --now openclaw-watchdog-b.timer]
|
||||
H --> I[可選：verify_watchdog_b_e2e.sh]
|
||||
```
|
||||
|
||||
- `verify.log`
|
||||
- `run-output.txt`
|
||||
- `queue-before.txt`
|
||||
- `queue-after.txt`
|
||||
- `sent-head.txt`
|
||||
- `state/notify-state.json`
|
||||
---
|
||||
|
||||
## Important config
|
||||
## 這是用來做什麼的 / What this is for
|
||||
|
||||
Expected live config lives in:
|
||||
### 中文
|
||||
|
||||
用這個 bundle 來：
|
||||
|
||||
- 在新主機快速部署 watchdog-b（採 `systemd --user timer`）
|
||||
- 驗證 owner-facing Discord 訊息是否真的送達
|
||||
- 修復 `owner_report_*` routing 路徑錯誤
|
||||
- 刷新 live bundle（`~/.openclaw/workspace/scripts/watchdog-b/`）
|
||||
|
||||
### English
|
||||
|
||||
Use this bundle to:
|
||||
|
||||
- deploy watchdog-b on a new OpenClaw host (via `systemd --user timer`)
|
||||
- verify owner-facing Discord delivery end-to-end
|
||||
- fix broken `owner_report_*` routing / path issues
|
||||
- refresh the live install under `~/.openclaw/workspace/scripts/watchdog-b/`
|
||||
|
||||
---
|
||||
|
||||
## 包含內容 / Included
|
||||
|
||||
- Skill doc: `SKILL.md`
|
||||
- Scripts: `scripts/*.sh`, `scripts/*.py`, `scripts/watchdog-b.env.example`
|
||||
- systemd user units: `scripts/openclaw-watchdog-b.service`, `scripts/openclaw-watchdog-b.timer`
|
||||
- References: `references/*.md`
|
||||
|
||||
---
|
||||
|
||||
## 重要設定（單一來源） / Single source of config
|
||||
|
||||
設定檔 / Config file:
|
||||
- `~/.config/openclaw/watchdog-b.env`
|
||||
|
||||
Typical minimum values:
|
||||
最低必填 / Minimum required:
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_NOTIFY_DRY_RUN=0
|
||||
WATCHDOG_B_RUNNING_REPORT_MODE=enqueue-and-drain
|
||||
WATCHDOG_B_OWNER_DELIVERY_MODE=direct-discord
|
||||
WATCHDOG_B_OWNER_REPORT_CHANNEL=discord
|
||||
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
|
||||
```
|
||||
|
||||
Optional if the host really has a valid OpenClaw agent id:
|
||||
可選（只有 host 上真的存在該 agent id 才設）/ Optional (only set if the agent id exists on the host):
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_MAIN_AGENT_ID=backend
|
||||
```
|
||||
|
||||
If this is unset, stalled/idle paths skip main-agent nudge instead of failing on `Unknown agent id`.
|
||||
未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。
|
||||
|
||||
## Known pitfalls fixed in this bundle
|
||||
If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` failures.
|
||||
|
||||
This bundle already includes fixes for these previously observed issues:
|
||||
---
|
||||
|
||||
1. **Wrong producer path**
|
||||
- bad: `.../workspace/scripts/scripts/owner_report_producer.py`
|
||||
- fixed: `.../workspace/scripts/watchdog-b/owner_report_producer.py`
|
||||
## 驗收/證據標準 / Evidence Standard
|
||||
|
||||
2. **Missing consumer in portable bundle**
|
||||
- `owner_report_consumer.py` is included and installed to the live bundle
|
||||
請把「成功」拆成三層，不要混為一談：
|
||||
|
||||
3. **Bootstrap wrongly required old live owner-reporting-system tree**
|
||||
- bootstrap now validates the installed live bundle under `scripts/watchdog-b/`
|
||||
- **transport accepted**：send API 回傳成功/有 message id
|
||||
- **channel-readable**：可以從 target channel 讀回
|
||||
- **human-confirmed**：Eric 確認在 Discord 看到
|
||||
|
||||
4. **Invalid hard-coded `main` agent nudge**
|
||||
- nudge now uses `WATCHDOG_B_MAIN_AGENT_ID` only when configured
|
||||
|
||||
## Evidence standard
|
||||
|
||||
When claiming success, distinguish these clearly:
|
||||
Do not collapse “success” into one claim:
|
||||
|
||||
- **transport accepted**: send returned success / message id
|
||||
- **channel-readable**: message can be read back from the target Discord channel
|
||||
- **human-confirmed**: the user confirms they saw it
|
||||
- **channel-readable**: message can be read back from the target channel
|
||||
- **human-confirmed**: Eric confirmed it is visible in Discord
|
||||
|
||||
Do not collapse them into one claim.
|
||||
最低 E2E 成功訊號 / Minimum E2E success signals:
|
||||
|
||||
## Safety / cleanup rules
|
||||
- `~/.clawteam/owner-reports/pending/` pending created
|
||||
- pending moved into `~/.clawteam/owner-reports/sent/`
|
||||
- Discord send success / message id
|
||||
- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`
|
||||
|
||||
- Do **not** delete `~/.clawteam/owner-reports/sent/` history unless explicitly asked
|
||||
- Do **not** delete live `state/watchdog-b/notify-state.json` unless explicitly doing a hard reset
|
||||
- Prefer archiving old test residue under `state/archive/<timestamp>/`
|
||||
---
|
||||
|
||||
## Repo purpose
|
||||
## 已知故障排查 FAQ（雙語對照） / Troubleshooting FAQ (bilingual)
|
||||
|
||||
This repo is meant to be a reusable, host-portable source of truth for the watchdog-b Discord delivery path, not just a local one-off workspace patch.
|
||||
### Q1（中文）
|
||||
**錯誤：** `can't open file .../scripts/scripts/owner_report_producer.py`
|
||||
|
||||
**原因：** notifier 使用了錯誤的 base path。
|
||||
|
||||
**正確路徑：** `.../scripts/watchdog-b/owner_report_producer.py`
|
||||
|
||||
**處理：** 先強制刷新 bundle，再跑 bootstrap：
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
### Q1 (English)
|
||||
**Error:** `can't open file .../scripts/scripts/owner_report_producer.py`
|
||||
|
||||
**Cause:** the notifier is using a wrong base path.
|
||||
|
||||
**Correct path:** `.../scripts/watchdog-b/owner_report_producer.py`
|
||||
|
||||
**Fix:** force refresh the bundle, then rerun bootstrap:
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q2（中文）
|
||||
**錯誤：** `bootstrap_watchdog_bundle.sh` 說 `owner-reporting-system root missing`
|
||||
|
||||
**原因：** host 上仍是舊版 bootstrap（期待舊的 live tree）。
|
||||
|
||||
**處理：** 刷新 bundle 之後再 bootstrap：
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
**期待行為：** bootstrap 只檢查 `scripts/watchdog-b/*.py`，不再要求獨立的 `owner-reporting-system/` 目錄。
|
||||
|
||||
### Q2 (English)
|
||||
**Error:** `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`
|
||||
|
||||
**Cause:** you are still running an older bootstrap that expects the legacy live tree.
|
||||
|
||||
**Fix:** refresh the bundle, then rerun bootstrap:
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
```
|
||||
|
||||
**Expected behavior:** bootstrap validates only the installed live bundle under `scripts/watchdog-b/*.py` and no longer requires a separate `owner-reporting-system/` directory.
|
||||
|
||||
---
|
||||
|
||||
### Q3（中文）
|
||||
**錯誤：** `Unknown agent id "main"`
|
||||
|
||||
**原因：** 某些路徑（stalled/idle）嘗試 nudge hard-coded `main`，但該 host 上不存在。
|
||||
|
||||
**處理：**
|
||||
- 最保守：不要設定 `WATCHDOG_B_MAIN_AGENT_ID`（讓它自動 skip）
|
||||
- 或：設定為 host 上真的存在的 agent id（例如 `backend`）
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_MAIN_AGENT_ID=backend
|
||||
```
|
||||
|
||||
### Q3 (English)
|
||||
**Error:** `Unknown agent id "main"`
|
||||
|
||||
**Cause:** stalled/idle path attempted to nudge a hard-coded `main`, which does not exist on this host.
|
||||
|
||||
**Fix:**
|
||||
- safest: leave `WATCHDOG_B_MAIN_AGENT_ID` unset (it will be skipped)
|
||||
- or set it to a real host-local agent id (e.g. `backend`)
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_MAIN_AGENT_ID=backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q4（中文）
|
||||
**問題：** `~/.config/openclaw/watchdog-b.env` 不存在
|
||||
|
||||
**原因：** 只有產生 example，但沒有建立 live env。
|
||||
|
||||
**處理：**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/openclaw
|
||||
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
|
||||
```
|
||||
|
||||
然後至少設定：
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
|
||||
```
|
||||
|
||||
### Q4 (English)
|
||||
**Problem:** `~/.config/openclaw/watchdog-b.env` does not exist
|
||||
|
||||
**Cause:** the example exists, but the live env file was never created.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/openclaw
|
||||
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
|
||||
```
|
||||
|
||||
Then set at least:
|
||||
|
||||
```bash
|
||||
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q5（中文）
|
||||
**問題：** bootstrap 通過，但 Discord 還是沒送到
|
||||
|
||||
**檢查順序：**
|
||||
1. `WATCHDOG_B_OWNER_REPORT_TARGET` 是否真實（不是 placeholder）
|
||||
2. `pending/` 是否有檔、是否有進 `sent/`
|
||||
3. send 是否只有 transport accepted（有 message id）但其實你看不到（非 channel-readable）
|
||||
4. `state/watchdog-b-verify-e2e/<run-id>/` artifacts 是否齊全
|
||||
|
||||
**建議動作：**
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/scripts/watchdog-b
|
||||
./verify_watchdog_b_e2e.sh
|
||||
```
|
||||
|
||||
### Q5 (English)
|
||||
**Problem:** bootstrap passes, but Discord delivery still fails
|
||||
|
||||
**Check in order:**
|
||||
1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real (not placeholder)
|
||||
2. a pending file exists and moves from `pending/` to `sent/`
|
||||
3. distinguish transport accepted (message id) vs channel-readable visibility
|
||||
4. verify artifacts exist under `state/watchdog-b-verify-e2e/<run-id>/`
|
||||
|
||||
**Suggested action:**
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/scripts/watchdog-b
|
||||
./verify_watchdog_b_e2e.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q6（中文）
|
||||
**問題：** timer active / service success，但 owner-facing route 仍不通
|
||||
|
||||
**解釋：** timer 代表排程活著，不代表鏈路通。仍需以 verify/evidence 為準。
|
||||
|
||||
### Q6 (English)
|
||||
**Problem:** timer is active / service is successful, but owner-facing route still doesn’t work
|
||||
|
||||
**Explanation:** a live scheduler does not guarantee the delivery chain works. Verify using E2E evidence.
|
||||
|
||||
---
|
||||
|
||||
### Q7（中文）
|
||||
**問題：** 我該 rerun install 還是只跑 verify？
|
||||
|
||||
**規則：**
|
||||
- scripts/env/units 可能舊了 → rerun **install**
|
||||
- 要做 host readiness 檢查 → rerun **bootstrap**
|
||||
- 安裝都在，只需要新證據 → rerun **verify**
|
||||
|
||||
**實務順序：**
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
cd ~/.openclaw/workspace/scripts/watchdog-b
|
||||
./verify_watchdog_b_e2e.sh
|
||||
```
|
||||
|
||||
### Q7 (English)
|
||||
**Problem:** should I rerun install or just rerun verify?
|
||||
|
||||
**Rule:**
|
||||
- scripts/env/units may be stale → rerun **install**
|
||||
- need host readiness validation → rerun **bootstrap**
|
||||
- install is fine, need fresh evidence → rerun **verify**
|
||||
|
||||
**Practical order:**
|
||||
|
||||
```bash
|
||||
./scripts/install_watchdog_bundle.sh --install-env-example --force
|
||||
./scripts/bootstrap_watchdog_bundle.sh
|
||||
cd ~/.openclaw/workspace/scripts/watchdog-b
|
||||
./verify_watchdog_b_e2e.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Safety / 清理規則
|
||||
|
||||
- **不要刪** `~/.clawteam/owner-reports/sent/` 歷史（除非明確要求）
|
||||
- **不要刪** `state/watchdog-b/notify-state.json`（除非做 hard reset）
|
||||
|
||||
---
|
||||
|
||||
## Repo
|
||||
|
||||
- https://gitea.cowbay.org/openclaw/watchdog-discord-route
|
||||
|
||||
Reference in New Issue
Block a user