Skip to main content
Use this page when you want to know whether your Clawboo install is sound: which foundations passed at boot, what the server resolved (state dir, database, port), and what production posture it is running with. The System Health panel is the always-visible surface over the boot probe; it is a normal navigation item. The panel (SystemHealthPanel) is backed by /api/health. The boot probe runs once on every server start and is cached; the panel reads that cached report and can recompute it on demand.

​
Prerequisites

System Health is always available. It is the one liveness surface that answers even when the OpenClaw Gateway is down; the report is computed from local filesystem, SQLite, vault, and in-process MCP state, not from a runtime connection.
  • A running Clawboo server. No runtime needs to be connected; the panel works on a fresh install before you have onboarded.

​
Open the panel

In the left sidebar, the secondary nav lists System Health (heart-pulse icon). Selecting it switches the view to the health nav slot, which renders SystemHealthPanel. On open, the panel calls GET /api/health and renders the report. It also re-fetches every 30 seconds while the view is mounted, so a long-lived dashboard stays current without a manual refresh.

​
What the panel shows

The panel has three sections plus a status banner.

​
The header status pill

The toolbar shows a single rollup pill computed from the report’s fatal and degraded arrays:

​
The degraded / fatal banner

When the report has any failing check, a banner appears above the checklist:
  • Fatal: “The install has a fatal problem.” The failing check below says what to do; resetting ~/.clawboo and re-running onboarding is the last resort.
  • Degraded: “Running degraded.” Some optional subsystems are unavailable; the rest of Clawboo works normally. The failing checks below tell you which.
This split is intentional: almost everything degrades (the server keeps running) rather than being fatal. Three failures are fatal: the clawboo home is not writable, the SQLite file fails its integrity check, or its schema is short a column, because nothing works without them.

​
The Checks checklist

Each entry in report.checks[] renders as a row with an icon, the humanized check name, a tone pill (OK / Degraded / Fatal), the check’s durationMs, a one-line message, and, only when the check failed, its detail line. The nine checks the boot probe runs, in order:
mcpServersHealthy is a constructability + tools/list check: it builds a fresh server instance per probe over the same database, not the cached HTTP singleton that real attaches consume. It proves the server can be built and answers a request; it is not a liveness probe of the pre-warmed singleton.

​
Runtime state

The report.resolved block, shown as a key/value card, surfaces what the server actually resolved this boot:

​
Production defaults

The report.config block surfaces the shipped production-defaults posture so you (or a bug report) can see what this install runs with: The 80% figure is the budget math’s soft-cap percentage (SOFT_CAP_PERCENT), referenced by budgetWarnSoftPct so the two never drift. See Production defaults for the full posture catalog.

​
Re-run the probe

After you fix a failing check (for example, you tighten the vault permissions or re-enter a runtime key), click Re-run probe in the toolbar. This calls POST /api/health/recheck, which recomputes a fresh report, re-running the integrity check, the MCP round-trips, and the Gateway/OTel probes, and replaces the cached one. The button is disabled (with a spinner) while a probe is in flight; concurrent probes are de-duped server-side so the slow checks run at most once. The plain GET /api/health returns the cached report (or computes one on first call if the server has not produced one yet); only recheck forces a fresh run.

​
Options / variations

Both responses carry a top-level ok field (true when there are no fatal checks), so a simple external liveness check can read that one field. Every check’s detail and the resolved paths are redacted-on-display before send; a credential-shaped substring is masked while the readable paths and config stay.

​
Verify it worked

  • After a successful Re-run probe, the header pill flips to All systems go and every row reads OK (assuming you fixed the failing checks).
  • A bare liveness check works from any shell:
.ok is true when no check is fatal; .fatal and .degraded list the failing check ids by name.

​
Troubleshooting

A fatal check means the install is broken. A fatal clawbooHomeWritable or databaseIntegrity is not something the panel can fix. A fatal databaseSchema means the database is short something the current version needs: a core table, or a column that could not be added. Its detail names what is missing and the remedy, so follow that before resetting. When nothing there applies, reset ~/.clawboo and re-run the onboarding wizard to start clean. (Back up the database first if you need its data.)
master key reads “unreadable, re-enter runtime keys”. The boot sentinel did not decrypt, which means the master key changed, was lost, or CLAWBOO_SECRETS_MASTER_KEY now differs from what encrypted the vault. Stored runtime provider keys cannot be decrypted; re-enter them from Settings, then the Runtimes panel (see Connecting runtimes), or reset ~/.clawboo for a clean start. This check degrades; the server keeps running.
OpenClaw Gateway shows degraded but everything else works. The Gateway is optional. When it is unreachable, Clawboo serves the last-synced agents from SQLite; this is a degraded check, never fatal. If you run native-first (no Gateway), this check is skipped entirely.
Last modified on August 10, 2026