Section 3: Installation Walkthrough

Installation walkthrough

This walkthrough is written for non-technical users. You don't need prior experience. Each step explains what you're doing and why before asking you to do it. Copy commands exactly, run one step at a time, and verify each step before moving on.

What is a terminal, and why are you opening one?

A terminal (also called a command line or shell) is a text-based window where you type instructions directly to your computer. Instead of clicking buttons, you type a command and press Enter. It might look old-fashioned, but it's the fastest and most reliable way to install and manage software like OpenClaw.

Don't be put off if you've never used one. You only need a small set of commands to complete this setup.

How to open a terminal on your system:

• macOS: Press Command + Space, type "Terminal," and press Enter.
• Linux: Look for "Terminal" in your applications menu, or press Ctrl + Alt + T.
• Windows: Search for "PowerShell" or "Windows Terminal" in the Start menu. (Read the Windows note below first.)

Once the terminal is open, you'll see a blinking cursor. That's where you type.

3.1 Prerequisites

Before installing OpenClaw, make sure you have:

• A machine selected from Section 2 (your computer, a VPS, or a home server)
• Terminal access on that machine
• About 30–60 minutes of focused setup time

::: warning Windows users OpenClaw is usually easiest on Linux or macOS. On Windows, either:

1. Use WSL (Windows Subsystem for Linux) — this gives you a Linux-style terminal inside Windows: Microsoft's WSL install guide
2. Or choose the VPS route to avoid local compatibility friction

If this is your first time, the VPS path is often simpler. See Section 2 for guidance. :::

3.2 Install Node.js

OpenClaw is built on Node.js — a software engine that many modern tools use. Think of it as the foundation OpenClaw runs on. You need version 18 or newer.

Step 1: Check if Node.js is already installed. Type this in your terminal and press Enter:

🖥️ Type this in your terminal:

node --version

If you see something like v18.x.x or higher, you already have it — skip to Step 3.3. If you see an error or a version below 18, continue with Step 2.

Step 2: Install Node.js. Pick one method:

Method A: nvm (recommended — works on macOS and Linux)

nvm (Node Version Manager) makes it easy to install and switch Node versions. Copy both commands below — the first installs nvm, then after restarting your terminal, the second installs Node 18.

🖥️ Type this in your terminal:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Close and reopen your terminal (this activates nvm), then run:

🖥️ Type this in your terminal:

nvm install 18
nvm use 18

Method B: direct installer (easiest for beginners on macOS or Windows)

• Go to nodejs.org and download the LTS (Long Term Support) version
• Run the installer and follow the prompts — it's like installing any other app

Step 3: Confirm Node.js and npm are ready. npm is a tool that comes bundled with Node.js and is used to install OpenClaw.

🖥️ Type this in your terminal:

node --version
npm --version

Both should print version numbers without errors. If so, you're ready.

::: beginner What is Node.js? Node.js is the runtime OpenClaw uses. If OpenClaw is the app, Node.js is the engine that runs it. You don't need to understand how it works — just that it needs to be installed first. :::

3.3 Install OpenClaw

Now that Node.js is ready, install OpenClaw itself. This single command downloads and installs OpenClaw system-wide so you can use it from anywhere in your terminal.

🖥️ Type this in your terminal:

npm install -g openclaw@latest

This may take a minute or two. When it finishes, confirm it installed correctly:

🖥️ Type this in your terminal:

openclaw --version

You should see a version number. If you see command not found, check the troubleshooting table in Section 3.7.

::: tip What does -g mean? The -g flag installs the command system-wide ("globally") so openclaw works from any folder, not just the one you installed it in. :::

3.4 Run the onboarding wizard

The wizard walks you through the first-time setup interactively — you won't need to edit any files by hand. It will ask for your API key and set up your basic configuration.

🖥️ Type this in your terminal:

openclaw onboard

The wizard helps you:

1. Configure an API key (you'll need one from Anthropic, OpenAI, or another provider — see Section 4)
2. Create your base configuration file
3. Set initial behavior and personality defaults

Follow the prompts on screen. If you're unsure what to enter for any step, the safe choice is usually the default option shown in brackets.

::: power-user Manual setup option If you prefer manual config, you can skip the wizard and create config files directly. If a command differs by version, run openclaw help to confirm current syntax. :::

3.5 Set up background service

For OpenClaw to be available 24/7 — especially if you want to use it from your phone or other devices — it needs to run as a background service. This means it stays running even when you're not actively using your terminal.

🖥️ Type this in your terminal:

# Install as a background service
openclaw onboard --install-daemon

# Install the gateway service (handles multi-channel communication)
openclaw gateway install

Now check that the gateway started correctly:

🖥️ Type this in your terminal:

openclaw gateway status

You should see a status message indicating the gateway is running. Also check overall health:

🖥️ Type this in your terminal:

openclaw status

3.6 First-run checklist

Before continuing to Section 4, verify these things are working. You don't need to edit any file — just run the commands and read the output.

⚙️ Reference only — do not paste this into any file:

- [ ] OpenClaw responds to `openclaw status` command
- [ ] API key is properly configured (check `~/.openclaw/openclaw.json`)
- [ ] Primary model/auth profile is configured (check `openclaw status`)
- [ ] Gateway is running (test with `openclaw gateway status`)
- [ ] No error messages in logs (`openclaw logs`)

3.7 Common installation issues

::: action Next steps After installation:

1. Confirm service health with openclaw gateway status and openclaw status
2. Configure your first channel
3. Create/refine your assistant persona and rules
4. Run a small real task end-to-end to validate setup :::