> 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-zh.md).

# 《深入 OpenClaw》—— 目录与纲要

> **生成模型**：Claude Opus 5 (claude-opus-5) / Claude Opus 4.6（早期章节） **工具**：Claude Code + OpenClaw + OpenCode **最近更新**：2026-08-02 **源码基线**：`v2026.3.9`（`v2026.3.8-170-g665f67726`） **GitHub**：<https://github.com/0xtresser/OpenClaw-Book>

***

## 语言

[English](/readme.md)

***

## 本书的三个层次

本书按「由浅入深」组织，但你不必按顺序读。三个层次各自成立：

| 层次     | 对应部分              | 读它是为了              | 需要读源码吗  |
| ------ | ----------------- | ------------------ | ------- |
| **用法** | 第一部分（第 1–10 章）    | 把 OpenClaw 装起来、用起来 | 不需要     |
| **实现** | 第二～十部分（第 11–42 章） | 搞懂每个子系统是怎么实现的      | 需要      |
| **洞察** | 第十一部分（第 43–45 章）  | 提炼可迁移的设计经验与风险判断    | 读完实现层更佳 |

从第 11 章起，多数章节末尾有一节 **「源码深读」**。它比正文更贴近源码、信息密度更高，逐行追踪真实实现与它背后的 issue。

> **正文是理解结构，深读是理解取舍。** 只想搞清楚"这块是干什么的"，读正文即可；要动手改它、或在自己项目里重现它，读深读。

***

## [前言](/zh/00-qian-yan/qian-yan.md)

* 本书的写作动机与目标读者
* OpenClaw 项目概况：一个运行在自己设备上的个人 AI 助手
* 本书的组织结构与阅读建议
* 源码版本说明（基于 `v2026.3.9`）
* 预备知识：TypeScript 基础、Node.js 运行时概念、WebSocket 协议、基本的操作系统知识

***

## 第一部分：入门指南

> 从零开始，带你从安装到精通 OpenClaw。无需阅读源码，跟着做就能上手。

### 第 1 章 认识 OpenClaw

* [**1.1 什么是 OpenClaw：个人 AI 助手的全新范式**](/zh/di-01-zhang-ren-shi-openclaw/1.1-shen-me-shi-openclaw-ge-ren-ai-zhu-shou-de-quan-xin-fan-shi.md)
* [**1.2 核心架构一览**](/zh/di-01-zhang-ren-shi-openclaw/1.2-he-xin-jia-gou-yi-lan.md)
* [**1.3 技术栈与项目生态**](/zh/di-01-zhang-ren-shi-openclaw/1.3-ji-shu-zhan-yu-xiang-mu-sheng-tai.md)

### 第 2 章 安装与快速上手

* [**2.1 环境准备与安装**](/zh/di-02-zhang-an-zhuang-yu-kuai-su-shang-shou/2.1-huan-jing-zhun-bei-yu-an-zhuang.md)
* [**2.2 引导向导与首次配置**](/zh/di-02-zhang-an-zhuang-yu-kuai-su-shang-shou/2.2-yin-dao-xiang-dao-yu-shou-ci-pei-zhi.md)
* [**2.3 发送第一条消息**](/zh/di-02-zhang-an-zhuang-yu-kuai-su-shang-shou/2.3-fa-song-di-yi-tiao-xiao-xi.md)

### 第 3 章 通道连接实战

* **\[3.1 Telegram Bot 完整配置]\(ZH/第03章-通道连接实战/3.1-Telegram Bot完整配置.md)**
* [**3.2 Discord 与 Slack 接入**](/zh/di-03-zhang-tong-dao-lian-jie-shi-zhan/3.2discord-yu-slack-jie-ru.md)
* [**3.3 多通道策略与群组管理**](/zh/di-03-zhang-tong-dao-lian-jie-shi-zhan/3.3-duo-tong-dao-ce-le-yu-qun-zu-guan-li.md)

### 第 4 章 对话与工具使用

* [**4.1 对话技巧与命令**](/zh/di-04-zhang-dui-hua-yu-gong-ju-shi-yong/4.1-dui-hua-ji-qiao-yu-ming-ling.md)
* [**4.2 Bash 工具实战**](/zh/di-04-zhang-dui-hua-yu-gong-ju-shi-yong/4.2bash-gong-ju-shi-zhan.md)
* [**4.3 浏览器工具与 Canvas 画布**](/zh/di-04-zhang-dui-hua-yu-gong-ju-shi-yong/4.3-liu-lan-qi-gong-ju-yu-canvas-hua-bu.md)

### 第 5 章 定时任务与自动化

* [**5.1 Cron 定时任务入门**](/zh/di-05-zhang-ding-shi-ren-wu-yu-zi-dong-hua/5.1cron-ding-shi-ren-wu-ru-men.md)
* [**5.2 Webhook 与事件驱动**](/zh/di-05-zhang-ding-shi-ren-wu-yu-zi-dong-hua/5.2webhook-yu-shi-jian-qu-dong.md)
* [**5.3 自动化实战案例**](/zh/di-05-zhang-ding-shi-ren-wu-yu-zi-dong-hua/5.3-zi-dong-hua-shi-zhan-an-li.md)

### 第 6 章 Skills 生态

* [**6.1 Skills 概念与 ClawHub**](/zh/di-06-zhang-skills-sheng-tai/6.1skills-gai-nian-yu-clawhub.md)
* [**6.2 实战：常用 Skills 详解**](/zh/di-06-zhang-skills-sheng-tai/6.2-shi-zhan-chang-yong-skills-xiang-jie.md)
* [**6.3 编写自定义 Skill**](/zh/di-06-zhang-skills-sheng-tai/6.3-bian-xie-zi-ding-yi-skill.md)

### 第 7 章 模型配置与优化

* [**7.1 多提供者配置与 API 密钥**](/zh/di-07-zhang-mo-xing-pei-zhi-yu-you-hua/7.1-duo-ti-gong-zhe-pei-zhi-yu-api-mi-yao.md)
* [**7.2 回退链与性价比优化**](/zh/di-07-zhang-mo-xing-pei-zhi-yu-you-hua/7.2-hui-tui-lian-yu-xing-jia-bi-you-hua.md)
* [**7.3 中国 AI 模型接入**](/zh/di-07-zhang-mo-xing-pei-zhi-yu-you-hua/7.3-zhong-guo-ai-mo-xing-jie-ru.md)

### 第 8 章 中国平台与部署

* [**8.1 飞书 / 钉钉 / 企业微信集成**](/zh/di-08-zhang-zhong-guo-ping-tai-yu-bu-shu/8.1-fei-shu-ding-ding-qi-ye-wei-xin-ji-cheng.md)
* [**8.2 国内云部署实战**](/zh/di-08-zhang-zhong-guo-ping-tai-yu-bu-shu/8.2-guo-nei-yun-bu-shu-shi-zhan.md)
* [**8.3 Docker 部署与生产配置**](/zh/di-08-zhang-zhong-guo-ping-tai-yu-bu-shu/8.3docker-bu-shu-yu-sheng-chan-pei-zhi.md)

### 第 9 章 多 Agent 实战

* [**9.1 多 Agent 配置与路由**](/zh/di-09-zhang-duo-agent-shi-zhan/9.1-duo-agent-pei-zhi-yu-lu-you.md)
* [**9.2 子代理与跨 Agent 通信**](/zh/di-09-zhang-duo-agent-shi-zhan/9.2-zi-dai-li-yu-kua-agent-tong-xin.md)
* [**9.3 团队协作与实战案例**](/zh/di-09-zhang-duo-agent-shi-zhan/9.3-tuan-dui-xie-zuo-yu-shi-zhan-an-li.md)

### 第 10 章 高级技巧与最佳实践

* [**10.1 记忆系统与知识管理**](/zh/di-10-zhang-gao-ji-ji-qiao-yu-zui-jia-shi-jian/10.1-ji-yi-xi-tong-yu-zhi-shi-guan-li.md)
* [**10.2 安全加固与权限管理**](/zh/di-10-zhang-gao-ji-ji-qiao-yu-zui-jia-shi-jian/10.2-an-quan-jia-gu-yu-quan-xian-guan-li.md)
* [**10.3 定制与常见问题**](/zh/di-10-zhang-gao-ji-ji-qiao-yu-zui-jia-shi-jian/10.3-ding-zhi-yu-chang-jian-wen-ti.md)

***

## 第二部分：Gateway 控制平面

### 第 11 章 Gateway 服务器架构

* [**11.1 Gateway 的角色与设计目标**](/zh/di-11-zhang-gateway-fu-wu-qi-jia-gou/11.1gateway-de-jue-se-yu-she-ji-mu-biao.md)
* [**11.2 服务器启动流程源码分析**](/zh/di-11-zhang-gateway-fu-wu-qi-jia-gou/11.2-fu-wu-qi-qi-dong-liu-cheng-yuan-ma-fen-xi.md)
* [**11.3 WebSocket 服务器实现**](/zh/di-11-zhang-gateway-fu-wu-qi-jia-gou/11.3websocket-fu-wu-qi-shi-xian.md)
* [**11.4 HTTP 层**](/zh/di-11-zhang-gateway-fu-wu-qi-jia-gou/11.4http-ceng.md)
* 🔬 [**11.5 源码深读：装配现场与方法路由表**](/zh/di-11-zhang-gateway-fu-wu-qi-jia-gou/11.5-yuan-ma-shen-du-zhuang-pei-xian-chang-yu-fang-fa-lu-you-biao.md)
  * 平面方法路由表与调度器三道闸（角色**双向**隔离、作用域、控制面写预算）
  * `startGatewayServer` 的 15 步装配序列与手工依赖注入
  * HTTP stage 流水线；OpenAI 兼容层的"agent 即模型"取舍
  * 不变式：节点从不运行网关服务

### 第 12 章 Gateway 协议与类型系统

* [**12.1 协议设计哲学**](/zh/di-12-zhang-gateway-xie-yi-yu-lei-xing-xi-tong/12.1-xie-yi-she-ji-zhe-xue.md)
* [**12.2 TypeBox 类型模式**](/zh/di-12-zhang-gateway-xie-yi-yu-lei-xing-xi-tong/12.2typebox-lei-xing-mo-shi.md)
* [**12.3 核心方法与事件**](/zh/di-12-zhang-gateway-xie-yi-yu-lei-xing-xi-tong/12.3-he-xin-fang-fa-yu-shi-jian.md)
* [**12.4 认证与授权**](/zh/di-12-zhang-gateway-xie-yi-yu-lei-xing-xi-tong/12.4-ren-zheng-yu-shou-quan.md)
* 🔬 [**12.5 源码深读：三种帧、握手与四层鉴权**](/zh/di-12-zhang-gateway-xie-yi-yu-lei-xing-xi-tong/12.5-yuan-ma-shen-du-san-zhong-zhen-wo-shou-yu-si-ceng-jian-quan.md)
  * 三种帧与 discriminated union 的 codegen 动机
  * "事件不重放 + 请求幂等"为何是弱网重连的正确性基础
  * 四层鉴权：共享凭证 → Ed25519 设备身份 → 配对审批 → 设备令牌
  * 浏览器来源的哨兵 IP 记账；Tailscale 身份头必须反查验证

### 第 13 章 会话管理

* [**13.1 会话模型设计**](/zh/di-13-zhang-hui-hua-guan-li/13.1-hui-hua-mo-xing-she-ji.md)
* [**13.2 会话路由源码分析**](/zh/di-13-zhang-hui-hua-guan-li/13.2-hui-hua-lu-you-yuan-ma-fen-xi.md)
* [**13.3 会话生命周期**](/zh/di-13-zhang-hui-hua-guan-li/13.3-hui-hua-sheng-ming-zhou-qi.md)
* [**13.4 会话裁剪**](/zh/di-13-zhang-hui-hua-guan-li/13.4-hui-hua-cai-jian.md)
* [**13.5 会话间通信**](/zh/di-13-zhang-hui-hua-guan-li/13.5-hui-hua-jian-tong-xin.md)
* 🔬 [**13.6 源码深读：双层 lane 与三种排队语义**](/zh/di-13-zhang-hui-hua-guan-li/13.6-yuan-ma-shen-du-shuang-ceng-lane-yu-san-zhong-pai-dui-yu-yi.md)
  * `session lane(并发1) ⊂ global lane(并发N)`：约 300 行纯 Promise
  * 六种排队模式速查；collect 的跨渠道退化与溢出 summarize
  * typing 指示器的双信号收敛点（最容易踩的扩展陷阱）
  * 会话重置"换 ID 不删 key"；四项代价

### 第 14 章 通道路由与消息分发

* [**14.1 通道注册表**](/zh/di-14-zhang-tong-dao-lu-you-yu-xiao-xi-fen-fa/14.1-tong-dao-zhu-ce-biao.md)
* [**14.2 入站消息处理流水线**](/zh/di-14-zhang-tong-dao-lu-you-yu-xiao-xi-fen-fa/14.2-ru-zhan-xiao-xi-chu-li-liu-shui-xian.md)
* [**14.3 出站消息处理**](/zh/di-14-zhang-tong-dao-lu-you-yu-xiao-xi-fen-fa/14.3-chu-zhan-xiao-xi-chu-li.md)
* [**14.4 多 Agent 路由**](/zh/di-14-zhang-tong-dao-lu-you-yu-xiao-xi-fen-fa/14.4-duo-agent-lu-you.md)
* 🔬 [**14.5 源码深读：入站流水线的七道关**](/zh/di-14-zhang-tong-dao-lu-you-yu-xiao-xi-fen-fa/14.5-yuan-ma-shen-du-ru-zhan-liu-shui-xian-de-qi-dao-guan.md)
  * 入站去抖（滑动窗口、媒体与命令强制直通）
  * mention 门禁三路判定与零宽字符清洗；被拦下的消息进 history buffer
  * binding 七级瀑布匹配与三级缓存（config 对象做 WeakMap key）
  * session key 默认把所有私聊塌缩进主会话——"一个人，多个入口"

***

## 第三部分：AI Agent 运行时

### 第 15 章 Pi Agent 运行时核心

* [**15.1 Pi Agent 是什么**](/zh/di-15-zhang-piagent-yun-xing-shi-he-xin/15.1piagent-shi-shen-me.md)
* [**15.2 Agent Loop 端到端解析**](/zh/di-15-zhang-piagent-yun-xing-shi-he-xin/15.2agentloop-duan-dao-duan-jie-xi.md)
* [**15.3 队列与并发控制**](/zh/di-15-zhang-piagent-yun-xing-shi-he-xin/15.3-dui-lie-yu-bing-fa-kong-zhi.md)
* [**15.4 超时与中止机制**](/zh/di-15-zhang-piagent-yun-xing-shi-he-xin/15.4-chao-shi-yu-zhong-zhi-ji-zhi.md)
* 🔬 [**15.5 源码深读：一次运行的完整旅程**](/zh/di-15-zhang-piagent-yun-xing-shi-he-xin/15.5-yuan-ma-shen-du-yi-ci-yun-xing-de-wan-zhenglcheng.md)
  * 8.8 万行里，驱动循环的只有 `session.prompt()` 一句
  * 重试上限按认证档案数缩放；`attempt.ts` 2,096 行的十步装配
  * streamFn 洋葱：对 pi 的唯一注入点，七层各对应一个真实 issue
  * 流式事件桥的标签剥离、工具发送去重、推理三形态

### 第 16 章 模型提供者与故障转移

* [**16.1 模型选择机制**](/zh/di-16-zhang-mo-xing-ti-gong-zhe-yu-gu-zhang-zhuan-yi/16.1-mo-xing-xuan-ze-ji-zhi.md)
* [**16.2 Auth Profile 与凭据管理**](/zh/di-16-zhang-mo-xing-ti-gong-zhe-yu-gu-zhang-zhuan-yi/16.2authprofile-yu-ping-ju-guan-li.md)
* [**16.3 模型目录与配置**](/zh/di-16-zhang-mo-xing-ti-gong-zhe-yu-gu-zhang-zhuan-yi/16.3-mo-xing-mu-lu-yu-pei-zhi.md)
* [**16.4 故障转移错误处理**](/zh/di-16-zhang-mo-xing-ti-gong-zhe-yu-gu-zhang-zhuan-yi/16.4-gu-zhang-zhuan-yi-cuo-wu-chu-li.md)
* 🔬 [**16.5 源码深读：认证档案的轮换、冷却与降级**](/zh/di-16-zhang-mo-xing-ti-gong-zhe-yu-gu-zhang-zhuan-yi/16.5-yuan-ma-shen-du-ren-zheng-dang-an-de-lun-huan-leng-que-yu-jiang-ji.md)
  * 排序函数里写着成本策略：OAuth 订阅优先，API key 兜底
  * 两条关键纪律：**活跃窗口不可延长**、**timeout 从不记账**
  * 四个时间尺度各管一段；三套结构化观测日志为何是必需品

### 第 17 章 系统提示词与上下文组装

* [**17.1 系统提示词的构建**](/zh/di-17-zhang-xi-tong-ti-shi-ci-yu-shang-xia-wen-zu-zhuang/17.1-xi-tong-ti-shi-ci-de-gou-jian.md)
* [**17.2 工作区与上下文文件注入**](/zh/di-17-zhang-xi-tong-ti-shi-ci-yu-shang-xia-wen-zu-zhuang/17.2-gong-zuo-qu-yu-shang-xia-wen-wen-jian-zhu-ru.md)
* [**17.3 身份系统**](/zh/di-17-zhang-xi-tong-ti-shi-ci-yu-shang-xia-wen-zu-zhuang/17.3-shen-fen-xi-tong.md)
* [**17.4 上下文压缩**](/zh/di-17-zhang-xi-tong-ti-shi-ci-yu-shang-xia-wen-zu-zhuang/17.4-shang-xia-wen-ya-suo.md)
* **\[17.5 Context Engine 插件系统]\(ZH/第17章-系统提示词与上下文组装/17.5-Context Engine插件系统.md)**
* 🔬 [**17.6 源码深读：上下文治理的四道防线**](/zh/di-17-zhang-xi-tong-ti-shi-ci-yu-shang-xia-wen-zu-zhuang/17.6-yuan-ma-shen-du-shang-xia-wen-zhi-li-de-si-dao-fang-xian.md)
  * 入口守卫 → 请求内剪枝（不落盘）→ 压缩（落盘）→ 工具结果截断
  * 把 Anthropic 的 5 分钟缓存 TTL 纳入剪枝时机（成本感知上下文管理）
  * compaction-safeguard：宁可取消压缩，也不产出劣质摘要
  * usage 统计的坑：`cacheRead` 不能累加

### 第 18 章 流式传输与分块回复

* [**18.1 流式传输架构**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.1-liu-shi-chuan-shu-jia-gou.md)
* [**18.2 块流**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.2-kuai-liu.md)
* [**18.3 合并与人性化节奏**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.3-he-bing-yu-ren-xing-hua-jie-zou.md)
* [**18.4 Telegram 草稿流**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.4telegram-cao-gao-liu.md)
* [**18.5 回复塑形与抑制**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.5-hui-fu-su-xing-yu-yi-zhi.md)
* 🔬 [**18.6 源码深读：出站串行链与分块聚合**](/zh/di-18-zhang-liu-shi-chuan-shu-yu-fen-kuai-hui-fu/18.6-yuan-ma-shen-du-chu-zhan-chuan-xing-lian-yu-fen-kuai-ju-he.md)
  * `pending` 从 1 起步的"预留计数"
  * 拆（chunk）与合（coalescer）两个方向相反的组件
  * `routeReply` 的失败兜底：**当送达与送对冲突时，选送对**

***

## 第四部分：多通道消息系统

### 第 19 章 通道适配器抽象层

* [**19.1 通道适配器设计模式**](/zh/di-19-zhang-tong-dao-shi-pei-qi-chou-xiang-ceng/19.1-tong-dao-shi-pei-qi-she-ji-mo-shi.md)
* [**19.2 入站消息规范化**](/zh/di-19-zhang-tong-dao-shi-pei-qi-chou-xiang-ceng/19.2-ru-zhan-xiao-xi-gui-fan-hua.md)
* [**19.3 出站消息适配**](/zh/di-19-zhang-tong-dao-shi-pei-qi-chou-xiang-ceng/19.3-chu-zhan-xiao-xi-shi-pei.md)
* 🔬 [**19.4 源码深读：ChannelPlugin 合约与双注册表**](/zh/di-19-zhang-tong-dao-shi-pei-qi-chou-xiang-ceng/19.4-yuan-ma-shen-du-channelplugin-he-yue-yu-shuang-zhu-ce-biao.md)
  * 为什么没有统一消息总线：统一发生在合约层而非数据流层
  * 回复路由确定性——从设计上消除"注入让 Agent 改道"的攻击
  * **dock / plugin 轻重分离**：全章最值得抄的一笔
  * 信封头的转义防伪造；`src/web/` 其实是 WhatsApp

### 第 20 章 核心通道实现深入

* [**20.1 WhatsApp 通道**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.1whatsapp-tong-dao.md)
* [**20.2 Telegram 通道**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.2telegram-tong-dao.md)
* [**20.3 Discord 通道**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.3discord-tong-dao.md)
* [**20.4 Slack 通道**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.4slack-tong-dao.md)
* [**20.5 其他核心通道**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.5-qi-ta-he-xin-tong-dao.md)
* 🔬 [**20.6 源码深读：三种长连接与两种流式**](/zh/di-20-zhang-he-xin-tong-dao-shi-xian-shen-ru/20.6-yuan-ma-shen-du-san-zhong-chang-lian-jie-yu-liang-zhong-liu-shi.md)
  * Telegram 看门狗：探针寄生在正常 getUpdates 流量上
  * block streaming vs draft streaming 的分野与共享节流内核
  * `sendMayHaveLanded`：**"我不知道"是必须被建模的第三种状态**
  * 全通道横向对比表（17 个通道）

### 第 21 章 通道扩展机制

* [**21.1 扩展架构设计**](/zh/di-21-zhang-tong-dao-kuo-zhan-ji-zhi/21.1-kuo-zhan-jia-gou-she-ji.md)
* [**21.2 扩展 API 表面**](/zh/di-21-zhang-tong-dao-kuo-zhan-ji-zhi/21.2-kuo-zhan-api-biao-mian.md)
* [**21.3 代表性扩展实现解析**](/zh/di-21-zhang-tong-dao-kuo-zhan-ji-zhi/21.3-dai-biao-xing-kuo-zhan-shi-xian-jie-xi.md)
* [**21.4 开发自定义扩展**](/zh/di-21-zhang-tong-dao-kuo-zhan-ji-zhi/21.4-kai-fa-zi-ding-yi-kuo-zhan.md)
* 🔬 [**21.5 源码深读：装载器、jiti 与 SDK 能力面**](/zh/di-21-zhang-tong-dao-kuo-zhan-ji-zhi/21.5-yuan-ma-shen-du-zhuang-zai-qi-jiti-yu-sdk-neng-li-mian.md)
  * 清单/执行分离：**"验证配置永远不会变成运行代码"**
  * jiti 的交易：审计即所得 + SDK 零漂移 ↔ 零运行时隔离
  * 真正有强制力的边界只有三道，其余是文档边界
  * npm 三件套替代中心化市场；`--ignore-scripts` 移除供应链面

***

## 第五部分：工具系统与自动化

### 第 22 章 工具系统总览

* [**22.1 工具系统架构**](/zh/di-22-zhang-gong-ju-xi-tong-zong-lan/22.1-gong-ju-xi-tong-jia-gou.md)
* [**22.2 工具执行运行时**](/zh/di-22-zhang-gong-ju-xi-tong-zong-lan/22.2-gong-ju-zhi-xing-yun-xing-shi.md)
* [**22.3 工具权限与策略**](/zh/di-22-zhang-gong-ju-xi-tong-zong-lan/22.3-gong-ju-quan-xian-yu-ce-le.md)
* [**22.4 工具与 Agent 的协作**](/zh/di-22-zhang-gong-ju-xi-tong-zong-lan/22.4-gong-ju-yu-agent-de-xie-zuo.md)
* 🔬 [**22.5 源码深读：工具装配流水线与沙箱**](/zh/di-22-zhang-gong-ju-xi-tong-zong-lan/22.5-yuan-ma-shen-du-gong-ju-zhuang-pei-liu-shui-xian-yu-sha-xiang.md)
  * 五阶段总装线与**七层策略过滤**；全部工具走 `customTools` 的理由
  * `exec` 三维度：security 取最小、ask 取最大（取向刻意相反）
  * 审批两阶段协议解耦"LLM 同步调用"与"人类异步审批"
  * 沙箱不是 `docker exec`：只读根 + cap-drop + configHash 自动重建

### 第 23 章 Bash 工具与进程管理

* [**23.1 Bash 执行引擎**](/zh/di-23-zhang-bash-gong-ju-yu-jin-cheng-guan-li/23.1bash-zhi-xing-yin-qing.md)
* [**23.2 进程管理**](/zh/di-23-zhang-bash-gong-ju-yu-jin-cheng-guan-li/23.2-jin-cheng-guan-li.md)
* [**23.3 Shell 工具与共享基础设施**](/zh/di-23-zhang-bash-gong-ju-yu-jin-cheng-guan-li/23.3shell-gong-ju-yu-gong-xiang-ji-chu-she-shi.md)

### 第 24 章 浏览器控制

* [**24.1 浏览器架构概述**](/zh/di-24-zhang-liu-lan-qi-kong-zhi/24.1-liu-lan-qi-jia-gou-gai-shu.md)
* [**24.2 CDP 层实现**](/zh/di-24-zhang-liu-lan-qi-kong-zhi/24.2cdp-ceng-shi-xian.md)
* [**24.3 Playwright 层实现**](/zh/di-24-zhang-liu-lan-qi-kong-zhi/24.3playwright-ceng-shi-xian.md)
* [**24.4 浏览器服务器**](/zh/di-24-zhang-liu-lan-qi-kong-zhi/24.4-liu-lan-qi-fu-wu-qi.md)
* 🔬 [**24.5 源码深读：四种来源与三道安全闸**](/zh/di-24-zhang-liu-lan-qi-kong-zhi/24.5-yuan-ma-shen-du-liu-lan-qi-de-si-zhong-lai-yuan-yu-san-dao-an-quan-zha.md)
  * 不是 headless——附着到真实 Chrome，橙色窗口标识
  * 快照是可访问性文本树而非截图：token 效率高一个量级
  * SSRF 守卫的关键洞察：**环境代理会让 DNS 预检形同虚设**
  * 认证自举：**loopback 不等于安全**

