Skip to main content

​
CLAWDBOT 🦞

“EXFOLIATE! EXFOLIATE!” — A space lobster, probably

CLAWDBOT

Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).
Send a message, get an agent response — from your pocket.

GitHub · Releases · Docs · Clawd setup

CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like Pi. It’s built for Clawd, a space lobster who needed a TARDIS.

​
Start here

If the Gateway is running on the same computer, that link opens the browser Control UI immediately. If it fails, start the Gateway first: clawdbot gateway.

​
Dashboard (browser Control UI)

The dashboard is the browser Control UI for chat, config, nodes, sessions, and more. Local default: http://127.0.0.1:18789/ Remote access: https://docs.clawd.bot/web and https://docs.clawd.bot/gateway/tailscale

​
How it works

WhatsApp / Telegram / Discord
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │  tcp://0.0.0.0:18790 (Bridge)
  │                           │  http://<gateway-host>:18793
  │                           │    /__clawdbot__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (clawdbot …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (Clawdbot.app)
              ├─ iOS node via Bridge + pairing
              └─ Android node via Bridge + pairing
Most operations flow through the Gateway (clawdbot gateway), a single long-running process that owns provider connections and the WebSocket control plane.

​
Network model

  • One Gateway per host: it is the only process allowed to own the WhatsApp Web session.
  • Loopback-first: Gateway WS defaults to ws://127.0.0.1:18789.
    • For Tailnet access, run clawdbot gateway --bind tailnet --token ... (token is required for non-loopback binds).
  • Bridge for nodes: optional LAN/tailnet-facing bridge on tcp://0.0.0.0:18790 for paired nodes (Bonjour-discoverable).
  • Canvas host: HTTP file server on canvasHost.port (default 18793), serving /__clawdbot__/canvas/ for node WebViews; see docs/configuration.md (canvasHost).
  • Remote use: SSH tunnel or tailnet/VPN; see docs/remote.md and docs/discovery.md.

​
Features (high level)

  • 📱 WhatsApp Integration — Uses Baileys for WhatsApp Web protocol
  • ✈️ Telegram Bot — DMs + groups via grammY
  • 🎮 Discord Bot — DMs + guild channels via discord.js
  • 💬 iMessage — Local imsg CLI integration (macOS)
  • 🤖 Agent bridge — Pi (RPC mode) with tool streaming
  • ⏱️ Streaming + chunking — Block streaming + Telegram draft streaming details (/concepts/streaming)
  • 🧠 Multi-agent routing — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
  • 🔐 Subscription auth — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
  • 💬 Sessions — Direct chats collapse into shared main (default); groups are isolated
  • 👥 Group Chat Support — Mention-based by default; owner can toggle /activation always|mention
  • 📎 Media Support — Send and receive images, audio, documents
  • 🎤 Voice notes — Optional transcription hook
  • 🖥️ WebChat + macOS app — Local UI + menu bar companion for ops and voice wake
  • 📱 iOS node — Pairs as a node and exposes a Canvas surface
  • 📱 Android node — Pairs as a node and exposes Canvas + Chat + Camera
Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.

​
Quick start

Runtime requirement: Node ≥ 22. 
# From source (recommended while the npm package is still settling)
pnpm install
pnpm build
pnpm link --global

# Pair WhatsApp Web (shows QR)
clawdbot login

# Run the Gateway (leave running)
clawdbot gateway --port 18789
Multi-instance quickstart (optional): 
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
clawdbot gateway --port 19001
Send a test message (requires a running Gateway): 
clawdbot send --to +15555550123 --message "Hello from CLAWDBOT"

​
Configuration (optional)

Config lives at ~/.clawdbot/clawdbot.json.
  • If you do nothing, CLAWDBOT uses the bundled Pi binary in RPC mode with per-sender sessions.
  • If you want to lock it down, start with whatsapp.allowFrom and (for groups) mention rules.
Example: 
{
  whatsapp: {
    allowFrom: ["+15555550123"],
    groups: { "*": { requireMention: true } }
  },
  routing: { groupChat: { mentionPatterns: ["@clawd"] } }
}

​
Docs

​
The name

CLAWDBOT = CLAW + TARDIS — because every space lobster needs a time-and-space machine.
“We’re all just playing with our own prompts.” — an AI, probably high on tokens

​
Credits

  • Peter Steinberger (@steipete) — Creator, lobster whisperer
  • Mario Zechner (@badlogicc) — Pi creator, security pen-tester
  • Clawd — The space lobster who demanded a better name

​
Core Contributors

​
License

MIT — Free as a lobster in the ocean 🦞
“We’re all just playing with our own prompts.” — An AI, probably high on tokens