vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-03-12 07:20:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(gateway): document Docker bridge networking and loopback bind caveat (#28001)

Browse Source 
* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
This commit is contained in:
Anandesh Sharma
2026-03-02 09:15:27 +05:30
committed by GitHub
parent 92199ac129
commit 61ef76edb5
4 changed files with 18 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/gateway/configuration-reference.md
View File

@@ -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)).

10
docs/install/docker.md
View File

@@ -33,6 +33,12 @@ Sandboxing details: [Sandboxing](/gateway/sandboxing)
### Quick start (recommended)
<Note>
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`.
</Note>
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: