解剖龙虾:OpenClaw 四层架构深度拆解

当你在微信上发一条消息给 AI，几秒钟后收到它的回复——这中间到底发生了什么？一条消息要经过多少道工序，才能准确找到模型、拼出动态提示词、在上下文溢出时自动压缩，最终把回答送回你的手机？

2025 年 11 月，开发者 Peter Steinberger 用周末时间给自己做了个 WhatsApp 转发工具，顺手开源了。短短两个月，这个项目狂揽 10 万 GitHub Star，单周访客破 200 万，甚至在中国掀起了一阵“养龙虾”热潮。

这个经历了三次改名（从 Clawd 到 Moltbot，再到最终定名）、连吉祥物都换成龙虾的项目，就是如今名声大噪的OpenClaw。

然而，作为一名开发者，真正让你兴奋的肯定不是它有多火，而是这只“龙虾”里面到底长什么样？

如果你曾苦恼于市面上的教程大多停留在“教你写提示词”或“用 LangChain 拼个玩具 Demo”，渴望突破瓶颈，构建真正在生产环境落地的复杂 Agent 架构；或者，你正野心勃勃地想为这个 10 万 Star 的顶级开源项目提交核心 PR。

那么，继从 Claude Code 泄露的源码提炼出 Agent Harness 工程设计的核心原则后，我又用AI写了一本书——《解剖龙虾：深入 OpenClaw》，这就是你的必读指南。

这本书使用ebook-from-source skill 和 mdbook 构建，O’Reilly 动物书风格封面并加版画风格插画，6 篇 20 章，共 299 页。

私信公众号输入“openclaw”可下载全书

这本书在做什么：一次外科手术般的解剖

这本书的本质，是解剖一个全速运行的 Agent 系统。

解剖的工具不是手术刀，而是源码。全书围绕 OpenClaw 2026.4.15版本源码，顺着四层架构（Client → Gateway → Harness → Model）逐层拆解。从流量入口到模型末梢，每一步都精准标注了源码路径（如src/gateway/server.ts:42），每一条设计决策皆有据可查。

写作环境：Pi + ebook-from-source skill + github copilot（claude sonnet 4.6）。外部工具使用了 agent-spec、mdbook、gemini 等。

它不教你“怎么用”，而是剖析“怎么造”。

全书结构：从外壳到神经

为了降低认知负荷，本书放弃了枯燥的技术模块罗列，而是按“从外到内”的解剖顺序展开。就像你吃龙虾时，先看外形，再剥壳，最后品尝虾肉。

第一篇：全局鸟瞰——先画地图

👉 读后收益：建立系统大局观，让你在庞大的开源代码库中不再迷路。

第 1 章以一条 WhatsApp 消息的完整旅程为主线，建立全书的核心地图——四层架构：Client（客户端）→ Gateway（控制面）→ Harness（智能体脚手架）→ Model（模型调用）。每一层只调用下一层，不反向依赖。贯穿四层的横切层：Plugin SDK，让 60+ 提供商和 20+ 渠道全部通过统一注册合约接入。

第 2 章俯瞰整个代码库的目录结构、模块边界与依赖规则。四棵逻辑树（核心代码、插件、客户端应用、构建脚本）之间有严格的单向依赖：插件只能通过 Plugin SDK 接触核心，核心完全不知道具体插件的存在。

第二篇：控制平面——龙虾的中枢神经

👉 读后收益：掌握单进程长驻服务的设计哲学与优雅的配置管理。

第 3 章解释为什么Gateway服务器选择单进程而不是微服务架构（因为 WhatsApp 要求单会话、全局状态管理更简单、进程内事件广播几乎零成本），并详解三阶段启动流程和设备认证握手。

第 4 章 解释Gateway协议层，是技术亮点之一：用 TypeBox 定义协议 Schema，一份定义同时生成 TypeScript 类型、运行时校验器和 Swift 代码。macOS 客户端的网络层代码是自动生成的，永远和后端保持同步。

第 5 章展示如何用 Zod 实现配置子系统“配置即文档即校验”。最精彩的设计是doctor修复路径：检测到过时配置时，Gateway 不会偷偷改你的文件，而是提示你运行openclaw doctor —fix，把修复的权利和知情权留给用户。

第三篇：插件生态——龙虾的甲壳与附肢

👉 读后收益：直接复用这套插件注册机制，为你自己的系统打造高扩展性底座。

第 6 章分析 Plugin SDK 的核心设计——横切层的能力注册合约。Plugin SDK 不属于四层中的任何一层，而是在启动时为 Gateway 层、Harness 层、Model 层注册能力的基础设施。插件通过结构化的注册 API 声明自己能做什么。Gateway 控制激活范围（全量注册、仅元数据、仅配置），单个插件失败不会拖垮整个系统。

第 7 章解析 Provider（模型提供商）插件的三层抽象：传输层（HTTP/SSE）、流式解析层（按”流式行为族”分组）、认证轮换层（多 API Key 自动冷却切换）。最精巧的是FailoverError+FallbackSummaryError的组合。不是报一个笼统的”出错了”，而是给你一份完整的“尝试了哪些 Key、哪个模型、多久后可以重试”的诊断报告。

第 8 章展示 Channel（消息渠道）插件的“稀疏能力适配器”设计：每个渠道只实现自己需要的接口方法，不需要的方法留空就好。WhatsApp 有 pairing（配对）和 threading（群组话题），而一个简单的 HTTP Webhook 渠道可能只需要接收消息。

第四篇：推理引擎——龙虾的核心肌肉

👉 读后收益：学到最值钱的“省流秘籍”，大幅降低 API 调用成本与延迟。

第 9 章路由与会话管理：session key是一个结构化字符串（编码了渠道 + 对方 ID + 线程），保证同一对话的消息始终路由到同一个 AI 会话。WeakMap缓存让路由查找几乎零成本，配置变更时自动失效。入站去重机制会在用户“手抖连发三条”时合并为一次推理。

第 10 章Skill 系统：Skills 是 Markdown 文件(SKILL.md)，不需要写代码就能扩展 AI 行为。6 个来源目录按优先级覆盖，提示词预算用两阶段策略控制。先退化到名称摘要，再截断。

第 11 章是全书最精彩的一章——系统提示词的字节级稳定设计。为了最大化 AI API 的 KV Cache 命中（也就是省钱、省时间），系统提示被分成“稳定前缀”和“动态后缀”两部分，中间用 HTML 注释做分界。三个归一化层确保内容在字节级别完全确定：换行符统一、尾部空格清除、能力 ID 按字母排序。这意味着同一会话的连续两轮对话之间，前缀部分逐字节相同，AI 服务商的缓存能完美命中。

第 12 章 Agent/Pi 推理引擎的双队列执行：会话级串行（同一对话不并发）+ 全局并发控制。三级渐进式故障恢复——轮换 API Key（最便宜）→ 切换备用模型（较贵）→ 报结构化错误（给用户清晰的诊断信息）。

第 13 章会话压缩（Compaction）：当对话历史超过模型的上下文窗口时，自动把旧消息压缩成摘要。分块摘要 + 每块独立重试 + 15 分钟安全超时 + 失败后回退到原始截断。

第五篇：多智能体与记忆——龙虾的高级神经系统

👉 读后收益：跳出“单次对话”思维，设计具备长程记忆与安全边界的真智能体。

第 14 章工具系统的 7 步策略管道：从预设配置到最终允许列表，每一步只能“减”不能“增”——安全层永远只能收紧、永远不能放松。Bash 工具有独立的三级安全模型（拒绝/白名单/完全授权），Docker 沙箱执行时自动映射路径。

第 15 章多智能体的生命周期管理：用时间戳（而不是状态枚举）来追踪 Agent 状态，这样即使分布式事件乱序到达也能正确判断。15 秒的错误宽限期防止瞬态错误杀死成功的任务。

第 16 章是另一个亮点——三层记忆架构 + 梦境系统。L1 工作记忆（上下文窗口）→ L2 主动记忆（每日日志）→ L3 长期记忆（MEMORY.md + LanceDB 向量检索）。最有趣的是“做梦”机制：空闲时运行“浅睡”（消化日志）和“REM 睡眠”（用 4 维置信度公式决定哪些记忆值得长期保留）。

第 17 章后台任务系统的韧性设计：Cron 任务在隔离会话中执行，“锁内标记、锁外执行”避免长时间推理阻塞调度器，看门狗防止调度器静默死亡。

第六篇：集成边界与工程原则

👉 读后收益：提炼顶级开源项目的方法论，直接转化为团队的架构 Checklist。

第 18 章MCP 双向实现：既是 MCP 服务器（暴露消息能力给 Claude Desktop），又是 MCP 客户端（连接外部 MCP 服务器）。权限审批用“频外协商”——用户在任意渠道回复yes abcde即可批准，无需专用审批 UI。

第 19 章operator 客户端的统一 WebSocket 协议：macOS/iOS/Android/Web/TUI 这五类直连 Gateway 的客户端共享同一套握手协议，但角色分离（Operator 和 Node 有完全不同的权限模型）。序列号间隙补偿处理网络断连时的状态同步。

第 20 章从全书源码分析中提炼 7 条可迁移的工程原则，每条都附带“什么时候不该用”的指导。

你的进阶路线图：如何阅读本书

不同背景的读者，可以通过不同路径最大化这本书的价值：

目标：成为 OpenClaw 源码贡献者

建议从头到尾精读。前两章是你的必修导航图，后续章节对应的源码路径是你提 PR、修 Bug 的精准坐标。

目标：提升 Agent 架构能力的工程师

推荐带着问题跳读。做 API 优化的直奔第 11 章（提示词cache稳定）与第 13 章（会话压缩）；做多智能体协同的研读第 15 章与第 16 章（梦境记忆）；构建底层插件的死磕第 6 章（注册合约）。这些被真实流量验证过的设计，能让你的系统少走弯路。

目标：带队的技术 Leader 与架构师

时间紧迫？请直奔第 20 章。直接将提炼出的 7 条架构原则引入团队的内部技术分享或架构评审 Checklist。

写在最后

好的架构从来不是某个天才的灵光一现，而是在四层流转、 20 多种渠道、 60 多家模型提供商的极限业务拉扯中，一步步“蜕壳”演进而来的。

正如书中所言：

解剖一只龙虾，不是要把它拆坏，而是要在不破坏整体结构的前提下，把四层架构的每一层都翻开来看清楚。看完之后，你再见到一只活的龙虾，感受会完全不同。

理解并内化这些底层机制，就是你从“调参侠”、“API 搬运工”向“顶级 AI 基础架构师”蜕变的必经之路。

现在，手术刀已经递到了你的手上。🦞

私信公众号输入“openclaw”可下载全书

延伸阅读：

从 Claude Code 泄露源码中，我提炼出了 Agent 的 Harness 工程密码

#OpenClaw #AI #智能体 #Agent #龙虾 #harnesd #架构设计 #源码分析 #开源项目 #深度进阶 #ClaudeCode