Something broke, your bot went dark, and now you're scrolling through an intimidating stack trace. OpenClaw's error messages are usually specific enough to tell you exactly what's wrong — if you know the patterns. This cheat sheet covers every common OpenClaw error we see in production, what it actually means, and the fastest way to fix it.
Pairing Required Errors
By far the most common OpenClaw error. If you see any of these:
Gateway closed (1008): pairing requiredGatewayClientRequestError: pairing requiredError: pairing requiredopenclaw docker pairing required
It means your gateway client connected successfully but the server refused to hand out an auth session because the client hasn't been paired yet.
The fix: open the OpenClaw gateway control UI in a browser, generate a pairing code, and run the pair command from your CLI. For the full walkthrough including the rare case where the credentials directory is missing, see our dedicated pairing required fix guide.
Gateway Token Missing or Unauthorized
Messages like:
openclaw unauthorized: gateway token missingUnauthorized: open the dashboard to generate a tokenGenerate and configure a gateway token now?
These mean your config file has no gateway.auth.token field, or the token doesn't match what the gateway expects.
The fix: generate a token from the dashboard and write it to gateway.auth as an object, not a string. The correct shape is gateway.auth: { token: "..." }. A surprising number of config examples online show it as a bare string, which silently fails validation. See our gateway token setup guide.
Gateway Connect Failed
Variations include:
Gateway connect failed: GatewayClientRequestErrorGateway connect failed: Error: pairing requiredopenclaw gateway connect failed
This is the umbrella error for "client could not establish a session with the gateway server." The root cause is almost always one of: wrong gateway URL, missing token, missing pairing, or a trusted-proxy misconfiguration.
The fix: check in this order — (1) is the gateway URL reachable from inside the container, (2) is the token set and correct, (3) has the client paired, (4) does trustedProxies use exact IPs rather than CIDR blocks. CIDR blocks like 172.17.0.0/16 break OpenClaw silently; use the exact Docker bridge IP like 172.17.0.1.
Bot Not Responding
Your gateway is fine, the bot started cleanly, but messages go in and nothing comes out. Two things to check first:
- Model provider errors. Check your logs for rate limits, invalid API keys, or "insufficient credits" from OpenRouter or your provider.
- Channel plugin disabled. Both
channels.telegram.enabled: trueandplugins.entries.telegram.enabled: truemust be set. Enabling only one is a common mistake.
See our bot not responding guide for the full checklist.
Stuck on Starting
Container boots, logs show "initializing", and it never gets further. Usually this is one of:
- Missing credentials directory —
~/.openclaw/credentials/must exist even if empty, or pairing-based channels silently hang. - Invalid model ID — OpenRouter model IDs need the provider prefix:
openrouter/anthropic/claude-sonnet-4.6, notanthropic/claude-sonnet-4.6. - Wrong session scope — use
session.scope, notsession.dmScope. The latter is silently ignored and some channels never initialize.
Relay Not Reachable
If you're using the browser sidecar and see relay not reachable, the Chromium process inside the container either didn't start or the relay port isn't exposed. Check that the browser sidecar is actually running with docker exec <container> ps aux | grep chrom and that your config points at the correct relay URL.
Skill Install Failures
ClawHub skill installs fail for two main reasons:
- Missing search API key. Many skills (including tavily-search) need their own API key set as an environment variable before install.
- Version mismatch. A skill built against a newer OpenClaw MCP version won't load on an older container. Upgrade OpenClaw or pick a compatible skill version.
When You Just Want It to Work
Most of these errors come from hand-wiring config, credentials, and version pins. If you'd rather skip the troubleshooting entirely, OpenClaw Launch handles gateway tokens, pairing, version pinning, and credentials for you — deploy a bot in two minutes and get the errors fixed before they happen.