OpenClaw Gateway Guide
Understand the OpenClaw Gateway, verify its service and connectivity, and diagnose a local endpoint before debugging channels.
The Gateway is the long-running control plane that connects an OpenClaw agent to channels, the Control UI, and other local operations. When several features fail together, verify the Gateway before debugging each channel.
Check service and connectivity
openclaw status
openclaw gateway status
openclaw gateway probegateway status checks the managed service and endpoint. gateway probe asks whether the endpoint is reachable and reports the capability level proven by the probe.
Expected result
Runtime: runningConnectivity probe: okReachable: yes
A limited read capability can mean diagnostics lack a scope; it is not necessarily a connection failure.
Identify the failing layer
| Observation | Likely layer | Next check |
|---|---|---|
| Service is stopped | Managed runtime | Gateway service status and first startup error |
| Service runs but probe fails | Bind, port, authentication, or endpoint | Local URL, port owner, and auth configuration |
| Probe succeeds but every channel fails | Shared model or routing | Model status and Gateway logs |
| One channel fails | Channel credential or policy | channels status --probe and channel guide |
| Control UI page loads but disconnects | WebSocket auth or device pairing | Control UI authentication and devices |
Read logs before restarting
openclaw logs --followLook for the first stable error rather than every follow-on warning. Useful signatures include a missing local mode, an unauthenticated non-loopback bind, or EADDRINUSE when another process owns the port.
Gateway access boundary
Loopback is the safest default for a personal Gateway. A non-loopback bind needs an intentional authentication path. Do not solve a remote access problem by exposing an unauthenticated endpoint.
When channels fail
Once the Gateway is healthy, probe channels separately:
openclaw channels status --probeThis separates a Gateway-wide outage from a token, pairing, allowlist, or provider-specific channel issue.
Recover without losing evidence
Capture the first stable error and current status before restarting. A restart can clear the immediate symptom while hiding a port conflict, invalid configuration, or repeated crash. After repair, repeat the same status, probe, model, and channel checks so recovery is measured rather than assumed.
Source notes
Technical facts on this page were checked against primary sources.