How to Use OpenClaw Trusted Proxy Auth

Trusted-proxy auth is one of the most security-sensitive OpenClaw features, and the docs absolutely sound the alarm on it. This mode delegates authentication entirely to your reverse proxy, which means a good setup feels elegant and a bad setup can expose the gateway to unauthorized access. The right way to use it is not to treat it as a shortcut. Treat it as a precise deployment pattern for environments that already have an identity-aware proxy in front of the gateway.

Step 1: confirm that your proxy is actually doing identity-aware auth

The docs say trusted-proxy mode is for systems like Pomerium, Caddy with OAuth, nginx with oauth2-proxy, or Traefik with forward auth. The proxy must authenticate users and pass identity headers. If your proxy is only terminating TLS or forwarding traffic, it is not enough. The docs also say you should not use this mode if there is any path to the gateway that bypasses the proxy. That includes firewall holes and accidental internal access.

Step 2: configure the gateway for non-loopback trusted traffic

The example configuration starts with a non-loopback bind such as lan, then lists the exact proxy IPs under gateway.trustedProxies. Under gateway.auth, set mode to trusted-proxy and configure the trustedProxy block with a required userHeader, optional requiredHeaders, and optional allowUsers. The important thing is that the trust is coming from two places together: the source IP must match a trusted proxy, and the expected identity headers must be present.

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1", "172.17.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
        allowUsers: ["nick@example.com", "admin@company.org"]
      }
    }
  }
}

Step 3: respect the loopback rule

The docs are explicit that trusted-proxy auth rejects loopback-source requests. Same-host loopback reverse proxies do not count. If your proxy is on the same host and reaching the gateway through loopback, use token or password auth instead, or route through a non-loopback trusted proxy address that OpenClaw can verify. This rule is easy to resent and exactly the kind of thing that prevents a fake proxy boundary from turning into accidental open access.

Step 4: remember that pairing stops being the primary gate for Control UI

When trusted-proxy auth is active and the request passes trusted-proxy checks, the docs say Control UI WebSocket sessions can connect without device-pairing identity. That means your reverse proxy policy and allowUsers list become the effective access control. This is why the docs repeat the firewall and trustedProxies requirement so aggressively. If you enable trusted-proxy auth, you are consciously moving the front door.

Step 5: finish the deployment cleanly

The docs also mention a few supporting rules. Non-loopback Control UI deployments still need explicit gateway.controlUi.allowedOrigins. TLS termination and HSTS should be applied deliberately, typically at the proxy. And rollout should begin with a short HSTS max-age before moving to long-lived values. These are not random extras. They are part of making sure the proxy boundary you are delegating to is actually the one users go through.

The safe version of trusted-proxy auth looks like this: identity-aware proxy, strict trusted proxy IP list, explicit identity header, no bypass path, non-loopback source, and deliberate origin plus TLS policy. If that sounds strict, good. This is one of those OpenClaw features where the docs are trying very hard to save you from a clever but fragile setup.

The docs are basically asking you to prove the proxy boundary is real before you turn this on. If you cannot point to the exact trusted proxy IPs, the exact identity header, and the exact rule that prevents bypass traffic, you are not ready yet. That is a healthy standard. Trusted-proxy auth is powerful precisely because OpenClaw treats a good proxy as a real security boundary.

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.