When OpenClaw installation fails, first identify the failing stage: runtime, CLI installation, onboarding, Gateway startup, or model access. Reinstalling before that distinction can hide the original error and leave multiple installations behind.
Independent guide. Commands and workflow checked on October 2, 2026 against official troubleshooting, Node setup, and the Gateway CLI. Examples are diagnostic instructions, not a claim that each failure was reproduced.
Collect a small baseline
node --version
openclaw --version
openclaw gateway status
openclaw config validate
openclaw doctor
Keep the exact error and installation method. Native CLI, source checkout, Docker, and WSL2 each have a different environment. Run diagnostics in the environment that owns the Gateway.
If the CLI starts, watch logs while repeating the failure:
openclaw logs --follow
Redact keys, tokens, private messages, and account identifiers before sharing output. Logs often contain more than the single line you need for support.
Unsupported Node runtime
Compare the detected runtime with the current official requirements. At this review, the quickstart lists Node.js 24.16+ or 26.1+. An older tutorial's Node 18/20 recommendation may not match the package you just installed.
After updating Node, open a new terminal and recheck node --version. If a managed service still uses another binary, inspect openclaw gateway status and follow the documented runtime repair. Changing the shell runtime does not necessarily change an existing service's runtime path.
Do not invent an error string or treat every startup failure as a native C++ compilation problem. Follow the actual installer's message and the dependency named in its output.
openclaw: command not found
First check whether installation completed under the same account and environment. A Linux CLI inside WSL is not automatically available to Windows PowerShell.
On macOS or Linux, these checks show the selected executables and npm's global prefix:
command -v node
command -v openclaw
npm prefix -g
Use the installer or your runtime manager's PATH instructions to make the correct installation available. Open a new shell after changing PATH. Avoid adding several guessed directories until one happens to work; that can select an old copy later.
Return to the installation guide if the official installer did not finish.
Permission denied during npm installation
Read the path in the error. If it is a system-owned global package directory, choose a user-managed Node installation or the official platform installer. Do not apply recursive ownership changes to system directories just to make one command pass.
If the failure is a state directory, confirm which account owns the Gateway and that account's home directory. Config created as root and a service running as an ordinary user are different ownership contexts.
Keep private state backups before correcting ownership or changing the runtime account. The server guide uses one dedicated account for installation and operation.
Port already in use or an existing Gateway
Start with:
openclaw gateway status
A healthy managed service may already be listening on the default port 18789. In that case, open its dashboard instead of launching another foreground Gateway.
For a configured native installation that deliberately needs a different listener:
openclaw config get gateway.port
openclaw config set gateway.port 18790 --strict-json
openclaw config validate
Restart the managed service only after checking active work, and use the updated dashboard port. A Docker deployment also has a published host port; use the Docker guide for that distinction.
Identify a conflicting process before stopping it. Killing every Node process can interrupt unrelated applications without fixing the installation that owns your Gateway.
Invalid configuration
openclaw config file
openclaw config validate
openclaw config schema
Read the exact unknown field or invalid value. Current runtime config is JSON5 in openclaw.json; invented openclaw.yaml, generic server.workers, and memory.backend examples do not define a supported Gateway installation.
If the error appeared after one edit, compare that edit with the prior working configuration. Back up before using repair commands. See our configuration guide for patching and validation.
Dashboard opens but no reply
A loading UI does not prove model access. Check provider sign-in or key validity, selected model permissions, rate limits, and usage balance. Review the error while sending one short message.
Run openclaw doctor and follow the guidance relevant to your provider. If onboarding never completed working inference, resume it with openclaw onboard rather than replacing unrelated Gateway settings.
When local chat works but a messaging channel does not, investigate channel authentication, pairing, and allowlists. See OpenClaw not working for the channel route.
Docker exits, permissions, and build memory
From your Compose deployment directory:
docker compose ps
docker compose logs --tail=100 openclaw-gateway
For state permission errors, compare the mount ownership with the official image's runtime user. Keep persistent mounts and use the documented setup files. Do not delete volumes as a generic repair step.
Exit code 137 can mean a forced kill; check whether the container or host actually reports an out-of-memory event before calling it a proven memory problem. The official Docker guide requires at least 6 GB for a local source-image build. A supported pre-built image avoids that build cost, though runtime tools can still consume significant memory.
FAQ
Do I need Redis or PostgreSQL to fix startup?
They are not prerequisites for the basic installation described by the official quickstart. Diagnose those services only when a specific integration you installed requires them.
Should I erase ~/.openclaw and start again?
Back up and diagnose first. That directory can contain credentials, configuration, and assistant state. A provider quota error will not be solved by deleting it.
What should I include in a useful bug report?
Version, operating system, installation method, failing command, and the relevant redacted error. Say whether Gateway health, the dashboard, and a simple model reply work; those checks narrow the failure.