watchdog-discord-route/README.md

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:

./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:

WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID

Then validate:

./scripts/bootstrap_watchdog_bundle.sh

Only after bootstrap passes:

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:

./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh

End-to-end verification

Run:

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:

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:

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.