Skip to main content
By the end of this tutorial you’ll have a running OpenClaw Gateway connected to Clawboo, set up from the onboarding wizard’s Add more runtimes step. Onboarding is native-first, so you connect the native runtime first, then add OpenClaw through its setup detour: detect your environment, install OpenClaw if needed, configure a model provider, start the Gateway, and approve the one-time device pairing. Once OpenClaw is connected you deploy an OpenClaw team from the dashboard. This is the OpenClaw path. Unlike the other four runtimes, OpenClaw is a connected substrate; Clawboo connects to a running OpenClaw Gateway (a WebSocket server that hosts OpenClaw agents), rather than installing and spawning a CLI per task. If you want a working team with no Gateway at all, the native runtime quickstart is faster: paste one provider key and you’re done.
These docs describe Clawboo v0.3.1, the current release.

​
Prerequisites

  • Node.js 22 or newer: Clawboo’s engines field requires node >=22.0.0.
  • npm on your PATH: the install step runs npm install -g openclaw@^2026.5.
  • A provider API key for whichever model provider you’ll configure OpenClaw with (Anthropic, OpenAI, Google, OpenRouter, and others). Ollama needs no key, but it must be running locally.
  • No prior OpenClaw install is required; the wizard can install, configure, and start one for you.
OpenClaw is a separate project; Clawboo connects to a Gateway you run locally, it does not bundle OpenClaw. The wizard pins the install to openclaw@^2026.5 deliberately: Clawboo’s gateway client advertises connect protocol minProtocol: 3, maxProtocol: 4, and the pin keeps a fresh user on a protocol-compatible OpenClaw.

​
Steps

​
1. Install and launch Clawboo

Install Clawboo globally, then run it:
Prefer not to install? npx clawboo runs the latest instead. Either way, the CLI prints the Clawboo logo, does a quick informational probe of the OpenClaw Gateway port (localhost:18789), starts the bundled dashboard server, then opens your browser at the discovered URL. Expected result: your terminal shows Dashboard started and Clawboo opened at http://localhost:18790 (or the next free port in the 18790–18809 range), and the dashboard loads. Because this is a fresh machine, the onboarding wizard appears.

​
2. Click “Get Started”

The first screen is the welcome splash: the Clawboo wordmark, the line “Your AI agents, visible.”, and a Get Started button. Expected result: clicking Get Started advances to the native connect step. There is no “pick a runtime” screen; native is the default, and OpenClaw is added afterward.

​
3. Connect the native runtime, then choose “Set up OpenClaw”

Onboarding is native-first, so you connect the built-in native runtime before adding OpenClaw. On the Connect your AI provider step, pick a provider and paste a key (or select Ollama for a keyless local model), then click Continue. Clawboo stores the key and advances to the Add more runtimes step (you pick and deploy a team in a later step). (The native connect step is covered in full in Quickstart: native.) On Add more runtimes, find the Set up OpenClaw row and click Set up OpenClaw. Expected result: the wizard enters the OpenClaw setup detour at the System Check step. Everything in steps 4 to 7 below happens inside this detour, which returns you to Add more runtimes when it’s done. The OpenClaw setup running on the Add more runtimes step: install output streams in the terminal log while the Gateway starts

​
4. Let Clawboo detect your environment

The System Check step fetches GET /api/system/status on mount and shows an animated three-item checklist: Node.js, OpenClaw, and Gateway, each revealed in sequence:
  • Node.js: a green check when your version is 22 or newer (a red X with a Download link otherwise).
  • OpenClaw: green with the detected version when the openclaw binary is on your PATH; an amber dot reading “Not found” otherwise.
  • Gateway: green “Running on :18789” when a managed Gateway process is alive or the port probes reachable; amber “Not running” otherwise.
A single call-to-action button at the bottom reflects what’s missing. On a fresh box it reads Install OpenClaw; once OpenClaw is installed but unconfigured it reads Set Up OpenClaw; once configured but the Gateway is down it reads Start Gateway; when everything is green it reads Continue and auto-advances after ~1.5 seconds. Expected result: the checklist resolves, and the CTA tells you the next action. If everything was already green, you skip ahead to the team step (step 8); otherwise click the CTA to proceed through the steps below.
If you already run a Gateway on another machine, click Connect to remote gateway → at the bottom of System Check to enter a Gateway URL and token directly instead of installing locally.

​
5. Install OpenClaw

If OpenClaw isn’t installed, clicking Install OpenClaw opens the Installing OpenClaw step, which streams POST /api/system/install-openclaw, a Server-Sent Events stream that runs npm install -g openclaw@^2026.5 and shows live npm output in a terminal log. The stream emits typed events: On complete, the step shows “Installed! v…” and auto-advances to configuration after ~1 second. Expected result: the terminal log fills with npm output, then the step reports the installed version and moves on.
A global npm install can fail with EACCES (“permission denied”). The stream emits an error event with code EACCES, and the step shows a How to fix panel suggesting a Node version manager (nvm/fnm) or Homebrew. Prefer either of those over sudo.

