# watchdog-discord-route

> **繁體中文 / English bilingual README** (same file)

這個 repo 是一個可攜式 OpenClaw skill bundle，用於打通並驗證 **watchdog-b → owner-facing Discord** 回報鏈路。

This repo is a portable OpenClaw skill bundle to deliver and verify the **watchdog-b → owner-facing Discord** reporting route.

---

## TL;DR 最短安裝（建議） / Quick Install (recommended)

### 1) 安裝 bundle + 建立設定檔

```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 目標（必要）

把 `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
```

### 3) Bootstrap（通過後才開 timer）

```bash
./scripts/bootstrap_watchdog_bundle.sh
systemctl --user daemon-reload
systemctl --user enable --now openclaw-watchdog-b.timer
```

### 4)（可選）跑 E2E 驗證

```bash
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```

---

## 安裝流程圖 / Install Flow

```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]
```

---

## 這是用來做什麼的（中文）

用這個 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`

最低必填：

```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)

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
- 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
- artifacts 寫入 `state/watchdog-b-verify-e2e/<run-id>/`

---

## 已知故障排查 FAQ / Troubleshooting FAQ

### Q1: `.../scripts/scripts/owner_report_producer.py` 找不到
A: 代表路徑基準錯了。正確應該在 `.../scripts/watchdog-b/owner_report_producer.py`。

修正：

```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）。

### Q3: timer active 但 owner-facing 沒送到
A: timer 只代表排程活著，不代表鏈路通。請跑：

```bash
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```

並檢查 `pending/`→`sent/` 移動與 send 回傳。

---

## Safety / 清理規則

- **不要刪** `~/.clawteam/owner-reports/sent/` 歷史（除非明確要求）
- **不要刪** `state/watchdog-b/notify-state.json`（除非做 hard reset）

---

## Repo

- https://gitea.cowbay.org/openclaw/watchdog-discord-route