OpenClaw Security Audit: Reverse Proxy, Trusted Proxies & Gateway Hardening [2026]

If you've run openclaw security audit and seen the warning "reverse proxy headers are not trusted" alongside the code gateway.trusted_proxies_missing, you're looking at one of the most common — and most important — security findings in an OpenClaw deployment. This guide explains exactly what the warning means, why ignoring it is dangerous, and how to fix it for every major reverse proxy.

What the Security Audit Is Telling You

Running openclaw security audit performs a series of checks against your gateway configuration. When OpenClaw detects that it's receiving forwarded headers (like X-Forwarded-For) but has no gateway.trustedProxies list configured, it produces this output:

WARN  gateway.trusted_proxies_missing
      Reverse proxy headers are not trusted.
      Configure gateway.trustedProxies in openclaw.json

This means OpenClaw is sitting behind a reverse proxy but has no way to verify which forwarded headers to trust. Every request arrives with a source IP of 127.0.0.1 (the proxy), and OpenClaw cannot determine the real client IP.

Why This Matters: IP Spoofing and Header Injection

The X-Forwarded-For header is how reverse proxies communicate the original client IP to backend services. The problem is that this header can be set by anyone — including attackers. Without a trusted proxies configuration, two things go wrong:

1. Client IP spoofing. An attacker can send a request with a fake X-Forwarded-For: 192.168.1.1 header. If OpenClaw blindly trusts that header, it logs the wrong IP, applies the wrong access controls, and its per-client rate limiting breaks down.[^1]

2. Access control bypass. OpenClaw uses the client IP to distinguish local connections from remote ones. Local connections get elevated access (like device pairing and admin operations). If the proxy IP isn't in the trusted list, OpenClaw either treats every connection as local (because it comes from 127.0.0.1) or refuses to trust forwarded headers entirely — both outcomes undermine security.

The gateway.trustedProxies setting tells OpenClaw: "Only strip and trust X-Forwarded-For headers from these specific IPs." Everything else gets the header discarded.

The Fix: Configuring gateway.trustedProxies

The core fix is the same regardless of which reverse proxy you use:

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

This tells the gateway to trust forwarded headers only when the request originates from 127.0.0.1 — your local reverse proxy. If your proxy runs on a different machine, use that machine's IP instead.

You can also edit openclaw.json directly:

{
  "gateway": {
    "mode": "local",
    "trustedProxies": ["127.0.0.1"]
  }
}

After making the change, restart the gateway and re-run the audit:

openclaw restart
openclaw security audit

You should now see:

OK  gateway.trusted_proxies — reverse proxy headers are trusted

Reverse Proxy Configuration by Server

The OpenClaw side is only half the fix. Your reverse proxy must also be configured to set the correct forwarded headers.

Caddy

Caddy handles forwarded headers automatically. A minimal Caddyfile is all you need:[^2]

openclaw.yourdomain.com {
    reverse_proxy localhost:3001
}

Caddy sets X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host by default. No extra header configuration is required.

Reload after changes:

caddy reload --adapter caddyfile --config /etc/caddy/Caddyfile

Nginx

Nginx requires explicit header directives. Without them, OpenClaw receives no forwarding information at all:[^3]

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The critical line is proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for. This appends the real client IP to any existing X-Forwarded-For chain rather than replacing it — important for multi-proxy setups.

After editing, test and reload:

nginx -t && systemctl reload nginx

Apache

For Apache with mod_proxy, enable mod_headers and configure forwarding:

<VirtualHost *:443>
    ServerName openclaw.yourdomain.com

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3001/
    ProxyPassReverse / http://127.0.0.1:3001/

    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}e"

    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:3001/$1 [P,L]
</VirtualHost>

Enable the required modules:

a2enmod proxy proxy_http proxy_wstunnel headers rewrite
systemctl restart apache2

Understanding the Full Security Audit Output

The trusted_proxies_missing check is one of several items the security audit evaluates. A full openclaw security audit covers:

OK   gateway.token_set — gateway token is configured
WARN gateway.trusted_proxies_missing — reverse proxy headers are not trusted
OK   gateway.port_restricted — gateway port is not publicly exposed
OK   security.device_pairing — device pairing is enabled
OK   security.webhook_auth — webhook endpoints require authentication

The --deep flag runs additional checks:

openclaw security audit --deep

This adds checks for open ports, enabled browser-control tools, file permission exposure, and skill sandbox integrity.

Multiple Proxy Hops

If traffic passes through multiple proxies (e.g., Cloudflare to Nginx to OpenClaw), you need to trust each hop:

openclaw config set gateway.trustedProxies '["127.0.0.1", "172.17.0.1"]'

List every proxy IP that will set forwarded headers. OpenClaw walks the X-Forwarded-For chain from right to left, stripping trusted IPs until it finds the first untrusted one — that becomes the real client IP.

Do not use ["0.0.0.0/0"] or wildcard CIDRs. Trusting all IPs defeats the entire purpose of the setting and leaves you vulnerable to the same spoofing attacks the audit warns about.

Verifying the Fix

After configuring both sides, verify end to end:

# 1. Re-run the security audit
openclaw security audit

# 2. Check gateway logs for the real client IP
openclaw logs --follow

# 3. Run doctor for overall health
openclaw doctor

If the audit now reports OK for gateway.trusted_proxies, your forwarded headers are being validated correctly.

Skip the Configuration Entirely

ClawTank handles reverse proxy configuration, TLS certificates, and trusted proxy settings automatically for every instance. The security audit passes out of the box — no manual gateway hardening required.

[^1]: OWASP Web Security Testing Guide — covers X-Forwarded-For header abuse and IP-based access control testing. [^2]: Caddy reverse_proxy directive documentation — details automatic header handling and upstream configuration. [^3]: Nginx ngx_http_proxy_module documentation — reference for proxy_set_header and forwarded header configuration.