watchdog-discord-route/SKILL.md

name, description

name	description
watchdog-discord-route	Install, reset, verify, or operate the OpenClaw watchdog-b owner-facing Discord route. Use when setting up or repairing watchdog-b -> owner-report -> Discord delivery, cleaning old watchdog test residue, enabling the systemd --user timer, running end-to-end verification, or adjusting the Discord-facing notification path/target/template.

Watchdog Discord Route

Use this skill when the task is about the watchdog-b owner-facing notification path to Discord.

This skill covers four recurring jobs:

1. Reset / clean old watchdog test residue without deleting live audit assets.
2. Verify the end-to-end path from watchdog-b to Discord.
3. Install / enable the live watchdog schedule.
4. Repair / adjust the Discord-facing route, target, or message format.

What the current canonical path is

Preferred owner-facing path:

watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive

For watchdog-b single-shot owner-facing delivery, prefer the direct Discord driver path over relying on the generic wrapper watchdog destination semantics.

Current default Discord target in this workspace is a validated example, but the portable skill should treat target as host-local configuration.

For portable installs, set:

• WATCHDOG_B_OWNER_REPORT_TARGET=channel:REPLACE_ME

Bundled skill resources

This skill now carries a portable bundle under its own directory. Prefer these bundled files first when adapting or reusing on another host:

scripts/

• scripts/check_openclaw_state.sh
• scripts/notify_watchdog_b.py
• scripts/run_watchdog_b.sh
• 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-watchdog-b.service
• scripts/openclaw-watchdog-b.timer
• scripts/openclaw_runtime_probe.py
• scripts/watchdog-b.env.example

references/

• references/watchdog-b-readme.md
• references/owner-reporting-system.md
• references/owner-report-operator-manual.md

If working in this workspace, you may still inspect the live workspace files too, but the bundled skill files are the portable baseline.

When resetting / cleaning

Before touching anything, inventory:

• state/watchdog-b/
• state/watchdog-b-test-*
• state/watchdog-b-verify-e2e/
• state/archive/
• ~/.clawteam/owner-reports/pending/
• ~/.clawteam/owner-reports/sent/
• user crontab entries related to owner-report/watchdog
• ~/.config/systemd/user/openclaw-watchdog-b.*

Rules:

• Do not delete ~/.clawteam/owner-reports/sent/ history unless explicitly asked.
• Do not delete live state/watchdog-b/notify-state.json unless the user explicitly wants a hard reset.
• Prefer archiving old state/watchdog-b-test-* into state/archive/<timestamp>/.
• Distinguish clearly between:
  • live state
  • old test residue
  • repo templates
  • live installed units

When doing end-to-end verification

Default verification script:

• bundled: scripts/verify_watchdog_b_e2e.sh
• workspace live path: scripts/watchdog-b/verify_watchdog_b_e2e.sh

This should be treated as the single-source verification path unless there is a specific reason to bypass it.

Minimum success evidence:

• Discord send success with a new message id
• pending report created then moved to sent
• sent file exists under ~/.clawteam/owner-reports/sent/
• verification artifacts under state/watchdog-b-verify-e2e/<run-id>/

Useful artifacts:

• verify.log
• run-output.txt
• queue-before.txt
• queue-after.txt
• sent-head.txt
• state/notify-state.json

Do not claim human-visible success unless either:

• the user confirms visibility, or
• you can read back the message from the exact Discord channel and match the message id/content.

When installing the live schedule

Preferred scheduler: systemd --user timer.

Before claiming a host is ready, prefer to run the bundled bootstrap checker first:

• scripts/bootstrap_watchdog_bundle.sh

When installing or refreshing the portable bundle into live paths, prefer the bundled installer:

• scripts/install_watchdog_bundle.sh --install-env-example

Use bootstrap when you need a quick host-readiness answer without changing the host. Use install when you need to copy the bundled scripts/service/timer/env example into the live workspace and user config paths.

Use it when:

• systemd --user is available
• linger/user services are supported
• you want journal/status/list-timers visibility

Live install paths:

• ~/.config/systemd/user/openclaw-watchdog-b.service
• ~/.config/systemd/user/openclaw-watchdog-b.timer
• ~/.config/openclaw/watchdog-b.env

Portable install sources carried by this skill:

• scripts/check_openclaw_state.sh
• scripts/run_watchdog_b.sh
• scripts/notify_watchdog_b.py
• 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-watchdog-b.service
• scripts/openclaw-watchdog-b.timer
• scripts/openclaw_runtime_probe.py
• scripts/watchdog-b.env.example

