Overview

Relevant source files

• .agents/skills/crabbox/SKILL.md
• .agents/skills/openclaw-testing/agents/openai.yaml
• .crabbox.yaml
• .github/workflows/crabbox-hydrate.yml
• .gitignore
• AGENTS.md
• CHANGELOG.md
• README.md
• SECURITY.md
• docs/.generated/config-baseline.sha256
• docs/automation/index.md
• docs/channels/irc.md
• docs/channels/synology-chat.md
• docs/cli/commitments.md
• docs/cli/index.md
• docs/cli/mcp.md
• docs/cli/proxy.md
• docs/concepts/commitments.md
• docs/gateway/configuration-reference.md
• docs/plugins/bundles.md
• docs/plugins/google-meet.md
• docs/security/incident-response.md
• docs/security/network-proxy.md
• docs/tools/web-fetch.md
• extensions/AGENTS.md
• extensions/chutes/model-discovery-env.ts
• extensions/chutes/models.ts
• extensions/google-meet/index.test.ts
• extensions/google-meet/index.ts
• extensions/google-meet/openclaw.plugin.json
• extensions/google-meet/src/cli.test.ts
• extensions/google-meet/src/cli.ts
• extensions/google-meet/src/config.ts
• extensions/google-meet/src/create.ts
• extensions/google-meet/src/node-host.ts
• extensions/google-meet/src/realtime-node.ts
• extensions/google-meet/src/realtime.ts
• extensions/google-meet/src/runtime.ts
• extensions/google-meet/src/transports/chrome.ts
• extensions/google-meet/src/transports/types.ts
• extensions/google/cli-backend.ts
• extensions/huggingface/model-discovery-env.ts
• extensions/huggingface/models.ts
• extensions/memory-lancedb/package.json
• qa/scenarios/memory/commitments-heartbeat-target-none.md
• scripts/clawtributors-map.json
• scripts/e2e/commitments-safety-docker.sh
• scripts/update-clawtributors.ts
• scripts/update-clawtributors.types.ts
• src/agents/AGENTS.md
• src/agents/pi-embedded-runner/run/AGENTS.md
• src/agents/tools/AGENTS.md
• src/agents/tools/web-fetch.ssrf.test.ts
• src/agents/tools/web-fetch.ts
• src/agents/tools/web-tools.fetch.test.ts
• src/channels/AGENTS.md
• src/channels/plugins/configured-binding-consumers.ts
• src/cli/proxy-cli.runtime.test.ts
• src/cli/proxy-cli.runtime.ts
• src/cli/proxy-cli.test.ts
• src/cli/proxy-cli.ts
• src/config/config-misc.test.ts
• src/config/config.schema-regressions.test.ts
• src/config/schema.base.generated.ts
• src/config/schema.help.quality.test.ts
• src/config/schema.help.ts
• src/config/schema.labels.ts
• src/config/schema.test.ts
• src/config/types.agent-defaults.ts
• src/config/types.agents.ts
• src/config/types.gateway.ts
• src/config/types.tools.ts
• src/config/zod-schema.agent-defaults.test.ts
• src/config/zod-schema.agent-defaults.ts
• src/config/zod-schema.agent-runtime.ts
• src/config/zod-schema.ts
• src/gateway/AGENTS.md
• src/infra/net/proxy/proxy-validation.test.ts
• src/infra/net/proxy/proxy-validation.ts
• src/infra/outbound/AGENTS.md
• src/infra/outbound/channel-target-prefix.ts
• src/plugins/agent-tool-result-middleware-loader.ts
• src/plugins/contracts/extension-runtime-dependencies.contract.test.ts
• src/plugins/contracts/package-manifest.contract.test.ts
• src/plugins/plugin-registry-snapshot.test.ts
• src/plugins/plugin-registry-snapshot.ts

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.

What is OpenClaw

OpenClaw is a multi-platform AI gateway and personal assistant system that orchestrates conversations between messaging channels and AI agents AGENTS.md21 It connects to messaging platforms like WhatsApp, Telegram, Slack, and Discord, providing a unified interface for AI interaction CHANGELOG.md13

The system 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 via the google_meet tool, filesystem access, and specialized MCP (Model Context Protocol) servers docs/plugins/google-meet.md113-122 docs/gateway/configuration-reference.md84-88

