Updated February 2026 · 20 min read

The Complete Guide to Setting Up Clawdbot in 2026

Last updated: February 2026

Clawdbot turns Claude (or other AI models) into a persistent assistant that lives in your Telegram, WhatsApp, or other messaging apps. It can read your emails, manage your calendar, browse the web, run code, and remember conversations across sessions.

This guide walks you through everything: installation, configuration, connecting channels, setting up multi-agent systems, and troubleshooting common issues.

Not sure what Clawdbot is? Start with What is Clawdbot? for the basics.

Time required: 30-60 minutes for basic setup, 2-4 hours for full multi-agent configuration.

What is Clawdbot?
Prerequisites
Installation
Initial Configuration
Connecting Your AI Model
Setting Up Channels
Creating Your First Agent
Multi-Agent Setup
Integrations
Memory and Persistence
Running as a Service
Troubleshooting
FAQ

What is Clawdbot?

Clawdbot is an open-source CLI tool that bridges AI models with messaging platforms and external services. Think of it as the infrastructure layer that turns a stateless AI into a persistent, capable assistant.

Key capabilities: - Multi-channel: Connect to Telegram, WhatsApp, Discord, Slack, Signal, and more - Tool use: Browse the web, read/write files, execute code, manage calendars, send emails - Memory: Persistent context across conversations using workspace files - Multi-agent: Run separate AI personalities for different purposes (work, family, projects) - Scheduling: Cron jobs for automated check-ins, reminders, and background tasks - Voice: Text-to-speech output via ElevenLabs or other providers

What Clawdbot is NOT: - It’s not an AI model — it connects TO models (Claude, GPT-4, etc.) - It’s not a chatbot builder — it’s infrastructure for AI-powered assistants - It’s not no-code — you’ll need basic terminal skills

Prerequisites

Before you start, you’ll need:

Required

Node.js 18+ (recommended: Node 22)
npm (comes with Node.js)
A terminal (macOS Terminal, Windows PowerShell, Linux shell)
An AI API key (Anthropic Claude recommended)

Check your Node version

node --version
# Should output v18.x.x or higher

If you need to install Node.js: - macOS: brew install node@22 - Ubuntu/Debian: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs - Windows: Download from nodejs.org

Installation

Step 1: Install Clawdbot globally

npm install -g clawdbot

Verify the installation:

clawdbot --version

Step 2: Create your workspace

Your workspace is where Clawdbot stores configuration, memory files, and agent data.

mkdir ~/clawd
cd ~/clawd

Step 3: Initialize configuration

clawdbot init

This creates the default configuration file at ~/.clawdbot/clawdbot.json.

Initial Configuration

The main configuration file lives at ~/.clawdbot/clawdbot.json. Here’s the basic structure:

{
  "agents": [
    {
      "id": "main",
      "name": "Main Assistant",
      "workspace": "~/clawd",
      "model": "anthropic/claude-sonnet-4-20250514",
      "channels": []
    }
  ],
  "gateway": {
    "port": 3000
  }
}

Key configuration options

Option	Description	Example
`agents[].id`	Unique identifier for the agent	`"main"`, `"work"`, `"family"`
`agents[].workspace`	Directory for agent files	`"~/clawd"`
`agents[].model`	AI model to use	`"anthropic/claude-opus-4-5"`
`agents[].channels`	Messaging channels to connect	See Channels
`gateway.port`	Port for the gateway server	`3000`

Connecting Your AI Model

Clawdbot supports multiple AI providers. We recommend Claude for the best tool use and reasoning.

Option A: Anthropic API (Pay-per-use)

Get an API key from console.anthropic.com
Add it to Clawdbot:

clawdbot configure --section models
# Follow the prompts to add your Anthropic API key

Or manually add to your config:

{
  "models": {
    "anthropic": {
      "apiKey": "sk-ant-api03-..."
    }
  }
}

Option B: Anthropic Max (Subscription)

If you have an Anthropic Max subscription, you can use OAuth:

clawdbot models auth setup-token --provider anthropic
# Follow the browser prompt to authenticate

Option C: OpenAI / Other Providers

Clawdbot also supports: - OpenAI (GPT-4, GPT-4-turbo) - Google (Gemini) - Local models via Ollama

clawdbot configure --section models
# Select your provider and enter credentials

Verify model connection

clawdbot models list

You should see your configured models listed.

Setting Up Channels

Channels connect Clawdbot to messaging platforms. Start with Telegram — it’s the easiest.

Telegram Setup

Create a Telegram bot:
- Open Telegram and message @BotFather
- Send /newbot
- Follow the prompts to name your bot
- Copy the API token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
Add the bot to your config:

{
  "agents": [
    {
      "id": "main",
      "channels": [
        {
          "type": "telegram",
          "token": "YOUR_BOT_TOKEN",
          "allowedUsers": [YOUR_TELEGRAM_USER_ID]
        }
      ]
    }
  ]
}

Find your Telegram user ID:
- Message @userinfobot on Telegram
- It will reply with your user ID
Start the gateway:

clawdbot gateway start

Test it:
- Open Telegram and message your bot
- You should get a response from your AI

WhatsApp Setup

WhatsApp requires linking via QR code:

clawdbot whatsapp link

Scan the QR code with WhatsApp on your phone (Settings → Linked Devices → Link a Device).

Other Channels

Clawdbot supports: - Discord: Requires bot token from Discord Developer Portal - Slack: Requires Slack app with bot token - Signal: Requires signal-cli setup - iMessage: macOS only, requires BlueBubbles

For a detailed Telegram walkthrough, see our complete Telegram setup guide. For other channels, check the Clawdbot documentation.

Creating Your First Agent

An agent is a configured AI personality with its own workspace, tools, and memory.

Workspace Structure

Create these files in your workspace (e.g., ~/clawd/):

~/clawd/
├── AGENTS.md      # Instructions for the AI (how to behave, what to do)
├── MEMORY.md      # Long-term memory (persists across sessions)
├── TOOLS.md       # Notes about available tools and how to use them
├── USER.md        # Information about you (the user)
└── memory/        # Daily memory files
    └── 2026-02-03.md

AGENTS.md Example

This file tells the AI how to behave:

# AGENTS.md

You are Felix, a personal AI assistant.

## Behavior
- Be helpful, concise, and proactive
- Check email and calendar when asked
- Remember important information by writing to memory files

## Tools Available
- Gmail (read/send emails)
- Google Calendar (view/create events)
- Web browsing
- File read/write

## Rules
- Don't send external emails without explicit approval
- When in doubt, ask

MEMORY.md Example

This is the AI’s long-term memory:

# MEMORY.md

## About the User
- Name: [Your name]
- Timezone: Europe/Lisbon
- Preferences: [Your preferences]

## Important Information
- [Add things the AI should remember]

Start your agent

clawdbot gateway start

Message your bot on Telegram. The AI will now read your workspace files and behave according to your instructions.

Multi-Agent Setup

Run multiple AI personalities for different purposes — one for work, one for family, one for a specific project.

Configuration

{
  "agents": [
    {
      "id": "main",
      "name": "Felix",
      "workspace": "~/clawd",
      "model": "anthropic/claude-opus-4-5",
      "channels": [
        {
          "type": "telegram",
          "token": "BOT_TOKEN_1",
          "allowedUsers": [YOUR_USER_ID]
        }
      ]
    },
    {
      "id": "work",
      "name": "Work Assistant",
      "workspace": "~/clawd-work",
      "model": "anthropic/claude-sonnet-4-20250514",
      "channels": [
        {
          "type": "telegram",
          "token": "BOT_TOKEN_2",
          "allowedUsers": [YOUR_USER_ID]
        }
      ]
    }
  ]
}

