From 7678917c49d147c6f6d8dc48b4bc081c3a77f26e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 21:01:34 +0100
Subject: [PATCH] docs: refresh exposed bind auth mirrors

---
 docs/gateway/troubleshooting.md | 5 +++--
 docs/help/faq.md                | 7 ++++++-
 docs/install/fly.md             | 2 +-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index 9464caa0bc9..34a79a0c41b 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -402,6 +402,7 @@ Common signatures:
 
 ```bash
 openclaw config get gateway.bind
+openclaw config get gateway.auth.mode
 openclaw config get gateway.auth.token
 openclaw gateway status
 openclaw logs --follow
@@ -409,12 +410,12 @@ openclaw logs --follow
 
 What to check:
 
-- Non-loopback binds (`lan`, `tailnet`, `custom`) need auth configured.
+- Non-loopback binds (`lan`, `tailnet`, `custom`) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment.
 - Old keys like `gateway.token` do not replace `gateway.auth.token`.
 
 Common signatures:
 
-- `refusing to bind gateway ... without auth` → bind+auth mismatch.
+- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path.
 - `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.
 
 ### 3) Pairing and device identity state changed
diff --git a/docs/help/faq.md b/docs/help/faq.md
index a4ab116ab09..3cbf60779aa 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -1467,7 +1467,10 @@ for usage/billing and raise limits as needed.
   </Accordion>
 
   <Accordion title='I set gateway.bind: "lan" (or "tailnet") and now nothing listens / the UI says unauthorized'>
-    Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`).
+    Non-loopback binds **require a valid gateway auth path**. In practice that means:
+
+    - shared-secret auth: token or password
+    - `gateway.auth.mode: "trusted-proxy"` behind a correctly configured non-loopback identity-aware reverse proxy
 
     ```json5
     {
@@ -1485,8 +1488,10 @@ for usage/billing and raise limits as needed.
 
     - `gateway.remote.token` / `.password` do **not** enable local gateway auth by themselves.
     - Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
+    - For password auth, set `gateway.auth.mode: "password"` plus `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`) instead.
     - If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
     - Shared-secret Control UI setups authenticate via `connect.params.auth.token` or `connect.params.auth.password` (stored in app/UI settings). Identity-bearing modes such as Tailscale Serve or `trusted-proxy` use request headers instead. Avoid putting shared secrets in URLs.
+    - With `gateway.auth.mode: "trusted-proxy"`, same-host loopback reverse proxies still do **not** satisfy trusted-proxy auth. The trusted proxy must be a configured non-loopback source.
 
   </Accordion>
 
diff --git a/docs/install/fly.md b/docs/install/fly.md
index 0611fb6e4bc..dea614012b2 100644
--- a/docs/install/fly.md
+++ b/docs/install/fly.md
@@ -110,7 +110,7 @@ read_when:
 
     **Notes:**
 
-    - Non-loopback binds (`--bind lan`) require `OPENCLAW_GATEWAY_TOKEN` for security.
+    - Non-loopback binds (`--bind lan`) require a valid gateway auth path. This Fly.io example uses `OPENCLAW_GATEWAY_TOKEN`, but `gateway.auth.password` or a correctly configured non-loopback `trusted-proxy` deployment also satisfy the requirement.
     - Treat these tokens like passwords.
     - **Prefer env vars over config file** for all API keys and tokens. This keeps secrets out of `openclaw.json` where they could be accidentally exposed or logged.