Building a Personal Assistant

Overview

Clawdbot serves as a gateway connecting messaging platforms to AI agents, allowing you to interact with an AI assistant through your preferred messaging app.

Safety Considerations

Clawdbot can execute commands, access files, and send messages. Important security measures:

• Set channels.whatsapp.allowFrom to restrict access
• Use a dedicated phone number for the assistant
• Start with heartbeats disabled ("0m") until trusted
• Review permissions before granting shell access

Prerequisites

• Node.js 22+
• Clawdbot installed globally
• A second phone number for the assistant (recommended)

Recommended Architecture

Use two phones for the safest setup:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your Phone     │────▶│  Assistant      │────▶│  Your Computer  │
│  (Personal)     │     │  Phone Number   │     │  (Clawdbot)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Your personal device messages a second phone (the assistant) that's linked to Clawdbot running on your computer.

Quick Start

1. Pair WhatsApp Web

clawdbot channels login whatsapp

Scan the QR code with your assistant phone.

2. Start Gateway

clawdbot gateway --port 18789

3. Configure Allowlist

Edit ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890"],
      "dmPolicy": "allowlist"
    }
  }
}

Workspace & Memory

Default Workspace

Location: ~/.clawdbot/workspace

Contains instruction files:

Version Control

Treat your workspace as a git repository for backup:

cd ~/.clawdbot/workspace
git init
git add .
git commit -m "Initial workspace"

Sessions

Sessions are stored per-sender. Commands to manage sessions:

Heartbeats (Proactive Tasks)

Heartbeats are periodic checks where the agent reads HEARTBEAT.md for tasks.

Configuration

In ~/.clawdbot/clawdbot.json:

{
  "heartbeat": {
    "interval": "30m",
    "enabled": true
  }
}

Behavior

• Default: Every 30 minutes
• Agent reads HEARTBEAT.md for pending tasks
• Responds with HEARTBEAT_OK if nothing needs attention
• Set to "0m" to disable

Example HEARTBEAT.md

# Heartbeat Tasks

- Check for new emails and summarize important ones
- Review calendar for upcoming meetings
- Monitor stock prices for AAPL, GOOGL

Media Handling

Inbound Attachments

Clawdbot can receive and process:

• Images
• Documents
• Voice notes
• Videos

Outbound Media

Send media using the MEDIA:<path> syntax:

MEDIA:/path/to/image.png

Operations

Status Commands

# Check health
clawdbot health

# View status
clawdbot status

# Check logs
tail -f /tmp/clawdbot/gateway.log

Logging

Logs are stored in /tmp/clawdbot/:

Multi-Channel Setup

Configure multiple channels in clawdbot.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    },
    "discord": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  }
}

Next Steps

• Pairing - Configure access control
• Showcase - See what others have built
• Skills - Extend with plugins