Chapter 0: Getting Started
OpenClaw is an AI-powered automation platform that runs as a long-lived Gateway daemon on your machine, exposing AI agents that can read files, execute shell commands, control browsers, send messages, and manage sub-agents. Getting started requires three things: a supported OS (macOS 11+, Ubuntu 20.04+, or Windows with WSL2), Node.js 18+, and an AI provider API key (Anthropic or OpenAI recommended). Installation is straightforward via Homebrew (brew install openclaw) or npm (npm install -g openclaw), followed by running the guided onboarding wizard with openclaw onboard. The wizard walks through workspace location, AI provider selection, API key entry, model choice (Claude Sonnet 4-5 recommended for Anthropic), optional channel setup, and the desktop app.
After installation, the core loop is simple: message → agent → tool → action → response. The Gateway daemon (openclaw gateway start) runs persistently in the background, and all configuration lives in ~/.openclaw/openclaw.json. Communication channels—WhatsApp, Telegram, Discord—are configured in the channels section of the config file and require QR code scanning (WhatsApp) or bot tokens (Telegram/Discord). The workspace directory is where all file operations, scripts, memory files, and project work live, organized by a convention that includes SOUL.md (agent identity), USER.md (user preferences), MEMORY.md (persistent cross-session memory), and a memory/ folder for daily logs.
The desktop app provides a local web interface at http://localhost:18789, while the CLI allows direct chat via openclaw chat "...". Workspace files like SOUL.md and USER.md are editable text files that shape the agent's personality and context on every session start. For WhatsApp specifically, the integration uses whatsapp-web.js under the hood, connecting via QR code the same way WhatsApp Web does. Testing your installation involves verifying file operations, command execution, web search, and memory persistence with a series of probe messages. Common issues—Gateway not responding, permission errors, API key invalidity, port conflicts—are addressed with specific diagnostic commands.
Key Patterns
- **Homebrew or npm install:** `brew install openclaw` on Mac/Linux, `npm install -g openclaw` cross-platform
- **Onboarding wizard:** Run `openclaw onboard` to configure workspace, AI provider, model, and channels
- **Gateway lifecycle:** `openclaw gateway start/status/stop/restart` — the daemon must be running for any interaction
- **WhatsApp via QR code:** Uses whatsapp-web.js; scan the code shown in terminal after enabling in config
- **Workspace-as-context:** SOUL.md, USER.md, and MEMORY.md are read at every session start to restore identity and context
Related Concepts
- [[kelly-handbook-ch2-architecture]] for understanding the Gateway, sessions, and tools architecture
- [[kelly-handbook-ch5-communication-automation]] for deeper WhatsApp, Telegram, and Discord setup
- [[kelly-tweets-openclaw]] for OpenClaw session management patterns