Skip to main content

​
Building a personal assistant with CLAWDBOT (Clawd-style)

CLAWDBOT is a WhatsApp + Telegram + Discord gateway for Pi agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.

​
⚠️ Safety first

You’re putting an agent in a position to:
  • run commands on your machine (depending on your Pi tool setup)
  • read/write files in your workspace
  • send messages back out via WhatsApp/Telegram/Discord
Start conservative:
  • Always set whatsapp.allowFrom (never run open-to-the-world on your personal Mac).
  • Use a dedicated WhatsApp number for the assistant.
  • Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting agent.heartbeat.every: "0m".

​
Prerequisites

  • Node 22+
  • CLAWDBOT available on PATH (recommended: global install)
  • A second phone number (SIM/eSIM/prepaid) for the assistant
npm install -g clawdbot@latest
# or: pnpm add -g clawdbot@latest
From source (development): 
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:install
pnpm ui:build
pnpm build
pnpm link --global
You want this: 
Your Phone (personal)          Second Phone (assistant)
┌─────────────────┐           ┌─────────────────┐
│  Your WhatsApp  │  ──────▶  │  Assistant WA   │
│  +1-555-YOU     │  message  │  +1-555-CLAWD   │
└─────────────────┘           └────────┬────────┘
                                       │ linked via QR
                                       ▼
                              ┌─────────────────┐
                              │  Your Mac       │
                              │  (clawdbot)      │
                              │    Pi agent     │
                              └─────────────────┘
If you link your personal WhatsApp to CLAWDBOT, every message to you becomes “agent input”. That’s rarely what you want.

​
5-minute quick start

  1. Pair WhatsApp Web (shows QR; scan with the assistant phone):
clawdbot providers login
  1. Start the Gateway (leave it running):
clawdbot gateway --port 18789
  1. Put a minimal config in ~/.clawdbot/clawdbot.json:
{
  whatsapp: {
    allowFrom: ["+15555550123"]
  }
}
Now message the assistant number from your allowlisted phone.

​
Give the agent a workspace (AGENTS)

Clawd reads operating instructions and “memory” from its workspace directory. By default, Clawdbot uses ~/clawd as the agent workspace, and will create it (plus starter AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md) automatically on setup/first agent run. BOOTSTRAP.md is only created when the workspace is brand new (it should not come back after you delete it). Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideally private) so your AGENTS.md + memory files are backed up. 
clawdbot setup
Full workspace layout + backup guide: docs/agent-workspace.md Optional: choose a different workspace with agent.workspace (supports ~). 
{
  agent: {
    workspace: "~/clawd"
  }
}
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely: 
{
  agent: {
    skipBootstrap: true
  }
}

​
The config that turns it into “an assistant”

CLAWDBOT defaults to a good assistant setup, but you’ll usually want to tune:
  • persona/instructions in SOUL.md
  • thinking defaults (if desired)
  • heartbeats (once you trust it)
Example: 
{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    workspace: "~/clawd",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Start with 0; enable later.
    heartbeat: { every: "0m" }
  },
  whatsapp: {
    allowFrom: ["+15555550123"],
    groups: {
      "*": { requireMention: true }
    }
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@clawd", "clawd"]
    }
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    idleMinutes: 10080
  }
}

​
Sessions and memory

  • Session files: ~/.clawdbot/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Session metadata (token usage, last route, etc): ~/.clawdbot/agents/<agentId>/sessions/sessions.json (legacy: ~/.clawdbot/sessions/sessions.json)
  • /new or /reset starts a fresh session for that chat (configurable via resetTriggers). If sent alone, the agent replies with a short hello to confirm the reset.
  • /compact [instructions] compacts the session context and reports the remaining context budget.

​
Heartbeats (proactive mode)

By default, CLAWDBOT runs a heartbeat every 30 minutes with the prompt: Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time. Set agent.heartbeat.every: "0m" to disable.
  • If the agent replies with HEARTBEAT_OK (optionally with short padding; see agent.heartbeat.ackMaxChars), CLAWDBOT suppresses outbound delivery for that heartbeat.
  • Heartbeats run full agent turns — shorter intervals burn more tokens.
{
  agent: {
    heartbeat: { every: "30m" }
  }
}

​
Media in and out

Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
  • {{MediaPath}} (local temp file path)
  • {{MediaUrl}} (pseudo-URL)
  • {{Transcript}} (if audio transcription is enabled)
Outbound attachments from the agent: include MEDIA:<path-or-url> on its own line (no spaces). Example: 
Here’s the screenshot.
MEDIA:/tmp/screenshot.png
CLAWDBOT extracts these and sends them as media alongside the text.

​
Operations checklist

clawdbot status          # local status (creds, sessions, queued events)
clawdbot status --deep   # also probes the running Gateway (WA connect + Telegram)
clawdbot health --json   # gateway health snapshot (WS)
Logs live under /tmp/clawdbot/ (default: clawdbot-YYYY-MM-DD.log).

​
Next steps