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 the user-facing replacement for the deleted Labs Diagnostics panel, so it is a normal navigation item, not a feature-gated lab.
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 toolbar shows a single rollup pill computed from the report’s fatal and degraded arrays:
| Pill | Condition |
|---|
All systems go (success) | no fatal and no degraded checks |
N degraded (warning) | at least one degraded check, none fatal |
N fatal (error) | at least one fatal check |
The degraded / fatal banner
When the report has any failing check, a banner appears above the checklist:
- Fatal: “The install has a fatal problem.” Clawboo has no upgrade/repair path, so the remedy is to reset
~/.clawboo and re-run onboarding for a clean start.
- 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. Only two failures are fatal: the clawboo home is not writable, or the SQLite file fails its integrity check, 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:
| Check id | Label | What it verifies | Failure tone |
|---|
clawbooHomeWritable | Clawboo home writable | ~/.clawboo exists and is writable (mkdir + W_OK) | fatal |
vaultPerms | Secrets vault permissions | secrets/ is 0700, master.key is 0600, proxy device identity is 0600 (POSIX only; skipped on Windows; “not yet created” on a fresh install) | degraded |
masterKeyBootSentinel | Master key | A fixed sentinel encrypted on first boot decrypts on every later boot, proving the master key still works | degraded |
databaseIntegrity | Database integrity | SQLite opens and PRAGMA integrity_check returns ok | fatal |
databaseSchema | Database schema | The core bootstrap tables (teams, agents, settings, budgets, orchestration_events, tasks) are present | degraded |
apiPortFileMatches | API port file | The on-disk api-port file matches the actual listening port (skipped pre-listen when no port is supplied) | degraded |
mcpServersHealthy | MCP servers | Each of the four MCP servers (tasks, memory, tools, teamchat) builds and answers a tools/list round-trip | degraded |
openclawGatewayReachable | OpenClaw Gateway | The Gateway is reachable and synced (skipped if no Gateway is configured; a miss degrades to serving last-synced agents from SQLite) | degraded |
otelExporterReachable | OTel exporter | Only runs when an OTLP endpoint is configured; otherwise reports “disabled” and passes | degraded |
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:
| Row | Source |
|---|
| clawboo home | resolveClawbooDir(process.env) (~/.clawboo, CLAWBOO_HOME override) |
| database | the resolved SQLite path (~/.clawboo/clawboo.db) |
| API port | the actual listening port, or (unknown) pre-listen |
| OpenClaw state dir | OpenClaw’s interop dir, or (not resolved) |
| secrets vault | present or not yet created |
| master key | verified, or unreadable — re-enter runtime keys when the sentinel failed |
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:
| Row | Value shown |
|---|
| log level | info (pino level; LOG_LEVEL env override) |
| budget posture | track-and-warn (no global hard cap; warns at 80%) when no hard cap is set; otherwise hard cap $X.XX |
| observability | local event log (OTel opt-in), or OTel exporter active when an OTLP endpoint is configured |
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
| Action | Route | Effect |
|---|
| Open / auto-refresh | GET /api/health | Returns the latest cached BootReport (computes one if none exists yet) |
| Re-run probe | POST /api/health/recheck | Recomputes fresh and replaces the cache |
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:
curl -s http://localhost:18790/api/health | jq '.ok, .fatal, .degraded'
.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. Clawboo has no migration or repair path; a fatal clawbooHomeWritable or databaseIntegrity is not something the panel can fix. 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 in 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.
