let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
Files
db222070143aa76b869bb305f97637dd34f5a37d
clawdbot/docs/index.md
Peter Steinberger db22207014 feat: add message tool and CLI
2026-01-09 06:44:20 +01:00

9.4 KiB
Raw Blame History

summary, read_when
summary read_when
Top-level overview of Clawdbot, features, and purpose
Introducing Clawdbot to newcomers

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 · Clawdbot assistant 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. Clawdbot also powers Clawd, the space‑lobster assistant.

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.

# Recommended: global install (npm/pnpm)
npm install -g clawdbot@latest
# or: pnpm add -g clawdbot@latest

# Onboard + install the daemon (launchd/systemd user service)
clawdbot onboard --install-daemon

# Pair WhatsApp Web (shows QR)
clawdbot providers login

# Gateway runs via daemon after onboarding; manual run is still possible:
clawdbot gateway --port 18789

From source (development):

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:install
pnpm ui:build
pnpm build
pnpm clawdbot onboard --install-daemon

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 message 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

Reference in New Issue View Git Blame Copy Permalink