diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md
index 14ca0cd86e7..40d5b810ac7 100644
--- a/docs/channels/bluebubbles.md
+++ b/docs/channels/bluebubbles.md
@@ -404,9 +404,9 @@ Prefer `chat_guid` for stable routing:
 
 ## Security
 
-- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
+- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`.
 - Keep the API password and webhook endpoint secret (treat them like credentials).
-- Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure `gateway.trustedProxies`. See [Gateway security](/gateway/security#reverse-proxy-configuration).
+- There is no localhost bypass for BlueBubbles webhook auth. If you proxy webhook traffic, keep the BlueBubbles password on the request end-to-end. `gateway.trustedProxies` does not replace `channels.bluebubbles.password` here. See [Gateway security](/gateway/security#reverse-proxy-configuration).
 - Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
 
 ## Troubleshooting
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index 61121494838..154129e71bb 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -408,14 +408,21 @@ schema:
 
 ## Reverse Proxy Configuration
 
-If you run the Gateway behind a reverse proxy (nginx, Caddy, Traefik, etc.), you should configure `gateway.trustedProxies` for proper client IP detection.
+If you run the Gateway behind a reverse proxy (nginx, Caddy, Traefik, etc.), configure
+`gateway.trustedProxies` for proper forwarded-client IP handling.
 
 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.
 
+`gateway.trustedProxies` also feeds `gateway.auth.mode: "trusted-proxy"`, but that auth mode is stricter:
+
+- trusted-proxy auth **fails closed on loopback-source proxies**
+- same-host loopback reverse proxies can still use `gateway.trustedProxies` for local-client detection and forwarded IP handling
+- for same-host loopback reverse proxies, use token/password auth instead of `gateway.auth.mode: "trusted-proxy"`
+
 ```yaml
 gateway:
   trustedProxies:
-    - "127.0.0.1" # if your proxy runs on localhost
+    - "10.0.0.1" # reverse proxy IP
   # Optional. Default false.
   # Only enable if your proxy cannot provide X-Forwarded-For.
   allowRealIpFallback: false
diff --git a/docs/install/exe-dev.md b/docs/install/exe-dev.md
index bea8c03eec9..24b7daec6dd 100644
--- a/docs/install/exe-dev.md
+++ b/docs/install/exe-dev.md
@@ -93,7 +93,7 @@ server {
         # Standard proxy headers
         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-For $remote_addr;
         proxy_set_header X-Forwarded-Proto $scheme;
 
         # Timeout settings for long-lived connections
@@ -103,6 +103,10 @@ server {
 }
 ```
 
+Overwrite forwarding headers instead of preserving client-supplied chains.
+OpenClaw trusts forwarded IP metadata only from explicitly configured proxies,
+and append-style `X-Forwarded-For` chains are treated as a hardening risk.
+
 ## 5) Access OpenClaw and grant privileges
 
 Access `https://<vm-name>.exe.xyz/` (see the Control UI output from onboarding). If it prompts for auth, paste the