### 第 25 章 Canvas 与 A2UI

* [**25.1 Canvas 概念**](/zh/di-25-zhang-canvas-yu-a2ui/25.1canvas-gai-nian.md)
* [**25.2 Canvas Host 实现**](/zh/di-25-zhang-canvas-yu-a2ui/25.2canvashost-shi-xian.md)
* [**25.3 Canvas 工具**](/zh/di-25-zhang-canvas-yu-a2ui/25.3canvas-gong-ju.md)

### 第 26 章 Cron 调度与自动化

* [**26.1 Cron 系统设计**](/zh/di-26-zhang-cron-diao-du-yu-zi-dong-hua/26.1cron-xi-tong-she-ji.md)
* [**26.2 Cron 作业执行**](/zh/di-26-zhang-cron-diao-du-yu-zi-dong-hua/26.2cron-zuo-ye-zhi-xing.md)
* [**26.3 Webhook 与 Gmail Pub/Sub**](/zh/di-26-zhang-cron-diao-du-yu-zi-dong-hua/26.3webhook-yu-gmailpubsub.md)
* 🔬 [**26.4 源码深读：cron 与 heartbeat 的分工**](/zh/di-26-zhang-cron-diao-du-yu-zi-dong-hua/26.4-yuan-ma-shen-du-cron-yu-heartbeat-de-fen-gong.md)
  * 两种会话形态在创建时强校验配对
  * 三条事故教训：`setTimeout(0)` 热循环、重启补跑风暴、卡死任务
  * 确定性错峰用 job id 的 SHA-256 而非随机数
  * heartbeat 的让路、省钱与静音三件套

### 第 27 章 节点系统

* [**27.1 节点概念**](/zh/di-27-zhang-jie-dian-xi-tong/27.1-jie-dian-gai-nian.md)
* [**27.2 节点注册与发现**](/zh/di-27-zhang-jie-dian-xi-tong/27.2-jie-dian-zhu-ce-yu-fa-xian.md)
* [**27.3 节点 Host 实现**](/zh/di-27-zhang-jie-dian-xi-tong/27.3-jie-dian-host-shi-xian.md)
* 🔬 [**27.4 源码深读：反向 RPC 与"叫醒"机制**](/zh/di-27-zhang-jie-dian-xi-tong/27.4-yuan-ma-shen-du-fan-xiang-rpc-yu-jiao-xing-ji-zhi.md)
  * `node.invoke` 外的四层包装
  * **能改变权限的操作不该和普通操作走同一条通道**
  * APNs 三段唤醒：只在前两段失败后才打扰用户
  * iOS 前台队列——移动系统生命周期的补丁被做成了机制

***

## 第六部分：记忆、技能与生态系统

### 第 28 章 记忆系统

* [**28.1 记忆模型设计**](/zh/di-28-zhang-ji-yi-xi-tong/28.1-ji-yi-mo-xing-she-ji.md)
* [**28.2 向量记忆搜索**](/zh/di-28-zhang-ji-yi-xi-tong/28.2-xiang-liang-ji-yi-sou-suo.md)
* [**28.3 混合搜索**](/zh/di-28-zhang-ji-yi-xi-tong/28.3-hun-he-sou-suo.md)
* [**28.4 高级记忆功能**](/zh/di-28-zhang-ji-yi-xi-tong/28.4-gao-ji-ji-yi-gong-neng.md)
* 🔬 [**28.5 源码深读：文件事实源与混合检索**](/zh/di-28-zhang-ji-yi-xi-tong/28.5-yuan-ma-shen-du-wen-jian-shi-shi-yuan-yu-hun-he-jian-suo.md)
  * 四层结构：向量索引是唯一的二进制状态，且可随时重建
  * **检索是模型的行为，不是框架的行为**（与 LanceDB 的相反极端并存）
  * LanceDB auto-capture 只处理 user 消息："避免模型输出自我污染"
  * flush 的安全提示不可被用户覆盖：**允许改语气，不允许改边界**

### 第 29 章 技能系统

* [**29.1 技能平台设计**](/zh/di-29-zhang-ji-neng-xi-tong/29.1-ji-neng-ping-tai-she-ji.md)
* [**29.2 技能结构**](/zh/di-29-zhang-ji-neng-xi-tong/29.2-ji-neng-jie-gou.md)
* [**29.3 技能安装与管理**](/zh/di-29-zhang-ji-neng-xi-tong/29.3-ji-neng-an-zhuang-yu-guan-li.md)
* [**29.4 ClawHub 技能注册中心**](/zh/di-29-zhang-ji-neng-xi-tong/29.4clawhub-ji-neng-zhu-ce-zhong-xin.md)
* 🔬 [**29.5 源码深读：渐进式披露与三层装载**](/zh/di-29-zhang-ji-neng-xi-tong/29.5-yuan-ma-shen-du-jian-jin-shi-pi-lu-yu-san-ceng-zhuang-zai.md)
  * 按 `requires` 预过滤：**模型永远不会推荐一个跑不了的方案**
  * 渐进式披露的四条纪律，上下文成本从 O(N) 降到 O(1)
  * 信任边界：`SKILL.md` 直接进提示词，唯一防线是自己读一遍

### 第 30 章 钩子系统

* [**30.1 内部钩子**](/zh/di-30-zhang-gou-zi-xi-tong/30.1-nei-bu-gou-zi.md)
* [**30.2 插件钩子**](/zh/di-30-zhang-gou-zi-xi-tong/30.2-cha-jian-gou-zi.md)
* 🔬 [**30.3 源码深读：两套事件系统与 hook 包约定**](/zh/di-30-zhang-gou-zi-xi-tong/30.3-yuan-ma-shen-du-liang-tao-shi-jian-xi-tong-yu-hook-bao-yue-ding.md)
  * `session-memory` hook 如何实现"重置会话但不失忆"
  * fire-and-forget 的例外：`agent:bootstrap` 可修改引导文件列表
  * Gmail watcher：外部世界 → agent 回合的代表性入口

***

## 第七部分：安全、配置与基础设施

### 第 31 章 配置系统

* [**31.1 配置加载与解析**](/zh/di-31-zhang-pei-zhi-xi-tong/31.1-pei-zhi-jia-zai-yu-jie-xi.md)
* [**31.2 配置类型系统详解**](/zh/di-31-zhang-pei-zhi-xi-tong/31.2-pei-zhi-lei-xing-xi-tong-xiang-jie.md)
* [**31.3 配置热重载**](/zh/di-31-zhang-pei-zhi-xi-tong/31.3-pei-zhi-re-zhong-zai.md)
* [**31.4 遗留配置迁移**](/zh/di-31-zhang-pei-zhi-xi-tong/31.4-yi-liu-pei-zhi-qian-yi.md)
* [**31.5 环境变量**](/zh/di-31-zhang-pei-zhi-xi-tong/31.5-huan-jing-bian-liang.md)
* 🔬 [**31.6 源码深读：五段读管线与写回还原**](/zh/di-31-zhang-pei-zhi-xi-tong/31.6-yuan-ma-shen-du-wu-duan-du-guan-xian-yu-xie-hui-huan-yuan.md)
  * fail closed 是安全底线：**绝不悄悄退回宽松默认值**
  * legacy 检测必须在 Zod 之前——错误信息质量取决于拦截层
  * 写回三手段：merge-patch 回投 + env-ref 还原 + 原型键黑名单
  * 一个反直觉隐患：**读操作会写文件**

### 第 32 章 安全模型

* [**32.1 安全设计原则**](/zh/di-32-zhang-an-quan-mo-xing/32.1-an-quan-she-ji-yuan-ze.md)
* [**32.2 DM 配对系统**](/zh/di-32-zhang-an-quan-mo-xing/32.2dm-pei-dui-xi-tong.md)
* [**32.3 沙箱机制**](/zh/di-32-zhang-an-quan-mo-xing/32.3-sha-xiang-ji-zhi.md)
* [**32.4 安全审计**](/zh/di-32-zhang-an-quan-mo-xing/32.4-an-quan-shen-ji.md)
* [**32.5 SOUL 安全**](/zh/di-32-zhang-an-quan-mo-xing/32.5soul-an-quan.md)
* 🔬 [**32.6 源码深读：准入、密钥与审计三件套**](/zh/di-32-zhang-an-quan-mo-xing/32.6-yuan-ma-shen-du-zhun-ru-mi-yao-yu-shen-ji-san-jian-tao.md)
  * **配对是会话准入，不是权限授予**（群命令不继承 DM 配对）
  * 外部内容用随机 16 位 id 定界 + 同形字归一化
  * secrets 三层：SecretRef → 双快照 → 脱敏（限界正则防自己被 DoS）
  * 审计**严重度随实际暴露面变化**；工具不假装自己是边界

### 第 33 章 CLI 命令行工具

* [**33.1 CLI 架构**](/zh/di-33-zhang-cli-ming-ling-xing-gong-ju/33.1cli-jia-gou.md)
* [**33.2 核心命令解析**](/zh/di-33-zhang-cli-ming-ling-xing-gong-ju/33.2-he-xin-ming-ling-jie-xi.md)
* [**33.3 聊天命令**](/zh/di-33-zhang-cli-ming-ling-xing-gong-ju/33.3-liao-tian-ming-ling.md)
* 🔬 [**33.4 源码深读：两棵命令树与启动速度偏执**](/zh/di-33-zhang-cli-ming-ling-xing-gong-ju/33.4-yuan-ma-shen-du-liang-ke-ming-ling-shu-yu-qi-dong-su-du-pian-zhi.md)
  * 聊天命令注册表：一份声明驱动五种前端 + 构建期自检
  * 三层启动优化（version fast-path / route-first / 懒注册占位）
  * config-guard 的"fail closed + 白名单放行"避免修复死锁
  * DI 走窄接口 + 默认参数：**接口小到测试替身可以手写**

### 第 34 章 基础设施

* [**34.1 日志系统**](/zh/di-34-zhang-ji-chu-she-shi/34.1-ri-zhi-xi-tong.md)
* [**34.2 媒体管道**](/zh/di-34-zhang-ji-chu-she-shi/34.2-mei-ti-guan-dao.md)
* [**34.3 链接理解与媒体理解**](/zh/di-34-zhang-ji-chu-she-shi/34.3-lian-jie-li-jie-yu-mei-ti-li-jie.md)
* [**34.4 TTS 文本转语音**](/zh/di-34-zhang-ji-chu-she-shi/34.4tts-wen-ben-zhuan-yu-yin.md)
* [**34.5 投票系统**](/zh/di-34-zhang-ji-chu-she-shi/34.5-tou-piao-xi-tong.md)
* 🔬 [**34.6 源码深读：媒体理解的候选链与 vision 短路**](/zh/di-34-zhang-ji-chu-she-shi/34.6-yuan-ma-shen-du-mei-ti-li-jie-de-hou-xuan-lian-yu-vision-duan-lu.md)
  * **探测顺序而非配置开关**——把配置问题降级成性能问题
  * vision 短路：主模型能看图就别做二手转述
  * 链接理解在抽取阶段就过滤 SSRF——把防护提前到数据入口

***

## 第八部分：客户端应用与 Web UI

### 第 35 章 Web 控制台 UI

* [**35.1 UI 技术选型**](/zh/di-35-zhang-web-kong-zhi-tai-ui/35.1ui-ji-shu-xuan-xing.md)
* [**35.2 控制台 UI 架构**](/zh/di-35-zhang-web-kong-zhi-tai-ui/35.2-kong-zhi-tai-ui-jia-gou.md)
* [**35.3 WebChat 实现**](/zh/di-35-zhang-web-kong-zhi-tai-ui/35.3webchat-shi-xian.md)

### 第 36 章 原生客户端应用

* [**36.1 macOS 应用**](/zh/di-36-zhang-yuan-sheng-ke-hu-duan-ying-yong/36.1macos-ying-yong.md)
* [**36.2 iOS 节点应用**](/zh/di-36-zhang-yuan-sheng-ke-hu-duan-ying-yong/36.2ios-jie-dian-ying-yong.md)
* [**36.3 Android 节点应用**](/zh/di-36-zhang-yuan-sheng-ke-hu-duan-ying-yong/36.3android-jie-dian-ying-yong.md)
* [**36.4 共享组件**](/zh/di-36-zhang-yuan-sheng-ke-hu-duan-ying-yong/36.4-gong-xiang-zu-jian.md)

***

## 第九部分：部署与运维

### 第 37 章 部署方案

* [**37.1 本地部署**](/zh/di-37-zhang-bu-shu-fang-an/37.1-ben-di-bu-shu.md)
* [**37.2 Docker 部署**](/zh/di-37-zhang-bu-shu-fang-an/37.2docker-bu-shu.md)
* [**37.3 远程访问**](/zh/di-37-zhang-bu-shu-fang-an/37.3-yuan-cheng-fang-wen.md)
* [**37.4 Nix 声明式部署**](/zh/di-37-zhang-bu-shu-fang-an/37.4nix-sheng-ming-shi-bu-shu.md)
* [**37.5 VPS 部署**](/zh/di-37-zhang-bu-shu-fang-an/37.5vps-bu-shu.md)

