---
summary: "Top-level overview of Clawdbot, features, and purpose"
read_when:
- Introducing Clawdbot to newcomers
---
# Clawdbot ๐ฆ
> *"EXFOLIATE! EXFOLIATE!"* โ A space lobster, probably
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](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
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 / iMessage (+ plugins)
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Gateway โ ws://127.0.0.1:18789 (loopback-only)
โ (single source) โ
โ โ http://: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](/gateway/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](/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 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](/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 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):
```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
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):
```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 --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:
```json5
{
channels: {
whatsapp: {
allowFrom: ["+15555550123"],
groups: { "*": { requireMention: true } }
}
},
messages: { groupChat: { mentionPatterns: ["@clawd"] } }
}
```
## Docs
- Start here:
- [Docs hubs (all pages linked)](/start/hubs)
- [Help](/help) โ *common fixes + troubleshooting*
- [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](/channels/telegram)
- [Discord](/channels/discord)
- [Mattermost (plugin)](/channels/mattermost)
- [iMessage](/channels/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