Skip to main content

​
Troubleshooting

If you only have 2 minutes, use this page as a triage front door.

​
First 60 seconds

Run this exact ladder in order: 
openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
Good output in one line:
  • openclaw status → shows configured channels and no obvious auth errors.
  • openclaw status --all → full report is present and shareable.
  • openclaw gateway probe → expected gateway target is reachable.
  • openclaw gateway status → Runtime: running and RPC probe: ok.
  • openclaw doctor → no blocking config/service errors.
  • openclaw channels status --probe → channels report connected or ready.
  • openclaw logs --follow → steady activity, no repeating fatal errors.

​
Decision tree

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow
Good output looks like:
  • Runtime: running
  • RPC probe: ok
  • Your channel shows connected/ready in channels status --probe
  • Sender appears approved (or DM policy is open/allowlist)
Common log signatures:
  • drop guild message (mention required → mention gating blocked the message in Discord.
  • pairing request → sender is unapproved and waiting for DM pairing approval.
  • blocked / allowlist in channel logs → sender, room, or group is filtered.
Deep pages:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Good output looks like:
  • Dashboard: http://... is shown in openclaw gateway status
  • RPC probe: ok
  • No auth loop in logs
Common log signatures:
  • device identity required → HTTP/non-secure context cannot complete device auth.
  • unauthorized / reconnect loop → wrong token/password or auth mode mismatch.
  • gateway connect failed: → UI is targeting the wrong URL/port or unreachable gateway.
Deep pages:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Good output looks like:
  • Service: ... (loaded)
  • Runtime: running
  • RPC probe: ok
Common log signatures:
  • Gateway start blocked: set gateway.mode=local → gateway mode is unset/remote.
  • refusing to bind gateway ... without auth → non-loopback bind without token/password.
  • another gateway instance is already listening or EADDRINUSE → port already taken.
Deep pages:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Good output looks like:
  • Channel transport is connected.
  • Pairing/allowlist checks pass.
  • Mentions are detected where required.
Common log signatures:
  • mention required → group mention gating blocked processing.
  • pairing / pending → DM sender is not approved yet.
  • not_in_channel, missing_scope, Forbidden, 401/403 → channel permission token issue.
Deep pages:
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow
Good output looks like:
  • cron.status shows enabled with a next wake.
  • cron runs shows recent ok entries.
  • Heartbeat is enabled and not outside active hours.
Common log signatures:
  • cron: scheduler disabled; jobs will not run automatically → cron is disabled.
  • heartbeat skipped with reason=quiet-hours → outside configured active hours.
  • requests-in-flight → main lane busy; heartbeat wake was deferred.
  • unknown accountId → heartbeat delivery target account does not exist.
Deep pages:
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow
Good output looks like:
  • Node is listed as connected and paired for role node.
  • Capability exists for the command you are invoking.
  • Permission state is granted for the tool.
Common log signatures:
  • NODE_BACKGROUND_UNAVAILABLE → bring node app to foreground.
  • *_PERMISSION_REQUIRED → OS permission was denied/missing.
  • SYSTEM_RUN_DENIED: approval required → exec approval is pending.
  • SYSTEM_RUN_DENIED: allowlist miss → command not on exec allowlist.
Deep pages:
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor
Good output looks like:
  • Browser status shows running: true and a chosen browser/profile.
  • openclaw profile starts or chrome relay has an attached tab.
Common log signatures:
  • Failed to start Chrome CDP on port → local browser launch failed.
  • browser.executablePath not found → configured binary path is wrong.
  • Chrome extension relay is running, but no tab is connected → extension not attached.
  • Browser attachOnly is enabled ... not reachable → attach-only profile has no live CDP target.
Deep pages: