OpenClaw gateway troubleshooting

When the fast triage page is not enough, the docs send you to the deep gateway runbook. It is an index rather than a wall of fixes: a command ladder, the signals a healthy gateway shows, and six symptom-area pages with stable anchors. Its most useful section is the short list of things that break right after an upgrade. Here is the map.

The ladder and the six pages

• Run the status, gateway status, log follow, doctor and channel probe commands in that order; healthy means gateway status shows a running runtime, an ok connectivity probe and a capability line, doctor reports no blocking config or service issue, and the probe shows live per-account transport status with a works or audit ok marker where supported.
• Updates and rollbacks covers a gateway left down or mismatched by an update, downgrade or split-brain install: after an update, the prepared model runtime publication timeout, the newer-config guard, fixing the search path, reinstalling the service, removing stale wrappers and a protocol mismatch after rollback. Skills and model providers covers a skipped skill root, the rate-limit error for long context with its standard-window, eligible-credential and fallback-model fixes, blocked upstream responses, and a local OpenAI-compatible backend that passes probes but fails agent runs.
• Agent replies and the control interface covers a run failing with a storage error, no reply arriving, dashboard connectivity, the connect and auth signatures with a quick map of auth detail codes and the connect challenge, payload signing and device nonce steps. Gateway service and process covers a service that will not run or stay up, a macOS gateway that silently stops until the dashboard is touched, a supervisor loop with duplicate launch agents, and an exit under high memory use.
• Config validation and probes covers a rejected invalid config, what happened, inspect and repair, its common signatures and fix options, and gateway probe warnings. Channel delivery and tools covers a channel connected with messages not flowing, scheduled and heartbeat delivery, a paired node whose tool fails, browser tool failures, plugin and executable signatures, browser session signatures and element, screenshot and upload signatures; every old anchor of the single page still resolves to its new home.

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

If you upgraded and something broke

The index keeps three checks inline. First, auth and URL override behaviour: read the gateway mode, the remote URL and the auth mode, because with the mode set to remote the command line may be targeting a remote gateway while the local service is fine, and explicit URL calls do not fall back to stored credentials; a connect-failed signature means the wrong URL target and an unauthorized signature means the endpoint is reachable with the wrong auth. Second, bind and auth guardrails are stricter: non-loopback binds need a valid auth path, a shared token or password or a correctly configured non-loopback trusted proxy, and the old token key does not replace the current auth token key; refusing to bind without auth and a failed connectivity probe with the runtime running are the signatures. Third, pairing and device identity state: list devices and channel pairings and look for pending device approvals for the dashboard or nodes and pending approvals after a policy or identity change; device identity required and pairing required are the signatures. If service config and runtime still disagree, reinstall the service metadata from the same profile and state directory and restart.

Reading the signals

• A running runtime with a failed connectivity probe is the single most telling combination: the process is alive but the command line cannot reach it with its current URL and auth, so the fix is in the mode, URL or token, not in the service.
• A device identity required signature after an upgrade is not a bug in the client; device auth is now enforced and the dashboard or node needs its pending approval, which the devices and pairing lists show.
• The probe is per account: a channel with two accounts can show one transport working and one failing, which the status line alone does not reveal.

OpenClaw channel troubleshooting is the channel-level companion for the case where the transport connects but behaviour is wrong, and OpenClaw doctor explains the repair command the ladder relies on.

Why an index

Splitting the runbook by symptom area keeps each page short enough to read while something is down, and the preserved anchors mean links from older threads and issues still land on the right section. The order of the ladder is deliberate too: it goes from the widest signal to the narrowest, and doctor sits before the probe because it repairs the misconfigurations the probe would otherwise report as failures. OpenClaw pairing covers the approvals the third check looks for and OpenClaw configuration the keys the first two checks read.

On Diali

On Diali the runtime configuration is generated from the dashboard and replaced at each release, which removes most of the drift the post-upgrade section describes, and the same ladder runs on the hosted runtime. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around it.

• Five commands in order; runtime running plus probe ok is healthy.
• Six symptom pages; every old anchor still resolves.
• After an upgrade: mode and URL, bind and auth, pairing state.