openclaw.json, approve a device-pairing request, and list the model catalog. The dashboard’s OpenClaw setup and Manage section in Settings > Runtimes, the System panel and the update chip call them. The last routes are about Clawboo itself: which release this server runs and what it supports (self-version, capabilities), whether it is up at all (live, from 0.9.0), installing a newer one (self-update), holding new agent runs back before a stop (hold), what a host that stops an idle server needs to know (idle, presence), and the settings an administrator can pin (operator-settings).
Every route here except
self-version, live, capabilities, self-update, hold, idle, presence and operator-settings is for OpenClaw. OpenClaw runs as its own Gateway process that Clawboo starts and talks to, so its lifecycle lives here. /api/runtimes covers Clawboo Native (built in), Claude Code, Codex and Hermes, and the agent registry is in the Agents API.POST /api/system/install-openclaw and POST /api/system/self-update always, and POST /api/system/gateway for start and restart. Each is documented with an event catalog (event type and payload). Request bodies are JSON (up to 2 MB). Every route counts against the general rate limit of 3,000 requests a minute per client address, except GET /api/system/live, which has a limit of its own (from 0.9.0); routes marked sensitive also count against a limit of 60 a minute. Add the access cookie to each curl example (see Authentication).
Routes
GET /api/system/status
Returns one snapshot of the Node runtime, the OpenClaw install and the Gateway process. The dashboard reads it at startup to decide what to show, and the OpenClaw setup and the System panel read it for the Gateway’s state. When the Gateway is running and .env exists, the call also copies the Gateway token from .env into Clawboo’s settings, so Clawboo never connects with a stale token.
The OpenClaw check looks in Clawboo’s runtimes folder first, then on PATH. For Clawboo’s own copy the version comes from its install record, and nothing is spawned. For a copy on PATH the check is cached per binary path and gives up on openclaw --version after 6 seconds, so a slow first start never holds up the server. installed says whether either was found; version is null when the version check timed out or failed (the binary still reads installed).
While nothing uses the Gateway (gateway.inUse: false, see How Clawboo connects), the call does not probe the Gateway’s port: a probe is a connection, and it would start a Gateway that a service manager starts on its first connection. running then says only whether a Gateway that Clawboo started is still alive, and the dashboard loads without connecting to the Gateway.
- Path/query params: none.
- Request body: none.
Responses
200 OK: the status snapshot:
500 Internal Server Error: any failure assembling the snapshot:
Example
POST /api/system/install-openclaw
Installs OpenClaw into Clawboo’s own runtimes folder, never into npm’s global folder, so it never needs sudo. Set up OpenClaw and Check for Updates in Settings > System call it.
- Node.js first. OpenClaw will run on the Node.js the server runs on, so the route checks that version against OpenClaw’s range,
>=24.22.1 <25 || >=26.12.1. Outside it, the stream sends oneNODE_UNSUPPORTEDerror and installs nothing. npm itself would not refuse such a Node: it would install an older OpenClaw release. - One install at a time. A request while an OpenClaw install is running gets an
INSTALL_RUNNINGerror. - npm into a new folder. npm runs on the server’s Node (the npm beside it, else the one on
PATH) asnpm install --prefix <new install folder> --include=optional --no-fund --no-audit openclaw@~2026.9, under umask 022 and withoutnpm_config_global,npm_config_locationandnpm_config_prefix. The pin is~2026.9(not@latest, and not^2026.9, which would allow any 2026.x) so a new install gets an OpenClaw whose config format matches what Clawboo writes. - Switch on success. The install becomes current, and its launcher,
<runtimes folder>/bin/openclaw, starts OpenClaw on that Node. The previous install is kept and older ones are removed. A failed or stopped install is removed, and the current one is untouched.
openclaw doctor --fix, device approval, the model list and the ChatGPT sign-in all use that launcher when it is there, else an openclaw on PATH. A Gateway that something else runs, such as OpenClaw’s own launchd service on port 18789, is left alone.
- Path/query params: none.
- Request body: none.
Responses
200 OK + text/event-stream: the stream sends data: <json>\n\n frames with Cache-Control: no-cache. If the client closes the connection, the install is stopped and its folder removed.
Event catalog
The
error codes:
When npm fails, the message reads
Installation failed with exit code <n>. followed by npm’s own reason. On success, complete carries the installed version ('unknown' when it could not be read) and path, the launcher in the runtimes folder.
Example frames:
Example
POST /api/system/configure-openclaw
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Writes a fresh openclaw.json and .env for one provider, makes a new Gateway token, and saves the Gateway URL and token in Clawboo’s settings. No dashboard screen calls this route; it is for scripts and manual setup. The dashboard’s OpenClaw setup (in Settings > Runtimes and onboarding’s Add more runtimes step) uses POST /api/system/auto-configure-openclaw instead, and when that answers needsKey it saves the key you paste with POST /api/providers/:id/connect and calls auto-configure again.
The written openclaw.json holds only: gateway (mode: 'local', the port, token auth read from GATEWAY_AUTH_TOKEN), the default model under agents.defaults.model.primary, OpenClaw’s tool sandbox turned off (agents.defaults.sandbox.mode: 'off'), agent-to-agent coordination (tools.agentToAgent.enabled: true, tools.sessions.visibility: 'all'), and for Ollama an optional models.providers.ollama entry. With the sandbox off, OpenClaw runs its agents’ tools on the host, the computer Clawboo and its other agents use, rather than in a Docker or Podman container of its own. off is OpenClaw’s default; the route writes it so it holds if a later OpenClaw changes that default. The written .env holds GATEWAY_AUTH_TOKEN=<64 hex characters> plus one key line, and only its owner can read it (mode 0600). The route also creates ~/.openclaw/workspace. The token is kept on the server and never returned.
- Path/query params: none.
- Request body:
model is omitted: anthropic/claude-sonnet-4-5, openai/gpt-5.4, google/gemini-3.6-flash, openrouter/anthropic/claude-sonnet-4-5, xai/grok-3, groq/llama-3.3-70b-versatile, mistral/mistral-large-latest, moonshot/kimi-k2.5, minimax/MiniMax-M2.5, together/meta-llama/Llama-3.3-70B-Instruct-Turbo, nvidia/llama-3.1-nemotron-70b-instruct, huggingface/deepseek-ai/DeepSeek-R1, cerebras/zai-glm-4.7, venice/llama-3.3-70b, and for ollama a pulled model (below). Any other provider gets <provider>/default. openai-codex (the ChatGPT sign-in) gets your plan’s own default model as openai-codex/<model>, read from your Codex CLI through GET /api/runtimes/codex/models. OpenAI decides which models each plan may use, so Clawboo names none of its own: when that list is unknown, openclaw.json gets no default model and OpenClaw applies its own.
The key line in .env uses the provider’s own variable (for example ANTHROPIC_API_KEY, GEMINI_API_KEY for google, HF_TOKEN for huggingface). A provider with no known variable gets CUSTOM_API_KEY. openai-codex (the ChatGPT sign-in) writes no key line: OpenClaw uses its own sign-in profile, created with openclaw models auth login --provider openai-codex.
ollama works differently, because OpenClaw runs only a model the local Ollama has pulled and loads its Ollama provider only when it has a credential:
- The model is checked against Ollama’s
/api/tags. The requested model (orllama3.2when none is sent) is kept when it is pulled; otherwise the route writes the most recently pulled model, preferring one that can use tools, the same pick a new Clawboo Native agent gets. With no chat model pulled, or Ollama not answering, the request stands. It is always written as anollama/<model>ref. .envgetsOLLAMA_API_KEY=ollama-local, the marker OpenClaw accepts for a local Ollama. It is not a secret.- OpenClaw calls
http://127.0.0.1:11434and does not readOLLAMA_BASE_URL. When that variable is set, the route writes its address (without/v1) tomodels.providers.ollama.baseUrl, so OpenClaw uses the same Ollama whose models were checked.
Responses
400 Bad Request: the body is missing or not an object:
400 Bad Request: provider is missing or empty:
400 Bad Request: a keyed provider with a missing or empty apiKey:
200 OK: both files written, the token made and saved:
model is the default written to openclaw.json. For ollama it can differ from the model you sent, when Ollama has not pulled that one. It is null for openai-codex when your plan’s model list is unknown, and then no default is written.
500 Internal Server Error: a file or token failure:
Example
POST /api/system/auto-configure-openclaw
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Sets up OpenClaw from a credential you have already connected, so the OpenClaw setup never asks for a key it could find itself. The dashboard’s OpenClaw setup calls it first and shows the key prompt only when this route finds nothing to use. Unlike configure-openclaw, it keeps what is already in openclaw.json and .env (see the list after the responses).
- Path/query params: none.
- Request body: none (ignored).
In step 1, with several keys connected, the route takes the first in this fixed order, not your default native provider: anthropic, openai, google, openrouter, xai, groq, mistral, moonshot, minimax, together, nvidia, huggingface, cerebras, venice. A provider counts as connected when its key is in the vault or in
~/.openclaw/.env (a variable only in the server’s shell does not count), but the value written is the one that resolves first: the server’s environment, then the vault, then .env.
In step 2 a missing default model becomes your plan’s own default (openai-codex/<model>, read from your Codex CLI through GET /api/runtimes/codex/models). When that list is unknown, none is written and OpenClaw applies its own.
Step 3 exists because a codex login in your terminal is a ChatGPT subscription that OpenClaw cannot use until it holds a sign-in profile of its own. loginCommand is openclaw models auth login --provider openai-codex. When the OpenClaw found is Clawboo’s copy, openclaw is replaced by its launcher’s full path (quoted when it needs it), since the runtimes folder is not on your PATH. The dashboard runs it for you through POST /api/auth/cli-login/openclaw and shows the command only if that fails.
Step 4 uses the same Ollama setup Clawboo Native reads: you picked Ollama in onboarding or pressed Use on it in Clawboo Native’s Manage, or no choice is recorded and OLLAMA_BASE_URL is set. Disconnect Ollama, or a full disconnect of Clawboo Native, turns it off again. It is the last resort before the key prompt. It writes what configure-openclaw writes for ollama: OLLAMA_API_KEY=ollama-local in .env, a default model your Ollama has pulled (when llama3.2 is not pulled, the most recently pulled model, preferring one that can use tools, always as ollama/<model>), and, when OLLAMA_BASE_URL is set, its address as models.providers.ollama.baseUrl.
Responses
200 OK (steps 1, 2 and 4): openclaw.json was written and the Gateway URL and token saved in Clawboo’s settings. provider is the provider that matched ('openai-codex' for step 2, 'ollama' for step 4):
pullCommand before it starts the Gateway, with Check again (which calls this route again) and Continue anyway.
200 OK (steps 3 and 5): nothing was written; the body says which prompt to show:
500 Internal Server Error: a file or token failure:
- The Gateway token.
GATEWAY_AUTH_TOKENin.envis reused; a new token is made only when there is none. - Your
openclaw.jsonsettings. Onlygateway.modeis set (to'local').gateway.port,gateway.auth, the default model,agents.defaults.sandbox(as{ mode: 'off' }),tools.agentToAgent,tools.sessionsand, in step 4,models.providers.ollamaare filled in only when missing. A sandbox you set up yourself stays. - An existing
OLLAMA_API_KEY. Step 4 keeps one that has a value, since any value lets OpenClaw load its Ollama provider. - The port. There is no
gatewayPortinput. A missinggateway.portbecomes18789; an existing one is left alone.
gatewayUrl uses the port the Gateway route will use: the port in Clawboo’s Gateway PID file, then gateway.port when it is a positive number, then 18789. So a Gateway you moved to another port is the one Clawboo connects to.
Example
POST /api/system/gateway
Starts, stops, restarts or reports on the Gateway process. action picks the operation. A start runs Clawboo’s own OpenClaw from the runtimes folder when there is one, so the Gateway runs on the Node.js that installed it, else the openclaw on PATH. status and stop return JSON; start and restart stream SSE, because they wait for the port to open and report progress. The port comes from Clawboo’s Gateway PID file, then gateway.port in openclaw.json, then 18789.
A start or restart is a need for the Gateway: the server connects to it (see How Clawboo connects), also when the start finds it running already. status probes the port only once something uses the Gateway, as in GET /api/system/status.
- Path/query params: none.
- Request body:
Responses
400 Bad Request: body is missing or not an object:
400 Bad Request: action is not one of the four values:
200 OK (action: 'status'): current process state (a stale PID file is cleaned up as a side effect):
200 OK (action: 'stop'): the stop result. stopped: true means a process was signalled (SIGTERM, then SIGKILL after a 2-second grace). When none was found, the body is { ok: false, message } instead:
200 OK + text/event-stream (action: 'start' or 'restart'): the stream sends data: <json>\n\n frames. restart first stops the running process. The route starts openclaw gateway --port <port> --allow-unconfigured as a detached process that keeps running when the client disconnects or Clawboo restarts. The Gateway’s output goes to ~/.clawboo/gateway.log (under CLAWBOO_HOME when set), and the stream relays new lines from that file as output frames.
Event catalog (start / restart)
Terminal
error code values:
Automatic repair. After an OpenClaw upgrade the Gateway can refuse to start until its data is migrated (for example
Legacy workspace setup state requires migration for ~/.openclaw/workspace; run openclaw doctor --fix). When a launch exits with that request, the route runs openclaw doctor --fix --non-interactive once, with OPENCLAW_SERVICE_REPAIR_POLICY=external so doctor never installs, loads or restarts a launchd or systemd Gateway service, streams its output, and launches again. Only the failure line of that launch counts, so a passing mention of doctor elsewhere in the log never triggers it. A second start or restart that arrives while the repair runs waits for it instead of launching against data that is mid-migration. The repair has a 5-minute limit.
Every launch, and the repair, runs with an explicit working directory that exists: the OpenClaw CLI refuses to start in a deleted one.
When the port opens, the route copies the .env token into Clawboo’s settings, starts reconnecting Clawboo’s own Gateway connection (which then syncs the agent list), and sends complete without waiting for that reconnect. A start that finds the port already open sends complete at once with message: 'Gateway already running'. A start that finds a Gateway Clawboo launched still starting up waits for that launch instead of starting a second one.
Example frames:
Example
GET /api/system/openclaw-config
Reads openclaw.json, flags for which provider keys OpenClaw holds (from .env and the agents’ auth-profiles.json), the exec policy, and the state of OpenClaw’s ChatGPT sign-in. The flags report presence only; no key value is returned.
- Path/query params: none.
- Request body: none.
Responses
200 OK: the config and flags:
true when its variable has a value in .env, or an agent’s auth-profiles.json holds a key for that provider. Only one agent’s file counts: the scan stops at the first agent whose auth-profiles.json holds any key. hasGoogleKey matches GEMINI_API_KEY or GOOGLE_API_KEY; hasHuggingFaceKey matches HF_TOKEN or HUGGINGFACE_HUB_TOKEN.
500 Internal Server Error: a read failure:
Example
PATCH /api/system/openclaw-config
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Changes parts of openclaw.json and, when keys are sent, writes them to .env and every OpenClaw agent’s auth-profiles.json. Every field is optional and only the fields you send are touched. A missing or unreadable openclaw.json is treated as empty. Keys sent here go to OpenClaw’s files only, not to Clawboo’s vault.
- Path/query params: none.
- Request body (all fields optional):
modelsets the default model. It also setsagents.defaults.contextTokensto the context window the OpenClaw CLI’s model catalog reports for that exact model; when the catalog has no entry,contextTokensis not written.agentModelsets one agent’s model override in OpenClaw’s roster,agents.entries.<agentId>.model. A legacyagents.listarray is folded intoagents.entriesand removed first, because OpenClaw rejects a config that has both. Amodelofnullor''deletes only the override and keeps the agent’s entry, since the entry is the agent’s place in the roster. When the roster then holds more than one agent and has noagents.ownership, it is set to'explicit'.gatewayPortsetsgateway.portand savesws://localhost:<port>as Clawboo’s Gateway URL.apiKeysupserts each key under its provider’s variable (a provider with no known variable gets<PROVIDER>_API_KEY) and as the<provider>:defaultprofile in each agent’sauth-profiles.json.agentToAgentwithenabled: truealso setstools.sessions.visibility: 'all'.
Responses
400 Bad Request: the body is missing or not an object:
400 Bad Request: agentModel.agentId is __proto__, constructor or prototype. Nothing is written:
200 OK: written. hotReloadHint is present only when the Gateway is reachable, as a sign that a client can reload its config:
500 Internal Server Error: a file failure:
Example
POST /api/system/approve-device
A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example.
Approves the most recent pending OpenClaw device-pairing request. OpenClaw does not pair a new device on its own: the device waits until a person approves it, and until then its Gateway connection fails with NOT_PAIRED (“pairing required: device is not approved yet”). The dashboard’s pairing card (Approve this device) calls this route.
It runs two commands. First openclaw devices approve --latest, which only previews: it prints the pending request’s UUID (in a line like Approve this exact request with: openclaw devices approve <UUID>) and exits non-zero. The route reads the UUID from that output, then runs openclaw devices approve <UUID> to approve it. The first command gets 5 seconds and the second 10.
- Path/query params: none.
- Request body: none.
Responses
400 Bad Request: OpenClaw is not installed:
500 Internal Server Error: the preview command could not run (not found, or timed out):
404 Not Found: the preview output named no pending request. details is its first 500 characters:
200 OK: the device was approved. output is the command’s output, up to 1,000 characters:
500 Internal Server Error: the approval command failed. The message carries its error output, up to 500 characters:
Finding the UUID depends on the wording of OpenClaw’s output (the pattern
/openclaw devices approve\s+([a-f0-9-]{36})/i). If an OpenClaw release changes that line, this route answers 404. The pairing card then shows the error, and its footer always lists the manual openclaw devices approve commands.Example
GET /api/system/models
The model catalog behind the OpenClaw model pickers. It comes from openclaw models list --all --json (cached for 5 minutes); without the CLI, the built-in catalog is used instead. OpenClaw 2026.9 refuses that listing when several agents are configured and none is named the owner (“model inspection has no explicit owner”), which an install running a Clawboo team usually is. Clawboo then asks again with --agent, naming the agent marked default, else main, else the first one configured, and keeps passing it on later refreshes until a system agent (agents.defaults.systemAgent.agentId) is configured; OpenClaw then lists as that agent by itself, and the plain command runs again. It never sends --agent to an install that did not refuse. The listing follows that agent’s sign-ins and keys. The result keeps only the 14 key providers, ollama and openai-codex, with provider names in the built-in catalog’s display spelling. A known provider the CLI does not list is filled in from the built-in catalog. The built-in catalog’s OpenAI Codex group has no models: the pickers fill it from your plan’s live list (GET /api/runtimes/codex/models) and leave it out while that list is unknown.
configuredProviders lists the providers OpenClaw can use: those with a key in .env or in an agent’s auth-profiles.json, those with a sign-in profile (for example openai-codex after a ChatGPT sign-in), and always ollama.
- Path/query params: none.
- Request body: none.
Responses
200 OK: the grouped catalog:
This route never answers with an error status. An unexpected error comes back as
{ "groups": null, "configuredProviders": [] } with status 200, so a picker can fall back to its own list.Example
GET /api/system/self-version
Which Clawboo this server runs, how it was installed, and whether a newer release is published. The dashboard’s Update available chip reads it, and so does the clawboo command when it finds a server already running (see the CLI reference).
Query parameters
With
CLAWBOO_DISABLE_SELF_UPDATE=1, or disableSelfUpdate in the operator settings file, every request answers as ?local=1 does, and applyable is false.
?local=1 is for the CLI, which reads this route each time it attaches to a running server only to compare versions. The registry check is capped at 5 seconds and a failed check is not cached, so without it an offline machine would wait on every launch.
Responses
Always200. An unreachable registry is a null latest, never an error status.
A dev checkout reports
current: "0.0.0-dev" and is never told an update is available. The chip and the CLI both treat a 0.0.0* version as “don’t nag”, and the CLI never offers to restart such a server, so a contributor’s pnpm dev process is never a target.Example
GET /api/system/live
Available from 0.9.0. Whether this server is up, for a program running beside it, a process supervisor or a load balancer that polls. It needs no sign-in: the access gate lets it through without the access token, and the identity lane without an identity token, in every mode. That is why it answers up or down and nothing else: no version, no state, nothing about the install. Use self-version or capabilities for what the server is, with the access token.
- Methods:
GETandHEAD. - Path/query params: none. Only this exact request is open: a query, a trailing slash, another letter case or another method needs the access token and, with the identity lane
required, an identity token, like any other route. A token the request does carry is checked as usual, and a bad one is refused. - Request body: none.
Responses
Both withCache-Control: no-store:
A server that is not running does not answer at all.
HEAD answers the same status with no body. It has a rate limit of its own, 600 requests a minute per client address, and does not count against the general one, so callers that have not signed in never use up the limit the dashboard shares. It sends no rate-limit headers and no X-Powered-By. The capability flag system.live says this server has the route.
Example
GET /api/system/capabilities
What this server is and which features it has: its Clawboo version, the client API revision, the oldest release whose clients it still serves, and a flat map of feature flags. A client (the dashboard, a desktop shell that bundles the server, a proxy in front of it, or an app on another device) reads it before it uses a feature, instead of calling a route to see whether it answers. The dashboard reads it after an in-app update, to tell the new server from the one that is shutting down.
The answer is built from the running process alone: no database read, no network call, nothing written. It carries no secret and no file path. The route sits behind the same-origin guard and the access token like every other /api route. A client that has not signed in gets the 401 described in Authentication, and that answer already tells it a Clawboo server is there.
- Path/query params: none.
- Request body: none.
Responses
200 OK, with Cache-Control: no-store because the answer changes when the server restarts into a new version:
Supported versions explains the window and how a client checks it.
Feature flags
A flag’s name never changes. A feature that goes away reportsfalse until the next API revision. The flags describe what the server can do, not the state of the machine: a runtime flag says the server can run that runtime, not that its CLI is installed.
For client authors
The workspace package@clawboo/control-client (in the repository, not published to npm) exports engineCapabilitiesSchema (zod), fetchEngineCapabilities(), engineHasFeature(), engineSupportsClient(), RESUMABLE_STREAMS, the schema of every event on the three resumable streams, and engineHoldStateSchema, the answer of the hold routes. A server older than this route answers 404 in development and the dashboard page (HTML, 200) once built; fetchEngineCapabilities() returns null for both.
The contract test apps/web/server/api/__tests__/clientContract.test.ts pins this answer, every route and method, the hold routes’ answer, and the stream events. It fails when one is removed or renamed without raising apiRevision.
Example
POST /api/system/self-update
Installs clawboo@latest globally and restarts the server into it, without cutting off an agent run. Streams Server-Sent Events. The request body is optional: { "force": true } restarts without waiting for agent runs.
Only a global install can update itself. An npx run lives in npm’s _npx cache, so a global install lands somewhere the running copy cannot reach, and a dev checkout never updates itself. A global install whose package folder, the folder holding it, or the prefix’s bin folder (where npm links the clawboo command) the server’s user cannot write is refused too, as is any install whose administrator turned in-app updates off. Each gets one unsupported event naming the reason and the command to run instead (the chip hides its button in those cases anyway).
Waiting for agent runs
An update holds the server from its first event, under the owner idself-update (see Drain and hold), so no new agent run starts while npm installs. An install that takes longer than 5 minutes stops holding, so a stalled npm does not keep agent work waiting; the update holds again once the install lands. Once the new version is installed, the server waits for the agent runs already going, then restarts. It waits at most 10 minutes; at that bound it restarts anyway, which interrupts the runs still going. While it waits it sends a progress event with step: 'waiting' each time the number of runs changes, and a : keepalive comment every 15 seconds, so a proxy does not close a quiet stream. A browser that disconnects during the wait does not cancel the restart, because the new version is already on disk. An update that ends without a restart (a failed install, or installed-elsewhere) releases its hold, and one refused with unsupported never holds.
{ "force": true } skips the wait. Sent with a new update, the server restarts as soon as the install lands. Sent while an update is waiting, it makes that update restart now and answers with one forced event; the waiting update’s own stream then reports restarting. The update chip’s Restart now button sends it. One update runs at a time: a second request without force gets an error event with code: 'IN_PROGRESS'.
Event stream
On a non-zero exit,
detail is npm’s own reason in one line (the Error: line, or the first line of its error block, or the name of a package whose install script failed), and message leads with it, so the chip shows why rather than only an exit code. detail is null when npm’s output named no reason.
npm runs in a working directory that exists, because npm exits with code 7 when its working directory has been deleted.
After restarting, the server starts a new server on the same port (CLAWBOO_API_PORT), told to wait until that port is free (CLAWBOO_AWAIT_PORT), and then exits so the new one can bind. The new server starts in a working directory that exists, and a server that does start in a deleted directory moves into the Clawboo directory before it loads anything. CLAWBOO_VERSION is removed from its environment, so it reads its version from the newly installed package. It starts with the old server’s node options (process.execArgv, such as --max-old-space-size=4096), except the inspector’s, whose port the old server still holds. The browser keeps polling the same address and reloads when the new server answers. The browser polls GET /api/system/capabilities and reloads once a server on a different version answers.
installed-elsewhere means the global install landed somewhere this running copy does not point at, so a restart would run the old code again. The server stays up and asks you to restart it yourself.updateCommand that self-version reports, then clawboo restart (see the CLI reference).
Example
Drain and hold
Anything that stops or restarts the server can first ask it to hold:clawboo stop, clawboo restart, a desktop app’s updater, a process manager’s stop script. A held server starts no new agent run, and the runs already going carry on to their end. The caller waits until backgroundWork is none, then stops the server, so no agent is cut off halfway through.
While the server is held:
- A run that would start waits instead, in the same queue that holds runs back when
CLAWBOO_MAX_CONCURRENT_RUNSis reached. That covers board task runs, team chat turns, 1:1 chat turns with Clawboo Native, Claude Code, Codex and Hermes agents, the turns of a peer exchange and Routine runs on any runtime. A run that is waiting is not failed and does not count against any time limit. - Clawboo’s Routines scheduler fires nothing. A Routine that falls due stays due and fires once the hold lifts, or after the next start.
- Team chat claims no board task. A task agents hand each other stays in To do instead of waiting
in_progress, and the board’s dispatch pump, which starts those tasks, skips its pass.
server-stop, so no run starts during the seconds it waits for its runs and runtime processes to end. The hold lives in memory and ends with the process: the next start is not held.
The hold covers the runs this server starts. A 1:1 chat with an OpenClaw agent, and OpenClaw’s own scheduled jobs and messaging channels, run inside the OpenClaw Gateway: they are neither held nor counted in backgroundWork, and stopping the server does not stop them.
A hold belongs to the owner id its caller picks, and only that id releases it. Each hold lapses after its time to live, 60 seconds unless the caller asks for another, so a caller that crashes cannot leave the server held. To hold for longer, place the hold again before it lapses: that renews it. Several callers can each hold at once; the server stays held until every hold is gone. Holds live in memory, so a restart clears them.
A typical stop:
POST /api/system/holdwith your owner id.- Poll
GET /api/system/holduntilbackgroundWorkisnone. Place the hold again every 20 seconds or so while you wait. Give up at a bound of your own. - Stop the server. To cancel instead,
DELETE /api/system/hold/<owner>.
work.routinesInFlight on GET /api/system/idle (Sleep and wake) counts these fires).
GET /api/system/hold
- Path/query params: none.
- Request body: none.
200 OK:
Each entry in
holds:
POST /api/system/hold
Holds the server, or renews the hold this owner already placed. Body:
DELETE /api/system/hold/:owner
Releases the hold owner placed. No other owner’s hold is touched.
Example
Sleep and wake
A host can stop the server when nobody is using it and start it again when it is needed: a process supervisor, a service manager, a desktop app, or a computer that sleeps when idle. Before it stops the server it needs three answers, andGET /api/system/idle gives all three in one read:
-
Is a person here? Not “is anything asking”. An open board polls the API dozens of times a minute whether or not anyone is looking at it, so request traffic says nothing about people. A person counts as here for 60 seconds after either of these:
- A presence beat a client sends on purpose (
POST /api/system/presence, below). The dashboard sends one every 20 seconds while its tab is visible and focused and someone has touched the page in the last 15 minutes, and one more as that stops. Opening the page or switching to it counts for 2 minutes without a touch, so a window restored on its own, or left focused on a locked screen, soon stops counting. A hidden or background tab sends nothing. - Something a person does, seen by the server from any client (the dashboard, the API, a linked device): answering an approval or an agent’s question, sending a chat message or a comment, and creating, moving, retrying, reopening, assigning, stopping or pausing work, or pressing Run now. Beyond those, any other write the identity lane names a person on counts too, except the automatic writes listed below.
- A presence beat a client sends on purpose (
-
Is work going? The same answer as
GET /api/system/hold(Drain and hold):backgroundWorkispresentwhile an agent run or a team chat’s work check is going.routinesInFlightcounts routine fires that have begun, a due OpenClaw routine waiting for the Gateway to connect included: it runs or fails within 5 minutes, and stopping the server meanwhile would only mean starting it again for it. - When is scheduled work next due? The earliest next run across every schedule: Clawboo’s own routines, the cron jobs of an OpenClaw Gateway that stops when this machine does, and the jobs of a Hermes gateway Clawboo runs. A Gateway counts unless its address is another machine’s IP address; a name this server cannot place (a LAN or tailnet name) counts, since waking for jobs that would have run anyway only costs a wake. Wake the server a minute before it.
- Read
GET /api/system/idleevery 30 seconds or so. - Wait until
people.presenthas beenfalse,work.backgroundWorkhas beennoneandwork.routinesInFlighthas been0for as long as you like (a few minutes;people.lastSeenAtandpeople.lastActedAtlet you measure your own window). Compare times withat, the server’s own clock, rather than yours: a virtual machine’s clock can fall behind after a sleep. - Drain the server as in Drain and hold, note
nextDue.at, and stop it. - Start it again a minute before
nextDue.at, or when a person asks for it. WhennextDue.completeisfalse, a source could not be read and something may be due sooner, so pick a shorter bound of your own.
What the dashboard sends on its own
So a host can check its idle rule against them, these are the requests an open dashboard sends without anyone doing anything. None of them counts as a person. Writes. Several of these routes are also used when a person does something (saving a file, creating a team); they never count either, because the server cannot tell the two apart.
Reads, which never count anyway. While its tab is visible the dashboard polls, depending on what is open: pending approvals and an agent’s latest browser frame every 3 seconds; the board, the run graph’s health and the budgets every 5 seconds; runtimes, fleet health and routines every 8 seconds; system status, previews and a task’s workspace every 10 seconds; workspaces and an agent’s routines every 15; routine runs, System Health and runtimes every 30; the memory provider every 2 to 30; brokered apps every 60 to 120. A hidden tab polls nothing, except that with background alerts on it reads the board and pending approvals when something happens. Event streams stay open:
GET /api/obs/stream from every open dashboard, hidden or not, and the chat streams of an open chat.
GET /api/system/idle
- Path/query params: none.
- Request body: none.
- Answers with
Cache-Control: no-store. Reading it writes nothing and starts nothing.
200 OK:
Each entry in
nextDue.sources:
What counts as due, for Clawboo’s routines: a routine waiting for its next time, and one that is due and not yet fired (its time passed, or someone pressed Run now). A paused routine, one stopped after a failure, a spent one-time routine, one on an archived team, and one whose agent or team is paused are not counted: they do not run until a person acts, and a person acting brings the server up anyway. A routine that is running is work, not due. For the Gateway’s cron jobs: enabled jobs with a next run.
POST /api/system/presence
A client says whether a person is at it. Send one beat when that changes and every 20 seconds while a person is there; a beat counts for 60 seconds. Each client names its own tab or window with a tabId, so its later beats replace its earlier ones.
Presence lives in memory, so a server that just started has seen nobody until the next beat.
Example
GET /api/system/operator-settings
The settings an administrator can pin for everyone on this install, with the value in force and where it comes from. The Deployment card in Settings > System reads it. Pin settings for everyone explains the file.
Responses
200 with { "settings": [...] }, one entry per key, in this order: disableSelfUpdate, disableBrowserAutostart, catalogIndexUrl, then the proxy identity keys from proxyIdentity to proxyIdentityRoles, then proxyIdentityControlClaim and personCheck (from 0.9.0), with proxyIdentityReaderPublicKey between them from 0.9.0, then the provider base URLs from anthropicBaseUrl to moonshotBaseUrl.
Example
PUT /api/system/operator-settings/:key
Saves a value for a key the dashboard offers, today only disableBrowserAutostart. There is one value per install, so it applies to everyone who uses it. It never writes the operator file. Body: { "value": true } or { "value": false }.
Responses
Example
Error envelope
Errors use the standard{ "error": string } body. approve-device adds details on its 404 and requestId on the 500 from the approval command. GET /api/system/models never returns an error status; it falls back to a 200 with a null catalog. The SSE routes report failures as error frames once the stream is open. Going over a rate limit answers 429 with { "error": "Too many requests. Wait a moment and retry." } (general) or { "error": "Too many requests for this operation. Wait a moment and retry." } (sensitive), plus a Retry-After header.
Source of truth: apps/web/server/api/system.ts, systemUpdate.ts, systemCapabilities.ts, systemHold.ts and operatorSettings.ts; the hold in apps/web/server/lib/engineHold.ts and the run queue it gates in apps/web/server/lib/runSlots.ts; the version check in apps/web/server/lib/updateCheck.ts; the feature flags in apps/web/server/lib/engineCapabilities.ts; pinned settings in apps/web/server/lib/operatorSettings.ts; key files in apps/web/server/lib/openclawEnv.ts.
Related
- OpenClaw: set up OpenClaw, the Gateway and device pairing in the dashboard.
- System: Gateway control and OpenClaw settings in the System panel.
- System Health: the start-up checks behind
/api/health. - Settings API: the saved Gateway URL and token these routes write.
- Runtimes API: Clawboo Native, Claude Code, Codex and Hermes.
- REST API overview: authentication, rate limits and conventions.