let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
Files
320b45c051a7bc20a02573ce0624533eda62fac6
clawdbot/docs/index.md

9.2 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).
Plugins add Mattermost and more. 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 / channels.discord.js), and iMessage (imsg CLI) to coding agents like Pi. Plugins add Mattermost (Bot API + WebSocket) and more. 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: Web surfaces and Tailscale

How it works

WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://<gateway-host>:18793
  │                           │    /__clawdbot__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (clawdbot …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (Clawdbot.app)
              ├─ iOS node via Gateway WS + pairing
              └─ Android node via Gateway WS + pairing

Most operations flow through the Gateway (clawdbot gateway), a single long-running process that owns channel connections and the WebSocket control plane.

Network model

  • One Gateway per host (recommended): it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see Multiple gateways.
  • Loopback-first: Gateway WS defaults to ws://127.0.0.1:18789.
    • The wizard now generates a gateway token by default (even for loopback).
    • For Tailnet access, run clawdbot gateway --bind tailnet --token ... (token is required for non-loopback binds).
  • Nodes: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed.
  • Canvas host: HTTP file server on canvasHost.port (default 18793), serving /__clawdbot__/canvas/ for node WebViews; see Gateway configuration (canvasHost).
  • Remote use: SSH tunnel or tailnet/VPN; see Remote access and Discovery.

Features (high level)

  • 📱 WhatsApp Integration — Uses Baileys for WhatsApp Web protocol
  • ✈️ Telegram Bot — DMs + groups via grammY
  • 🎮 Discord Bot — DMs + guild channels via channels.discord.js
  • 🧩 Mattermost Bot (plugin) — Bot token + WebSocket events
  • 💬 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 service (launchd/systemd user service)
clawdbot onboard --install-daemon

# Pair WhatsApp Web (shows QR)
clawdbot channels login

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

Switching between npm and git installs later is easy: install the other flavor and run clawdbot doctor to update the gateway service entrypoint.

From source (development):

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
clawdbot onboard --install-daemon

If you don’t have a global install yet, run the onboarding step via pnpm clawdbot ... from the repo.

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 --target +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 channels.whatsapp.allowFrom and (for groups) mention rules.

Example:

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { 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