Gateway Troubleshooting Runbook

This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first.

Command ladder

Run in this order:

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

Healthy signals:

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

After an update

Use when an update finishes but the Gateway is down, channels are empty, or model calls fail with 401s.

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

Look for:

Update restart in openclaw status / openclaw status --all. Pending or failed handoffs include the next command to run.
plugin load failed: dependency tree corrupted; run openclaw doctor --fix under Channels: the channel config still exists, but plugin registration failed before the channel could load.
Provider 401s after re-auth: openclaw doctor --fix checks for stale per-agent OAuth auth shadows and removes old copies so all agents resolve the current shared profile.

Split brain installs and newer config guard

Use when a gateway service unexpectedly stops after an update, or logs show one openclaw binary is older than the version that last wrote openclaw.json.

OpenClaw stamps config writes with meta.lastTouchedVersion. Read-only commands can inspect a config written by a newer OpenClaw, but process and service mutations refuse to run from an older binary. Blocked actions: gateway service start/stop/restart/uninstall, forced service reinstall, service-mode gateway startup, and gateway --force port cleanup.

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:

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.

Protocol mismatch after rollback

Use when logs keep printing protocol mismatch after a downgrade or rollback. An older Gateway is running, but a newer local client process is still reconnecting with a protocol range the older Gateway cannot speak.

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

Look for:

protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway logs.
Established clients: in openclaw gateway status --deep or Gateway clients in openclaw doctor --deep: active TCP clients connected to the Gateway port, with PIDs and command lines when the OS allows it.
A client process whose command line points at the newer OpenClaw install or wrapper you rolled back from.

Fix:

Stop or restart the stale OpenClaw client process shown by gateway status --deep.
Restart apps or wrappers that embed OpenClaw: local dashboards, editors, app-server helpers, or long-running openclaw logs --follow shells.
Re-run openclaw gateway status --deep or openclaw doctor --deep and confirm the stale client PID is gone.

Do not make an older Gateway accept a newer incompatible protocol. Protocol bumps protect the wire contract; rollback recovery is a process/version cleanup problem.

Skill symlink skipped as path escape

Use when logs include:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

Every skill root is a containment boundary. A symlink under ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, or ~/.openclaw/skills is skipped when its real target resolves outside that root, unless the target is explicitly trusted.

Inspect the link:

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

If the target is intentional, configure both the direct skill root and the allowed symlink target:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Then start a new session or wait for the skills watcher to refresh. Restart the gateway if the running process predates the config change.

Do not use broad targets such as ~, /, or a whole synced project folder. Keep allowSymlinkTargets scoped to the real skill root that contains trusted SKILL.md directories.

If Skill Workshop apply should also write through those trusted symlinked workspace skill paths, enable skills.workshop.allowSymlinkTargetWrites. Keep it disabled for read-only shared skill roots.

Anthropic 429 extra usage required for long context

Use this when the logs or errors mention HTTP 429: rate_limit_error: Extra usage is required for long context requests.

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

Check for these signs:

The selected Anthropic model is a GA-capable 1M Claude 4.x model (Opus 4.6/4.7/4.8, Sonnet 4.6), or the model config still includes the legacy params.context1m: true.
The current Anthropic credential does not qualify for long-context usage.
Failures happen only on long sessions or model runs that require the 1M context path.

Remedies:

Use a standard context window

Move to a model with a standard window, or strip the legacy context1m from older model config that lacks GA capability for 1M context.

Use an eligible credential

Pick an Anthropic credential that qualifies for long-context requests, or fall back to an Anthropic API key.

Configure fallback models

Set up fallback models so runs proceed when Anthropic rejects long-context requests.

See also:

Upstream 403 blocked responses

Use this when an upstream LLM provider answers with a generic 403 like Your request was blocked.

Do not assume an OpenClaw configuration problem every time. The reply may originate from an upstream security layer, for instance a CDN, WAF, bot-management rule, or reverse proxy sitting in front of an OpenAI-compatible endpoint.

openclaw status
openclaw gateway status
openclaw logs --follow

Check for:

Multiple models under the same provider failing identically.
HTML or generic security text where a normal provider API error should appear.
Provider-side security events at the same time as the requests.
A minimal direct curl probe succeeding while normal SDK-shaped requests fail.

When evidence points to a WAF/CDN block, address the provider-side filtering first. Prefer a narrowly scoped allow or skip rule for the API path OpenClaw uses, and avoid turning off protection for the entire site.

Warning

A successful minimal curl does not prove that real SDK-style requests will get through the same upstream security layer.

See also:

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

Use this when:

curl ... /v1/models functions correctly.
Small direct /v1/chat/completions calls work.
OpenClaw model runs fail only on ordinary agent turns.

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

Check for:

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

Common signatures

model_not_found with a local MLX/vLLM-style server: confirm baseUrl contains /v1, api is "openai-completions" for /v1/chat/completions backends, and models.providers.<provider>.models[].id is the bare provider-local id. Select it once with the provider prefix, for example mlx/mlx-community/Qwen3-30B-A3B-6bit; keep the catalog entry as mlx-community/Qwen3-30B-A3B-6bit.
messages[...].content: invalid type: sequence, expected a string: backend rejects structured Chat Completions content parts. Remedy: set models.providers.<provider>.models[].compat.requiresStringContent: true.
validation.keys or allowed message keys like ["role","content"]: backend rejects OpenAI-style replay metadata on Chat Completions messages. Remedy: set models.providers.<provider>.models[].compat.strictMessageKeys: true.
incomplete turn detected ... stopReason=stop payloads=0: the backend finished the Chat Completions request but returned no user-visible assistant text for that turn. OpenClaw retries replay-safe empty OpenAI-compatible turns once; persistent failures usually mean the backend is emitting empty/non-text content or suppressing final-answer text.
Direct tiny requests succeed, but OpenClaw agent runs fail with backend/model crashes (for example Gemma on some inferrs builds): OpenClaw transport is likely already correct; the backend is failing on the larger agent-runtime prompt shape.
Failures shrink after disabling tools but do not disappear: tool schemas were part of the pressure, but the remaining issue is still upstream model/server capacity or a backend bug.

Fix options

Set compat.requiresStringContent: true for string-only Chat Completions backends.
Set compat.strictMessageKeys: true for strict Chat Completions backends that only accept role and content on each message.
Set compat.supportsTools: false for models/backends that cannot handle OpenClaw's tool schema surface reliably.
Lower prompt pressure where possible: smaller workspace bootstrap, shorter session history, lighter local model, or a backend with stronger long-context support.
If tiny direct requests keep passing while OpenClaw agent turns still crash inside the backend, treat it as an upstream server/model limitation and file a repro there with the accepted payload shape.

See also:

No replies

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

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

Check for:

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

Common signatures:

