|
|
---
|
|
|
summary: "Top-level overview of Clawdbot, features, and purpose"
|
|
|
read_when:
|
|
|
- Introducing Clawdbot to newcomers
|
|
|
---
|
|
|
# Clawdbot 🦞
|
|
|
|
|
|
> *"EXFOLIATE! EXFOLIATE!"* — A space lobster, probably
|
|
|
|
|
|
<p align="center">
|
|
|
<img src="whatsapp-clawd.jpg" alt="Clawdbot" width="420" />
|
|
|
</p>
|
|
|
|
|
|
<p align="center">
|
|
|
<strong>Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).</strong><br />
|
|
|
Send a message, get an agent response — from your pocket.
|
|
|
</p>
|
|
|
|
|
|
<p align="center">
|
|
|
<a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
|
|
|
<a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
|
|
|
<a href="/">Docs</a> ·
|
|
|
<a href="/start/clawd">Clawdbot assistant setup</a>
|
|
|
</p>
|
|
|
|
|
|
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](https://github.com/badlogic/pi-mono).
|
|
|
Clawdbot also powers [Clawd](https://clawd.me), the space‑lobster assistant.
|
|
|
|
|
|
## Start here
|
|
|
|
|
|
- **New install from zero:** [Getting Started](/start/getting-started)
|
|
|
- **Guided setup (recommended):** [Wizard](/start/wizard) (`clawdbot onboard`)
|
|
|
- **Open the dashboard (local Gateway):** http://127.0.0.1:18789/ (or http://localhost:18789/)
|
|
|
|
|
|
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](/web) and [Tailscale](/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`.
|
|
|
- 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).
|
|
|
- **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 [Gateway configuration](/gateway/configuration) (`canvasHost`).
|
|
|
- **Remote use**: SSH tunnel or tailnet/VPN; see [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).
|
|
|
|
|
|
## 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](/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**.
|
|
|
|
|
|
```bash
|
|
|
# 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
|
|
|
```
|
|
|
|
|
|
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):
|
|
|
|
|
|
```bash
|
|
|
git clone https://github.com/clawdbot/clawdbot.git
|
|
|
cd clawdbot
|
|
|
pnpm install
|
|
|
pnpm ui:build # auto-installs UI deps on first run
|
|
|
pnpm build
|
|
|
pnpm clawdbot onboard --install-daemon
|
|
|
```
|
|
|
|
|
|
Multi-instance quickstart (optional):
|
|
|
|
|
|
```bash
|
|
|
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
|
|
|
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
|
|
|
clawdbot gateway --port 19001
|
|
|
```
|
|
|
|
|
|
Send a test message (requires a running Gateway):
|
|
|
|
|
|
```bash
|
|
|
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:
|
|
|
|
|
|
```json5
|
|
|
{
|
|
|
whatsapp: {
|
|
|
allowFrom: ["+15555550123"],
|
|
|
groups: { "*": { requireMention: true } }
|
|
|
},
|
|
|
routing: { groupChat: { mentionPatterns: ["@clawd"] } }
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## Docs
|
|
|
|
|
|
- Start here:
|
|
|
- [Docs hubs (all pages linked)](/start/hubs)
|
|
|
- [FAQ](/start/faq) ← *common questions answered*
|
|
|
- [Configuration](/gateway/configuration)
|
|
|
- [Configuration examples](/gateway/configuration-examples)
|
|
|
- [Slash commands](/tools/slash-commands)
|
|
|
- [Multi-agent routing](/concepts/multi-agent)
|
|
|
- [Updating / rollback](/install/updating)
|
|
|
- [Pairing (DM + nodes)](/start/pairing)
|
|
|
- [Nix mode](/install/nix)
|
|
|
- [Clawdbot assistant setup (Clawd)](/start/clawd)
|
|
|
- [Skills](/tools/skills)
|
|
|
- [Skills config](/tools/skills-config)
|
|
|
- [Workspace templates](/reference/templates/AGENTS)
|
|
|
- [RPC adapters](/reference/rpc)
|
|
|
- [Gateway runbook](/gateway)
|
|
|
- [Nodes (iOS/Android)](/nodes)
|
|
|
- [Web surfaces (Control UI)](/web)
|
|
|
- [Discovery + transports](/gateway/discovery)
|
|
|
- [Remote access](/gateway/remote)
|
|
|
- Providers and UX:
|
|
|
- [WebChat](/web/webchat)
|
|
|
- [Control UI (browser)](/web/control-ui)
|
|
|
- [Telegram](/providers/telegram)
|
|
|
- [Discord](/providers/discord)
|
|
|
- [iMessage](/providers/imessage)
|
|
|
- [Groups](/concepts/groups)
|
|
|
- [WhatsApp group messages](/concepts/group-messages)
|
|
|
- [Media: images](/nodes/images)
|
|
|
- [Media: audio](/nodes/audio)
|
|
|
- Companion apps:
|
|
|
- [macOS app](/platforms/macos)
|
|
|
- [iOS app](/platforms/ios)
|
|
|
- [Android app](/platforms/android)
|
|
|
- [Windows (WSL2)](/platforms/windows)
|
|
|
- [Linux app](/platforms/linux)
|
|
|
- Ops and safety:
|
|
|
- [Sessions](/concepts/session)
|
|
|
- [Cron jobs](/automation/cron-jobs)
|
|
|
- [Webhooks](/automation/webhook)
|
|
|
- [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
|
|
|
- [Security](/gateway/security)
|
|
|
- [Troubleshooting](/gateway/troubleshooting)
|
|
|
|
|
|
## 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](https://twitter.com/steipete)) — Creator, lobster whisperer
|
|
|
- **Mario Zechner** ([@badlogicc](https://twitter.com/badlogicgames)) — Pi creator, security pen-tester
|
|
|
- **Clawd** — The space lobster who demanded a better name
|
|
|
|
|
|
## Core Contributors
|
|
|
|
|
|
- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) — Blogwatcher skill
|
|
|
- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) — Location parsing (Telegram + WhatsApp)
|
|
|
|
|
|
## License
|
|
|
|
|
|
MIT — Free as a lobster in the ocean 🦞
|
|
|
|
|
|
---
|
|
|
|
|
|
*"We're all just playing with our own prompts."* — An AI, probably high on tokens
|