openclaw/watchdog-discord-route
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make README bilingual (繁中/EN) and front-load quick install

Browse Source
This commit is contained in:
Alice
2026-04-22 08:49:37 +08:00
parent 05feb92907
commit ae7c5af69d
1 changed files with 129 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

382
README.md
View File

@@ -1,313 +1,189 @@
# watchdog-discord-route # 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 + 建立設定檔
```bash ```bash
./scripts/install_watchdog_bundle.sh --install-env-example ./scripts/install_watchdog_bundle.sh --install-env-example
mkdir -p ~/.config/openclaw && cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env mkdir -p ~/.config/openclaw && cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
```
### 2) 設定 Discord 目標（必要）
把 `WATCHDOG_B_OWNER_REPORT_TARGET` 改成真的 channel id（不要留 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 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. ### 3) Bootstrap（通過後才開 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:
```bash ```bash
./scripts/bootstrap_watchdog_bundle.sh ./scripts/bootstrap_watchdog_bundle.sh
```
Only after bootstrap passes:
```bash
systemctl --user daemon-reload systemctl --user daemon-reload
systemctl --user enable --now openclaw-watchdog-b.timer systemctl --user enable --now openclaw-watchdog-b.timer
``` ```
## Quick update / refresh on a host ### 4)（可選）跑 E2E 驗證
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:
```bash ```bash
cd ~/.openclaw/workspace/scripts/watchdog-b cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh ./verify_watchdog_b_e2e.sh
``` ```
Minimum success evidence: ---
- pending owner report created ## 安裝流程圖 / Install Flow
- report moved to `~/.clawteam/owner-reports/sent/`
- Discord send returns success / message id
- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`
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 ## 這是用來做什麼的（中文）
Expected live config lives in: 用這個 bundle 來：
- 在新主機快速部署 watchdog-b（採 `systemd --user timer`）
- 驗證 owner-facing Discord 訊息是否真的送達
- 修復 `owner_report_*` routing 路徑錯誤
- 刷新 live bundle（`~/.openclaw/workspace/scripts/watchdog-b/`）
### 包含內容
- Skill 文件：`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`
### 重要設定（單一來源）
設定檔：
- `~/.config/openclaw/watchdog-b.env` - `~/.config/openclaw/watchdog-b.env`
Typical minimum values: 最低必填：
```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:
```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`.
## Known pitfalls fixed in this bundle
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`
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/`
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:
- **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
Do not collapse them into one claim.
## Known troubleshooting FAQ
### 1. `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`
Cause:
- an older bundle / script still expects the old live tree
- or the host has not refreshed to the fixed portable bundle yet
Fix:
- refresh the live bundle:
```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh
```
Expected fixed behavior:
- bootstrap should validate the installed live bundle under `scripts/watchdog-b/`
- it should **not** require a separate `owner-reporting-system/` live directory
### 2. `can't open file .../scripts/scripts/owner_report_producer.py`
Cause:
- notifier is using the wrong base path for `owner_report_producer.py`
Bad path:
- `.../workspace/scripts/scripts/owner_report_producer.py`
Correct path:
- `.../workspace/scripts/watchdog-b/owner_report_producer.py`
Fix:
- update to a bundle that uses the live script directory correctly
- then rerun:
```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```
### 3. `Unknown agent id "main"`
Cause:
- stalled / idle path tried to nudge a hard-coded `main` agent id that does not exist on that host
Fix:
- either leave `WATCHDOG_B_MAIN_AGENT_ID` unset
- or set it to a real host-local agent id
Example:
```bash
WATCHDOG_B_MAIN_AGENT_ID=backend
```
If unset, the fixed bundle skips main-agent nudge instead of failing.
### 4. `~/.config/openclaw/watchdog-b.env` does not exist
Cause:
- install copied the example, but the live env was never created
Fix:
```bash
mkdir -p ~/.config/openclaw
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
```
Then edit at least:
```bash ```bash
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
``` ```
### 5. Bootstrap passes, but Discord delivery still fails 可選（只有 host 上真的存在該 agent id 才設）：
Check these in order: ```bash
WATCHDOG_B_MAIN_AGENT_ID=backend
```
1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real, not placeholder > 未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。
2. Discord routing actually works on that host
3. the send was only transport-accepted vs actually channel-readable
4. `~/.clawteam/owner-reports/pending/` and `sent/` show the expected file movement
5. `state/watchdog-b-verify-e2e/<run-id>/` contains the expected verification artifacts
### 6. Timer is active, but owner-facing route still did not work ---
This means: ## What this is for (English)
- `systemd --user` scheduling is alive
- but the notification chain may still be broken
Do not stop at `timer active` / `service success`. Use this bundle to:
You still need to verify:
- pending owner report creation - deploy watchdog-b on a new OpenClaw host (via `systemd --user timer`)
- sent archive movement - verify the 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`
Minimum required:
```bash
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
```
Optional (only set if the agent id exists on the host):
```bash
WATCHDOG_B_MAIN_AGENT_ID=backend
```
If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` failures.
---
## 驗收/證據標準 / Evidence Standard
請把「成功」拆成三層，不要混為一談：
- **transport accepted**：send API 回傳成功/有 message id
- **channel-readable**：可以從 target channel 讀回
- **human-confirmed**：Eric 確認在 Discord 看到
最低 E2E 成功訊號（verify script 期待的）：
- `~/.clawteam/owner-reports/pending/` 產生 pending
- pending 進入 `~/.clawteam/owner-reports/sent/`
- Discord send success / message id - Discord send success / message id
- readback or human-visible evidence if claiming visible delivery - artifacts 寫入 `state/watchdog-b-verify-e2e/<run-id>/`
### 7. How do I know whether I should rerun install or just rerun verify? ---
Use this rule: ## 已知故障排查 FAQ / Troubleshooting FAQ
- rerun **install** when scripts / env example / units may be stale or incomplete ### Q1: `.../scripts/scripts/owner_report_producer.py` 找不到
- rerun **bootstrap** when you need host-readiness validation A: 代表路徑基準錯了。正確應該在 `.../scripts/watchdog-b/owner_report_producer.py`。
- rerun **verify** when install is already in place and you need fresh E2E evidence
Practical order: 修正：
```bash ```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force ./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh ./scripts/bootstrap_watchdog_bundle.sh
```
### Q2: `Unknown agent id "main"`
A: 不要硬編碼 `main`。改用 `WATCHDOG_B_MAIN_AGENT_ID`（或不設讓它 skip）。
### Q3: timer active 但 owner-facing 沒送到
A: timer 只代表排程活著，不代表鏈路通。請跑：
```bash
cd ~/.openclaw/workspace/scripts/watchdog-b cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh ./verify_watchdog_b_e2e.sh
``` ```
## Safety / cleanup rules 並檢查 `pending/`→`sent/` 移動與 send 回傳。
- 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 ## Safety / 清理規則
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. - **不要刪** `~/.clawteam/owner-reports/sent/` 歷史（除非明確要求）
- **不要刪** `state/watchdog-b/notify-state.json`（除非做 hard reset）
---
## Repo
- https://gitea.cowbay.org/openclaw/watchdog-discord-route