Use this file to discover all available pages before exploring further.

Troubleshooting

This page is the deep runbook. Start at /help/troubleshooting if you want the fast triage flow first.

Command ladder

Run these first, in this order:


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

Expected healthy signals:

text
openclaw gateway status
shows
text
Runtime: running
,
text
Connectivity probe: ok
, and a
text
Capability: ...
line.
text
openclaw doctor
reports no blocking config/service issues.
text
openclaw channels status --probe
shows live per-account transport status and, where supported, probe/audit results such as
text
works
or
text
audit ok
.

Split brain installs and newer config guard

Use this when a gateway service unexpectedly stops after an update, or logs show that one

text

openclaw

binary is older than the version that last wrote

text

openclaw.json

OpenClaw stamps config writes with

text

meta.lastTouchedVersion

. Read-only commands can still inspect a config written by a newer OpenClaw, but process and service mutations refuse to continue from an older binary. Blocked actions include gateway service start, stop, restart, uninstall, forced service reinstall, service-mode gateway startup, and

text

gateway --force

port cleanup.


bash
which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

Fix PATH

Fix `PATH` so `openclaw` resolves to the newer install, then rerun the action.

Reinstall the gateway service

Reinstall the intended gateway service from the newer install:


text
```bash}
openclaw gateway install --force
openclaw gateway restart
```

Remove stale wrappers

Remove stale system package or old wrapper entries that still point at an old `openclaw` binary.

warning

For intentional downgrade or emergency recovery only, set `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` for the single command. Leave it unset for normal operation.

Anthropic 429 extra usage required for long context

Use this when logs/errors include:

text

HTTP 429: rate_limit_error: Extra usage is required for long context requests


bash
openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

Look for:

Selected Anthropic Opus/Sonnet model has
text
params.context1m: true
.
Current Anthropic credential is not eligible for long-context usage.
Requests fail only on long sessions/model runs that need the 1M beta path.

Fix options:

Disable context1m

Disable `context1m` for that model to fall back to the normal context window.

Use an eligible credential

Use an Anthropic credential that is eligible for long-context requests, or switch to an Anthropic API key.

Configure fallback models

Configure fallback models so runs continue when Anthropic long-context requests are rejected.

Local OpenAI-compatible backend passes direct probes but agent runs fail

Use this when:

text
curl ... /v1/models
works
tiny direct
text
/v1/chat/completions
calls work
OpenClaw model runs fail only on normal agent turns


bash
curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

Look for:

direct tiny calls succeed, but OpenClaw runs fail only on larger prompts
text
model_not_found
or 404 errors even though direct
text
/v1/chat/completions
works with the same bare model id
backend errors about
text
messages[].content
expecting a string
intermittent
text
incomplete turn detected ... stopReason=stop payloads=0
warnings with an OpenAI-compatible local backend
backend crashes that appear only with larger prompt-token counts or full agent runtime prompts

No replies

If channels are up but nothing answers, check routing and policy before reconnecting anything.


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

Look for:

Pairing pending for DM senders.
Group mention gating (
text
requireMention
,
text
mentionPatterns
).
Channel/group allowlist mismatches.

Common signatures:

