> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenClaw Architecture
> Architecture of OpenClaw a self-hosted, single-user personal AI assistant with pluggable models, multi-channel integration, and policy-driven tool safety
OpenClaw is a production-grade, single-user, self-hosted personal AI (PAI) assistant you run on your own devices. It connects to popular messaging channels (WhatsApp, Telegram, Slack, Discord, Signal, iMessage) so you can interact through familiar interfaces while keeping your data and control local.
OpenClaw is implemented in TypeScript on Node.js and follows a Perceive–Reason–Act agent loop. It supports multiple model providers (Anthropic Claude, OpenAI GPT, Google Gemini, AWS Bedrock) and is designed to run on desktops and servers (macOS, Linux, Windows) as well as resource-constrained devices such as Raspberry Pi. Mobile access is available through iOS and Android clients.
OpenClaw is optimized for self-hosted, private deployments and supports pluggable model providers. You can run it on a local server, a small cloud VM, or an edge device like a Raspberry Pi for low-cost always-on access.
Quick facts
| Category | Details |
| - | - |
| Implementation | `TypeScript` on `Node.js` |
| Agent loop | Perceive–Reason–Act |
| Model providers | Anthropic Claude, OpenAI GPT, Google Gemini, AWS Bedrock |
| Deployment targets | `macOS`, `Linux`, `Windows`, Raspberry Pi, iOS & Android clients |
| Config format | Validated `JSON5` with typed defaults |
Agent configuration (example)
```typescript theme={null}
// src/agent/pi-agent.ts
interface PiAgentConfig {
name: string;
model: 'claude' | 'gpt' | 'gemini' | 'bedrock';
platforms: Platform[];
}
```
Message flow
When a user sends a message from any supported channel, OpenClaw processes it through a consistent, reliable pipeline:
1. Channel Monitor normalizes the incoming payload (unifying formats from WhatsApp, Telegram, Discord, etc.).
2. Routing Engine selects the correct agent or agent instance based on channel, session, or metadata.
3. Gateway (a WebSocket coordinator) handles authentication, concurrency, and connection lifecycle, then forwards the request to the agent system.
4. Agent Loop executes the Perceive–Reason–Act cycle: perceive input, reason (including tool use and memory retrieval), act (invoke tools or craft a response), and decide whether follow-up steps are needed.
5. Auto-reply Engine formats the agent’s response to the originating channel’s required payload structure.
6. Channel Sender dispatches the formatted response back to the user.
Core systems
OpenClaw is organized into eight primary systems that together provide resilience, extensibility, and safety:
| System | Responsibility | Examples / Notes |
| - | -: | - |
| Agent execution | Runs the agent loop, manages task lifecycles, retries, and error handling | Agent instance lifecycle, task queue |
| Gateway | WebSocket-based coordinator for concurrent requests and auth | Connection pooling, token validation |
| Channels | Adapters for external messaging platforms; normalize message formats | WhatsApp, Telegram, Slack, Discord, iMessage |
| Tools | Capabilities the agent can invoke (CLI, search, browser automation, memory) | `bash`, web search, headless browser, vector DB |
| Routing | Assigns incoming messages to the correct agent instance | Channel/session-based routing rules |
| Plugins | External integrations and feature extensions | CRM, calendar, cloud connectors |
| Config | Centralized validated `JSON5` with typed defaults and runtime validation | `config/*.json5` |
| Policy & safety | Enforces tool usage policies, approvals, auditing | RBAC, approval flows, audit logs |
Patterns and safety
OpenClaw applies established architectural and safety patterns commonly used in agent systems:
* Augmented LLMs with first-class tool integration and persistent memory (embeddings + vector stores).
* Policy-driven tool access: tools can be allowed, restricted, or require explicit human approval.
* Routing by channel and session to ensure conversation continuity per agent instance.
* Context window compression and model fallback to handle provider rate limits or outages.
* Human-in-the-loop for risky, destructive, or safety-sensitive operations.
* Robust error handling: credential rotation, rate-limit backoff, and retries.
Tools that perform destructive operations (e.g., file deletion or remote shell access) must be protected by strict policies and human approval workflows. Test policies in a safe environment before enabling them in production.
Example of a simple tool policy
This example shows how tool access can be defined and enforced by the tools subsystem:
```typescript theme={null}
// src/tools/policy.ts
const toolPolicy: ToolPolicy = {
allowed: ["bash", "browser"],
requireApproval: ["rm", "ssh"],
};
```
Policies like this can be extended with auditing, role-based approvals, per-channel constraints, and contextual rules.
Deployment and scaling considerations
* Run-time environments: Node.js LTS on macOS, Linux, and Windows.
* Edge deployment: lightweight agent builds and trimmed toolsets for Raspberry Pi.
* Scaling: multiple gateway instances and routing allow horizontal scaling; session affinity ensures conversation continuity.
* Configuration: store sensitive keys and secrets securely (e.g., environment variables, secret stores) and use validated `JSON5` for runtime configuration.
References
* Node.js — [https://nodejs.org/](https://nodejs.org/)
* OpenAI — [https://openai.com/](https://openai.com/)
* Anthropic Claude — [https://www.anthropic.com/](https://www.anthropic.com/)
* Google Gemini — [https://cloud.google.com/gemini](https://cloud.google.com/gemini)
* AWS Bedrock — [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/)
Summary
OpenClaw combines a compact Perceive–Reason–Act agent loop with a WebSocket gateway, pluggable channel adapters, tools and persistent memory, and a policy-driven safety layer. This architecture enables a practical, self-hosted personal assistant that runs across many devices while keeping control and extensibility in developer hands.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.