Use this file to discover all available pages before exploring further.

Trusted proxy auth

warning

**Security-sensitive feature.** This mode delegates authentication entirely to your reverse proxy. Misconfiguration can expose your Gateway to unauthorized access. Read this page carefully before enabling.

When to use

Use

text

trusted-proxy

auth mode when:

You run OpenClaw behind an identity-aware proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
Your proxy handles all authentication and passes user identity via headers.
You're in a Kubernetes or container environment where the proxy is the only path to the Gateway.
You're hitting WebSocket
text
1008 unauthorized
errors because browsers can't pass tokens in WS payloads.

When NOT to use

If your proxy doesn't authenticate users (just a TLS terminator or load balancer).
If there's any path to the Gateway that bypasses the proxy (firewall holes, internal network access).
If you're unsure whether your proxy correctly strips/overwrites forwarded headers.
If you only need personal single-user access (consider Tailscale Serve + loopback for simpler setup).

How it works

Proxy authenticates the user

Your reverse proxy authenticates users (OAuth, OIDC, SAML, etc.).

Proxy adds an identity header

Proxy adds a header with the authenticated user identity (e.g., `x-forwarded-user: nick@example.com`).

Gateway verifies trusted source

OpenClaw checks that the request came from a **trusted proxy IP** (configured in `gateway.trustedProxies`).

Gateway extracts identity

OpenClaw extracts the user identity from the configured header.

Authorize

If everything checks out, the request is authorized.

Control UI pairing behavior

When

text

gateway.auth.mode = "trusted-proxy"

is active and the request passes trusted-proxy checks, Control UI WebSocket sessions can connect without device pairing identity.

Implications:

Pairing is no longer the primary gate for Control UI access in this mode.
Your reverse proxy auth policy and
text
allowUsers
become the effective access control.
Keep gateway ingress locked to trusted proxy IPs only (
text
gateway.trustedProxies
+ firewall).

Configuration