> 跨平台服务安装的源码深读见 [**附录 F**](/zh/fu-lu/fu-lufshou-hu-jin-cheng-yu-she-bei-jie-dian-shen-du.md)。

### 第 38 章 监控与故障排查

* [**38.1 健康检查**](/zh/di-38-zhang-jian-kong-yu-gu-zhang-pai-cha/38.1-jian-kang-jian-cha.md)
* [**38.2 在线追踪**](/zh/di-38-zhang-jian-kong-yu-gu-zhang-pai-cha/38.2-zai-xian-zhui-zong.md)
* [**38.3 用量追踪**](/zh/di-38-zhang-jian-kong-yu-gu-zhang-pai-cha/38.3-yong-liang-zhui-zong.md)
* [**38.4 故障排查**](/zh/di-38-zhang-jian-kong-yu-gu-zhang-pai-cha/38.4-gu-zhang-pai-cha.md)

***

## 第十部分：高级主题与实践

### 第 39 章 多代理架构

* [**39.1 多代理设计**](/zh/di-39-zhang-duo-dai-li-jia-gou/39.1-duo-dai-li-she-ji.md)
* [**39.2 子代理**](/zh/di-39-zhang-duo-dai-li-jia-gou/39.2-zi-dai-li.md)
* [**39.3 多代理沙箱工具**](/zh/di-39-zhang-duo-dai-li-jia-gou/39.3-duo-dai-li-sha-xiang-gong-ju.md)
* 🔬 [**39.4 源码深读：子代理生成与跨代理通信**](/zh/di-39-zhang-duo-dai-li-jia-gou/39.4-yuan-ma-shen-du-zi-dai-li-sheng-cheng-yu-kua-dai-li-tong-xin.md)
  * 深度限制防 fork 炸弹；系统提示里明令禁止轮询
  * 幂等键 = 子会话 key + run id；迟到事件用 `NO_REPLY` 静默吞掉
  * **沙箱会话禁止 spawn ACP**——宁可明说没有保护，也不给假开关

### 第 40 章 ACP（Agent Communication Protocol）

* [**40.1 ACP 协议概述**](/zh/di-40-zhang-acp/40.1acp-xie-yi-gai-shu.md)
* [**40.2 ACP 会话管理与运行时**](/zh/di-40-zhang-acp/40.2acp-hui-hua-guan-li-yu-yun-xing-shi.md)
* [**40.3 ACP 控制面与集成模式**](/zh/di-40-zhang-acp/40.3acp-kong-zhi-mian-yu-ji-cheng-mo-shi.md)
* 🔬 [**40.4 源码深读：方向相反的两套 ACP 子系统**](/zh/di-40-zhang-acp/40.4-yuan-ma-shen-du-fang-xiang-xiang-fan-de-liang-tao-acp-zi-xi-tong.md)
  * ACP 桥（被调）与 ACP Runtime（调用）的分野
  * `runId` 一键三用；**错误映射为 `end_turn` 而非 refusal**
  * 确定性 sessionKey 代替持久化映射表；"配置即期望状态"

### 第 41 章 TUI（终端用户界面）

* [**41.1 TUI 架构**](/zh/di-41-zhang-tui/41.1tui-jia-gou.md)
* [**41.2 TUI 交互机制**](/zh/di-41-zhang-tui/41.2tui-jiao-hu-ji-zhi.md)
* [**41.3 TUI 高级特性**](/zh/di-41-zhang-tui/41.3tui-gao-ji-te-xing.md)

### 第 42 章 实战项目：构建你自己的 AI 助手

* [**42.1 项目规划**](/zh/di-42-zhang-shi-zhan-xiang-mu/42.1-xiang-mu-gui-hua.md)
* [**42.2 核心功能实现**](/zh/di-42-zhang-shi-zhan-xiang-mu/42.2-he-xin-gong-neng-shi-xian.md)
* [**42.3 通道集成**](/zh/di-42-zhang-shi-zhan-xiang-mu/42.3-tong-dao-ji-cheng.md)
* [**42.4 高级功能**](/zh/di-42-zhang-shi-zhan-xiang-mu/42.4-gao-ji-gong-neng.md)
* [**42.5 部署上线**](/zh/di-42-zhang-shi-zhan-xiang-mu/42.5-bu-shu-shang-xian.md)

***

## 第十一部分：源码研读与设计洞察

> 前面四十二章像拆机器一样把 OpenClaw 拆开看，每一章都在回答"这块是怎么实现的"。 这一部分换个视角：合上放大镜，退后几步，提炼**贯穿全库的形状**、**可迁移的模式**与**必须知道的风险**。
>
> 具体的行号会过期，形状不会。

### 第 43 章 工程全景

* [**43.1 项目定位与演化脉络**](/zh/di-43-zhang-gong-cheng-quan-jing/43.1-xiang-mu-ding-wei-yu-yan-hua-mai-luo.md)
  * 四条工程主线与四次改名；**心脏是外借的**（嵌入 pi-mono 而非自研）
  * Agent 的人格是一组可 git 管理的 Markdown 文件
* [**43.2 工程规模与子系统地图**](/zh/di-43-zhang-gong-cheng-quan-jing/43.2-gong-cheng-gui-mo-yu-zi-xi-tong-di-tu.md)
  * 六个数字：50.7 万行、1,935 个测试、18,005 提交、40 扩展、52 技能
  * 章节索引反查表；三个反直觉事实
* [**43.3 AI 协作开发：当代码库的第一读者不是人**](/zh/di-43-zhang-gong-cheng-quan-jing/43.3ai-xie-zuo-kai-fa-dang-dai-ma-ku-de-di-yi-du-zhe-bu-shi-ren.md)
  * `AGENTS.md` 不是贡献指南，是 agent 踩坑判例集
  * 三类规则：防 AI 代码病灶 / 多 agent 并行安全 / 合并门禁
  * `r:*` 标签体系与三条可迁移经验
* [**43.4 源码阅读路径**](/zh/di-43-zhang-gong-cheng-quan-jing/43.4-yuan-ma-yue-du-lu-jing.md)
  * 四条路径；**把 1,935 个测试文件名当规格书用**
  * 反向建议：别从 2,096 行的装配文件开始读

### 第 44 章 贯穿全库的设计主题

* [**44.1 收敛的网络面，与"嵌入而不 fork"**](/zh/di-44-zhang-guan-chuan-quan-ku-de-she-ji-zhu-ti/44.1-shou-lian-de-wang-luo-mian-yu-qian-ru-er-bu-fork.md)
  * 主题一：一个端口、一个协议、一套准入（代价是复杂度被集中）
  * 主题二：**宁交架构税，不背 fork 债**——判断标准是上游变更频率
