github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-19 01:07:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(gateway): harden proxy client ip resolution

Browse Source
This commit is contained in:
Peter Steinberger
2026-02-21 13:32:25 +01:00
parent 8b1fe0d1e2
commit be7f825006
15 changed files with 246 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/gateway/security/index.md
View File

@@ -168,18 +168,34 @@ keys so you can review them in one place (for example
If you run the Gateway behind a reverse proxy (nginx, Caddy, Traefik, etc.), you should configure `gateway.trustedProxies` for proper client IP detection.
When the Gateway detects proxy headers (`X-Forwarded-For` or `X-Real-IP`) from an address that is **not** in `trustedProxies`, it will **not** treat connections as local clients. If gateway auth is disabled, those connections are rejected. This prevents authentication bypass where proxied connections would otherwise appear to come from localhost and receive automatic trust.
When the Gateway detects proxy headers from an address that is **not** in `trustedProxies`, it will **not** treat connections as local clients. If gateway auth is disabled, those connections are rejected. This prevents authentication bypass where proxied connections would otherwise appear to come from localhost and receive automatic trust.
```yaml
gateway:
trustedProxies:
- "127.0.0.1" # if your proxy runs on localhost
# Optional. Default false.
# Only enable if your proxy cannot provide X-Forwarded-For.
allowRealIpFallback: false
auth:
mode: password
password: ${OPENCLAW_GATEWAY_PASSWORD}
```
When `trustedProxies` is configured, the Gateway will use `X-Forwarded-For` headers to determine the real client IP for local client detection. Make sure your proxy overwrites (not appends to) incoming `X-Forwarded-For` headers to prevent spoofing.
When `trustedProxies` is configured, the Gateway uses `X-Forwarded-For` to determine the client IP. `X-Real-IP` is ignored by default unless `gateway.allowRealIpFallback: true` is explicitly set.
Good reverse proxy behavior (overwrite incoming forwarding headers):
```nginx
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
```
Bad reverse proxy behavior (append/preserve untrusted forwarding headers):
```nginx
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```
## Local session logs live on disk