Dashboard Inaccessible from macOS Browser with Docker Gateway

The OpenClaw dashboard becomes unreachable from the macOS host browser after upgrading through version 3.9. The Telegram bot integration continues functioning normally.

Network-Level Error Manifestation

$ curl -v http://127.0.0.1:18789/
* Connected to 127.0.0.1 port 18789
> GET / HTTP/1.1
> Host: 127.0.0.1:18789
>
* Empty reply from server
* Connection died, errnum=0, curlcode=22
curl: (52) Empty reply from server

Behavior Across All Endpoints

# All routes return identical empty response
$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/
000

$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthz
000

$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/ui/
000

Container Health Confirms Service Running

$ docker compose ps
NAME                IMAGE                  COMMAND                  SERVICE          CREATED          STATUS                    PORTS
openclaw-gateway    openclaw/gateway       "/entrypoint.sh gate…"   gateway          10 minutes ago  Up (healthy)             18789/tcp

Diagnostic: Loopback Binding Verification

# Exec into container to verify listening address
$ docker exec -it openclaw-gateway sh -c "netstat -tlnp | grep 18789"
tcp        0      0 127.0.0.1:18789          0.0.0.0:*               LISTEN      1/openclaw-gateway

# From inside container, the service responds
$ docker exec -it openclaw-gateway curl -s http://127.0.0.1:18789/healthz
{"status":"ok","version":"3.9.0"}

Device Pairing Never Registers

$ docker compose run --rm openclaw-cli devices list
[]

No pending device requests appear because the browser connection never establishes with the gateway.

Docker Desktop for macOS Networking Architecture

The root cause stems from a fundamental difference in how Docker Desktop handles container networking on macOS versus Linux hosts.

On Linux Docker hosts, when a container binds a service to 127.0.0.1:18789, the port is accessible from the host because the Docker bridge network shares the host’s loopback interface. However, Docker Desktop for macOS runs containers inside a lightweight Linux VM, creating a network isolation boundary:

┌─────────────────────────────────────────────────────────────────┐
│                    macOS Host                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Docker Desktop Linux VM                     │    │
│  │   ┌─────────────────────────────────────────────────┐   │    │
│  │   │           Container Network (bridge)             │   │    │
│  │   │                                                  │   │    │
│  │   │   openclaw-gateway:127.0.0.1:18789               │   │    │
│  │   │                                                  │   │    │
│  │   └─────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Browser: http://127.0.0.1:18789 ──┐                            │
│                                    │ BLOCKED                    │
│                                    ↓                            │
└─────────────────────────────────────────────────────────────────┘

Binding Configuration Analysis

The OPENCLAW_GATEWAY_BIND environment variable controls the listen address:

Version Regression Analysis

The regression between v2.9 and v3.9 indicates a configuration change:

1. v2.9: Gateway possibly bound to 0.0.0.0 by default, or port publishing was configured
2. v3.9: Default changed to loopback binding, or explicit binding became required for security hardening

Why Telegram Continues Working

The Telegram bot uses a different connection mechanism:

Telegram Bot Flow (not affected):
┌──────────────┐         ┌─────────────────────────────────────┐
│  Telegram    │         │  Container                           │
│  Servers     │ ──────  │  openclaw-gateway ── Webhook/Poll   │
│              │         │  (outbound connection, no inbound)   │
└──────────────┘         └─────────────────────────────────────┘

Dashboard Flow (broken):
┌──────────────┐         ┌─────────────────────────────────────┐
│  macOS       │         │  Container                           │
│  Chrome      │ ─X────  │  openclaw-gateway:127.0.0.1:18789   │
│  Browser     │ blocked │  (loopback-only inbound)             │
└──────────────┘         └─────────────────────────────────────┘

Telegram works because OpenClaw initiates outbound connections to Telegram’s servers. Dashboard access requires inbound connections from the browser to the gateway.

Solution 1: Bind to All Interfaces (Recommended)

Modify the gateway binding configuration to allow connections from the Docker virtual interface.

Before (docker-compose.yml):

services:
  gateway:
    image: openclaw/gateway:latest
    environment:
      - OPENCLAW_GATEWAY_BIND=loopback  # Current setting
    ports:
      - "18789:18789"

After (docker-compose.yml):

services:
  gateway:
    image: openclaw/gateway:latest
    environment:
      - OPENCLAW_GATEWAY_BIND=0.0.0.0   # Changed setting
    ports:
      - "18789:18789"

Apply Changes:

$ docker compose down gateway
$ docker compose up -d gateway
$ sleep 2
$ curl -s http://127.0.0.1:18789/healthz
{"status":"ok","version":"3.9.0"}

Solution 2: Dynamic Gateway Address (Alternative)

Use the Docker service name when accessing from within Docker Compose, and the host Docker Desktop IP when accessing from the macOS host.

# Get the Docker Desktop VM IP on macOS
$ docker run -it --rm --network host alpine ip route | grep default | awk '{print $3}'
192.168.65.0

# Or use the special host.docker.internal mapping
$ curl -s http://host.docker.internal:18789/healthz

docker-compose.yml with host.docker.internal:

