OpenClaw Gateway Token Missing or Unauthorized? Read the Detail Code First

Your OpenClaw Gateway is running, the port answers, and the client still refuses to connect. The Control UI shows a blank panel or drops with unauthorized (1008). The CLI prints unauthorized. A node or an external app reports a token problem. Every one of those symptoms comes from the same handshake, and OpenClaw tells you exactly which part of it failed, if you know where to look.

This guide is about connection auth: the shared gateway token, the per-device token, and device pairing. It is not about model provider keys. If openclaw models status is the thing complaining, you have a provider credential problem instead, which is a different fix.

Read the detail code before you change anything

Do not start by rotating tokens. A failed connect response carries error.details.code, and that single value decides which of five different fixes you need. Rotating a shared token when the real problem is a scope contract will waste an afternoon and leave you exactly where you started.

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

Reproduce the failure while the logs are streaming, then read the detail code out of the failed connect response.

The five auth detail codes, and what each one actually means

• AUTH_TOKEN_MISSING: the client never sent a shared token that the gateway requires. Nothing is broken, nothing is stale. The client simply has no token configured.
• AUTH_TOKEN_MISMATCH: a shared token arrived and it did not match. This is classic token drift after a partial upgrade, a hand-edited config, or a second machine holding an old value.
• AUTH_DEVICE_TOKEN_MISMATCH: the cached per-device token is stale or was revoked. The shared token may be perfectly fine.
• AUTH_SCOPE_MISMATCH: the device token was recognised and accepted, but the approved scopes do not cover what this connection is asking for. This is the one people misread most often. It is not a token problem at all.
• PAIRING_REQUIRED: the device identity needs approval. Check error.details.reason for not-paired, scope-upgrade, role-upgrade or metadata-upgrade.

Fix 1: gateway token missing, or you never knew where to find it

The shared token lives in your gateway config. Read it on the gateway host:

openclaw config get gateway.auth.token

Paste that value into the Control UI settings, or pass it explicitly to the CLI with --token. In containers and daemon setups you can supply it as the OPENCLAW_GATEWAY_TOKEN environment variable instead.

One trap that costs people hours: when you pass --url to a CLI command, OpenClaw stops falling back to your config and environment credentials. You must then pass --token or --password explicitly, or the command fails even though the token is sitting right there in your config file.

Fix 2: token mismatch, the drift recovery checklist

Run these in order. Stop as soon as the client connects.

1. Confirm the current token source: openclaw config get gateway.auth.token
2. List paired devices and find the affected device id: openclaw devices list
3. Rotate the operator token for that device: openclaw devices rotate --device <id> --role operator
4. If rotation is not enough, remove the stale pairing and approve it again: openclaw devices remove <id>, then openclaw devices list, then openclaw devices approve <requestId>
5. Retry the client with the current shared token or password.

Rotation returns a new token and it is a secret, so treat it like one. If a client rotates its own token while authenticated with that same device token, the response includes the replacement so the client can save it before reconnecting. Shared and admin rotations never echo the token back.

Fix 3: device token mismatch, when the shared token is innocent

If the code is AUTH_DEVICE_TOKEN_MISMATCH, the cached per-device token is stale or revoked. Rotate or re-approve that one device and reconnect. Do not touch the shared gateway token, because it is not the thing failing.

OpenClaw also has a forgiving path here. When AUTH_TOKEN_MISMATCH comes back with canRetryWithDeviceToken=true, the client is allowed one trusted retry that sends both the shared token and the stored device token together. That retry reuses the scope set cached with the paired device token.

Fix 4: scope mismatch, do not rotate anything

An AUTH_SCOPE_MISMATCH means the device is known and trusted, but its approved role or scopes do not cover this request. The correct action is to re-pair the device or approve the requested scope contract. Changing the shared gateway auth will not help and adds a second problem on top of the first.

You can see this clearly in openclaw devices list, which prints requested access next to currently approved access for a pending request on an already paired device. That is how a scope upgrade stops looking like a lost pairing.

Fix 5: pairing required

A brand new client, a browser you have not used before, or an app connecting through an adapter all have to be approved once.

openclaw devices list
openclaw devices approve <requestId>

Two details matter. Running openclaw devices approve with no id, or with --latest, only previews the newest pending request and exits with code 1. You have to rerun it with the exact request id to actually approve. And if a device retries pairing with changed role, scopes or public key, OpenClaw supersedes the old pending entry with a new request id, so always list right before you approve.

The macOS trap that produces permanent unauthorized errors

On macOS, launchctl setenv OPENCLAW_GATEWAY_TOKEN ... overrides the config file. If someone set it once, the gateway keeps reading that stale value and every client gets unauthorized no matter how many times you fix the config. Clear it:

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN

Errors that look like auth but are not

• device identity required: you are on a non-secure context, typically plain HTTP from a non-loopback origin, or device auth is simply not set up. Use loopback or a proper secure context.
• origin not allowed: the browser Origin is not in gateway.controlUi.allowedOrigins. Add it, or connect from loopback.
• device nonce required or device nonce mismatch: the client is not completing the challenge based flow. Update the client.
• device signature invalid or device signature expired: the client signed the wrong payload, or the timestamp is stale. Update the connecting client, then check openclaw --version and openclaw doctor.
• gateway connect failed: with no auth code at all: the host, port or URL target is wrong. This is a networking problem, not an auth one.
• too many failed authentication attempts (retry later): repeated failures from the same browser origin are temporarily locked out. Wait it out. A different localhost origin uses a separate bucket.

Quick reference

openclaw gateway status --json      # see the probe URL and auth mode
openclaw config get gateway.auth.token
openclaw devices list               # pending requests and paired devices
openclaw devices approve <id>
openclaw devices rotate --device <id> --role operator
openclaw devices remove <id>
openclaw doctor
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN   # macOS only

Connection auth on a self-hosted gateway is a lot of moving state: one shared token, one token per device, a scope contract per pairing, and an approval queue. On a managed OpenClaw server the gateway, its token and the device approvals are configured once and kept in sync for you, so this class of problem does not reach you in the first place.