前言
生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~130,000 tokens，输出 ~12,000 tokens（本章）
为什么写这本书
2025 年末，大语言模型（LLM）的能力已经从"能对话"跨越到"能做事"。AI Agent 不再是论文里的概念——它们正在接管邮件回复、日程管理、代码生成、信息检索等日常任务。然而，市面上绝大多数 AI 助手都运行在云端，你的对话记录、偏好设置、工作文件全部托管在第三方服务器上。
OpenClaw 提供了一条不同的路径：在你自己的设备上运行一个完整的 AI 助手。它连接到你已经在用的消息平台（WhatsApp、Telegram、Slack、Discord、Signal、iMessage 等），你可以在任何一个平台上和它对话，而所有的数据——对话记录、记忆文件、配置——都保存在你的本地磁盘上。
OpenClaw 是一个开源项目（MIT 许可证），截至本书写作时，其 TypeScript 源码超过 30 万行，覆盖了从 WebSocket 网关、多通道消息路由、AI Agent 运行时、浏览器自动化，到原生 macOS/iOS/Android 客户端等完整技术栈。这使得它成为一个绝佳的学习素材——不仅涵盖了现代 AI 应用的核心架构模式，还展示了一个生产级项目如何组织代码、管理复杂性、处理安全问题。
本书旨在从源码出发，带领读者深入理解 OpenClaw 的架构设计、核心机制与关键实现。读完本书后，你应该能够：
理解 一个多通道 AI 助手的完整架构
阅读 OpenClaw 的源码并追踪任意功能的实现路径
动手 开发出类似的 AI 助手产品
目标读者
本书面向具备一定编程基础的读者，典型画像包括：
计算机科学本科生：学过数据结构、操作系统、计算机网络等基础课程
初级至中级开发者：有 JavaScript/TypeScript 经验，想深入理解 AI Agent 架构
技术爱好者：对本地 AI 助手感兴趣，想了解背后的工程实现
你不需要是 TypeScript 专家，但需要能读懂基本的 TypeScript 代码。对于一些在计算机科学教科书中不常出现的概念（如 WebSocket 控制平面、向量嵌入搜索、Chrome DevTools Protocol 等），本书会在首次出现时给出衍生解释。
本书的组织结构
全书分为十个部分，34 章外加 5 个附录：
第一部分
全局概览：项目介绍、架构总览、开发环境
第 1–2 章
第二部分
Gateway 控制平面：服务器、协议、会话、路由
第 3–6 章
第三部分
AI Agent 运行时：Pi Agent、模型管理、提示词、流式传输
第 7–10 章
第四部分
多通道消息系统：适配器层、核心通道、扩展机制
第 11–13 章
第五部分
工具与自动化：工具架构、Bash、浏览器、Canvas、Cron、节点
第 14–19 章
第六部分
记忆、技能与生态：向量搜索、技能平台、钩子系统
第 20–22 章
第七部分
安全、配置与基础设施：配置系统、安全模型、CLI、底层设施
第 23–26 章
第八部分
客户端应用与 Web UI：Lit 控制台、原生应用
第 27–28 章
第九部分
部署与运维：部署方案、监控与故障排查
第 29–30 章
第十部分
高级主题与实践：多代理、ACP、TUI、实战项目
第 31–34 章
建议的阅读路线：
快速了解：阅读第 1 章，然后跳到感兴趣的部分
系统学习：从第 1 章开始顺序阅读
动手实践：在阅读过程中同步参考第 34 章的实战项目
源码版本说明
本书基于 OpenClaw v2026.2.x 版本的源码进行分析。具体对应的 package.json 版本号为 2026.2.6-3。源码仓库地址：
建议读者将源码克隆到本地，以便在阅读时随时对照：
由于 OpenClaw 是一个活跃维护的项目，后续版本的代码可能与本书描述有所出入，但核心架构和设计理念应该保持一致。
预备知识
阅读本书需要以下基础知识：
TypeScript / JavaScript 基础：变量、函数、类、模块、Promise/async-await
Node.js 运行时概念：事件循环、模块系统（ESM）、Buffer、Stream
基本的网络知识：HTTP、WebSocket、TCP/IP
命令行操作：终端使用、npm/pnpm 包管理
Git 版本控制：克隆、分支、标签
以下知识有帮助但不是必需的——本书会在需要时进行讲解：
Docker 容器化
大语言模型（LLM）的基本原理
数据库（SQLite）
WebSocket 协议细节
浏览器自动化（Playwright/CDP）
约定
源码路径相对于 OpenClaw 仓库根目录，例如
src/gateway/server.ts中文术语首次出现时会标注英文原文，例如 "控制平面（Control Plane）"
代码片段以 TypeScript 语法高亮显示
每个文档标注生成所使用的 AI 模型和 Token 消耗量
让我们开始吧。
Last updated