> 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

[中文版本](https://www.openclawbook.xyz/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](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch01-understanding-openclaw/1.1-what-is-openclaw.md)
* [**1.2 Core Architecture Overview**](https://www.openclawbook.xyz/en/ch01-understanding-openclaw/1.2-core-architecture-overview.md)
* [**1.3 Technology Stack Overview**](https://www.openclawbook.xyz/en/ch01-understanding-openclaw/1.3-technology-stack-overview.md)
* [**1.4 Project Directory Structure**](https://www.openclawbook.xyz/en/ch01-understanding-openclaw/1.4-project-directory-structure.md)

### Chapter 2: Installation and Quick Start

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

### Chapter 3: Connecting Channels

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

### Chapter 4: Conversation and Tools

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

### Chapter 5: Scheduling and Automation

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

### Chapter 6: The Skills Ecosystem

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

### Chapter 7: Model Configuration and Optimization

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

### Chapter 8: Regional Platforms and Deployment

* [**8.1 Feishu, DingTalk, and WeCom**](https://www.openclawbook.xyz/en/ch08-regional-platforms-and-deployment/8.1-feishu-dingtalk-and-wecom.md)
* [**8.2 Cloud Deployment in Practice**](https://www.openclawbook.xyz/en/ch08-regional-platforms-and-deployment/8.2-cloud-deployment-in-practice.md)
* [**8.3 Docker Deployment and Production Configuration**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch09-multi-agent-in-practice/9.1-multi-agent-configuration-and-routing.md)
* [**9.2 Subagents and Cross-Agent Communication**](https://www.openclawbook.xyz/en/ch09-multi-agent-in-practice/9.2-subagents-and-cross-agent-communication.md)
* [**9.3 Team Collaboration and Case Studies**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch10-advanced-techniques/10.1-memory-and-knowledge-management.md)
* [**10.2 Security Hardening and Permission Management**](https://www.openclawbook.xyz/en/ch10-advanced-techniques/10.2-security-hardening-and-permissions.md)
* [**10.3 Customization and Common Questions**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch11-gateway-server-architecture/11.1-gateway-role-and-design-goals.md)
* [**11.2 Server Startup Flow Source Analysis**](https://www.openclawbook.xyz/en/ch11-gateway-server-architecture/11.2-server-startup-flow-source-analysis.md)
* [**11.3 WebSocket Server Implementation**](https://www.openclawbook.xyz/en/ch11-gateway-server-architecture/11.3-websocket-server-implementation.md)
* [**11.4 HTTP Layer**](https://www.openclawbook.xyz/en/ch11-gateway-server-architecture/11.4-http-layer.md)
* 🔬 [**11.5 Source Deep Dive: The Assembly Site and the Method Routing Table**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch12-gateway-protocol-and-type-system/12.1-protocol-design-philosophy.md)
* [**12.2 TypeBox Type Schema**](https://www.openclawbook.xyz/en/ch12-gateway-protocol-and-type-system/12.2-typebox-type-schema.md)
* [**12.3 Core Methods and Events**](https://www.openclawbook.xyz/en/ch12-gateway-protocol-and-type-system/12.3-core-methods-and-events.md)
* [**12.4 Authentication and Authorization**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch13-session-management/13.1-session-model-design.md)
* [**13.2 Session Routing Source Analysis**](https://www.openclawbook.xyz/en/ch13-session-management/13.2-session-routing-source-analysis.md)
* [**13.3 Session Lifecycle**](https://www.openclawbook.xyz/en/ch13-session-management/13.3-session-lifecycle.md)
* [**13.4 Session Pruning**](https://www.openclawbook.xyz/en/ch13-session-management/13.4-session-pruning.md)
* [**13.5 Inter-Session Communication**](https://www.openclawbook.xyz/en/ch13-session-management/13.5-inter-session-communication.md)
* 🔬 [**13.6 Source Deep Dive: Two-Tier Lanes and Three Queue Semantics**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch14-channel-routing-and-message-dispatch/14.1-channel-registry.md)
* [**14.2 Inbound Message Processing Pipeline**](https://www.openclawbook.xyz/en/ch14-channel-routing-and-message-dispatch/14.2-inbound-message-processing-pipeline.md)
* [**14.3 Outbound Message Processing**](https://www.openclawbook.xyz/en/ch14-channel-routing-and-message-dispatch/14.3-outbound-message-processing.md)
* [**14.4 Multi-Agent Routing**](https://www.openclawbook.xyz/en/ch14-channel-routing-and-message-dispatch/14.4-multi-agent-routing.md)
* 🔬 [**14.5 Source Deep Dive: Seven Gates on the Inbound Pipeline**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch15-piagent-runtime-core/15.1-what-is-piagent.md)
* [**15.2 Agent Loop End-to-End Analysis**](https://www.openclawbook.xyz/en/ch15-piagent-runtime-core/15.2-agent-loop-end-to-end-analysis.md)
* [**15.3 Queue and Concurrency Control**](https://www.openclawbook.xyz/en/ch15-piagent-runtime-core/15.3-queue-and-concurrency-control.md)
* [**15.4 Timeout and Abort Mechanisms**](https://www.openclawbook.xyz/en/ch15-piagent-runtime-core/15.4-timeout-and-abort-mechanisms.md)
* 🔬 [**15.5 Source Deep Dive: The Full Journey of a Run**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch16-model-providers-and-failover/16.1-model-selection-mechanism.md)
* [**16.2 AuthProfile and Credential Management**](https://www.openclawbook.xyz/en/ch16-model-providers-and-failover/16.2-authprofile-and-credential-management.md)
* [**16.3 Model Catalog and Configuration**](https://www.openclawbook.xyz/en/ch16-model-providers-and-failover/16.3-model-catalog-and-configuration.md)
* [**16.4 Failover Error Handling**](https://www.openclawbook.xyz/en/ch16-model-providers-and-failover/16.4-failover-error-handling.md)
* 🔬 [**16.5 Source Deep Dive: Auth Profile Rotation, Cooldown, and Degradation**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch17-system-prompts-and-context-assembly/17.1-building-system-prompts.md)
* [**17.2 Workspace and Context File Injection**](https://www.openclawbook.xyz/en/ch17-system-prompts-and-context-assembly/17.2-workspace-and-context-file-injection.md)
* [**17.3 Identity System**](https://www.openclawbook.xyz/en/ch17-system-prompts-and-context-assembly/17.3-identity-system.md)
* [**17.4 Context Compaction**](https://www.openclawbook.xyz/en/ch17-system-prompts-and-context-assembly/17.4-context-compaction.md)
* [**17.5 The Context Engine Plugin System**](https://www.openclawbook.xyz/en/ch17-system-prompts-and-context-assembly/17.5-context-engine-plugin-system.md)
* 🔬 [**17.6 Source Deep Dive: Four Lines of Context Defense**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch18-streaming-and-block-replies/18.1-streaming-architecture.md)
* [**18.2 Block Streaming**](https://www.openclawbook.xyz/en/ch18-streaming-and-block-replies/18.2-block-streaming.md)
* [**18.3 Coalescing and Humanized Pacing**](https://www.openclawbook.xyz/en/ch18-streaming-and-block-replies/18.3-coalescing-and-humanized-pacing.md)
* [**18.4 Telegram Draft Streaming**](https://www.openclawbook.xyz/en/ch18-streaming-and-block-replies/18.4-telegram-draft-streaming.md)
* [**18.5 Reply Shaping and Suppression**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch19-channel-adapter-abstraction/19.1-channel-adapter-design-pattern.md)
* [**19.2 Inbound Message Normalization**](https://www.openclawbook.xyz/en/ch19-channel-adapter-abstraction/19.2-inbound-message-normalization.md)
* [**19.3 Outbound Message Adaptation**](https://www.openclawbook.xyz/en/ch19-channel-adapter-abstraction/19.3-outbound-message-adaptation.md)
* 🔬 [**19.4 Source Deep Dive: The ChannelPlugin Contract and Dual Registries**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch20-core-channel-implementations/20.1-whatsapp-channel.md)
* [**20.2 Telegram Channel**](https://www.openclawbook.xyz/en/ch20-core-channel-implementations/20.2-telegram-channel.md)
* [**20.3 Discord Channel**](https://www.openclawbook.xyz/en/ch20-core-channel-implementations/20.3-discord-channel.md)
* [**20.4 Slack Channel**](https://www.openclawbook.xyz/en/ch20-core-channel-implementations/20.4-slack-channel.md)
* [**20.5 Other Core Channels**](https://www.openclawbook.xyz/en/ch20-core-channel-implementations/20.5-other-core-channels.md)
* 🔬 [**20.6 Source Deep Dive: Three Long-Lived Connections, Two Streaming Modes**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch21-channel-extension-mechanism/21.1-extension-architecture-design.md)
* [**21.2 Extension API Surface**](https://www.openclawbook.xyz/en/ch21-channel-extension-mechanism/21.2-extension-api-surface.md)
* [**21.3 Representative Extension Implementations**](https://www.openclawbook.xyz/en/ch21-channel-extension-mechanism/21.3-representative-extension-implementations.md)
* [**21.4 Developing Custom Extensions**](https://www.openclawbook.xyz/en/ch21-channel-extension-mechanism/21.4-developing-custom-extensions.md)
* 🔬 [**21.5 Source Deep Dive: The Loader, jiti, and the SDK Surface**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch22-tool-system-overview/22.1-tool-system-architecture.md)
* [**22.2 Tool Registration and Policy**](https://www.openclawbook.xyz/en/ch22-tool-system-overview/22.2-tool-registration-and-policy.md)
* [**22.3 Tool Execution and Result Handling**](https://www.openclawbook.xyz/en/ch22-tool-system-overview/22.3-tool-execution-and-result-handling.md)
* [**22.4 Execution Approval Mechanism**](https://www.openclawbook.xyz/en/ch22-tool-system-overview/22.4-execution-approval-mechanism.md)
* 🔬 [**22.5 Source Deep Dive: The Tool Assembly Pipeline and the Sandbox**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch23-bash-tools-and-process-management/23.1-bash-execution-engine.md)
* [**23.2 Process Management**](https://www.openclawbook.xyz/en/ch23-bash-tools-and-process-management/23.2-process-management.md)
* [**23.3 Shell Tools and Shared Infrastructure**](https://www.openclawbook.xyz/en/ch23-bash-tools-and-process-management/23.3-shell-tools-and-shared-infrastructure.md)

### Chapter 24: Browser Control

* [**24.1 Browser Architecture Overview**](https://www.openclawbook.xyz/en/ch24-browser-control/24.1-browser-architecture-overview.md)
* [**24.2 CDP Layer Implementation**](https://www.openclawbook.xyz/en/ch24-browser-control/24.2-cdp-layer-implementation.md)
* [**24.3 Playwright Layer Implementation**](https://www.openclawbook.xyz/en/ch24-browser-control/24.3-playwright-layer-implementation.md)
* [**24.4 Browser Server**](https://www.openclawbook.xyz/en/ch24-browser-control/24.4-browser-server.md)
* 🔬 [**24.5 Source Deep Dive: Four Browser Sources and Three Security Gates**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch25-canvas-and-a2ui/25.1-canvas-concepts.md)
* [**25.2 Canvas Host Implementation**](https://www.openclawbook.xyz/en/ch25-canvas-and-a2ui/25.2-canvas-host-implementation.md)
* [**25.3 Canvas Tools**](https://www.openclawbook.xyz/en/ch25-canvas-and-a2ui/25.3-canvas-tools.md)

### Chapter 26: Cron Scheduling and Automation

* [**26.1 Cron System Design**](https://www.openclawbook.xyz/en/ch26-cron-scheduling-and-automation/26.1-cron-system-design.md)
* [**26.2 Cron Job Execution**](https://www.openclawbook.xyz/en/ch26-cron-scheduling-and-automation/26.2-cron-job-execution.md)
* [**26.3 Webhooks and Gmail Pub/Sub**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch27-node-system/27.1-node-concepts.md)
* [**27.2 Node Registration and Discovery**](https://www.openclawbook.xyz/en/ch27-node-system/27.2-node-registration-and-discovery.md)
* [**27.3 Node Host Implementation**](https://www.openclawbook.xyz/en/ch27-node-system/27.3-node-host-implementation.md)
* 🔬 [**27.4 Source Deep Dive: Reverse RPC and the Wake Mechanism**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch28-memory-system/28.1-memory-model-design.md)
* [**28.2 Vector Memory Search**](https://www.openclawbook.xyz/en/ch28-memory-system/28.2-vector-memory-search.md)
* [**28.3 Hybrid Search**](https://www.openclawbook.xyz/en/ch28-memory-system/28.3-hybrid-search.md)
* [**28.4 Advanced Memory Features**](https://www.openclawbook.xyz/en/ch28-memory-system/28.4-advanced-memory-features.md)
* 🔬 [**28.5 Source Deep Dive: Files as the Source of Truth, and Hybrid Retrieval**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch29-skill-system/29.1-skill-platform-design.md)
* [**29.2 Skill Structure**](https://www.openclawbook.xyz/en/ch29-skill-system/29.2-skill-structure.md)
* [**29.3 Skill Installation and Management**](https://www.openclawbook.xyz/en/ch29-skill-system/29.3-skill-installation-and-management.md)
* [**29.4 ClawHub Skill Registry**](https://www.openclawbook.xyz/en/ch29-skill-system/29.4-clawhub-skill-registry.md)
* 🔬 [**29.5 Source Deep Dive: Progressive Disclosure and Three-Layer Loading**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch30-hook-system/30.1-internal-hooks.md)
* [**30.2 Plugin Hooks**](https://www.openclawbook.xyz/en/ch30-hook-system/30.2-plugin-hooks.md)
* 🔬 [**30.3 Source Deep Dive: Two Event Systems and the Hook Package Convention**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch31-configuration-system/31.1-configuration-loading-and-parsing.md)
* [**31.2 Configuration Type System Deep Dive**](https://www.openclawbook.xyz/en/ch31-configuration-system/31.2-configuration-type-system-deep-dive.md)
* [**31.3 Configuration Hot Reload**](https://www.openclawbook.xyz/en/ch31-configuration-system/31.3-configuration-hot-reload.md)
* [**31.4 Legacy Configuration Migration**](https://www.openclawbook.xyz/en/ch31-configuration-system/31.4-legacy-configuration-migration.md)
* [**31.5 Environment Variables**](https://www.openclawbook.xyz/en/ch31-configuration-system/31.5-environment-variables.md)
* 🔬 [**31.6 Source Deep Dive: The Five-Stage Read Pipeline and Write-Back Restoration**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch32-security-model/32.1-security-design-principles.md)
* [**32.2 DM Pairing System**](https://www.openclawbook.xyz/en/ch32-security-model/32.2-dm-pairing-system.md)
* [**32.3 Sandbox Mechanism**](https://www.openclawbook.xyz/en/ch32-security-model/32.3-sandbox-mechanism.md)
* [**32.4 Security Auditing**](https://www.openclawbook.xyz/en/ch32-security-model/32.4-security-auditing.md)
* [**32.5 SOUL Security: The Trust Position of Bootstrap Files**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch33-cli-tools/33.1-cli-architecture.md)
* [**33.2 Core Command Analysis**](https://www.openclawbook.xyz/en/ch33-cli-tools/33.2-core-command-analysis.md)
* [**33.3 Chat Commands**](https://www.openclawbook.xyz/en/ch33-cli-tools/33.3-chat-commands.md)
* 🔬 [**33.4 Source Deep Dive: Two Command Trees and Startup-Speed Paranoia**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch34-infrastructure/34.1-logging-system.md)
* [**34.2 Media Pipeline**](https://www.openclawbook.xyz/en/ch34-infrastructure/34.2-media-pipeline.md)
* [**34.3 Link and Media Understanding**](https://www.openclawbook.xyz/en/ch34-infrastructure/34.3-link-understanding-and-media-understanding.md)
* [**34.4 TTS Text-to-Speech**](https://www.openclawbook.xyz/en/ch34-infrastructure/34.4-tts-text-to-speech.md)
* [**34.5 Polls System**](https://www.openclawbook.xyz/en/ch34-infrastructure/34.5-polls-system.md)
* 🔬 [**34.6 Source Deep Dive: The Media Candidate Chain and the Vision Short-Circuit**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch35-web-console-ui/35.1-ui-technology-selection.md)
* [**35.2 Console UI Architecture**](https://www.openclawbook.xyz/en/ch35-web-console-ui/35.2-console-ui-architecture.md)
* [**35.3 WebChat Implementation**](https://www.openclawbook.xyz/en/ch35-web-console-ui/35.3-webchat-implementation.md)

### Chapter 36: Native Client Apps

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

***

## Part IX: Deployment and Operations

### Chapter 37: Deployment

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

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

### Chapter 38: Monitoring and Troubleshooting

* [**38.1 Health Checks**](https://www.openclawbook.xyz/en/ch38-monitoring-and-troubleshooting/38.1-health-checks.md)
* [**38.2 Presence Tracking**](https://www.openclawbook.xyz/en/ch38-monitoring-and-troubleshooting/38.2-presence-tracking.md)
* [**38.3 Usage Tracking**](https://www.openclawbook.xyz/en/ch38-monitoring-and-troubleshooting/38.3-usage-tracking.md)
* [**38.4 Troubleshooting**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch39-multi-agent-architecture/39.1-multi-agent-design.md)
* [**39.2 Sub-Agents**](https://www.openclawbook.xyz/en/ch39-multi-agent-architecture/39.2-sub-agents.md)
* [**39.3 Multi-Agent Sandbox Tools**](https://www.openclawbook.xyz/en/ch39-multi-agent-architecture/39.3-multi-agent-sandbox-tools.md)
* 🔬 [**39.4 Source Deep Dive: Subagent Spawning and Cross-Agent Communication**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch40-acp/40.1-acp-protocol-overview.md)
* [**40.2 ACP Session Management and Runtime**](https://www.openclawbook.xyz/en/ch40-acp/40.2-acp-session-management-and-runtime.md)
* [**40.3 ACP Control Plane and Integration Patterns**](https://www.openclawbook.xyz/en/ch40-acp/40.3-acp-control-plane-and-integration-patterns.md)
* 🔬 [**40.4 Source Deep Dive: Two ACP Subsystems Pointing Opposite Ways**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/en/ch41-tui/41.1-tui-architecture.md)
* [**41.2 TUI Interaction Mechanisms**](https://www.openclawbook.xyz/en/ch41-tui/41.2-tui-interaction-mechanisms.md)
* [**41.3 TUI Advanced Features**](https://www.openclawbook.xyz/en/ch41-tui/41.3-tui-advanced-features.md)

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

* [**42.1 Project Planning**](https://www.openclawbook.xyz/en/ch42-hands-on-project/42.1-project-planning.md)
* [**42.2 Core Feature Implementation**](https://www.openclawbook.xyz/en/ch42-hands-on-project/42.2-core-feature-implementation.md)
* [**42.3 Channel Integration**](https://www.openclawbook.xyz/en/ch42-hands-on-project/42.3-channel-integration.md)
* [**42.4 Advanced Features**](https://www.openclawbook.xyz/en/ch42-hands-on-project/42.4-advanced-features.md)
* [**42.5 Deployment and Launch**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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"**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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**](https://www.openclawbook.xyz/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](https://www.openclawbook.xyz/en/appendices/appendix-a-openclaw-configuration-reference.md)

Complete JSON5 config example · full config key reference

### [Appendix B: Gateway WebSocket Protocol Reference](https://www.openclawbook.xyz/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](https://www.openclawbook.xyz/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](https://www.openclawbook.xyz/en/appendices/appendix-d-source-code-navigation-map.md)

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

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

Every technical term in this book, with explanation

### 🔬 [Appendix F: Daemon and Device Node Deep Dive](https://www.openclawbook.xyz/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](https://www.openclawbook.xyz/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**   |
