- Best for: people who already use OpenClaw, or who want agents that also answer on OpenClaw’s messaging channels (set up in OpenClaw itself).
- You need: Clawboo running on a Node.js version that OpenClaw supports, and a credential it can use: a provider key, a ChatGPT sign-in or a local Ollama. Clawboo installs and starts the Gateway for you.
Before you begin
- Clawboo on a Node.js in OpenClaw’s range: the setup installs the newest 2026.9 release of OpenClaw, and installs it on the Node.js Clawboo itself runs on. Since 2026.9.34 that release needs 24.22.1 or later in the 24 line, or 26.12.1 and later (
>=24.22.1 <25 || >=26.12.1). Node 22 and Node 25 can no longer run it, even though Clawboo itself runs on Node 22.12 and later. The setup checks this first and installs nothing on a Node.js outside the range. Settings > System shows the Node.js Clawboo runs on. See OpenClaw’s Node.js guide. - npm, which comes with Node.js. The setup installs
openclaw@~2026.9into Clawboo’s own runtimes folder, never into npm’s global folder, so it needs nosudo. - A credential OpenClaw can reuse: a provider key you connected in Clawboo, a ChatGPT sign-in, or the local Ollama you set up for Clawboo Native. With none of these, the setup asks you for a key.
Set up OpenClaw
Set up OpenClaw is one button. It reuses a credential you already connected, installs OpenClaw if needed, starts the Gateway and connects to it. The same setup runs from Settings > Runtimes and from onboarding’s Add more runtimes step.Start the setup
Let Clawboo reuse a credential
- A provider key saved in Clawboo (on the Providers page, in onboarding or on a runtime’s card) or already in OpenClaw’s
~/.openclaw/.env. A key that is only exported in your shell doesn’t count. With several keys, it takes the first in this order: Anthropic, OpenAI, Google, OpenRouter, xAI, Groq, Mistral, Moonshot, MiniMax, Together, NVIDIA, Hugging Face, Cerebras, Venice. - A ChatGPT sign-in that OpenClaw already holds.
- A ChatGPT sign-in that only Codex holds. The panel asks you to sign OpenClaw in too (next step).
- The local Ollama you set up for Clawboo Native.
- Nothing. The panel asks you for a key (next step).
Add a key or sign in, if asked
ollama pull command for it. Run that command, then click Check again. Continue anyway starts the Gateway regardless, but OpenClaw agents can’t answer until the model is there.Install OpenClaw and start the Gateway
openclaw@~2026.9 into Clawboo’s runtimes folder, with npm’s output in a log. Then it shows Starting the Gateway…. A Gateway that is already running on OpenClaw’s port is used as it is. Otherwise Clawboo starts one and waits up to 60 seconds for it to answer.If OpenClaw asks for openclaw doctor --fix before it will start (this can happen after an OpenClaw upgrade), Clawboo runs it once and starts the Gateway again.The log fills with install and Gateway lines, then the panel moves on to connecting.Approve this device

