This guide uses Docker Desktop for Mac to run OpenClaw, an open-source personal AI agent that communicates through messaging platforms like WhatsApp, Telegram, and Discord.
Important: OpenClaw uses file-based storage (no external database required). Configuration is stored in ~/.openclaw/openclaw.json.
For Docker Desktop installation, see Docker Desktop for Mac.
Before installing OpenClaw, ensure Docker has sufficient resources:
Create a directory for your OpenClaw configuration:
mkdir -p ~/Projects/openclaw
cd ~/Projects/openclaw
Create subdirectories for configuration and workspace:
mkdir -p config workspace
Generate secure random tokens for gateway authentication:
# Gateway token (required)
openssl rand -hex 32
# Optional: Additional secret
openssl rand -base64 32
Save these values for your .env file.
Create a .env file in your project directory:
cat > .env << EOF
# Gateway access token (use value generated above)
OPENCLAW_GATEWAY_TOKEN=your-random-token-here
# Gateway ports
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
# Bind address: "lan" for network access, "loopback" for localhost only
OPENCLAW_GATEWAY_BIND=lan
# Volume paths (Mac-specific)
OPENCLAW_CONFIG_DIR=/Users/$(whoami)/Projects/openclaw/config
OPENCLAW_WORKSPACE_DIR=/Users/$(whoami)/Projects/openclaw/workspace
# Docker image (build locally from repository)
OPENCLAW_IMAGE=openclaw:local
# For local Ollama (uncomment when using Ollama)
# OLLAMA_BASE_URL=http://host.docker.internal:11434
# MODEL_PROVIDER=ollama
# OLLAMA_MODEL=llama3.1
EOF
Note: The host.docker.internal hostname allows containers to reach services running on your Mac.
Create a docker-compose.yml file:
version: '3.8'
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-gateway
restart: unless-stopped
ports:
- "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
- "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
environment:
- HOME=/home/node
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
command: ["node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND:-lan}", "--port", "18789"]
# Uncomment when using Ollama on host
# extra_hosts:
# - "host.docker.internal:host-gateway"
openclaw-cli:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-cli
restart: unless-stopped
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
environment:
- HOME=/home/node
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
- BROWSER=echo
entrypoint: ["node", "dist/index.js"]
stdin_open: true
tty: true
Start OpenClaw in the background:
docker compose up -d
Check that containers are running:
docker compose ps
View the logs:
docker compose logs -f openclaw-gateway
On Mac, access the Web UI at:
http://localhost:18789/?token=<your-gateway-token>
To retrieve your token if needed:
docker compose run --rm openclaw-cli dashboard --no-open
If this is your first run, you’ll need to complete the onboarding process:
http://localhost:18789If you prefer to use local models instead of cloud APIs, you can run Ollama on your Mac.
# Using Homebrew
brew install ollama
# Or download from https://ollama.ai
ollama serve
ollama pull llama3.1
Or other models:
ollama pull mistral
ollama pull phi3
ollama pull codellama
Add the extra_hosts configuration to your docker-compose.yml:
openclaw-gateway:
# ... existing config ...
extra_hosts:
- "host.docker.internal:host-gateway"
During onboarding, select Ollama as your model provider and use:
Base URL: http://host.docker.internal:11434
Model: llama3.1 (or your pulled model)
softwareupdate --install-rosetta
Check if port 18789 is in use:
lsof -i :18789
Change the port in your .env file if needed:
OPENCLAW_GATEWAY_PORT=19001
Ensure your user has access to Docker volumes:
# Check directory permissions
ls -la ~/Projects/openclaw/
# Fix if needed
chmod -R 755 ~/Projects/openclaw/
If you encounter authentication issues:
OPENCLAW_GATEWAY_TOKEN is set in .envopenssl rand -hex 32
.env and restart:docker compose down
docker compose up -d
Approve the device pairing:
# List pending devices
docker compose exec openclaw-gateway node dist/index.js devices list
# Approve device
docker compose exec openclaw-gateway node dist/index.js devices approve <REQUEST_ID>
docker compose down
# Pull latest image
docker compose pull
# Restart with new image
docker compose up -d
# All services
docker compose logs -f
# Specific service
docker compose logs -f openclaw-gateway
# Standard shell
docker compose exec openclaw-gateway bash
# Root shell (for installing packages)
docker compose exec -u root openclaw-gateway bash
# Create timestamped backup
tar -czf ~/Desktop/openclaw-backup-$(date +%Y%m%d_%H%M%S).tar.gz config workspace
# Stop services
docker compose down
# Extract backup
tar -xzf ~/Desktop/openclaw-backup-YYYYMMDD_HHMMSS.tar.gz
# Restart
docker compose up -d
For temporary public access to your local OpenClaw instance:
# Install ngrok
brew install ngrok
# Expose your local OpenClaw
ngrok http 18789
config and workspace directoriesAny questions?
Feel free to contact us. Find all contact information on our contact page.