Clawdbot is an open-source, local-first personal AI assistant designed to run on a user's own devices, providing a fast, always-on, single-user experience. It integrates with numerous messaging channels and operating systems, serving as a comprehensive control plane for AI interactions.

The core methodology revolves around a Gateway architecture, which acts as the central control plane. This Gateway is a WebSocket server, typically running at ws://127.0.0.1:18789, responsible for managing sessions, presence, configuration, cron jobs, webhooks, a Control UI, and a Canvas host. Interactions with the Gateway occur via a Command Line Interface (CLI) (clawdbot ...), a WebChat UI, a macOS application, and iOS/Android nodes.

At its heart, Clawdbot utilizes a Pi agent runtime operating in Remote Procedure Call (RPC) mode, featuring tool streaming and block streaming for efficient execution of AI-driven tasks. The system employs a sophisticated session model, differentiating between a "main" session for direct chats and isolated sessions for groups. It supports various activation modes, queue modes, and reply-back mechanisms. A media pipeline handles images, audio, and video, including transcription hooks, size caps, and temporary file lifecycle management.

Multi-channel support is a cornerstone feature, enabling communication across an extensive list of platforms: WhatsApp (via Baileys), Telegram (via grammY), Slack (via Bolt), Discord (via discord.js), Google Chat (via Chat API), Signal (via signal-cli), iMessage (macOS-only via imsg), BlueBubbles, Microsoft Teams, Matrix, Zalo, Zalo Personal, and a WebChat interface. Group routing, mention gating, reply tags, and per-channel chunking/routing are managed through channel-specific configurations.

Companion applications and nodes extend functionality:

• A macOS app provides menu bar control, Voice Wake, Push-to-Talk (PTT) overlay, WebChat, debug tools, and remote gateway control.
• iOS and Android nodes pair via a Bridge, exposing capabilities like Canvas, camera snap/clip, screen recording, location retrieval, and notifications.
• macOS nodes can expose system-level actions like system.run (executing local commands, optionally requiring screen recording permission) and system.notify. These device-local actions are invoked via the Gateway protocol using node.invoke.

First-class tools empower the AI assistant:

• Browser control: A dedicated clawd Chrome/Chromium instance for web interactions, including snapshots, actions, uploads, and profile management.
• Canvas: An agent-driven visual workspace utilizing A2UI for dynamic rendering and interaction.
• Nodes: Access to device-specific capabilities (camera, screen recording, location, notifications).
• Automation: Cron jobs, webhooks, and Gmail Pub/Sub triggers.
• Sessions tools (sessions_*): A set of RPC methods (sessions_list, sessions_history, sessions_send) allowing agents to discover, log, and communicate with other active sessions, facilitating cross-session coordination.

The skills platform allows for bundled, managed, and workspace-defined skills, with install gating and UI integration. ClawdHub provides a minimal skill registry for automatic skill discovery and pull-in.

Security is emphasized with default settings. Inbound Direct Messages (DMs) are treated as untrusted input. The default $dmPolicy="pairing"$ requires unknown senders to complete a pairing code ($clawdbot pairing approve <channel> <code>$) before their messages are processed, creating a local allowlist. Public inbound DMs require explicit opt-in ($dmPolicy="open"$ and "*" in allowFrom). For group/channel safety, the system supports Docker sandboxing (agents.defaults.sandbox.mode: "non-main") to run non-main sessions within isolated containers. This allows for granular tool allowlisting and denylisting (e.g., bash, process, read, write, edit, sessions_* are typically allowlisted, while browser, canvas, nodes, cron, discord, gateway might be denylisted in sandboxed environments).

Configuration is managed primarily via ~/.clawdbot/clawdbot.json, with environment variables overriding settings. The system is designed to work with various AI models, strongly recommending Anthropic Pro/Max (100/200) + Opus 4.5 for long-context strength and prompt injection resistance, while also supporting OpenAI models. It implements model failover and authentication profile rotation (OAuth vs. API keys).

Installation is recommended via npm install -g clawdbot@latest or pnpm add -g clawdbot@latest, followed by clawdbot onboard --install-daemon to set up the Gateway daemon (launchd/systemd user service). Development from source prefers pnpm. The runtime environment requires Node.js $\ge 22$.

Remote access to the Gateway dashboard is facilitated by auto-configuration of Tailscale Serve (tailnet-only HTTPS) or Funnel (public HTTPS), ensuring the Gateway can remain bound to loopback. Clients can connect over Tailscale or SSH tunnels.