Fix Docker Errors on macOS

Running OpenClaw in Docker on macOS can trigger path and permission errors because the container (Linux) doesn't have your macOS filesystem. This guide walks through every common failure and its fix.

Why This Happens

When OpenClaw runs inside a Docker container, it's running on a minimal Linux environment — not macOS. If your config references macOS paths like /Users/yourname/..., the container tries to create those directories inside Linux and fails with EACCES. This is the #1 Docker issue on macOS.

Error 1: EACCES Permission Denied

Cause

Your clawhub.json or environment variables contain macOS-specific paths (like /Users/yourname/project). The container can't create these paths because /Users doesn't exist in Linux and requires root permissions to create at the filesystem root.

Fix

Use relative paths or container-appropriate paths in your config. If you need to share files between host and container, use Docker volumes:

services:
  openclaw:
    volumes:
      - ./workspace:/app/workspace    # Map host folder into container
    environment:
      - WORKSPACE_DIR=/app/workspace  # Use container path in config

Error 2: Token Mismatch / Connection Refused

Cause

Docker containers have their own network namespace. When the OpenClaw server inside Docker listens on 127.0.0.1, it's listening on the container's localhost — not your Mac's. If you're using Docker Compose with multiple services, they need to reference each other by service name, not localhost.

Fix

services:
  openclaw:
    environment:
      - HOST=0.0.0.0           # Listen on all interfaces inside container
      - BROWSER_WS=ws://browser:3000  # Reference other service by name

  browser:
    image: browserless/chrome
    ports:
      - "3000:3000"

Error 3: Chrome / Browser Not Found

Cause

The base Docker image doesn't include Chrome or Chromium. On macOS, OpenClaw uses your locally installed Chrome, but inside Docker there's no browser available.

Option A: Use a Separate Browser Service

Run a headless browser as a separate Docker service (recommended for production):

services:
  openclaw:
    environment:
      - BROWSER_WS=ws://browser:3000

  browser:
    image: browserless/chrome
    environment:
      - CONNECTION_TIMEOUT=600000

Option B: Install Chromium in the OpenClaw Image

Build a custom Dockerfile that includes Chromium (simpler for development):

FROM openclaw/openclaw:latest

# Install Chromium and dependencies
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    libnss3 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libxcomposite1 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

ENV CHROME_PATH=/usr/bin/chromium
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

Then build and run:

docker build -t openclaw-with-chrome .
docker run -it openclaw-with-chrome

Error 4: No-Extension Mode Issues

If you want to run OpenClaw without the browser extension (headless mode), ensure your config explicitly disables the extension requirement:

{
  "browser": {
    "mode": "headless",
    "executablePath": "/usr/bin/chromium",
    "args": [
      "--no-sandbox",
      "--disable-gpu",
      "--disable-dev-shm-usage"
    ]
  }
}

Complete Working Example

Here's a full docker-compose.yml that avoids all the errors above:

version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "8080:8080"
    volumes:
      - ./workspace:/app/workspace
      - ./clawhub.json:/app/clawhub.json
    environment:
      - HOST=0.0.0.0
      - BROWSER_WS=ws://browser:3000
      - WORKSPACE_DIR=/app/workspace
    depends_on:
      - browser

  browser:
    image: browserless/chrome
    ports:
      - "3000:3000"
    environment:
      - CONNECTION_TIMEOUT=600000
      - MAX_CONCURRENT_SESSIONS=5

Quick Checklist

Still Stuck?

Run our diagnostic tool to catch configuration issues automatically:

npx clawkit-doctor@latest