> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claw.boo/llms.txt
> Use this file to discover all available pages before exploring further.

# Check System Health

> Read the boot-probe checklist, the degraded/fatal banner, resolved runtime state, and re-run the probe from the System Health panel.

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](/appendices/glossary); 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

<Note>
  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.
</Note>

* 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:

| 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."* 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](/appendices/glossary) 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:

| 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 are present, and no column the schema declares is missing from them                                                        | **fatal**    |
| `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     |

<Note>
  `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.
</Note>

### 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          |

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](/operating/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                                  |

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:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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

<Danger>
  **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.)
</Danger>

<Warning>
  **`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](/runtimes/connecting-runtimes)), or reset `~/.clawboo` for a clean start. This check degrades; the server keeps running.
</Warning>

<Note>
  **`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.
</Note>

## Related

* [`/api/settings` and `/api/health` reference](/reference/rest-api/settings): full request/response shapes for the health routes
* [Production defaults](/operating/production-defaults): budget posture, breaker defaults, and the full shipped-defaults catalog
* [Connecting runtimes](/runtimes/connecting-runtimes): where the encrypted vault and runtime keys live
* [Security](/operating/security): the vault, redaction, and safe exposure
* [Data and state](/operating/data-and-state): SQLite, file locations, backup, and reset