​

Clawdia 🦞

“MEOW! MEOW!” — A space cat, probably

​

Start here

• New install from zero: Getting Started
• Guided setup (recommended): Wizard (clawdia onboard)
• Open the dashboard (local Gateway): http://127.0.0.1:18789/ (or http://localhost:18789/)

​

Dashboard (browser Control UI)

​

How it works

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

​

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 clawdia 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 /__clawdia__/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

​

Quick start

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

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

# Pair WhatsApp Web (shows QR)
clawdia channels login

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

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

CLAWDIA_CONFIG_PATH=~/.clawdia/a.json \
CLAWDIA_STATE_DIR=~/.clawdia-a \
clawdia gateway --port 19001

clawdia message send --target +15555550123 --message "Hello from Clawdia"

​

Configuration (optional)

• If you do nothing, Clawdia 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.

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { groupChat: { mentionPatterns: ["@clawd"] } }
}

​

Docs

• Start here:
  • Docs hubs (all pages linked)
  • Help ← common fixes + troubleshooting
  • Configuration
  • Configuration examples
  • Slash commands
  • Multi-agent routing
  • Updating / rollback
  • Pairing (DM + nodes)
  • Nix mode
  • Clawdia assistant setup (Clawd)
  • Skills
  • Skills config
  • Workspace templates
  • RPC adapters
  • Gateway runbook
  • Nodes (iOS/Android)
  • Web surfaces (Control UI)
  • Discovery + transports
  • Remote access
• Providers and UX:
  • WebChat
  • Control UI (browser)
  • Telegram
  • Discord
  • Mattermost (plugin)
  • iMessage
  • Groups
  • WhatsApp group messages
  • Media: images
  • Media: audio
• Companion apps:
  • macOS app
  • iOS app
  • Android app
  • Windows (WSL2)
  • Linux app
• Ops and safety:
  • Sessions
  • Cron jobs
  • Webhooks
  • Gmail hooks (Pub/Sub)
  • Security
  • Troubleshooting

​

The name

​

Credits

• The Community — All the contributors who make Clawdia better every day

​

License