OpenClaw Troubleshooting Guide

Triage entry point. Reach a diagnosis in about two minutes, then move to the detailed page.

First 60 seconds

Work through this sequence in order:

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

With healthy output, each line shows:

openclaw status lists the configured channels without any authentication errors.
openclaw status --all generates a complete report that can be shared.
openclaw gateway probe displays Reachable: yes. Capability: ... reflects the authentication level verified by the probe; Read probe: limited - missing scope: operator.read points to degraded diagnostics rather than a connection failure.
openclaw gateway status shows Runtime: running, Connectivity probe: ok, and a sensible Capability: .... Append --require-rpc if you also want proof of read-scope RPC.
openclaw doctor finds no blocking configuration or service errors.
openclaw channels status --probe gives live transport state per account (works / audit ok) when the gateway is reachable; otherwise it falls back to summaries based on configuration only.
openclaw logs --follow indicates steady activity with no recurring fatal errors.

Assistant feels limited or missing tools

Verify the active tool profile:

openclaw status
openclaw status --all
openclaw doctor

Typical reasons:

tools.profile: "minimal" restricts access to session_status.
tools.profile: "messaging" is limited, intended for chat-only agents.
tools.profile: "coding" serves as the default for fresh local setups (repo, file, shell, and runtime operations).
tools.profile: "full" lifts all profile restrictions; reserve it for trusted operator-controlled agents.
A per-agent agents.entries.*.tools either tightens or broadens the root profile for a single agent.

After changing the profile, restart or reload the Gateway, then confirm with openclaw status --all. See the full profile/group reference: Tool profiles.

Anthropic long context 429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Anthropic 429 extra usage required for long context.

Local OpenAI-compatible backend works directly but fails in OpenClaw

Your local or self-hosted /v1 backend handles direct /v1/chat/completions probes but fails on openclaw infer model run or normal agent turns:

If the error mentions messages[].content expecting a string, configure models.providers.<provider>.models[].compat.requiresStringContent: true.
If failures occur only on OpenClaw agent turns, set models.providers.<provider>.models[].compat.supportsTools: false and try again.
Small direct calls succeed but larger OpenClaw prompts crash the backend: that is an upstream model or server constraint, not an OpenClaw defect. Continue with Local OpenAI-compatible backend passes direct probes but agent runs fail.

Plugin install fails with missing openclaw extensions

package.json missing openclaw.extensions indicates the plugin package uses a structure OpenClaw no longer supports.

Resolve it inside the plugin package:

Add openclaw.extensions to package.json, pointing to built runtime artifacts (typically ./dist/index.js).
Republish, then execute openclaw plugins install <package> once more.

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Reference: Plugin architecture

Install policy blocks plugin installs or updates

An update completes but plugins remain outdated, disabled, or report blocked by install policy, install policy failed closed, or Disabled "<plugin>" after plugin update failure: inspect security.installPolicy.

