Docker image and Compose setup for running OpenClaw with OpenClaw OS registered as a gateway plugin.

OpenClaw OS is served by the OpenClaw gateway itself at:

http://localhost:18789/plugins/openclawos

./scripts/init-env.sh
docker compose up -d --build

Windows PowerShell:

.\scripts\init-env.ps1
docker compose up -d --build

Wait until the gateway is healthy:

docker compose ps

The openclaw-gateway row should say healthy. First startup can take 20-60 seconds because the gateway installs/registers the OpenClaw OS plugin.

Then open the pre-authenticated OpenClaw OS URL:

macOS/Linux:

./scripts/openclaw.sh os url

Windows PowerShell:

.\scripts\openclaw.ps1 os url

Copy the printed URL into your browser. This avoids manually pasting the gateway token. The plain workspace route is http://localhost:18789/plugins/openclawos if you want to enter the gateway settings yourself.

If the browser says the page is empty or unavailable, the gateway is probably still starting or has crashed. Check:

docker compose ps
docker compose logs --tail=100 openclaw-gateway

Edit openclaw-os.yaml before starting the container:

model:
  primary: openai/gpt-5.5
  thinking: medium

apiKeys:
  openai: sk-your-key-here

You can also keep secrets in .env and reference them from YAML:

OPENAI_API_KEY=sk-your-key-here

apiKeys:
  openai: ${OPENAI_API_KEY}

The container applies openclaw-os.yaml on every start and stores API keys in OpenClaw's auth-profile store under ./data/openclaw.

# Check gateway health/status.
./scripts/openclaw.sh gateway probe

# Configure models, channels, plugins, and gateway settings.
./scripts/openclaw.sh configure

# Reinstall the OpenClaw OS plugin into the persistent OpenClaw home.
./scripts/openclaw.sh plugins install /opt/openclaw-os-plugin/node_modules/@openuidev/openclaw-os-plugin --force

Use the wrapper scripts for gateway/device commands instead of a host-installed openclaw binary. The wrapper always uses the OpenClaw CLI inside this image, so its gateway protocol matches the container. A host-installed OpenClaw CLI may be older than the Docker gateway and fail with protocol mismatch.

Defaults are pinned in .env.example:

• openclaw@2026.5.27
• @openuidev/openclaw-os-plugin@0.1.5

Change OPENCLAW_VERSION or OPENCLAW_OS_PLUGIN_VERSION, then rebuild:

docker compose build --no-cache
docker compose up -d

Compose bind-mounts state into:

• ./data/openclaw for OpenClaw config, workspace, sessions, and installed plugin state
• ./data/openclaw-auth-profile-secrets for auth-profile secret material

Keep both directories private.