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 (Reachable: yes). RPC: limited - missing scope: operator.read is degraded diagnostics, not a connect failure.
  • openclaw gateway status → Runtime: running and RPC probe: ok.
  • openclaw doctor → no blocking config/service errors.
  • openclaw channels status --probe → reachable gateway returns live per-account transport state plus probe/audit results such as works or audit ok; if the gateway is unreachable, the command falls back to config-only summaries.
  • openclaw logs --follow → steady activity, no repeating fatal errors.

​
Anthropic long context 429

If you see: HTTP 429: rate_limit_error: Extra usage is required for long context requests, go to /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

​
Plugin install fails with missing openclaw extensions

If install fails with package.json missing openclaw.extensions, the plugin package is using an old shape that OpenClaw no longer accepts. Fix in the plugin package:
  1. Add openclaw.extensions to package.json.
  2. Point entries at built runtime files (usually ./dist/index.js).
  3. Republish the plugin and run openclaw plugins install <package> again.
Example: 
{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}
Reference: Plugin architecture

​
Decision tree

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
Good output looks like:
  • Runtime: running
  • RPC probe: ok
  • Your channel shows transport connected and, where supported, works or audit ok 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.
  • origin not allowed → browser Origin is not allowed for the Control UI gateway target.
  • AUTH_TOKEN_MISMATCH with retry hints (canRetryWithDeviceToken=true) → one trusted device-token retry may occur automatically.
  • That cached-token retry reuses the cached scope set stored with the paired device token. Explicit deviceToken / explicit scopes callers keep their requested scope set instead.
  • On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure, so a second concurrent bad retry can already show retry later.
  • too many failed authentication attempts (retry later) from a localhost browser origin → repeated failures from that same Origin are temporarily locked out; another localhost origin uses a separate bucket.
  • repeated unauthorized after that retry → wrong token/password, auth mode mismatch, or stale paired device token.
  • 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 or existing config is missing gateway.mode → gateway mode is remote, or the config file is missing the local-mode stamp and should be repaired.
  • refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
  • 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 config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask
openclaw gateway restart
What changed:
  • If tools.exec.host is unset, the default is auto.
  • host=auto resolves to sandbox when a sandbox runtime is active, gateway otherwise.
  • host=auto is routing only; the no-prompt “YOLO” behavior comes from security=full plus ask=off on gateway/node.
  • On gateway and node, unset tools.exec.security defaults to full.
  • Unset tools.exec.ask defaults to off.
  • Result: if you are seeing approvals, some host-local or per-session policy tightened exec away from the current defaults.
Restore current default no-approval behavior:
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart
Safer alternatives:
  • Set only tools.exec.host=gateway if you just want stable host routing.
  • Use security=allowlist with ask=on-miss if you want host exec but still want review on allowlist misses.
  • Enable sandbox mode if you want host=auto to resolve back to sandbox.
Common log signatures:
  • Approval required. → command is waiting on /approve ....
  • SYSTEM_RUN_DENIED: approval required → node-host exec approval is pending.
  • exec host=sandbox requires a sandbox runtime for this session → implicit/explicit sandbox selection but sandbox mode is off.
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 starts, or user can see local Chrome tabs.
Common log signatures:
  • unknown command "browser" or unknown command 'browser' → plugins.allow is set and does not include browser.
  • Failed to start Chrome CDP on port → local browser launch failed.
  • browser.executablePath not found → configured binary path is wrong.
  • browser.cdpUrl must be http(s) or ws(s) → the configured CDP URL uses an unsupported scheme.
  • browser.cdpUrl has invalid port → the configured CDP URL has a bad or out-of-range port.
  • No Chrome tabs found for profile="user" → the Chrome MCP attach profile has no open local Chrome tabs.
  • Remote CDP for profile "<name>" is not reachable → the configured remote CDP endpoint is not reachable from this host.
  • Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no live CDP target.
  • stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run openclaw browser stop --browser-profile <name> to close the active control session and release emulation state without restarting the gateway.
Deep pages: