Chapter 2: Installation & Setup

This chapter walks you through installing OpenClaw from scratch, running the onboarding wizard, and getting your gateway live. By the end you will have a working OpenClaw instance ready to connect channels and agents.

Prerequisites

Before installing OpenClaw, make sure your system meets the following requirements:

Requirement	Minimum Version	Check Command
Node.js	18.x or higher	`node --version`
npm	9.x or higher	`npm --version`
OS	macOS, Linux, or Windows (WSL2 recommended)	—
RAM	512 MB free	—
Disk	200 MB free	—

If you do not have Node.js installed, download it from nodejs.org — the LTS version is recommended.

Windows users: OpenClaw works on Windows natively, but WSL2 (Windows Subsystem for Linux) gives you a smoother experience, especially when connecting to channels like iMessage or Signal that rely on Unix tooling.

Step 1 — Install OpenClaw Globally

Install the OpenClaw CLI via npm:

npm install -g openclaw@latest

This installs the openclaw command globally on your system. Verify the installation:

openclaw --version

You should see output like:

openclaw/2.x.x linux-x64 node-v20.x.x

Step 2 — Run the Onboarding Wizard

OpenClaw includes an interactive onboarding wizard that creates your initial configuration file and installs the background daemon.

openclaw onboard --install-daemon

The wizard will ask you a series of questions:

? Where should OpenClaw store its config? (~/.openclaw)  [Enter to confirm]
? Which AI provider do you want to use by default?
  ❯ Anthropic (Claude)
    OpenAI (GPT-4)
    Google (Gemini)
    Ollama (local)
? Enter your Anthropic API key: sk-ant-...
? Which Claude model should be the default?
  ❯ claude-sonnet-4-6
    claude-opus-4-7
    claude-haiku-4-5
? Create a default workspace named "personal"? (Y/n)  Y
? Install as a system daemon (auto-start on login)? (Y/n)  Y

After answering, the wizard:

Creates ~/.openclaw/ directory
Writes your openclaw.json config file
Installs the daemon so OpenClaw starts automatically when your machine boots

Step 3 — Start the Gateway

If you chose to install the daemon, OpenClaw is already running in the background. You can confirm this:

openclaw status

● openclaw gateway
  Status:  running
  PID:     12483
  Uptime:  0m 14s
  Channels: 0 connected
  Agents:  1 loaded (claude-sonnet-4-6)
  Workers: 4

If you did not install the daemon, start the gateway manually:

openclaw start

To run it in the foreground with live logs (useful during development):

openclaw start --foreground

The Config File: `openclaw.json`

The onboarding wizard creates your config file at ~/.openclaw/openclaw.json. Here is what a minimal config looks like after onboarding:

{
  "version": "2",
  "gateway": {
    "port": 3100,
    "host": "localhost"
  },
  "agents": [
    {
      "id": "default",
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "apiKey": "sk-ant-..."
    }
  ],
  "workspaces": [
    {
      "id": "personal",
      "name": "Personal",
      "agentId": "default",
      "channels": []
    }
  ]
}

Field	Description
`gateway.port`	Port the OpenClaw HTTP server listens on (default: 3100)
`gateway.host`	Bind address — use `0.0.0.0` to expose to the network
`agents`	List of AI backends (Claude, GPT, Gemini, Ollama)
`workspaces`	Logical groups of channels and users

You will expand this file as you connect channels in the coming chapters. Never commit your openclaw.json to a public repository — it contains your API keys.

Daemon Management

The --install-daemon flag registers OpenClaw with your OS's process manager:

OS	Process Manager
macOS	launchd (plist in `~/Library/LaunchAgents/`)
Linux (systemd)	systemd user service
Windows	Windows Task Scheduler

Useful daemon commands:

openclaw daemon start      # Start the daemon
openclaw daemon stop       # Stop the daemon
openclaw daemon restart    # Restart the daemon
openclaw daemon uninstall  # Remove from startup
openclaw daemon logs       # Tail daemon logs

Updating OpenClaw

To update to the latest version:

npm install -g openclaw@latest
openclaw daemon restart

Check the GitHub releases page for changelogs before upgrading in production.

Uninstalling

To completely remove OpenClaw:

openclaw daemon uninstall   # Remove from startup
npm uninstall -g openclaw   # Remove CLI
rm -rf ~/.openclaw          # Remove config and data

Warning: Removing ~/.openclaw deletes all your configuration, channel credentials, and conversation history. Back it up first if needed.

Troubleshooting Installation

`openclaw: command not found`

npm's global bin directory is not in your PATH. Find where npm installs global packages:

npm config get prefix

Add the bin subdirectory of that path to your PATH in ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.npm-global/bin:$PATH"

Port 3100 already in use

Another process is using the default port. Change it in openclaw.json:

"gateway": {
  "port": 3200
}

Then restart: openclaw daemon restart

Onboarding wizard exits without finishing

This usually means a network error when validating your API key. Re-run the wizard and confirm your API key is correct:

openclaw onboard

You can skip key validation with --skip-validate if you are offline:

openclaw onboard --skip-validate

Tip: Keep openclaw daemon logs --follow open in a separate terminal while you work through the next few chapters. Watching the logs in real time makes it much easier to understand what OpenClaw is doing when you connect a channel or send a message.

Next: Chapter 3 — Onboarding Dashboard — Explore the OpenClaw web dashboard, manage workspaces, and monitor your gateway from a browser.