📑 Quick Navigation

What is Clawdbot?
Step 0: Check Prerequisites
Step 1: Install Clawdbot CLI
Step 2: Run Onboarding Wizard
Step 3: Pair Your Messaging Service
Step 4: Verify & Test
FAQ & Troubleshooting

What is Clawdbot?

Stop asking AI questions. Start telling it to do things.

Clawdbot is your personal AI assistant that actually takes action. Tell it to clear your inbox, draft emails, manage your calendar, check you in for flights — all from WhatsApp, Telegram, Discord, or any chat app you already use.

It runs 24/7 on your computer, remembers everything you tell it, and gets smarter the more you interact with it. Think of it like having a coworker who's always available, never gets tired, and learns how you work.

Why people are excited:

✅ It actually does things — sends emails, manages tasks, takes notes, runs searches. Not just a chatbot.
✅ Perfect memory — remembers context 24/7. Tells you things you told it weeks ago.
✅ Always available — runs on your computer, accessible from any messaging app
✅ Your data stays yours — runs locally, not in some cloud company's servers
✅ Keeps learning — the more you use it, the better it gets at knowing what you want
✅ Does work automatically — can run background tasks, reminders, and recurring jobs

✅ Estimated Time: 10-15 minutes

Most of this time is waiting for downloads and QR scanning. Actual setup is quick.

Step 0: Check Prerequisites

Before installing, make sure you have the right system setup.

System Requirements

Node.js 22 or higher

Check your Node version: node --version
Don't have Node? Download Node.js

Operating System

✅ macOS (Intel or Apple Silicon)
✅ Linux (Ubuntu, Debian, etc.)
✅ Windows (WSL2 required — not native Windows)

💡 Did you know? You can also set up Clawdbot on a VPS (Linux-based) for 24/7 uptime without needing to keep your personal computer running.

Internet Connection

Required for model API calls and downloading packages

API Key (Optional)

For AI models: Anthropic (Claude) or OpenAI
Get a free Anthropic API key at console.anthropic.com

⚠️ Windows Users: WSL2 Required

If you're on Windows, you MUST use WSL2 (Windows Subsystem for Linux 2). Native Windows is not supported and has compatibility issues.

Install WSL2 first, then follow the Linux instructions below.

Step 1: Install Clawdbot CLI

Choose the installation method for your operating system.

Install on macOS

The easiest way is using the installer script:

curl -fsSL https://clawd.bot/install.sh | bash

This will:

Download the Clawdbot CLI
Install it globally to your PATH
Make it accessible from any terminal

Verify installation:

clawdbot --version

You should see a version number like 2026.1.23

Install on Linux

Use the same installer as macOS:

curl -fsSL https://clawd.bot/install.sh | bash

For Debian/Ubuntu, you may need to update your shell PATH:

export PATH="$HOME/.local/bin:$PATH"

Verify installation:

clawdbot --version

Install via npm or pnpm