text
drop guild message (mention required
→ group message ignored until mention.
text
pairing request
→ sender needs approval.
text
blocked
/
text
allowlist
→ sender/channel was filtered by policy.

Dashboard control UI connectivity

When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.


bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Look for:

Correct probe URL and dashboard URL.
Auth mode/token mismatch between client and gateway.
HTTP usage where device identity is required.

Auth detail codes quick map

Use

text

error.details.code

from the failed

text

connect

response to pick the next action:

Detail code	Meaning	Recommended action
text `AUTH_TOKEN_MISSING`	Client did not send a required shared token.	Paste/set token in the client and retry. For dashboard paths: text `openclaw config get gateway.auth.token` then paste into Control UI settings.
text `AUTH_TOKEN_MISMATCH`	Shared token did not match gateway auth token.	If text `canRetryWithDeviceToken=true` , allow one trusted retry. Cached-token retries reuse stored approved scopes; explicit text `deviceToken` / text `scopes` callers keep requested scopes. If still failing, run the token drift recovery checklist.
text `AUTH_DEVICE_TOKEN_MISMATCH`	Cached per-device token is stale or revoked.	Rotate/re-approve device token using devices CLI, then reconnect.
text `PAIRING_REQUIRED`	Device identity needs approval. Check text `error.details.reason` for text `not-paired` , text `scope-upgrade` , text `role-upgrade` , or text `metadata-upgrade` , and use text `requestId` / text `remediationHint` when present.	Approve pending request: text `openclaw devices list` then text `openclaw devices approve <requestId>` . Scope/role upgrades use the same flow after you review the requested access.

note

Direct loopback backend RPCs authenticated with the shared gateway token/password should not depend on the CLI's paired-device scope baseline. If subagents or other internal calls still fail with `scope-upgrade`, verify the caller is using `client.id: "gateway-client"` and `client.mode: "backend"` and is not forcing an explicit `deviceIdentity` or device token.

Device auth v2 migration check:


bash
openclaw --version
openclaw doctor
openclaw gateway status

If logs show nonce/signature errors, update the connecting client and verify it:

Wait for connect.challenge

Client waits for the gateway-issued `connect.challenge`.

Sign the payload

Client signs the challenge-bound payload.

Send the device nonce

Client sends `connect.params.device.nonce` with the same challenge nonce.

text

openclaw devices rotate

text

revoke

text

remove

is denied unexpectedly:

paired-device token sessions can manage only their own device unless the caller also has
text
operator.admin
text
openclaw devices rotate --scope ...
can only request operator scopes that the caller session already holds

Gateway service not running

Use this when service is installed but process does not stay up.


bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

Look for:

text
Runtime: stopped
with exit hints.
Service config mismatch (
text
Config (cli)
vs
text
Config (service)
).
Port/listener conflicts.
Extra launchd/systemd/schtasks installs when
text
--deep
is used.
text
Other gateway-like services detected (best effort)
cleanup hints.

Gateway restored last-known-good config

Use this when the Gateway starts, but logs say it restored

text

openclaw.json


bash
openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

Look for:

text
Config auto-restored from last-known-good
text
gateway: invalid config was restored from last-known-good backup
text
config reload restored last-known-good config after invalid-config
A timestamped
text
openclaw.json.clobbered.*
file beside the active config
A main-agent system event that starts with
text
Config recovery warning

Gateway probe warnings

Use this when

text

openclaw gateway probe

reaches something, but still prints a warning block.


bash
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

Look for:

text
warnings[].code
and
text
primaryTargetId
in JSON output.
Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.

Common signatures:

text
SSH tunnel failed to start; falling back to direct probes.
→ SSH setup failed, but the command still tried direct configured/loopback targets.
text
multiple reachable gateways detected
→ more than one target answered. Usually this means an intentional multi-gateway setup or stale/duplicate listeners.
text
Read-probe diagnostics are limited by gateway scopes (missing operator.read)
→ connect worked, but detail RPC is scope-limited; pair device identity or use credentials with
text
operator.read
.
text
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed
→ connect worked, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare
text
connect.ok
and
text
connect.rpcOk
in
text
--json
output.
text
Capability: pairing-pending
or
text
gateway closed (1008): pairing required
→ the gateway answered, but this client still needs pairing/approval before normal operator access.
unresolved
text
gateway.auth.*
/
text
gateway.remote.*
SecretRef warning text → auth material was unavailable in this command path for the failed target.

Channel connected, messages not flowing

If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.


bash
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Look for:

DM policy (
text
pairing
,
text
allowlist
,
text
open
,
text
disabled
).
Group allowlist and mention requirements.
Missing channel API permissions/scopes.

Common signatures:

text
mention required
→ message ignored by group mention policy.
text
pairing
/ pending approval traces → sender is not approved.
text
missing_scope
,
text
not_in_channel
,
text
Forbidden
,
text
401/403
→ channel auth/permissions issue.

Cron and heartbeat delivery

If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.


bash
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Look for:

Cron enabled and next wake present.
Job run history status (
text
ok
,
text
skipped
,
text
error
).
Heartbeat skip reasons (
text
quiet-hours
,
text
requests-in-flight
,
text
cron-in-progress
,
text
lanes-busy
,
text
alerts-disabled
,
text
empty-heartbeat-file
,
text
no-tasks-due
).

Node paired, tool fails

If a node is paired but tools fail, isolate foreground, permission, and approval state.


bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Look for:

Node online with expected capabilities.
OS permission grants for camera/mic/location/screen.
Exec approvals and allowlist state.

Common signatures:

text
NODE_BACKGROUND_UNAVAILABLE
→ node app must be in foreground.
text
*_PERMISSION_REQUIRED
/
text
LOCATION_PERMISSION_REQUIRED
→ missing OS permission.
text
SYSTEM_RUN_DENIED: approval required
→ exec approval pending.
text
SYSTEM_RUN_DENIED: allowlist miss
→ command blocked by allowlist.

Browser tool fails

Use this when browser tool actions fail even though the gateway itself is healthy.


bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Look for:

Whether
text
plugins.allow
is set and includes
text
browser
.
Valid browser executable path.
CDP profile reachability.
Local Chrome availability for
text
existing-session
/
text
user
profiles.

If you upgraded and something suddenly broke

Most post-upgrade breakage is config drift or stricter defaults now being enforced.

If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:


bash
openclaw gateway install --force
openclaw gateway restart

OpenClaw Docs

Troubleshooting

Command ladder

Split brain installs and newer config guard

Fix PATH

Reinstall the gateway service

Remove stale wrappers

warning

Anthropic 429 extra usage required for long context

Disable context1m

Use an eligible credential

Configure fallback models

Local OpenAI-compatible backend passes direct probes but agent runs fail

No replies

Dashboard control UI connectivity

Auth detail codes quick map

note

Wait for connect.challenge

Sign the payload

Send the device nonce

Gateway service not running

Gateway restored last-known-good config

Gateway probe warnings

Channel connected, messages not flowing

Cron and heartbeat delivery

Node paired, tool fails

Browser tool fails

If you upgraded and something suddenly broke

Related