> For the complete documentation index, see [llms.txt](https://www.openclawbook.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.openclawbook.xyz/readme.md).

# Deep Dive into OpenClaw — Table of Contents

> **Generated by**: Claude Opus 5 (claude-opus-5) / Claude Opus 4.6 (earlier chapters) **Tools**: Claude Code + OpenClaw + OpenCode **Last updated**: 2026-08-02 **Source baseline**: `v2026.3.9` (`v2026.3.8-170-g665f67726`) **GitHub**: <https://github.com/0xtresser/OpenClaw-Book>

***

## Language

[中文版本](/readme-zh.md)

***

## Three Layers

The book is organized shallow-to-deep, but **you don't have to read it in order**. The three layers stand on their own:

| Layer              | Parts                  | Read it to                                            | Source code required?                 |
| ------------------ | ---------------------- | ----------------------------------------------------- | ------------------------------------- |
| **Usage**          | Part I (Ch. 1–10)      | Install and use OpenClaw                              | No                                    |
| **Implementation** | Parts II–X (Ch. 11–42) | Understand how each subsystem works                   | Yes                                   |
| **Insight**        | Part XI (Ch. 43–45)    | Extract transferable design lessons and risk judgment | Better after the implementation layer |

From Chapter 11 on, most chapters end with a **🔬 Source Deep Dive** section. It sits closer to the source than the main text and carries a higher information density, tracing the real implementation line by line along with the issues behind it.

> **The main text is for understanding structure; the deep dive is for understanding trade-offs.** If you only want to know what a piece does, the main text is enough. If you're going to modify it, or reproduce it in your own project, read the deep dive.

***

## [Preface](/en/00-preface/preface.md)

* Why this book exists, and who it's for
* What OpenClaw is: a personal AI assistant that runs on your own devices
* How the book is organized, and how to read it
* Source version (`v2026.3.9`)
* Prerequisites: TypeScript basics, Node.js runtime concepts, WebSocket, basic operating-system knowledge

***

## Part I: Getting Started

> From zero to fluent. No source reading required — follow along and it works.

### Chapter 1: Understanding OpenClaw

* [**1.1 What is OpenClaw**](/en/ch01-understanding-openclaw/1.1-what-is-openclaw.md)
* [**1.2 Core Architecture Overview**](/en/ch01-understanding-openclaw/1.2-core-architecture-overview.md)
* [**1.3 Technology Stack Overview**](/en/ch01-understanding-openclaw/1.3-technology-stack-overview.md)
* [**1.4 Project Directory Structure**](/en/ch01-understanding-openclaw/1.4-project-directory-structure.md)

### Chapter 2: Installation and Quick Start

* [**2.1 Environment Setup**](/en/ch02-getting-started/2.1-environment-setup.md)
* [**2.2 Onboarding Wizard**](/en/ch02-getting-started/2.2-onboarding-wizard.md)
* [**2.3 Starting the Gateway Daemon**](/en/ch02-getting-started/2.3-starting-the-gateway-daemon.md)
* [**2.4 Development Workflow**](/en/ch02-getting-started/2.4-development-workflow.md)

### Chapter 3: Connecting Channels

* [**3.1 Telegram Bot: Complete Setup**](/en/ch03-channel-setup/3.1-telegram-bot-complete-setup.md)
* [**3.2 Discord and Slack**](/en/ch03-channel-setup/3.2-discord-and-slack.md)
* [**3.3 Multi-Channel Strategy and Group Management**](/en/ch03-channel-setup/3.3-multi-channel-strategy-and-groups.md)

### Chapter 4: Conversation and Tools

* [**4.1 Conversation Techniques and Commands**](/en/ch04-conversation-and-tools/4.1-conversation-techniques-and-commands.md)
* [**4.2 Bash Tools in Practice**](/en/ch04-conversation-and-tools/4.2-bash-tools-in-practice.md)
* [**4.3 Browser Tools and Canvas**](/en/ch04-conversation-and-tools/4.3-browser-tools-and-canvas.md)

### Chapter 5: Scheduling and Automation

* [**5.1 Getting Started with Cron**](/en/ch05-scheduling-and-automation/5.1-getting-started-with-cron.md)
* [**5.2 Webhooks and Event-Driven Automation**](/en/ch05-scheduling-and-automation/5.2-webhooks-and-event-driven-automation.md)
* [**5.3 Automation Case Studies**](/en/ch05-scheduling-and-automation/5.3-automation-case-studies.md)

### Chapter 6: The Skills Ecosystem

* [**6.1 Skills Concepts and ClawHub**](/en/ch06-skills-ecosystem/6.1-skills-concepts-and-clawhub.md)
* [**6.2 Common Skills in Practice**](/en/ch06-skills-ecosystem/6.2-common-skills-in-practice.md)
* [**6.3 Writing a Custom Skill**](/en/ch06-skills-ecosystem/6.3-writing-a-custom-skill.md)

### Chapter 7: Model Configuration and Optimization

* [**7.1 Providers and API Keys**](/en/ch07-model-configuration/7.1-providers-and-api-keys.md)
* [**7.2 Fallback Chains and Cost Optimization**](/en/ch07-model-configuration/7.2-fallback-chains-and-cost-optimization.md)
* [**7.3 Regional Model Providers**](/en/ch07-model-configuration/7.3-regional-model-providers.md)

### Chapter 8: Regional Platforms and Deployment

* [**8.1 Feishu, DingTalk, and WeCom**](/en/ch08-regional-platforms-and-deployment/8.1-feishu-dingtalk-and-wecom.md)
* [**8.2 Cloud Deployment in Practice**](/en/ch08-regional-platforms-and-deployment/8.2-cloud-deployment-in-practice.md)
* [**8.3 Docker Deployment and Production Configuration**](/en/ch08-regional-platforms-and-deployment/8.3-docker-and-production-configuration.md)

### Chapter 9: Multi-Agent in Practice

* [**9.1 Multi-Agent Configuration and Routing**](/en/ch09-multi-agent-in-practice/9.1-multi-agent-configuration-and-routing.md)
* [**9.2 Subagents and Cross-Agent Communication**](/en/ch09-multi-agent-in-practice/9.2-subagents-and-cross-agent-communication.md)
* [**9.3 Team Collaboration and Case Studies**](/en/ch09-multi-agent-in-practice/9.3-team-collaboration-and-case-studies.md)

### Chapter 10: Advanced Techniques and Best Practices

* [**10.1 Memory and Knowledge Management**](/en/ch10-advanced-techniques/10.1-memory-and-knowledge-management.md)
* [**10.2 Security Hardening and Permission Management**](/en/ch10-advanced-techniques/10.2-security-hardening-and-permissions.md)
* [**10.3 Customization and Common Questions**](/en/ch10-advanced-techniques/10.3-customization-and-common-questions.md)

***

## Part II: Gateway Control Plane

### Chapter 11: Gateway Server Architecture

* [**11.1 Gateway Role and Design Goals**](/en/ch11-gateway-server-architecture/11.1-gateway-role-and-design-goals.md)
* [**11.2 Server Startup Flow Source Analysis**](/en/ch11-gateway-server-architecture/11.2-server-startup-flow-source-analysis.md)
* [**11.3 WebSocket Server Implementation**](/en/ch11-gateway-server-architecture/11.3-websocket-server-implementation.md)
* [**11.4 HTTP Layer**](/en/ch11-gateway-server-architecture/11.4-http-layer.md)
* 🔬 [**11.5 Source Deep Dive: The Assembly Site and the Method Routing Table**](/en/ch11-gateway-server-architecture/11.5-source-deep-dive-assembly-and-method-routing.md)
  * A flat method routing table and the dispatcher's three gates (**bidirectional** role isolation, scope, control-plane write budget)
  * `startGatewayServer`'s 15-step assembly sequence and hand-rolled dependency injection
  * The HTTP stage pipeline; the "agent as model" trade-off in the OpenAI-compatible layer
  * The invariant: a node never runs gateway services

### Chapter 12: Gateway Protocol and Type System

* [**12.1 Protocol Design Philosophy**](/en/ch12-gateway-protocol-and-type-system/12.1-protocol-design-philosophy.md)
* [**12.2 TypeBox Type Schema**](/en/ch12-gateway-protocol-and-type-system/12.2-typebox-type-schema.md)
* [**12.3 Core Methods and Events**](/en/ch12-gateway-protocol-and-type-system/12.3-core-methods-and-events.md)
* [**12.4 Authentication and Authorization**](/en/ch12-gateway-protocol-and-type-system/12.4-authentication-and-authorization.md)
* 🔬 [**12.5 Source Deep Dive: Three Frames, the Handshake, and Four Auth Layers**](/en/ch12-gateway-protocol-and-type-system/12.5-source-deep-dive-frames-handshake-and-auth.md)
  * Three frame types, and the codegen motive behind the discriminated union
  * Why "events don't replay + requests are idempotent" is the correctness basis for reconnecting over a flaky network
  * Four auth layers: shared credential → Ed25519 device identity → pairing approval → device token
  * Sentinel-IP accounting for browser origins; Tailscale identity headers must be reverse-verified

### Chapter 13: Session Management

* [**13.1 Session Model Design**](/en/ch13-session-management/13.1-session-model-design.md)
* [**13.2 Session Routing Source Analysis**](/en/ch13-session-management/13.2-session-routing-source-analysis.md)
* [**13.3 Session Lifecycle**](/en/ch13-session-management/13.3-session-lifecycle.md)
* [**13.4 Session Pruning**](/en/ch13-session-management/13.4-session-pruning.md)
* [**13.5 Inter-Session Communication**](/en/ch13-session-management/13.5-inter-session-communication.md)
* 🔬 [**13.6 Source Deep Dive: Two-Tier Lanes and Three Queue Semantics**](/en/ch13-session-management/13.6-source-deep-dive-two-tier-lanes-and-queue-semantics.md)
  * `session lane(1) ⊂ global lane(N)` — about 300 lines of plain Promises
  * Six queueing modes at a glance; `collect`'s cross-channel degradation and overflow summarize
  * The typing indicator's dual-signal convergence point (the extension trap people hit most)
  * Session reset "changes the ID without deleting the key"; four costs

### Chapter 14: Channel Routing and Message Dispatch

* [**14.1 Channel Registry**](/en/ch14-channel-routing-and-message-dispatch/14.1-channel-registry.md)
* [**14.2 Inbound Message Processing Pipeline**](/en/ch14-channel-routing-and-message-dispatch/14.2-inbound-message-processing-pipeline.md)
* [**14.3 Outbound Message Processing**](/en/ch14-channel-routing-and-message-dispatch/14.3-outbound-message-processing.md)
* [**14.4 Multi-Agent Routing**](/en/ch14-channel-routing-and-message-dispatch/14.4-multi-agent-routing.md)
* 🔬 [**14.5 Source Deep Dive: Seven Gates on the Inbound Pipeline**](/en/ch14-channel-routing-and-message-dispatch/14.5-source-deep-dive-seven-inbound-gates.md)
  * Inbound debounce (sliding window, with media and commands forced through)
  * The mention gate's three-way decision and zero-width-character scrubbing; blocked messages still enter the history buffer
  * The seven-level binding cascade and three-level cache (the config object as a WeakMap key)
  * The default session key collapses every DM into one main session — "one person, many entrances"

***

## Part III: AI Agent Runtime

### Chapter 15: Pi Agent Runtime Core

* [**15.1 What is Pi Agent**](/en/ch15-piagent-runtime-core/15.1-what-is-piagent.md)
* [**15.2 Agent Loop End-to-End Analysis**](/en/ch15-piagent-runtime-core/15.2-agent-loop-end-to-end-analysis.md)
* [**15.3 Queue and Concurrency Control**](/en/ch15-piagent-runtime-core/15.3-queue-and-concurrency-control.md)
* [**15.4 Timeout and Abort Mechanisms**](/en/ch15-piagent-runtime-core/15.4-timeout-and-abort-mechanisms.md)
* 🔬 [**15.5 Source Deep Dive: The Full Journey of a Run**](/en/ch15-piagent-runtime-core/15.5-source-deep-dive-full-journey-of-a-run.md)
  * Across 88,000 lines, exactly one statement drives the loop: `session.prompt()`
  * Retry ceilings scale with the number of auth profiles; `attempt.ts`'s 2,096-line ten-step assembly
  * The streamFn onion: the single injection point into pi, with each of its seven layers tracing to a real issue
  * The streaming event bridge's tag stripping, tool-send deduplication, and three forms of reasoning

### Chapter 16: Model Providers and Failover

* [**16.1 Model Selection Mechanism**](/en/ch16-model-providers-and-failover/16.1-model-selection-mechanism.md)
* [**16.2 AuthProfile and Credential Management**](/en/ch16-model-providers-and-failover/16.2-authprofile-and-credential-management.md)
* [**16.3 Model Catalog and Configuration**](/en/ch16-model-providers-and-failover/16.3-model-catalog-and-configuration.md)
* [**16.4 Failover Error Handling**](/en/ch16-model-providers-and-failover/16.4-failover-error-handling.md)
* 🔬 [**16.5 Source Deep Dive: Auth Profile Rotation, Cooldown, and Degradation**](/en/ch16-model-providers-and-failover/16.5-source-deep-dive-auth-profile-rotation.md)
  * The cost policy is written into the sort function: OAuth subscriptions first, API keys as backstop
  * Two critical disciplines: **an active window is never extended**, and **timeouts are never charged**
  * Four time scales each governing one span; why three structured observability logs are a requirement, not a luxury

### Chapter 17: System Prompts and Context Assembly

* [**17.1 Building System Prompts**](/en/ch17-system-prompts-and-context-assembly/17.1-building-system-prompts.md)
* [**17.2 Workspace and Context File Injection**](/en/ch17-system-prompts-and-context-assembly/17.2-workspace-and-context-file-injection.md)
* [**17.3 Identity System**](/en/ch17-system-prompts-and-context-assembly/17.3-identity-system.md)
* [**17.4 Context Compaction**](/en/ch17-system-prompts-and-context-assembly/17.4-context-compaction.md)
* [**17.5 The Context Engine Plugin System**](/en/ch17-system-prompts-and-context-assembly/17.5-context-engine-plugin-system.md)
* 🔬 [**17.6 Source Deep Dive: Four Lines of Context Defense**](/en/ch17-system-prompts-and-context-assembly/17.6-source-deep-dive-four-lines-of-context-defense.md)
  * Entry guard → in-request pruning (not persisted) → compaction (persisted) → tool-result truncation
  * Folding Anthropic's 5-minute cache TTL into the pruning decision (cost-aware context management)
  * compaction-safeguard: better to cancel compaction than emit a bad summary
  * The usage-accounting trap: `cacheRead` must not be summed

### Chapter 18: Streaming and Block Replies

* [**18.1 Streaming Architecture**](/en/ch18-streaming-and-block-replies/18.1-streaming-architecture.md)
* [**18.2 Block Streaming**](/en/ch18-streaming-and-block-replies/18.2-block-streaming.md)
* [**18.3 Coalescing and Humanized Pacing**](/en/ch18-streaming-and-block-replies/18.3-coalescing-and-humanized-pacing.md)
* [**18.4 Telegram Draft Streaming**](/en/ch18-streaming-and-block-replies/18.4-telegram-draft-streaming.md)
* [**18.5 Reply Shaping and Suppression**](/en/ch18-streaming-and-block-replies/18.5-reply-shaping-and-suppression.md)
* 🔬 [**18.6 Source Deep Dive: The Serial Outbound Chain and Chunk Aggregation**](/en/ch18-streaming-and-block-replies/18.6-source-deep-dive-outbound-chain-and-chunking.md)
  * `pending` starting at 1 — a reservation count
  * Splitting (chunk) and merging (coalescer): two components pulling in opposite directions
  * `routeReply`'s failure fallback: **when delivered and delivered-correctly conflict, choose correctly**

***

## Part IV: Multi-Channel Messaging System

### Chapter 19: Channel Adapter Abstraction

* [**19.1 Channel Adapter Design Pattern**](/en/ch19-channel-adapter-abstraction/19.1-channel-adapter-design-pattern.md)
* [**19.2 Inbound Message Normalization**](/en/ch19-channel-adapter-abstraction/19.2-inbound-message-normalization.md)
* [**19.3 Outbound Message Adaptation**](/en/ch19-channel-adapter-abstraction/19.3-outbound-message-adaptation.md)
* 🔬 [**19.4 Source Deep Dive: The ChannelPlugin Contract and Dual Registries**](/en/ch19-channel-adapter-abstraction/19.4-source-deep-dive-channelplugin-contract-and-dual-registries.md)
  * Why there's no unified message bus: unification happens at the contract layer, not the data-flow layer
  * Reply routing is deterministic — designing out the "injection reroutes the agent" attack
  * **The dock / plugin heavy-light split**: the single most copyable move in the chapter
  * Envelope-header escaping against forgery; `src/web/` is actually WhatsApp

### Chapter 20: Core Channel Implementations

* [**20.1 WhatsApp Channel**](/en/ch20-core-channel-implementations/20.1-whatsapp-channel.md)
* [**20.2 Telegram Channel**](/en/ch20-core-channel-implementations/20.2-telegram-channel.md)
* [**20.3 Discord Channel**](/en/ch20-core-channel-implementations/20.3-discord-channel.md)
* [**20.4 Slack Channel**](/en/ch20-core-channel-implementations/20.4-slack-channel.md)
* [**20.5 Other Core Channels**](/en/ch20-core-channel-implementations/20.5-other-core-channels.md)
* 🔬 [**20.6 Source Deep Dive: Three Long-Lived Connections, Two Streaming Modes**](/en/ch20-core-channel-implementations/20.6-source-deep-dive-three-connections-two-streaming-modes.md)
  * The Telegram watchdog: the probe rides on ordinary `getUpdates` traffic
  * Block streaming vs. draft streaming, and the throttle kernel they share
  * `sendMayHaveLanded`: **"I don't know" is a third state that must be modeled**
  * A side-by-side comparison of all 17 channels

### Chapter 21: Channel Extension Mechanism

* [**21.1 Extension Architecture Design**](/en/ch21-channel-extension-mechanism/21.1-extension-architecture-design.md)
* [**21.2 Extension API Surface**](/en/ch21-channel-extension-mechanism/21.2-extension-api-surface.md)
* [**21.3 Representative Extension Implementations**](/en/ch21-channel-extension-mechanism/21.3-representative-extension-implementations.md)
* [**21.4 Developing Custom Extensions**](/en/ch21-channel-extension-mechanism/21.4-developing-custom-extensions.md)
* 🔬 [**21.5 Source Deep Dive: The Loader, jiti, and the SDK Surface**](/en/ch21-channel-extension-mechanism/21.5-source-deep-dive-loader-jiti-and-sdk-surface.md)
  * Manifest/execution separation: **"validating configuration never becomes running code"**
  * The jiti bargain: what-you-audit-is-what-runs and zero SDK drift ↔ zero runtime isolation
  * Only three boundaries are actually enforced; the rest are documentation boundaries
  * Three npm primitives instead of a centralized marketplace; `--ignore-scripts` removes the supply-chain surface

***

## Part V: Tool System and Automation

### Chapter 22: Tool System Overview

* [**22.1 Tool System Architecture**](/en/ch22-tool-system-overview/22.1-tool-system-architecture.md)
* [**22.2 Tool Registration and Policy**](/en/ch22-tool-system-overview/22.2-tool-registration-and-policy.md)
* [**22.3 Tool Execution and Result Handling**](/en/ch22-tool-system-overview/22.3-tool-execution-and-result-handling.md)
* [**22.4 Execution Approval Mechanism**](/en/ch22-tool-system-overview/22.4-execution-approval-mechanism.md)
* 🔬 [**22.5 Source Deep Dive: The Tool Assembly Pipeline and the Sandbox**](/en/ch22-tool-system-overview/22.5-source-deep-dive-tool-assembly-and-sandbox.md)
  * A five-stage assembly line and **seven layers of policy filtering**; why every tool goes through `customTools`
  * `exec`'s three dimensions: `security` takes the minimum, `ask` takes the maximum — deliberately opposite
  * The two-phase approval protocol decouples "the LLM calls synchronously" from "a human approves asynchronously"
  * The sandbox is not `docker exec`: read-only root + cap-drop + `configHash` auto-rebuild

### Chapter 23: Bash Tools and Process Management

* [**23.1 Bash Execution Engine**](/en/ch23-bash-tools-and-process-management/23.1-bash-execution-engine.md)
* [**23.2 Process Management**](/en/ch23-bash-tools-and-process-management/23.2-process-management.md)
* [**23.3 Shell Tools and Shared Infrastructure**](/en/ch23-bash-tools-and-process-management/23.3-shell-tools-and-shared-infrastructure.md)

### Chapter 24: Browser Control

* [**24.1 Browser Architecture Overview**](/en/ch24-browser-control/24.1-browser-architecture-overview.md)
* [**24.2 CDP Layer Implementation**](/en/ch24-browser-control/24.2-cdp-layer-implementation.md)
* [**24.3 Playwright Layer Implementation**](/en/ch24-browser-control/24.3-playwright-layer-implementation.md)
* [**24.4 Browser Server**](/en/ch24-browser-control/24.4-browser-server.md)
* 🔬 [**24.5 Source Deep Dive: Four Browser Sources and Three Security Gates**](/en/ch24-browser-control/24.5-source-deep-dive-four-sources-three-gates.md)
  * Not headless — it attaches to a real Chrome, with an orange window marker
  * The snapshot is an accessibility text tree rather than a screenshot: an order of magnitude better on tokens
  * The key SSRF insight: **an environment proxy renders DNS pre-checks meaningless**
  * Auth bootstrap: **loopback does not mean safe**

### Chapter 25: Canvas and A2UI

* [**25.1 Canvas Concepts**](/en/ch25-canvas-and-a2ui/25.1-canvas-concepts.md)
* [**25.2 Canvas Host Implementation**](/en/ch25-canvas-and-a2ui/25.2-canvas-host-implementation.md)
* [**25.3 Canvas Tools**](/en/ch25-canvas-and-a2ui/25.3-canvas-tools.md)

### Chapter 26: Cron Scheduling and Automation

* [**26.1 Cron System Design**](/en/ch26-cron-scheduling-and-automation/26.1-cron-system-design.md)
* [**26.2 Cron Job Execution**](/en/ch26-cron-scheduling-and-automation/26.2-cron-job-execution.md)
* [**26.3 Webhooks and Gmail Pub/Sub**](/en/ch26-cron-scheduling-and-automation/26.3-webhooks-and-gmail-pubsub.md)
* 🔬 [**26.4 Source Deep Dive: The Division of Labor Between Cron and Heartbeat**](/en/ch26-cron-scheduling-and-automation/26.4-source-deep-dive-cron-vs-heartbeat.md)
  * Two session shapes, strictly validated as a pair at creation time
  * Three incident lessons: the `setTimeout(0)` hot loop, the restart catch-up storm, and stuck jobs
  * Deterministic jitter from the SHA-256 of the job id rather than a random number
  * The heartbeat's three-part design: yield, economize, stay silent

### Chapter 27: Node System

* [**27.1 Node Concepts**](/en/ch27-node-system/27.1-node-concepts.md)
* [**27.2 Node Registration and Discovery**](/en/ch27-node-system/27.2-node-registration-and-discovery.md)
* [**27.3 Node Host Implementation**](/en/ch27-node-system/27.3-node-host-implementation.md)
* 🔬 [**27.4 Source Deep Dive: Reverse RPC and the Wake Mechanism**](/en/ch27-node-system/27.4-source-deep-dive-reverse-rpc-and-wake.md)
  * Four layers wrapped around `node.invoke`
  * **An operation that changes permissions should not travel the same channel as an ordinary one**
  * The three-stage APNs wake: the user is only disturbed after the first two fail
  * The iOS foreground queue — a patch for the mobile lifecycle, promoted into a mechanism

***

## Part VI: Memory, Skills, and Ecosystem

### Chapter 28: Memory System

* [**28.1 Memory Model Design**](/en/ch28-memory-system/28.1-memory-model-design.md)
* [**28.2 Vector Memory Search**](/en/ch28-memory-system/28.2-vector-memory-search.md)
* [**28.3 Hybrid Search**](/en/ch28-memory-system/28.3-hybrid-search.md)
* [**28.4 Advanced Memory Features**](/en/ch28-memory-system/28.4-advanced-memory-features.md)
* 🔬 [**28.5 Source Deep Dive: Files as the Source of Truth, and Hybrid Retrieval**](/en/ch28-memory-system/28.5-source-deep-dive-files-as-truth-and-hybrid-search.md)
  * Four layers, in which the vector index is the only binary state — and it can be rebuilt at any time
  * **Retrieval is the model's behavior, not the framework's** (coexisting with LanceDB's opposite extreme)
  * LanceDB auto-capture only handles user messages: "avoid the model polluting itself with its own output"
  * The flush safety notice cannot be overridden by the user: **you may change the tone, not the boundary**

### Chapter 29: Skill System

* [**29.1 Skill Platform Design**](/en/ch29-skill-system/29.1-skill-platform-design.md)
* [**29.2 Skill Structure**](/en/ch29-skill-system/29.2-skill-structure.md)
* [**29.3 Skill Installation and Management**](/en/ch29-skill-system/29.3-skill-installation-and-management.md)
* [**29.4 ClawHub Skill Registry**](/en/ch29-skill-system/29.4-clawhub-skill-registry.md)
* 🔬 [**29.5 Source Deep Dive: Progressive Disclosure and Three-Layer Loading**](/en/ch29-skill-system/29.5-source-deep-dive-progressive-disclosure.md)
  * Pre-filtering by `requires`: **the model never recommends a plan that can't run**
  * Four disciplines of progressive disclosure, taking context cost from O(N) to O(1)
  * The trust boundary: `SKILL.md` goes straight into the prompt, and reading it yourself is the only defense

### Chapter 30: Hook System

* [**30.1 Internal Hooks**](/en/ch30-hook-system/30.1-internal-hooks.md)
* [**30.2 Plugin Hooks**](/en/ch30-hook-system/30.2-plugin-hooks.md)
* 🔬 [**30.3 Source Deep Dive: Two Event Systems and the Hook Package Convention**](/en/ch30-hook-system/30.3-source-deep-dive-two-event-systems.md)
  * How the `session-memory` hook achieves "reset the session without losing memory"
  * The exception to fire-and-forget: `agent:bootstrap` can modify the bootstrap file list
  * The Gmail watcher: a representative entry point from the outside world into an agent turn

***

## Part VII: Security, Configuration, and Infrastructure

### Chapter 31: Configuration System

* [**31.1 Configuration Loading and Parsing**](/en/ch31-configuration-system/31.1-configuration-loading-and-parsing.md)
* [**31.2 Configuration Type System Deep Dive**](/en/ch31-configuration-system/31.2-configuration-type-system-deep-dive.md)
* [**31.3 Configuration Hot Reload**](/en/ch31-configuration-system/31.3-configuration-hot-reload.md)
* [**31.4 Legacy Configuration Migration**](/en/ch31-configuration-system/31.4-legacy-configuration-migration.md)
* [**31.5 Environment Variables**](/en/ch31-configuration-system/31.5-environment-variables.md)
* 🔬 [**31.6 Source Deep Dive: The Five-Stage Read Pipeline and Write-Back Restoration**](/en/ch31-configuration-system/31.6-source-deep-dive-read-pipeline-and-write-back.md)
  * Failing closed is the security floor: **never silently fall back to a permissive default**
  * Legacy detection must run before Zod — error-message quality depends on which layer intercepts
  * Three write-back techniques: merge-patch projection + env-ref restoration + a prototype-key blocklist
  * One counterintuitive hazard: **a read operation writes a file**

### Chapter 32: Security Model

* [**32.1 Security Design Principles**](/en/ch32-security-model/32.1-security-design-principles.md)
* [**32.2 DM Pairing System**](/en/ch32-security-model/32.2-dm-pairing-system.md)
* [**32.3 Sandbox Mechanism**](/en/ch32-security-model/32.3-sandbox-mechanism.md)
* [**32.4 Security Auditing**](/en/ch32-security-model/32.4-security-auditing.md)
* [**32.5 SOUL Security: The Trust Position of Bootstrap Files**](/en/ch32-security-model/32.5-soul-security.md) — includes the `soul-evil` removal case study
* 🔬 [**32.6 Source Deep Dive: Admission, Secrets, and Audit**](/en/ch32-security-model/32.6-source-deep-dive-admission-secrets-and-audit.md)
  * **Pairing is session admission, not permission grant** (group commands don't inherit DM pairing)
  * External content is delimited by a random 16-character id, with homoglyph normalization
  * Three secret layers: SecretRef → dual snapshots → redaction (with bounded regexes so it can't DoS itself)
  * **Audit severity varies with your actual exposure**; tools don't pretend to be boundaries

### Chapter 33: CLI Tools

* [**33.1 CLI Architecture**](/en/ch33-cli-tools/33.1-cli-architecture.md)
* [**33.2 Core Command Analysis**](/en/ch33-cli-tools/33.2-core-command-analysis.md)
* [**33.3 Chat Commands**](/en/ch33-cli-tools/33.3-chat-commands.md)
* 🔬 [**33.4 Source Deep Dive: Two Command Trees and Startup-Speed Paranoia**](/en/ch33-cli-tools/33.4-source-deep-dive-two-command-trees.md)
  * The chat command registry: one declaration driving five front ends, with a build-time self-check
  * Three layers of startup optimization (version fast-path / route-first / lazy registration placeholders)
  * config-guard's "fail closed + allowlist passthrough" avoids a repair deadlock
  * DI through narrow interfaces plus default parameters: **interfaces small enough to hand-write a test double**

### Chapter 34: Infrastructure

* [**34.1 Logging System**](/en/ch34-infrastructure/34.1-logging-system.md)
* [**34.2 Media Pipeline**](/en/ch34-infrastructure/34.2-media-pipeline.md)
* [**34.3 Link and Media Understanding**](/en/ch34-infrastructure/34.3-link-understanding-and-media-understanding.md)
* [**34.4 TTS Text-to-Speech**](/en/ch34-infrastructure/34.4-tts-text-to-speech.md)
* [**34.5 Polls System**](/en/ch34-infrastructure/34.5-polls-system.md)
* 🔬 [**34.6 Source Deep Dive: The Media Candidate Chain and the Vision Short-Circuit**](/en/ch34-infrastructure/34.6-source-deep-dive-media-candidate-chain-and-vision-skip.md)
  * **Probe order instead of a config switch** — demoting a configuration problem into a performance problem
  * The vision short-circuit: if the main model can see the image, don't paraphrase it second-hand
  * Link understanding filters SSRF at the extraction stage — moving the defense forward to the data entry point

***

## Part VIII: Client Apps and Web UI

### Chapter 35: Web Console UI

* [**35.1 UI Technology Selection**](/en/ch35-web-console-ui/35.1-ui-technology-selection.md)
* [**35.2 Console UI Architecture**](/en/ch35-web-console-ui/35.2-console-ui-architecture.md)
* [**35.3 WebChat Implementation**](/en/ch35-web-console-ui/35.3-webchat-implementation.md)

### Chapter 36: Native Client Apps

* [**36.1 macOS App**](/en/ch36-native-client-apps/36.1-macos-app.md)
* [**36.2 iOS Node App**](/en/ch36-native-client-apps/36.2-ios-node-app.md)
* [**36.3 Android Node App**](/en/ch36-native-client-apps/36.3-android-node-app.md)
* [**36.4 Shared Components**](/en/ch36-native-client-apps/36.4-shared-components.md)

***

## Part IX: Deployment and Operations

### Chapter 37: Deployment

* [**37.1 Local Deployment**](/en/ch37-deployment/37.1-local-deployment.md)
* [**37.2 Docker Deployment**](/en/ch37-deployment/37.2-docker-deployment.md)
* [**37.3 Remote Access**](/en/ch37-deployment/37.3-remote-access.md)
* [**37.4 Nix Declarative Deployment**](/en/ch37-deployment/37.4-nix-declarative-deployment.md)
* [**37.5 VPS Deployment**](/en/ch37-deployment/37.5-vps-deployment.md)

> Source-level deep dive on cross-platform service installation: [**Appendix F**](/en/appendices/appendix-f-daemon-and-node-host-deep-dive.md).

### Chapter 38: Monitoring and Troubleshooting

* [**38.1 Health Checks**](/en/ch38-monitoring-and-troubleshooting/38.1-health-checks.md)
* [**38.2 Presence Tracking**](/en/ch38-monitoring-and-troubleshooting/38.2-presence-tracking.md)
* [**38.3 Usage Tracking**](/en/ch38-monitoring-and-troubleshooting/38.3-usage-tracking.md)
* [**38.4 Troubleshooting**](/en/ch38-monitoring-and-troubleshooting/38.4-troubleshooting.md)

***

## Part X: Advanced Topics and Practice

### Chapter 39: Multi-Agent Architecture

* [**39.1 Multi-Agent Design**](/en/ch39-multi-agent-architecture/39.1-multi-agent-design.md)
* [**39.2 Sub-Agents**](/en/ch39-multi-agent-architecture/39.2-sub-agents.md)
* [**39.3 Multi-Agent Sandbox Tools**](/en/ch39-multi-agent-architecture/39.3-multi-agent-sandbox-tools.md)
* 🔬 [**39.4 Source Deep Dive: Subagent Spawning and Cross-Agent Communication**](/en/ch39-multi-agent-architecture/39.4-source-deep-dive-subagent-spawn-and-communication.md)
  * Depth limits against fork bombs; the system prompt explicitly forbids polling
  * Idempotency key = subsession key + run id; late events are swallowed silently with `NO_REPLY`
  * **A sandboxed session may not spawn ACP** — better to say plainly there's no protection than to offer a fake switch

### Chapter 40: ACP (Agent Communication Protocol)

* [**40.1 ACP Protocol Overview**](/en/ch40-acp/40.1-acp-protocol-overview.md)
* [**40.2 ACP Session Management and Runtime**](/en/ch40-acp/40.2-acp-session-management-and-runtime.md)
* [**40.3 ACP Control Plane and Integration Patterns**](/en/ch40-acp/40.3-acp-control-plane-and-integration-patterns.md)
* 🔬 [**40.4 Source Deep Dive: Two ACP Subsystems Pointing Opposite Ways**](/en/ch40-acp/40.4-source-deep-dive-two-opposite-acp-subsystems.md)
  * The split between the ACP bridge (being called) and the ACP Runtime (calling)
  * `runId` doing three jobs at once; **errors map to `end_turn`, not a refusal**
  * A deterministic `sessionKey` instead of a persisted mapping table; "configuration is the desired state"

### Chapter 41: TUI (Terminal User Interface)

* [**41.1 TUI Architecture**](/en/ch41-tui/41.1-tui-architecture.md)
* [**41.2 TUI Interaction Mechanisms**](/en/ch41-tui/41.2-tui-interaction-mechanisms.md)
* [**41.3 TUI Advanced Features**](/en/ch41-tui/41.3-tui-advanced-features.md)

### Chapter 42: Hands-On Project: Build Your Own AI Assistant

* [**42.1 Project Planning**](/en/ch42-hands-on-project/42.1-project-planning.md)
* [**42.2 Core Feature Implementation**](/en/ch42-hands-on-project/42.2-core-feature-implementation.md)
* [**42.3 Channel Integration**](/en/ch42-hands-on-project/42.3-channel-integration.md)
* [**42.4 Advanced Features**](/en/ch42-hands-on-project/42.4-advanced-features.md)
* [**42.5 Deployment and Launch**](/en/ch42-hands-on-project/42.5-deployment-and-launch.md)

***

## Part XI: Source Reading and Design Insight

> The first forty-two chapters took OpenClaw apart like a machine, each answering *how is this piece implemented?*
>
> This part changes the lens: put the magnifying glass down, step back, and extract **the shapes that recur across the codebase**, **the patterns worth stealing**, and **the risks you need to know about**.
>
> Specific line numbers expire. Shapes don't.

### Chapter 43: Engineering Panorama

* [**43.1 Positioning and Evolution**](/en/ch43-engineering-panorama/43.1-positioning-and-evolution.md)
  * Four engineering tracks and four renames; **the heart is borrowed** (pi-mono is embedded, not written)
  * The agent's personality is a set of git-manageable Markdown files
* [**43.2 Scale and Subsystem Map**](/en/ch43-engineering-panorama/43.2-scale-and-subsystem-map.md)
  * Six verified numbers: 507,227 lines, 1,935 tests, 18,005 commits, 40 extensions, 52 skills
  * A reverse index from code to chapter; three counterintuitive facts
* [**43.3 AI-Collaborative Development**](/en/ch43-engineering-panorama/43.3-ai-collaborative-development.md)
  * `AGENTS.md` is not a contributing guide — it's a case book of agent mistakes
  * Three rule categories: AI code pathologies / multi-agent safety / merge gates
* [**43.4 Source Reading Paths**](/en/ch43-engineering-panorama/43.4-source-reading-paths.md)
  * Four paths; **use the 1,935 test filenames as the spec**
  * Anti-recommendation: don't start with the 2,096-line assembly file

### Chapter 44: Design Themes Running Through the Codebase

* [**44.1 A Converged Network Surface, and "Embed, Don't Fork"**](/en/ch44-design-themes/44.1-converged-surface-and-embed-not-fork.md)
  * Theme 1: one port, one protocol, one admission path (cost: complexity concentrated, not eliminated)
  * Theme 2: **pay the architecture tax rather than carry the fork debt** — decided by upstream change frequency
* [**44.2 Degradation Chains Everywhere**](/en/ch44-design-themes/44.2-degradation-chains-everywhere.md)
  * Theme 3: the same pattern appears **independently** in six modules — consensus, not reuse
  * Four points for getting it right; **copying this pattern requires copying the observability**
* [**44.3 Files as the Source of Truth, Declaration Tables as the Single Truth**](/en/ch44-design-themes/44.3-files-as-truth-tables-as-truth.md)
  * Theme 4: the vector index is the only binary state, defined as a rebuildable derivative
  * Theme 5: knowledge needing multi-place consistency collapses into a table + generation/validation
* [**44.4 A Trust Model Honest Enough to Be Case Law**](/en/ch44-design-themes/44.4-a-trust-model-written-as-case-law.md)
  * Theme 6: writing "what does not count as a vulnerability" as citable precedent
  * Much of it exists to handle **AI-generated vulnerability reports**
* [**44.5 Conversation Experience as a First-Class Engineering Object**](/en/ch44-design-themes/44.5-conversation-experience-as-first-class.md)
  * Theme 7: three queueing semantics for three real mental models
  * Two-tier lanes solve three constraints in \~300 lines of Promises; the heartbeat's traceless design

### Chapter 45: Risks and Transferable Lessons

* [**45.1 Ten Engineering Patterns Worth Stealing**](/en/ch45-risks-and-lessons/45.1-ten-patterns-worth-stealing.md)
  * Selection criterion: **they hold up outside OpenClaw's context**
  * With a "pick by system characteristics" mapping table
* [**45.2 Risk and Improvement List**](/en/ch45-risks-and-lessons/45.2-risk-and-improvement-list.md)
  * One verified defect (`systemd.ts:484/528` — **uninstalling the node stops the gateway**)
  * Three architecture-level risks + seven correctness/maintainability risks
  * **Every risk is the invoice for one of Chapter 44's advantages**
* [**45.3 A Contrasting Route**](/en/ch45-risks-and-lessons/45.3-a-contrasting-route.md)
  * Twelve decision points, nearly all opposite
  * Three key contrasts: who errors teach / where trust collapses / the cost curve of channel abstraction
* [**45.4 Epilogue: From Tool to Infrastructure**](/en/ch45-risks-and-lessons/45.4-epilogue-from-tool-to-infrastructure.md)
  * A **working** agent takes \~200 lines. What are the other 499,800 doing?
  * Three principles to take away

***

## Appendices

### [Appendix A: OpenClaw Configuration Reference](/en/appendices/appendix-a-openclaw-configuration-reference.md)

Complete JSON5 config example · full config key reference

### [Appendix B: Gateway WebSocket Protocol Reference](/en/appendices/appendix-b-gateway-websocket-protocol-reference.md)

Three frame types · the `connect` handshake (protocol version 3) · all 110 methods · 19 event types · four auth layers

### [Appendix C: Tool Definition Reference](/en/appendices/appendix-c-tool-definition-reference.md)

Every built-in tool, its schema and purpose · how the seven-layer policy pipeline trims the set

### [Appendix D: Source Code Navigation Map](/en/appendices/appendix-d-source-code-navigation-map.md)

Dependency map · message sequence diagram · directory-to-chapter reference · three verification techniques

### [Appendix E: Glossary](/en/appendices/appendix-e-glossary.md)

Every technical term in this book, with explanation

### 🔬 [Appendix F: Daemon and Device Node Deep Dive](/en/appendices/appendix-f-daemon-and-node-host-deep-dive.md)

* Per-platform quirk patches — launchd's persisted disabled state, systemd's dual-scope bus fallback, schtasks' localized-text trap
* The service file as the source of configuration truth (`readCommand` reverse parsing)
* **One verified defect**: systemd install/uninstall ignores the unit-name override
* node-host exec security: a pure-function policy core plus four runtime re-verifications

### 🔬 [Appendix G: Gateway Network Model and Protocol Reference](/en/appendices/appendix-g-gateway-network-model-reference.md)

* The six things people most often get wrong (including the "two pairing systems" warning)
* Four-level transport fallback; three Tailscale modes; credential precedence rules
* OpenAI-compatible API limits, and **SSRF defenses are orthogonal to the allowlist**
* Port and config key quick reference

***

## Scope

| Part                                           | Chapters                       | Estimated words |
| ---------------------------------------------- | ------------------------------ | --------------- |
| Part I: Getting Started                        | 10                             | \~80,000        |
| Part II: Gateway Control Plane                 | 4                              | \~44,000        |
| Part III: AI Agent Runtime                     | 4                              | \~44,000        |
| Part IV: Multi-Channel Messaging               | 3                              | \~33,000        |
| Part V: Tool System and Automation             | 6                              | \~40,000        |
| Part VI: Memory, Skills, Ecosystem             | 3                              | \~25,000        |
| Part VII: Security, Config, Infrastructure     | 4                              | \~36,000        |
| Part VIII: Client Apps and Web UI              | 2                              | \~6,000         |
| Part IX: Deployment and Operations             | 2                              | \~6,000         |
| Part X: Advanced Topics and Practice           | 4                              | \~20,000        |
| **Part XI: Source Reading and Design Insight** | **3**                          | **\~24,000**    |
| Appendices                                     | 7                              | \~14,000        |
| **Total**                                      | **45 chapters + 7 appendices** | **\~372,000**   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://www.openclawbook.xyz/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.