In this chapter, you will install OpenClaw from scratch, survive the most common installation failure, and connect your first messaging channel.
By the end, you should be able to explain the universal setup pattern. This chapter is pure hands-on. If you finish without opening a terminal, something went wrong.
James closed the OpenClaw docs and reached for his terminal. "Six dimensions on a notepad are nice. But I have been burned before." He looked at Emma. "At my old company, we evaluated three warehouse management systems. All three had perfect feature lists. Two of them crashed during the pilot install."
Emma nodded. "So what do you want to do?"
"Install it," James said. "Right now. If it breaks during setup, I want to know before I build anything on top of it."
Emma picked up her laptop bag. "Good instinct. Install it. Connect WhatsApp. Send one message." She paused at the door. "I need to check on a deploy. When I get back, tell me two things: whether it actually works, and what the gateway log taught you when it did not."
You are doing exactly what James is doing. The feature list sounded promising in Module 9.1, Chapter 1. Now you find out if the install matches the marketing.
Open a terminal. This takes about 15 minutes: install, connect a messaging channel, send your first message.
Everything in this chapter is free. You need a computer with a terminal, Node.js 22+, a Google account, and a WhatsApp, Telegram, or Discord account. No paid API keys. No credit cards.
OpenClaw installs through a single terminal command. The installer detects your OS, checks prerequisites (Homebrew and Node.js on macOS), and installs the OpenClaw package automatically.
Open PowerShell as Administrator:
The installer handles everything: checking for Node.js (installing it if needed), installing the OpenClaw npm package, and creating your configuration directory at ~/.openclaw/. When it finishes, you see a version confirmation:
What happens next matters: the installer transitions directly into the setup wizard. Do not close your terminal. Do not skip the wizard. Read what it asks you.
npm Fallback
If the install script fails, install directly via npm: npm install -g openclaw@latest, then run openclaw to start the wizard. To restart the wizard later, use openclaw setup --wizard.
The first thing the wizard shows you is a security acknowledgment. Read it.
OpenClaw tells you directly: it is a hobby project, still in beta, and a bad prompt can trick it into doing unsafe things. It recommends a security baseline (pairing and allowlists, sandboxing, least-privilege access) and links to docs.openclaw.ai/gateway/security.
You must acknowledge: "I understand this is powerful and inherently risky. Continue?"
This is a teaching moment, not a formality. An agent with access to your email, calendar, and files is a high-value target. The habit of reading security warnings starts here.
The wizard shows a long list of providers: Google, Anthropic, OpenAI, OpenRouter, DeepSeek, Ollama, and 25+ others. Select Google (Gemini API key + OAuth).
The wizard then offers two authentication methods:
Either method is free. No credit card required.
The wizard then asks you to pick a default model. Scroll down and select google/gemini-3.1-flash-lite-preview (1024k context, reasoning capable). It gets the most free daily requests of any available model, enough for every exercise in this chapter. If quota runs out during a session, switch to google/gemini-2.5-flash (separate quota, slightly slower).
Alternative: OpenRouter
If you prefer not to use Google, select OpenRouter from the provider list. Visit openrouter.ai to create a free API key, then choose any model tagged "free." OpenRouter rotates free models, so availability varies.
To check or change your model later:
The wizard asks which messaging platform to connect. WhatsApp, Telegram, and Discord are all fully supported first-class channels. Pick whichever you use daily:
Select WhatsApp (QR link). The wizard displays a QR code in your terminal:
The terminal prints Linked after restart; web session ready. No tokens to copy; authentication happens through the QR scan.
The wizard then asks three setup questions:
1. Phone setup: The wizard offers two options:
For this chapter, either option works. If you only have one phone number, select "Personal" and continue. If you have a spare SIM or virtual number, use that.
2. DM policy: Select Pairing (recommended). Unknown senders receive a pairing code and must be approved before the agent engages. Your own number is auto-authorized. The other options (allowlist, open, disabled) are for production scenarios covered in Chapter 14.
3. allowFrom: Select Unset allowFrom (default). You can restrict access to specific numbers later.
Personal Number Risk
WhatsApp integration uses the Baileys library, which reverse-engineers the WhatsApp Web protocol. This is not an official Meta API and violates their Terms of Service. Meta can ban accounts using unofficial automation without warning or appeal.
There is also a privacy reason: when an unknown number messages your agent, the bot auto-replies with a pairing code that includes your phone number. With a personal number, your real number is exposed to anyone who messages the bot.
For learning, the risk is low (your agent is behind pairing mode). For production, use a dedicated number (Module 9.1, Chapter 14 covers deployment).
Didn't See WhatsApp in the Wizard?
If the wizard only shows Telegram and Discord, add WhatsApp manually after setup:
QR Code Expires Quickly
The QR code expires in about 60 seconds. If it times out, run openclaw channels login --channel whatsapp to generate a new one.
Select Telegram (Bot API). The wizard walks you through creating a bot:
Paste the token into the wizard. No manual JSON editing; the installer writes the configuration for you.
Protect Your Bot Token
Your bot token grants full control over your Telegram bot. Treat it like a password. Never share it publicly or commit it to Git.
Telegram Availability
Telegram is blocked in some regions (including Pakistan). If you cannot access Telegram, use WhatsApp or Discord instead.
Select Discord (Bot API). The wizard needs three things: a server name (guild), a channel name, and a bot token. You will create the server and channel first, then create the bot.
Step 1: Create a Discord Server
If you already have a server you want to use, skip to Step 2.
Remember this name. The wizard will ask for it.
Step 2: Create a Channel
Your server comes with a #general channel by default. You can use that, or create a dedicated channel:
Remember this channel name. If you are using the default, the channel name is general.
Step 3: Enable Developer Mode
You will need Developer Mode to copy IDs for troubleshooting later:
Step 4: Create the Bot and Get the Token
Step 5: Invite the Bot to Your Server
Step 6: Enter the Details in the Wizard
The wizard asks for three values:
The wizard writes the configuration for you. No manual JSON editing required.
Protect Your Bot Token
Your bot token grants full control over your Discord bot. Treat it like a password. Never share it publicly or commit it to Git.
Every exercise in this chapter works identically through any connected channel or the Control UI.
The wizard has several more steps after channel setup. Accept these defaults:
The TUI (Terminal User Interface) opens and sends "Wake up, my friend!" to your agent. The agent responds and asks about your preferences. This is your first conversation. Tell it your name, what you do, and how you want it to behave. This is not cosmetic: what you say here seeds the agent's persistent memory.
The Control UI is also available at http://127.0.0.1:18789/. You can open it anytime with openclaw dashboard.
Now switch to WhatsApp (or your connected channel) and send a message:
The agent responds. You are talking to a real agent with tool access, memory, and the ability to invoke actions on your behalf.
Open the Control UI in your browser:
This copies the dashboard URL (with auth token) to your clipboard and opens it. You see your agent's status, connected channels, active sessions, and message history. The dashboard is the visual confirmation that your Personal AI Employee is running.
Bookmark this URL. You will use it throughout the chapter alongside the terminal and WhatsApp.
If you do not receive a response from WhatsApp within 30 seconds:
The log is your source of truth. Every message received, every tool invoked, every error thrown appears here. If the agent is silent, the log tells you why.
You have one agent, but you will not want all your conversations in one thread. A coding question, a personal schedule check, and a research task do not belong in the same conversation history. Groups solve this.
Every WhatsApp or Telegram group your employee joins gets its own isolated session. This means:
Create groups by topic to keep conversations focused:
The setup wizard does not configure group messaging. The fastest way is to ask your employee in a DM:
Discord uses channels within a server instead of groups. Create additional channels in your Discord server (e.g., #ai-work, #ai-code) and mention the bot in whichever channel you want to use. Each channel gets its own isolated session automatically.
Your employee edits ~/.openclaw/openclaw.json, sets groupPolicy to "open", and restarts the gateway. Ask "What is your current group policy?" to verify it actually changed.
Keep It Open, Not Allowlist
Your employee may try to "improve" the setup by switching from open to allowlist mode with explicit group IDs. Do not let it. Allowlist mode requires exact group ID matching and breaks easily: messages stop arriving but the employee reports success. If groups stop working after they were working before, the first thing to check is whether the policy was changed. Ask: "What is my current group policy? If it is not open, change it back to open and restart the gateway."
Manual Fallback
If the employee cannot modify its own config, use the CLI directly:
After enabling group messaging, create a group (you can be the only member besides the bot), then @mention the bot. Even with groupPolicy open, the bot requires a mention to respond in groups, preventing it from replying to every message in a busy thread.
One Employee, Many Contexts
This is not multi-agent. You have one employee with one set of skills and one personality. Groups give you separate conversation threads, like having different chat windows open with the same colleague for different projects. Your employee's identity files (SOUL.md, USER.md, IDENTITY.md from hatching) load in every session including groups, so its name and personality are consistent. But MEMORY.md (long-term curated memory) only loads in your main private session. Conversation history stays fully isolated per group.
If everything worked and your agent is responding, skip ahead to Try With AI. The sections below cover the three most common issues. Come back here if you hit one.
Your first-response tool for any issue:
This checks your Node.js version, network connectivity, configuration paths, and service status. Fix anything it flags before digging deeper. You will use openclaw doctor again in Module 9.1, Chapter 6 and Module 9.1, Chapter 14.
Also verify that the wizard wrote your gateway mode:
If this returns local, the wizard completed correctly. If it returns nothing or errors, read the Crash Loop section next.
This is the single most common installation failure, and it teaches a pattern you will use for the rest of this chapter: when something breaks, the gateway log has the answer.
The setup wizard (or openclaw doctor) installs a macOS LaunchAgent (a background service that starts automatically at login) for the gateway. On Linux, it uses systemd instead. Either way, the gateway starts automatically at boot. Useful, except for one problem: if gateway.mode is not set in the configuration, the gateway crashes on startup. macOS restarts it. It crashes again. Eighteen restarts in 10 minutes.
The log shows:
The wizard or doctor installed the LaunchAgent (the service that keeps the gateway running) before the configuration it depends on was complete. This is a real bug: the background service was registered before its prerequisite config existed.
One command:
Then restart the gateway:
Verify it is running:
You should see channel status output (even if no channels are connected yet, the gateway process should be alive).
The Crash Loop Escape Hatch
If the gateway is crash-looping and you cannot stop it through normal commands, remove the LaunchAgent manually:
Then set gateway.mode and start the gateway fresh.
This catches everyone. Even developers who have rotated API keys hundreds of times.
When you configure an LLM provider (Google, OpenAI, Anthropic, OpenRouter), OpenClaw caches your credentials in a file:
The problem: this cache takes priority over environment variables. If you set a fresh GOOGLE_API_KEY or ANTHROPIC_API_KEY in your shell, OpenClaw ignores it and uses the cached (possibly expired) key from auth-profiles.json.
This is the opposite of what most developers expect. Environment variables should override cached values. In OpenClaw, they do not.
The fix when model calls fail with auth errors after a key rotation:
Then reconfigure your provider. The next request will use your fresh credentials.
Delete the Cache, Not the Config
auth-profiles.json is a cache file, not your main configuration. Deleting it forces OpenClaw to re-authenticate. Your main configuration at ~/.openclaw/openclaw.json is untouched.
If your agent stops responding with quota errors, check your limits. Google Gemini's free tier has per-model quotas (check Google AI Studio for current limits):
gemini-3.1-flash-lite-preview gives you the most room. If you hit the daily limit, switch to gemini-2.5-flash (separate quota) by running openclaw configure --section model.
OpenRouter Free Tier
OpenRouter's free models have much lower limits (1-2 requests before rate limiting). If you started with OpenRouter and hit 404 errors, switch to Google Gemini. The OAuth setup takes 2 minutes and the free quota is significantly larger.
The Activation Dance
Every OpenClaw capability follows the same four steps:
Restart the gateway after step 3. You will encounter this pattern repeatedly.
The Activation Dance is OpenClaw's core design pattern. Every feature you enable in this chapter, from skills in Module 9.1, Chapter 6 to voice in Module 9.1, Chapter 9 to custom plugins in Module 9.1, Chapter 13, follows these same four steps. Once you see it, every new feature feels familiar. Before you see it, every new feature feels broken on first try.
Your AI Employee is running. These exercises show you what it can actually do.
Send this on WhatsApp (or your connected channel):
What you are learning: Your agent generates text and delivers it through WhatsApp. That's the starting point. Module 9.1, Chapter 3 shows you what else it can do.
Send two messages, a few minutes apart:
First message:
Wait a moment, then send:
What you are learning: The agent remembers across messages within a session. In Module 9.1, Chapter 4, you will learn about persistent memory (MEMORY.md) that survives across sessions and channels. For now, notice: this is not a stateless chat window. It knows who you are.
Every agent framework you will encounter follows the same five steps:
The gateway log (~/.openclaw/logs/gateway.log) is your source of truth. The dashboard shows summaries; the log shows everything. openclaw doctor is your first-response diagnostic tool.
When Emma came back, James held up his phone. A WhatsApp conversation was open. The agent had summarized what OpenClaw is and remembered his name from an earlier message.
"It works," James said. "And it remembers me. I told it my name ten minutes ago and it still knows."
"Did the install go clean?" Emma asked.
"No," James said. "The gateway crashed in a loop. Missing gateway.mode." He turned his laptop to show the terminal. "But the log told me exactly what was wrong. Three lines, same error, over and over. One config command fixed it."
Emma set her bag down. "That is the pattern. When something breaks, the log has the answer. Not the dashboard, not the error message in chat. The log."
James nodded. "Fair. But right now it is doing the same thing ChatGPT does: generating text and remembering context. I could get this from any chatbot."
Emma looked at him. "So what is different?"
James thought about that. "At my old warehouse, when we onboarded a temp worker, they could answer questions about the company by day two. Read the handbook, knew the jargon. But they could not unlock the stockroom or sign for a delivery." He looked at the WhatsApp thread. "This agent knows things. But I have not tested whether it can do things."
"Knowing and doing are different privileges," Emma said. She paused. "I skipped that distinction the first time I taught this. Went straight to 'install skills' without establishing why access matters. Three students thought the agent was broken because it could not list their files." She opened her laptop. "In Chapter 3, you send it something a chatbot would refuse. That is where the employee part starts."