Start here

General troubleshooting

Triage front door. 2 minutes to a diagnosis, then jump to the deep page.

For official OpenClaw support, visit community.openclaw.ai. See Get support for safe diagnostics and separate bug and security reporting routes.

First 60 seconds

Run this ladder in order:

bash

openclaw triageopenclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

Good output, one line each:

openclaw triage writes a sanitized, agent-ready diagnosis and, when the Gateway is reachable, a support archive. See Triage for agent handoff options.
openclaw status shows configured channels, no auth errors.
openclaw status --all produces a full, shareable report.
openclaw gateway probe shows Reachable: yes. Capability: ... is the auth level the check proved. Missing operator.read scope limits read diagnostics; it does not mean the connection failed.
openclaw gateway status shows Runtime: running, a successful connectivity check, and a plausible Capability: .... Add --require-rpc to also require read-scope RPC proof.
openclaw doctor reports no blocking config/service errors.
openclaw channels status --probe returns live per-account transport state (works / audit ok) when the gateway is reachable; falls back to config-only summaries when it is not.
openclaw logs --follow shows steady activity, no repeating fatal errors.

Assistant feels limited or missing tools

Check the effective tool profile:

bash

openclaw statusopenclaw status --allopenclaw doctor

Common causes:

tools.profile: "minimal" allows session_status and gateway maintenance (update.run, restart, and update.cleanup), but not configuration reads.
tools.profile: "messaging" is narrow, for chat-only agents.
tools.profile: "coding" selects repo, file, shell, and runtime work.
tools.profile: "full" is the local onboarding default. It removes core profile filtering and selects optional plugin tools, subject to independent restrictions.
An unset profile leaves core tools unfiltered but does not itself select optional plugin tools. Existing configs stay unchanged unless onboarding is run again.
Per-agent agents.entries.*.tools overrides narrow or expand the root profile for one agent.

Change the profile, restart or reload the Gateway, then recheck with openclaw status --all. Check the chat Execution permissions menu separately; Full tool selection does not grant Full Access or configure missing plugins. Full profile/group table: 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/self-hosted /v1 backend answers direct /v1/chat/completions checks but fails on openclaw infer model run or normal agent turns:

Error mentions messages[].content expecting a string: set models.providers.<provider>.models[].compat.requiresStringContent: true.
Still fails only on OpenClaw agent turns: set models.providers.<provider>.models[].compat.supportsTools: false and retry.
Tiny direct calls work but larger OpenClaw prompts crash the backend: that is an upstream model/server limit, not an OpenClaw bug. Continue in Local OpenAI-compatible backend passes direct checks but agent runs fail.

Plugin install fails with missing openclaw extensions

package.json missing openclaw.extensions means the plugin package uses a shape OpenClaw no longer accepts.

Fix in the plugin package:

Add openclaw.extensions to package.json, pointing at built runtime files (usually ./dist/index.js).
Republish, then run openclaw plugins install <package> again.

json

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

Reference: Plugin architecture

Install policy blocks plugin installs or updates

Update finishes but plugins are stale, disabled, or show blocked by install policy, install policy failed closed, or Disabled "<plugin>" after plugin update failure: check security.installPolicy.