Install policy applies during plugin installs and updates. @openclaw/* plugin versions generally track the OpenClaw release, so an OpenClaw upgrade can require a corresponding plugin upgrade during post-update sync.

Steer clear of these policy patterns unless you also maintain the matching upgrade rule:

Pinning OpenClaw-owned plugins to a single old version (for instance, only @openclaw/*@2026.5.3).
Filtering solely by source kind (every npm, network, or request.mode: "update" request).
Treating the policy command as optional: when security.installPolicy is enabled, a missing, slow, unreadable, or permission-blocked policy executable fails closed.
Approving versions without comparing the request's openclawVersion against plugin candidate metadata.

Choose rules that permit trusted @openclaw/* updates compatible with the current host, rather than locking one release forever. If npm is blocked by default, add a narrow exception for the plugin ids you rely on, and enforce the same trust rule for request.mode: "update" as for installs.

Recovery:

openclaw doctor --deep
openclaw plugins update --all
openclaw status --all

When the policy is deliberately restrictive, loosen it for the trusted upgrade period, execute openclaw plugins update --all once more, then bring back the stricter configuration. If a plugin was turned off because of a failed update, check it carefully before turning it back on:

openclaw plugins inspect <plugin-id> --runtime --json
openclaw plugins enable <plugin-id>

Reference: Operator install policy

Plugin present but blocked by suspicious ownership

openclaw doctor, setup, or startup warnings appear:

blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
plugin present but blocked

A different Unix user than the one running the process owns the plugin files. Leave the plugin config untouched; correct the file ownership instead, or start OpenClaw under the user that holds the state directory.

Docker deployments operate as node (uid 1000). Fix the host bind mounts:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

When you deliberately run OpenClaw as root, repair the managed plugin root:

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

More detail: Blocked plugin path ownership, Docker: Permissions and EACCES

Decision tree

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

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

Expected results:

Runtime: running
Connectivity probe: ok
Capability: read-only, write-capable, or admin-capable
Transport shows connected on the channel, plus works or audit ok in channels status --probe where supported
Sender approved, or DM policy set to open/allowlist

Log clues:

drop guild message (mention required → Discord mention gating stopped the message.
pairing request → sender not approved, awaiting DM pairing approval.
blocked / allowlist in channel logs → sender, room, or group filtered.

Further reading: No replies, Channel troubleshooting, Pairing

Dashboard or Control UI will not connect

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

Expected results:

Dashboard: http://... visible in openclaw gateway status
Connectivity probe: ok
Capability: read-only, write-capable, or admin-capable
No repeated auth attempts in logs

Log clues:

device identity required → device auth cannot finish in an HTTP/non-secure context.
origin not allowed → browser Origin is blocked for the Control UI gateway target.
AUTH_TOKEN_MISMATCH with canRetryWithDeviceToken=true → one automatic retry of a trusted device-token may occur, reusing cached scopes from the paired token.
unauthorized recurring after that retry → wrong token/password, mismatched auth mode, or an outdated paired device token.
too many failed authentication attempts (retry later) → that browser Origin is temporarily locked out after repeated failures; other localhost origins have separate buckets. Check Dashboard/Control UI connectivity for the Tailscale Serve concurrent-retry detail.
gateway connect failed: → UI points to an incorrect URL/port, or the gateway cannot be reached.

More detail: Dashboard/Control UI connectivity, Control UI, Authentication

Gateway will not start or service installed but not running

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

Expected results:

Service: ... (loaded)
Runtime: running
Connectivity probe: ok
Capability: read-only, write-capable, or admin-capable

Log signatures:

Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → remote gateway mode is active, or the local-mode marker is absent from the config and requires fixing.
refusing to bind gateway ... without auth → binding to a non-loopback address without a valid authentication route (token/password, or trusted-proxy when enabled).
another gateway instance is already listening or EADDRINUSE → the port is already in use.

Deep pages: Gateway service not running, Background process, Configuration

Channel connects but messages do not flow

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

Good output:

Channel transport is connected.
Pairing and allowlist checks pass.
Mentions are detected when required.

Log signatures:

mention required → group mention gating stopped processing.
pairing / pending → DM sender has not been approved yet.
not_in_channel, missing_scope, Forbidden, 401/403 → channel permission token issue.

Deep pages: Channel connected, messages not flowing, Channel troubleshooting

Cron or heartbeat did not fire or did not deliver

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

Good output:

cron status shows the scheduler is enabled with a next wake time.
cron runs shows recent ok entries.
Heartbeat is enabled and falls within active hours.

Log signatures:

cron: scheduler disabled; jobs will not run automatically → cron is disabled.
heartbeat skipped reason quiet-hours → outside the configured active hours.
heartbeat skipped reason empty-heartbeat-file → heartbeat monitor scratch contains only blank lines, comments, headers, fences, or empty-checklist scaffolding.
heartbeat skipped reason alerts-disabled → showOk, showAlerts, and useIndicator are all turned off.
requests-in-flight → main lane is busy; heartbeat wake was postponed.
unknown accountId → the heartbeat delivery target account does not exist.

Deep pages: Cron and heartbeat delivery, Scheduled tasks: Troubleshooting, Heartbeat

Node is paired but tool fails camera canvas screen exec

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

Good output:

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.

Log signatures:

NODE_BACKGROUND_UNAVAILABLE → bring the node app to the foreground.
*_PERMISSION_REQUIRED → OS permission is denied or missing.
SYSTEM_RUN_DENIED: approval required → exec approval is waiting.
SYSTEM_RUN_DENIED: allowlist miss → command is not on the exec allowlist.

Deep pages: Node paired, tool fails, Node troubleshooting, Exec approvals

Exec suddenly asks for approval

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

What changed:

When tools.exec.host is not set, it falls back to auto, and that value points to sandbox if a sandbox runtime is active, or gateway in other cases.
host=auto handles routing exclusively; the absence of prompts is driven by security=full combined with ask=off on gateway and node.
Leaving tools.exec.security unset applies full by default on gateway and node.
If tools.exec.ask remains unset, off becomes the default.
Approvals appearing in your workflow indicate that host-local or per-session policies have restricted exec beyond these defaults.

To bring back the current no-approval defaults:

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

More cautious options:

Configure only tools.exec.host=gateway to keep host routing stable.
Pair security=allowlist with ask=on-miss for host exec that reviews allowlist misses.
Turn on sandbox mode so host=auto maps back to sandbox.

Log markers:

Approval required. signals that a command is blocked on /approve ....
SYSTEM_RUN_DENIED: approval required means node-host exec approval is still pending.
exec host=sandbox requires a sandbox runtime for this session indicates implicit or explicit sandbox selection, yet sandbox mode is disabled.

Browser tool fails

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

Expected results:

The browser status displays running: true along with a selected browser and profile.
The openclaw profile launches, or the user profile picks up local Chrome tabs.

Log markers:

unknown command "browser" means plugins.allow is configured and excludes browser.
Failed to start Chrome CDP on port indicates the local browser could not start.
browser.executablePath not found points to an incorrect binary path in the configuration.
browser.cdpUrl must be http(s) or ws(s) shows the CDP URL uses a scheme that is not supported.
browser.cdpUrl has invalid port flags a CDP URL with an invalid or out-of-range port.
No Chrome tabs found for profile="user" means the Chrome MCP attach profile has no open local Chrome tabs.
Remote CDP for profile "<name>" is not reachable indicates the configured remote CDP endpoint cannot be reached from this host.
Browser attachOnly is enabled ... not reachable means an attach-only profile has no live CDP target.
Stale viewport, dark-mode, locale, or offline overrides on attach-only or remote CDP profiles: run openclaw browser stop --browser-profile <name> to close the control session and clear emulation state without restarting the gateway.

FAQ, common questions
Gateway Troubleshooting, issues specific to the gateway
Doctor, automated checks and fixes
Channel Troubleshooting, connectivity problems with channels
Scheduled tasks: Troubleshooting, cron and heartbeat problems

First 60 seconds

Assistant feels limited or missing tools

Anthropic long context 429

Local OpenAI-compatible backend works directly but fails in OpenClaw

Plugin install fails with missing openclaw extensions

Install policy blocks plugin installs or updates

Plugin present but blocked by suspicious ownership

Decision tree

No replies

Dashboard or Control UI will not connect

Gateway will not start or service installed but not running

Channel connects but messages do not flow

Cron or heartbeat did not fire or did not deliver

Node is paired but tool fails camera canvas screen exec

Exec suddenly asks for approval

Browser tool fails

Related