<!-- source: https://deepwiki.com/openclaw/openclaw/1-overview -->

# Overview

- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-testing/SKILL.md
- .crabbox.yaml
- .github/actions/ensure-base-commit/action.yml
- .github/actions/setup-node-env/action.yml
- .github/actions/setup-pnpm-store-cache/action.yml
- .github/actions/setup-pnpm-store-cache/ensure-node.sh
- .github/workflows/ci-build-artifacts-testbox.yml
- .github/workflows/ci-check-testbox.yml
- .github/workflows/ci.yml
- .github/workflows/crabbox-hydrate.yml
- .github/workflows/openclaw-cross-os-release-checks-reusable.yml
- .github/workflows/windows-blacksmith-testbox.yml
- AGENTS.md
- CHANGELOG.md
- CONTRIBUTING.md
- docs/.generated/plugin-sdk-api-baseline.sha256
- docs/ci.md
- docs/plugins/codex-harness-reference.md
- docs/plugins/codex-harness-runtime.md
- docs/plugins/codex-harness.md
- docs/plugins/sdk-migration.md
- docs/plugins/sdk-subpaths.md
- docs/reference/full-release-validation.md
- docs/tools/btw.md
- extensions/acpx/npm-shrinkwrap.json
- extensions/amazon-bedrock-mantle/npm-shrinkwrap.json
- extensions/amazon-bedrock/npm-shrinkwrap.json
- extensions/anthropic-vertex/npm-shrinkwrap.json
- extensions/codex/harness.ts
- extensions/codex/index.test.ts
- extensions/codex/npm-shrinkwrap.json
- extensions/codex/src/app-server/dynamic-tools.test.ts
- extensions/codex/src/app-server/dynamic-tools.ts
- extensions/codex/src/app-server/event-projector.test.ts
- extensions/codex/src/app-server/event-projector.ts
- extensions/codex/src/app-server/local-runtime-attribution.ts
- extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts
- extensions/codex/src/app-server/protocol-validators.ts
- extensions/codex/src/app-server/protocol.ts
- extensions/codex/src/app-server/run-attempt.test.ts
- extensions/codex/src/app-server/run-attempt.ts
- extensions/codex/src/app-server/side-question.test.ts
- extensions/codex/src/app-server/side-question.ts
- extensions/codex/src/app-server/thread-lifecycle.test.ts
- extensions/codex/src/app-server/thread-lifecycle.ts
- extensions/codex/src/app-server/trajectory.test.ts
- extensions/codex/src/app-server/trajectory.ts
- extensions/codex/test-api.ts
- extensions/diagnostics-otel/npm-shrinkwrap.json
- extensions/discord/index.ts
- extensions/discord/npm-shrinkwrap.json
- extensions/google-meet/src/realtime-node.ts
- extensions/google-meet/src/realtime.ts
- extensions/memory-core/src/memory/provider-adapters.ts
- extensions/memory-lancedb/npm-shrinkwrap.json
- extensions/twitch/npm-shrinkwrap.json
- extensions/whatsapp/npm-shrinkwrap.json
- npm-shrinkwrap.json
- package.json
- pnpm-lock.yaml
- pnpm-workspace.yaml
- qa/scenarios/memory/thread-memory-isolation.md
- scripts/AGENTS.md
- scripts/ci-run-timings.mjs
- scripts/crabbox-wrapper.mjs
- scripts/generate-prompt-snapshots.ts
- scripts/lib/ci-node-test-plan.mjs
- scripts/lib/docker-build.sh
- scripts/lib/plugin-sdk-entrypoints.json
- scripts/lib/plugin-sdk-private-local-only-subpaths.json
- scripts/prompt-snapshot-files.ts
- src/agents/auth-profile-runtime-contract.test.ts
- src/agents/btw.test.ts
- src/agents/btw.ts
- src/agents/harness/types.ts
- src/agents/tools/image-tool.providers.live.test.ts
- src/plugin-sdk/entrypoints.ts
- src/plugin-sdk/memory-core-host-embedding-registry.ts
- src/plugin-sdk/realtime-voice.ts
- src/talk/output-activity-tracker.test.ts
- src/talk/output-activity-tracker.ts
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/README.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.discord-group.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.heartbeat-turn.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.telegram-direct.json
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/discord-group-codex-message-tool.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md
- test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-heartbeat-codex-tool.md
- test/helpers/agents/happy-path-prompt-snapshots.ts
- test/helpers/agents/prompt-snapshot-paths.ts
- test/scripts/ci-node-test-plan.test.ts
- test/scripts/ci-run-timings.test.ts
- test/scripts/ci-workflow-guards.test.ts
- test/scripts/crabbox-wrapper.test.ts
- test/scripts/openclaw-cross-os-release-workflow.test.ts
- test/scripts/package-acceptance-workflow.test.ts
- test/scripts/prompt-snapshots.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/vitest/vitest.unit-support.config.ts

