Skip to main content

Setup Your AI Employee (Free)

In Lesson 1, you saw why the AI Employee paradigm matters and how OpenClaw validated it at scale. Now you build one yourself. In the next 30-45 minutes, you will have a working AI Employee on your phone -- not a demo, not a simulation, but a real agent that can research, write, analyze, and remember.

Everything in this lesson is free. Google Gemini's free tier gives you enough tokens to complete this entire chapter without spending a dollar. You need a computer with a terminal, Node.js 22 or later, a Google account, and a WhatsApp, Telegram, or Discord account. No paid API keys to create. No credit cards to enter.

Honest time estimate: Budget 45 minutes. The happy path takes 15-20 minutes, but Node.js version issues, network hiccups, and shell PATH problems are common first-time obstacles. Troubleshooting is where real learning happens.

Alternative: OpenRouter

If you prefer not to use Google, OpenRouter (openrouter.ai) provides free models through a single API key. Select OpenRouter instead of Google when the QuickStart wizard asks for your provider.

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 2026.2.15 (3fe22ea)

What happens next is important: the installer transitions directly into the setup wizard. You do not need to run a separate onboarding command. Read what the installer asks you -- do not blindly press Enter.

npm Alternative

If the install script fails, install directly via npm: npm install -g openclaw@latest, then run openclaw to start the wizard. To restart wizard use openclaw setup --wizard

If you run into any error run the built-in diagnostic before continuing openclaw doctor. This checks your Node.js version, network connectivity, configuration paths, and service status. Fix any issues it flags before proceeding -- it catches the most common setup problems (wrong Node version, missing PATH entries, port conflicts) in seconds.

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.

QuickStart Onboarding​

Select QuickStart when the wizard asks. It configures sensible defaults: gateway port 18789, loopback binding (127.0.0.1), token-based auth, Tailscale off. These are secure for local development.

Connect Your AI (Google Gemini)​

Select Google as your model provider, then Google Gemini CLI OAuth as the authentication method.

A browser window opens for Google sign-in. Authorize the connection. The wizard completes authentication automatically via an OAuth callback on localhost -- no keys or tokens to copy.

The wizard then asks you to pick a model:

  • gemini-2.0-flash -- fast, lightweight
  • gemini-2.5-flash -- reasoning capable, 1024k context (recommended)
  • gemini-2.5-pro -- most capable, slower
  • gemini-3-flash-preview / gemini-3-pro-preview -- latest previews

Select gemini-2.5-flash. It balances capability with speed for this chapter.

Connect Your Messaging 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 two setup questions:

  • Phone setup: Select Separate phone just for OpenClaw (recommended). See the caution below for why.
  • DM policy: Select Pairing (recommended). Unknown senders must request access before the bot engages in full conversations. Your own number is auto-authorized.
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
Use a Dedicated Phone Number

WhatsApp integration uses the Baileys library, which reverse-engineers the WhatsApp Web protocol. This is not an official API and violates Meta's 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 you, the bot auto-replies with a pairing code that includes your phone number. Use a dedicated number -- not your personal one -- so your real number is never exposed.

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 task in this chapter works identically through any connected channel or the Control UI.

Skills and Gateway​

The wizard shows a skills status summary and asks if you want to configure skills now. Select No -- none are required for this chapter. You can always add skills later with openclaw skills.

The wizard then configures the gateway as a background service (LaunchAgent on macOS, systemd on Linux) and starts it. You see a channel status confirmation:

WhatsApp: linked (auth age 0m)

Your AI Employee's infrastructure is live.

Meet Your AI Employee​

The wizard offers first contact options. Select Hatch in TUI (recommended).

The terminal opens an interactive session. OpenClaw sends: "Wake up, my friend!" Your AI Employee responds: "Hey there! I just came online. Who am I? Who are you?"

Give it a name. Tell it what you do. Describe the work you want help with. If you are not sure where to start, try this:

Introduce yourself and tell me what you can help with.

