前言

这本书讲的是一只「龙虾」。

不是海里的那只，而是你电脑上的那只：OpenClaw。

「Claw」是龙虾的螯——它最有力的那只钳子。这个名字精准地概括了 OpenClaw 的设计意图：一个有「抓力」的 AI 助手。和只会聊天的 AI 不同，OpenClaw 能真正「伸出手来」抓住你的文件、邮箱、浏览器、命令行——它的本事不在嘴上，而在手上。

OpenClaw 是一个开源的个人 AI 助手框架。你把它装在自己的机器上，它通过你熟悉的聊天工具——WhatsApp、Telegram、Slack、Discord、Signal、iMessage……和你说话，帮你收邮件、写代码、查资料、跑脚本、定时提醒，甚至打开浏览器自己去点点点、填表单、抓数据。它不是一个「网站」，也不是一款单纯的「App」，而更像是一个常驻在你个人设备上的小团队：会说话、会动手、有记忆、还有一堆可以扩展的技能。

本书的目标，就是帮你把这只龙虾「拆开来看」。

• 从产品视角：它解决了什么问题？和 ChatGPT/App Store/SaaS 有什么根本区别？
• 从架构视角：Gateway、Agent Runtime、Channels、Nodes、Browser、Skills 这些模块是怎么拼在一起的？
• 从源码视角：仓库目录、关键数据结构与调用链、典型请求从哪儿进、走到哪儿、怎么出去？
• 从实战视角：怎么写出自己可控的 Skill，让 OpenClaw 变成你个人/团队的自动化中枢？

为了不重复官方文档，本书不会再一步步教你「在哪个按钮上点鼠标」，而是做三件事：

• 给你一张地图：把分散在 README、docs、GitHub 代码和社区中的零散经验，整合成一条清晰的学习路径；
• 解释为什么：面对每个关键设计（多通道、Agent 抽象、技能系统、安全模型），都尽量讲清背后的权衡；
• 给你可抄的范本：在 Skills、自动化、部署、安全等章节，给出可以直接套用或改造的思路和代码骨架。

这本书适合谁

本书默认你具备以下基础：

• 至少熟悉一门后端或脚本语言（TypeScript/JavaScript/Go/Rust/Python 皆可）；
• 对命令行不恐惧，能看懂基本的 JSON/YAML 配置；
• 对「让 AI 真正帮我干活」有强烈兴趣，而不仅仅是「聊聊天」。

不同读者可以有不同阅读路径：

• 想玩爽的个人用户

  • 推荐重点阅读：Part I、Part II、Part IV。
  • 目标：理解 OpenClaw 能干什么、怎么思考问题、怎么用 Skills 把自己的需求变成可复用的「工作流」。

• 需要集成的工程师

  • 推荐重点阅读：Part I、Part II、Part III、Part IV。
  • 目标：搞清楚 Gateway、Agent Runtime、Channels、Nodes、Skills 的调用链，并能按照自己的基础设施改造、嵌入、扩展。

• 做架构/平台的负责人

  • 推荐重点阅读：Part I、II、III、IV、V、VI。
  • 目标：看清 OpenClaw 这类「本地 Agent OS」在架构、安全、运维上的设计取舍，哪些可以复用到自己的平台中。

如何使用本书

• 如果你刚接触 OpenClaw，建议按顺序阅读：至少读完 Part I 和 Part II，再按兴趣跳转到 Skills（Part IV）或安全与运维（Part V）。
• 如果你已经在用 OpenClaw，但想深入源码，可直接从 Part III 开始，把第 8 章和第 10 章当作两条主干调用链来走读。
• 如果你关心的是「我该不该在公司推这东西」，可以先看 Part I、第 14 章（安全模型）、第 15–16 章（部署与运维），最后读第 17 章（架构复盘与未来）。

本书默认你会一边看一边试：很多章节会引用官方文档的链接，鼓励你在本地起一个 OpenClaw 实例，跟着一起改配置、装 Skills、看日志。真正理解一个系统的最好方式，一向是：跑起来，改一改，搞挂一次，再修回来。在 Part II 你会先遇到核心概念（Session、Agent、Channel、Node），在 Part III–IV 里，才会真正和源码细节「贴脸接触」。

本书如何解读架构和源码

为了配得上「架构和源码解读」这五个字，本书在后续章节会刻意做几件事：

• 站在「组件 + 数据流」的角度讲架构
  每个 Part 都会给出文字版架构图或时序图，描述清楚：请求从哪儿进来、经过哪些组件、状态在哪里更新、最后从哪儿出去。

• 指路到真实代码位置，而不是虚构伪项目
  出现重要概念时，会注明大致所在目录（例如 src/、packages/、apps/ 中的哪个子模块），方便你一边读书一边翻 GitHub 仓库。

• 用 TypeScript 代码片段和伪代码说明关键路径
  对 Session、消息路由、工具调用、技能生命周期等关键路径，会给出简化后的接口/类型定义，以及主干调用链的伪代码，帮助你把文档里的「方块图」脑补成真实代码。

• 解释「为什么这样设计」，而不仅是「长什么样」
  在深挖章节，会特别强调：为什么选这种抽象、为什么把逻辑放在 Gateway 而不是 Skill 里、为什么用 Cron/Webhook 组合而不是重造一套调度系统。

如果你愿意，可以把这本书当成 https://github.com/openclaw/openclaw 的「人肉注释版」：
看到有趣的类型/函数/模块，就顺着书里的线索去源码里继续挖。