json5
{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

warning

**Important runtime rules**

Trusted-proxy auth rejects loopback-source requests (
text
127.0.0.1
,
text
::1
, loopback CIDRs) by default.
Same-host loopback reverse proxies do not satisfy trusted-proxy auth unless you explicitly set
text
gateway.auth.trustedProxy.allowLoopback = true
and include the loopback address in
text
gateway.trustedProxies
.
text
allowLoopback
trusts local processes on the Gateway host to the same degree as the reverse proxy. Enable it only when the Gateway is still firewalled from direct remote access and the local proxy strips or overwrites client-supplied identity headers.
Internal Gateway clients that do not travel through the reverse proxy should use
text
gateway.auth.password
/
text
OPENCLAW_GATEWAY_PASSWORD
, not trusted-proxy identity headers.
Non-loopback Control UI deployments still need explicit
text
gateway.controlUi.allowedOrigins
.
Forwarded-header evidence overrides loopback locality for local direct fallback. If a request arrives on loopback but carries
text
X-Forwarded-For
/
text
X-Forwarded-Host
/
text
X-Forwarded-Proto
headers pointing at a non-local origin, that evidence disqualifies local-direct password fallback and device-identity gating. With
text
allowLoopback: true
, trusted-proxy auth can still accept the request as a same-host proxy request, while
text
requiredHeaders
and
text
allowUsers
continue to apply.

Configuration reference

Array of proxy IP addresses to trust. Requests from other IPs are rejected. Must be `"trusted-proxy"`. Header name containing the authenticated user identity. Additional headers that must be present for the request to be trusted. Allowlist of user identities. Empty means allow all authenticated users. Opt-in support for same-host loopback reverse proxies. Defaults to `false`.

warning

Only enable `allowLoopback` when the local reverse proxy is the intended trust boundary. Any local process that can connect to the Gateway can try to send proxy identity headers, so keep direct Gateway access private to the host and require proxy-owned headers such as `x-forwarded-proto` or a signed assertion header where your proxy supports one.

TLS termination and HSTS

Use one TLS termination point and apply HSTS there.

When your reverse proxy handles HTTPS for `https://control.example.com`, set `Strict-Transport-Security` at the proxy for that domain.


text
* Good fit for internet-facing deployments.
* Keeps certificate + HTTP hardening policy in one place.
* OpenClaw can stay on loopback HTTP behind the proxy.

Example header value:

```text}
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

If OpenClaw itself serves HTTPS directly (no TLS-terminating proxy), set:


text
```json5}
{
  gateway: {
    tls: { enabled: true },
    http: {
      securityHeaders: {
        strictTransportSecurity: "max-age=31536000; includeSubDomains",
      },
    },
  },
}
```

`strictTransportSecurity` accepts a string header value, or `false` to disable explicitly.

Rollout guidance

Start with a short max age first (for example
text
max-age=300
) while validating traffic.
Increase to long-lived values (for example
text
max-age=31536000
) only after confidence is high.
Add
text
includeSubDomains
only if every subdomain is HTTPS-ready.
Use preload only if you intentionally meet preload requirements for your full domain set.
Loopback-only local development does not benefit from HSTS.

Proxy setup examples

Mixed token configuration

OpenClaw rejects ambiguous configurations where both a

text

gateway.auth.token

(or

text

OPENCLAW_GATEWAY_TOKEN

) and

text

trusted-proxy

mode are active at the same time. Mixed token configs can cause loopback requests to silently authenticate on the wrong auth path.

If you see a

text

mixed_trusted_proxy_token

error on startup:

Remove the shared token when using trusted-proxy mode, or
Switch
text
gateway.auth.mode
to
text
"token"
if you intend token-based auth.

Loopback trusted-proxy identity headers still fail closed: same-host callers are not silently authenticated as proxy users. Internal OpenClaw callers that bypass the proxy may authenticate with

text

gateway.auth.password

text

OPENCLAW_GATEWAY_PASSWORD

instead. Token fallback remains intentionally unsupported in trusted-proxy mode.

Operator scopes header

Trusted-proxy auth is an identity-bearing HTTP mode, so callers may optionally declare operator scopes with

text

x-openclaw-scopes

Examples:

text
x-openclaw-scopes: operator.read
text
x-openclaw-scopes: operator.read,operator.write
text
x-openclaw-scopes: operator.admin,operator.write

Behavior:

When the header is present, OpenClaw honors the declared scope set.
When the header is present but empty, the request declares no operator scopes.
When the header is absent, normal identity-bearing HTTP APIs fall back to the standard operator default scope set.
Gateway-auth plugin HTTP routes are narrower by default: when
text
x-openclaw-scopes
is absent, their runtime scope falls back to
text
operator.write
.
Browser-origin HTTP requests still have to pass
text
gateway.controlUi.allowedOrigins
(or deliberate Host-header fallback mode) even after trusted-proxy auth succeeds.

Practical rule: send

text

x-openclaw-scopes

explicitly when you want a trusted-proxy request to be narrower than the defaults, or when a gateway-auth plugin route needs something stronger than write scope.

Security checklist

Before enabling trusted-proxy auth, verify:

Proxy is the only path: The Gateway port is firewalled from everything except your proxy.
trustedProxies is minimal: Only your actual proxy IPs, not entire subnets.
Loopback proxy source is deliberate: trusted-proxy auth fails closed for loopback-source requests unless
text
gateway.auth.trustedProxy.allowLoopback
is explicitly enabled for a same-host proxy.
Proxy strips headers: Your proxy overwrites (not appends)
text
x-forwarded-*
headers from clients.
TLS termination: Your proxy handles TLS; users connect via HTTPS.
allowedOrigins is explicit: Non-loopback Control UI uses explicit
text
gateway.controlUi.allowedOrigins
.
allowUsers is set (recommended): Restrict to known users rather than allowing anyone authenticated.
No mixed token config: Do not set both
text
gateway.auth.token
and
text
gateway.auth.mode: "trusted-proxy"
.
Local password fallback is private: If you configure
text
gateway.auth.password
for internal direct callers, keep the Gateway port firewalled so non-proxy remote clients cannot reach it directly.

Security audit

text

openclaw security audit

will flag trusted-proxy auth with a critical severity finding. This is intentional — it's a reminder that you're delegating security to your proxy setup.

The audit checks for:

Base
text
gateway.trusted_proxy_auth
warning/critical reminder
Missing
text
trustedProxies
configuration
Missing
text
userHeader
configuration
Empty
text
allowUsers
(allows any authenticated user)
Enabled
text
allowLoopback
for same-host proxy sources
Wildcard or missing browser-origin policy on exposed Control UI surfaces

Troubleshooting

Migration from token auth

If you're moving from token auth to trusted-proxy:

Configure the proxy

Configure your proxy to authenticate users and pass headers.

Test the proxy independently

Test the proxy setup independently (curl with headers).

Update OpenClaw config

Update OpenClaw config with trusted-proxy auth.

Restart the Gateway

Restart the Gateway.

Test WebSocket

Test WebSocket connections from the Control UI.

Audit

Run `openclaw security audit` and review findings.

Configuration — config reference
Remote access — other remote access patterns
Security — full security guide
Tailscale — simpler alternative for tailnet-only access

OpenClaw Docs

Trusted proxy auth

warning

When to use

When NOT to use

How it works

Proxy authenticates the user

Proxy adds an identity header

Gateway verifies trusted source

Gateway extracts identity

Authorize

Control UI pairing behavior

Configuration

warning

Configuration reference

warning

TLS termination and HSTS

Rollout guidance

Proxy setup examples

Mixed token configuration

Operator scopes header

Security checklist

Security audit

Troubleshooting

Migration from token auth

Configure the proxy

Test the proxy independently

Update OpenClaw config

Restart the Gateway

Test WebSocket

Audit

Related