drop guild message (mention required → group message is ignored until the user is mentioned.
pairing request → the sender must be approved first.
blocked / allowlist → policy filtered out either the sender or the channel.

Related material:

Dashboard control UI connectivity

If the dashboard or control UI refuses to connect, double-check the URL, the authentication mode, and whether the secure context assumptions still hold.

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

Check for these issues:

The probe URL and dashboard URL are correct.
The auth mode or token does not match between the client and the gateway.
HTTP is being used in a situation where device identity is mandatory.

When a local browser cannot reach 127.0.0.1:18789 following an update, start by restoring the local Gateway service and verifying that it is actually delivering the dashboard:

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

If curl responds with OpenClaw HTML, the Gateway is operational, and the problem most likely stems from browser caching, an outdated deep link, or a stale tab. Open http://127.0.0.1:18789 directly and navigate from the dashboard. Should the service stop after a restart, execute openclaw gateway start and then verify openclaw gateway status again.

Connect / auth signatures

device identity required → either the context is non-secure or device authentication is absent.
origin not allowed → the browser Origin is missing from gateway.controlUi.allowedOrigins (or the connection originates from a non-loopback browser origin without an explicit allowlist).
device nonce required / device nonce mismatch → the client never finishes the challenge-based device authentication flow (connect.challenge + device.nonce).
device signature invalid / device signature expired → the client signed the wrong payload, or the timestamp was stale, for the current handshake.
AUTH_TOKEN_MISMATCH combined with canRetryWithDeviceToken=true → the client may perform one trusted retry using a cached device token.
That cached-token retry reuses the cached scope set stored alongside the paired device token. Explicit deviceToken / explicit scopes callers instead keep the scope set they requested.
AUTH_SCOPE_MISMATCH → the device token was recognized, but its approved scopes do not cover this connect request; re-pair or approve the requested scope contract rather than rotating a shared gateway token.
Outside that retry path, connect auth precedence runs: explicit shared token or password first, then explicit deviceToken, then the stored device token, then the bootstrap token.
On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure. Two bad concurrent retries from the same client can therefore surface retry later on the second attempt instead of two plain mismatches.
too many failed authentication attempts (retry later) from a browser-origin loopback client → repeated failures from that same normalized Origin trigger a temporary lockout; another localhost origin uses a separate bucket.
Repeated unauthorized after that retry → shared token or device token drift; refresh the token config and re-approve or rotate the device token if needed.
gateway connect failed: → the host, port, or URL target is wrong.

Auth detail codes quick map

Use error.details.code from the failed connect response to decide what to do next:

Detail code	What it indicates	What you should do
`AUTH_TOKEN_MISSING`	The client omitted a shared token that was required.	On the Gateway host, launch `openclaw gateway auth-token --show` in an interactive terminal, copy the result into the client, and attempt the request again.
`AUTH_TOKEN_MISMATCH`	The shared token did not match the gateway's auth token.	When `canRetryWithDeviceToken=true` is true, permit a single trusted retry. Retries using cached tokens reuse previously approved scopes; callers that explicitly use `deviceToken` / `scopes` preserve their requested scopes. If the problem persists, follow the token drift recovery checklist.
`AUTH_DEVICE_TOKEN_MISMATCH`	The cached per-device token is outdated or has been revoked.	Use the devices CLI to rotate or re-approve the device token, then establish a new connection.
`AUTH_SCOPE_MISMATCH`	The device token is valid, but its approved role or scopes do not cover this connect request.	Re-pair the device or approve the requested scope contract; do not mistake this for shared-token drift.
`PAIRING_REQUIRED`	Device identity requires approval. Inspect `error.details.reason` for `not-paired`, `scope-upgrade`, `role-upgrade`, or `metadata-upgrade`, and apply `requestId` / `remediationHint` when they are available.	Approve the pending request: run `openclaw devices list` then `openclaw devices approve <requestId>`. Scope or role upgrades follow the same procedure after you review the access being requested.

Note

Direct loopback backend RPCs that authenticate with the shared gateway token or password should not rely on the CLI's paired-device scope baseline. If subagents or other internal calls still encounter scope-upgrade, confirm the caller uses client.id: "gateway-client" and client.mode: "backend" and does not force an explicit deviceIdentity or device token.

Device auth v2 migration check:

openclaw --version
openclaw doctor
openclaw gateway status

If the logs report nonce or signature errors, upgrade the connecting client and confirm it:

Wait for connect.challenge

The client waits for the gateway-issued connect.challenge.

Sign the payload

The client signs the payload bound to the challenge.

Send the device nonce

The client sends connect.params.device.nonce using the same challenge nonce.

If openclaw devices rotate / revoke / remove is denied without an obvious cause:

Sessions using paired-device tokens can only manage their own device, unless the caller also holds operator.admin.
openclaw devices rotate --scope ... can request only operator scopes that the caller session already possesses.

Gateway service not running

Use this when the service is installed but the process will not stay running.

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

Check for:

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

Common signatures

Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → local gateway mode is disabled, or the config file was overwritten and gateway.mode is missing. Fix: specify gateway.mode="local" in your config, or execute openclaw onboard --mode local / openclaw setup again to reapply the expected local-mode configuration. When OpenClaw runs under Podman, the default config path is ~/.openclaw/openclaw.json.
refusing to bind gateway ... without auth → binding to a non-loopback address without a valid gateway auth path (token/password, or trusted-proxy where configured).
another gateway instance is already listening / EADDRINUSE → another process is already using the port.
Other gateway-like services detected (best effort) → leftover or concurrent launchd/systemd/schtasks units exist. Most deployments should run a single gateway per machine; if multiple are necessary, separate ports and config/state/workspace. Refer to /gateway#multiple-gateways-same-host.
System-level OpenClaw gateway service detected from doctor → a systemd system unit is present while the user-level service is absent. Remove or disable the duplicate before letting doctor install a user service, or set OPENCLAW_SERVICE_REPAIR_POLICY=external if the system unit should be the supervisor.
Gateway service port does not match current gateway config → the installed supervisor still references the old --port. Run openclaw doctor --fix or openclaw gateway install --force, then restart the gateway service.

macOS gateway silently stops responding, then resumes when you touch the dashboard

Apply this when channels (Telegram, WhatsApp, etc.) on a macOS host stay silent for minutes to hours, and the gateway recovers as soon as you open the Control UI, SSH in, or otherwise touch the host. Typically, openclaw status shows nothing unusual because the gateway is already back by the time you check.

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Look for:

One or more *-uncaught_exception.json bundles in ~/.openclaw/logs/stability/ where error.code is a transient network code like ENETDOWN, ENETUNREACH, EHOSTUNREACH, or ECONNREFUSED.
pmset -g log entries such as Entering Sleep state due to 'Maintenance Sleep' or en0 driver is slow (msg: WillChangeState to 0) matching the crash timestamps. Power Nap / Maintenance Sleep briefly drops the Wi-Fi driver to state 0; any outbound connect() hitting that window can fail with ENETDOWN even if the host otherwise has full network connectivity.
launchctl print output showing state = not running with several recent runs and an exit code, especially when the gap between crash and next launch is around an hour rather than seconds. macOS launchd applies an undocumented respawn-protection gate after a crash burst, which can stop honoring KeepAlive=true until an external trigger like interactive login, dashboard connection, or launchctl kickstart re-arms it.

Common signatures:

A stability bundle with error.code set to ENETDOWN or a sibling code, and the call stack pointing into Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 and later treat these as benign transient network errors, so they no longer reach the top-level uncaught handler; on older releases, upgrade first.
Long quiet stretches ending the moment you connect to the Control UI or SSH in: the user-visible activity re-arms launchd's respawn gate, not anything the dashboard does to the gateway.
runs count climbing through the day with no matching received SIG*; shutting down line in ~/Library/Logs/openclaw/gateway.log: clean shutdowns log a signal; transient crashes do not.

What to do:

Upgrade the gateway if you are on a release before 2026.5.26. After upgrading, future ENETDOWN errors become warnings instead of killing the process.
Cut maintenance sleep activity on Mac mini / desktop hosts meant to run as always-on servers:
```
sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
```
This lowers, but does not fully remove, the underlying driver flap. The system can still do some maintenance sleeps for TCP keepalive and mDNS upkeep regardless of these flags.

Add a liveness watchdog so a future crash burst parked by launchd gets caught quickly:

# Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgent
state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
if [ "$state" != "running" ]; then
  launchctl kickstart -k gui/$UID/ai.openclaw.gateway
fi

The goal is to externally re-arm the respawn gate; KeepAlive=true alone is not enough on macOS after a crash burst.

macOS launchd supervisor loop with duplicate gateway/node LaunchAgents

Use this when a macOS install keeps restarting every few seconds, openclaw health checks flip between healthy and unavailable, and channel dispatch stalls even though the service appears to be running.

This issue appeared on older installations where both the ai.openclaw.gateway and ai.openclaw.node LaunchAgents were running, with each one injecting OPENCLAW_LAUNCHD_LABEL. Under those conditions, OpenClaw can recognize launchd supervision, attempt to return restart control to launchd, and end up in a rapid EADDRINUSE/respawn cycle rather than maintaining a single stable gateway process.

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

Check for:

Multiple gateway PIDs appearing over the 30-second window instead of one consistent process.
Entries like EADDRINUSE, another gateway instance is already listening, or recurring restart/handoff messages in gateway.log.
Both ~/Library/LaunchAgents/ai.openclaw.gateway.plist and ~/Library/LaunchAgents/ai.openclaw.node.plist loaded simultaneously on a host meant to run only one managed gateway service.

Resolution steps:

When this host is dedicated to the Gateway service alone, remove the managed node service through OpenClaw. Skip this step if you depend on the node service for remote node capabilities; removing it disables those features on this machine:
```
openclaw node uninstall
```
Set up a persistent Gateway wrapper that clears the inherited launchd markers prior to launching OpenClaw. Use the supported --wrapper option, and avoid editing the generated file under ~/.openclaw/service-env/, since service reinstall, update, and doctor repair recreate that file:
```
mkdir -p ~/.local/bin
cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
#!/bin/sh
set -eu
unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
exec openclaw "$@"
EOF
chmod 700 ~/.local/bin/openclaw-launchd-workaround

openclaw gateway install \
  --wrapper ~/.local/bin/openclaw-launchd-workaround \
  --force
```
The wrapper path is preserved by gateway install across forced reinstalls, updates, and doctor repairs.
Confirm the Gateway is stable and handling RPC traffic, not just accepting connections:
```
openclaw gateway status --deep --require-rpc

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done
```
The PID sample should reveal one steady process rather than a changing set of PIDs, and inbound channel dispatch should start working again.
Once you upgrade to a release where the dual-LaunchAgent loop is corrected, remove this workaround and reinstall the standard managed service:
```
OPENCLAW_WRAPPER= openclaw gateway install --force
rm ~/.local/bin/openclaw-launchd-workaround
```

Gateway exits during high memory use

Apply this when the Gateway vanishes under heavy load, the supervisor reports an OOM-style restart, or logs mention critical memory pressure bundle written.

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

Check for:

Reason: diagnostic.memory.pressure.critical inside the most recent stability bundle.
Memory pressure: accompanied by critical/rss_threshold, critical/heap_threshold, or critical/rss_growth.
V8 heap: readings approaching the heap limit.
Largest session files: records such as agents/<agent>/sessions/<session>.jsonl or sessions/<session>.jsonl.
Linux cgroup memory counters when the gateway runs within a container or a memory-constrained service.

Typical indicators:

critical memory pressure bundle written shows up right before a restart → OpenClaw saved a pre-OOM stability bundle. Examine it with openclaw gateway stability --bundle latest.
memory pressure: level=critical appears in gateway logs → OpenClaw sensed critical memory pressure and stored the available in-process memory details.
Largest session files: references a very large redacted transcript path → trim retained session history, check session growth, or relocate old transcripts out of the active store before restarting.
V8 heap: used bytes sit near the heap limit → first reduce prompt/session pressure or cut concurrent work. For a managed service, look at Gateway heap: in openclaw gateway status; if it reads not set, regenerate old service metadata with openclaw gateway install --force. Ambient shell NODE_OPTIONS is deliberately ignored. Apply an explicit supervisor-level heap override only after verifying the sustained workload and preserving sufficient native-memory headroom.
Memory pressure: critical/rss_growth → memory expanded quickly within one sampling interval. Review the latest logs for a large import, runaway tool output, repeated retries, or a backlog of queued agent tasks.
Critical memory pressure logged but no bundle present → run openclaw gateway diagnostics export after the event to gather the available operational evidence.

The stability bundle carries no payload. It contains operational memory evidence and redacted relative file paths, not message text, webhook bodies, credentials, tokens, cookies, or raw session ids. Attach the diagnostics export to bug reports rather than pasting raw logs.

Gateway rejected invalid config

Apply this when Gateway startup fails with Invalid config or hot reload logs indicate it skipped an invalid edit.

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

Check for:

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
A timestamped openclaw.json.rejected.* file next to the active config.
A timestamped openclaw.json.clobbered.* file if doctor --fix fixed a broken direct edit.
OpenClaw keeps the latest 32 .clobbered.* files for each config path and discards older ones.

What happened

Validation of the config can fail at startup, during hot reload, or when OpenClaw itself writes the file.
When the Gateway boots, it fails closed rather than altering openclaw.json.
Hot reload ignores invalid external modifications and leaves the current runtime config untouched.
OpenClaw-owned writes block invalid or destructive payloads prior to committing, then store .rejected.*.
Repair duties fall to openclaw doctor --fix. It can strip non-JSON prefixes or bring back the last-known-good copy, all while keeping the rejected payload safe as .clobbered.*.
If a single config path triggers repeated repairs, OpenClaw cycles out older .clobbered.* files so the most recent repaired payload remains accessible.

Inspect and repair

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

Common signatures

.clobbered.* being present means doctor fixed a broken external edit while keeping the active config repaired.
.rejected.* appearing indicates an OpenClaw-owned config write failed schema or clobber checks before commit.
Config write rejected: signals the write attempted to drop required shape, shrink the file drastically, or persist invalid config.
config reload skipped (invalid config): points to a direct edit that failed validation and was skipped by the running Gateway.
Invalid config at ... means startup failed before Gateway services came up.
missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, or size-drop-vs-last-good:* show an OpenClaw-owned write was rejected for losing fields or size relative to the last-known-good backup.
Config last-known-good promotion skipped means the candidate held redacted secret placeholders like ***.

Fix options

Execute openclaw doctor --fix so doctor can repair prefixed or clobbered config, or restore last-known-good.
Pull only the intended keys from .clobbered.* or .rejected.*, then apply them using openclaw config set or config.patch.
Run openclaw config validate prior to restarting.
For manual edits, retain the full JSON5 config rather than just the partial object you intended to change.

Gateway probe warnings

Employ this when openclaw gateway probe reaches something yet still emits a warning block.

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

Check for:

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

Typical signatures:

SSH tunnel failed to start; falling back to direct probes. indicates SSH setup failed, yet the command still attempted direct configured or loopback targets.
multiple reachable gateway identities detected means distinct gateways responded, or OpenClaw could not confirm reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL pointing to the same gateway counts as one gateway with multiple transports, even when transport ports differ.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) shows connect succeeded, but detail RPC is scope-limited; pair the device identity or use credentials with operator.read.
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed shows connect succeeded, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare connect.ok and connect.rpcOk in --json output.
Capability: pairing-pending or gateway closed (1008): pairing required means the gateway answered, but this client still requires pairing or approval before normal operator access.
Unresolved gateway.auth.* / gateway.remote.* SecretRef warning text means auth material was unavailable in this command path for the failed target.

