| name | openclaw-setup |
| description | Use when the user wants to install OpenClaw, set up OpenClaw, onboard OpenClaw, get started with OpenClaw, run the OpenClaw installer, configure the OpenClaw daemon, or deploy OpenClaw on macOS, Linux, or WSL2.
|
OpenClaw Installation & Setup
Guide the user through installing and configuring OpenClaw, a self-hosted gateway connecting messaging apps to AI coding agents.
Prerequisites
- Node.js 22+ required. Check with
node --version.
- OS: macOS, Linux, or Windows (WSL2 strongly recommended over native Windows).
Installation Methods
Installer Script (Recommended)
Detects Node.js, installs if missing, installs the CLI globally via npm, and launches the onboarding wizard.
macOS / Linux / WSL2:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell):
iwr -useb https://openclaw.ai/install.ps1 | iex
Skip onboarding (install CLI only):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
npm (Manual)
npm install -g openclaw@latest
openclaw onboard --install-daemon
If sharp build errors occur:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
pnpm
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon
Build from Source
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon
Onboarding Wizard
Run openclaw onboard --install-daemon to start the interactive wizard. It configures:
- Model/Auth - Choose provider (Anthropic, OpenAI, etc.), enter API key or use SecretRef for env-backed credentials.
- Workspace - Set workspace directory (default:
~/.openclaw/workspace).
- Gateway - Configure port (default 18789), bind address, auth mode (token or password).
- Channels - Optionally set up WhatsApp, Telegram, Discord, etc.
- Daemon - Install as LaunchAgent (macOS) or systemd user service (Linux/WSL2).
- Health Check - Starts gateway and verifies it's running.
Use openclaw configure to reconfigure later.
Service Installation
macOS (LaunchAgent)
Installed automatically by openclaw onboard --install-daemon. Auto-starts on login.
Linux/WSL2 (systemd)
Installed as systemd user service. Enable lingering to survive logout:
sudo loginctl enable-linger $USER
Verification
After install, verify with:
openclaw status
openclaw gateway status
openclaw doctor
openclaw dashboard
Adding Another Agent
openclaw agents add <name>
Creates a separate agent with its own workspace, sessions, and auth profiles.
Common Install Issues
- Command not found: Add npm global bin to PATH:
export PATH="$(npm prefix -g)/bin:$PATH"
- Sharp build errors: Use
SHARP_IGNORE_GLOBAL_LIBVIPS=1 prefix
- pnpm build scripts: Run
pnpm approve-builds -g after install
- systemd stops on logout: Enable lingering with
sudo loginctl enable-linger $USER
- Token not resolved: Set the env var before daemon install, or use plaintext token
Key Paths
| Path | Purpose |
|---|
~/.openclaw/openclaw.json | Main config file (JSON5) |
~/.openclaw/workspace/ | Agent workspace (skills, prompts) |
~/.openclaw/credentials/ | Channel auth data |
~/.openclaw/agents/ | Per-agent state and sessions |
See references/installation-guide.md for detailed per-platform steps.
