How to Set Up Clawdbot: The Complete Guide (2026)

What Is Clawdbot and Why Should You Care?

Clawdbot is an open-source AI agent framework that turns Claude — Anthropic's large language model — into a persistent, always-on personal assistant. Unlike chatbot wrappers that simply relay messages to an API, Clawdbot gives Claude a workspace, tools, memory, and the ability to take real actions on your behalf. It can read and write files, execute shell commands, browse the web, control browsers, manage calendars, send messages across platforms, and much more.

Think of it this way: ChatGPT is a conversation. Clawdbot is an employee. It has a home directory, remembers context between sessions through a file-based memory system, runs on your infrastructure (so your data stays yours), and can be customized with skills — modular capability packages that extend what it can do. Need it to manage your CRM? There's a skill for that. Want it to monitor your servers? Write a skill, or ask it to write one for itself.

The framework is built on Node.js and communicates through a gateway daemon that handles message routing, session management, heartbeats (periodic check-ins where the bot proactively does useful work), and channel integrations. It's designed for people who want genuine AI automation — not just another chat interface, but an agent that lives on your server, understands your workflow, and grows more useful over time.

At ZINTOS, we run Clawdbot as our internal workhorse. It manages our CRM via Notion API, handles lead intake through webhooks, monitors projects, and serves as a knowledge base for our team. We've set up dozens of Clawdbot instances for clients through our AI Agent Setup Service, and this guide distills everything we've learned into a single, comprehensive walkthrough. Whether you're a developer wanting full control or a business owner evaluating whether to DIY or hire help, this guide gives you the complete picture.

Requirements and Prerequisites

Before you start, let's make sure you have everything you need. Clawdbot isn't demanding on hardware, but getting the prerequisites right saves headaches later.

Hardware and Infrastructure

For a VPS (recommended for production): You need at minimum 2 GB RAM, 1 vCPU, and 20 GB SSD storage. This comfortably handles a single Clawdbot instance with moderate usage. For heavier workloads — multiple channels, frequent heartbeats, browser automation — step up to 4 GB RAM and 2 vCPUs. Providers like Hetzner, DigitalOcean, and Contabo all work well. We typically recommend Hetzner for the price-to-performance ratio in Europe, and DigitalOcean for US-based deployments.

For local development: Any modern Mac, Linux box, or Windows machine with WSL2 will do. You'll want at least 4 GB of free RAM since you'll be running other things alongside it. Local setups are perfect for testing and development but aren't ideal for production since the bot goes offline when your computer sleeps.

Software Prerequisites

• Operating System: Ubuntu 22.04+, Debian 12+, macOS 13+, or Windows with WSL2
• Node.js: Version 20 or later (we recommend using nvm for version management)
• Git: For cloning the repository
• A text editor: nano works fine; VS Code with SSH remote is ideal for non-terminal people

API Keys and Accounts

You'll need an Anthropic API key — this is the engine that powers Clawdbot's intelligence. Sign up at console.anthropic.com and generate an API key. You'll also want accounts for whichever channels you plan to connect: a Telegram bot token (from BotFather), a Discord bot application, or a WhatsApp-linked device. We'll cover each of these in the channels section. Budget roughly $10–$50/month for API costs depending on usage intensity, plus $5–$20/month for VPS hosting.

One thing people overlook: a domain name is optional but useful. If you plan to use webhooks (for CRM integrations, form submissions, etc.), having a domain pointed at your VPS with SSL makes life much easier than dealing with raw IP addresses.

Step-by-Step Installation (VPS, Local, Docker)

Let's get Clawdbot installed. We'll cover three approaches: VPS (the recommended production path), local development, and Docker.

Option A: VPS Installation (Recommended)

Start by SSHing into your VPS. If you're on a fresh Ubuntu server, update packages and install Node.js first:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git

Verify your Node version with node --version — you need v20+. Now clone Clawdbot and install dependencies:

cd ~
git clone https://github.com/clawdbot/clawdbot.git clawd
cd clawd
npm install

The installation pulls in all dependencies. This typically takes 1–3 minutes depending on your server's connection speed. Once complete, you'll have the full Clawdbot framework in ~/clawd.

Option B: Local Installation

For local development on macOS or Linux, the process is nearly identical. Install Node.js via nvm if you haven't already:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22

Then clone and install as above. On macOS, you may need Xcode command-line tools (xcode-select --install) for native module compilation. Windows users should install WSL2 first (Ubuntu recommended), then follow the Linux instructions inside WSL.

Option C: Docker Installation

Docker is great for isolation and reproducibility. If you have Docker installed, you can get running quickly:

docker pull clawdbot/clawdbot:latest
docker run -d \
  --name clawdbot \
  -v ~/clawd-data:/root/clawd \
  -e ANTHROPIC_API_KEY=your-key-here \
  --restart unless-stopped \
  clawdbot/clawdbot:latest

The volume mount at ~/clawd-data persists your bot's memory, configuration, and skills across container restarts. This is crucial — without it, your bot loses its memory every time the container restarts. Docker is especially useful if you're running multiple Clawdbot instances (perhaps for different clients or projects) on the same server, as each container is fully isolated.

Regardless of which method you choose, you should now have a working Clawdbot installation. The next step is configuration — telling Clawdbot who it is, which model to use, and how to authenticate.

Core Configuration and API Keys

Clawdbot's behavior is controlled through configuration files and environment variables. Getting this right is the difference between a bot that feels like a generic chatbot and one that feels like your assistant.

Environment Variables

Create a .env file in your Clawdbot root directory (or set these as system environment variables):

ANTHROPIC_API_KEY=sk-ant-your-key-here
DEFAULT_MODEL=claude-sonnet-4-20250514
GATEWAY_PORT=3000

The DEFAULT_MODEL determines which Claude model handles conversations. Claude Sonnet 4 is the sweet spot for most users — fast, capable, and cost-effective. For tasks requiring deeper reasoning (complex coding, strategic analysis), you can switch to Claude Opus on a per-session basis. Haiku is available for high-volume, lower-complexity tasks where cost matters most.

Personality and Workspace Files

This is where Clawdbot gets interesting. The framework uses a set of markdown files to define the bot's identity and behavior:

• SOUL.md: Defines the bot's personality, name, communication style, and core directives. This is who the bot is.
• USER.md: Describes the human it serves — your preferences, timezone, communication style, what you care about.
• AGENTS.md: The operational manual. Rules about memory management, safety constraints, tool usage, and workspace conventions.
• TOOLS.md: Local notes about your specific setup — camera names, SSH hosts, API endpoints, device nicknames.
• MEMORY.md: Long-term curated memory. The bot reads this each session to maintain continuity.

Take time with SOUL.md and USER.md. A well-written soul file transforms the bot from a generic assistant into something that genuinely understands your context. Describe your work, your communication preferences, your sense of humor, what annoys you. The more context you provide, the less you'll need to repeat yourself in conversations.

Starting the Gateway

With configuration in place, start the Clawdbot gateway daemon:

clawdbot gateway start

Check status with clawdbot gateway status. If everything is configured correctly, you'll see the gateway running and ready to accept connections. The gateway manages all message routing, session lifecycle, heartbeat scheduling, and channel integrations. It's the central nervous system of your Clawdbot installation.

Connecting Channels: Telegram, Discord & WhatsApp

A Clawdbot without channels is like a brain without a mouth. Channels are how you interact with your bot — and how it interacts with the world. Let's connect the big three.

Telegram (Recommended First Channel)

Telegram is the gold standard for Clawdbot. It supports inline buttons, reactions, file sharing, voice messages, and has the most reliable API of any messaging platform. Here's how to connect it:

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to name your bot
3. Copy the API token BotFather gives you
4. Add the token to your Clawdbot configuration as the Telegram channel token
5. Restart the gateway: clawdbot gateway restart

Your bot should now be live on Telegram. Send it a message to verify. Telegram bots can work in private chats, group chats, and even channels. For personal assistant use, private chat is ideal. For team use, add the bot to a group and configure it to respond to mentions or all messages.

Discord

Discord integration is ideal for team environments or community management. Setup requires creating a Discord Application in the Developer Portal:

1. Go to discord.com/developers/applications and create a new application
2. Under the Bot section, create a bot and copy the token
3. Enable the Message Content intent (required for reading messages)
4. Generate an invite URL with appropriate permissions (Send Messages, Read Message History, Add Reactions)
5. Add the token to your Clawdbot Discord channel configuration

Discord supports slash commands, reactions, thread management, and voice channel integration. Configure which channels the bot monitors, whether it responds to all messages or only mentions, and its behavior in different server channels.

WhatsApp

WhatsApp integration uses the Baileys library for linked-device connectivity. It's more complex than Telegram or Discord because WhatsApp doesn't offer an official bot API for most users. The setup involves:

1. Configure the WhatsApp channel in Clawdbot
2. Start the gateway — it will generate a QR code
3. Scan the QR code with WhatsApp on your phone (like WhatsApp Web)
4. The session persists until you log out or the session expires

A word of caution: WhatsApp's terms of service don't officially support automated messaging through unofficial APIs. Use this for personal automation at your own discretion. Many of our clients use WhatsApp in read-only mode — the bot reads messages to stay informed but only responds through Telegram. This gives you WhatsApp context without the risk.