If you prefer npm or pnpm (or the scripts don't work):

npm install -g clawdbot@latest

Or with pnpm:

pnpm add -g clawdbot@latest

Verify:

clawdbot --version

Step 2: Run the Onboarding Wizard

The onboarding wizard sets up your entire Clawdbot configuration interactively. Run:

clawdbot onboard --install-daemon

What You'll Configure

🔑 AI Model & Authentication

Choose your AI provider. Clawdbot supports:

Anthropic (Claude) — Recommended. Three options:
- API key (fastest setup) — Get free key at console.anthropic.com
- Claude Code OAuth — Reuse existing Claude Code CLI credentials
- Setup token — Run claude setup-token and paste
OpenAI Codex — Requires paid Codex subscription + auth.json
MiniMax — Alternative AI provider
GLM — Chinese AI provider
Moonshot — AI provider option
AI Gateway — Custom gateway setup

The wizard securely stores your credentials and will prompt for your preference during setup.

🔌 Messaging Providers

Choose which messaging services to connect (you can add more later):

WhatsApp — Requires QR code scan
Telegram — Requires bot token
Discord — Requires bot token
iMessage — macOS only, requires native integration

⚙️ Gateway Settings

Decides where Clawdbot runs:

Local Gateway (recommended) — Runs on your machine on port 18789
Remote Gateway — For advanced users running on VPS/server

📦 Background Service

The wizard installs Clawdbot as a background service:

macOS — Uses launchd (auto-starts on login)
Linux — Uses systemd (auto-starts at boot)
Windows WSL2 — Uses systemd

Wizard Walkthrough

Press Enter to start the wizard and accept prompts
Paste your API key when prompted (or choose OAuth)
Select messaging providers — start with one (WhatsApp is easiest)
Choose local gateway — default option is recommended
Review settings — wizard shows your configuration before saving
Daemon install — wizard sets up background service

✅ After Onboarding

The wizard automatically starts the Gateway and loads Clawdbot. Your AI assistant is now running!

Step 3: Pair Your Messaging Service

Now connect your first messaging channel to Clawdbot.

Pair WhatsApp

Easiest option: QR code scan (no bot token needed).

Run the pairing command:
clawdbot channels login
Clawdbot will generate a QR code in your terminal
On your phone, open WhatsApp:
- Go to Settings → Linked Devices
- Tap "Link a Device"
- Point your camera at the QR code and scan
Wait for confirmation — Terminal will show "WhatsApp session established"

✅ WhatsApp is Now Connected!

You can now DM your Clawdbot from WhatsApp and chat with your AI assistant.

Pair Telegram

Requires a Telegram bot token (more setup than WhatsApp, but more reliable).

Create a Telegram bot token:
- Open Telegram and search for @BotFather
- Send /start
- Send /newbot
- Follow the prompts (give your bot a name like "MyClawd")
- Copy the bot token (long string like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
Configure Clawdbot for Telegram:
clawdbot configure

Or manually edit your config file and add your bot token.
Test the bot:
- Search for your bot in Telegram (the name you gave it)
- Send a message: "Hello!"
- Bot should reply with a pairing code
Approve the pairing:
clawdbot pairing approve telegram <code>

✅ Telegram is Now Connected!

Start chatting with your Clawdbot via Telegram messages.

Pair Discord

Requires a Discord bot token and server setup.

Create a Discord bot:
- Go to Discord Developer Portal
- Click "New Application"
- Go to "Bot" → "Add Bot"
- Copy the token under "TOKEN"
Get OAuth invite URL:
- Go to "OAuth2" → "URL Generator"
- Select scopes: bot
- Select permissions: Send Messages, Read Message History
- Copy the generated URL
Invite bot to your server:
- Open the OAuth URL in your browser
- Select your Discord server
- Authorize
Configure Clawdbot:
clawdbot configure

Add your Discord bot token.

✅ Discord is Now Connected!

Use Clawdbot in Discord channels and DMs.

Step 4: Verify & Test Installation

Make sure everything is working correctly.

Check Gateway Status

clawdbot gateway status

You should see something like:

            Listening: 127.0.0.1:18789

Gateway: ✅ running (pid 12345)

Auth: ✅ configured

Channels: ✅ WhatsApp connected

Health Check

clawdbot health

Send a Test Message

From your paired messaging service (WhatsApp/Telegram/Discord), send a simple message to your Clawdbot:

Example: "What is the capital of France?"
Expected response: "The capital of France is Paris."

✅ Congratulations!

Your Clawdbot installation is complete and working. You're now ready to use your AI assistant across all your messaging platforms!

FAQ & Troubleshooting

The onboarding wizard crashes or hangs ▼

Issue: Wizard exits unexpectedly or never completes.

Solution: Try running with verbose output to see what's happening:

clawdbot onboard --verbose

Common causes:

Node.js version too old (need 22+)
Missing dependencies (try npm install -g clawdbot@latest)
Corrupted config (delete ~/.clawdbot/config.json and retry)

WhatsApp QR code won't scan ▼

Issue: QR code appears in terminal but WhatsApp says "Invalid QR code"

Solutions:

Make sure you're in WhatsApp Settings → Linked Devices (not regular scan)
Try making your terminal window bigger so QR code is larger
If terminal rendering is bad, try taking a screenshot and scanning that instead
QR codes expire after ~30 seconds. If it times out, run clawdbot channels login again

Telegram bot doesn't respond to messages ▼

Issue: Bot token is set but bot doesn't reply

Solutions:

Check that the bot token is correct (paste it in config again)
Make sure you approved the pairing code: clawdbot pairing list telegram then clawdbot pairing approve telegram <code>
Restart the gateway: clawdbot gateway restart
Check auth is configured: clawdbot status should show your AI model

Getting "auth not configured" error ▼

Issue: Clawdbot says "no auth configured" or "API key not found"

Solution: You didn't set up your AI model API key during onboarding.

Run the wizard again:

clawdbot onboard

Or manually add your API key:

clawdbot configure --section auth

Gateway not starting / port 18789 in use ▼

Issue: Error says "port 18789 is already in use"

Solution: Another process is using that port.

Find what's using the port:
lsof -i :18789
Kill the process:
kill -9 <pid>
Or restart with a different port:
clawdbot gateway --port 18790

How do I see Clawdbot logs? ▼

To view real-time logs:

clawdbot gateway --verbose

For background service logs:

macOS (launchd):

log stream --predicate 'process == "clawdbot"' --level debug

Linux (systemd):

journalctl -u clawdbot-gateway -f

Can I use Clawdbot on multiple devices? ▼

Yes, but with caveats:

WhatsApp: You can link Clawdbot on one device only (like official WhatsApp Web). If you want it on another device, unlink from the first.
Telegram/Discord: The bot token works on any number of machines, but only one instance should run the gateway at a time.
Remote gateway: For advanced setups, you can run the gateway on a VPS and control it from multiple local machines.

What's Next?

Congratulations! Your Clawdbot is installed and running. Here are some next steps:

Customize Your AI Prompt: Teach Clawdbot about yourself by editing the system prompt in config
Add More Channels: Connect additional messaging services (Discord, Telegram, etc.)
Install Skills: Add web search, calendar integration, and other capabilities
Set Up a VPS: For 24/7 availability, run Clawdbot on a remote server
Explore the Dashboard: View status and manage your bot at http://127.0.0.1:18789/

📚 Learn More

For advanced topics and full documentation, visit docs.clawd.bot