Documentation

Run OpenClaw and the runtime in Docker

Use the clawcontrol-openclaw-docker example project to run a self-managed OpenClaw plus ClawControl runtime stack in Docker.

Who this is for

Use this guide if you want to run your own OpenClaw gateway and ClawControl runtime on a Docker host you manage. If you want ClawControl to operate the host for you, use managed instances instead.

This guide uses the example project for the Docker stack:

claw-control/clawcontrol-openclaw-docker

The stack starts:

an OpenClaw gateway container
an OpenClaw CLI helper container for onboarding and approval commands
a runtime container built from the published @clawcontrol/runtime npm package

Before you start

Make sure the Docker host has:

Docker Engine with the Docker Compose v2 plugin
enough disk space for container images plus persistent OpenClaw and runtime state
a ClawControl workspace where you can create a pairing code

1. Clone the example project

Clone the repo, then move into the project directory:

git clone https://github.com/claw-control/clawcontrol-openclaw-docker.git
cd clawcontrol-openclaw-docker

2. Create the local env file

cp .env.example .env

At minimum, review these values in .env:

Variable	What it controls
`OPENCLAW_IMAGE`	The OpenClaw image tag or digest used for the gateway and helper CLI
`OPENCLAW_GATEWAY_TOKEN`	Bootstrap token the runtime uses to reach the local gateway
`CLAWCONTROL_RUNTIME_NPM_SPEC`	Published runtime version or dist-tag baked into the runtime image
`OPENCLAW_GATEWAY_PORT`	Host port mapped to the gateway WebSocket and health endpoint
`OPENCLAW_BROWSER_UI_PORT`	Host port mapped to the OpenClaw browser UI

Version pinning

CLAWCONTROL_RUNTIME_NPM_SPEC=latest is convenient for testing, but an exact version such as 0.2.7 is better when you want repeatable installs.

3. Build and start the stack

./stack.sh up --build

This command:

pulls the configured OPENCLAW_IMAGE
builds a runtime image that installs @clawcontrol/runtime@${CLAWCONTROL_RUNTIME_NPM_SPEC}
starts the OpenClaw gateway and runtime containers

4. Onboard OpenClaw on first run

If this is a fresh state/openclaw directory, run:

./stack.sh onboard

If the gateway reports pending device approvals during onboarding, approve them:

./stack.sh approve-pending

5. Pair the runtime to ClawControl

Create a pairing code in ClawControl

In the ClawControl app, open the runtimes area and generate a pairing code for this Docker host.

Run pair inside the runtime container

Use the helper to run the runtime CLI in the container:

./stack.sh pair <PAIRING_CODE> --name "Docker Runtime"

If OpenClaw asks for approval again after pairing, run:

./stack.sh approve-pending

6. Verify the stack

Check container status:

./stack.sh ps

Check runtime status:

./stack.sh runtime runtime status

Tail logs:

./stack.sh logs runtime

Default host endpoints:

OpenClaw browser UI: http://127.0.0.1:18801
OpenClaw gateway: ws://127.0.0.1:18799

Persistent data

By default, the repo stores data next to the stack files:

state/openclaw for OpenClaw state
state/runtime for runtime config and state
workspace for the mounted OpenClaw workspace

If you want those paths somewhere else, set OPENCLAW_STATE_DIR, OPENCLAW_WORKSPACE_DIR, or RUNTIME_STATE_DIR in .env before starting the stack.

Day-2 commands

./stack.sh logs
./stack.sh restart --build
./stack.sh pull-openclaw
./stack.sh shell-openclaw
./stack.sh shell-runtime
./stack.sh runtime runtime logs --follow
./stack.sh down

When to use this guide vs other runtime docs

Use this guide when you want OpenClaw and the runtime to live together on a Docker host you manage.
Use Install and connect a runtime when OpenClaw already exists on the host and you want to install the runtime directly from npm.
Use managed instances when you do not want to operate the host yourself.