Key points:

Each agent needs its own workspace directory
Each agent needs its own bot token (create separate bots via BotFather)
Agents can use different models (Opus for important stuff, Sonnet for routine tasks)
Agents are isolated — they don’t share memory unless you explicitly connect them

Workspace per agent

~/clawd/           # Main assistant
~/clawd-work/      # Work assistant  
~/clawd-family/    # Family assistant

Each workspace has its own AGENTS.md, MEMORY.md, etc.

Integrations

Clawdbot can connect to external services via skills and tools.

Google Workspace (Gmail, Calendar, Drive)

Install gogcli:

brew install gog  # macOS
# or npm install -g @anthropic/gog

Authenticate:

gog auth login

The AI can now:
- Read and send emails
- View and create calendar events
- Access Google Drive files

Web Browsing

Built-in. The AI can: - Search the web (requires Brave API key) - Fetch and read web pages - Take screenshots - Interact with web pages (click, type, navigate)

Voice (Text-to-Speech)

Get an ElevenLabs API key from elevenlabs.io
Add to config:

{
  "tts": {
    "provider": "elevenlabs",
    "apiKey": "YOUR_ELEVENLABS_KEY",
    "voiceId": "YOUR_PREFERRED_VOICE"
  }
}

The AI can now send voice messages in Telegram/WhatsApp.

Custom Tools

You can add custom tools by creating skill files. See the Skills documentation.

Memory and Persistence

Clawdbot uses files for memory. This is intentional — files are durable, versionable, and human-readable.

How memory works

Session context: The AI remembers the current conversation
Workspace files: MEMORY.md, AGENTS.md, daily notes — the AI reads these each session
Memory search: The AI can search past conversations and notes

Best practices

Write important things down: Tell the AI to update MEMORY.md when learning something important
Use daily notes: Create memory/YYYY-MM-DD.md files for daily logs
Version control: Consider using git to track changes to memory files

Example daily note

# 2026-02-03

## Tasks completed
- Set up Clawdbot on new server
- Connected Telegram bot

## Notes
- User prefers morning briefings at 7am
- Important meeting with [Client] on Friday

Running as a Service

For 24/7 operation, run Clawdbot as a system service.

macOS (launchd)

Create the plist file:

nano ~/Library/LaunchAgents/com.clawdbot.gateway.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.clawdbot.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/node</string>
        <string>/opt/homebrew/bin/clawdbot</string>
        <string>gateway</string>
        <string>start</string>
        <string>--foreground</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/clawd</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.clawdbot.gateway.plist

Check status:

clawdbot gateway status

Linux (systemd)

Create the service file:

sudo nano /etc/systemd/system/clawdbot.service

[Unit]
Description=Clawdbot Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/clawd
ExecStart=/usr/bin/node /usr/bin/clawdbot gateway start --foreground
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable clawdbot
sudo systemctl start clawdbot

Troubleshooting

“Command not found: clawdbot”

Cause: npm global bin directory not in PATH.

Fix:

# Find where npm installs global packages
npm config get prefix
# Add that path + /bin to your PATH in ~/.zshrc or ~/.bashrc
export PATH="$(npm config get prefix)/bin:$PATH"

“Model not configured”

Cause: No API key set for the model.

Fix:

clawdbot configure --section models
# Add your API key

“Telegram bot not responding”

Causes: 1. Bot token incorrect 2. User ID not in allowedUsers 3. Gateway not running

Fix:

# Check gateway status
clawdbot gateway status

# Check logs
clawdbot gateway logs

# Verify your user ID is in allowedUsers in config

“Permission denied” errors

Cause: File permissions on workspace.

Fix:

chmod -R 755 ~/clawd

Gateway crashes on startup

Cause: Usually a config syntax error.

Fix:

# Validate your config
clawdbot config validate

# Check JSON syntax
cat ~/.clawdbot/clawdbot.json | python -m json.tool

