OpenClaw on Docker — Quick Install

Docker setup to run OpenClaw in a Linux container, with the web dashboard reachable on your machine at http://127.0.0.1:18789 (or the host/port you configure). It works on Windows, macOS, and Linux as long as Docker and Docker Compose v2 are installed; the host OS only needs to run Docker—the container is always Linux inside.

Use PowerShell or Command Prompt on Windows, Terminal on macOS, or your usual shell on Linux. The docker compose commands below are identical on all of them.

Quick Start

1. Build and Start the Container

docker compose up -d --build

Note: Save the token generated in the console output to the .env file in the OPENCLAW_GATEWAY_TOKEN variable.

2. Run Onboarding

docker compose exec openclaw openclaw onboard

3. Restart Docker

docker compose restart openclaw

4. Message via Telegram

Send a message to the bot to start the pairing flow.

5. Approve Pairing

docker compose exec openclaw openclaw pairing approve telegram <code>

The <code> is provided in the first interaction via Telegram.

Optional: Web Dashboard

1. Configure Startup Opening

docker compose exec openclaw openclaw configure

Select the following options in each prompt: ◇ Where will the Gateway run? │ Local (this machine) │ ◇ Select sections to configure │ Gateway │ ◇ Gateway port │ 18789 │ ◇ Gateway bind mode │ LAN (All interfaces) │ ◇ Gateway auth │ Token │ ◇ Tailscale exposure │ Off

Finally you will get a token (a long alphanumeric key) that you must copy and save.

2. Restart the Container

docker compose restart

3. Enter the Dashboard

Open:

http://127.0.0.1:18789/?token=

On this first connection, the system will tell you that you are not authorized. Continue with the next step to approve your host.

4. Pair Host

First time you log in you must grant permission to the host.

docker compose exec openclaw openclaw devices list

docker compose exec openclaw openclaw devices approve <request_id>

Useful Commands

Container Management

# View status
docker compose ps

# View logs
docker compose logs -f openclaw

# Restart
docker compose restart openclaw

# Stop
docker compose stop openclaw

# Remove (⚠️ keeps data)
docker compose down

# Remove with data (⚠️)
docker compose down -v

OpenClaw Commands

# General status
docker compose exec openclaw openclaw status --all

# Health check
docker compose exec openclaw openclaw health

# Interactive configuration
docker compose exec openclaw openclaw onboard

# View web configuration
docker compose exec openclaw openclaw configure

Folder Structure

openclaw-docker/
├── Dockerfile              # Docker image
├── docker-compose.yml      # Docker Compose configuration
├── entrypoint.sh          # Entrypoint script
├── .env.example           # Example environment variables file
├── .env                   # Environment variables (create from .env.example)
├── .gitignore             # Files ignored by Git
├── openclaw-data/         # Persistent data
└── README.md              # This file

Troubleshooting

Container won't start

# View detailed logs
docker compose logs openclaw

Check that nothing else is using the gateway port (default 18789):

• Windows (PowerShell or CMD): netstat -ano | findstr "18789"
• macOS / Linux: lsof -i :18789 or ss -tlnp | grep 18789 (if ss is installed)

Dashboard not responding

# Restart the container
docker compose restart openclaw

# Check gateway-related log lines
docker compose logs openclaw 2>&1 | grep -i gateway

On Windows CMD or PowerShell, you can use findstr instead of grep:
docker compose logs openclaw 2>&1 | findstr /i gateway

Error "no auth configured"

Make sure you complete the initial onboarding and configure the corresponding provider.

Additional Documentation

• Official documentation: https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw
• Complete guide: See instructions.md file

Important Notes

⚠️ Security:

• Never expose port 18789 without authentication on the Internet
• Keep API keys out of the repository (never in the Dockerfile)
• Generate strong tokens

📝 Requirements:

• Host: Windows (Docker Desktop), macOS (Docker Desktop), or Linux (Docker Engine / Compose plugin)
• Docker Engine >= 20.10
• Docker Compose >= 2.0
• Minimum 2GB RAM available (container limit in docker-compose.yml is 2G)
• Port 18789 (or your OPENCLAW_GATEWAY_PORT) free on the host for the published mapping

Support

For additional issues, consult:

1. The logs: docker compose logs openclaw
2. The official documentation at https://docs.openclaw.ai
3. The complete instructions file at instructions.md