The agent introduces itself and explains its capabilities. From there, personalize: tell it your name, your role, and what kind of work you need help with. The agent remembers this first conversation and uses it to shape future interactions.

This matters more than it seems. The difference between a generic chatbot and a personal AI Employee starts with this moment of personalization. You are not configuring a tool. You are onboarding a colleague.

Connect on Your Messaging Channel​

WhatsApp does not require a separate pairing step. Since you linked your own WhatsApp account via QR code, your number is automatically authorized. Open WhatsApp and send a message -- your AI Employee responds directly. Same agent, same memory as the TUI session, just a different channel.

Will it respond to other people? OpenClaw has two layers of access control that determine who your AI Employee talks to:

DM policies control who can message the bot privately:

PolicyBehavior
pairing (default)Unknown senders must request access -- you approve with openclaw pairing approve
allowlistOnly numbers in your allowFrom list can trigger the bot
openAnyone can message and get a response
disabledAll DMs blocked

Right now yours is pairing -- only your own number is auto-authorized. If an unknown number messages you on WhatsApp, the bot auto-replies with a pairing code and your phone number, telling them how to request access. It does not silently ignore them. This is another reason to use a dedicated phone number (see the caution in the setup section above).

Group policies control behavior in group chats:

PolicyBehavior
allowlistOnly senders in groupAllowFrom can trigger the bot
openAny group member can trigger it
disabledIgnore all group messages

Even with open group policy, the bot requires a mention to respond -- it will not reply to every message in the group. Someone must either @mention the bot, reply to a bot message, or match a configured mention pattern. This prevents the bot from spamming every conversation.

However, the bot reads all messages silently. When you do mention it, the agent receives the recent conversation history as context -- so it knows what the group has been discussing, even though it stayed quiet.

Chat via WhatsApp Groups

A dedicated group is the cleanest way to use your AI Employee on WhatsApp -- each group gets its own isolated session with separate conversation history. See the Organizing with Groups section below for setup steps and use cases.

Let Your General Agent Handle Configuration

You do not need to memorize these policies. The full access policy documentation lives at docs.openclaw.ai/gateway/security. Ask Claude Code (your General Agent from Chapter 14) to read the docs and configure everything for you -- one prompt replaces reading an entire documentation page:

Read the OpenClaw access policy docs and configure my WhatsApp channel:
- Keep DMs restricted to just my number (pairing mode)
- Enable group messaging so anyone in the group can trigger the bot
- Add a mention pattern so typing "Jayy" triggers a response
  without needing to @mention

If the agent does not respond: run openclaw gateway stop && openclaw gateway start to restart the gateway, then try again. Also check ~/.openclaw/logs/gateway.log for errors.

The Control UI​

You also have a browser-based chat. Open it with:

openclaw dashboard

This launches the Control UI in your default browser with authentication handled automatically. Going to http://127.0.0.1:18789/ directly will fail with "too many bad/missing token attempts" because the URL requires an authentication token. Always use the command.

Three channels, one agent: TUI, your messaging app (WhatsApp, Telegram, or Discord), and the Control UI all reach the same AI Employee with the same memory. That is the channel adapter pattern from Lesson 1.

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.

WhatsApp Groups as Separate Sessions​

Every WhatsApp group your employee joins gets its own isolated session. The session key looks like agent:<agentId>:whatsapp:group:<groupId>. This means:

  • Each group has its own conversation history and context
  • Commands like /verbose on 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"ACP delegation, code reviews
"AI Employee - Learn"Research, book summaries, questions

Each group maintains its own memory context. When you ask a question in the Code group, your employee sees the coding conversation history -- not yesterday's scheduling discussion from the Work group.

To set up groups:

Step 1 -- Enable group messaging (one-time). The setup wizard does not configure this. 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 -- just open. 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. The confirmation step matters -- 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 WhatsApp 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

Step 2 -- Create a group. Create a WhatsApp or Telegram group (you can be the only member besides the bot).

Step 3 -- Mention the bot. Send a message that @mentions the bot. Even with groupPolicy open, the bot requires a mention to respond -- this prevents it from replying to every message in a busy group.

