Installation Errors

This page covers problems that happen during or right after installing OpenClaw: the openclaw command not found, Node.js version conflicts, npm install failures, permission errors, and WSL2-specific issues. If the gateway or channels fail after a successful install, see Gateway issues or Channel errors.

Run openclaw doctor once OpenClaw is on your PATH. After you fix installation (command available and gateway can start), run openclaw doctor to check gateway health, config, and paths. See Quick diagnostics for the full flow.

Quick Diagnostic (After Install)

Once openclaw is installed and in your PATH, use these commands to verify the installation:

# Full health check (do this first)
openclaw doctor

# Optional: apply automatic fixes in dev/test
openclaw doctor --fix

# Check gateway and service status
openclaw status
openclaw status --all

# View logs
openclaw logs --tail 50
openclaw logs --follow

# Validate configuration
openclaw config validate

If you see openclaw: command not found, work through the sections below (PATH and install method) before you can run these commands.

Common Installation Issues & Solutions

Use this table to find your symptom, then read the detailed section for that issue.

Symptom / Error Likely Cause Solution
openclaw: command not found PATH not set or install path not on PATH Add install directory to PATH, or use full path; see "openclaw command not found" below
Node version error / Unsupported engine Node.js < 22 Install Node.js 22+; see Node.js version conflicts
npm install fails (network, ENOENT, build) Network, cache, or native build issues See npm install failures
Permission denied (EACCES, write to data dir) User cannot write to install or data directory Fix ownership/permissions or install without sudo; see Permission denied
Command works in one shell but not another (e.g. WSL) PATH or environment differs (common on WSL2) See WSL2-specific issues
Gateway won't start after install Port in use, config, or bind address Gateway issues - check port, run openclaw doctor
Agent not responding API key or model config Verify API key and model in config; see Model & API errors

"openclaw command not found" (PATH Issues)

Error: Running openclaw in the terminal returns "command not found" (or equivalent on your OS).

Cause: The directory where the openclaw binary was installed is not in your shell's PATH environment variable.

Solutions:

  • One-line installer (macOS/Linux): The installer often adds PATH for you. If you closed the terminal or use a different shell, re-source your profile (e.g. source ~/.bashrc or source ~/.zshrc) or log out and back in. Check the installer output for the exact path it used (e.g. ~/.local/bin or /usr/local/bin).
  • npm global install: Global binaries are usually in npm root -g. Add that directory to PATH, e.g. export PATH="$(npm root -g)/../bin:$PATH" (or the path shown by npm root -g).
  • Manual install: Use the full path to the binary (e.g. /path/to/openclaw/bin/openclaw) or add that directory to your PATH in ~/.bashrc, ~/.zshrc, or ~/.profile.

Prevention: After installing, run which openclaw (or where openclaw on Windows) to confirm the command is found. If not, add the install directory to PATH permanently in your shell config.

See also: Installation hub (platform-specific guides for macOS, Windows (WSL2), Linux, Docker).

Node.js Version Conflicts

Error: During install or when running OpenClaw you see messages like "Unsupported engine", "Node version must be 22.x", or similar.

Cause: OpenClaw requires Node.js 22 or newer. Older LTS (e.g. 18, 20) may fail at install or runtime.

Solutions:

  • Check version: node -v. If it shows v18 or v20, upgrade.
  • macOS/Linux: Use nvm or your package manager to install Node 22+: e.g. nvm install 22, nvm use 22.
  • Windows (WSL2): Install Node 22 inside WSL (e.g. nvm or NodeSource). Do not rely on Windows Node if you run OpenClaw in WSL.
  • Re-run the OpenClaw installer or npm install after switching Node version.

Prevention: Before installing OpenClaw, run node -v and ensure it reports v22.x or higher. See Installation hub for platform-specific requirements.

npm install Failures

Error: npm install -g openclaw (or a project-based install) fails with network errors, ENOENT, or native build failures.

Causes & solutions:

  • Network / registry: Use a working connection; try npm config set registry https://registry.npmjs.org/. If behind a proxy, set npm config set proxy and https-proxy as needed.
  • Cache corruption: Run npm cache clean --force, then retry npm install.
  • Native addons / build tools: On Linux, install build-essential (or equivalent) and Python. On Windows, ensure build tools (e.g. Visual Studio Build Tools) are installed if the installer prompts for them.
  • Permission errors during global install: Avoid sudo npm install -g. Prefer installing Node via nvm or a user-level directory so global installs do not require root. See Permission denied.

Prevention: Use the official installation method for your platform (one-line installer, Docker, or documented npm approach). Ensure Node 22+ and a stable network before running install.

Permission Denied Errors

Error: EACCES when writing to a directory, or "Permission denied" when running openclaw or when the gateway writes to its data directory.

Cause: The user running OpenClaw does not have write access to the install directory, global npm directory, or OpenClaw data directory (e.g. ~/.openclaw or the path in your config).

Solutions:

  • Data directory: Ensure the user running OpenClaw owns and can write to the data directory. If you changed the path in config, create the directory and set ownership: mkdir -p /path/to/data, chown $USER /path/to/data.
  • Global install: Do not use sudo npm install -g openclaw. Use a user-level Node (nvm) or install to a directory in your PATH that you own.
  • File permissions: Config and credential files should be readable only by the running user (e.g. chmod 600 for sensitive files). See Security best practices.

Prevention: Install OpenClaw as the same user that will run it; avoid root. After post-installation, run openclaw doctor to confirm paths and permissions.

WSL2-Specific Issues

On Windows, OpenClaw is typically run inside WSL2. Installation issues specific to WSL2 include:

  • PATH not set in WSL: If you installed OpenClaw inside WSL, use a WSL terminal (e.g. Ubuntu in WSL) to run openclaw. The Windows PATH is separate; ensure your WSL shell profile (~/.bashrc or ~/.zshrc) includes the directory where openclaw is installed.
  • Node version in WSL: Install Node 22+ inside WSL (e.g. via nvm). The Node version in Windows does not apply to WSL.
  • Paths and drives: Use WSL paths (e.g. /home/username/.openclaw) in OpenClaw config when running in WSL, not Windows paths (e.g. C:\Users\...).
  • Gateway binding: Bind the gateway to localhost or the WSL interface so it is not exposed to the Windows network. See Security best practices and Windows installation (WSL2).

For full steps, see Install OpenClaw on Windows (WSL2).

Step-by-Step Debugging After Install

  1. Confirm command: which openclaw (Linux/macOS) or where openclaw (Windows) - if not found, fix PATH (see command not found).
  2. Confirm Node: node -v - must be v22 or higher.
  3. Run doctor: openclaw doctor - addresses many setup issues with hints.
  4. Check status: openclaw status and openclaw status --all.
  5. Review logs: openclaw logs --tail 50 or openclaw logs --follow.
  6. Validate config: openclaw config validate.
  7. Clean restart: openclaw stop, wait a few seconds, then openclaw start.

If the gateway still fails, see Gateway issues. If config validation fails, see Configuration problems.

Related Troubleshooting

Getting Help

If you're still stuck after following this page:

Before posting, run openclaw doctor (once the command is available) and share relevant lines. See Troubleshooting guide for the full topic list.