Principle:Openclaw Openclaw Channel Health Verification
| Knowledge Sources | |
|---|---|
| Domains | Messaging, Monitoring, Gateway |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Channel health verification is the process of probing each configured messaging channel's live connection status and reporting its operational health to the operator.
Description
Once channels are registered and the gateway is running, operators need visibility into whether each channel is actually connected and functioning. A channel may be configured correctly in the config file but fail at runtime due to an expired token, a network issue, a platform API change, or a misconfigured webhook. Channel health verification provides this runtime visibility.
The verification system operates at two levels: config-only status (what the config file says about each channel) and live gateway status (what the running gateway reports about each channel's actual runtime state). Config-only status is available even when the gateway is not reachable and shows basic information like whether a channel is enabled, configured, and has valid credentials. Live gateway status adds runtime signals like whether the channel is connected, running, when it last received an inbound or outbound message, and the results of active probes.
The probe mode (activated with --deep or --probe) goes further by actively testing the channel's connection. For Telegram, this might call the getMe API to verify the bot token. For Discord, it might check the WebSocket gateway connection. Probe results include success/failure status and additional metadata like the bot's username, which helps operators verify they have connected the correct bot account.
The health verification system also collects and reports status issues -- warnings about configuration problems that may not prevent the channel from running but indicate suboptimal or potentially broken setups (e.g., missing webhook secrets, disabled intents, or stale tokens).
Usage
Channel health verification is accessed through the openclaw channels status CLI command. The basic command shows config-level status. Adding --deep or --probe activates live probing via the gateway. The --json flag outputs machine-readable status for monitoring integrations.
Theoretical Basis
The health verification model uses a progressive depth approach:
- Config snapshot -- Each channel plugin's
config.listAccountIdsenumerates configured accounts. For each account,buildChannelAccountSnapshotgathers static config data: enabled/disabled, configured/unconfigured, linked/unlinked status. - Gateway runtime overlay -- When the gateway is reachable, the
channels.statusRPC call returns runtime data that overlays the config snapshot: connection state, last inbound/outbound timestamps, running/stopped status, and any active errors. - Active probe -- In probe mode, the gateway additionally calls each channel's health check endpoint to verify live connectivity. Probe results are attached to the account snapshot.
- Issue collection -- The
collectChannelStatusIssuesfunction scans the status payload for known warning patterns and produces actionable fix suggestions.
This layered approach ensures that operators always get some level of visibility (config status) even when the gateway is down, and can progressively deepen their view when the gateway is available.