forked from Selig/openclaw-skill
Initial commit: OpenClaw Skill Collection
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
This commit is contained in:
@@ -0,0 +1,316 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
# Gateway troubleshooting
|
||||
|
||||
This page is the deep runbook.
|
||||
Start at [/help/troubleshooting](/help/troubleshooting) if you want the fast triage flow first.
|
||||
|
||||
## Command ladder
|
||||
|
||||
Run these first, in this order:
|
||||
|
||||
```bash theme={null}
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Expected healthy signals:
|
||||
|
||||
* `openclaw gateway status` shows `Runtime: running` and `RPC probe: ok`.
|
||||
* `openclaw doctor` reports no blocking config/service issues.
|
||||
* `openclaw channels status --probe` shows connected/ready channels.
|
||||
|
||||
## No replies
|
||||
|
||||
If channels are up but nothing answers, check routing and policy before reconnecting anything.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw status
|
||||
openclaw channels status --probe
|
||||
openclaw pairing list <channel>
|
||||
openclaw config get channels
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* Pairing pending for DM senders.
|
||||
* Group mention gating (`requireMention`, `mentionPatterns`).
|
||||
* Channel/group allowlist mismatches.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `drop guild message (mention required` → group message ignored until mention.
|
||||
* `pairing request` → sender needs approval.
|
||||
* `blocked` / `allowlist` → sender/channel was filtered by policy.
|
||||
|
||||
Related:
|
||||
|
||||
* [/channels/troubleshooting](/channels/troubleshooting)
|
||||
* [/channels/pairing](/channels/pairing)
|
||||
* [/channels/groups](/channels/groups)
|
||||
|
||||
## Dashboard control ui connectivity
|
||||
|
||||
When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* Correct probe URL and dashboard URL.
|
||||
* Auth mode/token mismatch between client and gateway.
|
||||
* HTTP usage where device identity is required.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `device identity required` → non-secure context or missing device auth.
|
||||
* `unauthorized` / reconnect loop → token/password mismatch.
|
||||
* `gateway connect failed:` → wrong host/port/url target.
|
||||
|
||||
Related:
|
||||
|
||||
* [/web/control-ui](/web/control-ui)
|
||||
* [/gateway/authentication](/gateway/authentication)
|
||||
* [/gateway/remote](/gateway/remote)
|
||||
|
||||
## Gateway service not running
|
||||
|
||||
Use this when service is installed but process does not stay up.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw gateway status --deep
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* `Runtime: stopped` with exit hints.
|
||||
* Service config mismatch (`Config (cli)` vs `Config (service)`).
|
||||
* Port/listener conflicts.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `Gateway start blocked: set gateway.mode=local` → local gateway mode is not enabled.
|
||||
* `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
|
||||
* `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
|
||||
|
||||
Related:
|
||||
|
||||
* [/gateway/background-process](/gateway/background-process)
|
||||
* [/gateway/configuration](/gateway/configuration)
|
||||
* [/gateway/doctor](/gateway/doctor)
|
||||
|
||||
## Channel connected messages not flowing
|
||||
|
||||
If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw channels status --probe
|
||||
openclaw pairing list <channel>
|
||||
openclaw status --deep
|
||||
openclaw logs --follow
|
||||
openclaw config get channels
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* DM policy (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
* Group allowlist and mention requirements.
|
||||
* Missing channel API permissions/scopes.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `mention required` → message ignored by group mention policy.
|
||||
* `pairing` / pending approval traces → sender is not approved.
|
||||
* `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → channel auth/permissions issue.
|
||||
|
||||
Related:
|
||||
|
||||
* [/channels/troubleshooting](/channels/troubleshooting)
|
||||
* [/channels/whatsapp](/channels/whatsapp)
|
||||
* [/channels/telegram](/channels/telegram)
|
||||
* [/channels/discord](/channels/discord)
|
||||
|
||||
## Cron and heartbeat delivery
|
||||
|
||||
If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw cron status
|
||||
openclaw cron list
|
||||
openclaw cron runs --id <jobId> --limit 20
|
||||
openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* Cron enabled and next wake present.
|
||||
* Job run history status (`ok`, `skipped`, `error`).
|
||||
* Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`).
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
|
||||
* `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
|
||||
* `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
|
||||
* `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.
|
||||
|
||||
Related:
|
||||
|
||||
* [/automation/troubleshooting](/automation/troubleshooting)
|
||||
* [/automation/cron-jobs](/automation/cron-jobs)
|
||||
* [/gateway/heartbeat](/gateway/heartbeat)
|
||||
|
||||
## Node paired tool fails
|
||||
|
||||
If a node is paired but tools fail, isolate foreground, permission, and approval state.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
openclaw approvals get --node <idOrNameOrIp>
|
||||
openclaw logs --follow
|
||||
openclaw status
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* Node online with expected capabilities.
|
||||
* OS permission grants for camera/mic/location/screen.
|
||||
* Exec approvals and allowlist state.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `NODE_BACKGROUND_UNAVAILABLE` → node app must be in foreground.
|
||||
* `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → missing OS permission.
|
||||
* `SYSTEM_RUN_DENIED: approval required` → exec approval pending.
|
||||
* `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist.
|
||||
|
||||
Related:
|
||||
|
||||
* [/nodes/troubleshooting](/nodes/troubleshooting)
|
||||
* [/nodes/index](/nodes/index)
|
||||
* [/tools/exec-approvals](/tools/exec-approvals)
|
||||
|
||||
## Browser tool fails
|
||||
|
||||
Use this when browser tool actions fail even though the gateway itself is healthy.
|
||||
|
||||
```bash theme={null}
|
||||
openclaw browser status
|
||||
openclaw browser start --browser-profile openclaw
|
||||
openclaw browser profiles
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
* Valid browser executable path.
|
||||
* CDP profile reachability.
|
||||
* Extension relay tab attachment for `profile="chrome"`.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `Failed to start Chrome CDP on port` → browser process failed to launch.
|
||||
* `browser.executablePath not found` → configured path is invalid.
|
||||
* `Chrome extension relay is running, but no tab is connected` → extension relay not attached.
|
||||
* `Browser attachOnly is enabled ... not reachable` → attach-only profile has no reachable target.
|
||||
|
||||
Related:
|
||||
|
||||
* [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
|
||||
* [/tools/chrome-extension](/tools/chrome-extension)
|
||||
* [/tools/browser](/tools/browser)
|
||||
|
||||
## If you upgraded and something suddenly broke
|
||||
|
||||
Most post-upgrade breakage is config drift or stricter defaults now being enforced.
|
||||
|
||||
### 1) Auth and URL override behavior changed
|
||||
|
||||
```bash theme={null}
|
||||
openclaw gateway status
|
||||
openclaw config get gateway.mode
|
||||
openclaw config get gateway.remote.url
|
||||
openclaw config get gateway.auth.mode
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
* If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine.
|
||||
* Explicit `--url` calls do not fall back to stored credentials.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `gateway connect failed:` → wrong URL target.
|
||||
* `unauthorized` → endpoint reachable but wrong auth.
|
||||
|
||||
### 2) Bind and auth guardrails are stricter
|
||||
|
||||
```bash theme={null}
|
||||
openclaw config get gateway.bind
|
||||
openclaw config get gateway.auth.token
|
||||
openclaw gateway status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
* Non-loopback binds (`lan`, `tailnet`, `custom`) need auth configured.
|
||||
* Old keys like `gateway.token` do not replace `gateway.auth.token`.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `refusing to bind gateway ... without auth` → bind+auth mismatch.
|
||||
* `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.
|
||||
|
||||
### 3) Pairing and device identity state changed
|
||||
|
||||
```bash theme={null}
|
||||
openclaw devices list
|
||||
openclaw pairing list <channel>
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
* Pending device approvals for dashboard/nodes.
|
||||
* Pending DM pairing approvals after policy or identity changes.
|
||||
|
||||
Common signatures:
|
||||
|
||||
* `device identity required` → device auth not satisfied.
|
||||
* `pairing required` → sender/device must be approved.
|
||||
|
||||
If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:
|
||||
|
||||
```bash theme={null}
|
||||
openclaw gateway install --force
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Related:
|
||||
|
||||
* [/gateway/pairing](/gateway/pairing)
|
||||
* [/gateway/authentication](/gateway/authentication)
|
||||
* [/gateway/background-process](/gateway/background-process)
|
||||
Reference in New Issue
Block a user