Open System Health
Open Settings (the Settings row at the bottom of the left sidebar, or Cmd+, on macOS and Ctrl+, on Windows and Linux), then System Health in the System group. It works on a fresh install before you connect anything, and while the OpenClaw Gateway is down. Clawboo runs its checks each time its server starts. The panel shows the results of the last run and reads them again every 30 seconds while its tab is visible, but reading does not run the checks again. Click Re-run probe to run them now, for example after you fix something. A failed check never stops Clawboo. The server keeps running, so you can read the details here.Read the panel
- The header pill sums up the checks: All systems go, N degraded or N fatal.
- A banner appears when a check fails. “Running degraded.” means some optional parts are unavailable and the rest of Clawboo works normally. “The install has a fatal problem.” means Clawboo cannot work properly until you fix it. The banner points you to the failing check, and to resetting
~/.clawbooonly as the last resort. - Checks lists each check with an OK, Degraded or Fatal pill, how long it took, and a one-line result. A failed check also shows its details: what went wrong, often with the file or setting involved.
- Runtime state and Production defaults show what this server is using (see Runtime state and defaults).
The checks
The checks run in this order. Three of them are fatal when they fail, because nothing works without them; the rest are degraded.Fix a failing check
Fix the fatal checks first: a database that cannot open also stops the MCP servers check. After a fix, click Re-run probe. Where a fix says to restart Clawboo, runclawboo restart (on an install protected by an access token, see the CLI reference instead).
Clawboo home writable is Fatal
Clawboo home writable is Fatal
What it means: Clawboo cannot create or write its folder. The details give the system’s reason, such as a permission error.Fix: make sure your user account owns
~/.clawboo and can write to it, or set CLAWBOO_HOME to a folder you can write. Then restart Clawboo.Secrets vault permissions is Degraded
Secrets vault permissions is Degraded
What it means: other users on this computer could read the files that protect your keys. The details name each file and its current mode, such as If you set
secrets/ is 755.Fix: make those files private to your account, then click Re-run probe. Run the line for each file the details name:CLAWBOO_HOME, use that folder instead of ~/.clawboo.Master key is Degraded
Master key is Degraded
What it means: the key that encrypts the vault is not the one that encrypted it, so Clawboo cannot read your saved provider keys or connector sign-ins. The master key row under Runtime state reads unreadable and asks you to re-enter runtime keys.The key is
~/.clawboo/secrets/master.key, or the value of CLAWBOO_SECRETS_MASTER_KEY when that is set. It usually changes when that variable is set, changed or removed, when master.key is deleted or replaced, or when ~/.clawboo is restored without its secrets folder.Fix:- If you can, put the original key back: set
CLAWBOO_SECRETS_MASTER_KEYto its old value, or restore the originalmaster.key. Restart Clawboo, then click Re-run probe. Your saved keys work again. - If the original key is gone, the saved keys cannot be recovered. Delete
~/.clawboo/secrets/runtime-keys.json, the vault file that holds them, and click Re-run probe. Then re-enter your keys under Settings > Providers (or on a runtime’s card under Settings > Runtimes, wherever you first entered them) and reconnect your connectors.
CLAWBOO_SECRETS_MASTER_KEY that is not a 32-byte key.Database integrity is Fatal
Database integrity is Fatal
What it means: the database could not be opened, or SQLite found damage in it. The details give SQLite’s own words.Fix: stop Clawboo with
clawboo stop and restore ~/.clawboo/clawboo.db from a backup. With no backup, keep a copy of the damaged file, then reset the data: Clawboo starts with an empty database, and you lose everything that was in it, such as your teams, board, chats and memory. Data and state has the steps for both.Database schema is Fatal
Database schema is Fatal
What it means: a table or column Clawboo needs is missing from the database. The details name it.Fix: restart Clawboo first. Each time it opens the database it adds any missing columns, so this usually clears. If the result says the schema “cannot be upgraded in place”, this version of Clawboo cannot run on that database: the details name the file and the choices. Either run the Clawboo version that created the database, or move the file aside to start clean, which loses everything stored in it, such as your teams, board, chats and memory.
API port file is Degraded
API port file is Degraded
What it means:
~/.clawboo/api-port.txt names a different port from the one this server listens on, or is missing. From 0.9.0 the check also needs the start marker api-port.json to name this server’s process and port. The clawboo command reads these files to find the server, so clawboo stop and clawboo restart can miss this one. A common cause is a second Clawboo server that started later and wrote its own port.Fix: if you run more than one Clawboo server, stop the one you don’t need with CLAWBOO_API_PORT=<port> clawboo stop. Then run clawboo restart, and the running server writes its port again. This server’s port is the API port row under Runtime state.MCP servers is Degraded
MCP servers is Degraded
What it means: one of Clawboo’s tool servers did not start or answer, so agents may lose its tools: board tasks, memory, connected apps or messages between agents. The details name the server and its error. “MCP servers not probed (database unavailable)” means the database failed first; fix that.Fix: restart Clawboo. If the check still fails, look for the error in the server log,
~/.clawboo/server.log, and open an issue with the details.OpenClaw Gateway is Degraded
OpenClaw Gateway is Degraded
What it means: Clawboo’s server was not connected to the OpenClaw Gateway when the checks ran. The result reads “OpenClaw Gateway not reachable”, followed by the connection state, and the details give the Gateway’s address. Your OpenClaw agents still show as they were at the last sync but cannot take work. Your other runtimes are not affected.The check runs only when OpenClaw is set up on this computer: Clawboo’s settings name a Gateway, or OpenClaw’s own
openclaw.json exists. Otherwise it passes as “OpenClaw Gateway not set up on this machine (skipped)”.Clawboo connects to the Gateway only once something needs it: an OpenClaw agent, opening OpenClaw in Settings > Runtimes, or a routine for an OpenClaw agent falling due (see How Clawboo connects). If OpenClaw is set up and nothing uses it yet, the check passes as “OpenClaw Gateway not in use yet (skipped)”. Clawboo has not tried to connect, so a Gateway that starts on its first connection stays asleep.Fix: if you use OpenClaw, start or reconnect the Gateway in Settings > Runtimes > OpenClaw (Reconnect, or Manage > Restart), then click Re-run probe. The check reflects the moment the checks ran, so a Gateway that started afterwards reads Degraded until you run them again. OpenClaw covers the Gateway’s own errors.OTel exporter is Degraded
OTel exporter is Degraded
What it means: an OpenTelemetry endpoint is set (
OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT), but the exporter did not start. Traces stay in Clawboo’s own log. On an install from npm this is expected: the package does not include the OpenTelemetry SDK, and the result says so.Fix: to clear the warning, unset both variables and restart Clawboo. To export traces, run Clawboo where the SDK is installed, such as a source checkout. See Export traces with OpenTelemetry.Runtime state and defaults
Runtime state shows what this server is using. It helps when you have moved Clawboo’s folder, or run more than one copy.
Production defaults shows how this version is set up out of the box. Its log level and budget posture rows always show the shipped default, not your own settings:
Under the hood
Under the hood
GET /api/healthreturns the report from the last run of the checks, andPOST /api/health/recheckruns them again (the Re-run probe button). Both carry a top-levelok, which istruewhen no check is fatal, plusfatalanddegradedlists of check ids. A monitor can read that one field.- With an access token set (
STUDIO_ACCESS_TOKEN), these routes need the access cookie like every other/apiroute. - Check ids, in order:
clawbooHomeWritable,vaultPerms,masterKeyBootSentinel,databaseIntegrity,databaseSchema,apiPortFileMatches,mcpServersHealthy,openclawGatewayReachable,otelExporterReachable. - Credential-shaped text in a check’s details is masked before it is sent.
- See the Settings, health and layout API for the full report shape.
Next steps
- Data and state: every file in
~/.clawboo, and how to back up, restore and reset. - CLI reference: restart Clawboo and find its log.
- OpenClaw: start, restart and repair the OpenClaw Gateway.
- Connect providers and runtimes: re-enter a provider key.
- Check on your agents: your agents’ work, errors and traces.
- Troubleshooting: fixes for other problems.