Installation and Setup
In this lesson you will install OpenClaw, run the onboarding wizard, connect your first messaging platform, and verify that your agent is running. By the end you will have a working OpenClaw agent responding to your messages.
Prerequisites
Before installing, make sure you have:
- Node.js 22 or later — check with
node --version - A package manager — npm (bundled with Node.js), pnpm, or bun
- An AI provider API key — at least one of: Anthropic, OpenAI, Google Gemini, DeepSeek, or OpenRouter
- A messaging account — WhatsApp, Telegram, Discord, Slack, or any supported channel
- macOS, Linux, or Windows with WSL2 — native Windows is not supported; WSL2 is strongly recommended
Step 1: Install OpenClaw
Choose one of these methods:
npm (recommended):
npm install -g openclaw@latest
pnpm:
pnpm add -g openclaw@latest
curl installer:
curl -fsSL https://openclaw.ai/install.sh | bash
Verify the installation:
openclaw --version
You should see a version number like openclaw/1.x.x.
Step 2: Run the Onboarding Wizard
The onboarding wizard walks you through the entire initial setup:
openclaw onboard --install-daemon
The --install-daemon flag installs the Gateway as a background service (launchd on macOS, systemd on Linux) so it starts automatically and stays running.
The wizard will guide you through four stages:
- Gateway setup — creates your workspace directory and configuration files
- AI model selection — prompts for your API key and preferred model
- Channel connection — connects your first messaging platform
- Skill configuration — enables default skills
Choosing a Model
When the wizard asks which model to use, you can pick any provider you have an API key for:
openclaw onboard --auth-choice anthropic
Or let the wizard prompt you interactively. You can always change models later:
openclaw models set anthropic/claude-opus-4-6
openclaw models list # see all configured models
Step 3: Connect a Messaging Platform
During onboarding, the wizard will ask you to connect at least one channel. Here is what the process looks like for the most popular platforms:
WhatsApp (Most Popular)
- The wizard displays a QR code in your terminal
- Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
- Scan the QR code
- Your agent is now accessible via WhatsApp messages
WhatsApp uses the Baileys library and connects through WhatsApp Web—no business API or phone number required.
Telegram
- Create a bot via @BotFather on Telegram
- Copy the bot token
- Paste it when the wizard asks for your Telegram token
- Message your bot on Telegram to start a conversation
Discord
- Create a Discord application at the Discord Developer Portal
- Create a bot user and copy the token
- Invite the bot to your server using the generated OAuth2 URL
- Paste the token when the wizard asks
Slack
- Create a Slack App in the Slack API dashboard
- Enable Socket Mode and generate an app-level token
- Add the required Bot Token Scopes
- Install the app to your workspace
- Paste the tokens when the wizard asks
You can add more channels later with:
openclaw channels add <channel-type>
Step 4: Verify Your Agent
After onboarding, verify the Gateway is running:
openclaw status
You should see output confirming the Gateway process is active, the connected channels, and the configured model.
Send a test message to your agent on whichever platform you connected:
Hello, are you there?
If your agent replies, the setup is complete.
Workspace Directory Structure
The onboarding wizard creates a workspace directory (default: ~/.openclaw/) with these key files:
~/.openclaw/
├── config.json # Gateway configuration
├── SOUL.md # Agent personality and behavioral traits
├── USER.md # Information about you (preferences, context)
├── AGENTS.md # Agent-level configuration
├── HEARTBEAT.md # Periodic task checklist
├── MEMORY.md # Long-term memory
├── memory/ # Daily logs (YYYY-MM-DD.md)
├── skills/ # Managed/local skills
└── transcripts/ # Conversation JSONL logs
All of these are plain text files. You can open them in any editor, back them up with Git, or search through them with grep.
Common Setup Issues
| Problem | Solution |
|---|---|
command not found: openclaw | Ensure the global npm bin directory is in your PATH |
| QR code expired (WhatsApp) | Run openclaw channels reconnect whatsapp to generate a new code |
ECONNREFUSED on model call | Check that your API key is valid and the provider is reachable |
| Gateway not starting | Check logs with openclaw logs --tail 50 |
| Port conflicts | The Gateway uses port 3100 by default; change with --port flag |
Key Takeaway
Installing OpenClaw takes a single npm command. The onboarding wizard handles the rest—configuring the Gateway daemon, selecting an AI model, and connecting your first messaging platform. Your workspace is a folder of plain text files you fully control. In the next lesson, you will learn how the Gateway processes every message your agent receives.