How to Set Up OpenClaw Gateway Authentication

Gateway authentication protects the OpenClaw control plane: dashboard, WebSocket, HTTP APIs, and operator actions. The dashboard docs list several accepted identity paths during the WebSocket handshake: connect.params.auth.token, connect.params.auth.password, Tailscale Serve identity headers when allowed, and trusted-proxy identity headers when trusted-proxy mode is configured. Pick one primary path and document it; mixed auth guesses are a common source of 1008 disconnects.

Use a shared token for the basic path

The shared-token source is gateway.auth.token or OPENCLAW_GATEWAY_TOKEN. Running openclaw dashboard can pass a token through a URL fragment for one-time bootstrap when that is safe, and the Control UI stores it in sessionStorage for the current browser tab session and selected gateway URL. If the token is SecretRef-managed, the CLI prints or opens a non-tokenized URL by design so an externally managed secret does not leak into shell logs, clipboard history, or browser arguments.

Use a password when that fits your environment

A shared password can come from gateway.auth.password or OPENCLAW_GATEWAY_PASSWORD. The dashboard does not persist passwords across reloads. That is less convenient than a stored tab token, but it can be easier for some operator workflows. Store the password in the right secret source for your host, not in a team chat or a README. If auth is unresolved because the shell cannot see a SecretRef or env var, fix the gateway host environment before blaming the browser.

Use identity-bearing access for private networks

Tailscale Serve can satisfy Control UI and WebSocket auth through identity headers when gateway.auth.allowTailscale is true. A non-loopback identity-aware reverse proxy can satisfy auth when gateway.auth.mode is trusted-proxy. These modes are useful when you want the network identity layer to do the heavy lifting. They also require careful proxy boundaries. Only trust headers from the proxy path you control; never accept identity headers from arbitrary public traffic.

Handle 1008 and token drift

If you see unauthorized or 1008, first confirm the gateway is reachable. Then retrieve or supply the shared secret from the gateway host. The docs mention openclaw config get gateway.auth.token for token lookup, resolving the configured password or environment password, exporting OPENCLAW_GATEWAY_TOKEN for SecretRef-managed token repair, or running openclaw doctor --generate-gateway-token when no shared secret exists. Token drift may require the device recovery checklist.

Security stance

Do not expose Control UI publicly. Authentication is necessary, but network exposure still matters because the UI is an admin surface. Prefer localhost, Tailscale Serve, a properly configured trusted proxy, or an SSH tunnel. The OpenClaw Playbook's gateway auth runbook is intentionally boring: one auth mode, one secret source, one private route, one recovery command, and one note explaining who may approve new devices.

Pick one recovery owner

Gateway auth problems become stressful when everyone tries to repair them differently. Pick one recovery owner for a production gateway and document the approved repair sequence: confirm reachability, identify the intended auth mode, resolve the secret source, regenerate only if necessary, and revoke stale device approvals when appropriate. Avoid generating new tokens just because one browser tab is stale. A shared gateway can accumulate old secrets, old paired devices, and old proxy assumptions quickly. Clean auth is boring because there is one expected path and one person accountable for changing it.

Final verification

Before calling How to Set Up OpenClaw Gateway Authentication finished, perform one direct test, one failure test, and one rollback check. The direct test proves the happy path works. The failure test proves the documented guardrail is real, not just assumed. The rollback check tells the next operator how to undo the change without improvising. Save those notes beside the channel, node, or gateway config you changed. OpenClaw gets powerful when agents can act, but it stays trustworthy when every new surface has a small, repeatable verification habit attached to it.