Back to Articles
General5 min read
Why OpenClaw Gateway Fails (Complete Fix Guide)
OpenClaw Gateway down? Fix port conflicts, auth errors, and config issues fast — with exact commands from the official OpenClaw documentation.
OpenClaw Gateway down? Fix port conflicts, auth errors, and config issues fast — with exact commands from the official OpenClaw documentation.
The OpenClaw Gateway is the nerve center of your entire OpenClaw setup. It is the single long-running Node.js process that manages all communication, orchestration, and channel connections — from WhatsApp and Telegram to Discord and iMessage. When it fails, nothing works. No replies, no agent runs, no channel connections.
This guide walks through every verified cause of Gateway failure, the exact command ladders to diagnose them, and the precise fixes — based entirely on the official OpenClaw documentation.
Before diving into fixes, it helps to understand what you are actually debugging. According to the official docs, the Gateway is a single multiplexed process that handles:
/v1/models, /v1/chat/completions, /v1/embeddings)The default bind is loopback-only (127.0.0.1:18789). Auth is required by default. Every failure you will encounter traces back to one of these components.
Run these commands first, in this exact order, before anything else:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probeopenclaw gateway status shows Runtime: running and RPC probe: okopenclaw doctor reports no blocking config or service issuesopenclaw channels status --probe shows live per-account transport statusIf the above checks reveal issues, use the sections below to fix them.
refusing to bind, unauthorized)refusing to bind gateway ... without authRPC probe: failed while runtime is runningunauthorized on connect attemptsopenclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --followIf you changed the bind mode to lan, tailnet, or custom, OpenClaw requires a valid auth path. You cannot expose the Gateway to a non-loopback interface without either:
gateway.auth.token or the OPENCLAW_GATEWAY_TOKEN environment variablegateway.auth.password or OPENCLAW_GATEWAY_PASSWORDtrusted-proxy modeSecurity note: The official docs warn that security researchers found 40,000+ exposed instances with the Gateway bound to 0.0.0.0. Never bind to a public interface without auth.Set a token in your config:
openclaw config set gateway.auth.token YOUR_TOKEN_HEREOr in openclaw.json:
{
gateway: {
auth: {
token: "your-secure-token"
}
}
}Note that old keys like gateway.token do not replace gateway.auth.token. If you migrated from an older config, update the key path.
---
device identity required errororigin not allowed errorAUTH_TOKEN_MISMATCH or AUTH_TOKEN_MISSING in logsopenclaw gateway status
openclaw gateway status --json
openclaw logs --follow
openclaw doctorUse error.details.code from the failed connect response to pick the correct fix:
| Code | Meaning | Fix |
|---|---|---|
| AUTH_TOKEN_MISSING | Client did not send a required shared token | Paste/set token in client. Check with: openclaw config get gateway.auth.token |
| AUTH_TOKEN_MISMATCH | Shared token did not match gateway token | Run the token drift recovery checklist in the devices CLI docs |
| AUTH_DEVICE_TOKEN_MISMATCH | Per-device token is stale or revoked | Run openclaw devices list then openclaw devices approve <requestId> |
| PAIRING_REQUIRED | Device known but not approved for this role | Approve via openclaw devices list + openclaw devices approve <requestId> |
origin not allowedThe browser's Origin is not in gateway.controlUi.allowedOrigins. This happens when you access the Control UI from a non-loopback origin without an explicit allowlist entry. Add your origin to the config:
openclaw config set gateway.controlUi.allowedOrigins '["http://your-host:18789"]'device identity requiredThis error occurs in non-secure contexts (HTTP instead of HTTPS for remote access) or when the device auth flow is incomplete. The client must:
1. Wait for connect.challenge
2. Sign the challenge-bound payload
3. Send connect.params.device.nonce with the same challenge nonce
Update the connecting client if it is not following this flow, then reconnect.
---
openclaw channels status --probe
openclaw pairing list --channel <channel>
openclaw logs --follow
openclaw config get channelsThe group message was ignored because the bot requires a mention. Either mention the bot explicitly, or adjust requireMention in your channel config.
The sender needs approval before the bot will reply. Approve with:
openclaw pairing list --channel <channel>
openclaw devices approve <requestId>The sender or channel was filtered by a policy allowlist. Check:
openclaw config get channelsand verify DM policy is set to pairing, open, or allowlist as intended — not disabled.
The channel API token or bot does not have the required permissions/scopes. Re-authorize the channel with the correct permission set.
---
This is a subtle failure specific to homelab setups using Ollama, LM Studio, or other local OpenAI-compatible backends.
curl http://127.0.0.1:1234/v1/models workscurl 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 --followLog signature:
messages[...].content: invalid type: sequence, expected a stringThe local backend only accepts string content (not structured parts). Fix:
openclaw config set models.providers.<provider>.models[0].compat.requiresStringContent trueIf disabling tools reduces failures but does not eliminate them:
openclaw config set models.providers.<provider>.models[0].compat.supportsTools falseIf tiny requests succeed but agent runs still crash, the backend is hitting capacity limits. Options:
---
HTTP 429: rate_limit_error: Extra usage is required for long context requestsopenclaw logs --follow
openclaw models status
openclaw config get agents.defaults.modelsLook for a model with params.context1m: true that is being used with a credential not eligible for long-context access.
1. Disable context1m to fall back to the standard context window
2. Use an Anthropic API key (instead of Claude.ai credentials) which is eligible for long-context requests
3. Configure fallback models so agent runs continue when long-context requests are rejected
---
Config auto-restored from last-known-good.rejected.* files appear next to openclaw.jsonThe Gateway watches ~/.openclaw/openclaw.json for changes. According to the official configuration docs, it rejects edits that:
gateway.modeRejected edits are saved as .rejected.* files for inspection.
# Validate your config before applying
openclaw config validate
# If rejected, inspect what was wrong
ls ~/.openclaw/*.rejected.*
# Fix the payload, then apply cleanly
openclaw config set <key> <value>Use openclaw config set for single keys or openclaw config patch for partial updates instead of replacing the entire file. openclaw config apply replaces the entire config — use it carefully.
---
| Log / error message | Cause | Fix |
|---|---|---|
| refusing to bind gateway ... without auth | Non-loopback bind without auth | Set gateway.auth.token |
| EADDRINUSE / another gateway instance is already listening | Port conflict | Run gateway status --deep, clean up stale services |
| Gateway start blocked: set gateway.mode=local | Missing or wrong gateway mode | Run openclaw onboard --mode local |
| unauthorized on connect | Token or device token mismatch | See auth detail codes table above |
| origin not allowed | Browser origin not in allowlist | Add origin to gateway.controlUi.allowedOrigins |
| device identity required | Non-secure context or incomplete device auth flow | Use HTTPS for remote access or update client |
| drop guild message (mention required) | Group mention policy | Mention the bot or adjust requireMention |
| pairing request | Sender not approved | openclaw devices approve <requestId> |
| messages[...].content: invalid type: sequence | Local backend needs string content | Set compat.requiresStringContent: true |
| Config auto-restored from last-known-good | Config file was invalid or clobbered | openclaw config validate, fix and re-apply |
---
The OpenClaw Gateway is a single point of control — when it breaks, it breaks everything. But the failure modes are well-defined and the official docs provide exact command ladders for each one.
Start with the five-command diagnostic sequence every time: openclaw status → openclaw gateway status → openclaw logs --follow → openclaw doctor → openclaw channels status --probe. In the majority of cases, openclaw doctor alone will surface the blocking issue and tell you what to fix.
For issues not covered here, refer to the official OpenClaw documentation: