169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
# watchdog-discord-route
|
|
|
|
Portable OpenClaw skill bundle for the **watchdog-b owner-facing Discord route**.
|
|
|
|
This repo packages the scripts, env example, systemd user units, and skill documentation needed to install, verify, and repair the path:
|
|
|
|
`watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive`
|
|
|
|
## 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
|
|
./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:
|
|
|
|
```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>/`
|
|
|
|
Useful verification files:
|
|
|
|
- `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:
|
|
|
|
- `~/.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.
|
|
|
|
## Safety / cleanup rules
|
|
|
|
- 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
|
|
|
|
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.
|