Summary

Add explicit safeguards and warnings for auth.mode = trusted-proxy to prevent insecure deployments when upstream proxy authentication is not configured.

Problem to solve

OpenClaw currently recommends using reverse proxy authentication solutions (e.g., Pomerium, OAuth-based proxies, forward-auth, etc.) together with trusted-proxy mode.
However, in practice:

• Users may misconfigure or omit authentication at the proxy layer
• OpenClaw fully trusts proxy headers (e.g., X-Forwarded-User) without validation
• Built-in authentication (token/password) is completely bypassed

This creates a silent failure mode:

• The system appears “secured” (trusted-proxy enabled)
• But gateway is fully open if proxy auth is missing or misconfigured

This is especially risky for:

• New users unfamiliar with reverse proxy security
• Copy-paste configurations from examples
• Internal deployments later exposed to wider networks

Proposed solution

Introduce explicit safety guardrails while preserving the design philosophy of trusted-proxy.

1. Explicit opt-in requirement
   Require users to explicitly acknowledge the security implications when enabling trusted-proxy. Possible approaches:

• Add a required config flag, e.g.:

"auth": {
  "mode": "trusted-proxy",
  "insecureAllowNoUpstreamAuth": true
}

• Or require confirmation if no additional safeguards are present

2. Runtime warning
   Display a clear warning when trusted-proxy is enabled:

WARNING: trusted-proxy mode disables built-in authentication.
Authentication is fully delegated to the upstream proxy.
Ensure your proxy enforces authentication correctly.

Alternatives considered

No response

Impact

Affected users/systems/channels:

• All deployments using auth.mode = trusted-proxy
• Especially users setting up reverse proxies manually (nginx, Caddy, Traefik, etc.)

Severity:

• High (can result in unintended unauthenticated access)

Frequency:

• Common in misconfigured setups
• Likely during initial deployment or experimentation

Consequence:

• Unauthorized access
• Identity spoofing via headers
• False sense of security
• Potential exposure when moving from local → network environments

Evidence/examples

1. Misconfigured nginx for users unfamiliar with reverse proxy and without any authentication:

server {
    listen 8080;
    location / {
        proxy_pass http://127.0.0.1:17890;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-User test@example.com;
    }
}

2. Configure OpenClaw:

"gateway": {
  "port": 17890,
  "mode": "local",
  "bind": "loopback",
  "auth": {
    "mode": "trusted-proxy",
    "token": "xxx",
    "trustedProxy": {
      "userHeader": "x-forwarded-user"
    }
  },
  "trustedProxies": ["127.0.0.1"]
}

3. From another device on the same network, access: http://<host>:8080
4. Result:

• Any request is treated as authenticated
• User identity is fully controlled by header injection

Additional information

This proposal does not aim to change the trust model, but to:

• Make the trust boundary explicit
• Prevent accidental insecure configurations
• Improve UX and security awareness

It remains fully backward-compatible:

• Advanced users can still opt-in and use trusted-proxy as intended
• No breaking changes to existing config keys