OpenClaw Gateway Unauthorized Errors Fix

Unauthorized Gateway errors are usually not random. They come from one of a few seams: wrong token, wrong URL, URL override without explicit credentials, device-token drift, trusted-proxy headers not matching the request path, Tailscale assumptions, or repeated failures triggering a temporary rate limit. The fix is to identify which auth path you are using before changing config.

30-second answer

First confirm the target URL and auth mode. For CLI commands with --url, pass --token or --password explicitly. For Control UI, check device identity, origin, token/device-token mismatch, and pairing state. For Tailscale Serve, remember that identity headers can cover Control UI/WebSocket flows, but HTTP APIs such as /v1/* and /tools/invoke still require normal Gateway HTTP auth.

When this pays off

This matters when Open WebUI cannot connect, a remote tunnel works for health but not status, Control UI says device identity required, a tool invoke returns 401, or a Tailscale URL works in the browser but API calls fail. In production, auth confusion wastes time and can tempt unsafe config changes, so solve it methodically.

Operator runbook

1. Identify the surface. Gateway WebSocket RPC, Control UI, OpenAI-compatible /v1 endpoints, /tools/invoke, node pairing, and trusted-proxy paths do not all fail the same way. Write down the exact URL, command, client, and whether it is browser, CLI, HTTP, or WebSocket.
2. For CLI URL overrides, add credentials explicitly. The Gateway docs warn that when you pass --url, the CLI does not fall back to config or environment credentials. Use --token or --password on that command. Missing explicit credentials is expected to fail.
3. For token/password auth, verify the server-side source. gateway.auth.token or OPENCLAW_GATEWAY_TOKEN configures token auth; gateway.auth.password or OPENCLAW_GATEWAY_PASSWORD configures password auth. gateway.remote.token is a client credential source, not a server auth setting by itself.
4. For Control UI, read the detail code. Troubleshooting docs mention device identity required, origin not allowed, nonce mismatch, signature invalid or expired, AUTH_TOKEN_MISMATCH, retry later, and gateway connect failed. Each points to a different fix: secure context, allowed origin, challenge flow, token refresh, rate-limit wait, or wrong URL.
5. For Tailscale Serve, separate UI auth from HTTP API auth. Verified identity headers can support Control UI and WebSocket authentication when allowTailscale is true. The docs explicitly say /v1/*, /tools/invoke, and /api/channels/* still follow normal Gateway HTTP auth mode.
6. For trusted-proxy mode, check source and loopback rules. A same-host loopback reverse proxy requires gateway.auth.trustedProxy.allowLoopback to be explicitly true. Forwarded headers that contradict loopback locality should not be treated as trusted local traffic.

Verification

Run one known-good local check, one remote check through the real URL, and one HTTP API check if applicable. Confirm wrong credentials fail, correct credentials succeed, and repeated bad attempts stop producing new failures after the Retry-After window. Keep tokens out of logs and screenshots while debugging.

Common mistakes

Do not turn auth mode to none to see if it works unless the ingress is private and deliberate. Do not paste Gateway tokens into browser frontends. Do not assume a Tailscale page load proves /tools/invoke is authenticated. And do not rotate every credential at once; that makes it harder to know which layer was wrong.

Turn it into a repeatable operating system

The Playbook gives you the auth runbook: local, SSH, tailnet, trusted proxy, device pairing, API callers, and rescue access. Unauthorized errors get much easier when every surface has one documented credential path and one owner.

Before rollout

Before rollout, keep a safe credential rotation checklist. Unauthorized loops often appear right after token changes, service restarts, or tunnel moves. Record where the server token lives, where client tokens are read, and which commands require explicit credentials when a URL override is used.