OpenClaw Trusted Proxy Auth: Put Gateway Access Behind Real Identity

Putting an OpenClaw Gateway behind a reverse proxy sounds simple until the proxy becomes your security boundary.

That is the point of trusted-proxy auth. It lets OpenClaw delegate user authentication to an identity-aware proxy such as Pomerium, Caddy with OAuth, nginx with oauth2-proxy, or Traefik with forward auth. The proxy authenticates the human, passes an identity header, and OpenClaw accepts the request only if it came from a configured trusted proxy source.

This is useful when you want a real operator login in front of the Control UI, WebSocket traffic, or Gateway HTTP surfaces. It is also risky. If the Gateway can be reached without the proxy, or if clients can spoof the identity header, you did not add auth. You moved the front door and left the side door open.

Use it for identity-aware proxy setups

The OpenClaw docs are clear about the intended shape. Use trusted proxy auth when the reverse proxy actually authenticates users and passes user identity through headers. Good fits include OAuth, OIDC, SAML, forward-auth, and Kubernetes or container setups where the proxy is the only route into the Gateway.

It is not the right answer for a plain TLS terminator. A load balancer that only forwards traffic is not an auth layer. If all you need is personal single-user access, the docs point to simpler patterns such as loopback access with SSH tunnels or Tailscale Serve. That is usually the better default for a solo operator.

Trusted proxy auth earns its keep when you have more than one operator, a real identity provider, or a browser path that cannot pass token material cleanly during WebSocket upgrades. In that world, the proxy owns login, and OpenClaw verifies that the request really came through that login boundary.

The minimum safe config

The core config has three parts: the Gateway binding, the list of trusted proxy IPs, and the trusted-proxy auth block.

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

The important field is not the header name. It is trustedProxies. OpenClaw checks that the request source is one of those configured proxy addresses. Requests from other sources are rejected before the user header gets to act like identity.

userHeader is the header that contains the authenticated user. The docs show examples such as x-forwarded-user, x-pomerium-claim-email, and x-auth-request-email. Pick the header your proxy actually controls. Do not pick a header clients can supply and the proxy merely forwards.

I would also set allowUsers from the start. The docs say an empty allowlist allows all authenticated users. That might be fine inside a tightly controlled company identity group, but for most operators it is too broad. The whole point is to be explicit about who can reach the agent control surface.

Loopback is deliberately stricter now

A common same-host setup is Caddy or nginx on the same machine as OpenClaw, proxying to the Gateway on loopback. That pattern can be safe, but only if you are honest about what is being trusted.

The live docs say trusted-proxy auth rejects loopback-source requests by default. Same-host loopback proxies need an explicit opt-in with gateway.auth.trustedProxy.allowLoopback = true and the loopback address in gateway.trustedProxies.

{
  gateway: {
    bind: "loopback",
    trustedProxies: ["127.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        requiredHeaders: ["x-forwarded-proto"],
        allowUsers: ["operator@example.com"],
        allowLoopback: true,
      },
    },
  },
}

That flag is not cosmetic. Enabling it means local processes on the Gateway host are trusted to the same degree as the reverse proxy path. That can be acceptable on a locked-down single-purpose host. It is not something I would casually enable on a shared development machine with random local services and scripts.

If you do use loopback, keep the Gateway private to the host, require proxy-owned headers such as x-forwarded-proto or a signed assertion header where possible, and make sure the proxy strips or overwrites any client-supplied forwarded headers.

WebSocket access has its own trap

Trusted proxy auth helps with browser and WebSocket setups because the proxy can pass identity on the upgrade request. But the Control UI is still a control surface, not just a login page.

The current docs describe an important scope behavior. In trusted-proxy mode, a Control UI WebSocket session may connect without device pairing identity after the trusted-proxy checks pass. But device-less Control UI sessions do not get operator scopes by default. OpenClaw clears requested scopes to an empty list so an unpaired browser session cannot simply declare its own permissions.

If the WebSocket connects but calls such as session or model reads fail with a missing scope error, that can be expected. The safer fix is to use HTTPS so the browser can generate device identity and complete pairing. The docs also mention gateway.controlUi.dangerouslyDisableDeviceAuth as a break-glass option, and the name is doing real work there. It is a severe downgrade, not a convenience toggle.

For non-loopback Control UI deployments, the docs also call out gateway.controlUi.allowedOrigins. Set the exact browser origins you expect. Do not rely on wildcard origin behavior just because the proxy already authenticated the user.

Proxy examples are patterns, not paste-and-pray configs

The docs include patterns for several proxies. A Caddy setup with OAuth can authenticate the user and pass the email into OpenClaw:

