Summary

The manual Docker setup documented at https://docs.openclaw.ai/install/docker fails with multiple issues that prevent the CLI from connecting to the gateway and the web UI from working properly.

Steps to reproduce

1. Follow the manual Docker setup instructions at https://docs.openclaw.ai/install/docker
2. Run docker compose up -d openclaw-gateway
3. Run docker compose run --rm openclaw-cli status
4. Observe: Gateway unreachable (connect failed: connect ECONNREFUSED 127.0.0.1:18789)

Root cause

The docker-compose.yml file has the openclaw-cli and openclaw-gateway services in separate containers. Both share the same config volume which has gateway.mode=local and gateway.bind=loopback. This causes the CLI to try connecting to 127.0.0.1:18789, which is the CLI container's own loopback interface, not the gateway container.

Expected behavior

The CLI should be able to communicate with the gateway container out of the box.

Actual behavior

• CLI cannot connect to gateway: connect ECONNREFUSED 127.0.0.1:18789
• Web UI shows repeated unauthorized and closed before connect errors in gateway logs
• Manual workarounds required to make it work

Additional issues encountered

1. Token mismatch: The onboarding process creates a token in openclaw.json that differs from OPENCLAW_GATEWAY_TOKEN in .env, causing authentication failures
2. Permissions issues: Files created during onboarding are owned by the wrong user, requiring manual sudo chown -R 1000:1000 ~/.openclaw (related to [Bug]: "plugin not found" error due to EACCES permission issues in Docker image #5450)
3. Web UI pairing: Even after fixing connectivity and token, web UI requires manual device pairing approval via CLI (which is blocked by issue fix: add @lid format support and allowFrom wildcard handling #1)

Workaround

Add network_mode: "service:openclaw-gateway" to the openclaw-cli service in docker-compose.yml:

  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      # ... existing env vars ...
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    network_mode: "service:openclaw-gateway"  # <- ADD THIS LINE
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]

Suggested fixes

1. Update docker-compose.yml with the network_mode fix
2. Ensure onboarding flow synchronizes the gateway token between .env and openclaw.json
3. Improve documentation about device pairing requirements for web UI
4. Consider auto-pairing the web UI when using the tokenized dashboard URL

Environment

• OS: Linux 5.15.0-161-generic (x64)
• Docker Compose: v2
• OpenClaw version: 2026.1.29

Related issues

• [Bug]: "plugin not found" error due to EACCES permission issues in Docker image #5450 (permissions issues)
• Dashboard "pairing required" (1008) when running gateway in Docker Desktop on Windows #4941 (pairing required in Docker)
• [Feature]: improve Docker setup #2178 (improve Docker setup)