negodiy/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix: allow docker cli container to connect to gateway (#12504)

Browse Source 
* Docker: route CLI through gateway network namespace

* Tests: assert Docker Compose CLI namespace wiring

* Changelog: add Docker Compose CLI connectivity fix

* Docker: pin docker setup gateway mode and bind

* Tests: cover docker setup mode and bind sync

* Docs: clarify Docker LAN vs loopback gateway targeting

* Changelog: expand Docker #12504 targeting note

* Docker: default optional CLAUDE compose vars to empty

* Docs(Docker): document non-interactive compose runs

* Changelog: note docker compose env-noise reduction

* Docker: restore onboarding Tailscale guidance

* Docker: simplify onboarding output and clarify Tailscale

* Docker: harden shared-namespace CLI container

* Docs(Docker): document shared-namespace trust boundary

* Changelog: note docker shared-namespace hardening

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
This commit is contained in:
Beer van der Drift
2026-03-02 08:28:35 +07:00
committed by GitHub
parent 710004e011
commit feefedfb83
5 changed files with 90 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/install/docker.md
View File

@@ -59,6 +59,31 @@ After it finishes:
- Paste the token into the Control UI (Settings → token).
- Need the URL again? Run `docker compose run --rm openclaw-cli dashboard --no-open`.
### Automation/CI (non-interactive, no TTY noise)
For scripts and CI, disable Compose pseudo-TTY allocation with `-T`:
```bash
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
```
If your automation exports no Claude session vars, leaving them unset now resolves to
empty values by default in `docker-compose.yml` to avoid repeated "variable is not set"
warnings.
### Shared-network security note (CLI + gateway)
`openclaw-cli` uses `network_mode: "service:openclaw-gateway"` so CLI commands can
reliably reach the gateway over `127.0.0.1` in Docker.
Treat this as a shared trust boundary: loopback binding is not isolation between these two
containers. If you need stronger separation, run commands from a separate container/host
network path instead of the bundled `openclaw-cli` service.
To reduce impact if the CLI process is compromised, the compose config drops
`NET_RAW`/`NET_ADMIN` and enables `no-new-privileges` on `openclaw-cli`.
It writes config/workspace on the host:
- `~/.openclaw/`
@@ -322,9 +347,30 @@ scripts/e2e/onboard-docker.sh
pnpm test:docker:qr
```
### LAN vs loopback (Docker Compose)
`docker-setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to
`http://127.0.0.1:18789` works with Docker port publishing.
- `lan` (default): host browser + host CLI can reach the published gateway port.
- `loopback`: only processes inside the container network namespace can reach
the gateway directly; host-published port access may fail.
The setup script also pins `gateway.mode=local` after onboarding so Docker CLI
commands default to local loopback targeting.
If you see `Gateway target: ws://172.x.x.x:18789` or repeated `pairing required`
errors from Docker CLI commands, run:
```bash
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789
```
### Notes
- Gateway bind defaults to `lan` for container use.
- Gateway bind defaults to `lan` for container use (`OPENCLAW_GATEWAY_BIND`).
- Dockerfile CMD uses `--allow-unconfigured`; mounted config with `gateway.mode` not `local` will still start. Override CMD to enforce the guard.
- The gateway container is the source of truth for sessions (`~/.openclaw/agents/<agentId>/sessions/`).