Check the release's runtime requirement first
Use the official OpenClaw installation guide and the package linked to openclaw/openclaw. This guide checks OpenClaw 2026.10.6, identified by its CLI as fe06181, on macOS with a temporary Node installation.
The published package requires Node >=24.22.1 and <25, or >=26.12.1. The general installation overview showed a lower minimum when checked on October 23, 2026. For this pinned release, follow the package's stricter engines requirement and runtime check. Node 24.5.0, despite being in the same major series, does not meet it.
Before installing, inspect the versions in the terminal you intend to use:
node --version
npm --version
npm view openclaw@2026.10.6 engines
If they disagree with the required range, select a supported runtime before continuing. Changing a shell's Node version does not automatically update the runtime used by an already-installed background service.
Choose the CLI or your platform's app
The official guide covers macOS, Linux and Windows. Desktop companions and CLI installation are different routes. Choose the appropriate official platform download if you want a desktop application; do not assume that an installer for another processor or operating system will work.
For the CLI, the current npm instructions distinguish npm versions. With npm 11.16 or later, the pinned form is:
npm install -g openclaw@2026.10.6 --allow-scripts=openclaw
openclaw --version
The official instructions omit --allow-scripts on npm 11.15 and earlier. The flag permits OpenClaw's package lifecycle scripts under package managers that support that policy. Read the current installation guide if a future npm version changes the behavior.
That is a normal global installation recipe. Our test instead installed the package under a temporary prefix with lifecycle scripts disabled, using a checksum-verified official Node 24.22.1 archive. We tested the CLI and a limited Gateway configuration, not a global install, desktop app or all optional native integrations.
Decide whether you want setup or a chat request
The setup reference distinguishes baseline initialization from guided onboarding. Bare openclaw setup can enter a system-agent chat on a configured installation. Do not treat it as a command that only creates folders every time.
For a new, isolated check that does not connect a model:
openclaw setup --baseline --skip-bootstrap --workspace /absolute/path/to/test-workspace
Replace the workspace path with a dedicated directory. --baseline creates configuration and workspace/session state without onboarding. --skip-bootstrap avoids generating the default workspace bootstrap files. Run baseline setup while the relevant Gateway is stopped.
For isolation, the official configuration supports OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH. Set both to your test directory in every terminal used for the check. Otherwise a health command in a second terminal can inspect a different installation. Our test also used a temporary home, omitted real provider credentials and confirmed that the user's original OpenClaw, Claude and Codex settings were unchanged.
Baseline setup is not provider authentication. When you are ready to connect a model, use the documented guided onboarding for that same profile. Review the selected provider, model and account before its connection test. Do not pass a real key through a public command example or paste it into troubleshooting logs.
Start the Gateway in the foreground
The Gateway running reference distinguishes a foreground process from an installed service. For a local configuration, check that gateway.mode is local, use a free port, and keep the binding on loopback. Retain token authentication; the Gateway token is separate from a model-provider key.
In the test configuration file, merge these fields while preserving the generated agent/workspace settings:
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback",
"auth": { "mode": "token" }
},
"browser": { "enabled": false },
"plugins": { "enabled": false }
}
Use another free port if 18789 is already occupied. Set OPENCLAW_GATEWAY_TOKEN to the same locally generated secret in both test terminals; keep it out of shared logs and source control. This local secret authenticates the health connection, not a model provider.
Check configuration before starting:
openclaw config validate
openclaw gateway run
Keep that terminal open. gateway run is the foreground path; gateway install installs and starts a native service. The latter is unnecessary for this first check. Avoid --force when diagnosing a port conflict: it is intended to displace a listener, not merely report what is using the port.
Our temporary configuration disabled browser control, plugins, discovery and update checks. We selected an unused loopback port and supplied a temporary Gateway token through its documented environment variable. We did not configure a messaging channel, import existing sign-ins or install a launchd/systemd service.
Baseline setup and configuration validation exited successfully. The temporary Gateway then answered health RPC with ok: true, no configured channels and zero sessions. The same snapshot also flagged CPU-related event-loop degradation, so we do not describe it as an entirely clean health report. It was enough to confirm the local connection; it was not an inference or sustained-performance test.
Read the health result, not just the exit code
In a second terminal using the same configuration and state paths:
openclaw health --json --timeout 20000
The health reference describes a WebSocket RPC snapshot. Top-level ok: true means the Gateway answered the health request and produced that snapshot. Inspect its channel, plugin and queue details too. During startup, the command can instead return a non-failing status: starting; that is not a completed health snapshot.
Keep three outcomes separate:
| Outcome | Evidence to look for |
|---|---|
| Local configuration is valid | Configuration validation succeeds for the intended file |
| Gateway is reachable | Health RPC returns a snapshot from the intended process |
| Your assistant task works | The selected authenticated model returns the requested result, through the intended channel if one is involved |
A running process or an empty channel list cannot establish the third outcome. We did not make an authenticated model request or send a message through a channel in this test. Provider usage, subscriptions and limits remain separate from installing OpenClaw.
Diagnose and stop the correct process
If the command is missing, check the package's installation prefix and the current terminal's PATH. If the runtime is rejected, compare the complete Node version against the pinned package requirement. Reinstalling the same package under the same unsupported runtime will not fix that mismatch.
If configuration validation fails, keep a backup and inspect the reported field before allowing repair commands. If health cannot connect, compare state path, config path, port, process state and Gateway authentication. A wrong token should be corrected at the intended client; disabling authentication is not a substitute.
If Gateway health succeeds but a model request fails, inspect that provider's authentication and selected model separately. For a local API gateway such as FreeLLMAPI, its liveness and readiness checks also have separate meanings.
Stop a foreground test with Ctrl-C and confirm that its process exits. A managed service has its own owner and lifecycle; do not use service stop/uninstall commands against another working profile. Our temporary Gateway was stopped after the health check, and no persistent service was installed. Preserve a real installation's configuration, credentials and workspace before any reset or migration.