Step-by-step installation for every platform. No steps skipped. Every common error documented with an exact fix.
Before you install OpenClaw, make sure you have (or will have) the following:
Press Cmd + Space, type Terminal, and hit Enter. Or use iTerm2 if you have it.
Paste this command and press Enter:
curl -fsSL https://openclaw.ai/install.sh | bashThe script will: detect your OS, install Homebrew if missing, install Node.js 24, install OpenClaw via npm, and launch the onboarding wizard.
If macOS shows a warning about an "unidentified developer," go to System Settings → Privacy & Security and click Open Anyway next to the OpenClaw entry. This is a one-time thing.
The wizard (openclaw onboard --install-daemon) will ask you to configure your API provider, set up auth, and optionally connect a channel. See detailed wizard walkthrough below.
Windows has two paths. WSL2 is strongly recommended because it runs OpenClaw in a Linux environment inside Windows, which is the most stable and supported experience. The native PowerShell path works but has more gotchas.
Open PowerShell as Administrator (right-click the Start button → "Windows PowerShell (Admin)" or "Terminal (Admin)") and run:
wsl --installThis installs WSL2 with Ubuntu. Restart your computer when prompted.
After restarting, search for "Ubuntu" in the Start menu. It will finish setup on first launch and ask you to create a username and password. Use a simple username (no spaces). Remember this password; you'll need it for sudo commands.
In the Ubuntu terminal, run:
curl -fsSL https://openclaw.ai/install.sh | bashThis runs the same installer as Mac/Linux. It will install Node.js and OpenClaw.
openclaw onboard --install-daemonRight-click the Start button → Terminal (Admin) or Windows PowerShell (Admin). The "as Administrator" part is important because the installer needs elevated permissions to modify PATH.
iwr -useb https://openclaw.ai/install.ps1 | iexThe script will install Node.js via winget (or Chocolatey as fallback), install OpenClaw via npm, add the bin directory to your PATH, and launch onboarding.
After install, close PowerShell completely and open a fresh terminal. This reloads the PATH so the openclaw command is recognized.
openclaw onboard --install-daemonFor a local Linux machine: open Terminal. For a VPS: ssh user@your-server-ip
curl -fsSL https://openclaw.ai/install.sh | bashOn Ubuntu/Debian, the installer uses NodeSource scripts to install Node.js 24. On CentOS/RHEL, it uses dnf/yum. Handles everything automatically.
openclaw onboard --install-daemonOn a VPS with no TTY (piped input), add --no-prompt for non-interactive setup. Configure via the config file instead.
The --install-daemon flag above handles this. It installs OpenClaw as a systemd service that starts automatically on boot. Check status with:
openclaw gateway statusThe onboarding wizard (openclaw onboard) walks you through the essential configuration. Here's what it will ask:
~/.openclaw/workspace. Accept the default unless you have a reason to change it.openclaw setup to create the workspace identity files (SOUL.md, USER.md, AGENTS.md, etc.) with sensible defaults. These files define who your agent is and how it behaves.openclaw gateway statusShould show "running" or similar. If it shows "stopped," run openclaw gateway start.
openclaw doctorChecks for common configuration issues. Fix anything it flags before proceeding.
openclaw dashboardThis opens a browser at http://127.0.0.1:18789/. You should see the OpenClaw control panel. Try sending a message in the chat interface. If you get a response from the AI, everything is working.
The npm global bin directory isn't in your PATH. Fix:
npm config get prefixCopy the output (e.g., C:\Users\YourName\AppData\Roaming\npm). Go to System Settings → Advanced → Environment Variables, find Path in "User variables," click Edit, and add that directory. Close and reopen PowerShell.
Git isn't installed or not in PATH. Download and install Git for Windows, then close and reopen PowerShell and re-run the installer.
This happens when libvips is installed globally via Homebrew. Fix by setting an environment variable:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latestnpm's global prefix is pointing to a root-owned directory. Fix by changing the global npm prefix to your home directory:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latestSomething else is using that port. Run the gateway on a different port:
openclaw gateway --port 18790Or kill whatever is using 18789. On Linux/Mac: lsof -i :18789 to find the process, then kill [PID].
Usually an API key issue. Check: openclaw doctor. Common causes: API key not set, API key has no credit, wrong provider selected. Check your config at ~/.openclaw/openclaw.json and verify the agents.defaults.model and auth sections.
openclaw setupThis creates the identity files (SOUL.md, USER.md, AGENTS.md, etc.) with default templates. Edit these to customize your agent's personality and context.
Open ~/.openclaw/workspace/USER.md in any text editor. Add your name, timezone, how you like things explained, your work context. The agent reads this at the start of every session, so the more you put in, the better it serves you.
Go to discord.com/developers/applications, create a new application, add a Bot, copy the bot token, and add it to your OpenClaw config under channels.discord.token. Invite the bot to your server and you can chat with your agent from Discord.
Ask the agent to do something useful: "What's the weather today?" or "Search the web for [something relevant to your work] and summarize it." This confirms the full tool stack is working.
Was this guide helpful?