Step 4 -- The bot responds. This group now has its own isolated session. Every future message in this group stays in this group's context.

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 -- groups do not see it. Conversation history stays fully isolated per group.

Security Checkpoint​

Your AI Employee is running. Understand one critical security setting before moving forward.

Why the Gateway Binds to 127.0.0.1​

The gateway only accepts connections from your machine. The address 127.0.0.1 (localhost) means "this computer only." No other device on your network -- and no one on the internet -- can reach your gateway directly.

This is intentional. Your AI Employee can read files, browse the web, and execute actions on your behalf. Limiting access to localhost ensures only you interact with the admin interface.

If you change the bind address to 0.0.0.0 (all interfaces), your gateway becomes accessible to anyone on your network -- or the entire internet on a server without a firewall.

Bind AddressWho Can AccessUse Case
127.0.0.1 (default)Only your machineLocal development, personal use
0.0.0.0 without authAnyone on network/internetNever do this
0.0.0.0 with gateway tokenAnyone with the tokenRemote server with authentication

The rule: Never bind to 0.0.0.0 without setting a gateway authentication token first. Use an SSH tunnel or Tailscale for remote access.

Troubleshooting Quick Reference​

SymptomLikely CauseFix
command not found: openclawPATH not updatedClose and reopen terminal; run install script again if needed
Installer fails on prerequisitesNetwork or permissionsRun with sudo on Linux; ensure Homebrew works on macOS
Google OAuth window won't openBrowser or firewallCopy the URL from terminal and paste into browser manually
OAuth callback failsPort 8085 in useKill the process on port 8085, retry setup
Bot does not respond on messaging appGateway not running or channel misconfiguredCheck ~/.openclaw/logs/gateway.log
Gateway won't startPort 18789 in useRun lsof -i :18789, then kill the PID
Control UI rejects with token errorOpened 127.0.0.1:18789 directlyUse openclaw dashboard instead -- it includes the auth token
Control UI loads but chat failsLLM provider unreachableCheck internet; re-run setup to refresh OAuth tokens
Agent stops after closing terminalGateway service not runningRun openclaw gateway start to restart the background service

Managing the gateway: openclaw gateway status checks if it is running, openclaw gateway start starts it, and openclaw gateway stop stops it.

Getting logs: Run cat ~/.openclaw/logs/gateway.log | tail -50 to review recent errors.

The Universal Setup Pattern​

Every agent system you will ever encounter follows the same setup sequence:

  1. Install the runtime -- get the software on your machine
  2. Configure the intelligence -- connect an LLM provider
  3. Connect I/O channels -- give the agent ways to communicate
  4. Verify end-to-end -- send a test message and confirm the round trip
  5. Secure the boundary -- ensure only authorized users can access the agent

You just completed all five steps. The specifics change between systems, but this pattern is universal. When you encounter a new agent framework, you will already know the shape of the setup process.

Try With AI​

Now that your AI Employee is running, use it to deepen your understanding of what you just built.

Prompt 1 -- Trace the Message Flow:

Walk me through what happens technically when I send a message
to you on WhatsApp (or Telegram). Trace the message from my phone to the LLM
and back. What systems does it pass through? What could fail at
each step?

What you're learning: The end-to-end message architecture. Understanding this flow means you can diagnose problems at any point in the chain.

Prompt 2 -- Security Awareness:

What security risks exist when running a local AI agent that has
access to the internet and can execute actions on my behalf?
List 5 specific risks and how I should mitigate each one.

What you're learning: As agents gain more capabilities (file access, web browsing, code execution), the attack surface grows. Understanding risks now prevents problems later.

Prompt 3 -- Troubleshooting Practice:

My OpenClaw messaging channel is set up but not responding to messages.
Walk me through a systematic troubleshooting checklist. For each
step: what to check, the exact command, expected output, and what
to do if it fails.

What you're learning: Debugging agent systems systematically. Check the simplest things first, verify each layer independently.

Flashcards Study Aid​