If a step fails
The panel replaces its progress with the error and a Retry button. Retry runs the whole setup again: it skips the install once OpenClaw is installed, and joins a Gateway that is still starting instead of launching a second one. If the reconnect after approval fails, or OpenClaw still says the device isn’t approved, the error reads “OpenClaw still needs this device approved. Retry to approve it again.” Retry then brings back a fresh approval card. Cancel closes the panel at any point before it connects. An install that has already started still finishes in the background. The exact errors and their fixes are under Troubleshooting.Approve from a terminal instead
The approval card runs two OpenClaw commands for you. You can run them yourself:openclaw, such as ~/clawboo-runtimes/bin/openclaw devices approve --latest (see Where OpenClaw is installed). Then run Set up OpenClaw or Reconnect OpenClaw again so Clawboo connects. See OpenClaw’s devices command.
Use your ChatGPT plan
OpenClaw can run on a ChatGPT subscription instead of an API key, through its ownopenai-codex provider. It needs its own sign-in, separate from Codex’s:
- During setup, or later under Manage > ChatGPT subscription, click Sign in with ChatGPT. This needs Codex connected first; until then the row reads “Connect Codex first”.
- Or run OpenClaw’s own login in a terminal:
openclaw models auth login --provider openai-codex. When Clawboo installed OpenClaw, the command the panel shows names the full path of itsopenclaw, since that is not on yourPATH. Use it rather thanopenclaw onboard, which can reset your channels, memory and cron jobs.
Where OpenClaw is installed
Set up OpenClaw, and Check for Updates in Settings > System, install OpenClaw into Clawboo’s own runtimes folder,~/clawboo-runtimes by default (CLAWBOO_RUNTIMES_DIR moves it, and so does CLAWBOO_HOME), never into npm’s global folder. The command that starts it is ~/clawboo-runtimes/bin/openclaw, and it runs OpenClaw on the Node.js that installed it, whatever node comes first on your PATH later.
- Clawboo uses its own copy first. The Gateway Clawboo starts,
openclaw doctor --fix, device approval, the model list and the ChatGPT sign-in all run this copy, so the Gateway runs on the Node.js that installed it. Without one, Clawboo uses anopenclawon yourPATH, so a global install you made yourself keeps working. - It is not on your
PATH. To run an OpenClaw command yourself, such as the ones on this page, type the full path:~/clawboo-runtimes/bin/openclaw doctor --fix. - An update never leaves it half replaced. A new install goes into a folder beside the current one and becomes current only when npm succeeds. A failed install is removed, and the OpenClaw you had keeps working.
- A Gateway you run yourself is left alone, such as OpenClaw’s own launchd service on port 18789. It keeps running the OpenClaw it was started with.
- If its Node.js is gone, for example after
nvm uninstall, a Homebrew upgrade that deletes the old version, or an app that runs Clawboo on a Node.js of its own being moved or renamed, Clawboo from 0.9.0 moves this copy to the Node.js Clawboo runs on, and log it, when that Node.js is the same version or a later release of the same major version on the same kind of processor. An install from 0.8.0 or older recorded no processor, so for it the processor is not checked: install OpenClaw again if Clawboo now runs on a Node.js for another kind of processor. Otherwise, and in 0.8.0, Clawboo stops using this copy, and OpenClaw reads as not installed unless a global copy exists; Set up OpenClaw installs it again on the Node.js Clawboo runs on now. See Which copy Clawboo uses.
OpenClaw’s own sandbox stays off
OpenClaw can run its agents’ tools in a Docker or Podman container of its own. Clawboo keeps that sandbox off (agents.defaults.sandbox.mode: "off" in openclaw.json), so OpenClaw’s tools run on the same computer Clawboo and its other agents use. Set up OpenClaw writes it only when your config has no agents.defaults.sandbox, so a sandbox you set up yourself stays. off is OpenClaw’s own default; Clawboo writes it out so it holds if a later OpenClaw changes that default. Agent isolation, with one agent user or a user per agent, does not cover OpenClaw agents: they run inside the OpenClaw Gateway, as whoever started it.
Default models
When OpenClaw has no default model yet, the setup picks one for the provider it reused. It never replaces a default you already have.google/gemini-2.0-flash for a Google key. Google shut that model down on 2026-06-01, and OpenClaw now treats it as an unknown model and reports the whole config as invalid. If your default is still google/gemini-2.0-flash, pick another model under Manage > Default model.
What a new Boo is allowed to run
OpenClaw’s Gateway decides whether an OpenClaw agent may run a command, from each agent’s command policy. Clawboo sets that policy when it creates an agent:- A new OpenClaw agent gets Ask for Unknown. It asks you before running a command it hasn’t been allowed. (A caller of the REST API can pass another posture, and Clawboo writes that one instead.)
- A refused policy stops the creation. If the Gateway won’t take the policy, Clawboo removes the half-made agent and Create Boo shows “Could not set this agent’s command permissions on the Gateway, so it was not created”, followed by the reason.
- An agent made outside Clawboo has no policy from Clawboo. It follows the Gateway’s own defaults, which let it run commands without asking unless you changed them.
- Nothing re-applies a posture later. Clawboo writes it when it creates the agent, and when you change Command Execution on the agent’s Permissions tab. A change made outside Clawboo stays.
Manage OpenClaw
Once OpenClaw is connected, its row reads Connected and offers Manage:What Clawboo writes to OpenClaw
Clawboo changes OpenClaw’s files in these places.~/.openclaw is OpenClaw’s state folder (OPENCLAW_STATE_DIR moves it), and ~/.clawboo is Clawboo’s (CLAWBOO_HOME moves it).
How Clawboo talks to the Gateway
Clawboo keeps two connections to the Gateway. Both use a device identity that you approved once during setup, stored in~/.clawboo/proxy-device-identity.json. That identity only proves Clawboo to the Gateway; it does not protect the dashboard itself (see Self-host securely).
The server’s own connection stays open once something needs the Gateway (see How Clawboo connects), with or without a browser tab. Over it, Clawboo:
- runs every OpenClaw agent turn in team chat, including the tasks those agents are given;
- runs OpenClaw agent Routines, and lists the Gateway’s own cron jobs on the Routines page, where you can turn them on or off, run them or delete them;
- keeps its copy of your OpenClaw agents up to date, so they still show when the Gateway is down;
- receives command approval requests, so they wait in Clawboo’s approvals even with no tab open;
- records activity and token use from OpenClaw sessions, including ones Clawboo didn’t start, such as a channel message or one of an agent’s own cron jobs;
- registers its MCP servers in the Gateway’s configuration, and passes your comments into running tasks.
How Clawboo connects
The server connects to the Gateway only once something needs it. A Gateway that a service manager starts on its first connection, such as a systemd socket unit on a small Linux machine, then stays asleep while nothing uses OpenClaw. Each of these is a need:- An OpenClaw agent exists in Clawboo and is not archived, or, while OpenClaw is still set up, the delete of one is still owed to the Gateway (it was deleted while the Gateway was down). An install with OpenClaw agents connects at every start, as before.
- You open OpenClaw in Settings > Runtimes, or start the Gateway from Clawboo (setup, Reconnect, Start or Restart).
- The dashboard opens its own Gateway connection. It does that only once the Gateway is in use, so loading the dashboard is not a need.
- A routine for an OpenClaw agent falls due. The fire waits for the connection it starts, as it waits for any Gateway still coming up.
- A request that needs the Gateway: creating an OpenClaw agent or a sync without a body, when a Gateway is set up, or a change to the Gateway address or token. A create or sync on a Gateway nothing used yet waits up to about 5 seconds for the connection, and answers
503if it is not up by then; try it again a few seconds later.
GET /api/system/idle reports that source off with the reason not_in_use. Once something needs the Gateway, the server stays connected, and reconnects after a drop, until it stops.
For the protocol detail, see Gateway and events.
Clawboo tools inside OpenClaw
Each time the server connects, Clawboo registers three of its MCP servers in the Gateway’s configuration, so every OpenClaw agent can use them. One Gateway configuration serves every OpenClaw agent, so Clawboo can’t tell which agent is calling, and each server is limited accordingly:sessions_spawn and sessions_yield to OpenClaw’s denied tools, so agents hand work to their team instead of spawning sub-agents of their own. An OpenClaw leader hands work on by calling OpenClaw’s sessions_send tool, or with a <delegate to="@Name">…</delegate> block in its reply; Clawboo turns either one into a board task.
Agent files
An OpenClaw agent’s files live in its workspace on the Gateway. Clawboo writes them when it creates the agent, and when you edit them on the agent’s page (Details, then the file tabs). Editing needs the Gateway running.HEARTBEAT.md, USER.md or MEMORY.md; the file editor shows them only when they already have content. To schedule an OpenClaw agent’s own work, use OpenClaw’s cron jobs or a Clawboo Routine. OpenClaw’s agent workspace guide covers every file.
Comments on a running task
A comment you leave on a task an OpenClaw agent is working on joins its running turn at the next step, without stopping a tool that is running. If the run can’t take it, the comment waits for the agent’s next run. See Steering a running task.Costs
OpenClaw’s Gateway reports no cost to Clawboo, so every OpenClaw figure you see is Clawboo’s estimate:- Budgets are charged an estimate for each OpenClaw turn in team chat, and for each OpenClaw Routine run, whether it succeeds, fails, times out or is stopped. It is worked out from the length of the prompt and the reply, at about four characters per token, priced at the agent’s model in
openclaw.json. An agent whose model is anollama/one runs on your own Ollama, so it is charged nothing and its tasks read free. - Tokens Used shows the token counts OpenClaw records for each turn, priced from Clawboo’s rate table. A turn your own Ollama served is priced at $0.
- A 1:1 chat with an OpenClaw agent shows in Tokens Used, but is not charged to budgets.
Limits
- No worktree, no checks. OpenClaw agents work in their own Gateway workspace. Clawboo never gives them a git worktree and never runs verification on their work; see How work is checked.
- Global memory, no connectors from the graph. See Clawboo tools inside OpenClaw.
- A Gateway on this computer. Set up OpenClaw configures and starts a local Gateway. Clawboo registers its MCP servers at a
127.0.0.1address, which a Gateway on another machine can’t reach. - Routine runs stop after 10 minutes. An OpenClaw Routine run that hasn’t finished by then is stopped. Time the computer spends asleep does not count.
CLAWBOO_ROUTINE_OPENCLAW_TIMEOUT_MSchanges the limit. - The 2026.9 line. Clawboo installs
openclaw@~2026.9, because it writes OpenClaw’s configuration in that line’s format. - Not on the runtimes API.
/api/runtimes/openclaw/...answers404. OpenClaw is managed through the System API.
Troubleshooting
NOT_PAIRED: pairing required, device is not approved yet
NOT_PAIRED: pairing required, device is not approved yet
OpenClaw still needs this device approved. Retry to approve it again.
OpenClaw still needs this device approved. Retry to approve it again.
The approval card shows an error
The approval card shows an error
No pending device pairing requests found: OpenClaw had no request waiting, for example because the device is already approved. Close the panel with Cancel and run Set up OpenClaw again; it connects, or shows a fresh card.OpenClaw not installed: Clawboo found noopenclawcommand, in its runtimes folder or on yourPATH. Run the setup again, which installs it.Failed to approve device: …orFailed to run openclaw: …: the OpenClaw command failed. Run the two terminal commands above to see OpenClaw’s own message.
Node.js … is too old for OpenClaw, or is not one OpenClaw runs on
Node.js … is too old for OpenClaw, or is not one OpenClaw runs on
>=24.22.1 <25 || >=26.12.1), and says nothing was installed. OpenClaw runs on the Node.js Clawboo runs on, so the setup checks that version before it installs anything. “Too old” means below 24.22.1; “not one OpenClaw runs on” means Node 25, a Node 26 before 26.12.1, or a prerelease. The install stream’s error code is NODE_UNSUPPORTED. Earlier versions of Clawboo installed an older OpenClaw on such a Node.js without saying so.Fix: if Clawboo came with the desktop app, update the app, which brings its own Node.js. Otherwise start Clawboo with a supported Node.js. Node 24.22.1 or a newer Node 24 is the simplest. Stop Clawboo, switch to that Node.js in a terminal, and start Clawboo from it. A version manager such as nvm keeps global packages per Node.js, so install Clawboo again under the new one, or run npx clawboo@latest. Settings > System shows the version Clawboo runs on. Then click Retry.Installation failed with exit code
Installation failed with exit code
openclaw@~2026.9 into the runtimes folder. The message goes on with npm’s own reason, and the error code is npm’s, such as ETARGET or EACCES. Clawboo removed the new install’s folder, so an OpenClaw you already had is unchanged.Fix: fix what npm reports, such as a network or proxy problem, then click Retry.Clawboo's runtimes folder must be apart from Clawboo's data folder, or belongs to another user
Clawboo's runtimes folder must be apart from Clawboo's data folder, or belongs to another user
RUNTIMES_DIR_REFUSED, and the message says why: the folder is the data folder or the work folder, sits inside one or contains one, or it belongs to another user or others can write to it. Until that is fixed, Clawboo uses an openclaw on your PATH, if there is one.Fix: set CLAWBOO_RUNTIMES_DIR to a folder of its own and restart Clawboo, or, for a folder you do not own, make it yours and run chmod go-w on it. Then click Retry. See When Clawboo will not use it.Gateway did not start, or did not become reachable within 60s
Gateway did not start, or did not become reachable within 60s
Gateway did not start: …), or never answered on its port within 60 seconds.Fix: read the Gateway’s log at ~/.clawboo/gateway.log, fix what it reports, then click Retry. OpenClaw’s troubleshooting guide and doctor command help with OpenClaw’s own errors.OpenClaw needs openclaw doctor --fix, and running it failed
OpenClaw needs openclaw doctor --fix, and running it failed
openclaw doctor --fix that Clawboo ran failed.Fix: run openclaw doctor --fix in a terminal to see the whole report (~/clawboo-runtimes/bin/openclaw doctor --fix when Clawboo installed OpenClaw), then start the Gateway again with Retry or Reconnect OpenClaw. Do the same if the message says OpenClaw still asks for openclaw doctor --fix after Clawboo ran it.Clawboo couldn't find the model in your Ollama
Clawboo couldn't find the model in your Ollama
ollama pull command the panel shows, then click Check again.OpenClaw Gateway is offline, or unreachable
OpenClaw Gateway is offline, or unreachable
Could not set this agent's command permissions on the Gateway, so it was not created
Could not set this agent's command permissions on the Gateway, so it was not created
The API answers 503 gateway_disconnected
The API answers 503 gateway_disconnected
Check it works
Check the runtime
Talk to an OpenClaw agent
Put OpenClaw agents on a team
Under the hood
Under the hood
- The connections. The browser connects to
/api/gateway/wson the Clawboo server, which adds the token and signs the device before passing it on. The server’s own connection is an operator client (client idcli) that sends the Gateway host as its Origin and declares thetool-eventsandexec-approvalscapabilities. Clawboo supports Gateway connect protocols 3 and 4. - Write budget. The Gateway allows three configuration writes per 60 seconds, so the MCP registration skips its write when nothing has changed.
configure-openclaw. The dashboard never callsPOST /api/system/configure-openclaw. It writes a freshopenclaw.jsonand.env, replacing what is there, and makes a new Gateway token on every call, so use it only on a fresh OpenClaw. Set up OpenClaw usesPOST /api/system/auto-configure-openclaw, which fills in only what is missing. See the System API.- The model list. The pickers read
openclaw models list --all --json. OpenClaw 2026.9 refuses it when several agents are configured and none is named the owner, so Clawboo then asks again with--agent(the agent marked default, elsemain, else the first), until you configure a system agent (agents.defaults.systemAgent.agentId). SeeGET /api/system/modelsin the System API. - Model refs. Clawboo writes the ChatGPT model as
openai-codex/<model>.openclaw doctor --fixlater rewrites it toopenai/<model>and turns on the plugins that form needs. - The install.
POST /api/system/install-openclawchecks the Node.js version first, then runs npm into a new folder under the runtimes folder and switches to it on success.GET /api/system/statusreportsopenclaw.source(clawbooorpath) and, for Clawboo’s copy,openclaw.runsOnNode. See the System API. - The pin.
openclaw@~2026.9holds OpenClaw’s configuration format (the agent roster underagents.entries, and stricterconfig.patchrules), not the connect protocol. - More detail: Gateway and events and Agent sources.
Related
- Choose a runtime: how OpenClaw compares with the other runtimes
- Connect providers and runtimes: keys, sign-ins and what Disconnect removes
- Command permissions: review and revoke what an OpenClaw agent may run
- Where Clawboo keeps data: back up or reset
~/.clawbooand~/.openclaw - OpenClaw docs: install, channels, cron jobs and troubleshooting for OpenClaw itself