Skip to main content

Install & Connect Your Employee

What You Will Learn​

In this lesson, 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 lesson 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 Lesson 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 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 Windows PowerShell as Administrator. The fastest way: press the Windows key, type powershell, right-click Windows PowerShell, and select Run 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​

Pick Google. The wizard lists 25+ providers — Anthropic, OpenAI, OpenRouter, DeepSeek, Ollama, Gemini CLI OAuth, and more — but Google Gemini has the most generous free tier and enough daily requests to finish this chapter without touching your credit card.

The wizard then asks for a Google Gemini API key. Visit aistudio.google.com/app/api-keys, create a key, copy it, and paste it into the wizard. Free, no credit card.

Next, the wizard asks you to pick a default model. Scroll down and select google/gemini-3.1-flash-lite-preview. It has the most free daily requests of any available model, enough for every exercise in this chapter. If quota runs out mid-session, switch to google/gemini-2.5-flash, which has a separate quota.

Prefer browser sign-in? Use Gemini CLI OAuth instead

The wizard has a separate provider entry called Gemini CLI OAuth that lets you sign in with Google in a browser instead of managing an API key. It needs the gemini-cli tool installed (brew install gemini-cli or npm install -g @google/gemini-cli) and it is an unofficial integration — not endorsed by Google, and some users have reported account restrictions after using third-party Gemini OAuth clients. Prefer the plain API key path if you are on a shared or production Google account.

Don't want to use Google at all? Use OpenRouter

Pick OpenRouter from the provider list, visit openrouter.ai to create a free API key, and choose any model tagged "free." OpenRouter rotates its free model lineup, so availability varies.

Change Your Model Later​

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

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

Change Your API Key Later​

Rotating a key, refreshing expired credentials, or swapping to a fresh one? Four options. The first three update an API key; the fourth abandons keys entirely and switches to browser OAuth. Grab a new key from aistudio.google.com/app/api-keys first if you are staying with API keys.

Most students should use Option 1. Options 2 and 3 are for specific needs (scripted rollouts, dotfile-managed secrets, CI pipelines).

Option 1: Re-run the wizard for the model section. Safest path. Walks you back through provider, API key entry, and model selection so you can paste the new key.

openclaw configure --section model

Option 2: Edit the config file directly. Open ~/.openclaw/openclaw.json and update the apiKey field under models.providers.google with your new key:

{
  models: {
    providers: {
      google: { apiKey: "paste-new-key-here" },
    },
  },
}

Save and restart the gateway:

openclaw gateway restart

Option 3: Env var + config reference (expert path). Export the key as a shell environment variable, then reference it from ~/.openclaw/openclaw.json with ${VAR} syntax instead of hardcoding. This keeps secrets out of the config file and plays nicely with dotfiles and CI.

# Add to ~/.zshrc or ~/.bashrc for persistence
export GOOGLE_API_KEY="your-key-here"

Then in ~/.openclaw/openclaw.json:

{
  models: {
    providers: {
      google: { apiKey: "${GOOGLE_API_KEY}" },
    },
  },
}

OpenClaw expands ${VAR_NAME} references inside any config string at load time. Uppercase names only, and a missing or empty variable throws an error at load time instead of silently failing. Save and restart:

openclaw gateway restart

Option 4: Ditch API keys entirely and switch to Gemini CLI OAuth. This is not a key rotation — it replaces API-key auth with browser-based Google sign-in for the Gemini provider. Install gemini-cli first (brew install gemini-cli or npm install -g @google/gemini-cli), then:

openclaw models auth login --provider google-gemini-cli --set-default

A browser window opens for Google sign-in. OpenClaw sets Gemini CLI OAuth as your default provider. Same unofficial-integration caution applies as in the tip above.

Cache takes priority

OpenClaw caches credentials in ~/.openclaw/agents/main/agent/auth-profiles.json, and that cache wins over both the env var and the config file. If a fresh key seems ignored, delete the cache file (see "The Auth Cache Gotcha" section below) and re-run Option 1.

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:

OpenClaw connects to WhatsApp the same way WhatsApp Web on your laptop does: it pairs with a WhatsApp account on your phone by scanning a QR code. Whatever account you pair becomes your AI Employee. Every message sent to that WhatsApp number is received by the Employee, and every reply from that number is the Employee talking.

Before you scan anything, you need to decide one thing: which WhatsApp account should your AI Employee live on? You have two choices.

  • Option A — Dedicated number (recommended): A second WhatsApp account, separate from your personal one. Your regular WhatsApp stays untouched. You DM the Employee from your main WhatsApp when you want to talk to it. About 5 minutes of prep.
  • Option B — Personal number: Your own existing WhatsApp account becomes the Employee. No prep, but two real risks: Meta can ban accounts running unofficial automation (the plugin uses a reverse-engineered protocol, not an official API), and when strangers DM the Employee the auto-reply exposes the bound phone number — which in Option B is yours. Learning only; read the full caution below before committing.