Expected environment for live route:

• 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:REPLACE_ME
• optional: WATCHDOG_B_MAIN_AGENT_ID=<valid-agent-id-on-that-host>

Minimum installation verification:

• systemctl --user daemon-reload
• systemctl --user enable --now openclaw-watchdog-b.timer
• systemctl --user start openclaw-watchdog-b.service
• systemctl --user status openclaw-watchdog-b.timer --no-pager
• systemctl --user status openclaw-watchdog-b.service --no-pager
• systemctl --user list-timers --all | rg openclaw-watchdog-b
• journalctl --user -u openclaw-watchdog-b.service -n 50 --no-pager

When repairing Discord delivery

Check these in order:

1. Is the target channel correct?
   • Validate the host-local configured form such as channel:<discord_channel_id>
2. Is the send path using direct driver delivery or the generic wrapper?
   • For watchdog-b owner-facing single-shot delivery, prefer direct driver delivery.
3. If stalled/idle tries to nudge a main agent, is WATCHDOG_B_MAIN_AGENT_ID set to a valid agent id on that host?
   • If not, leave it unset so main-agent nudge is skipped instead of failing on Unknown agent id.
4. Does the message actually appear in channel readback?
5. Is the message merely transport-accepted, or human-visible?

Be precise in language:

• "transport accepted" = send returned success / message id
• "channel-readable" = message appears in channel readback
• "human-confirmed" = Eric says he saw it

Do not collapse these into one claim.

Message formatting preference

Eric reported that visible does not necessarily mean prominent.

When adjusting Discord-facing watchdog messages, prefer:

• short first line
• conclusion first
• minimize raw diagnostic fields in the user-facing body
• keep machine/audit detail in artifacts, not in the first visible lines

Preferred shape:

• 🔔 WATCHDOG｜<結論>
• 任務：...
• 結論：...
• 你現在不用做事 or 需要你介入：...

Suggested execution pattern

For most tasks in this skill:

1. Inventory live state and installed schedule.
2. Decide whether the task is:
   • reset/cleanup
   • route repair
   • schedule install
   • e2e verify
   • portability / migration
3. Preserve audit assets.
4. Prefer the bundled skill scripts as the reusable baseline.
5. Use direct driver Discord route for owner-facing verification.
6. Attach evidence paths and exact commands before claiming success.

Portability note

This skill is now suitable to copy to another OpenClaw workspace, but portability still depends on the target host having:

• a working OpenClaw install
• Discord routing available
• a valid destination channel/target configured in watchdog-b.env
• systemd --user if live scheduling is desired

When moving to another host, recommended order is:

1. Run scripts/install_watchdog_bundle.sh --install-env-example to populate live paths from the bundled copies.
2. If ~/.config/openclaw/watchdog-b.env does not exist, create it from the example:
   • mkdir -p ~/.config/openclaw
   • cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
3. Edit ~/.config/openclaw/watchdog-b.env and set at least:
   • WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
4. Run scripts/bootstrap_watchdog_bundle.sh.
5. Bootstrap should now validate the installed live bundle under scripts/watchdog-b/ and should not require a separate owner-reporting-system/ live tree.
6. Re-run bootstrap until it passes, then enable/start systemd --user units.

When moving to another host, runtime detection now follows this order:

1. explicit env overrides: WATCHDOG_B_NODE_BIN, WATCHDOG_B_OPENCLAW_MJS, WATCHDOG_B_OPENCLAW_ENTRY
2. PATH discovery: node, then openclaw-adjacent install roots
3. common install roots scan: nvm, pnpm global, npm-global, /usr/local, /usr, and Volta-style locations
4. hard failure with a message telling the operator which env vars to set manually

So on most hosts you should only need to update:

• WATCHDOG_B_OWNER_REPORT_TARGET
• WATCHDOG_B_WORKSPACE if the workspace is not the default ~/.openclaw/workspace

Only set WATCHDOG_B_NODE_BIN / WATCHDOG_B_OPENCLAW_ENTRY / WATCHDOG_B_OPENCLAW_MJS when auto-detection fails or you intentionally want to pin a non-default runtime.

If another agent reports that ~/.config/openclaw/watchdog-b.env does not exist, the correct response is to create it from watchdog-b.env.example before expecting bootstrap to pass.

Success checklist

Do not say done unless you have all applicable evidence:

• changed file paths
• exact command(s) run
• status output or send result
• sent archive path when queue/driver is involved
• channel/message evidence when claiming delivery
• rollback instructions when you changed live scheduling