Channel connected, messages not flowing

If channel state shows connected but message flow is stalled, direct attention to policy, permissions, and channel-specific delivery rules.

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 (pairing, allowlist, open, disabled).
Group allowlist and mention requirements.
Missing channel API permissions or scopes.

Typical signatures:

mention required → group mention policy caused the message to be dropped.
pairing / pending approval traces → the sender has not been approved.
missing_scope, not_in_channel, Forbidden, 401/403 → a channel auth or permissions problem exists.

Cron and heartbeat delivery

When cron or heartbeat fails to run or deliver, check the scheduler state before inspecting the delivery target.

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

Check for:

Cron is enabled and the next wake time is set.
Job run history status (ok, skipped, error).
Heartbeat skip reasons (quiet-hours, requests-in-flight, cron-in-progress, alerts-disabled, empty-heartbeat-file).

Common signatures

cron: scheduler disabled; jobs will not run automatically → cron is turned off.
cron: timer tick failed → scheduler tick encountered an error; inspect file, log, or runtime issues.
heartbeat skipped with reason=quiet-hours → the current time falls outside the active hours window.
heartbeat skipped with reason=empty-heartbeat-file → the heartbeat monitor scratch contains only blank lines, comments, headers, fences, or empty checklist scaffolding, so OpenClaw omits the model call.
heartbeat skipped with reason=no-route → the default owner target lacks a concrete owner in commands.ownerAllowFrom or channel allowFrom, the owner cannot be resolved to a DM, or no channel is set. An explicit last also requires a session conversation route.
heartbeat: unknown accountId → the account id for the heartbeat delivery target is invalid.
heartbeat skipped with reason=dm-blocked → the heartbeat target resolved to a DM-style destination while agents.defaults.heartbeat.directPolicy (or the per-agent override) is configured as block.

