This guide uses Docker Compose 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 installation, see Docker.
OpenClaw provides Dockerfiles in the repository for building images locally. The GitHub repository shows no official pre-built images published at ghcr.io, so you’ll need to build from source.
Note: Community-maintained Docker images may exist, but for production deployments, building from source using the provided Dockerfiles is recommended.
mkdir -p /opt/openclaw
cd /opt/openclaw
mkdir -p config workspace
Create a secure random token for gateway authentication:
openssl rand -hex 32
Save this token for later use.
Create a .env file:
cat > .env << EOF
# Gateway access token (use the value generated above)
OPENCLAW_GATEWAY_TOKEN=your-random-token-here
# Gateway port (default: 18789)
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
# Bind address: "lan" for all interfaces, "loopback" for localhost only
OPENCLAW_GATEWAY_BIND=lan
# Volume paths
OPENCLAW_CONFIG_DIR=/opt/openclaw/config
OPENCLAW_WORKSPACE_DIR=/opt/openclaw/workspace
# Docker image (build locally from repository)
OPENCLAW_IMAGE=openclaw:local
EOF
version: '3.8'
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-gateway
build:
context: .
dockerfile: Dockerfile
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"]
openclaw-cli:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-cli
build:
context: .
dockerfile: Dockerfile
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
docker compose up -d
Alternatively, clone the repository and use the included Docker setup script:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
The official repository includes an automated Docker setup script:
./docker-setup.sh
This script:
openclaw:local)Note: For production deployments, building from source using the provided Dockerfiles (Method 1) is recommended.
Follow the interactive onboarding prompts to configure:
Open your browser and navigate to:
http://localhost:18789
For complete control over your deployment, you can manually create the Docker Compose configuration. See Method 1 for the complete manual setup steps.
OpenClaw provides Dockerfiles in the repository for building images locally. This is the recommended approach for production deployments.
| Image | Tag | Description |
|---|---|---|
openclaw:local |
- | Build locally from source (recommended) |
# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# Build the Docker image
docker build -t openclaw:local .
Update your .env file:
OPENCLAW_IMAGE=openclaw:local
Note: The GitHub repository shows “PACKAGES 0” - there are no official pre-built Docker images published at ghcr.io/openclaw/openclaw. Community-maintained images may exist but are not officially supported. For production deployments, building from source is recommended.
---
## Configuration
### Configuration File
OpenClaw stores configuration in the mounted config volume:
/opt/openclaw/config/openclaw.json # (or your configured path)
This corresponds to `~/.openclaw/openclaw.json` inside the container.
### Key Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `OPENCLAW_GATEWAY_TOKEN` | (required) | Access token for Web UI authentication |
| `OPENCLAW_GATEWAY_PORT` | `18789` | Gateway HTTP/WebSocket port |
| `OPENCLAW_BRIDGE_PORT` | `18790` | Bridge port for internal communication |
| `OPENCLAW_GATEWAY_BIND` | `lan` | Bind address (`lan` = 0.0.0.0, `loopback` = 127.0.0.1) |
| `OPENCLAW_IMAGE` | `openclaw:local` | Docker image to use (build from source) |
### Volume Mounts
| Host Path | Container Path | Purpose |
|-----------|----------------|---------|
| `${OPENCLAW_CONFIG_DIR}` | `/home/node/.openclaw` | Configuration and credentials |
| `${OPENCLAW_WORKSPACE_DIR}` | `/home/node/.openclaw/workspace` | Agent workspace files |
---
## Useful Commands
### Container Management
```bash
# Start services
docker compose up -d
# Stop services
docker compose down
# Restart services
docker compose restart
# View logs
docker compose logs -f
# View logs for specific service
docker compose logs -f openclaw-gateway
# Check gateway status
docker compose run --rm openclaw-cli status
# Get dashboard URL with token
docker compose run --rm openclaw-cli dashboard --no-open
# List pending device pairings
docker compose exec openclaw-gateway node dist/index.js devices list
# Approve a device pairing
docker compose exec openclaw-gateway node dist/index.js devices approve <REQUEST_ID>
# Access shell inside gateway container
docker compose exec openclaw-gateway bash
# Access shell as root (for installing packages)
docker compose exec -u root openclaw-gateway bash
If you need to install additional packages inside the container:
docker compose exec -u root openclaw-gateway apt-get update
docker compose exec -u root openclaw-gateway apt-get install -y <package-name>
To use Ollama running on your host machine:
Add to your .env file:
# Enable host networking for Ollama access
OLLAMA_BASE_URL=http://host.docker.internal:11434
Add the extra_hosts configuration:
openclaw-gateway:
# ... existing config ...
extra_hosts:
- "host.docker.internal:host-gateway"
During onboarding, select Ollama as your model provider and use the base URL:
http://host.docker.internal:11434
# Check logs
docker compose logs openclaw-gateway
# Verify port is not in use
sudo lsof -i :18789
# Check volume permissions
ls -la /opt/openclaw/config
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>
Change the gateway port in your .env file:
OPENCLAW_GATEWAY_PORT=19001
Then restart:
docker compose down
docker compose up -d
# Stop services
docker compose down
# Backup configuration
mv config config.backup
# Restart (will trigger fresh onboarding)
docker compose up -d
# Pull latest image
docker compose pull
# Restart with new image
docker compose up -d
# Rebuild image
docker compose build
# Restart
docker compose up -d
# Create timestamped backup
tar -czf openclaw-backup-$(date +%Y%m%d_%H%M%S).tar.gz config workspace
# Extract backup
tar -xzf openclaw-backup-YYYYMMDD_HHMMSS.tar.gz
OPENCLAW_GATEWAY_TOKEN securelyOPENCLAW_GATEWAY_BIND=loopback) for local-only accessFor detailed security guidance, see OpenClaw Security.
~/.openclaw directory (mapped to your config volume)Deploying Openclaw in containers for production? Our consulting covers:
Get expert help: office@linux-server-admin.com | Contact Page