Troubleshoot OpenClaw: Resolve Issues in 2 Minutes

First 60 seconds

If you only have a minute, run this exact ladder in order to triage the situation:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Here is what you want to see in the output:

openclaw status shows your configured channels and confirms there are no obvious auth errors.
openclaw status --all provides a full report that is ready to share.
openclaw gateway probe confirms the gateway target is reachable. If you see RPC: limited - missing scope: operator.read, it just means diagnostics are degraded, not that the connection failed.
openclaw gateway status shows the runtime is running and the RPC probe is ok.
openclaw doctor verifies there are no blocking config or service errors.
openclaw channels status --probe gets live transport states and audit results from the gateway. If the gateway is down, it falls back to config summaries.
openclaw logs --follow lets you monitor for steady activity and repeating fatal errors.

Anthropic long context 429

If you run into this specific error: HTTP 429: rate_limit_error: Extra usage is required for long context requests, you should check out the details at /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

Local OpenAI-compatible backend works directly but fails in OpenClaw

If your local or self-hosted /v1 backend answers small direct /v1/chat/completions probes but fails when you run openclaw infer model run or start normal agent turns, you can try these fixes.

If you see an error mentioning that messages[].content expects a string, you need to set models.providers.<provider>.models[].compat.requiresStringContent: true in your configuration.
If the backend still fails specifically on OpenClaw agent turns, you should set models.providers.<provider>.models[].compat.supportsTools: false and try again.
Sometimes tiny direct calls work fine, but larger OpenClaw prompts crash the backend. If that happens, you should treat the issue as an upstream model or server limitation. You can find more details in the deep runbook: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

Plugin install fails with missing openclaw extensions

If you see an error saying package.json missing openclaw.extensions during installation, the plugin package uses an old format that OpenClaw no longer accepts.

You can fix this in the plugin package with these steps:

Add openclaw.extensions to your package.json.
Point the entries at your built runtime files (this is usually ./dist/index.js).
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

When things go wrong, you need a clear path to the fix. Use this logic flow to figure out which part of the system is acting up.

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]

No replies

If you are sending messages but getting nothing back, start by checking your status and logs. You want to see that the runtime is active and the RPC probe is healthy.

    openclaw status
    openclaw gateway status
    openclaw channels status --probe
    openclaw pairing list --channel <channel> [--account <id>]
    openclaw logs --follow

You know things are looking good when:

Runtime: running
RPC probe: ok
Your channel shows the transport is connected.
For supported channels, you see works or audit ok in the status probe.
The sender is approved or your DM policy allows the message.

Keep an eye out for these log signatures:

drop guild message (mention required — This means Discord blocked the message because a mention was missing.
pairing request — The sender isn’t approved yet and is waiting for you to allow the DM pairing.
blocked or allowlist — The sender, room, or group is being filtered out by your settings.

For more details, check out these pages:

Dashboard or Control UI will not connect

When the UI won’t load or connect to the gateway, you need to verify the gateway’s identity and your browser’s context.

    openclaw status
    openclaw gateway status
    openclaw logs --follow
    openclaw doctor
    openclaw channels status --probe

A healthy setup shows:

A valid Dashboard: http://... URL in your gateway status.
RPC probe: ok.
No infinite loops during authentication in the logs.

If it’s failing, you might see these in the logs:

device identity required — This usually happens when a non-secure context (HTTP) tries to finish device auth.
origin not allowed — Your browser’s Origin isn’t on the allowed list for the gateway.
AUTH_TOKEN_MISMATCH — You might see a hint that it canRetryWithDeviceToken=true. This retry uses the cached scopes from the paired device.
too many failed authentication attempts (retry later) — If you fail too many times from a localhost origin, you’ll be locked out temporarily.
unauthorized — This points to a wrong token, password, or a stale device token.
gateway connect failed: — The UI is trying to hit the wrong URL or port.

Deep dive here:

Gateway will not start or service installed but not running

If the background service is stuck or won’t boot, check the runtime and service load status.

    openclaw status
    openclaw gateway status
    openclaw logs --follow
    openclaw doctor
    openclaw channels status --probe

You are looking for:

Service: ... (loaded)
Runtime: running
RPC probe: ok

Common blockers include:

Gateway start blocked: set gateway.mode=local — The gateway thinks it’s in remote mode or the config is missing the local-mode stamp.
refusing to bind gateway ... without auth — You’re trying to bind to something other than loopback without setting up a token, password, or trusted proxy.
another gateway instance is already listening or EADDRINUSE — Something else is already using that port.

Channel connects but messages do not flow

Sometimes the connection looks fine, but the data just isn’t moving. You need to verify permissions and gating.

    openclaw status
    openclaw gateway status
    openclaw logs --follow
    openclaw doctor
    openclaw channels status --probe

Check if:

The channel transport is actually connected.
Pairing and allowlist checks are passing.
Mentions are being detected if they are required.

Log clues to watch for:

mention required — Group gating is blocking the message.
pairing or pending — You haven’t approved the DM sender yet.
not_in_channel, missing_scope, Forbidden, or 401/403 — These are all signs of a permission or token issue.

Troubleshooting links:

Cron or heartbeat did not fire or did not deliver

When automated tasks or heartbeats go silent, check the scheduler and the specific job history.

    openclaw status
    openclaw gateway status
    openclaw cron status
    openclaw cron list
    openclaw cron runs --id <jobId> --limit 20
    openclaw logs --follow

A working automation setup shows:

cron.status as enabled with a scheduled “next wake” time.
Recent ok entries in your cron runs.
Heartbeats that are enabled and currently inside their active hours.

If they aren’t firing, look for:

cron: scheduler disabled — The whole cron system is turned off.
heartbeat skipped with reason=quiet-hours — You’re outside the allowed time window.
heartbeat skipped with reason=empty-heartbeat-file — Your HEARTBEAT.md is just a blank template.
heartbeat skipped with reason=no-tasks-due — Task mode is on, but nothing is scheduled yet.
heartbeat skipped with reason=alerts-disabled — All visibility settings like showOk and showAlerts are off.
requests-in-flight — The main lane is too busy, so the heartbeat was pushed back.
unknown accountId — The account you’re trying to send the heartbeat to doesn’t exist.

More info:

Node is paired but tool fails camera canvas screen exec

If your node is connected but can’t execute specific tools like camera or screen commands, check the node’s capabilities.

      openclaw status
      openclaw gateway status
      openclaw nodes status
      openclaw nodes describe --node <idOrNameOrIp>
      openclaw logs --follow

Confirm that:

The node is listed as connected and has the node role.
The node actually has the capability for the command you’re running.
You’ve granted the necessary permissions for the tool.

Watch for these errors:

NODE_BACKGROUND_UNAVAILABLE — You need to bring the node app to the foreground.
*_PERMISSION_REQUIRED — The OS is blocking access (camera, screen, etc.).
SYSTEM_RUN_DENIED: approval required — The execution is waiting for you to say yes.
SYSTEM_RUN_DENIED: allowlist miss — The command isn’t on the allowed list.

Deep dive:

Exec suddenly asks for approval

If you used to run commands freely and now you’re getting prompts, your security policy or routing has changed.

      openclaw config get tools.exec.host
      openclaw config get tools.exec.security
      openclaw config get tools.exec.ask
      openclaw gateway restart

Here is how the logic works:

If tools.exec.host isn’t set, it defaults to auto.
host=auto sends commands to the sandbox if it’s active, otherwise to the gateway.
The “no-prompt” behavior happens when security=full and ask=off.
On the gateway and nodes, tools.exec.security defaults to full and tools.exec.ask defaults to off if they are unset.

To get back to the default no-approval behavior, run:

      openclaw config set tools.exec.host gateway
      openclaw config set tools.exec.security full
      openclaw config set tools.exec.ask off
      openclaw gateway restart

If you want to be safer, you can set tools.exec.host=gateway for stable routing, or use security=allowlist with ask=on-miss to only review things you haven’t pre-approved.

Log signatures:

Approval required. — The command is stuck waiting for an /approve command.
SYSTEM_RUN_DENIED: approval required — A node-host execution is pending approval.
exec host=sandbox requires a sandbox runtime — You’ve selected the sandbox, but it isn’t running.

Documentation:

Browser tool fails

When the browser tool stops working, it’s usually a path issue or a connection problem with the Chrome DevTools Protocol (CDP).

      openclaw status
      openclaw gateway status
      openclaw browser status
      openclaw logs --follow
      openclaw doctor

A good status shows:

running: true for the browser.
A valid browser profile being used.
Local Chrome tabs are visible to the user.

Common errors in the logs:

unknown command "browser" — Your plugins.allow list is active and doesn’t include the browser plugin.
Failed to start Chrome CDP on port — The local browser couldn’t launch.
browser.executablePath not found — The path to your browser binary is wrong.
browser.cdpUrl must be http(s) or ws(s) — You’re using an unsupported URL scheme.
No Chrome tabs found for profile="user" — The profile you’re trying to attach to has no open tabs.
Remote CDP for profile "<name>" is not reachable — The gateway can’t talk to the remote CDP endpoint.

If you have stale viewport or dark-mode settings on an attach-only profile, you can reset the session without restarting the whole gateway: openclaw browser stop --browser-profile <name>

Troubleshooting resources:

If you need more help or want to explore specific topics, these guides are the best place to start.

You can browse the FAQ for answers to common questions. If you are running into gateway-specific issues, check out Gateway Troubleshooting.

For a hands-off approach, Doctor provides automated health checks and repairs. If you are dealing with connectivity problems, the Channel Troubleshooting guide has you covered.

For issues with cron jobs or heartbeats, you should look at Automation Troubleshooting.

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.