2026-01-04 14:32:47 +00:00
# 🦞 CLAWDBOT — Personal AI Assistant
2025-11-25 04:44:10 +01:00
2025-11-25 14:29:21 +01:00
< p align = "center" >
2026-01-04 14:32:47 +00:00
< img src = "https://raw.githubusercontent.com/clawdbot/clawdbot/main/docs/whatsapp-clawd.jpg" alt = "CLAWDBOT" width = "400" >
2025-12-03 15:45:32 +00:00
< / p >
< p align = "center" >
< strong > EXFOLIATE! EXFOLIATE!< / strong >
2025-11-25 14:29:21 +01:00
< / p >
2025-11-25 14:42:12 +01:00
< p align = "center" >
2026-01-04 14:32:47 +00:00
< a href = "https://github.com/clawdbot/clawdbot/actions/workflows/ci.yml?branch=main" > < img src = "https://img.shields.io/github/actions/workflow/status/clawdbot/clawdbot/ci.yml?branch=main&style=for-the-badge" alt = "CI status" > < / a >
< a href = "https://github.com/clawdbot/clawdbot/releases" > < img src = "https://img.shields.io/github/v/release/clawdbot/clawdbot?include_prereleases&style=for-the-badge" alt = "GitHub release" > < / a >
2026-01-03 00:47:22 +00:00
< a href = "https://discord.gg/clawd" > < img src = "https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt = "Discord" > < / a >
2025-11-25 14:42:12 +01:00
< a href = "LICENSE" > < img src = "https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt = "MIT License" > < / a >
< / p >
2026-01-04 14:32:47 +00:00
**Clawdbot** is a *personal AI assistant* you run on your own devices.
2026-01-06 18:25:52 +00:00
It answers you on the providers you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
2025-12-19 18:41:17 +01:00
2026-01-03 22:19:41 +01:00
If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
2025-11-25 23:06:54 +01:00
2026-01-06 19:24:33 +01:00
[Website ](https://clawdbot.com ) · [Docs ](https://docs.clawd.bot ) · Updating: [https://docs.clawd.bot/updating ](https://docs.clawd.bot/updating ) · Showcase: [https://docs.clawd.bot/showcase ](https://docs.clawd.bot/showcase ) · FAQ: [https://docs.clawd.bot/faq ](https://docs.clawd.bot/faq ) · Wizard: [https://docs.clawd.bot/wizard ](https://docs.clawd.bot/wizard ) · Nix: [https://github.com/clawdbot/nix-clawdbot ](https://github.com/clawdbot/nix-clawdbot ) · Docker: [https://docs.clawd.bot/docker ](https://docs.clawd.bot/docker ) · Discord: [https://discord.gg/clawd ](https://discord.gg/clawd )
2026-01-01 21:09:24 +01:00
2026-01-04 14:32:47 +00:00
Preferred setup: run the onboarding wizard (`clawdbot onboard` ). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux** .
2026-01-05 22:23:14 +01:00
Works with npm, pnpm, or bun.
2026-01-01 20:19:00 +01:00
2026-01-05 21:02:02 +01:00
**Subscriptions (OAuth):**
- **Anthropic** (Claude Pro/Max)
- **OpenAI** (ChatGPT/Codex)
2026-01-06 18:41:00 +01:00
Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑ context strength and better prompt‑ injection resistance. See [Onboarding ](https://docs.clawd.bot/onboarding ).
2025-12-31 11:35:42 +01:00
2026-01-05 19:40:05 +01:00
## Recommended setup (from source)
2026-01-06 19:18:47 +01:00
Do **not** download prebuilt binaries. Run from source.
2026-01-05 19:40:05 +01:00
```bash
# Clone this repo
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
2026-01-06 09:08:25 +01:00
bun install
2026-01-06 13:58:48 -03:00
bun run ui:install
2026-01-06 09:08:25 +01:00
bun run ui:build
bun run clawdbot onboard
2026-01-05 19:40:05 +01:00
```
2026-01-06 19:18:47 +01:00
Note: `bun run build` is optional here (it produces `dist/` for running via Node / the packaged `clawdbot` binary). `bun run clawdbot ...` runs TypeScript directly.
2026-01-05 19:43:54 +01:00
## Quick start (from source)
2026-01-06 03:30:33 +01:00
Runtime: **Node ≥22** .
2026-01-06 18:41:00 +01:00
From source, **pnpm** is the default workflow. Bun is supported as an optional local workflow; see [Bun ](https://docs.clawd.bot/bun ).
2026-01-05 19:43:54 +01:00
```bash
2026-01-06 03:30:33 +01:00
# Install deps (no Bun lockfile)
bun install --no-save
# Build TypeScript
bun run build
# Build Control UI
bun install --cwd ui --no-save
bun run --cwd ui build
2026-01-05 19:43:54 +01:00
# Recommended: run the onboarding wizard
2026-01-06 03:30:33 +01:00
bun run clawdbot onboard
2026-01-05 19:43:54 +01:00
# Link WhatsApp (stores creds in ~/.clawdbot/credentials)
2026-01-06 03:30:33 +01:00
bun run clawdbot login
2026-01-05 19:43:54 +01:00
# Start the gateway
2026-01-06 03:30:33 +01:00
bun run clawdbot gateway --port 18789 --verbose
2026-01-05 19:43:54 +01:00
# Dev loop (auto-reload on TS changes)
2026-01-06 03:30:33 +01:00
bun run gateway:watch
2026-01-05 19:43:54 +01:00
# Send a message
2026-01-06 03:30:33 +01:00
bun run clawdbot send --to +1234567890 --message "Hello from Clawdbot"
2026-01-05 19:43:54 +01:00
# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord)
2026-01-06 03:30:33 +01:00
bun run clawdbot agent --message "Ship checklist" --thinking high
2026-01-05 19:43:54 +01:00
```
2026-01-06 19:24:33 +01:00
Upgrading? https://docs.clawd.bot/updating (and run `clawdbot doctor` ).
2026-01-05 20:10:56 +01:00
2026-01-06 03:30:33 +01:00
If you run from source, prefer `bun run clawdbot …` or `pnpm clawdbot …` (not global `clawdbot` ).
2026-01-05 19:43:54 +01:00
2026-01-06 18:07:11 +01:00
## Security defaults (DM access)
Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted input** .
2026-01-06 18:41:00 +01:00
Full security guide: https://docs.clawd.bot/security
2026-01-06 18:07:11 +01:00
Default behavior on Telegram/WhatsApp/Signal/iMessage/Discord/Slack:
- **DM pairing** (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"` ): unknown senders receive a short pairing code and the bot does not process their message.
- Approve with: `clawdbot pairing approve --provider <provider> <code>` (then the sender is added to a local allowlist store).
- Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the provider allowlist (`allowFrom` / `discord.dm.allowFrom` / `slack.dm.allowFrom` ).
Run `clawdbot doctor` to surface risky/misconfigured DM policies.
2026-01-04 16:36:40 +01:00
## Highlights
2026-01-06 18:41:00 +01:00
- **[Local-first Gateway ](https://docs.clawd.bot/gateway )** — single control plane for sessions, providers, tools, and events.
2026-01-06 18:25:52 +00:00
- **[Multi-provider inbox ](https://docs.clawd.bot/surface )** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android.
- **[Multi-agent routing ](docs/configuration.md )** — route inbound providers/accounts/peers to isolated agents (workspaces + per-agent sessions).
2026-01-06 18:41:00 +01:00
- **[Voice Wake ](https://docs.clawd.bot/voicewake ) + [Talk Mode ](https://docs.clawd.bot/talk )** — always-on speech for macOS/iOS/Android with ElevenLabs.
- **[Live Canvas ](https://docs.clawd.bot/mac/canvas )** — agent-driven visual workspace with [A2UI ](https://docs.clawd.bot/mac/canvas#canvas-a2ui ).
- **[First-class tools ](https://docs.clawd.bot/tools )** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
- **[Companion apps ](https://docs.clawd.bot/macos )** — macOS menu bar app + iOS/Android [nodes ](https://docs.clawd.bot/nodes ).
- **[Onboarding ](https://docs.clawd.bot/wizard ) + [skills ](https://docs.clawd.bot/skills )** — wizard-driven setup with bundled/managed/workspace skills.
2026-01-04 16:36:40 +01:00
## Everything we built so far
### Core platform
2026-01-06 18:41:00 +01:00
- [Gateway WS control plane ](https://docs.clawd.bot/gateway ) with sessions, presence, config, cron, webhooks, [Control UI ](https://docs.clawd.bot/web ), and [Canvas host ](https://docs.clawd.bot/mac/canvas#canvas-a2ui ).
- [CLI surface ](https://docs.clawd.bot/agent-send ): gateway, agent, send, [wizard ](https://docs.clawd.bot/wizard ), and [doctor ](https://docs.clawd.bot/doctor ).
- [Pi agent runtime ](https://docs.clawd.bot/agent ) in RPC mode with tool streaming and block streaming.
- [Session model ](https://docs.clawd.bot/session ): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups ](https://docs.clawd.bot/groups ).
- [Media pipeline ](https://docs.clawd.bot/images ): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio ](https://docs.clawd.bot/audio ).
2026-01-04 16:36:40 +01:00
2026-01-06 18:25:52 +00:00
### Providers
2026-01-06 18:41:00 +01:00
- [Providers ](https://docs.clawd.bot/surface ): [WhatsApp ](https://docs.clawd.bot/whatsapp ) (Baileys), [Telegram ](https://docs.clawd.bot/telegram ) (grammY), [Slack ](https://docs.clawd.bot/slack ) (Bolt), [Discord ](https://docs.clawd.bot/discord ) (discord.js), [Signal ](https://docs.clawd.bot/signal ) (signal-cli), [iMessage ](https://docs.clawd.bot/imessage ) (imsg), [WebChat ](https://docs.clawd.bot/webchat ).
2026-01-06 18:25:52 +00:00
- [Group routing ](https://docs.clawd.bot/group-messages ): mention gating, reply tags, per-provider chunking and routing. Provider rules: [Providers ](https://docs.clawd.bot/surface ).
2026-01-04 16:36:40 +01:00
### Apps + nodes
2026-01-06 18:41:00 +01:00
- [macOS app ](https://docs.clawd.bot/macos ): menu bar control plane, [Voice Wake ](https://docs.clawd.bot/voicewake )/PTT, [Talk Mode ](https://docs.clawd.bot/talk ) overlay, [WebChat ](https://docs.clawd.bot/webchat ), debug tools, [remote gateway ](https://docs.clawd.bot/remote ) control.
- [iOS node ](https://docs.clawd.bot/ios ): [Canvas ](https://docs.clawd.bot/mac/canvas ), [Voice Wake ](https://docs.clawd.bot/voicewake ), [Talk Mode ](https://docs.clawd.bot/talk ), camera, screen recording, Bonjour pairing.
- [Android node ](https://docs.clawd.bot/android ): [Canvas ](https://docs.clawd.bot/mac/canvas ), [Talk Mode ](https://docs.clawd.bot/talk ), camera, screen recording, optional SMS.
- [macOS node mode ](https://docs.clawd.bot/nodes ): system.run/notify + canvas/camera exposure.
2026-01-04 16:36:40 +01:00
### Tools + automation
2026-01-06 18:41:00 +01:00
- [Browser control ](https://docs.clawd.bot/browser ): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
- [Canvas ](https://docs.clawd.bot/mac/canvas ): [A2UI ](https://docs.clawd.bot/mac/canvas#canvas-a2ui ) push/reset, eval, snapshot.
- [Nodes ](https://docs.clawd.bot/nodes ): camera snap/clip, screen record, [location.get ](https://docs.clawd.bot/location-command ), notifications.
- [Cron + wakeups ](https://docs.clawd.bot/cron ); [webhooks ](https://docs.clawd.bot/webhook ); [Gmail Pub/Sub ](https://docs.clawd.bot/gmail-pubsub ).
- [Skills platform ](https://docs.clawd.bot/skills ): bundled, managed, and workspace skills with install gating + UI.
2026-01-04 16:36:40 +01:00
### Ops + packaging
2026-01-06 18:41:00 +01:00
- [Control UI ](https://docs.clawd.bot/web ) + [WebChat ](https://docs.clawd.bot/webchat ) served directly from the Gateway.
- [Tailscale Serve/Funnel ](https://docs.clawd.bot/tailscale ) or [SSH tunnels ](https://docs.clawd.bot/remote ) with token/password auth.
- [Nix mode ](https://docs.clawd.bot/nix ) for declarative config; [Docker ](https://docs.clawd.bot/docker )-based installs.
- [Doctor ](https://docs.clawd.bot/doctor ) migrations, [logging ](https://docs.clawd.bot/logging ).
2026-01-04 16:36:40 +01:00
## How it works (short)
2025-12-03 15:45:32 +00:00
```
2026-01-05 21:46:52 +01:00
WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat
2026-01-05 21:02:02 +01:00
│
▼
2025-12-19 18:41:17 +01:00
┌───────────────────────────────┐
│ Gateway │ ws://127.0.0.1:18789
2026-01-05 21:02:02 +01:00
│ (control plane) │ bridge: tcp://0.0.0.0:18790
2025-12-19 18:41:17 +01:00
└──────────────┬────────────────┘
│
├─ Pi agent (RPC)
2026-01-04 14:32:47 +00:00
├─ CLI (clawdbot …)
2026-01-05 21:02:02 +01:00
├─ WebChat UI
├─ macOS app
└─ iOS/Android nodes
2025-12-03 15:45:32 +00:00
```
2025-11-25 04:44:10 +01:00
2026-01-05 21:02:02 +01:00
## Key subsystems
2026-01-06 18:41:00 +01:00
- **[Gateway WebSocket network ](https://docs.clawd.bot/architecture )** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook ](https://docs.clawd.bot/gateway )).
- **[Tailscale exposure ](https://docs.clawd.bot/tailscale )** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote ](https://docs.clawd.bot/remote )).
- **[Browser control ](https://docs.clawd.bot/browser )** — clawd‑ managed Chrome/Chromium with CDP control.
- **[Canvas + A2UI ](https://docs.clawd.bot/mac/canvas )** — agent‑ driven visual workspace (A2UI host: [Canvas/A2UI ](https://docs.clawd.bot/mac/canvas#canvas-a2ui )).
- **[Voice Wake ](https://docs.clawd.bot/voicewake ) + [Talk Mode ](https://docs.clawd.bot/talk )** — always‑ on speech and continuous conversation.
- **[Nodes ](https://docs.clawd.bot/nodes )** — Canvas, camera snap/clip, screen record, `location.get` , notifications, plus macOS‑ only `system.run` /`system.notify` .
2026-01-05 21:02:02 +01:00
2026-01-05 22:15:26 +01:00
## Tailscale access (Gateway dashboard)
Clawdbot can auto-configure Tailscale **Serve** (tailnet-only) or **Funnel** (public) while the Gateway stays bound to loopback. Configure `gateway.tailscale.mode` :
- `off` : no Tailscale automation (default).
- `serve` : tailnet-only HTTPS via `tailscale serve` (uses Tailscale identity headers by default).
- `funnel` : public HTTPS via `tailscale funnel` (requires shared password auth).
Notes:
- `gateway.bind` must stay `loopback` when Serve/Funnel is enabled (Clawdbot enforces this).
- Serve can be forced to require a password by setting `gateway.auth.mode: "password"` or `gateway.auth.allowTailscale: false` .
- Funnel refuses to start unless `gateway.auth.mode: "password"` is set.
- Optional: `gateway.tailscale.resetOnExit` to undo Serve/Funnel on shutdown.
2026-01-06 18:41:00 +01:00
Details: [Tailscale guide ](https://docs.clawd.bot/tailscale ) · [Web surfaces ](https://docs.clawd.bot/web )
2026-01-05 22:15:26 +01:00
## Remote Gateway (Linux is great)
It’ s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels** , and you can still pair device nodes (macOS/iOS/Android) to execute device‑ local actions when needed.
- **Gateway host** runs the bash tool and provider connections by default.
- **Device nodes** run device‑ local actions (`system.run` , camera, screen recording, notifications) via `node.invoke` .
2026-01-05 22:32:02 +01:00
In short: bash runs where the Gateway lives; device actions run where the device lives.
2026-01-05 22:15:26 +01:00
2026-01-06 18:41:00 +01:00
Details: [Remote access ](https://docs.clawd.bot/remote ) · [Nodes ](https://docs.clawd.bot/nodes ) · [Security ](https://docs.clawd.bot/security )
2026-01-05 22:15:26 +01:00
## macOS permissions via the Gateway protocol
The macOS app can run in **node mode** and advertises its capabilities + permission map over the Gateway WebSocket (`node.list` / `node.describe` ). Clients can then execute local actions via `node.invoke` :
- `system.run` runs a local command and returns stdout/stderr/exit code; set `needsScreenRecording: true` to require screen-recording permission (otherwise you’ ll get `PERMISSION_MISSING` ).
- `system.notify` posts a user notification and fails if notifications are denied.
- `canvas.*` , `camera.*` , `screen.record` , and `location.get` are also routed via `node.invoke` and follow TCC permission status.
Elevated bash (host permissions) is separate from macOS TCC:
- Use `/elevated on|off` to toggle per‑ session elevated access when enabled + allowlisted.
- Gateway persists the per‑ session toggle via `sessions.patch` (WS method) alongside `thinkingLevel` , `verboseLevel` , `model` , `sendPolicy` , and `groupActivation` .
2026-01-06 18:41:00 +01:00
Details: [Nodes ](https://docs.clawd.bot/nodes ) · [macOS app ](https://docs.clawd.bot/macos ) · [Gateway protocol ](https://docs.clawd.bot/architecture )
2026-01-05 22:15:26 +01:00
2026-01-05 22:23:14 +01:00
## Agent to Agent (sessions_* tools)
2026-01-05 22:32:02 +01:00
- Use these to coordinate work across sessions without jumping between chat surfaces.
2026-01-05 22:23:14 +01:00
- `sessions_list` — discover active sessions (agents) and their metadata.
- `sessions_history` — fetch transcript logs for a session.
- `sessions_send` — message another session; optional reply‑ back ping‑ pong + announce step (`REPLY_SKIP` , `ANNOUNCE_SKIP` ).
2026-01-06 18:41:00 +01:00
Details: [Session tools ](https://docs.clawd.bot/session-tool )
2026-01-05 22:23:14 +01:00
2026-01-05 02:34:02 +01:00
## Skills registry (ClawdHub)
ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed.
2026-01-05 21:46:52 +01:00
https://ClawdHub.com
2026-01-05 02:34:02 +01:00
2025-12-22 20:36:34 +01:00
## Chat commands
2026-01-05 19:43:54 +01:00
Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only):
2025-12-22 20:36:34 +01:00
- `/status` — health + session info (group shows activation mode)
- `/new` or `/reset` — reset the session
2026-01-06 02:06:06 +01:00
- `/compact` — compact session context (summary)
2025-12-22 20:36:34 +01:00
- `/think <level>` — off|minimal|low|medium|high
- `/verbose on|off`
- `/restart` — restart the gateway (owner-only in groups)
- `/activation mention|always` — group activation toggle (groups only)
2026-01-05 20:10:56 +01:00
## macOS app (optional)
2025-12-13 23:50:23 +00:00
2026-01-05 20:10:56 +01:00
The Gateway alone delivers a great experience. All apps are optional and add extra features.
2025-12-06 05:24:27 +01:00
2026-01-05 21:02:02 +01:00
If you plan to build/run companion apps, initialize submodules first:
```bash
git submodule update --init --recursive
2026-01-05 22:24:31 +01:00
./scripts/restart-mac.sh
2026-01-05 21:02:02 +01:00
```
2026-01-05 20:10:56 +01:00
### macOS (Clawdbot.app) (optional)
2025-12-12 16:42:05 +00:00
2025-12-19 18:41:17 +01:00
- Menu bar control for the Gateway and health.
- Voice Wake + push-to-talk overlay.
- WebChat + debug tools.
- Remote gateway control over SSH.
2025-12-12 16:42:05 +00:00
2026-01-05 22:24:31 +01:00
Note: signed builds required for macOS permissions to stick across rebuilds (see `docs/mac/permissions.md` ).
2025-12-12 16:42:05 +00:00
2026-01-05 20:10:56 +01:00
### iOS node (optional)
2025-12-12 16:42:05 +00:00
2025-12-19 18:41:17 +01:00
- Pairs as a node via the Bridge.
- Voice trigger forwarding + Canvas surface.
2026-01-04 14:32:47 +00:00
- Controlled via `clawdbot nodes …` .
2025-12-06 05:24:27 +01:00
2026-01-06 18:41:00 +01:00
Runbook: [iOS connect ](https://docs.clawd.bot/ios ).
2025-12-13 23:50:23 +00:00
2026-01-05 20:10:56 +01:00
### Android node (optional)
2025-12-13 23:50:23 +00:00
2025-12-19 18:41:17 +01:00
- Pairs via the same Bridge + pairing flow as iOS.
- Exposes Canvas, Camera, and Screen capture commands.
2026-01-06 18:41:00 +01:00
- Runbook: [Android connect ](https://docs.clawd.bot/android ).
2025-12-13 23:50:23 +00:00
2025-12-19 18:41:17 +01:00
## Agent workspace + skills
2025-12-23 23:45:20 +00:00
- Workspace root: `~/clawd` (configurable via `agent.workspace` ).
2025-12-19 18:41:17 +01:00
- Injected prompt files: `AGENTS.md` , `SOUL.md` , `TOOLS.md` .
- Skills: `~/clawd/skills/<skill>/SKILL.md` .
2025-12-13 23:50:23 +00:00
2025-12-03 15:45:32 +00:00
## Configuration
2026-01-05 20:10:56 +01:00
Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
2026-01-05 01:03:01 +01:00
```json5
{
2026-01-05 20:10:56 +01:00
agent: {
model: "anthropic/claude-opus-4-5"
2026-01-05 01:03:01 +01:00
}
}
```
2026-01-06 18:41:00 +01:00
[Full configuration reference (all keys + examples). ](https://docs.clawd.bot/configuration )
2026-01-05 00:59:25 +01:00
2026-01-05 21:02:02 +01:00
## Security model (important)
2025-12-19 19:03:17 +01:00
2026-01-05 21:02:02 +01:00
- **Default:** tools run on the host for the **main** session, so the agent has full access when it’ s just you.
- **Group/channel safety:** set `agent.sandbox.mode: "non-main"` to run **non‑ main sessions** (groups/channels) inside per‑ session Docker sandboxes; bash then runs in Docker for those sessions.
2026-01-06 18:41:00 +01:00
- **Sandbox defaults:** allowlist `bash` , `process` , `read` , `write` , `edit` , `sessions_list` , `sessions_history` , `sessions_send` , `sessions_spawn` ; denylist `browser` , `canvas` , `nodes` , `cron` , `discord` , `gateway` .
2026-01-05 21:02:02 +01:00
2026-01-06 18:41:00 +01:00
Details: [Security guide ](https://docs.clawd.bot/security ) · [Docker + sandboxing ](https://docs.clawd.bot/docker ) · [Sandbox config ](https://docs.clawd.bot/configuration )
2026-01-05 21:02:02 +01:00
2026-01-06 18:41:00 +01:00
### [WhatsApp](https://docs.clawd.bot/whatsapp)
2026-01-05 20:34:26 +01:00
2026-01-04 14:32:47 +00:00
- Link the device: `pnpm clawdbot login` (stores creds in `~/.clawdbot/credentials` ).
2026-01-02 12:59:47 +01:00
- Allowlist who can talk to the assistant via `whatsapp.allowFrom` .
2026-01-06 04:47:41 +01:00
- If `whatsapp.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
2025-12-19 19:03:17 +01:00
2026-01-06 18:41:00 +01:00
### [Telegram](https://docs.clawd.bot/telegram)
2026-01-05 20:34:26 +01:00
2025-12-19 19:03:17 +01:00
- Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
2026-01-06 04:47:41 +01:00
- Optional: set `telegram.groups` (with `telegram.groups."*".requireMention` ); when set, it is a group allowlist (include `"*"` to allow all). Also `telegram.allowFrom` or `telegram.webhookUrl` as needed.
2025-12-19 19:03:17 +01:00
```json5
{
telegram: {
botToken: "123456:ABCDEF"
}
}
```
2026-01-06 18:41:00 +01:00
### [Slack](https://docs.clawd.bot/slack)
2026-01-05 20:34:26 +01:00
- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken` ).
2026-01-06 18:41:00 +01:00
### [Discord](https://docs.clawd.bot/discord)
2026-01-05 20:34:26 +01:00
2025-12-15 10:11:18 -06:00
- Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
2026-01-02 13:33:52 +01:00
- Optional: set `discord.slashCommand` , `discord.dm.allowFrom` , `discord.guilds` , or `discord.mediaMaxMb` as needed.
2025-12-15 10:11:18 -06:00
```json5
{
discord: {
token: "1234abcd"
}
}
```
2026-01-06 18:41:00 +01:00
### [Signal](https://docs.clawd.bot/signal)
2026-01-05 20:34:26 +01:00
- Requires `signal-cli` and a `signal` config section.
2026-01-06 18:41:00 +01:00
### [iMessage](https://docs.clawd.bot/imessage)
2026-01-05 20:34:26 +01:00
- macOS only; Messages must be signed in.
2026-01-06 04:47:41 +01:00
- If `imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
2026-01-05 20:34:26 +01:00
2026-01-06 18:41:00 +01:00
### [WebChat](https://docs.clawd.bot/webchat)
2026-01-05 20:34:26 +01:00
- Uses the Gateway WebSocket; no separate WebChat port/config.
2025-12-19 18:41:17 +01:00
Browser control (optional):
2025-12-13 15:15:09 +00:00
```json5
{
browser: {
enabled: true,
2025-12-13 15:29:39 +00:00
controlUrl: "http://127.0.0.1:18791",
2025-12-13 15:15:09 +00:00
color: "#FF4500 "
}
}
```
2025-12-19 18:41:17 +01:00
## Docs
2025-12-09 20:28:10 +00:00
2026-01-05 22:32:02 +01:00
Use these when you’ re past the onboarding flow and want the deeper reference.
2026-01-06 18:41:00 +01:00
- [Start with the docs index for navigation and “what’ s where.” ](https://docs.clawd.bot )
- [Read the architecture overview for the gateway + protocol model. ](https://docs.clawd.bot/architecture )
- [Use the full configuration reference when you need every key and example. ](https://docs.clawd.bot/configuration )
- [Run the Gateway by the book with the operational runbook. ](https://docs.clawd.bot/gateway )
- [Learn how the Control UI/Web surfaces work and how to expose them safely. ](https://docs.clawd.bot/web )
- [Understand remote access over SSH tunnels or tailnets. ](https://docs.clawd.bot/remote )
- [Follow the onboarding wizard flow for a guided setup. ](https://docs.clawd.bot/wizard )
- [Wire external triggers via the webhook surface. ](https://docs.clawd.bot/webhook )
- [Set up Gmail Pub/Sub triggers. ](https://docs.clawd.bot/gmail-pubsub )
- [Learn the macOS menu bar companion details. ](https://docs.clawd.bot/mac/menu-bar )
- [Platform guides: Windows ](https://docs.clawd.bot/windows ), [Linux ](https://docs.clawd.bot/linux ), [macOS ](https://docs.clawd.bot/macos ), [iOS ](https://docs.clawd.bot/ios ), [Android ](https://docs.clawd.bot/android )
- [Debug common failures with the troubleshooting guide. ](https://docs.clawd.bot/troubleshooting )
- [Review security guidance before exposing anything. ](https://docs.clawd.bot/security )
2025-12-24 22:59:09 +00:00
2026-01-05 22:30:47 +01:00
## Advanced docs (discovery + control)
2026-01-06 18:41:00 +01:00
- [Discovery + transports ](https://docs.clawd.bot/discovery )
- [Bonjour/mDNS ](https://docs.clawd.bot/bonjour )
- [Gateway pairing ](https://docs.clawd.bot/gateway/pairing )
- [Remote gateway README ](https://docs.clawd.bot/remote-gateway-readme )
- [Control UI ](https://docs.clawd.bot/control-ui )
- [Dashboard ](https://docs.clawd.bot/dashboard )
2026-01-05 22:30:47 +01:00
## Operations & troubleshooting
2026-01-06 18:41:00 +01:00
- [Health checks ](https://docs.clawd.bot/health )
- [Gateway lock ](https://docs.clawd.bot/gateway-lock )
- [Background process ](https://docs.clawd.bot/background-process )
- [Browser troubleshooting (Linux) ](https://docs.clawd.bot/browser-linux-troubleshooting )
- [Logging ](https://docs.clawd.bot/logging )
2026-01-05 22:30:47 +01:00
## Deep dives
2026-01-06 18:41:00 +01:00
- [Agent loop ](https://docs.clawd.bot/agent-loop )
- [Presence ](https://docs.clawd.bot/presence )
- [TypeBox schemas ](https://docs.clawd.bot/typebox )
- [RPC adapters ](https://docs.clawd.bot/rpc )
- [Queue ](https://docs.clawd.bot/queue )
2026-01-05 22:30:47 +01:00
## Workspace & skills
2026-01-06 18:41:00 +01:00
- [Skills config ](https://docs.clawd.bot/skills-config )
- [Default AGENTS ](https://docs.clawd.bot/AGENTS.default )
- [Templates: AGENTS ](https://docs.clawd.bot/templates/AGENTS )
- [Templates: BOOTSTRAP ](https://docs.clawd.bot/templates/BOOTSTRAP )
- [Templates: IDENTITY ](https://docs.clawd.bot/templates/IDENTITY )
- [Templates: SOUL ](https://docs.clawd.bot/templates/SOUL )
- [Templates: TOOLS ](https://docs.clawd.bot/templates/TOOLS )
- [Templates: USER ](https://docs.clawd.bot/templates/USER )
2026-01-05 22:30:47 +01:00
## Platform internals
2026-01-06 18:41:00 +01:00
- [macOS dev setup ](https://docs.clawd.bot/mac/dev-setup )
- [macOS menu bar ](https://docs.clawd.bot/mac/menu-bar )
- [macOS voice wake ](https://docs.clawd.bot/mac/voicewake )
- [iOS node ](https://docs.clawd.bot/ios )
- [Android node ](https://docs.clawd.bot/android )
- [Windows app ](https://docs.clawd.bot/windows )
- [Linux app ](https://docs.clawd.bot/linux )
2026-01-05 22:30:47 +01:00
2025-12-24 22:59:09 +00:00
## Email hooks (Gmail)
2026-01-06 18:41:00 +01:00
[Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here. ](https://docs.clawd.bot/gmail-pubsub )
2026-01-05 20:34:26 +01:00
Gateway auto-starts the watcher when `hooks.enabled=true` and `hooks.gmail.account` is set; `clawdbot hooks gmail run` is the manual daemon wrapper if you don’ t want auto-start.
2025-12-24 22:59:09 +00:00
```bash
2026-01-04 14:32:47 +00:00
clawdbot hooks gmail setup --account you@gmail .com
clawdbot hooks gmail run
2025-12-24 22:59:09 +00:00
```
2025-12-09 20:28:10 +00:00
2025-12-19 18:41:17 +01:00
## Clawd
2025-12-03 15:45:32 +00:00
2026-01-05 20:34:26 +01:00
Clawdbot was built for **Clawd** , a space lobster AI assistant. 🦞
by Peter Steinberger and the community.
2025-12-03 15:45:32 +00:00
2025-12-19 18:41:17 +01:00
- https://clawd.me
- https://soul.md
- https://steipete.me
2026-01-05 20:34:26 +01:00
## Community
2026-01-05 20:38:20 +01:00
See [CONTRIBUTING.md ](CONTRIBUTING.md ) for guidelines, maintainers, and how to submit PRs.
AI/vibe-coded PRs welcome! 🤖
2026-01-05 21:47:56 +01:00
Thanks to all clawtributors:
2026-01-05 20:34:26 +01:00
< p align = "left" >
< a href = "https://github.com/steipete" > < img src = "https://avatars.githubusercontent.com/u/58493?v=4&s=48" width = "48" height = "48" alt = "steipete" title = "steipete" / > < / a > < a href = "https://github.com/thewilloftheshadow" > < img src = "https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width = "48" height = "48" alt = "thewilloftheshadow" title = "thewilloftheshadow" / > < / a > < a href = "https://github.com/mcinteerj" > < img src = "https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width = "48" height = "48" alt = "mcinteerj" title = "mcinteerj" / > < / a > < a href = "https://github.com/joshp123" > < img src = "https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width = "48" height = "48" alt = "joshp123" title = "joshp123" / > < / a > < a href = "https://github.com/joaohlisboa" > < img src = "https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width = "48" height = "48" alt = "joaohlisboa" title = "joaohlisboa" / > < / a > < a href = "https://github.com/petter-b" > < img src = "https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width = "48" height = "48" alt = "petter-b" title = "petter-b" / > < / a > < a href = "https://github.com/mukhtharcm" > < img src = "https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width = "48" height = "48" alt = "mukhtharcm" title = "mukhtharcm" / > < / a > < a href = "https://github.com/dan-dr" > < img src = "https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width = "48" height = "48" alt = "dan-dr" title = "dan-dr" / > < / a > < a href = "https://github.com/Nachx639" > < img src = "https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width = "48" height = "48" alt = "Nachx639" title = "Nachx639" / > < / a > < a href = "https://github.com/jeffersonwarrior" > < img src = "https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width = "48" height = "48" alt = "jeffersonwarrior" title = "jeffersonwarrior" / > < / a >
< a href = "https://github.com/mbelinky" > < img src = "https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width = "48" height = "48" alt = "mbelinky" title = "mbelinky" / > < / a > < a href = "https://github.com/julianengel" > < img src = "https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width = "48" height = "48" alt = "julianengel" title = "julianengel" / > < / a > < a href = "https://github.com/CashWilliams" > < img src = "https://avatars.githubusercontent.com/u/613573?v=4&s=48" width = "48" height = "48" alt = "CashWilliams" title = "CashWilliams" / > < / a > < a href = "https://github.com/omniwired" > < img src = "https://avatars.githubusercontent.com/u/322761?v=4&s=48" width = "48" height = "48" alt = "omniwired" title = "omniwired" / > < / a > < a href = "https://github.com/jverdi" > < img src = "https://avatars.githubusercontent.com/u/345050?v=4&s=48" width = "48" height = "48" alt = "jverdi" title = "jverdi" / > < / a > < a href = "https://github.com/Syhids" > < img src = "https://avatars.githubusercontent.com/u/671202?v=4&s=48" width = "48" height = "48" alt = "Syhids" title = "Syhids" / > < / a > < a href = "https://github.com/meaningfool" > < img src = "https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width = "48" height = "48" alt = "meaningfool" title = "meaningfool" / > < / a > < a href = "https://github.com/rafaelreis-r" > < img src = "https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width = "48" height = "48" alt = "rafaelreis-r" title = "rafaelreis-r" / > < / a > < a href = "https://github.com/wstock" > < img src = "https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width = "48" height = "48" alt = "wstock" title = "wstock" / > < / a > < a href = "https://github.com/vsabavat" > < img src = "https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width = "48" height = "48" alt = "vsabavat" title = "vsabavat" / > < / a >
< a href = "https://github.com/scald" > < img src = "https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width = "48" height = "48" alt = "scald" title = "scald" / > < / a > < a href = "https://github.com/sreekaransrinath" > < img src = "https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width = "48" height = "48" alt = "sreekaransrinath" title = "sreekaransrinath" / > < / a > < a href = "https://github.com/ratulsarna" > < img src = "https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width = "48" height = "48" alt = "ratulsarna" title = "ratulsarna" / > < / a > < a href = "https://github.com/osolmaz" > < img src = "https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width = "48" height = "48" alt = "osolmaz" title = "osolmaz" / > < / a > < a href = "https://github.com/conhecendocontato" > < img src = "https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width = "48" height = "48" alt = "conhecendocontato" title = "conhecendocontato" / > < / a > < a href = "https://github.com/hrdwdmrbl" > < img src = "https://avatars.githubusercontent.com/u/554881?v=4&s=48" width = "48" height = "48" alt = "hrdwdmrbl" title = "hrdwdmrbl" / > < / a > < a href = "https://github.com/jayhickey" > < img src = "https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width = "48" height = "48" alt = "jayhickey" title = "jayhickey" / > < / a > < a href = "https://github.com/jamesgroat" > < img src = "https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width = "48" height = "48" alt = "jamesgroat" title = "jamesgroat" / > < / a > < a href = "https://github.com/gtsifrikas" > < img src = "https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width = "48" height = "48" alt = "gtsifrikas" title = "gtsifrikas" / > < / a > < a href = "https://github.com/djangonavarro220" > < img src = "https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width = "48" height = "48" alt = "djangonavarro220" title = "djangonavarro220" / > < / a >
< a href = "https://github.com/azade-c" > < img src = "https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width = "48" height = "48" alt = "azade-c" title = "azade-c" / > < / a > < a href = "https://github.com/andranik-sahakyan" > < img src = "https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width = "48" height = "48" alt = "andranik-sahakyan" title = "andranik-sahakyan" / > < / a >
2026-01-06 04:43:35 +00:00
< a href = "https://github.com/adamgall" > < img src = "https://avatars.githubusercontent.com/u/706929?v=4&s=48" width = "48" height = "48" alt = "adamgall" title = "adamgall" / > < / a > < a href = "https://github.com/jalehman" > < img src = "https://avatars.githubusercontent.com/u/550978?v=4&s=48" width = "48" height = "48" alt = "jalehman" title = "jalehman" / > < / a > < a href = "https://github.com/jarvis-medmatic" > < img src = "https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width = "48" height = "48" alt = "jarvis-medmatic" title = "jarvis-medmatic" / > < / a > < a href = "https://github.com/mneves75" > < img src = "https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width = "48" height = "48" alt = "mneves75" title = "mneves75" / > < / a > < a href = "https://github.com/regenrek" > < img src = "https://avatars.githubusercontent.com/u/5182020?v=4&s=48" width = "48" height = "48" alt = "regenrek" title = "regenrek" / > < / a > < a href = "https://github.com/tobiasbischoff" > < img src = "https://avatars.githubusercontent.com/u/711564?v=4&s=48" width = "48" height = "48" alt = "tobiasbischoff" title = "tobiasbischoff" / > < / a > < a href = "https://github.com/MSch" > < img src = "https://avatars.githubusercontent.com/u/7475?v=4&s=48" width = "48" height = "48" alt = "MSch" title = "MSch" / > < / a > < a href = "https://github.com/obviyus" > < img src = "https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width = "48" height = "48" alt = "obviyus" title = "obviyus" / > < / a > < a href = "https://github.com/dbhurley" > < img src = "https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width = "48" height = "48" alt = "dbhurley" title = "dbhurley" / > < / a >
2026-01-06 09:08:25 +01:00
< a href = "https://github.com/Asleep123" > < img src = "https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width = "48" height = "48" alt = "Asleep123" title = "Asleep123" / > < / a > < a href = "https://github.com/Iamadig" > < img src = "https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width = "48" height = "48" alt = "Iamadig" title = "Iamadig" / > < / a > < a href = "https://github.com/imfing" > < img src = "https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width = "48" height = "48" alt = "imfing" title = "imfing" / > < / a > < a href = "https://github.com/kitze" > < img src = "https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width = "48" height = "48" alt = "kitze" title = "kitze" / > < / a > < a href = "https://github.com/nachoiacovino" > < img src = "https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width = "48" height = "48" alt = "nachoiacovino" title = "nachoiacovino" / > < / a > < a href = "https://github.com/VACInc" > < img src = "https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width = "48" height = "48" alt = "VACInc" title = "VACInc" / > < / a > < a href = "https://github.com/cash-echo-bot" > < img src = "https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width = "48" height = "48" alt = "cash-echo-bot" title = "cash-echo-bot" / > < / a > < a href = "https://github.com/claude" > < img src = "https://avatars.githubusercontent.com/u/81847?v=4&s=48" width = "48" height = "48" alt = "claude" title = "claude" / > < / a > < a href = "https://github.com/kiranjd" > < img src = "https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width = "48" height = "48" alt = "kiranjd" title = "kiranjd" / > < / a > < a href = "https://github.com/pcty-nextgen-service-account" > < img src = "https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width = "48" height = "48" alt = "pcty-nextgen-service-account" title = "pcty-nextgen-service-account" / > < / a >
2026-01-05 20:34:26 +01:00
< / p >