Documentation

Install and connect a runtime

Install the ClawControl runtime from npm, pair it to your workspace, and verify that the host is ready.

Recommended path

Use clawcontrol runtime onboard for the first setup. It walks you through pairing, link validation or repair, gateway approval checks, and service startup in one guided flow.

Running OpenClaw in Docker?

If you want to run both OpenClaw and the ClawControl runtime on the same Docker host, use Run OpenClaw and the runtime in Docker.

Before you start

Make sure the host machine already has:

Node.js 20 or later
an OpenClaw environment installed
access to the OpenClaw gateway
a gateway bootstrap token for first-time connection
at least one local OpenClaw auth profile if you want the runtime to reuse existing provider authentication

Install from npm

Install the runtime globally:


pnpm add -g @clawcontrol/runtime

Then confirm the CLI is available:

clawcontrol --version

If you prefer a project-local install instead of a global one:


pnpm add @clawcontrol/runtime
npx clawcontrol --version

Recommended first-run flow

1. Create a pairing code in ClawControl

In the ClawControl app, open the runtime settings area and create a pairing code for the machine you want to connect.

2. Run the guided onboarding command

On the host machine, start the guided flow:

clawcontrol runtime onboard

During onboarding, the CLI can:

ask for the pairing code
let you set an optional runtime name
validate an existing local runtime link and repair it when needed
help you resolve pending OpenClaw gateway pairing approval
walk you through runtime configuration
offer to install and start the runtime as a background service

3. Choose how the runtime should start

The guided flow will ask whether you want to install the runtime as a service, run it in the foreground for testing, or leave startup for later.

Manual setup flow

If you want to run each step yourself, use this order.

1. Configure the runtime

clawcontrol runtime configure

The configuration wizard asks for or confirms:

the OpenClaw gateway URL
a gateway bootstrap token
whether to share runtime telemetry
the OpenClaw directory
the auth base agent used to locate local auth profiles

2. Pair the runtime

clawcontrol runtime pair <PAIRING_CODE> --name "My Runtime"

If you omit the pairing code in an interactive terminal, the CLI can prompt for it instead.

3. Install the background service

clawcontrol runtime service install

If you want to install it without starting it immediately:

clawcontrol runtime service install --no-start

4. Verify the runtime

clawcontrol doctor
clawcontrol runtime status

Run in the foreground for testing

If you want live logs in your terminal instead of a background service:

clawcontrol runtime run

This is useful during first-time setup or troubleshooting. Press Ctrl+C to stop it.

Good post-install checks

The runtime appears in ClawControl
The runtime is marked connected, not offline
clawcontrol doctor reports no blocking readiness issues
clawcontrol runtime status shows the service installed and running

If pairing does not finish cleanly

In some failure cases, the initial pairing request may reach ClawControl but the finalization step may not complete.

If that happens:

restart the runtime to let it retry a pending pairing finalization automatically
if the backend reports the pending finalize is no longer valid, generate a new pairing code and pair again
use clawcontrol doctor and clawcontrol runtime status before redoing the full setup

Common follow-up commands

clawcontrol doctor
clawcontrol runtime logs --follow
clawcontrol runtime service repair --restart
clawcontrol plugin install