Installation & Setup

Last December when I first installed OpenClaw, I spent ages getting ERR_MODULE_NOT_FOUND errors. Guess what? I was on Node 18. The infuriating part is the error message said nothing about the Node version — I spent thirty minutes on Stack Overflow before finding someone in GitHub Issue #4872 mentioning "must be Node >= 22." So check your environment first. Don't make my mistake.

Requirements

• Node.js >= 22 (recommend using nvm to manage versions)
• Package manager: pnpm (recommended) or npm
• OS: macOS / Linux / Windows (WSL2)
• Network: needs access to LLM APIs (OpenAI/Claude/Gemini)

Two important notes: Windows users must use WSL2 (Ubuntu recommended) — native Windows won't work. And don't use Bun — there are known bugs with WhatsApp and Telegram connections. It's been argued about in GitHub Issues multiple times and still isn't fully fixed.

Option 1: One-Line Install (Recommended)

macOS / Linux:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (WSL2):

iwr -useb https://openclaw.ai/install.ps1 | iex

This script auto-detects your environment and installs dependencies. Occasionally throws a permission-related warning on certain Linux distros — usually doesn't affect anything. I hit one on Ubuntu 24.04, ignored it, everything worked fine.

Option 2: npm Install

# npm
npm install -g openclaw@latest

# pnpm (recommended)
pnpm add -g openclaw@latest

Verify the install:

openclaw --version
# Should output something like: openclaw v2026.3.x

Option 3: Nix Install

If you're on NixOS or prefer Nix for toolchain management, OpenClaw supports declarative config:

# flake.nix or configuration.nix
environment.systemPackages = with pkgs; [
  openclaw
];

Nix gives you fully reproducible environments — great for keeping teams in sync. But the Nix learning curve... you know how it is. Beginners should stick with npm.

Option 4: Docker Deployment

Good for running 24/7 on a server:

docker pull openclaw/openclaw:latest

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

Option 5: Mobile and Desktop Clients

Besides command-line installation, OpenClaw has native clients:

• macOS menu bar app (macOS 15+ beta) — sits in your menu bar with a push-to-talk floating window. Hold a hotkey, speak your command. Great if you don't want a terminal open all the time
• iOS app — supports Canvas interactive whiteboard, Voice Wake, camera, screen recording, Bonjour auto-pairing with Mac
• Android app — chat, voice (Talk Mode), Canvas, camera/recording, the full package

Mobile and desktop clients work alongside the command-line version with shared data. I personally use the menu bar app + terminal on Mac, iOS app when I'm out. The experience is pretty seamless.

Running the Onboarding Wizard

After installation, run the onboarding wizard:

openclaw onboard --install-daemon

The wizard walks you through 4 steps.

Step 1: Choose Gateway Mode

? Select gateway mode:
  ❯ Local (recommended for personal use)
    Tailscale Serve (remote access)
    Tailscale Funnel (public access)

Pick Local if you're new. You can change it later. Honestly I think it's a bit odd that they put Tailscale options this prominently — most people don't need remote access right away.

Step 2: Configure AI Model

? Select your AI provider:
  ❯ OpenAI (recommended)
    Anthropic (Claude)
    Google (Gemini)
    Local LLM (Ollama)
    Custom API endpoint

Enter your API Key. Keys are stored at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Step 3: Connect Messaging Platform

? Which platforms would you like to connect?
  ◉ Telegram
  ◉ Discord
  ◯ WhatsApp
  ◯ Slack
  ◯ Feishu (飞书)
  ◯ More...

Each platform needs its Bot Token or QR code connection (WhatsApp). You can skip this and configure later. That's what I did — skipped it, then added platforms one by one.

Step 4: Install Daemon

? Install daemon for auto-start?
  ❯ Yes (recommended)
    No

Selecting Yes installs a launchd (macOS) or systemd (Linux) service for auto-start on boot.

Verify Installation

# Check running status
openclaw status

# Health check
openclaw health

