From 8c1b1feaad71f930a5d6469b122b19ba4626e313 Mon Sep 17 00:00:00 2001
From: Sakurapainting <you2899047197@163.com>
Date: Thu, 2 Apr 2026 18:02:46 +0800
Subject: [PATCH] docs(gateway): document fallback behavior and allowed CIDRs

---
 README.md             |  2 +-
 docs/configuration.md | 33 +++++++++++++++++++++++++++++++++
 docs/docker.md        |  3 +++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d73348554..04ff8fa1e 100644
--- a/README.md
+++ b/README.md
@@ -242,7 +242,7 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
 # Open http://localhost:18800
 ```
 
-> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host.
+> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host. If loopback bind fails at runtime, PicoClaw may fallback to `0.0.0.0` with CIDR restrictions; configure `gateway.allowed_cidrs` to keep exposure limited.
 
 ```bash
 # Check logs
diff --git a/docs/configuration.md b/docs/configuration.md
index 7a5902f58..72f6bfdbc 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -49,6 +49,39 @@ When omitted, the default is `warn`. Supported values: `debug`, `info`, `warn`,
 
 You can also override this with the environment variable `PICOCLAW_LOG_LEVEL`.
 
+### Gateway Host Fallback And CIDR Allowlist
+
+`gateway.host` defaults to `127.0.0.1`.
+
+When `gateway.host` is a loopback address (`127.0.0.1`, `::1`, or `localhost`) and bind fails (for example, on boards where loopback is unavailable), PicoClaw automatically:
+
+1. Scans non-loopback network interfaces and collects local CIDR ranges.
+2. Falls back to bind on `0.0.0.0`.
+3. Enforces a CIDR allowlist for gateway HTTP endpoints.
+
+CIDR sources in fallback mode:
+
+- If `gateway.allowed_cidrs` is configured, that list is used.
+- If `gateway.allowed_cidrs` is empty, discovered local CIDRs are used.
+- If no non-loopback CIDR can be discovered, gateway startup fails.
+
+Loopback clients are always allowed for local administration.
+
+Example:
+
+```json
+{
+  "gateway": {
+    "host": "127.0.0.1",
+    "port": 18790,
+    "allowed_cidrs": [
+      "192.168.1.0/24",
+      "10.0.0.0/8"
+    ]
+  }
+}
+```
+
 ### Workspace Layout
 
 PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
diff --git a/docs/docker.md b/docs/docker.md
index 6c32879a6..16c9e89f2 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -26,6 +26,9 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 > [!TIP]
 > **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
 
+> [!TIP]
+> If `gateway.host` is loopback and bind fails at runtime (for example, loopback unavailable on some boards), PicoClaw will fallback to `0.0.0.0` and enforce CIDR restrictions. Configure `gateway.allowed_cidrs` to keep exposure limited to trusted networks.
+
 > [!NOTE]
 > The `gateway` profile only serves the webhook handlers (including Pico when enabled) and health endpoints on the gateway port, so it does not expose generic REST chat endpoints such as `/chat` or `/a2a`. Launcher mode adds the browser UI plus `/api/pico/token` and a `/pico/ws` proxy on the launcher port, but `/pico/ws` is also available directly on the gateway whenever the Pico channel is enabled.