AI not reading workspace files

Cause: Workspace path incorrect in config.

Fix: Ensure workspace in your agent config points to the correct directory, and that AGENTS.md exists in that directory.

FAQ

How much does Clawdbot cost?

Clawdbot itself is free and open source. You pay for: - AI API usage: ~$0.01-0.10 per conversation turn depending on model - Optional: TTS (ElevenLabs ~$5-22/month), premium channels

Can I use GPT-4 instead of Claude?

Yes. Clawdbot supports OpenAI models. However, Claude generally has better tool use and longer context windows.

Is my data private?

Your data stays on your machine. Conversations are sent to your AI provider (Anthropic, OpenAI, etc.) for processing. Clawdbot doesn’t collect any data.

Can I run Clawdbot on a Raspberry Pi?

Yes, but performance may be limited. A Mac mini or Linux server is recommended for production use.

How do I update Clawdbot?

npm update -g clawdbot
clawdbot gateway restart

Can multiple people use the same bot?

Yes. Add multiple user IDs to allowedUsers. Each user can have their own session context.

How do I back up my setup?

Back up these directories: - ~/.clawdbot/ (configuration) - Your workspace(s) (~/clawd/, etc.)

Consider using git for version control on your workspace.

Where can I get help?

Documentation: docs.clawd.bot
GitHub Issues: github.com/clawdbot/clawdbot
Discord Community: discord.com/invite/clawd

Next Steps

Now that you have Clawdbot running:

Customize your agent: Edit AGENTS.md to define your AI’s personality and capabilities
Add integrations: Connect Gmail, Calendar, and other tools
Set up cron jobs: Automate daily briefings and check-ins
Join the community: Share your setup and learn from others

Need Help Setting This Up?

Setting up AI infrastructure can be complex. If you’d rather have experts handle it:

Swarm — We build and manage AI assistants for businesses. Same setup, zero headache.

Full configuration and deployment
Custom integrations for your workflow
Ongoing support and optimization
Based in Lisbon, serving businesses across Europe

→ Book a free consultation

This guide is maintained by the Swarm team. Last updated February 2026.

Need Help Setting This Up?

Swarm builds and manages AI assistants for businesses. Same tech, zero headache.

Book a Free Consultation →

Last updated: February 2026. Information may change — verify with official sources.
This guide is for informational purposes only.

The Complete Guide to Setting Up Clawdbot in 2026

Table of Contents

What is Clawdbot?

Prerequisites

Required

Recommended

Check your Node version

Installation

Step 1: Install Clawdbot globally

Step 2: Create your workspace

Step 3: Initialize configuration

Initial Configuration

Key configuration options

Connecting Your AI Model

Option A: Anthropic API (Pay-per-use)

Option B: Anthropic Max (Subscription)

Option C: OpenAI / Other Providers

Verify model connection

Setting Up Channels

Telegram Setup

WhatsApp Setup

Other Channels

Creating Your First Agent

Workspace Structure

AGENTS.md Example

MEMORY.md Example

Start your agent

Multi-Agent Setup

Configuration

Key points:

Workspace per agent

Integrations

Google Workspace (Gmail, Calendar, Drive)

Web Browsing

Voice (Text-to-Speech)

Custom Tools

Memory and Persistence

How memory works

Best practices

Example daily note

Running as a Service

macOS (launchd)

Linux (systemd)

Troubleshooting

“Command not found: clawdbot”

“Model not configured”

“Telegram bot not responding”

“Permission denied” errors

Gateway crashes on startup

AI not reading workspace files

FAQ

How much does Clawdbot cost?

Can I use GPT-4 instead of Claude?

Is my data private?

Can I run Clawdbot on a Raspberry Pi?

How do I update Clawdbot?

Can multiple people use the same bot?

How do I back up my setup?

Where can I get help?

Next Steps

Need Help Setting This Up?

Need Help Setting This Up?