Tips, Tricks & Advanced Features

Once your basic setup is running, these tips will help you get dramatically more value from Clawdbot.

Heartbeats: Proactive Intelligence

Heartbeats are periodic check-ins where Clawdbot proactively does useful work without being asked. Configure a heartbeat interval (we recommend every 30–60 minutes during active hours), and the bot will check emails, review calendars, monitor systems, or whatever you define in HEARTBEAT.md. This transforms Clawdbot from a reactive chatbot into a proactive assistant that surfaces important information before you ask for it.

Skills: Extending Capabilities

Skills are modular capability packages — each defined by a SKILL.md file and supporting scripts. You can install community skills, write your own, or even ask Clawdbot to write skills for itself. Popular skills include web scraping, CRM integration, social media management, and code review automation. Keep skills lean: just the SKILL.md and essential scripts, no bloat.

Memory Management

Clawdbot's memory system uses daily log files (memory/YYYY-MM-DD.md) for raw context and MEMORY.md for curated long-term knowledge. Teach your bot to be diligent about saving context — especially after important conversations or decisions. The bot should periodically review daily files and distill important information into MEMORY.md, like a human reviewing their journal.

Subagents for Complex Tasks

For complex or long-running tasks, Clawdbot can spawn subagents — isolated sessions that handle specific work and report back. This is like delegating to an employee: "Write those four blog posts" or "Research competitors and summarize findings." Subagents work independently without blocking your main conversation thread.

Common Issues and Troubleshooting

Even with a clean setup, things can go wrong. Here are the issues we see most often and how to resolve them quickly.

Gateway Won't Start

If clawdbot gateway start fails silently or shows errors, check: Is another process already using the configured port? Run lsof -i :3000 (or your configured port) to check. Are your environment variables loaded? Run echo $ANTHROPIC_API_KEY to verify. Is Node.js the right version? node --version must show v20+. Check the gateway logs — they usually tell you exactly what's wrong.

Bot Not Responding on Telegram

The most common cause is an invalid or expired bot token. Verify the token with BotFather, make sure you copied it correctly (no trailing spaces), and restart the gateway. Also check that the bot isn't blocked by your Telegram privacy settings, and that you're messaging the correct bot username. If the gateway is running but messages aren't arriving, the issue is usually network-related — check your VPS firewall settings.

High API Costs

If your Anthropic bill is higher than expected, check your heartbeat frequency and model selection. Heartbeats every 15 minutes with Claude Opus will burn through credits fast. Switch routine tasks to Sonnet or Haiku, reserve Opus for complex reasoning, and increase heartbeat intervals to 30–60 minutes. Monitor your usage on the Anthropic dashboard and set billing alerts.

Memory and Context Issues

If Clawdbot seems to "forget" things between sessions, check that memory files are being written correctly. Look for memory/ directory in your workspace and verify recent daily files exist and contain content. If using Docker, make sure your volume mount is correct — data inside the container is ephemeral without a persistent volume.

Security Best Practices

Clawdbot runs with significant system access — it can execute commands, read files, and interact with external services. Security isn't optional; it's essential.

Server Hardening

Start with the basics: disable root SSH login (use a regular user with sudo), enable key-based authentication and disable password auth, configure a firewall (UFW on Ubuntu) to only expose necessary ports, and keep your system updated. These fundamentals prevent the vast majority of common attacks and take 15 minutes to configure.

API Key Security

Never commit API keys to Git repositories. Use environment variables or a .env file that's excluded via .gitignore. Rotate your Anthropic API key periodically. If you suspect a key has been compromised, regenerate it immediately from the Anthropic console. Consider using separate API keys for development and production environments.

Access Control

Configure Clawdbot to only accept messages from authorized users. On Telegram, this means whitelisting your user ID so random people can't command your bot. On Discord, use role-based permissions. Never expose your Clawdbot gateway port to the public internet without authentication — it should only be accessible locally or through a reverse proxy with proper auth.

Data Privacy

Everything Clawdbot processes flows through the Anthropic API. Understand Anthropic's data retention policies and ensure they align with your use case. For sensitive business data, consider whether certain information should be excluded from the bot's context. Clawdbot running on your own server means your memory files and workspace stay on your infrastructure — a significant privacy advantage over cloud-hosted solutions.

Security is an ongoing practice, not a one-time setup. Review your configuration quarterly, audit bot permissions, and stay updated on both Clawdbot and system security patches. If security configuration feels overwhelming, that's exactly the kind of thing a professional setup service handles for you.