Skip to main content
Three small surfaces: the OpenClaw Gateway connection settings, the boot report the System Health panel shows, and the node positions the dashboard saves for its graphs. Use this page when you point Clawboo at a Gateway from a script, or check an install’s health from a monitor. Examples use the default port 18790. Add the access cookie to each curl, as shown under Authentication. All six routes are on the general rate limit described in the REST API overview.

Routes

Settings

Clawboo keeps the Gateway URL, the Gateway token and the time the first-run notice was dismissed in <clawboo home>/settings.json (~/.clawboo/settings.json unless CLAWBOO_HOME is set). Most other dashboard settings live in the SQLite settings table and are not served here. No route returns the Gateway token. The server adds it itself when it connects to the Gateway, so the browser never needs it. Errors use { "error": "<message>" }.

GET /api/settings

Responses

200 OK:
gatewayUrl is the first of:
  1. the URL saved in settings.json;
  2. ws://localhost:<port>, when no token is saved and OpenClaw’s openclaw.json has both a Gateway token and a port;
  3. ws://localhost:18789.
hasToken is true when a Gateway token resolves: the token saved in settings.json (a ${VAR} value is read from the environment, then from OpenClaw’s .env), or else the gateway.auth.token in OpenClaw’s openclaw.json. So it can be true with nothing saved in Clawboo. OpenClaw’s files are in its state directory, ~/.openclaw by default. 500 Internal Server Error: the settings could not be read, { "error": "<message>" }.

Example

POST /api/settings

Saves only the fields you send; the rest keep their values, so a dismiss-only request leaves the Gateway URL alone. A field of the wrong type is ignored rather than rejected.
  • Request body:
The URL is checked after trimming, and only a ws: or wss: URL is accepted, because the server later connects to it. After you clear it, GET returns the fallback above. Changing gatewayUrl or gatewayToken makes the server reconnect to the Gateway in the background.

Responses

200 OK: { "ok": true }. 400 Bad Request: the body is missing or not a JSON object:
400 Bad Request: a non-empty gatewayUrl that is not a ws:// or wss:// URL:
500 Internal Server Error: saving failed, { "error": "<message>" }.

Example

Health

The server runs a boot probe at startup and keeps the result: one pass or fail per check, plus what the install resolved (folders, port, vault). The System Health panel shows it. These routes answer with the Gateway down, and ok (true when no check is fatal) is the one field a monitor needs. Responses pass through the same redaction as the logs, so a credential-shaped string inside a check’s message is masked. On failure the health routes answer { "ok": false, "error": "<message>" }.

GET /api/health

Returns the latest boot report. A request that arrives before the first report exists computes one.

Responses

200 OK: the boot report (see The boot report below), with ok added. Dates are ISO strings. 200 OK while the server moves older work into the work folder at startup (see The work folder): { "ok": false, "status": "migrating", "migration": { "total": <n>, "done": <n>, "left": <n> } }. Until the move ends, every other request answers 503 with a Retry-After: 2 header and { "error": "Clawboo is moving its work folders. Try again in a moment.", "status": "migrating" }, and a WebSocket upgrade gets 503 too. The HTTP answers come after the access gate, like any other. A WebSocket upgrade is refused before the origin and access checks, with no body. 500 Internal Server Error: computing a first report failed, { "ok": false, "error": "<message>" }.

Example

POST /api/health/recheck

Runs the boot probe again: the Re-run probe button in System Health. It runs SQLite’s full integrity_check, where the boot probe runs the quicker quick_check, so on a large database the answer can take several seconds; the server keeps answering other requests meanwhile. When the Gateway cannot be reached, the answer also waits out the Gateway check, about 1.5 seconds. Takes no body.

Responses

200 OK: the new boot report, the same shape as GET /api/health. 500 Internal Server Error: { "ok": false, "error": "<message>" }.

Example

The boot report

Most failures only degrade: the server keeps running and the panel shows a warning, so a degraded install still answers ok: true with a non-empty degraded. Three failures are fatal: clawbooHomeWritable, databaseIntegrity and databaseSchema. Each failed check’s detail says what to do; resetting the Clawboo home folder is the last resort (see Data and state). The checks, in the order they run: config reports the defaults this build ships, not live overrides: logLevel reads info even when LOG_LEVEL is set. Only otelConfigured and otelActive reflect this boot.

Graph layout

The node positions the dashboard saves when you drag nodes on a graph, stored in the SQLite graph_layouts table under a pair of keys: a layout name and a Gateway URL. The URL is only part of the storage key: when the dashboard runs without a Gateway, it saves under ''. Errors on POST use { "ok": false, "error": "<message>" }. In a loose- layout the position keys are node ids such as loose:skill:web-search.

GET /api/graph-layout

The query parameter for the Gateway URL is url, not gatewayUrl.
  • Query params:

Responses

200 OK: the saved layout, or no positions when nothing is saved:
This route never answers an error: a database failure also returns { "positions": {} }.

Example

POST /api/graph-layout

Creates or replaces the positions for one layout. The positions are stored as sent.
  • Request body:

Responses

200 OK: { "ok": true }. 400 Bad Request: the body is not a JSON object:
400 Bad Request: gatewayUrl is missing or not a string:
500 Internal Server Error: { "ok": false, "error": "<message>" }.

Example

Source of truth: apps/web/server/api/settings.ts with packages/config/src/index.ts (settings resolution), apps/web/server/api/health.ts with apps/web/server/lib/bootProbe.ts and lib/defaults.ts, apps/web/server/lib/workDirMoveGate.ts (the answers while the work folder move runs), and apps/web/server/api/graphLayout.ts.
Last modified on November 18, 2026