A useful local setup check answers five different questions: does the CLI run, is the Gateway reachable, can the provider reply, is the right workspace selected, and does the intended channel work? Checking them separately makes a failure easier to fix.
If you have not installed OpenClaw yet, start with the local quickstart. This page covers verification and debugging after setup, so you can keep a reliable baseline as you add tools.
Independent guide. Diagnostic references checked on October 2, 2026. The checklist is an operator workflow, not a claim that your computer has passed it.
1. Record the environment
node --version
openclaw --version
openclaw config file
Record the operating system, installation method, active profile, and configuration path. Use the current Node requirements rather than a version number copied from an old tutorial.
On Windows with WSL2, note which environment hosts the Gateway. A shell in another environment may have a different home directory or CLI installation. Avoid comparing those outputs as if they came from one installation.
2. Check the Gateway before testing a model
openclaw gateway status
openclaw gateway health
If Gateway health fails, investigate the service, config, or local listener first. If it succeeds, continue to provider verification. The Gateway query reference describes the reported health and status information.
Keep one supervisor for a given Gateway. A managed service and a foreground process competing for one port can make an otherwise valid installation appear broken.
3. Validate configuration
openclaw config validate
openclaw config get agents.defaults.workspace
The usual runtime config is ~/.openclaw/openclaw.json, using JSON5. Use the reported active path when checking a recent edit. If validation fails, correct the field identified by the CLI before restarting repeatedly.
A valid schema does not prove that a selected model is accessible to your account. For safe editing, see the configuration guide.
4. Send a simple message
openclaw dashboard
Authenticate and send a short text-only request. Record whether the UI loads, whether the request begins, and whether a complete response arrives. These observations distinguish a connection failure from a provider rejection or an interrupted response.
Watch the relevant log while reproducing a failure:
openclaw logs --follow
Follow provider-specific errors such as account access, expired authentication, rate limits, or exhausted quota. Changing unrelated sandbox settings will not fix a failed provider login.
5. Check workspace behavior with disposable data
Use a folder and files you can safely discard. If you allow the assistant to write a note, inspect the actual file afterward. If it is supposed to read a file, compare the reply with that file's contents.
This checks an outcome instead of trusting the assistant's description of its actions. It also exposes mismatches between the expected workspace, the chosen agent, and a sandbox's view of the filesystem.
Read the official workspace reference before moving instruction or memory files. Use the sandbox reference if tool access is intentionally restricted.
6. Verify a channel independently
Add one messaging channel only after the Control UI conversation works. Confirm its account credentials and access policy, then send a message from an allowed account. A working browser session and an unanswered Telegram message do not imply the same failure.
Use the Telegram guide or WhatsApp guide for the corresponding pairing flow. Avoid loosening all access rules to diagnose one channel.
7. Verify persistence and restart behavior
Before restarting, stop active work and make a private backup. Use a harmless conversation or note for the test, then check it after the managed Gateway restarts:
openclaw gateway restart
openclaw gateway status
openclaw gateway health
Compare the workspace and profile before and after. An apparently missing conversation may be a different agent or state path; do not immediately assume storage corruption.
For a local computer, also test your intended power behavior. A healthy background service does not make a sleeping laptop available to remote channels.
Keep a small acceptance checklist
| Check | Evidence to save privately |
|---|---|
| CLI and runtime | Version and environment |
| Gateway | Status and health result |
| Configuration | Active path and successful validation |
| Provider | A completed simple reply |
| Workspace | Verified disposable file outcome |
| Channel | Reply to an allowed account |
| Restart | Same profile and expected state |
Repeat the relevant checks after an upgrade or a new plugin. Keep the test small enough that failures are easy to compare. For installation-specific errors, use our fix guide.
FAQ
Can I use a Python client to verify my installation?
Use the official Control UI and CLI for the baseline here. The earlier openclaw.Client snippets on this page were not supported by the documentation reviewed for this Gateway and have been removed.
Why does chat work but a file task fail?
Provider access and filesystem permission are different checks. Confirm the active agent, workspace, tool policy, and sandbox mounts using the relevant official references.
What is the safest next step when several checks fail?
Resolve the earliest failing stage, then repeat the same checklist. Read-only diagnostics such as openclaw doctor can help before you decide whether any repair is needed.