Not ready to decide? Skip WhatsApp for now

Pick Telegram or Discord in the wizard instead. You can add WhatsApp later with openclaw configure --section channels once you have picked a path.

Option A: Set up a dedicated number (~5 min)​

Before you scan the QR code, complete these three steps.

  1. Get a second phone number. A spare physical SIM, an eSIM, a Google Voice number (US), Twilio, or any prepaid number you can receive an SMS on.
  2. Install WhatsApp Business from the App Store or Play Store. It is free, a separate app from regular WhatsApp, and both apps run side-by-side on the same phone (on both iOS and Android).
  3. Open WhatsApp Business and register it with your second number. Confirm the SMS code. Done. You now have two WhatsApp accounts on one phone: regular WhatsApp on your main number, WhatsApp Business on the second.

Android users on WhatsApp from late 2023 onward can skip WhatsApp Business and use the native "dual account" feature inside regular WhatsApp instead. Same result.

Option B: Use your personal number​

Nothing to install. Your existing WhatsApp becomes the AI Employee. Read the Personal Number Risk caution below before you scan.

Scan the QR code​

Select WhatsApp (QR link) from the wizard's channel list. A QR code appears in your terminal.

On your phone:

  1. Open WhatsApp Business if you chose Option A, or regular WhatsApp if you chose Option B. Be deliberate — scanning from the wrong app links the wrong account.
  2. Go to Settings → Linked Devices → Link a Device.
  3. Scan the QR code.

The terminal prints Linked after restart; web session ready. You are paired. From this moment on, every message sent to that WhatsApp account is received by your OpenClaw AI Employee, and every reply from that account is the Employee talking.

Answer the wizard's three questions​

1. Phone setup.

  • Separate phone just for OpenClaw — pick this if you followed Option A.
  • This is my Personal Number — pick this if you followed Option B.

This question records which path you chose and adjusts a few defaults downstream.

2. DM policy — who can message the AI Employee?

Pick Pairing for this chapter. It is the safest default. The full menu, so you know what you are skipping:

PolicyHow someone reaches your AI EmployeeWhen to use
Pairing (default, recommended)A stranger DMs the Employee. The Employee replies with a one-time code. You approve them from the terminal. They chat.Learning, personal use
AllowlistYou pre-add specific phone numbers ahead of time. Only those numbers can DM. Everyone else is ignored.Small team with known users
OpenAnyone who knows the number can DM it. No approval step.Public bots, risky, covered in Lesson 14.
DisabledAll DMs blocked.Temporary lockdown

In Pairing mode, your own number is auto-authorized, so your first self-test works immediately without an approval step. When a stranger messages the Employee later in the chapter, you will approve them with openclaw pairing approve whatsapp <CODE>. The lesson walks you through it when you need it.

3. allowFrom. Pick Unset allowFrom (default). allowFrom is the config field that holds the list of pre-approved phone numbers. Leaving it unset is correct for Pairing mode.

Personal Number Risk (read before choosing Option B)

The WhatsApp plugin uses the Baileys library, which reverse-engineers the WhatsApp Web protocol. It is not an official Meta API and violates their Terms of Service. Meta can ban accounts running unofficial automation without warning or appeal.

Privacy angle: when a stranger DMs the AI Employee, the auto-reply contains a pairing code that includes the bound phone number. On Option B, that is your real number exposed to anyone who DMs the Employee.

For learning, the risk is low — the Employee is behind Pairing mode. For production, use Option A with a dedicated number. Lesson 14 covers deployment.

Small Delight: The 👀 Ack Reaction

OpenClaw can auto-react to your incoming WhatsApp message with an eye emoji the moment it starts processing, so you see "I got it, thinking…" before the full reply lands. It is configured under channels.whatsapp.ackReaction in openclaw.json:

ackReaction: {
  emoji: "👀",
  direct: true,
  group: "mentions"
}

direct: true reacts on DMs; group: "mentions" reacts only when the bot is @mentioned in a group. Small touch, big "this thing is alive" feeling.

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.

A Friend Tests Your Bot? Approve Them First

Your own number is auto-approved by pairing mode, so your first self-test works immediately. The first time a different number messages your bot, that person receives a one-time pairing code instead of a reply. You have to approve them.

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

After approval, that number can DM your bot normally. Two rules to know:

  • Pairing codes expire after 1 hour
  • Each channel allows up to 3 pending requests at a time

Lesson 14 covers the other DM policies (allowlist, open, disabled) for production scenarios. For now, pairing mode is the right default.

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.

What You Should Remember​

The Universal Setup Pattern​

Every agent framework you will encounter follows the same five steps:

  1. Install the runtime
  2. Configure intelligence (LLM provider and model)
  3. Connect I/O (messaging channel, voice, or web)
  4. Verify the connection works end-to-end
  5. Secure the deployment (localhost binding, pairing mode)

When Things Break​

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 Lesson 3, you send it something a chatbot would refuse. That is where the employee part starts."

Flashcards Study Aid​