From cdccebc5cb88bf7819d717d65c8242d4d773306b Mon Sep 17 00:00:00 2001 From: Alice Date: Wed, 22 Apr 2026 08:57:08 +0800 Subject: [PATCH] =?UTF-8?q?README:=20make=20troubleshooting=20FAQ=20fully?= =?UTF-8?q?=20bilingual=20(=E7=B9=81=E4=B8=AD/EN)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 279 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 225 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index afe9fa2..7bdee95 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # watchdog-discord-route -> **繁體中文 / English bilingual README** (same file) +> **繁體中文 / English bilingual README (same file)** 這個 repo 是一個可攜式 OpenClaw skill bundle，用於打通並驗證 **watchdog-b → owner-facing Discord** 回報鏈路。 @@ -10,22 +10,24 @@ This repo is a portable OpenClaw skill bundle to deliver and verify the **watchd ## TL;DR 最短安裝（建議） / Quick Install (recommended) -### 1) 安裝 bundle + 建立設定檔 +### 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 目標（必要） +### 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 ``` -### 3) Bootstrap（通過後才開 timer） +### 3) Bootstrap（通過後才開 timer） / Bootstrap (enable timer only after pass) ```bash ./scripts/bootstrap_watchdog_bundle.sh @@ -33,7 +35,7 @@ systemctl --user daemon-reload systemctl --user enable --now openclaw-watchdog-b.timer ``` -### 4)（可選）跑 E2E 驗證 +### 4)（可選）跑 E2E 驗證 / (Optional) run E2E verification ```bash cd ~/.openclaw/workspace/scripts/watchdog-b @@ -59,7 +61,9 @@ flowchart TD --- -## 這是用來做什麼的（中文） +## 這是用來做什麼的 / What this is for + +### 中文 用這個 bundle 來： @@ -68,67 +72,45 @@ flowchart TD - 修復 `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` - -最低必填： - -```bash -WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID -``` - -可選（只有 host 上真的存在該 agent id 才設）： - -```bash -WATCHDOG_B_MAIN_AGENT_ID=backend -``` - -> 未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。 - ---- - -## What this is for (English) +### English Use this bundle to: - deploy watchdog-b on a new OpenClaw host (via `systemd --user timer`) -- verify the owner-facing Discord delivery end-to-end +- 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 +--- + +## 包含內容 / 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: +## 重要設定（單一來源） / Single source of config + +設定檔 / Config file: - `~/.config/openclaw/watchdog-b.env` -Minimum required: +最低必填 / Minimum required: ```bash WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID ``` -Optional (only set if the agent id exists on the host): +可選（只有 host 上真的存在該 agent id 才設）/ Optional (only set if the agent id exists on the host): ```bash WATCHDOG_B_MAIN_AGENT_ID=backend ``` +未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。 + If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` failures. --- @@ -141,39 +123,228 @@ If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` f - **channel-readable**：可以從 target channel 讀回 - **human-confirmed**：Eric 確認在 Discord 看到 -最低 E2E 成功訊號（verify script 期待的）： +Do not collapse “success” into one claim: -- `~/.clawteam/owner-reports/pending/` 產生 pending -- pending 進入 `~/.clawteam/owner-reports/sent/` +- **transport accepted**: send returned success / message id +- **channel-readable**: message can be read back from the target channel +- **human-confirmed**: Eric confirmed it is visible in Discord + +最低 E2E 成功訊號 / Minimum E2E success signals: + +- `~/.clawteam/owner-reports/pending/` pending created +- pending moved into `~/.clawteam/owner-reports/sent/` - Discord send success / message id -- artifacts 寫入 `state/watchdog-b-verify-e2e//` +- artifacts written under `state/watchdog-b-verify-e2e//` --- -## 已知故障排查 FAQ / Troubleshooting FAQ +## 已知故障排查 FAQ（雙語對照） / Troubleshooting FAQ (bilingual) -### Q1: `.../scripts/scripts/owner_report_producer.py` 找不到 -A: 代表路徑基準錯了。正確應該在 `.../scripts/watchdog-b/owner_report_producer.py`。 +### 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 ``` -### Q2: `Unknown agent id "main"` -A: 不要硬編碼 `main`。改用 `WATCHDOG_B_MAIN_AGENT_ID`（或不設讓它 skip）。 +### Q1 (English) +**Error:** `can't open file .../scripts/scripts/owner_report_producer.py` -### Q3: timer active 但 owner-facing 沒送到 -A: timer 只代表排程活著，不代表鏈路通。請跑： +**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//` artifacts 是否齊全 + +**建議動作：** ```bash cd ~/.openclaw/workspace/scripts/watchdog-b ./verify_watchdog_b_e2e.sh ``` -並檢查 `pending/`→`sent/` 移動與 send 回傳。 +### 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//` + +**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 +``` ---