OpenClaw Trusted Proxy Auth Explained

Trusted-proxy auth is OpenClaw saying, If you already have a real identity-aware proxy, I can trust that boundary instead of asking browsers to carry gateway secrets directly. The docs describe the flow in five steps: the proxy authenticates the user, passes identity headers, OpenClaw verifies the request came from a trusted proxy IP, extracts the configured user header, and authorizes the request if everything matches. That is elegant when the boundary is real and dangerous when it is imaginary.

Why this exists in the first place

The docs call out a practical motivation: browsers and WebSockets can make token-based flows awkward, especially when you are fighting 1008 unauthorized errors. If you already have a reverse proxy handling OAuth, OIDC, or SAML, it can be cleaner to let the proxy authenticate the user and let OpenClaw trust the verified identity headers. In that sense, trusted-proxy auth is not about reducing security. It is about moving the security check to the edge that already owns browser-facing auth.

What makes a proxy trusted

A proxy is not trusted just because you say it is. The docs require explicit gateway.trustedProxies IP entries, a configured userHeader, and optional requiredHeaders for additional verification. Requests from other IPs are rejected. That is the core idea. OpenClaw is not blindly trusting forwarded headers from any source on the network. It is trusting only headers that arrive from an explicitly approved proxy boundary.

Why loopback proxies are rejected

One of the strongest runtime rules is that trusted-proxy auth rejects loopback-source requests. Same-host loopback reverse proxies do not satisfy the model. That is a surprisingly important rule because it stops people from building a fake trust boundary where the proxy and the gateway sit on the same host and anyone who can reach loopback effectively bypasses the intended network check. The docs are drawing a bright line between a real network boundary and a local illusion of one.

Control UI access changes under this mode

When trusted-proxy auth is active and the request passes checks, Control UI WebSocket sessions can connect without device-pairing identity. The docs call out the implication directly: pairing is no longer the primary gate for Control UI access in this mode. Your proxy policy and allowUsers list become the access control surface. That can be a feature if you have strong identity-aware infra. It can also be a trap if your proxy rules are loose or your gateway ingress is wider than you thought.

The rest of the deployment still matters

The docs go beyond the auth header itself and talk about TLS termination, HSTS, and explicit allowed origins for non-loopback Control UI deployments. That is the right level of detail because trusted-proxy auth is not just a header parser. It is a deployment model. The proxy must terminate and protect traffic properly, and the gateway still needs a correctly scoped ingress policy. Otherwise you end up with a beautiful identity header on top of a leaky network path.

So the explanation is simple: trusted-proxy auth works when the reverse proxy is genuinely the only front door and OpenClaw can verify that fact. It fails conceptually when the proxy is just one optional path among many. The docs are strict because this feature has to be strict. If the trust boundary is fuzzy, the whole mode stops making sense.

That is why the docs keep pairing this feature with origin, TLS, and ingress guidance instead of presenting it as a lone auth switch. Trusted-proxy auth only makes sense as part of a full deployment story. The identity header is necessary, but the actual trusted boundary is the whole network and proxy path around it.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.