​
6. Configure a provider

The Set Up OpenClaw step shows a provider grid: four primary cards (Anthropic, OpenAI, Google, Ollama) plus a “More providers” section (OpenRouter, xAI, Groq, and others). Pick a provider, paste your API key into the API Key field (the eye icon toggles visibility), and optionally choose a Default Model from the dropdown. Ollama needs no key; selecting it hides the key field. Clicking Configure & Start posts to POST /api/system/configure-openclaw with { provider, apiKey?, model? }. The handler:
  • writes OpenClaw’s openclaw.json in local mode (gateway.mode: 'local', token auth, agent-to-agent tooling enabled with tools.sessions.visibility: 'all') and a default model under agents.defaults.model.primary;
  • generates a Gateway auth token and writes it into OpenClaw’s ~/.openclaw/.env as GATEWAY_AUTH_TOKEN, alongside your provider key;
  • saves Clawboo’s own settings.json (gatewayUrl, gatewayToken).
The handler returns { ok: true, gatewayUrl }. The raw token is never returned in the response body; it’s persisted server-side, and the same-origin proxy injects it on connect. Expected result: the button shows “Configuring…”, then the wizard advances to the Gateway-start step.

​
7. Start the Gateway and approve the device

The Starting Gateway step posts POST /api/system/gateway with { "action": "start" }, an SSE stream that spawns the Gateway detached, polls until the port (18789) is reachable (up to 60 seconds), syncs the token, and reconnects Clawboo’s server-side agent source. On the complete event, the step auto-connects a Gateway client through the same-origin WebSocket proxy. On OpenClaw 2026.5.x and later, that first connect fails with NOT_PAIRED; a new device lands in OpenClaw’s pending list and must be approved by a human before it can connect:
Instead of an error, the step swaps in an Approve this device card. Click Approve this device. The card hits POST /api/system/approve-device, which performs a two-step shell-out against the OpenClaw CLI:
  1. openclaw devices approve --latest runs in preview mode: it prints Approve this exact request with: openclaw devices approve <UUID> and exits non-zero. Clawboo regex-extracts the UUID from the captured output.
  2. openclaw devices approve <UUID> performs the actual approval.
On success, the step automatically retries the original connect with the same URL and token, and the connection completes. Expected result: the mascot pulses while the Gateway starts, the Approve this device card appears, and after you click it the status flips to Connected! The detour then returns you to the Add more runtimes step, now showing a Connected pill for OpenClaw.
You can pair from a terminal instead: run openclaw devices approve --latest to see the request id, then openclaw devices approve <requestId>. The approval card surfaces this manual fallback too.

​
8. Finish onboarding, then deploy an OpenClaw team

Back on Add more runtimes, click Continue. The wizard advances to the Team step, where you pick a starter team from the marketplace and deploy it. During onboarding every agent defaults to Clawboo Native; now that the Gateway is connected you can switch any member to OpenClaw from its runtime picker in the customize step. Then the Your team is ready screen shows the roster and a “Led by …” badge for Boo Zero; click Open my dashboard. You land in the dashboard connected to the Gateway (“gateway” mode), in your new team’s group chat, which opens on a one-time introduce yourself screen. To build a team of OpenClaw agents, open the Marketplace (or + Create team in the leftmost sidebar), pick a template, and choose OpenClaw as the runtime for its members. Deploy creates the team and its agents: it POST /api/teams to create the team, writes each agent’s SOUL.md, IDENTITY.md, TOOLS.md, and an enhanced AGENTS.md with the team roster and collaboration protocol, assigns each agent to the team, sets the team-internal lead when one is detected, and, when any agent has @mention routing, enables agent-to-agent coordination in the Gateway config. See Deploy your first team for the full team-building flow. Expected result: the new team appears in the sidebar, connected to the Gateway, and opens directly in its group chat.

​
What you should see

The dashboard opens connected to the Gateway, with the team you deployed in view and OpenClaw available as a runtime you can build teams on. Once you deploy an OpenClaw team, its Boos are ready to collaborate. The team space looks like this once you start collaborating: Clawboo team space: a team's Ghost Graph on top and group chat below

​
What just happened

The wizard’s Add-runtimes detour walked the full OpenClaw setup: it detected your environment, installed and configured OpenClaw with your provider key, started the Gateway, and approved this device for pairing. Once the Gateway came up, Clawboo opened two connections to it: a browser-side same-origin proxy connection for the chat/execution stream, and a server-side connection that mirrors the Gateway’s agent list into SQLite (the registry of record, so the fleet survives the Gateway being down). Deploying an OpenClaw team from the dashboard then creates real OpenClaw agents and wires their routing, so they can delegate to each other over the Gateway.

​
Next steps

Enjoying Clawboo? Star it on GitHub

Clawboo is free and open source. A star is the best way to support the project and helps other people find it.
Last modified on August 6, 2026