OpenClaw trusted proxy auth

Trusted proxy auth is the mode for gateways that live behind an identity-aware proxy: the proxy authenticates the person, adds a header with their identity, and the gateway trusts that header, but only from the proxy. The docs open with a warning that misconfiguration exposes the gateway, and most of the page is the list of checks that make the trust safe. Here it is, in the order the gateway evaluates it.

When and how

• Use it behind Pomerium, Caddy with OAuth, nginx with oauth2-proxy or Traefik forward auth, in container environments where the proxy is the only path, or when browsers hit WebSocket unauthorized errors because they cannot pass tokens in the handshake; do not use it when the proxy only terminates TLS, when any path bypasses the proxy, when you are unsure the proxy strips forwarded headers, or for personal single-user access where a tailnet plus loopback is simpler.
• The flow: the proxy authenticates the user, adds an identity header such as the forwarded-user header, the gateway verifies the request came from a trusted proxy address, reads the required headers and the user identity, and authorizes when the user allowlist, if set, includes the user; the config binds to the local network, lists only the proxy addresses or ranges, sets the auth mode, the user header, optional required headers, an optional user allowlist, loopback off by default and device auto-approval off by default.
• Runtime rules in order: proxy-shaped traffic is attributed before gateway auth and must come from a trusted proxy with client-address headers resolving to a non-loopback client, or gateway-authenticated routes reject it for missing proxy attribution; the proxy must overwrite the forwarded-for chain safely, with the real-address header accepted only when its fallback is enabled; loopback sources are rejected unless the opt-in is true and loopback is also listed as a trusted proxy; sources matching one of the host's own interface addresses are rejected as a spoofing guard, and a failed interface discovery rejects too; then the required headers and the user header must be present and non-blank, and the user allowlist must include the user.
• Forwarded-header evidence on a loopback request disqualifies it from the local-direct password fallback and device-identity gating while still failing trusted-proxy auth; internal clients that do not travel through the proxy use the gateway password, which the status command selects automatically without a URL override; the trusted-proxy list accepts address ranges plainly or in mapped form, and a mapped prefix covering everything still needs the loopback opt-in for loopback.

A Gateway token cannot replace proxy authentication.

Grants, auto-approval and the scopes header

Identity scopes give selected verified users session-only scopes without widening their device grant: the key is the proxy identity or the tailnet login, emails match case-insensitively, the grant is unioned with the device-authorized scopes and then capped by an explicit scopes header, and token, password and no-auth connections never receive one. Device auto-approval, off by default, uses the proxy identity as the approval boundary for new browser and native operator devices and same-key scope upgrades: only trusted-proxy connections with a non-empty identity that passed the allowlist qualify, node-role connections and role upgrades never do, requested scopes are intersected with the configured list (read, write, approvals and questions when unset, never widened), the proxy scopes header caps the persistent grant too, and listing admin makes every proxy user able to receive a full-admin device, which the security audit reports as critical and the gateway warns about at startup. Device-less control-interface sessions cannot self-declare scopes: their list is cleared and a matching identity grant applied; a missing-scope failure after a successful connect means reloading so the browser pairs its device identity. The scopes header declares scopes when present, declares none when present but empty, and falls back to the default operator set when absent, while gateway-auth plugin routes fall back to write only.

TLS, mixed tokens and the audit

• Terminate TLS once and set the strict transport header there: at the proxy for internet-facing deployments with the gateway on loopback behind it, or on the gateway with TLS enabled and the strict transport security header when it serves HTTPS itself; start with a short max age, raise it only once confident, add the subdomain flag only when every subdomain is ready, and skip it for loopback-only development.
• Startup rejects trusted-proxy auth when a shared token is also configured, because a token would let same-host callers authenticate on a different path than the proxy-verified identity; remove the token or switch the mode, and remember that loopback identity headers still fail closed and that token fallback is intentionally unsupported.
• The security audit flags the mode as critical by design and checks for a missing trusted-proxy list, a missing user header, an empty user allowlist, an enabled loopback opt-in and enabled device auto-approval; the checklist adds that the proxy is the only path, the trusted list is minimal, the proxy overwrites forwarded headers and rebuilds the forwarded-for chain, allowed origins are explicit for a non-loopback control interface, and any local password fallback stays private behind the firewall.

OpenClaw operator scopes explains the scope model these grants feed and OpenClaw on Tailscale the simpler alternative for tailnet-only access.

Reading the rejection codes

The troubleshooting section maps each rejection: an untrusted source means the request did not come from a listed proxy address, which changes when containers restart; a loopback source means a same-host proxy without the deliberate opt-in; a local interface source means a process on the gateway host is sending identity headers directly or the proxy shares the host network namespace; a missing user means the header is absent or misnamed; a user not allowed means the account is authenticated but not in the allowlist, and the docs say not to remove the allowlist as a workaround; an origin not allowed means the browser origin failed the control-interface check. The message about proxy authentication being required is a rejected identity, not a network outage, and the fix is signing in at the proxy rather than sending headers from the browser. The migration from token auth is six steps: configure the proxy, test it independently, update the gateway config, restart, test the WebSocket from the control interface, and run the audit. OpenClaw remote access compares the other remote access patterns and OpenClaw pairing the device flow that auto-approval replaces.

On Diali

On Diali each customer gateway is reached through the platform ingress with the runtime configuration generated from the dashboard and replaced at each release, so this mode is not something a customer has to assemble by hand. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around each runtime.

• Trust the header only from listed proxy addresses.
• Loopback and own-interface sources fail closed.
• The scopes header narrows; identity grants add, session-only.