Should I use Docker for OpenClaw?

While it is a supported method, many users report success with native Linux installs or QEMU VMs due to ongoing networking complexities in containerized setups.

What is the token issue mentioned?

Users often encounter authentication failures alongside network errors. Always generate your token in advance and ensure it matches across your CLI and Gateway config files.

Can I bind the gateway to 127.0.0.1?

No. When using containers, binding to 127.0.0.1 inside the gateway container makes it inaccessible to other containers. You should bind to 0.0.0.0 if you are not sharing the network namespace.

Resolving Gateway Unreachable (ECONNREFUSED) in OpenClaw Docker

TL;DR — Quick Fix

The CLI is looking for the gateway on its own loopback instead of the container network; fix this by using network_mode: service:openclaw-gateway or adjusting your bind configuration.

Run Diagnostics

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Error Signal

Gateway unreachable (connect failed: connect ECONNREFUSED 127.0.0.1:18789)

What's Happening

You're running into a connection failure when using OpenClaw inside Docker. The CLI container attempts to reach the gateway via 127.0.0.1:18789, but because the services are containerized, the loopback address refers to the CLI container itself, not the gateway. This causes the 'Gateway unreachable' error.

The Fix

The most robust fix currently involves updating your docker-compose.yml to ensure the CLI container shares the network namespace with the gateway. Add the following configuration to your openclaw-cli service:

services:
  openclaw-cli:
    network_mode: "service:openclaw-gateway"
    depends_on:
      - openclaw-gateway

Alternatively, you may need to ensure your gateway is bound to the LAN interface rather than loopback. Check your shared configuration volume for gateway.bind and set it to 0.0.0.0 or your container's internal IP if you aren't using the network_mode fix.

Why This Occurs

By default, Docker Compose isolates network namespaces. When the CLI loads its configuration from the shared volume, it reads gateway.bind=loopback. Since it operates in its own container, it blindly tries to connect to its own local loopback address. It has no visibility into the gateway container's services on that port unless the network stack is unified or the gateway is explicitly bound to a reachable interface.

Prevention

If you find the Docker setup consistently fragile, many developers in the community are currently opting for native installs or dedicated QEMU VMs to avoid these networking limitations. If you stick with Docker, ensure your OPENCLAW_GATEWAY_TOKEN is exported correctly using export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32) before running your setup, as mismatched tokens are a common secondary issue when the connection finally succeeds.

Last Updated: April 2026

Did this guide solve your problem?