Principle:Openclaw Openclaw Verification And Dashboard
| Knowledge Sources | |
|---|---|
| Domains | CLI, Verification, Dashboard |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Post-setup verification is the process of confirming that a newly configured gateway is operational by opening a web-based control dashboard and optionally sending a test message through a connected channel.
Description
After a user completes the onboarding wizard -- configuring authentication, channels, and the daemon -- they need immediate confirmation that everything works. A gateway that silently starts but fails to bind, refuses connections, or cannot reach a messaging API leaves the user stranded. The verification and dashboard concept addresses this by providing two complementary verification mechanisms: a visual dashboard that shows gateway status at a glance, and a programmatic message-send command that exercises the full outbound pipeline end-to-end.
The dashboard mechanism reads the gateway configuration (port, bind address, custom host, base path) to construct the correct Control UI URL, copies it to the clipboard for convenience, and attempts to open it in the default browser. If the environment does not support browser launch (headless server, SSH session), it prints the URL along with an SSH port-forwarding hint so the user can access the dashboard from a local machine. The dashboard itself is a web application served by the gateway that shows channel status, connected sessions, and configuration state.
The message send mechanism provides a CLI command that sends a message through any configured channel. It validates the channel and action, constructs an outbound delivery request using the appropriate channel SDK, and reports the delivery result. This exercises the complete outbound pipeline: config loading, channel resolution, credential retrieval, API call, and response formatting. A successful test message proves that the gateway, configuration, and channel credentials are all working correctly.
Together, these two mechanisms give users confidence that their setup is complete and functional without requiring them to switch to another device or wait for an inbound message to trigger the gateway.
Usage
Apply this pattern when:
- A service has a web-based control panel that users should see immediately after setup.
- The runtime environment varies (desktop with browser, headless server, SSH session) and the verification UX must adapt.
- End-to-end verification requires exercising the actual outbound message pipeline, not just checking config syntax.
- Users need a quick, repeatable way to confirm that changes to configuration or credentials have taken effect.
Theoretical Basis
The verification phase combines two independent strategies:
Strategy 1 - Dashboard (Visual Verification):
read config -> resolve gateway port, bind, basePath
construct Control UI URL (e.g., http://127.0.0.1:18789/ui)
copy URL to clipboard (best-effort)
detect browser support
if browser available -> open URL
if browser unavailable -> print URL + SSH tunnel hint
report outcome
Strategy 2 - Test Message (Functional Verification):
load config
resolve action (send, poll, etc.)
validate channel + action against known types
create outbound send dependencies (per-channel SDK wrappers)
execute message action via runMessageAction
if json mode -> print JSON result
if text mode -> print formatted result lines
Key design decisions:
- Browser detection before launch: Rather than blindly calling open(url) and hoping, the dashboard command first checks for browser support via detectBrowserOpenSupport. This prevents confusing error messages on headless servers.
- SSH hint as fallback: When no browser is available, the command outputs an SSH port-forwarding command that the user can copy to create a tunnel from their local machine. This covers the common "headless VPS" deployment scenario.
- Clipboard as convenience: The URL is always copied to the clipboard (when available) regardless of whether the browser opens. This makes it easy to paste into a different browser or share.
- Channel-agnostic message dispatch: The message command does not hardcode any channel logic. It resolves the action and channel from the options, then delegates to runMessageAction which routes through the same outbound pipeline the gateway uses for real messages.
- Output mode flexibility: The message command supports both human-readable text output and structured JSON output (--json flag), making it suitable for both interactive verification and CI/automation scripts.