* [**44.2 故障降级链无处不在**](/zh/di-44-zhang-guan-chuan-quan-ku-de-she-ji-zhu-ti/44.2-gu-zhang-jiang-ji-lian-wu-chu-bu-zai.md)
  * 主题三：同一模式在六处**独立出现**——共识而非复用
  * 写对降级链的四条要点；**抄这个模式必须同时抄可观测性**
* [**44.3 文件即事实源，声明表即单一真相**](/zh/di-44-zhang-guan-chuan-quan-ku-de-she-ji-zhu-ti/44.3-wen-jian-ji-shi-shi-yuan-yu-sheng-ming-biao-ji-dan-yi-zhen-xiang.md)
  * 主题四：向量索引是唯一二进制状态，且被定义为派生物
  * 主题五：需要多处一致的知识，一律收敛为数据表 + 生成/校验
* [**44.4 诚实到判例化的信任模型**](/zh/di-44-zhang-guan-chuan-quan-ku-de-she-ji-zhu-ti/44.4-cheng-shi-dao-pan-li-hua-de-xin-ren-mo-xing.md)
  * 主题六：把"什么不算漏洞"写成可引用判例
  * 判例化是在应对 **AI 生成的漏洞报告**
  * 三条可迁移：写清什么不受保护 / 信任假设可自动检查 / 命名即契约
* [**44.5 对话体验是一等工程对象**](/zh/di-44-zhang-guan-chuan-quan-ku-de-she-ji-zhu-ti/44.5-dui-hua-ti-yan-shi-yi-deng-gong-cheng-dui-xiang.md)
  * 主题七：三种排队语义对应三种真实心智
  * 双层 lane 用 300 行纯 Promise 解决三个约束
  * heartbeat 无痕设计；**先建模用户心智，再设计系统行为**

### 第 45 章 风险清单与可迁移经验

* [**45.1 值得抄走的十个工程模式**](/zh/di-45-zhang-feng-xian-qing-dan-yu-ke-qian-yi-jing-yan/45.1-zhi-de-chao-zou-de-shi-ge-gong-cheng-mo-shi.md)
  * 挑选标准：**脱离 OpenClaw 上下文仍然成立**
  * 附"按系统特征选用"对照表
* [**45.2 风险与改进清单**](/zh/di-45-zhang-feng-xian-qing-dan-yu-ke-qian-yi-jing-yan/45.2-feng-xian-yu-gai-jin-qing-dan.md)
  * 一处已核实缺陷（`systemd.ts:484/528`，**卸载 node 会停掉 gateway**）
  * 三条架构级风险 + 七条正确性/维护类风险
  * **每条风险都是第 44 章某个优点的账单**
* [**45.3 另一条路线的对照**](/zh/di-45-zhang-feng-xian-qing-dan-yu-ke-qian-yi-jing-yan/45.3-ling-yi-tiao-lu-xian-de-dui-zhao.md)
  * 十二个决策点上几乎全选了相反方向
  * 三组关键对照：错误教谁 / 信任往哪收 / 渠道抽象的代价曲线
* [**45.4 结语：从工具到基础设施**](/zh/di-45-zhang-feng-xian-qing-dan-yu-ke-qian-yi-jing-yan/45.4-jie-yu-cong-gong-ju-dao-ji-chu-she-shi.md)
  * 写一个**能用**的 Agent 约 200 行，另外 49.98 万行在干什么
  * 三条带走的原则

***

## 附录

### [附录 A：OpenClaw 配置参考](/zh/fu-lu/fu-lu-aopenclaw-pei-zhi-can-kao.md)

完整配置 JSON5 示例 · 所有配置键速查表

### [附录 B：Gateway WebSocket 协议参考](/zh/fu-lu/fu-lu-bgatewaywebsocket-xie-yi-can-kao.md)

所有请求方法与参数 · 所有事件类型与负载

### [附录 C：工具定义参考](/zh/fu-lu/fu-lucgong-ju-ding-yi-can-kao.md)

所有内置工具的 Schema 与用途

### [附录 D：源码导航图](/zh/fu-lu/fu-ludyuan-ma-dao-hang-tu.md)

关键模块依赖关系图 · 数据流序列图

### [附录 E：术语表](/zh/fu-lu/fu-lueshu-yu-biao.md)

本书出现的全部专业术语中英文对照与解释

### 🔬 [附录 F：守护进程与设备节点深读](/zh/fu-lu/fu-lufshou-hu-jin-cheng-yu-she-bei-jie-dian-shen-du.md)

* 三平台服务安装的"怪癖补丁"——launchd 的 disabled 持久化、systemd 的 bus 双 scope、schtasks 的本地化文本陷阱
* 服务文件即配置真相源（`readCommand` 反解）
* **一处已核实缺陷**：systemd install/uninstall 忽略 unit 名 override
* node-host 的 exec 安全：纯函数策略核 + 四道运行期重验

### 🔬 [附录 G：Gateway 网络模型与协议速查](/zh/fu-lu/fu-lu-ggateway-wang-luo-mo-xing-yu-xie-yi-su-cha.md)

* 最容易搞错的六件事（含"两套 pairing"的警告）
* 传输选择四级降级；Tailscale 三模式；凭据优先级硬规则
* OpenAI 兼容 API 的限额与 **SSRF 防线与 allowlist 正交**
* 端口与配置键速查表

***

## 规模

| 部分                  | 章节数             | 预估字数            |
| ------------------- | --------------- | --------------- |
| 第一部分：入门指南           | 10 章            | \~80,000        |
| 第二部分：Gateway 控制平面   | 4 章             | \~40,000        |
| 第三部分：AI Agent 运行时   | 4 章             | \~40,000        |
| 第四部分：多通道消息系统        | 3 章             | \~30,000        |
| 第五部分：工具系统与自动化       | 6 章             | \~36,000        |
| 第六部分：记忆、技能与生态       | 3 章             | \~22,000        |
| 第七部分：安全、配置与基础设施     | 4 章             | \~32,000        |
| 第八部分：客户端应用与 Web UI  | 2 章             | \~6,000         |
| 第九部分：部署与运维          | 2 章             | \~6,000         |
| 第十部分：高级主题与实践        | 4 章             | \~16,000        |
| **第十一部分：源码研读与设计洞察** | **3 章**         | **\~24,000**    |
| 附录                  | 7 项             | \~14,000        |
| **合计**              | **45 章 + 7 附录** | **\~346,000 字** |

其中 🔬 标记的**源码深读**共 **24 节 + 2 附录**，约 12 万字。


---

# 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-zh.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.