# View Gateway dashboard
openclaw gateway status

Open http://127.0.0.1:18789/ in your browser — you should see the OpenClaw Dashboard. If the page won't load — I was confused for a while too — the Gateway probably didn't start successfully. Run openclaw logs and check the output.

Security Audit

After first install, run a deep security check:

openclaw security audit --deep

Also strongly recommend running openclaw doctor — it scans your configuration and flags risky settings like overly broad permissions or insecure Skill configs. First time I ran it, it actually caught several issues. Fixed them and felt much better:

openclaw doctor

There's also openclaw dashboard which opens the Control UI — a graphical management panel that's more intuitive than the command line. Great if you don't want to memorize a bunch of commands:

openclaw dashboard

Common Commands Reference

Directory Structure

After installation, key files live here:

~/.openclaw/
├── agents/           # Agent configs and auth info
├── credentials/      # OAuth credentials
├── skills/           # Globally installed skills
├── workspace/        # Workspace (root directory for file operations)
│   ├── SOUL.md       # Agent persona and behavior rules
│   ├── USER.md       # User preference memory
│   └── AGENTS.md     # Multi-Agent configuration
└── openclaw.json     # Main config file (JSON5 format)

The main config file is openclaw.json (JSON5 format, supports comments) — not config.json. Some old tutorials online still reference config.json; that's from early versions. Don't get misled. Memory files (SOUL.md, USER.md, AGENTS.md) are plain Markdown — edit directly or version-control with Git.

Environment Variables

OpenClaw supports a few key environment variables to override default paths:

# OpenClaw home directory (default ~/.openclaw)
export OPENCLAW_HOME="/path/to/openclaw"

# State data directory
export OPENCLAW_STATE_DIR="/path/to/state"

# Config file path
export OPENCLAW_CONFIG_PATH="/path/to/openclaw.json"

Useful for CI/CD or multi-instance deployments. For daily use, defaults are fine.

Which Install Method for You?

Release Channels

OpenClaw has three release channels: Stable (latest stable), Beta (pre-release), and Dev (syncs with main branch). Use Stable for daily work. Want to try new stuff? openclaw update --channel beta. Dev channel is for contributors and people willing to deal with breakage — not recommended for production.

If you just want to learn and experiment, npm install on your local Mac/Linux is enough. Pick OpenAI for the model (most stable), connect Telegram first (easiest). Don't go straight for Docker multi-platform setups. Not necessary.

Developers should consider building from source — makes it easier to read and modify code. Configure multiple model providers for failover. Docker works well for managing test environments.

For enterprise or team use, go with Docker + Tailscale Serve mode. Set up API Key rotation and cost monitoring. Enable security audit and DM pairing. Someone in the community ran a team of a dozen people for a week without setting spending limits — ended up with a $400+ OpenAI bill at month's end.

Cost Estimates

OpenClaw itself is free, but you pay for LLM API costs. Rough estimates: light usage (daily chat + simple tasks) roughly $1-5/month; moderate usage (file processing + automation) around $5-15/month; heavy usage (24/7 Agent + multi-platform) roughly $15-50/month.

The money-saving strategy is simple: use cheap models (like GPT-4o-mini) for simple tasks, only route to GPT-5 or Claude for complex ones. OpenClaw supports automatic model selection by task complexity — covered in detail in the LLM configuration chapter.

FAQ

Q: Install fails saying Node version is too low?

nvm install 22
nvm use 22

That simple. But this question gets asked at least three times a week in Discord.

Q: Gateway fails to start, port in use?

openclaw gateway --port 18790 --verbose

One more thing: after macOS restarts, leftover processes sometimes hold port 18789. Run lsof -i :18789 to find them, then kill. I've hit this twice now.

Q: WhatsApp QR code scan fails?

Make sure you're using Node, not Bun. Then retry:

openclaw channels login whatsapp

---

All set? Run openclaw status in your terminal to confirm everything's working, then go connect a messaging platform.