From 61ef76edb594b7a2db66f5d2afc943683f35009f Mon Sep 17 00:00:00 2001 From: Anandesh Sharma <30695364+Anandesh-Sharma@users.noreply.github.com> Date: Mon, 2 Mar 2026 09:15:27 +0530 Subject: [PATCH] docs(gateway): document Docker bridge networking and loopback bind caveat (#28001) * docs(gateway): document Docker bridge networking and loopback bind caveat The default loopback bind makes the gateway unreachable with Docker bridge networking because port-forwarded traffic arrives on eth0, not lo. Add a note in both the Dockerfile and the configuration reference explaining the workarounds (--network host or bind: lan). Fixes #27950 Co-Authored-By: Claude Opus 4.6 * docs(docker): note legacy gateway.bind alias migration * docs(gateway): clarify legacy bind alias auto-migration * docs(docker): require bind mode values in gateway.bind * docs(gateway): avoid bind alias auto-migration claim * changelog: add #28001 docker bind docs credit --------- Co-authored-by: Claude Opus 4.6 Co-authored-by: Vincent Koc --- CHANGELOG.md | 1 + Dockerfile | 5 +++++ docs/gateway/configuration-reference.md | 2 ++ docs/install/docker.md | 10 ++++++++++ 4 files changed, 18 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index af780acc773..f0b3114d11d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -144,6 +144,7 @@ Docs: https://docs.openclaw.ai - Auto-reply/Block reply timeout path: normalize `onBlockReply(...)` execution through `Promise.resolve(...)` before timeout wrapping so mixed sync/async callbacks keep deterministic timeout behavior across strict TypeScript build paths. (#19779) Thanks @dalefrieswthat and @vincentkoc. - Cron/One-shot reschedule re-arm: allow completed `at` jobs to run again when rescheduled to a later time than `lastRunAtMs`, while keeping completed non-rescheduled one-shot jobs inactive. (#28915) Thanks @Glucksberg. - Docs/Docker images: clarify the official GHCR image source and tag guidance (`main`, `latest`, ``), and document that `OPENCLAW_IMAGE` skips local image builds but still uses the repo-local compose/setup flow. (#27214, #31180) Fixes #15655. Thanks @ipl31. +- Docs/Gateway Docker bind guidance: clarify bridge-network loopback behavior and require bind mode values (`auto`/`loopback`/`lan`/`tailnet`/`custom`) instead of host aliases in `gateway.bind`. (#28001) Thanks @Anandesh-Sharma and @vincentkoc. - Docker/Image base annotations: add OCI labels for base image plus source/documentation/license metadata, include revision/version/created labels in Docker release builds, and document annotation keys/release context in install docs. Fixes #27945. Thanks @vincentkoc. - Agents/Model fallback: classify additional network transport errors (`ECONNREFUSED`, `ENETUNREACH`, `EHOSTUNREACH`, `ENETRESET`, `EAI_AGAIN`) as failover-worthy so fallback chains advance when primary providers are unreachable. Landed from contributor PR #19077 by @ayanesakura. Thanks @ayanesakura. - Agents/Copilot token refresh: refresh GitHub Copilot runtime API tokens after auth-expiry failures and re-run with the renewed token so long-running embedded/subagent turns do not fail on mid-session 401 expiry. Landed from contributor PR #8805 by @Arthur742Ramos. Thanks @Arthur742Ramos. diff --git a/Dockerfile b/Dockerfile index 3ba413c70d9..4bddcaf8f21 100644 --- a/Dockerfile +++ b/Dockerfile @@ -87,6 +87,11 @@ USER node # Start gateway server with default config. # Binds to loopback (127.0.0.1) by default for security. # +# IMPORTANT: With Docker bridge networking (-p 18789:18789), loopback bind +# makes the gateway unreachable from the host. Either: +# - Use --network host, OR +# - Override --bind to "lan" (0.0.0.0) and set auth credentials +# # For container platforms requiring external health checks: # 1. Set OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD env var # 2. Override CMD: ["node","openclaw.mjs","gateway","--allow-unconfigured","--bind","lan"] diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 00ef71c2d5f..f37ddf49caa 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -2292,6 +2292,8 @@ See [Plugins](/tools/plugin). - `mode`: `local` (run gateway) or `remote` (connect to remote gateway). Gateway refuses to start unless `local`. - `port`: single multiplexed port for WS + HTTP. Precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (Tailscale IP only), or `custom`. +- **Legacy bind aliases**: use bind mode values in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), not host aliases (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Docker note**: the default `loopback` bind listens on `127.0.0.1` inside the container. With Docker bridge networking (`-p 18789:18789`), traffic arrives on `eth0`, so the gateway is unreachable. Use `--network host`, or set `bind: "lan"` (or `bind: "custom"` with `customBindHost: "0.0.0.0"`) to listen on all interfaces. - **Auth**: required by default. Non-loopback binds require a shared token/password. Onboarding wizard generates a token by default. - `gateway.auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts. - `gateway.auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). diff --git a/docs/install/docker.md b/docs/install/docker.md index 8a40d041338..3ba7b766fbb 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -33,6 +33,12 @@ Sandboxing details: [Sandboxing](/gateway/sandboxing) ### Quick start (recommended) + +Docker defaults here assume bind modes (`lan`/`loopback`), not host aliases. Use bind +mode values in `gateway.bind` (for example `lan` or `loopback`), not host aliases like +`0.0.0.0` or `localhost`. + + From repo root: ```bash @@ -416,6 +422,10 @@ pnpm test:docker:qr The setup script also pins `gateway.mode=local` after onboarding so Docker CLI commands default to local loopback targeting. +Legacy config note: use bind mode values in `gateway.bind` (`lan` / `loopback` / +`custom` / `tailnet` / `auto`), not host aliases (`0.0.0.0`, `127.0.0.1`, +`localhost`, `::`, `::1`). + If you see `Gateway target: ws://172.x.x.x:18789` or repeated `pairing required` errors from Docker CLI commands, run: