Core Concepts
Clawdbot's architecture is designed around several core concepts. Understanding these will help you better configure and use the system.
Architecture Overview
┌─────────────────────────────────────────────────────────────┐
│ Gateway │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │WhatsApp │ │Telegram │ │ Discord │ │ Slack │ ... │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ Router │ │
│ └─────┬─────┘ │
│ ┌──────────────────┼──────────────────┐ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │
│ │(default)│ │ (work) │ │(personal)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘Core Components
Gateway
The Gateway is Clawdbot's central component, responsible for:
- Managing all message channel connections
- Routing messages to the correct agent
- Maintaining session state
- Providing WebSocket API
Agent
An Agent is an independent AI persona, each with:
- Independent workspace
- Independent state directory (agentDir)
- Independent session storage
- Independent authentication configuration
Session
A Session is the context container for conversations:
- DM messages can share main session or use independent sessions
- Group messages use independent sessions by default
- Supports automatic reset policies
Channel
A Channel is a connection to a chat platform:
- Each platform uses specific protocol libraries
- Supports DMs and group chats
- Configurable access policies
Key Features
Streaming
Clawdbot supports real-time streaming responses:
- Messages sent in chunks, displayed in real-time
- Configurable chunk size
- Supports partial streaming mode
Message Chunking
Long messages are automatically chunked:
- Default 4000 characters per chunk
- Automatically adjusted based on platform limits
- Maintains message integrity
Secure Access Control
Multi-layer security mechanisms:
- Pairing mode: Unknown users need pairing code
- Allowlist mode: Only allow listed users
- Open mode: Allow all users
Sandbox Isolation
Agents can run in sandboxes:
- host: Run directly on host
- docker: Isolated in Docker container
Configuration Structure
{
// Workspace
workspace: "~/clawd",
// Channel configuration
channels: {
whatsapp: { /* ... */ },
telegram: { /* ... */ }
},
// Agent configuration
agents: {
default: { /* ... */ },
work: { /* ... */ }
},
// Binding rules
bindings: [
{ match: { channel: "telegram" }, agent: "work" }
]
}Next Steps
- Gateway Architecture - Deep dive into the gateway
- Multi-Agent Routing - Configure multiple agents
- Session Management - Manage conversation context