Node paired, tool fails

If a node is paired but tools are failing, separate foreground, permission, and approval states for diagnosis.

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

Check for:

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

Common signatures:

NODE_BACKGROUND_UNAVAILABLE → the node app must be in the foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → an OS permission is missing.
SYSTEM_RUN_DENIED: approval required → exec approval is still pending.
SYSTEM_RUN_DENIED: allowlist miss → the allowlist is blocking the command.

Browser tool fails

Use this when browser tool actions fail while the gateway itself remains healthy.

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

Check for:

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

Plugin / executable signatures

unknown command "browser" or unknown command 'browser' → the built-in browser plugin gets blocked by plugins.allow.
Browser tool missing or unavailable while browser.enabled=true → plugins.allow blocks browser, so the plugin never loads.
Failed to start Chrome CDP on port → the browser process could not start.
browser.executablePath not found → the configured path is not valid.
browser.cdpUrl must be http(s) or ws(s) → the CDP URL you set uses an unsupported protocol, like file: or ftp:.
browser.cdpUrl has invalid port → the CDP URL's port is malformed or outside the valid range.
Playwright is not available in this gateway build; '<feature>' is unsupported. → the gateway installation is missing the core browser runtime dependency; reinstall or update OpenClaw and restart the gateway. ARIA snapshots and basic page screenshots remain functional, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.