openclaw.example.com {
    authenticate with oauth2_provider
    authorize with policy1

    reverse_proxy openclaw:18789 {
        header_up X-Forwarded-User {http.auth.user.email}
    }
}

An nginx plus oauth2-proxy setup can use an auth subrequest and pass X-Auth-Request-Email into the Gateway:

location / {
    auth_request /oauth2/auth;
    auth_request_set $user $upstream_http_x_auth_request_email;

    proxy_pass http://openclaw:18789;
    proxy_set_header X-Auth-Request-Email $user;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

The interesting detail in the nginx example is not the auth_request line. It is the WebSocket handling: proxy_http_version 1.1, Upgrade, and Connection. If those are wrong, a normal page load may work while the Control UI WebSocket still fails.

Also watch container IPs. The docs specifically call out that Docker container IPs can change. If trusted_proxy_untrusted_source appears after a deploy, do not blindly broaden trustedProxies. First confirm the actual proxy source with your container or cluster tooling.

Do not mix token auth into this mode

The live docs say OpenClaw rejects ambiguous configurations where both gateway.auth.token or OPENCLAW_GATEWAY_TOKEN and trusted-proxy mode are active at the same time. That is the right failure mode.

Mixed token and proxy identity setups can make it unclear which auth path actually admitted a request. In agent operations, ambiguity is where security incidents hide. If you are using trusted proxy auth, remove the shared token from that path. If you want token-based auth, use token mode instead.

Internal Gateway clients that do not go through the proxy should use password-based internal auth where the docs allow it, not fake trusted-proxy identity headers. Keep those internal paths private and boring.

Operator scopes should be intentionally narrow

Trusted proxy auth is identity-bearing HTTP auth, so the docs describe an optional x-openclaw-scopes header for HTTP API requests. That header can declare scopes such as operator.read, operator.write, or operator.admin.

The practical rule is simple: send scopes explicitly when you want a trusted-proxy request to be narrower than the default, or when a gateway-auth plugin route needs a stronger scope than the write fallback. Do not treat the header as magic authorization. For Control UI WebSocket upgrades, the header caps negotiated scopes; it does not grant scopes by itself.

That distinction matters if you are building internal automations around the Gateway. A proxy identity should not automatically mean "admin forever." It should mean "this authenticated operator or internal service can do the narrow thing this route requires."

Security audit will complain on purpose

The docs say openclaw security audit flags trusted-proxy auth with critical severity. That is intentional. OpenClaw is reminding you that it is delegating authentication to infrastructure outside the Gateway.

The audit checks for expected problems: missing trustedProxies, missing userHeader, empty allowUsers, enabled allowLoopback, and weak browser-origin policy on exposed Control UI surfaces. Do not treat the audit as noise. Treat it as a preflight checklist before you expose anything to operators.

1. Is the proxy the only network path to the Gateway?
2. Are trustedProxies exact proxy IPs, not broad subnets?
3. Does the proxy overwrite client-supplied identity headers?
4. Is allowUsers set to real operators?
5. Are Control UI origins explicit for non-loopback access?
6. Did openclaw security audit report only the risks you expect?

That checklist is the difference between a controlled operator login and a hopeful reverse proxy. Hope is not a security model.

Troubleshooting by error name

Trusted proxy auth has useful failure names. trusted_proxy_untrusted_source means the request did not come from a configured proxy IP. trusted_proxy_user_missing means the identity header is missing or empty. trusted_proxy_user_not_allowed means the authenticated user is not in allowUsers. trusted_proxy_origin_not_allowed means proxy auth succeeded, but the browser origin did not pass Control UI origin checks.

The error names point to different layers. Do not fix a source-IP problem by loosening the user allowlist. Do not fix a missing WebSocket scope by disabling device auth unless you have deliberately accepted that downgrade. Do not fix an origin failure with a wildcard until you understand exactly which browser origin is supposed to reach the Gateway.

When WebSocket still fails, check that the proxy supports upgrades and passes identity headers on upgrade requests, not only on normal HTTP requests. Many "the login page works but the UI is broken" reports end up here.

The setup I would trust

For a small team, I would start with the boring shape: one identity-aware proxy, HTTPS terminated at the proxy, exact trustedProxies, exact allowUsers, explicit Control UI origins, no mixed token config, and a short HSTS rollout while validating traffic.

If this is a solo operator setup, I would usually avoid trusted proxy auth entirely and use loopback plus SSH or Tailscale Serve first. Fewer moving parts means fewer wrong assumptions. If the setup grows into a team surface, then trusted proxy auth becomes worth the extra care.

The useful mindset is this: OpenClaw is not asking you to trust a header. It is asking you to trust the proxy that creates the header, the network boundary that forces traffic through that proxy, and the audit trail that proves the setup still matches that design.

Want the complete guide? Get ClawKit — $9.99