docs: add symptom-first troubleshooting hub and deep runbooks (openclaw#11196)

* docs(troubleshooting): add symptom-first troubleshooting runbooks

* docs(troubleshooting): fix approvals command examples

* docs(troubleshooting): wrap symptom cases in accordions

* docs(automation): clarify userTimezone missing-key behavior

* docs(troubleshooting): fix first-60-seconds ladder order

Author: sebslight

docs/automation/cron-jobs.md

@@ -17,6 +17,8 @@ the right time, and can optionally deliver output back to a chat.
 If you want _“run this every morning”_ or _“poke the agent in 20 minutes”_,
 cron is the mechanism.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## TL;DR
 
 - Cron runs **inside the Gateway** (not inside the model).

docs/automation/troubleshooting.md

@@ -0,0 +1,122 @@
+---
+summary: "Troubleshoot cron and heartbeat scheduling and delivery"
+read_when:
+  - Cron did not run
+  - Cron ran but no message was delivered
+  - Heartbeat seems silent or skipped
+title: "Automation Troubleshooting"
+---
+
+# Automation troubleshooting
+
+Use this page for scheduler and delivery issues (`cron` + `heartbeat`).
+
+## Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then run automation checks:
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw system heartbeat last
+```
+
+## Cron not firing
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw cron runs --id <jobId> --limit 20
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- `cron status` reports enabled and a future `nextWakeAtMs`.
+- Job is enabled and has a valid schedule/timezone.
+- `cron runs` shows `ok` or explicit skip reason.
+
+Common signatures:
+
+- `cron: scheduler disabled; jobs will not run automatically` → cron disabled in config/env.
+- `cron: timer tick failed` → scheduler tick crashed; inspect surrounding stack/log context.
+- `reason: not-due` in run output → manual run called without `--force` and job not due yet.
+
+## Cron fired but no delivery
+
+```bash
+openclaw cron runs --id <jobId> --limit 20
+openclaw cron list
+openclaw channels status --probe
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- Run status is `ok`.
+- Delivery mode/target are set for isolated jobs.
+- Channel probe reports target channel connected.
+
+Common signatures:
+
+- Run succeeded but delivery mode is `none` → no external message is expected.
+- Delivery target missing/invalid (`channel`/`to`) → run may succeed internally but skip outbound.
+- Channel auth errors (`unauthorized`, `missing_scope`, `Forbidden`) → delivery blocked by channel credentials/permissions.
+
+## Heartbeat suppressed or skipped
+
+```bash
+openclaw system heartbeat last
+openclaw logs --follow
+openclaw config get agents.defaults.heartbeat
+openclaw channels status --probe
+```
+
+Good output looks like:
+
+- Heartbeat enabled with non-zero interval.
+- Last heartbeat result is `ran` (or skip reason is understood).
+
+Common signatures:
+
+- `heartbeat skipped` with `reason=quiet-hours` → outside `activeHours`.
+- `requests-in-flight` → main lane busy; heartbeat deferred.
+- `empty-heartbeat-file` → `HEARTBEAT.md` exists but has no actionable content.
+- `alerts-disabled` → visibility settings suppress outbound heartbeat messages.
+
+## Timezone and activeHours gotchas
+
+```bash
+openclaw config get agents.defaults.heartbeat.activeHours
+openclaw config get agents.defaults.heartbeat.activeHours.timezone
+openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
+openclaw cron list
+openclaw logs --follow
+```
+
+Quick rules:
+
+- `Config path not found: agents.defaults.userTimezone` means the key is unset; heartbeat falls back to host timezone (or `activeHours.timezone` if set).
+- Cron without `--tz` uses gateway host timezone.
+- Heartbeat `activeHours` uses configured timezone resolution (`user`, `local`, or explicit IANA tz).
+- ISO timestamps without timezone are treated as UTC for cron `at` schedules.
+
+Common signatures:
+
+- Jobs run at the wrong wall-clock time after host timezone changes.
+- Heartbeat always skipped during your daytime because `activeHours.timezone` is wrong.
+
+Related:
+
+- [/automation/cron-jobs](/automation/cron-jobs)
+- [/gateway/heartbeat](/gateway/heartbeat)
+- [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat)
+- [/concepts/timezone](/concepts/timezone)

docs/channels/matrix.md

@@ -202,6 +202,32 @@ Once verified, the bot can decrypt messages in encrypted rooms.
 | Location        | ✅ Supported (geo URI; altitude ignored)                                              |
 | Native commands | ✅ Supported                                                                          |
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list matrix
+```
+
+Common failures:
+
+- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist.
+- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`.
+- Encrypted rooms fail: crypto support or encryption settings mismatch.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Matrix)
 
 Full configuration: [Configuration](/gateway/configuration)

docs/channels/signal.md

@@ -168,6 +168,32 @@ Config:
 - Groups: `signal:group:<groupId>`.
 - Usernames: `username:<name>` (if supported by your Signal account).
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list signal
+```
+
+Common failures:
+
+- Daemon reachable but no replies: verify account/daemon settings (`httpUrl`, `account`) and receive mode.
+- DMs ignored: sender is pending pairing approval.
+- Group messages ignored: group sender/mention gating blocks delivery.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Signal)
 
 Full configuration: [Configuration](/gateway/configuration)

docs/channels/slack.md

@@ -537,6 +537,32 @@ Slack tool actions can be gated with `channels.slack.actions.*`:
   scopes you expect (`chat:write`, `reactions:write`, `pins:write`,
   `files:write`) or those operations will fail.
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list slack
+```
+
+Common failures:
+
+- Connected but no channel replies: channel blocked by `groupPolicy` or not in `channels.slack.channels` allowlist.
+- DMs ignored: sender not approved when `channels.slack.dm.policy="pairing"`.
+- API errors (`missing_scope`, `not_in_channel`, auth failures): bot/app tokens or Slack scopes are incomplete.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Notes
 
 - Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.

