<!-- source: https://deepwiki.com/openclaw/openclaw/1.2-core-concepts -->

# Core Concepts

- apps/macos/Sources/OpenClaw/HostEnvSecurityPolicy.generated.swift
- docs/.i18n/glossary.zh-CN.json
- docs/automation/index.md
- docs/channels/ambient-room-events.md
- docs/channels/group-messages.md
- docs/channels/troubleshooting.md
- docs/cli/config.md
- docs/concepts/agent-workspace.md
- docs/concepts/context.md
- docs/concepts/soul.md
- docs/concepts/system-prompt.md
- docs/docs.json
- docs/gateway/config-agents.md
- docs/gateway/heartbeat.md
- docs/gateway/local-model-services.md
- docs/gateway/troubleshooting.md
- docs/help/faq-first-run.md
- docs/help/faq.md
- docs/nodes/camera.md
- docs/nodes/index.md
- docs/platforms/macos.md
- docs/providers/ds4.md
- docs/providers/index.md
- docs/reference/rich-output-protocol.md
- docs/reference/token-use.md
- docs/start/openclaw.md
- docs/tools/index.md
- docs/tools/skill-workshop.md
- extensions/anthropic/stream-wrappers.test.ts
- extensions/anthropic/stream-wrappers.ts
- extensions/codex/src/app-server/native-execution-policy.test.ts
- extensions/codex/src/app-server/native-execution-policy.ts
- extensions/whatsapp/light-runtime-api.ts
- extensions/whatsapp/runtime-api.ts
- extensions/whatsapp/src/auth-store.lazy-dir.test.ts
- src/agents/bootstrap-files.test.ts
- src/agents/command/session-store.test.ts
- src/agents/command/session-store.ts
- src/agents/context.test.ts
- src/agents/embedded-agent-helpers/bootstrap.ts
- src/agents/embedded-agent-runner/types.ts
- src/agents/live-model-switch.test.ts
- src/agents/live-model-switch.ts
- src/agents/tools/media-tool-shared.test.ts
- src/auto-reply/reply/commands-context-report.test.ts
- src/cli/config-set-dryrun.ts
- src/cli/program/route-args.test.ts
- src/commands/doctor-session-snapshots.test.ts
- src/commands/doctor-session-snapshots.ts
- src/config/sessions.cache.test.ts
- src/config/sessions/disk-budget.test.ts
- src/config/sessions/disk-budget.ts
- src/config/sessions/lifecycle.ts
- src/config/sessions/sessions.test.ts
- src/config/sessions/skill-prompt-blobs.ts
- src/config/sessions/store-cache.ts
- src/config/sessions/store-load.ts
- src/config/sessions/store.skills-stripping.test.ts
- src/config/sessions/store.ts
- src/config/sessions/types.ts
- src/config/types.agent-defaults.ts
- src/config/zod-schema.agent-defaults.ts
- src/docs/config-path-docs.test.ts
- src/gateway/session-utils.single-row-cache.test.ts
- src/infra/heartbeat-runner.model-override.test.ts
- src/infra/host-env-security-policy.json
- src/infra/host-env-security.reported-baseline.json
- src/infra/host-env-security.reported-baseline.test.ts
- src/infra/host-env-security.test.ts
- src/infra/json-files.test.ts
- src/infra/json-files.ts
- src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
- src/plugins/runtime/runtime-web-channel-plugin.test.ts
- src/plugins/runtime/runtime-web-channel-plugin.ts
- src/plugins/session-entry-slot-keys.ts
- ui/src/ui/views/config-quick.test.ts
- ui/src/ui/views/config-quick.ts

This page explains the fundamental building blocks of OpenClaw: the Gateway, Agents, Sessions, Channels, Tools, Skills, and the personal assistant trust model. Understanding these concepts is essential for configuring and operating OpenClaw effectively.

## Gateway

The Gateway is OpenClaw's central control plane-a Node.js server that coordinates all communication between clients, channels, agents, and tools. It serves as the single point of entry for managing configuration, sessions, and multi-platform messaging.

### Gateway Architecture

The Gateway acts as the traffic controller, routing inbound messages from various platform adapters to the appropriate agent runtime. It is responsible for loading plugins, managing the configuration lifecycle, and maintaining the global hook runner.

Title: Gateway Entity Mapping

```

```

**Key Gateway responsibilities:**

**Crestodian & Delegate Architecture**
For organizational deployments, OpenClaw supports a **delegate architecture** where an agent acts on behalf of humans. **Crestodian** serves as the configless-safe setup and repair helper. It ensures that even without a complex initial config, the system can be bootstrapped safely using the `wizard` state tracking and the `openclaw doctor` command [docs/help/faq.md60-67](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/help/faq.md?plain=1#L60-L67)

**Sources:** [src/gateway/local-request-context.ts16-21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/local-request-context.ts#L16-L21) [src/routing/session-key.ts27-34](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.ts#L27-L34) [docs/help/faq.md60-67](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/help/faq.md?plain=1#L60-L67) [src/config/sessions/store.ts86](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L86-L86)

## Agents

An agent is an isolated runtime context powered by the execution pipeline. It manages its own workspace, model providers, and tool execution logic. OpenClaw supports multi-agent routing where different channels or senders can be bound to different agents.

Title: Agent Execution Pipeline and Provider Resolution

```

```

**Agent configuration hierarchy:**

The execution pipeline handles the lifecycle of an interaction, including retries and model selection. After a run, `updateSessionStoreAfterAgentRun` persists the model used, token usage, and session metadata [src/agents/command/session-store.ts55-76](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/session-store.ts#L55-L76)

**Sources:** [docs/gateway/config-agents.md1-150](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L1-L150) [src/agents/command/session-store.ts55-120](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/session-store.ts#L55-L120) [src/agents/command/session-store.test.ts20-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/session-store.test.ts#L20-L24)

## Sessions

A session is the conversation state boundary. OpenClaw uses a flexible session scoping model. Sessions are identified by unique keys and persisted as JSONL transcripts in a dedicated store.

### Session Scoping

OpenClaw supports several session scoping modes:

- main : A single global session.
- agent : Sessions scoped to a specific agent instance.
- subagent : Specialized sessions spawned for task delegation.

**Session Storage and Cache:**
Sessions are stored in `sessions.json` and managed by `loadSessionStore` [src/config/sessions/store.ts42-46](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L42-L46) To improve performance, OpenClaw implements a multi-layer cache in `store-cache.ts` that includes a serialized string cache and a "DeepReadonly" snapshot cache [src/config/sessions/store-cache.ts14-39](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-cache.ts#L14-L39) Large strings, such as skill prompts, are interned to reduce memory pressure [src/config/sessions/store-cache.ts111-125](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-cache.ts#L111-L125)

**Maintenance:**
The Gateway automatically prunes stale entries and enforces a disk budget for session files [src/config/sessions/store.ts17-18](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L17-L18) Resets can be triggered based on idle time or daily schedules (e.g., 4 AM) [src/config/sessions/sessions.test.ts143-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/sessions.test.ts#L143-L150)

**Sources:** [src/config/sessions/store.ts1-60](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L1-L60) [src/config/sessions/store-cache.ts1-64](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-cache.ts#L1-L64) [src/config/sessions/sessions.test.ts42-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/sessions.test.ts#L42-L150)

## Channels

Channels are the messaging surfaces that connect to the Gateway. Each channel handles message normalization and delivery.

**Channel Architecture:**
Channels handle platform-specific events (e.g., Telegram, Discord, WhatsApp) and route them to the Gateway's multi-agent router. The system normalizes delivery context (channel, accountId, threadId) to ensure consistent routing [src/config/sessions/store-load.ts84-100](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-load.ts#L84-L100)

**Channel Policy:**
Access is governed by policies including `allowFrom` restrictions. Channels can enforce daily resets or idle timeouts for sessions to keep interactions fresh [src/config/sessions/sessions.test.ts125-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/sessions.test.ts#L125-L140)

**Sources:** [src/config/sessions/store-load.ts84-100](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-load.ts#L84-L100) [src/config/sessions/sessions.test.ts125-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/sessions.test.ts#L125-L140)

## Tools

Tools allow agents to interact with the host system or external APIs. They are registered via the plugin system and can be dynamically discovered by agents.

**Tool Categories:**

- Coding Tools: File manipulation and shell execution.
- Browser Automation: CDP-based tab control and web navigation.
- Memory Tools: Hybrid search for recalling information from session history docs/gateway/config-agents.md 192-194
- Media Tools: Image understanding and media processing.

**Tool Policy:**
Tool execution is governed by policies that can restrict access to specific agents or environments. The system uses a `SecretRef` system to handle credentials required by tools securely.

**Sources:** [docs/gateway/config-agents.md175-194](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L175-L194) [src/agents/command/session-store.ts24-33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/session-store.ts#L24-L33)

## Skills

Skills are modular capability definitions, often defined in `SKILL.md` files. They provide high-level guidance and standing orders to agents.

- Modular Instructions: Skills are injected into the system prompt based on an allowlist docs/gateway/config-agents.md 40-45
- Workspace Skills: Agents can load skills directly from their workspace directory ( ./skills ).
- Hydration: Skill prompts are stored as blobs and hydrated during agent execution src/config/sessions/store.ts 20-25

**Sources:** [docs/gateway/config-agents.md40-63](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L40-L63) [src/config/sessions/store.ts20-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L20-L25)

## Trust Model

OpenClaw is designed as a **personal AI assistant**, operating under a single-user trust model where the operator is the owner of the Gateway.

1. Trusted Operator Boundary: The system assumes the person running the Gateway is the authorized administrator.
2. Security Auditing: The system includes a security audit command to identify filesystem, gateway, and sandbox risks docs/help/faq.md 60-67
3. Sandboxing: OpenClaw supports Docker-based sandboxing for tool execution, ensuring that dangerous commands are isolated from the host system.
4. Secret Management: Sensitive credentials are never stored in plain text in transcripts; the system uses a SecretRef resolution hierarchy.

**Sources:** [docs/help/faq.md84-106](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/help/faq.md?plain=1#L84-L106) [src/config/sessions/store.ts150-168](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L150-L168)