OpenClaw is a **multi-platform AI gateway** and personal assistant system that orchestrates conversations between messaging channels and AI agents [package.json2-4](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L2-L4) It acts as a central control plane, connecting messaging platforms like WhatsApp, Telegram, Slack, and Discord to advanced AI models, providing a unified interface for AI interaction [package.json89-112](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L89-L112)

The system is powered by the **Pi Agent Core** [pnpm-lock.yaml56-58](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-lock.yaml#L56-L58) and is designed around a **Personal Assistant Trust Model**, assuming a single trusted operator boundary. It enables agents to perform real-world tasks through a rich tool ecosystem, including browser automation, filesystem access, and media understanding.

For installation and first-time setup, see [Getting Started](/openclaw/openclaw/1.1-getting-started). For fundamental mental models, see [Core Concepts](/openclaw/openclaw/1.2-core-concepts). For technical details on the build system and cross-platform clients, see [Platform Architecture](/openclaw/openclaw/1.3-platform-architecture).

Sources: [package.json2-4](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L2-L4) [package.json89-112](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L89-L112) [pnpm-lock.yaml56-58](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-lock.yaml#L56-L58)

## Core Architecture

OpenClaw is organized as a monorepo using `pnpm` workspaces [pnpm-workspace.yaml1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L1-L5) The Gateway is the central engine that manages the lifecycle of the assistant, configuration validation, and agent execution.

### System Mapping: Natural Language to Code Entities

```

```

Sources: [AGENTS.md44-60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L44-L60) [package.json16-17](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L16-L17) [docs/plugins/sdk-subpaths.md26-28](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L26-L28) [extensions/codex/src/app-server/run-attempt.ts32-36](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L32-L36) [pnpm-workspace.yaml1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L1-L5)

## 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. The system maintains a `models.json` for model discovery and configuration [CHANGELOG.md17](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L17-L17) Agents can utilize various runtimes, including the embedded Pi core or the **Codex app-server** harness for specialized coding tasks [extensions/codex/src/app-server/run-attempt.ts118-128](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L118-L128)

### Sessions & Channels

A **Session** represents a specific conversation thread. **Channels** are the transport layers (like Telegram, WhatsApp, or Google Meet) that route messages to the Gateway [CHANGELOG.md10](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L10-L10) The system now utilizes **SQLite-backed state** for inbound queues and monitor tracking to ensure persistence across restarts [CHANGELOG.md18](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L18-L18)

### Skills & Tools

**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.md4](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L4-L4) A new **Skill Workshop** flow in the Control UI allows for governed skill creation and reviewable proposals [CHANGELOG.md15](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L15-L15)

For a deeper dive into these primitives, see [Core Concepts](/openclaw/openclaw/1.2-core-concepts).

Sources: [CHANGELOG.md10-18](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L10-L18) [extensions/codex/src/app-server/run-attempt.ts118-128](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L118-L128) [AGENTS.md4-60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L4-L60)

## Multi-Platform Architecture

OpenClaw is built for high portability across desktop, server, and mobile environments. It leverages a shared TypeScript core and native UI components.

### Data Flow: Message to Tool Execution

```

```

Sources: [AGENTS.md44-55](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L44-L55) [extensions/codex/src/app-server/dynamic-tool-execution.js155](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/dynamic-tool-execution.js#L155-L155) [extensions/codex/src/app-server/run-attempt.ts32](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/codex/src/app-server/run-attempt.ts#L32-L32)

For details on the build system and native integrations, see [Platform Architecture](/openclaw/openclaw/1.3-platform-architecture).

## Security & Trust

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:

- Boundary Checks : Automated enforcement to prevent unauthorized cross-package imports AGENTS.md 51-53
- SecretRef System : Manifest-driven contract for managing provider integration credentials CHANGELOG.md 39
- Audit System : Diagnostic repair and health checks for disk space and post-upgrade JSON probes CHANGELOG.md 42
- Sandboxing : Execution of dangerous tasks within isolated environments like Docker or OpenShell package.json 105

Sources: [AGENTS.md51-59](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L51-L59) [CHANGELOG.md39-42](https://github.com/openclaw/openclaw/blob/fbdf5937/CHANGELOG.md?plain=1#L39-L42) [package.json105](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L105-L105)

## 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 pnpm-lock.yaml 47-61
2. Messaging Channels : Linking accounts for Telegram, WhatsApp, Discord, etc. package.json 89-112
3. Workspace Setup : Initializing the configuration and agent workspaces AGENTS.md 60

For a full walkthrough, see [Getting Started](/openclaw/openclaw/1.1-getting-started).

Sources: [package.json16-17](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L16-L17) [pnpm-lock.yaml47-61](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-lock.yaml#L47-L61) [AGENTS.md60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L60-L60)