Chrome MCP / existing-session signatures

Could not find DevToolsActivePort for chrome → Chrome MCP existing-session could not attach to the chosen browser data directory yet. Open the browser inspect page, enable remote debugging, keep the browser open, approve the first attach prompt, then retry. If signed-in state is not needed, use the managed openclaw profile instead.
No browser tabs found for profile="user" → the Chrome MCP attach profile has no open local Chrome tabs.
Remote CDP for profile "<name>" is not reachable → the gateway host cannot reach the configured remote CDP endpoint.
Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no reachable target, or the HTTP endpoint responded but the CDP WebSocket still failed to open.

Element / screenshot / upload signatures

fullPage is not supported for element screenshots → the screenshot request combined --full-page with --ref or --element.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session screenshot calls must use page capture or a snapshot --ref, not CSS --element.
existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP upload hooks require snapshot refs, not CSS selectors.
existing-session file uploads currently support one file at a time. → on Chrome MCP profiles, send only one upload per call.
existing-session dialog handling does not support timeoutMs. → dialog hooks on Chrome MCP profiles do not accept timeout overrides.
existing-session type does not support timeoutMs overrides. → leave out timeoutMs for act:type on profile="user" / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
response body is not supported for existing-session profiles yet. → responsebody still needs a managed browser or raw CDP profile.
Stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run openclaw browser stop --browser-profile <name> to close the active control session and release Playwright/CDP emulation state without restarting the entire gateway.

If you upgraded and something suddenly broke

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

1. Auth and URL override behavior changed

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

What to check:

If gateway.mode=remote, CLI calls may be hitting remote while your local service is fine.
Explicit --url calls do not fall back to stored credentials.

Common signatures:

gateway connect failed: → wrong URL target.
unauthorized → endpoint reachable but wrong auth.

2. Bind and auth guardrails are stricter

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

What to check:

Non-loopback binds (lan, tailnet, custom) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback trusted-proxy deployment.
Old keys like gateway.token do not replace gateway.auth.token.

Common signatures:

refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path.
Connectivity probe: failed while runtime is running → gateway alive but inaccessible with current auth/url.

3. Pairing and device identity state changed

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Things to inspect:

Device approvals that are still pending for dashboards or nodes.
DM pairing requests awaiting approval following policy or identity changes.

Typical indicators:

device identity required points to unsatisfied device authentication.
pairing required signals that the sender or device has not yet been approved.

When configuration and runtime continue to disagree even after these checks, reinstall the service metadata using the same profile or state directory:

openclaw gateway install --force
openclaw gateway restart

See also: