This page provides a high-level introduction to OpenClaw's architecture, core concepts, and system organization. It explains what OpenClaw is, how its major components fit together, and where to find detailed documentation for each subsystem.
For installation and first-time setup, see Getting Started. For architectural details of the Gateway control plane, see Core Concepts. For platform-specific details, see Platform Architecture.
OpenClaw is a multi-platform AI gateway and personal assistant system that orchestrates conversations between messaging channels and AI agents package.json2-4 It connects to messaging apps like WhatsApp, Telegram, Slack, and Discord, providing a unified interface for AI interaction package.json45-68
The system is powered by Pi Agent Core pnpm-lock.yaml52-54 and is designed around a Personal Assistant Trust Model, assuming a single trusted operator boundary per gateway. It enables agents to perform real-world tasks through a rich tool ecosystem, including browser automation, filesystem access, and media understanding.
Sources: package.json2-4 package.json45-68 pnpm-lock.yaml52-54
The following diagram illustrates how the high-level system components map to specific code entities and directories within the repository.
Sources: AGENTS.md37-39 package.json16-17 pnpm-lock.yaml142-144
Gateway as Central Control Plane
The Gateway is the core engine that manages the lifecycle of the assistant. It handles:
runEmbeddedPiAgent pipeline and specialized tool providers pnpm-lock.yaml52-54Sources: package.json45-68 pnpm-lock.yaml169-171 pnpm-lock.yaml190-192 AGENTS.md65-66
The Gateway is the always-on control plane. It manages Agents, which are execution contexts configured with specific models and workspace defaults. The system maintains a models.json for model discovery and configuration AGENTS.md26-27
A Session represents a specific conversation thread. Channels are the transport layers (like Telegram or WhatsApp) that route messages to the Gateway package.json45-68
Tools are functional capabilities (like web search or browser automation) that the agent can invoke. Skills are modular extensions that teach agents how to use these tools for specific domains, managed via SKILL.md files .agents/skills/autoreview/SKILL.md1-4
For a deeper dive, see Core Concepts.
Sources: package.json45-68 .agents/skills/autoreview/SKILL.md1-4 AGENTS.md26-27
OpenClaw is built for high portability across desktop, server, and mobile environments.
| Platform | Role | Technology |
|---|---|---|
| Server / Desktop | Core Gateway | Node 22.19+ / TypeScript package.json102-103 |
| Web | Control UI | React/Vite Dashboard (via ui/ workspace) pnpm-workspace.yaml3 |
| Native Clients | iOS / Android / macOS | Swift / Kotlin / Jetpack Compose (via apps/) AGENTS.md37-39 |
| Container | Deployment | Docker Multi-arch manifests package.json27 |
Sources: AGENTS.md55 package.json101 pnpm-lock.yaml52-54 src/cli/run-main.ts145-151
For details on the build system and native integrations, see Platform Architecture.
OpenClaw operates on a Personal Assistant Trust Model. Because the assistant has access to sensitive local tools (like shell execution), it includes several safety boundaries:
openclaw doctor --fix for diagnostic repair and security hardening AGENTS.md58Sources: AGENTS.md51-58
The recommended way to set up OpenClaw is via the interactive onboarding wizard.
This command guides you through:
.openclaw directory and agent workspaces src/cli/run-main.ts5-6For a full walkthrough, see Getting Started.
Sources: package.json16-17 pnpm-lock.yaml64-66 package.json45-68 src/cli/run-main.ts5-6
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.