OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

General troubleshooting

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

First 60 seconds

Run this ladder in order:

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

Good output, one line each:

  • 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 probe proved; Read probe: limited - missing scope: operator.read is degraded diagnostics, not a connect failure.
  • openclaw gateway status shows Runtime: running, Connectivity probe: ok, 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 only session_status.
  • tools.profile: "messaging" is narrow, for chat-only agents.
  • tools.profile: "coding" is the default for new local configs (repo, file, shell, and runtime work).
  • tools.profile: "full" removes profile restrictions; limit to trusted operator-controlled agents.
  • Per-agent agents.list[].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. 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 probes but fails on openclaw infer model run or normal agent turns:

  1. Error mentions messages[].content expecting a string: set models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Still fails only on OpenClaw agent turns: set models.providers.<provider>.models[].compat.supportsTools: false and retry.
  3. 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 probes 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:

  1. Add openclaw.extensions to package.json, pointing at built runtime files (usually ./dist/index.js).
  2. 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 fails closed.
  • 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 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
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

Good output:

  • Runtime: running
  • Connectivity probe: ok
  • 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
  • Connectivity probe: ok
  • 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 nuance.
  • 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
  • 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 → 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, Background process, 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 cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

Good output:

  • cron status shows the scheduler enabled with a next wake.
  • cron 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.md exists but contains only blank, comment, header, fence, or empty-checklist scaffolding.
  • heartbeat skipped reason no-tasks-due → task mode is active but no task interval is due yet.
  • heartbeat skipped reason alerts-disabled → showOk, showAlerts, and useIndicator are all off.
  • requests-in-flight → main lane busy; heartbeat wake 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

Was this useful?
On this page

On this page