Core concepts for understanding Clawdbot AI assistant architecture, sessions, multi-agent routing, and message handling.

Clawdbot Concepts Overview

Understanding Clawdbot's core concepts helps you configure and use your AI assistant effectively. This section covers the fundamental building blocks of Clawdbot.

Key Concepts

Gateway Architecture

The Gateway is the central daemon that:

Maintains all messaging provider connections
Exposes a typed WebSocket API
Manages agent runtime and sessions
Handles message routing

Learn more about Gateway Architecture

Sessions

Clawdbot treats one direct-chat session per agent as primary:

Direct chats collapse to agent:<agentId>:<mainKey>
Group/channel chats get their own keys
Session state is owned by the Gateway

Multi-Agent Routing

Run multiple isolated agents with separate:

Workspaces (files, persona rules)
State directories
Session stores
Auth profiles

Agent Runtime

The agent runtime handles:

Message processing
Tool execution
Context management
Response generation

Session Management

DM Scope Options

Scope	Description
`main` (default)	All DMs share the main session
`per-peer`	Isolate by sender id across channels
`per-channel-peer`	Isolate by channel + sender
`per-account-channel-peer`	Isolate by account + channel + sender

Session Keys

Source	Key Format
Direct chats	`agent:<agentId>:<mainKey>`
Group chats	`agent:<agentId>:<channel>:group:<id>`
Cron jobs	`cron:<job.id>`
Webhooks	`hook:<uuid>`

Session Lifecycle

Sessions are reused until they expire
Daily reset defaults to 4:00 AM local time
Optional idle reset via idleMinutes

Multi-Agent Setup

What is an Agent?

An agent is a fully scoped brain with:

Workspace: Files, AGENTS.md, SOUL.md, persona rules
State directory: Auth profiles, model registry
Session store: Chat history + routing state
Skills: Per-agent via workspace's skills/ folder

Single-Agent Mode (Default)

agentId defaults to main
Sessions keyed as agent:main:<mainKey>
Workspace at ~/.clawdbot/workspace

Adding Agents

# Add a new agent
clawdbot agents add work

# List agents with bindings
clawdbot agents list --bindings

Routing Rules

Messages are routed to agents via bindings:

{
  "bindings": [
    {
      "agentId": "alex",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "dm", "id": "+15551230001" }
      }
    }
  ]
}

Message Handling

Streaming and Chunking

Clawdbot supports streaming responses:

Partial message updates
Typing indicators
Chunked delivery for long responses

Retry Policy

Failed messages are retried with:

Exponential backoff
Configurable retry limits
Error handling

Where State Lives

Item	Location
Config	`~/.clawdbot/clawdbot.json`
Sessions	`~/.clawdbot/agents/<agentId>/sessions/`
Transcripts	`~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl`
Auth profiles	`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`

Next Steps

Clawdbot Gateway - Gateway configuration
Clawdbot Tools - Tool configuration
Clawdbot Channels - Channel setup

Clawdbot Concepts

On this page