clawboo command starts the dashboard and manages the server behind it. Use this page to look up a command or flag, what it prints, and when it exits with an error.
Install once with
npm install -g clawboo, then run clawboo. For a one-off run without installing, use npx clawboo@latest. Every command checks your Node version first: on Node older than 22.12 it prints “Clawboo requires Node.js 22.12 or newer”, your version and how to switch, then exits with code 1.
clawboo
Run with no subcommand,clawboo gets you to a working dashboard:
- It prints the logo and
Clawboo v<version>. - It checks whether an OpenClaw Gateway answers on
localhost:18789and says so. This is information only; the dashboard handles Gateway setup either way. - It looks for a running dashboard (see Port discovery).
- If it finds one, it compares that server’s version with its own and may offer a restart (see Version check).
- If none is running, it starts one in the background and waits up to about 45 seconds for it to answer.
- It opens the dashboard in your browser, prints “Clawboo opened at” with the URL, and lists next steps.
http://127.0.0.1:<port>, or http://127.0.0.1:<port><prefix>/ when you set CLAWBOO_BASE_PATH: the address the server listens on. The CLI uses it rather than localhost, which can resolve to ::1, where another program could be listening on the same port. When HOST names another loopback address, ::1 or another 127.x, the CLI uses that one, since it is all such a server listens on. For HOST=localhost, which leaves the address to the system, set HOST=127.0.0.1 or HOST=::1 instead. A browser signed in at one of these addresses is not signed in at the other. The browser opens with open on macOS, start on Windows and xdg-open elsewhere. On a server with an access token, which is every install unless you turn it off, the browser opens a one-time sign-in link instead: the same URL with ?access_code=<code> added, which signs the browser in once, within two minutes (see Signing in a browser). Only the plain URL is printed. When no browser opens, as on a server with no desktop, it prints “Could not open a browser on this computer.” and suggests clawboo open --print. When the server gives no sign-in link (it did not answer in time, or it is older than one-time links), the browser opens the plain address, and the CLI says it opened without a sign-in link and to run clawboo open if the dashboard says it is locked.
--no-version-check and -y apply to clawboo itself. clawboo stop takes --force and --wait <seconds>, clawboo restart takes those and --no-open, clawboo open takes --print, clawboo backup takes -f, --force, and clawboo agent-user plan takes --user <name>, or --pool <n> with --teams <m>, --first-uid <uid> and --first-team-gid <gid>. A mistyped subcommand, such as clawboo stopp, prints error: unknown command 'stopp' with the help text and exits 1 instead of starting anything.
Version check
A server keeps running the code it started with, so after an upgrade the running server can be older than the CLI you just installed. Before attaching,clawboo asks the server for its version (GET /api/system/self-version?local=1, with a 2-second timeout). The local=1 part tells the server to skip its npm lookup, so this check stays on your machine.
- It offers a restart only when both versions are real releases and the CLI is newer. It never offers a downgrade, and a source checkout (version
0.0.0-dev) is never compared. - The prompt reads “Restart it on port N to run vX?” and defaults to yes.
-yanswers yes for you. - Declining, or pressing Ctrl-C at the prompt, keeps the running server and opens it.
- When stdin or stdout is not a terminal, it never prompts. It attaches and tells you to run
clawboo restartor pass-y. - If stopping the old server fails, it prints why and a manual stop command, then continues with the running server.
- If it stopped the old server and the new one never answers, it prints “The previous server was stopped and could not be replaced. Nothing is running now.” and exits 1.
Port discovery
clawboo, clawboo stop and clawboo restart all find the server the same way, so they act on the same instance:
CLAWBOO_API_PORT, when set to a valid port (1-65535): only that port is checked.- The port file
<CLAWBOO_HOME>/api-port.txt(default~/.clawboo/api-port.txt), which the server writes when it starts listening. From 0.9.0 the CLI first checks the start marker beside it,api-port.json, and skips a port whose marker shows the server that wrote it is gone. With no marker, or one it cannot check, the port file counts on its own, as before. - The default range, ports 18790 through 18809.
GET /api/settings. Only a reply with Clawboo’s JSON shape counts, so another service listening in that range (OpenClaw’s helper ports, a Chrome debugging port) is never mistaken for the dashboard. A server with an access token answers that request with a 401 first; see Token-gated installs. A server you started with a different CLAWBOO_API_PORT_START is found only through the port file. clawboo backup does not look for a server at all.
The background server and its log
The server runs detached: it keeps running afterclawboo exits or you close the terminal. Stop it with clawboo stop.
- Normal install. The CLI starts the bundled server with
~/.clawbooas its working directory (created with owner-only permissions if missing) andNODE_ENV=production. - Source checkout. With no bundled server, it runs
npx tsx apps/web/server/index.tsfrom the repository root, found by walking up to apackage.jsonnamedclawboo(CLAWBOO_SERVER_PATHoverrides the search). With neither, it prints “Could not find the Clawboo server. Install with: npm install -g clawboo” and exits 1. - Log. The server’s output goes to
~/.clawboo/server.log, with a header line--- clawboo v<version> · pid <pid> ---for each launch. A log over 5 MiB is renamed toserver.log.1at the next launch. If the log cannot be opened, the output is discarded. - Slow start. The CLI checks for the dashboard every 500 ms, 90 times (about 45 seconds). If it never answers, the CLI prints “Dashboard is taking too long to start.”, the last 12 lines of the log and the log’s path, then exits 1. It never starts a second server.
- After an in-app update. A server that the dashboard’s update restarted writes nothing to this log. Run
clawboo restartto get logging back.
clawboo stop
clawboo would open, after the agent runs it is working on have finished. To target one port, run CLAWBOO_API_PORT=<port> clawboo stop.
- It finds the server through port discovery and confirms the port really is a Clawboo dashboard.
- Unless you pass
--force, it holds the server, so it starts no new agent run, and waits for the runs already going to finish. The spinner says how many are left and how long it will still wait. At the bound it prints “Waited 10m; stopping N agent runs still going.” and stops anyway. See Waiting for agent runs. - It looks up the process listening on that port (
lsofon macOS and Linux,netstat -anoon Windows) and sends it SIGTERM. - It waits up to 15 seconds for the port to close. The server’s own stop (below) normally ends within that, but the database checkpoint at its end has no bound and can run past it on a large database; the database stays crash-safe either way. If the port is still open, it checks that the same process still holds it, sends SIGKILL, and waits up to 2 more seconds.
- It prints “Clawboo stopped (pid N)”, or “(pid N, forced)” when SIGKILL was needed.
api-port.txt that names a dead server (and, from 0.9.0, a start marker that shows its server is gone), and exits 0, so it is safe in teardown scripts. It never signals process 1, itself or its parent.
A server too busy to answer still holds its port, but the command cannot find it, because it finds a server by asking it. When the port named in api-port.txt still takes connections and lets a request go unanswered, and (from 0.9.0) the start marker does not show the server that wrote it to be gone, the command keeps the file, prints “A server on port N, the port Clawboo recorded, takes connections but does not answer. It may be busy, so it was not stopped.”, then prints a command that stops the server’s process by hand (lsof -nP -iTCP:<port> -sTCP:LISTEN -t | xargs kill; on Windows, netstat then taskkill), and exits 1. --force finds a server the same way, so it cannot reach this one either.
When the stop fails it exits 1 and prints a manual stop command after one of these reasons:
- “The server on port N did not exit.”
- “The process on port N belongs to another user.”
- “Port N is held by a process this launcher refuses to signal.”
- “Could not identify the process listening on port N.” (also printed when neither
lsofnornetstatis available)
--force, and the ones left when the wait runs out. On macOS and Linux the server first signals the runtime processes it started and waits up to 5 seconds for them, removes api-port.txt if it still names its port (and, from 0.9.0, api-port.json if it names this server), and checkpoints the database. From 0.9.0 the Hermes gateway gets its planned stop at the same time (see Hermes), and traces are flushed last, for up to 2 seconds when you export them, so the whole wait stays under about 11 seconds. On Windows the stop ends the process at once, so none of that runs: clawboo stop removes the port file itself and the database recovers when it is next opened. Routines are re-armed when the server starts again. An OpenClaw Gateway that Clawboo started keeps running.
clawboo restart
clawboo stop does, waiting for its agent runs first, then starts a new one on the same port, so a browser tab that is already open reconnects. It opens the browser the way clawboo does, with a one-time sign-in link on a server with an access token. Use it after npm install -g clawboo@latest (the running server keeps its old code until it restarts) or after you change an environment variable the server reads at startup.
- The new server is pinned to the old port with
CLAWBOO_API_PORTand waits up to 15 seconds for it to free (CLAWBOO_AWAIT_PORT). If something else took the port in between, the new server starts without the pin and picks a port the usual way. - With nothing running, it starts a server. It starts none while the port named in
api-port.txtis still held, by a server too busy to answer or by a Clawboo server that answers there (under anotherCLAWBOO_API_PORT, or brought back by a supervisor): two servers would share one database. It says which, and exits 1; for a server that does not answer, it prints a command that stops the server’s process by hand (lsof -nP -iTCP:<port> -sTCP:LISTEN -t | xargs kill; on Windows,netstatthentaskkill). - If the stop fails, it exits 1 and does not start a replacement, so you never end up with two servers.
- If the new server never answers, it prints “The previous server was stopped and could not be replaced. Nothing is running now.” and exits 1.
pnpm dev, the dev script supervises the server and may start it again on its own. Restart through the dev script there.
Waiting for agent runs
clawboo stop and clawboo restart do not cut off an agent halfway through a task. Before they stop the server, they hold it through POST /api/system/hold under the owner id clawboo-stop-<pid> or clawboo-restart-<pid>:
- The held server starts no new agent run. A run that would start (a task, a chat turn, a Routine) waits instead, and runs already going carry on.
- The command polls the server every second until no agent run is going, then stops it. It renews the hold every 20 seconds while it waits, and places it again at once if a poll finds it gone (the server restarted meanwhile). The hold lasts 60 seconds, so a
clawboo stopthat is killed leaves the server free to start work again within a minute. A poll that fails is retried. After three in a row the command checks the server’s port: if nothing listens there any more, the server is gone and the command finishes the stop. If the server still listens but does not answer, it is not stopped, because agent runs were going at its last answer: the command prints “The server stopped answering while N agent runs were going, so it was not stopped.” with a command that stops the server’s process by hand (lsof -nP -iTCP:<port> -sTCP:LISTEN -t | xargs kill; on Windows,netstatthentaskkill), and exits 1.--forcewould not help: it finds the server through the same requests that went unanswered. - Press Ctrl+C during the wait to cancel. The command releases the hold, prints “Cancelled. Clawboo keeps running and starts new work again.” and exits 130 without stopping anything. If the release does not go through after two tries, it says the server starts new work again within a minute, when the hold lapses.
- If the stop then leaves the server running (it fails, or it finds no server to stop), the command releases the hold, so that server starts new work again. Whenever it cannot release a hold it placed, on any of these paths, it says the server starts new work again within a minute, when the hold lapses.
- A server older than this feature cannot be held. The command then stops it at once, as before.
- A server that gives no usable answer to three requests for the hold (no answer, a server error) is not stopped: whether agent runs are going is unknown. The command prints “The server did not answer the request to hold its agent runs, so it was not stopped.”, the command that stops the server’s process by hand, and exits 1.
clawboo launcher’s own offer to restart an older server it finds does not wait: it stops that server at once.
clawboo open
With
--print, the link is the only thing written to standard output, so you can pipe it, and a note goes to standard error. Use it on a computer with no browser, or for another browser on this computer. The link names 127.0.0.1; through an SSH tunnel that forwards the same port it opens as printed, and from another computer on the network, use this computer’s address in its place. On a server with no access token, it prints the plain address and says no sign-in is needed. On a server older than one-time links, it prints the plain address and suggests clawboo restart.
Signing in a browser
Every/api/* request needs the access cookie when the server has an access token. A server started with STUDIO_ACCESS_TOKEN unset locks itself with the per-install token in ~/.clawboo/access-token, so that is every install unless you set STUDIO_ACCESS_TOKEN yourself or set it blank to turn the gate off. The CLI asks the server for a one-time sign-in code (POST /api/access/launch-code) and opens ?access_code=<code>, which the server trades for the cookie once, within two minutes. The access token itself never goes into a URL or the command line of the program that opens your browser. Security has the details.
Token-gated installs
The CLI uses the same token as the server:STUDIO_ACCESS_TOKEN from the shell you run it in when it is set, no token when it is set blank, and otherwise the token in ~/.clawboo/access-token (it follows CLAWBOO_HOME), which it only reads. A server that clawboo starts gets the shell’s environment, so both pick the same token. The CLI asks each port without the token first. A port is asked again with the token as the cookie only when it answers with the access gate’s own refusal, which names Clawboo, and it is the port the server recorded in api-port.txt, at the address above. From 0.9.0 that record must also not be shown stale by the start marker: a server that crashed leaves its port file behind, and another program may hold the port by then. So another service in the port range, or another user’s program imitating the gate, never receives it. That includes a STUDIO_ACCESS_TOKEN set in the shell: CLAWBOO_API_PORT alone never qualifies a port, since it stays set while the server is down. For a server whose api-port.txt this shell cannot see (one in a container, or with another CLAWBOO_HOME), point CLAWBOO_HOME at that server’s folder, or manage it with its own service manager. A server that cannot write api-port.txt logs a warning that the CLI cannot sign in to it.
- The CLI has the server’s token.
clawboo,clawboo open,clawboo stopandclawboo restartwork as they do on an install without a token, and the browser opens signed in. A server older than one-time links cannot give a sign-in code; withSTUDIO_ACCESS_TOKENset,clawboothen prints “STUDIO_ACCESS_TOKEN is set. If the dashboard does not load, openhttp://127.0.0.1:<port>/?access_token=<token>once in this browser.” - The CLI has no token, or a different one. This happens with a server started with a
STUDIO_ACCESS_TOKENthat this shell does not have. The CLI can still tell that a Clawboo server is answering, because the access gate’s refusal names Clawboo.clawbooprints “A Clawboo server is running on port N, but it requires an access token.”, a line saying to set the server’s token in this shell (or that this shell’s token is not the server’s), and the address to open once,http://127.0.0.1:<port>/?access_token=<token>. Then it exits 1 without starting a second server.clawboo openprints the same notice and exits 1.clawboo stopandclawboo restartprint it with a manual stop command, then exit 1. They never signal a process they could not identify.
- macOS and Linux
- Windows
clawboo backup
<CLAWBOO_HOME>/clawboo.db (default ~/.clawboo/clawboo.db) read-only and uses SQLite’s online backup, so it is safe while the server runs and the copy includes the latest writes. The result needs no -wal or -shm files beside it.
It prints the file’s path and size. With no database yet it prints “No Clawboo database found at” the path, “Start the server once to create it, or set CLAWBOO_HOME.”, and exits 1.
To restore, stop the server (
clawboo stop) and copy the backup over clawboo.db. A database backup does not include ~/.clawboo/secrets/, where your saved provider keys and the key that decrypts them live. The copy is owner-only (mode 0600, like the live database) before anything is written to it, and a failed backup removes its partial file. It holds your chats and settings, so keep it private. Data and state covers what a full backup needs.
clawboo agent-user
--pool, a user per agent (Linux only for now). Neither action starts the dashboard. Both run inside the server bundle, so check is the same check the server runs at every start with CLAWBOO_AGENT_USER or CLAWBOO_AGENT_USERS set.
check ends with “Agent isolation is ready: agents will run as” the user (for a pool, “each agent will run as its own user”), and exits 0, with or without warnings. Otherwise it ends with “Agent isolation is not ready. Fix the failed step and run the check again.” and exits 1. With neither CLAWBOO_AGENT_USER nor CLAWBOO_AGENT_USERS set, it prints how to set CLAWBOO_AGENT_USER and exits 1. Any action other than plan or check prints error: unknown agent-user action '<action>' (use plan or check) and exits 1. What the startup check proves lists the steps.
Exit codes
Every command exits 0 on success and 1 on failure. Any command also exits 1 on Node older than 22.12 or when given an unknown subcommand.clawboo stop and clawboo restart exit 130 when you cancel their wait for agent runs with Ctrl+C.
Environment variables
These are the variables the CLI itself reads or sets. Everything else in your shell passes through to the server unchanged; the server reads many more, listed in Environment variables.MCP stdio bins
The package also installs four MCP servers that speak over stdio. You add them to an agent program you set up yourself (for example, your own Claude Code or Codex); Clawboo’s own agents reach the same servers over HTTP inside the dashboard server.
By default the bins open
~/.openclaw/clawboo/clawboo.db, which is a different file from the dashboard’s ~/.clawboo/clawboo.db. To work on the dashboard’s board and memory, set CLAWBOO_DB_PATH to the dashboard’s file. The stdio snippet from GET /api/mcp/config?transport=stdio already includes it. The bins and the server can use the same file at once.
- The memory bin looks for an embedding provider every 60 seconds: a local Ollama with
nomic-embed-textathttp://localhost:11434, thenOPENAI_API_KEYwhen remote embeddings are allowed. With neither, memory search is keyword-only. - The tools bin offers the two built-in tools,
echoandnote, andread_tool_result. It has no connector tools. - A stdio caller has no Clawboo identity: TeamChat tools take the author and team as arguments.
Under the hood
Under the hood
- The
clawboobin isdist/bootstrap.js. It checks the Node version before loading any dependency, because the CLI is CommonJS that loads ESM-only packages, which Node 22.0 to 22.11 cannot do. Each subcommand repeats the check. - The version is compiled in from
apps/cli/package.json; running the source directly reports0.0.0-dev. - The MCP bins are bundled with their dependencies, except
better-sqlite3,ws,pinoandpino-pretty, which resolve from the CLI’s own dependencies. The OpenTelemetry packages are left out. - The CLI reads the database only for
backupand never changes settings or the vault. Its own writes are creating~/.clawboowhen missing, appending toserver.log, and removing a staleapi-port.txt. clawboo agent-userrunsnode dist/server.js --agent-user <action>, socheckis the server’s own code (apps/cli/src/agentUser.ts,apps/web/server/lib/agentUser/cli.ts).- Source of truth:
apps/cli/src/index.ts,apps/cli/src/lifecycle.ts,apps/cli/src/server-log.ts,apps/cli/src/node-version.ts,apps/cli/src/versionCheck.ts.
Related
- Installation: install Clawboo and run it the first time
- Data and state: everything under
~/.clawboo, full backup and reset - Environment variables: every variable the server reads
- Limits and defaults: the timeouts on this page next to every other number
- Troubleshooting: fixes for a start timeout and other errors