Sources: AGENTS.md21 CHANGELOG.md13 docs/gateway/configuration-reference.md84-88 docs/plugins/google-meet.md113-122

Core Architecture

The following diagram illustrates how the high-level system components map to specific code entities and directories within the repository.

System Mapping: Natural Language to Code Entities

Gateway as Central Control Plane

The Gateway is the core engine that manages the lifecycle of the assistant. It handles:

1. Multi-Channel Integration: Managing plugins for platforms like Discord, Telegram, and Google Meet CHANGELOG.md13 extensions/google-meet/index.ts8
2. Configuration: Validating openclaw.json against the GENERATED_BASE_CONFIG_SCHEMA src/config/schema.base.generated.ts5-6
3. Agent Execution: Powering the assistant via the runEmbeddedPiAgent pipeline and specialized toolsets CHANGELOG.md15
4. Diagnostics: Implementing health probes and diagnostic event emission via OpenTelemetry (diagnostics.otel) src/config/schema.base.generated.ts154-162

Sources: src/config/schema.base.generated.ts1-10 CHANGELOG.md13-15 docs/gateway/configuration-reference.md9-18 AGENTS.md21

Core Concepts

Gateway & Agents

The Gateway is the always-on control plane. It manages Agents, which are execution contexts configured with specific models and workspace defaults docs/gateway/configuration-reference.md41-44 The system supports multi-agent routing where specific channels can be bound to different identities docs/gateway/configuration-reference.md46-47

Sessions & Channels

A Session represents a specific conversation thread, with automated lifecycle management and compaction to handle context limits docs/gateway/configuration-reference.md48 Channels are the transport layers (like Slack, Discord, or Google Meet) that route messages to the Gateway docs/gateway/configuration-reference.md34-39

Skills & Tools

Tools are functional capabilities (like google_meet or mcp) that the agent can invoke extensions/google-meet/index.ts113 Skills are modular extensions that teach agents how to use these tools, managed via SKILL.md files and the skills configuration block docs/gateway/configuration-reference.md126-130

For a deeper dive, see Core Concepts.

Sources: docs/gateway/configuration-reference.md34-130 CHANGELOG.md13-15 extensions/google-meet/index.ts113

Multi-Platform Architecture

OpenClaw is built for high portability across desktop, server, and mobile environments.

Platform	Role	Technology
Server / Desktop	Core Gateway	Node.js 22+ / TypeScript AGENTS.md46
Web	Control UI	Browser-based Dashboard src/config/schema.help.ts46
iOS / macOS	Native Client	Swift-based Apps (Talk mode support) src/config/schema.help.ts51-52
Android	Native Client	Jetpack Compose src/config/schema.help.ts52
Container	Deployment	Docker Multi-arch CHANGELOG.md43

Data Flow: Message to Tool Execution

For details on the build system and native integrations, see Platform Architecture.

Sources: AGENTS.md46 src/config/schema.help.ts51-52 extensions/google-meet/src/transports/chrome.ts18

Security & Trust

OpenClaw operates on a Personal Assistant Trust Model. Because the assistant has access to sensitive local tools (like shell execution or browser control), it defaults to a "fail-closed" posture:

• Authorization: Access is controlled via DM policies and explicit allow/deny lists for plugins docs/gateway/configuration-reference.md168-169
• Sensitive Data: The system includes built-in redaction (logging.redactSensitive) for logs and transcripts src/config/schema.help.ts45-48
• Sandboxing: Execution can be isolated using Docker sandboxes or specialized sandbox providers CHANGELOG.md43

Sources: src/config/schema.help.ts45-48 docs/gateway/configuration-reference.md168-169 CHANGELOG.md43

Getting Started

The recommended way to set up OpenClaw is via the interactive onboarding wizard.

This command guides you through:

1. Model Providers: Configuring API keys for providers like OpenAI, Anthropic, or Google Gemini CHANGELOG.md32
2. Messaging Channels: Linking accounts for Telegram, WhatsApp, etc. CHANGELOG.md13
3. Gateway Service: Configuring the bind host, port, and environment variables src/config/schema.base.generated.ts64-73

For a full walkthrough, see Getting Started.

Sources: src/config/schema.base.generated.ts80-127 CHANGELOG.md13-32 docs/gateway/configuration-reference.md13-22