General troubleshooting

If you only have 2 minutes, use this page as a triage front door.

First 60 seconds

Run this exact ladder in order:

bash
Copy
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:

• text

  Copy

  openclaw status
  → shows configured channels and no obvious auth errors.
• text

  Copy

  openclaw status --all
  → full report is present and shareable.
• text

  Copy

  openclaw gateway probe
  → expected gateway target is reachable (
  text

  Copy

  Reachable: yes
  ).
  text

  Copy

  Capability: ...
  tells you what auth level the probe could prove, and
  text

  Copy

  Read probe: limited - missing scope: operator.read
  is degraded diagnostics, not a connect failure.
• text

  Copy

  openclaw gateway status
  →
  text

  Copy

  Runtime: running
  ,
  text

  Copy

  Connectivity probe: ok
  , and a plausible
  text

  Copy

  Capability: ...
  line. Use
  text

  Copy

  --require-rpc
  if you need read-scope RPC proof too.
• text

  Copy

  openclaw doctor
  → no blocking config/service errors.
• text

  Copy

  openclaw channels status --probe
  → reachable gateway returns live per-account transport state plus probe/audit results such as
  text

  Copy

  works
  or
  text

  Copy

  audit ok
  ; if the gateway is unreachable, the command falls back to config-only summaries.
• text

  Copy

  openclaw logs --follow
  → steady activity, no repeating fatal errors.

Anthropic long context 429

If you see:

, go to /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

backend answers small direct probes but fails on or normal agent turns:

1. If the error mentions
   text

   Copy

   messages[].content
   expecting a string, set
   text

   Copy

   models.providers.<provider>.models[].compat.requiresStringContent: true
   .
2. If the backend still fails only on OpenClaw agent turns, set
   text

   Copy

   models.providers.<provider>.models[].compat.supportsTools: false
   and retry.
3. If tiny direct calls still work but larger OpenClaw prompts crash the backend, treat the remaining issue as an upstream model/server limitation and continue 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 install fails with

, the plugin package is using an old shape that OpenClaw no longer accepts.

Fix in the plugin package:

1. Add
   text

   Copy

   openclaw.extensions
   to
   text

   Copy

   package.json
   .
2. Point entries at built runtime files (usually
   text

   Copy

   ./dist/index.js
   ).
3. Republish the plugin and run
   text

   Copy

   openclaw plugins install <package>
   again.

Example:

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

Reference: Plugin architecture

Decision tree

mermaid
Copy
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

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

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