docs/channels/troubleshooting.md

@@ -1,30 +1,116 @@
 ---
-summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp/iMessage)"
+summary: "Fast channel level troubleshooting with per channel failure signatures and fixes"
 read_when:
-  - A channel connects but messages don’t flow
-  - Investigating channel misconfiguration (intents, permissions, privacy mode)
+  - Channel transport says connected but replies fail
+  - You need channel specific checks before deep provider docs
 title: "Channel Troubleshooting"
 ---
 
 # Channel troubleshooting
 
-Start with:
+Use this page when a channel connects but behavior is wrong.
+
+## Command ladder
+
+Run these in order first:
 
 ```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
 openclaw doctor
 openclaw channels status --probe
 ```
 
-`channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership).
+Healthy baseline:
+
+- `Runtime: running`
+- `RPC probe: ok`
+- Channel probe shows connected/ready
+
+## WhatsApp
+
+### WhatsApp failure signatures
+
+| Symptom                         | Fastest check                                       | Fix                                                     |
+| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
+| Connected but no DM replies     | `openclaw pairing list whatsapp`                    | Approve sender or switch DM policy/allowlist.           |
+| Group messages ignored          | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
+| Random disconnect/relogin loops | `openclaw channels status --probe` + logs           | Re-login and verify credentials directory is healthy.   |
+
+Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+
+## Telegram
+
+### Telegram failure signatures
+
+| Symptom                           | Fastest check                                   | Fix                                                       |
+| --------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
+| `/start` but no usable reply flow | `openclaw pairing list telegram`                | Approve pairing or change DM policy.                      |
+| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. |
+| Send failures with network errors | Inspect logs for Telegram API call failures     | Fix DNS/IPv6/proxy routing to `api.telegram.org`.         |
+
+Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+
+## Discord
+
+### Discord failure signatures
+
+| Symptom                         | Fastest check                       | Fix                                                       |
+| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
+| Bot online but no guild replies | `openclaw channels status --probe`  | Allow guild/channel and verify message content intent.    |
+| Group messages ignored          | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
+| DM replies missing              | `openclaw pairing list discord`     | Approve DM pairing or adjust DM policy.                   |
+
+Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+
+## Slack
+
+### Slack failure signatures
+
+| Symptom                                | Fastest check                             | Fix                                               |
+| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| Socket mode connected but no responses | `openclaw channels status --probe`        | Verify app token + bot token and required scopes. |
+| DMs blocked                            | `openclaw pairing list slack`             | Approve pairing or relax DM policy.               |
+| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.     |
+
+Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
+
+## iMessage and BlueBubbles
+
+### iMessage and BlueBubbles failure signatures
+
+| Symptom                          | Fastest check                                                           | Fix                                                   |
+| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
+| No inbound events                | Verify webhook/server reachability and app permissions                  | Fix webhook URL or BlueBubbles server state.          |
+| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation                 | Re-grant TCC permissions and restart channel process. |
+| DM sender blocked                | `openclaw pairing list imessage` or `openclaw pairing list bluebubbles` | Approve pairing or update allowlist.                  |
+
+Full troubleshooting:
+
+- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
+- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
+
+## Signal
+
+### Signal failure signatures
+
+| Symptom                         | Fastest check                              | Fix                                                      |
+| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
+| Daemon reachable but bot silent | `openclaw channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
+| DM blocked                      | `openclaw pairing list signal`             | Approve sender or adjust DM policy.                      |
+| Group replies do not trigger    | Check group allowlist and mention patterns | Add sender/group or loosen gating.                       |
+
+Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
 
-## Channels
+## Matrix
 
-- Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
-- Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
-- WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
-- iMessage (legacy): [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
+### Matrix failure signatures
 
-## Telegram quick fixes
+| Symptom                             | Fastest check                                | Fix                                             |
+| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- |
+| Logged in but ignores room messages | `openclaw channels status --probe`           | Check `groupPolicy` and room allowlist.         |
+| DMs do not process                  | `openclaw pairing list matrix`               | Approve sender or adjust DM policy.             |
+| Encrypted rooms fail                | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. |
 
-- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting).
-- Logs show `setMyCommands failed` → check outbound HTTPS and DNS reachability to `api.telegram.org` (common on locked-down VPS or proxies).
+Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting)

docs/docs.json

@@ -664,7 +664,7 @@
     },
     {
       "source": "/troubleshooting",
-      "destination": "/gateway/troubleshooting"
+      "destination": "/help/troubleshooting"
     },
     {
       "source": "/web/tui",
@@ -966,6 +966,7 @@
                   "hooks/soul-evil",
                   "automation/cron-jobs",
                   "automation/cron-vs-heartbeat",
+                  "automation/troubleshooting",
                   "automation/webhook",
                   "automation/gmail-pubsub",
                   "automation/poll",
@@ -976,6 +977,7 @@
                 "group": "Media and devices",
                 "pages": [
                   "nodes/index",
+                  "nodes/troubleshooting",
                   "nodes/images",
                   "nodes/audio",
                   "nodes/camera",

docs/gateway/heartbeat.md

@@ -13,6 +13,8 @@ title: "Heartbeat"
 Heartbeat runs **periodic agent turns** in the main session so the model can
 surface anything that needs attention without spamming you.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## Quick start (beginner)
 
 1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.