High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Clawdbot is a modular AI agent platform designed to operate across multiple messaging channels while maintaining a centralized gateway for task execution and state management. The system follows a client-server model where a "Gateway" daemon manages specialized "Agents" that utilize "Skills" to interact with the environment.
The architecture emphasizes extensibility through a plugin-based system for messaging channels (e.g., Discord, Telegram, Slack) and a tiered context-loading mechanism for skills to ensure efficient use of model context windows.
Sources: CLAUDE.md, skills/skill-creator/SKILL.md:16-25
Core System Components
Clawdbot's functionality is partitioned into several key layers: the CLI/Entry point, the Gateway server, the Agent Runtime, and the Skill ecosystem.
1. Gateway and CLI
The Gateway acts as the central hub. It handles routing between messaging channels, manages background execution sessions, and serves as an API host for UI components like the Canvas. The CLI provides wiring for commands, configuration management, and daemon control.
| Component | Responsibility | Relevant Path |
|---|---|---|
| CLI | Wiring commands, progress bars, and terminal output. | src/cli, src/commands |
| Gateway | Daemon service, message routing, and API server. | src/gateway |
| Infra | Low-level system operations and provider usage tracking. | src/infra |
Sources: CLAUDE.md, src/commands/status.command.ts:40-100
2. Agent Runtime
Agents are the primary execution units. Each agent is defined by a system prompt, a workspace, and an identity (name, theme, emoji). The system supports sub-agent spawning for parallelizing complex tasks.
The diagram above illustrates the flow of a message from a user through the gateway to an agent and its potential sub-agents.
Sources: src/agents/system-prompt.ts:160-200, AGENTS.md
Skill Ecosystem and Resource Management
Skills are modular packages that extend agent capabilities. They utilize a Progressive Disclosure Design Principle to manage context efficiency, loading only necessary information at each stage of the interaction.
Anatomy of a Skill
A skill is a directory containing a required SKILL.md and optional resource folders:
- Scripts (
scripts/): Executable code for deterministic reliability. - References (
references/): Documentation loaded into context as needed (e.g., API schemas). - Assets (
assets/): Files used in output (templates, icons) but not loaded into the model's context.
Context Loading Tiers
- Metadata: Name and description (always in context).
- SKILL.md Body: Detailed instructions (loaded upon skill trigger).
- Bundled Resources: Specific files or script outputs (loaded only when requested).
Sources: skills/skill-creator/SKILL.md:57-110
Communication and Media Pipeline
Clawdbot supports various messaging channels and a visual "Canvas" for rich UI rendering.
The Canvas System
The Canvas allows agents to display HTML/JS content on connected nodes (Mac, iOS, Android). It utilizes a dedicated host server and a node bridge.
This diagram shows the relationship between the Agent, the Canvas Host, and the remote rendering nodes.
Sources: skills/canvas/SKILL.md:15-35
Messaging Channels
Clawdbot integrates with multiple platforms through core code and extensions. All built-in and extension channels must be considered for routing and allowlists.
- Core Channels: Telegram, Discord, Slack, Signal, iMessage, WhatsApp (Web).
- Extensions: MS Teams, Matrix, Zalo, Voice Calls.
Sources: CLAUDE.md, skills/discord/SKILL.md:10-25
System Prompt Architecture
The agent's behavior is governed by a dynamically constructed system prompt. This prompt is built from several mandatory and optional sections based on the PromptMode (full, minimal, or none).
Mandatory Sections (Full Mode)
- Tooling: Lists available tools (e.g.,
read,write,exec,web_search). - Skills: Instructions for scanning and reading
SKILL.mdfiles. - Workspace: Defines the working directory and file access policies.
- Runtime: Provides metadata about the current environment (OS, Node version, Model).
Reasoning and Thinking
Agents can utilize different "Thinking Levels" (e.g., low, high). When internal reasoning is enabled, it is wrapped in <think>...</think> tags and stripped before being shown to the user.
Sources: src/agents/system-prompt.ts:15-60, src/agents/system-prompt.ts:380-450
Security and Sandboxing
Clawdbot implements a security audit system and sandboxing for tool execution.
- Security Audit: Scans configuration and filesystem for critical findings.
- Sandboxing: Optionally runs tools inside Docker containers with restricted workspace access (
none,ro,rw) and network allowlists for browser control.
Sources: src/commands/status.command.ts:56-70, src/agents/system-prompt.ts:310-350
Conclusion
The high-level architecture of Clawdbot is built on a foundation of modularity and context efficiency. By separating the gateway logic from agent execution and providing a structured skill system, the platform allows for complex, cross-platform workflows while maintaining security through sandboxing and periodic audits.