Verify the CLI and Gateway before connecting anything real

Verifiedon 2026-07-302026.7.1-2

Green is a bounded claim

A verification command is useful only when you state exactly what it proves. openclaw --version proves that one executable is available to one shell. openclaw doctor reports configuration or repair guidance. openclaw gateway status reports managed Gateway state. openclaw health asks a running Gateway for a health snapshot over WebSocket RPC. None of these proves that a provider can answer, a channel is authorised, a recipient is correct, or an external side effect is approved.

This lesson uses OpenClaw 2026.7.1-2, revision 1237c0cf8157a6ad4a900d6b165ea8c830449e78. The installation guide lists the first version/doctor/status smoke checks, while the health CLI reference defines the Gateway health snapshot. Read those primary pages rather than treating this course as a replacement command reference.

Lab: create a verification ledger

Run one command at a time and capture only the bounded result. Keep raw logs out of the learner artifact; if a command prints an endpoint, token, account name, or provider response, replace it with a redaction marker before saving. Run the checks from the same account and shell context that will run the first agent.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw health --json

Use a record like this:

[UTC] binary: pass | version=<course version>
[UTC] config: pass | doctor summary=<short redacted classification>
[UTC] service: pass | gateway status=<running/stopped/unknown>
[UTC] rpc: pass | health snapshot=<received/not received>
provider: checked separately in the previous lesson
channels: none connected
external actions: forbidden

The JSON form can make a ledger easier to audit, but JSON is not automatically safe. Do not commit a full JSON response if it includes configuration, model details that identify a private deployment, or a token-shaped value. Preserve the exit status and a short classification instead.

Make the ledger useful during a failure

A good ledger records the command, timestamp, exit state, scope, and next owner—not merely a green or red label. For each failed layer, write the smallest next observation that could distinguish two hypotheses. If the service is stopped, inspect whether it was intentionally stopped or unexpectedly exited before starting it. If RPC health times out, compare the endpoint and authentication context with the known configuration before changing either. If doctor reports a repair, quote only the redacted classification and link the source page that defines the command. This discipline prevents a troubleshooting session from turning four independent questions into one speculative restart.

Classify before changing

Missing CLI: openclaw --version fails or resolves a different binary than the ledger. Return to the install lesson. Check the user-level PATH and executable location; do not reinstall as root.

Configuration issue: the CLI runs, but openclaw doctor reports invalid or incomplete configuration. Read the exact diagnostic and compare it with the reviewed onboarding result. Do not edit arbitrary JSON because a key “looks wrong”. If the config may contain a credential, inspect through the documented command and redact the artifact.

Gateway unavailable: the CLI and configuration are usable, but openclaw gateway status reports stopped or unavailable. Determine whether this lesson’s installation was intended to start a managed service. If not, starting a service is a deliberate change, not a passive check. Keep the channel boundary disconnected and obtain approval before enabling persistent startup.

RPC health unavailable: the managed process appears present, but openclaw health cannot obtain a snapshot. Check the Gateway endpoint and authentication boundary using the official configuration guidance. A timeout is not proof that the Gateway did nothing: if a later agent turn might have been accepted, follow the current agent execution guidance and inspect status/transcript before retrying a side-effecting operation.

Healthy snapshot: a response proves only that the checked Gateway answered at the recorded time. It is a useful baseline for the first-agent lab, not an authorisation token.

Worked decision

Suppose the ledger says:

binary: pass; version=2026.7.1-2
config: pass; doctor=0 actionable issues
service: running
rpc: fail; timeout after 2500ms
provider: pass
channels: none

The least-change next step is not “attach a channel” or “restart everything”. Confirm the Gateway endpoint/auth context and inspect the bounded service evidence. If the service was started by a previous experiment, stop it and repeat from a clean state; if the endpoint is intentionally remote, verify the remote boundary and owner. The failure is still unresolved, so the expected result is a classified handoff, not a green badge.

Checkpoint: separate health from authority

A status check is green but no provider live check has passed. Can you connect a real messaging channel? No. The provider and channel boundaries are independent. Another case: the provider check passes, the Gateway health snapshot is green, but the workspace is the operator’s production repository. Can you run the first agent? No. The data boundary failed before the runtime did.

Expected result, failure mode, and rollback

Expected result: a four-layer ledger distinguishes binary, config, service, and RPC evidence and states what remains unverified. Failure mode: a green process is interpreted as permission, a timeout is retried blindly, or raw diagnostics leak private state. Rollback: leave channels disconnected, stop the test Gateway if it was started only for the exercise, preserve the redacted classification, and return to the first failing layer. Do not change configuration and service state in the same troubleshooting step; that destroys attribution.

Primary source receipt

• OpenClaw install smoke checks, reviewed revision
• OpenClaw health CLI, reviewed revision
• OpenClaw agent transport and retry scope, reviewed revision

Learner artifact: a timestamped, redacted verification ledger. Its strongest claim is a bounded one: what answered, when, and what it did not prove.