Install policy runs on plugin installs and updates. @openclaw/* plugin versions normally move with the OpenClaw release, so an OpenClaw update can need a matching plugin update during post-update sync.

Avoid these policy shapes unless you also maintain the matching upgrade rule:

Freezing OpenClaw-owned plugins to one exact old version (for example, only @openclaw/*@2026.5.3).
Blocking by source kind alone (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 blocks the install.
Approving versions without checking the request's openclawVersion against plugin candidate metadata.

Prefer rules that allow trusted @openclaw/* updates compatible with the current host, instead of pinning one release forever. If you block npm by default, add a narrow exception for the plugin ids you use, and apply the same trust rule to request.mode: "update" as to installs.

Recovery:

bash

openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

If the policy is intentionally strict, relax it for the trusted upgrade window, rerun openclaw plugins update --all, then restore the stricter rule. If update failure disabled a plugin, inspect before re-enabling:

bash

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

Reference: Operator install policy

Plugin present but blocked by suspicious ownership

openclaw doctor, setup, or startup warnings show:

text

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

The plugin files are owned by a different Unix user than the process loading them. Do not remove the plugin config; fix the file ownership, or run OpenClaw as the user that owns the state directory.

Docker installs run as node (uid 1000). Repair the host bind mounts:

bash

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

If you intentionally run OpenClaw as root, repair the managed plugin root instead:

bash

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

Deeper docs: 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 installed but 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 tool fails camera canvas screen exec]
  B --> I[Exec suddenly asks for approval]
  B --> J[Browser tool fails]

Each branch is the title of an accordion below.

No replies

bash

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

Good output:

Runtime: running
A successful connectivity check
Capability: read-only, write-capable, or admin-capable
Channel shows transport connected and, where supported, works or audit ok in channels status --probe
Sender is approved (or DM policy is open/allowlist)

Log signatures:

drop guild message (mention required → Discord mention gating blocked the message.
pairing request → sender unapproved, waiting on DM pairing approval.
blocked / allowlist in channel logs → sender, room, or group filtered.

Deep pages: No replies, Channel troubleshooting, Pairing

Dashboard or Control UI will not connect

bash

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Good output:

Dashboard: http://... shown in openclaw gateway status
A successful connectivity check
Capability: read-only, write-capable, or admin-capable
No auth loop in logs

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 canRetryWithDeviceToken=true → one trusted device-token retry may occur automatically, reusing the paired token's cached scopes.
repeated unauthorized after that retry → wrong token/password, auth mode mismatch, or stale paired device token.
too many failed authentication attempts (retry later) → repeated failures from that browser Origin are temporarily locked out; other localhost origins use separate buckets. See Dashboard/Control UI connectivity for the Tailscale Serve concurrent-retry details.
gateway connect failed: → UI targets the wrong URL/port, or the gateway is unreachable.

Deep pages: Dashboard/Control UI connectivity, Control UI, Authentication

Gateway will not start or service installed but not running

bash

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Good output:

Service: ... (loaded)
Runtime: running
A successful connectivity check
Capability: read-only, write-capable, or admin-capable

Log signatures:

Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → gateway mode is remote, or config is missing the local-mode stamp and needs repair.
refusing to bind gateway ... without auth → non-loopback bind without a valid auth path (token/password, or trusted-proxy where configured).
another gateway instance is already listening or EADDRINUSE → port already taken.

Deep pages: Gateway service not running, Supervision and service lifecycle, Configuration

Channel connects but messages do not flow

bash

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Good output:

Channel transport connected.
Pairing/allowlist checks pass.
Mentions detected where required.

Log signatures:

mention required → group mention gating blocked processing.
pairing / pending → DM sender not 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

bash

openclaw statusopenclaw gateway statusopenclaw automations statusopenclaw automations listopenclaw automations runs <jobId> --limit 20openclaw logs --follow

Good output:

automations status shows the scheduler enabled with a next wake.
automations runs shows recent ok entries.
Heartbeat is enabled and inside active hours.

Log signatures:

cron: scheduler disabled; jobs will not run automatically → cron is disabled.
heartbeat skipped reason quiet-hours → outside configured active hours.
heartbeat skipped reason empty-heartbeat-file → heartbeat monitor scratch contains only blank, comment, header, fence, or empty-checklist markup.
heartbeat skipped reason alerts-disabled → showOk, showAlerts, and useIndicator are all off.
requests-in-flight → the heartbeat's target session is busy; heartbeat wake dropped or deferred.
unknown accountId → 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

bash

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

Good output:

Node listed as connected and paired for role node.
Capability exists for the command you are invoking.
Permission state granted for the tool.

Log signatures:

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

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

Exec suddenly asks for approval

bash

openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

What changed:

Unset tools.exec.host defaults to auto, which resolves to sandbox when a sandbox runtime is active, gateway otherwise.
host=auto only routes; the no-prompt behavior comes from security=full plus ask=off on gateway/node.
Unset tools.exec.security defaults to full on gateway/node.
Unset tools.exec.ask defaults to off.
If you are seeing approvals, some host-local or per-session policy tightened exec away from these defaults.

Restore the current no-approval defaults:

bash

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

Safer alternatives:

Set only tools.exec.host=gateway for stable host routing.
Use security=allowlist with ask=on-miss for host exec with review on allowlist misses.
Enable sandbox mode so host=auto resolves back to sandbox.

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: Exec, Exec approvals, Security: What the audit checks

Browser tool fails

bash

openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

Good output:

Browser status shows running: true and a chosen browser/profile.
openclaw profile starts, or user profile sees local Chrome tabs.

Log signatures:

unknown command "browser" → plugins.allow is set and excludes 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) → configured CDP URL uses an unsupported scheme.
browser.cdpUrl has invalid port → 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 → configured remote CDP endpoint unreachable from this host.
Browser attachOnly is enabled ... 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 control session and release emulation state without restarting the gateway.

Deep pages: Browser tool fails, Missing browser command or tool, Browser: Linux troubleshooting, Browser: WSL2/Windows remote CDP troubleshooting

FAQ — frequently asked questions
Gateway Troubleshooting — gateway-specific issues
Doctor — automated health checks and repairs
Channel Troubleshooting — channel connectivity issues
Scheduled tasks: Troubleshooting — cron and heartbeat issues

Was this useful?