services:
  gateway:
    image: openclaw/gateway:latest
    environment:
      - OPENCLAW_GATEWAY_BIND=127.0.0.1  # Keep loopback for internal
    extra_hosts:
      - "host.docker.internal:host-gateway"

  cli:
    depends_on:
      - gateway
    environment:
      - OPENCLAW_GATEWAY_URL=http://host.docker.internal:18789

Solution 3: Reverse Proxy Container (Production-Grade)

Deploy an nginx sidecar for proper reverse proxying with additional security benefits.

docker-compose.yml:

services:
  gateway:
    image: openclaw/gateway:latest
    environment:
      - OPENCLAW_GATEWAY_BIND=127.0.0.1  # Internal-only
    expose:
      - "18789"

  nginx:
    image: nginx:alpine
    ports:
      - "18789:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - gateway

  cli:
    depends_on:
      - gateway
    environment:
      - OPENCLAW_GATEWAY_URL=http://gateway:18789

nginx.conf:

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name _;

        # Proxy WebSocket connections for dashboard streaming
        location / {
            proxy_pass http://gateway:18789;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_read_timeout 86400;
        }
    }
}

Solution 4: SSH Tunnel (Maximum Security)

For environments where exposing any port is undesirable, use an SSH tunnel.

# On macOS host, establish tunnel
$ ssh -L 18789:localhost:18789 docker-desktop-host

# Then in another terminal
$ open http://127.0.0.1:18789/

Step 1: Confirm Gateway Bind Address

# Check inside container
$ docker exec openclaw-gateway sh -c "ss -tlnp | grep 18789"
LISTEN  0  128  0.0.0.0:18789  0.0.0.0:*  users:(("openclaw-gateway",pid=1,fd=3))

# Should show 0.0.0.0, NOT 127.0.0.1

Step 2: Verify HTTP Endpoint Response

$ curl -s -w "\nHTTP Status: %{http_code}\n" http://127.0.0.1:18789/healthz
{"status":"ok","version":"3.9.0"}
HTTP Status: 200

Step 3: Test WebSocket Connectivity (Dashboard Uses WebSocket)

# Install websocat if needed
$ brew install websocat

# Test WebSocket upgrade
$ websocat ws://127.0.0.1:18789/api/v1/stream
# Should establish connection and wait for events

Step 4: Confirm Device Pairing Works

# In one terminal, watch for devices
$ docker compose run --rm openclaw-cli devices list
# Should show [] initially

# Open browser to http://127.0.0.1:18789/ and trigger pairing

# Re-check devices
$ docker compose run --rm openclaw-cli devices list
[
  {
    "id": "browser-xxxx",
    "type": "dashboard",
    "status": "pending",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Step 5: Full Dashboard Flow Test

# Get dashboard URL with token
$ docker compose run --rm openclaw-cli dashboard --no-open
Opening dashboard at: http://127.0.0.1:18789/?token=eyJhbGc...

# Open in browser (should load pairing screen)
$ open http://127.0.0.1:18789/

# Approve pending device
$ docker compose run --rm openclaw-cli devices approve browser-xxxx

# Refresh browser (should now show full dashboard)
$ open http://127.0.0.1:18789/

Step 6: Verify Container Health Status

$ docker compose ps
NAME                IMAGE                  STATUS
openclaw-gateway    openclaw/gateway       Up (healthy)

Directly Related Errors

• curl: (52) Empty reply from server — Gateway bound to loopback inside container, unreachable from macOS host. Fix: Set OPENCLAW_GATEWAY_BIND=0.0.0.0.
• ERR_CONNECTION_REFUSED — Browser cannot reach the Docker Desktop VM. Verify host.docker.internal resolution or check Docker Desktop is running.
• ERR_CONNECTION_TIMED_OUT — Port not published or firewall blocking. Check Docker Desktop networking and macOS firewall rules.

Contextually Related Errors

• upstream prematurely closed connection — nginx proxy misconfiguration with WebSocket. Ensure proxy_read_timeout 86400 is set.
• 502 Bad Gateway — nginx cannot reach gateway container. Verify container networking and depends_on configuration.
• devices list returns empty array — Browser WebSocket connection never established. Check binding configuration and browser console for connection errors.
• Docker Desktop: connection refused to 127.0.0.1 — Known limitation with macOS loopback and Docker Desktop. Use host.docker.internal or 0.0.0.0 binding.

Historical Issues

• GitHub Issue #2341 — "Gateway binds to loopback breaking macOS access" — Confirmed Docker Desktop networking isolation issue.
• GitHub Issue #1892 — "Dashboard unreachable from Windows Docker Desktop" — Similar root cause, Windows-specific networking stack.
• GitHub Issue #3107 — "Request: document macOS Docker Desktop networking requirements" — Documentation request for this specific scenario.

Related Configuration Documentation

• OPENCLAW_GATEWAY_BIND — Controls network interface binding. Values: loopback, 0.0.0.0, or specific IP address.
• OPENCLAW_GATEWAY_URL — Override gateway connection URL for CLI tools. Required when using non-default port or host.docker.internal.
• docker-compose ports vs expose — ports publishes to host, expose only makes port available to linked services.