Principle:Openclaw Openclaw Deployment Health Verification
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Docker |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Deployment health verification is the concept of probing the gateway's health endpoint, checking channel connectivity, and confirming operational status after deployment.
Description
After deploying the OpenClaw gateway -- whether via Docker Compose, Fly.io, Render, or any other platform -- operators need to verify that the deployment is functioning correctly. This goes beyond simple process liveness: a healthy OpenClaw gateway must have a responsive WebSocket/HTTP server, valid configuration, connected messaging channels, active session stores, and running heartbeat timers.
The health verification system operates at two levels. The health snapshot (getHealthSnapshot) runs locally within the gateway process, collecting comprehensive status from all subsystems: it iterates over every registered channel plugin, resolves account bindings, probes each configured account for connectivity (e.g., verifying Telegram bot tokens via API calls), builds session summaries, and reports heartbeat intervals per agent. The health command (healthCommand) is the CLI-facing wrapper that calls the gateway via RPC (using the callGateway function), renders the results as formatted terminal output or JSON, and reports the status of each channel with color-coded indicators.
For Docker deployments specifically, health verification serves multiple purposes: it validates that volume mounts are correct (sessions are accessible), that the gateway token is accepted (authentication works), that outbound network connections succeed (channel probes reach external APIs), and that the bind mode allows the health check to reach the server. Cloud platforms like Render use the /health HTTP endpoint for automated health checks, while operators use the CLI openclaw health command for deeper inspection.
Usage
Apply this concept immediately after any deployment or configuration change. Run openclaw health (or the Docker equivalent) to verify gateway reachability and channel connectivity. Use --verbose for detailed probe results including API response times, or --json for machine-readable output suitable for monitoring integrations.
Theoretical Basis
The health verification system follows a layered probe architecture:
- Gateway reachability: The CLI sends an RPC call to the gateway's WebSocket endpoint. If this succeeds, the gateway process is running and accepting connections. This is represented by the
ok: truefield in the response.
- Channel health probing: For each registered channel plugin, the system:
- Resolves all configured account IDs (including bound accounts per agent).
- Checks whether each account is enabled and configured.
- If the channel plugin provides a
probeAccountmethod, calls it with a timeout to verify external API connectivity. - Aggregates results per channel, selecting the preferred account for the default summary.
- Agent health: For each configured agent, reports the heartbeat interval, session store path, session count, and most recent session activity timestamps.
- Output formatting: Results are rendered as color-coded terminal lines (green for ok/linked, yellow for warnings, red for failures, gray for unconfigured) or as structured JSON for programmatic consumption.
The health check is designed to be non-destructive and read-only. Channel probes use lightweight API calls (e.g., Telegram getMe) rather than sending messages. The default timeout is 10 seconds, capped at a minimum of 1 second.