Skip to main content

Install & Connect Your Employee

James closed the OpenClaw docs and reached for his terminal. "I want to see this for myself."

Emma picked up her laptop bag. "Install it. Connect WhatsApp. Send one message. I need to check on a deploy. When I get back, tell me what the gateway log taught you."

You are doing exactly what James is doing. Open a terminal. This takes about 15 minutes: install, connect a messaging channel, send your first message.

Everything in this lesson 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.

Install OpenClaw​

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:

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

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:

OpenClaw vX.X.X (latest)

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 Security Warning​

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.

Configure Your LLM Provider​

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:

  • Google Gemini CLI OAuth: A browser window opens for Google sign-in. No API key to create. Fastest path.
  • Google Gemini API key: Visit aistudio.google.com/app/api-keys, create a key, copy it, and paste it into the wizard. Use this if OAuth does not work in your environment.

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:

# See your current model
openclaw config get agents.defaults.model

# Change the default model directly
openclaw config set agents.defaults.model.primary "google/gemini-2.5-flash"
openclaw gateway restart

Connect Your Channel​

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:

  1. Open WhatsApp on your phone
  2. Go to Settings > Linked Devices > Link a Device
  3. Scan the QR code

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:

  • Separate phone just for OpenClaw (recommended): Tells OpenClaw this is a dedicated number for the agent. Safer for automation.
  • This is my Personal Number: Works for learning, but read the caution below. Meta can ban numbers using unofficial automation without warning.

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 Lesson 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 (Lesson 14 covers deployment).

Didn't See WhatsApp in the Wizard?

If the wizard only shows Telegram and Discord, add WhatsApp manually after setup:

openclaw plugins enable whatsapp
openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp
openclaw gateway restart
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.

Every exercise in this chapter works identically through any connected channel or the Control UI.

Finish the Wizard​

The wizard has several more steps after channel setup. Accept these defaults:

Wizard StepWhat to SelectWhy
Web search providerDuckDuckGo (experimental)Free, no API key needed
Configure skills now?Yes, then Skip all API key promptsNo skills needed for the next few lessons (Lesson 6 covers this)
Enable hooks?Skip for nowHooks are covered in Lesson 13
Optional appsSkipmacOS/iOS/Android companion apps are optional
How to hatch your bot?Hatch in TUI (recommended)Opens the terminal chat where your agent comes alive

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.

Send Your First Message​

Now switch to WhatsApp (or your connected channel) and send a message:

Hello. What can you help me with?

The agent responds. You are talking to a real agent with tool access, memory, and the ability to invoke actions on your behalf.

Explore the Dashboard​

Open the Control UI in your browser:

openclaw dashboard

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:

  1. Check openclaw channels status --probe (is the channel connected?)
  2. Check openclaw doctor (is the gateway healthy?)
  3. Check the gateway log for errors:
tail -f ~/.openclaw/logs/gateway.log

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.

Organizing with Groups: Multiple Conversations, One Employee​

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:

  • Each group has its own conversation history and context
  • Commands in one group do not affect other groups
  • Your personal DM session is completely separate from all groups

Create groups by topic to keep conversations focused:

Group NamePurpose
"AI Employee - Work"Daily tasks, scheduling, email
"AI Employee - Code"Code reviews, technical questions
"AI Employee - Learn"Research, book summaries, questions

Setting Up Group Messaging​

The setup wizard does not configure group messaging. The fastest way is to ask your employee in a DM:

Set my WhatsApp group policy to "open" in the config and restart
the gateway. Do not use allowlist mode. Confirm when done and tell
me the current group policy setting.

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:

# For WhatsApp
openclaw config set channels.whatsapp.groupPolicy "open"

# For Telegram
openclaw config set channels.telegram.groupPolicy "open"

# Restart the gateway to apply
openclaw gateway stop && openclaw gateway start

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.

When Things Go Wrong​

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:

openclaw doctor

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 Lesson 6 and Lesson 14.

Also verify that the wizard wrote your gateway mode:

openclaw config get gateway.mode

If this returns local, the wizard completed correctly. If it returns nothing or errors, read the Crash Loop section next.

The Crash Loop​

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.

What Happens​

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:

Gateway start blocked — gateway.mode not configured
Gateway start blocked — gateway.mode not configured
Gateway start blocked — gateway.mode not configured

Why It Happens​

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.

The Fix​

One command:

openclaw config set gateway.mode local

Then restart the gateway:

openclaw gateway restart

Verify it is running:

openclaw channels status --probe

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:

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Then set gateway.mode and start the gateway fresh.

The Auth Cache Gotcha​

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:

~/.openclaw/agents/main/agent/auth-profiles.json

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:

rm ~/.openclaw/agents/main/agent/auth-profiles.json

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.

Free-Tier Quota Limits​

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):

ModelRequests/minRequests/day
gemini-3.1-flash-lite-preview15500
gemini-2.5-flash10250
gemini-2.5-pro550

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:

  1. Bundled plugin exists (check: openclaw plugins list)
  2. Disabled by default (security: nothing auto-activates)
  3. Enable: openclaw config set plugins.entries.<id>.enabled true
  4. Configure the feature-specific settings

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 Lesson 6 to voice in Lesson 9 to custom plugins in Lesson 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.

Try With AI​

Your AI Employee is running. These exercises show you what it can actually do.

Exercise 1: Give It a Real Task​

Send this on WhatsApp (or your connected channel):

Write a short summary of what OpenClaw is and why someone would use it.
Keep it under 100 words.

What you are learning: Your agent generates text and delivers it through WhatsApp. That's the starting point. Lesson 3 shows you what else it can do.

Exercise 2: Test Its Memory​

Send two messages, a few minutes apart:

First message:

My name is [your name]. I work on [your project]. Remember this.

Wait a moment, then send:

What is my name and what do I work on?

What you are learning: The agent remembers across messages within a session. In Lesson 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.

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 remembers me," he said. "I told it my name ten minutes ago and it still knows."

Emma set her bag down. "That is the memory dimension. But right now it is doing the same thing ChatGPT does: generating text and remembering context."

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. Knowing things and doing things are different privileges."

Emma 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 Lesson 3, you find out what happens when you ask it to do something on your machine. That is where the employee part starts."

Flashcards Study Aid​