构建篇：打开引擎盖

本篇目标： 从“驾驶员”进阶为“工程师”，理解 OpenClaw 的内部机制，掌握自定义 Skills、接入新渠道和架构优化的能力。

2026年初，当OpenClaw迅速攀升GitHub趋势榜时，大多数人看到的是一个好用的工具。但在这背后，有一个更值得注意的趋势：AI Agent正在从"黑盒产品"变成"可理解、可修改、可重建的基础设施"。

在第一部分，你学会了"驾驶"——安装、配置、使用Skills、接入移动端。这项实用技能足以让你的日常效率提升一个量级。

但想象一下这个场景：

你：帮我把过去一周的重要邮件整理成周报
OpenClaw：好的，正在读取邮件... 奇怪，有些邮件没有显示在结果里
你：（困惑）为什么？是我的搜索词不对，还是它漏掉了？

作为驾驶员，你只能再试一次或换个说法。但如果你理解引擎是如何运转的，你就能定位问题：

• 是exec命令的文件匹配参数不正确？
• 还是read工具读取的文件范围不够完整？
• 或者是LLM在总结时压缩掉了重要内容？

这就是第二部分的起点：从"再试一次"到"我知道为什么"。

---

1. Why：为什么要理解底层

1.1 解决那些"说不清的问题"

使用AI工具时，最让人沮丧的不是"它做错了"，而是"我不知道它为什么错"。

让我们看几个真实的场景：

场景一：记忆丢失

你一周前告诉OpenClaw："我习惯用Tab而不是空格缩进。"今天它生成代码时，又用了4个空格。

作为用户，你只能再次纠正。但如果你理解它的记忆系统，你会知道：

• 用户偏好存储在MEMORY.md中
• 该文件有大小限制，旧内容会被压缩
• 更可能的是，你的偏好只是被当作了"对话历史"
• 解决方案是在AGENTS.md中明确写入编码规范

场景二：工具选择错误

你让OpenClaw分析项目代码结构，它用exec工具调用find命令时参数设置不合理，导致找不到关键文件。

理解工具系统后你会发现：

• 工具描述（description）的质量直接影响LLM的选择
• OpenClaw的提示词中可能缺乏对文件搜索最佳实践的具体说明
• 你可以通过修改TOOLS.md来优化工具描述，让LLM做出更好的选择

场景三：响应太慢

一次简单的文件查询要等十几秒。

理解架构后，你能定位到：

• 是Gateway到模型服务的网络延迟？
• 还是LLM的推理时间过长？
• 或者是消息在队列中的排队等待？
• 你可以通过openclaw logs查看具体哪个环节在耗时

这些问题的共同点是：表面上是"AI不听话"，实际上是"某个环节的配置或设计不符合预期"。当你理解底层机制，诊断时间能从几小时缩短到几分钟。

1.2 掌握AI时代的"元能力"

让我们坦诚地说：OpenClaw不会永远是最好的AI Agent工具。

回顾AI发展历程：2023年是AutoGPT的爆发期，2024-2025年各类Agent框架层出不穷。技术迭代的速度远超任何人的学习速度。

但有一些概念是跨框架、跨时代的：

概念	在OpenClaw中	在其他框架中
Agent Runtime	Gateway→Agent Runtime→Clients/Nodes架构	LangChain的Chains、AutoGPT的Executor
Agent Loop	接收→上下文组装→模型推理→工具执行→回复	几乎所有Agent的核心范式
记忆分层	SOUL.md(身份)+MEMORY.md(事实)+对话历史	向量数据库+缓存+上下文窗口管理
工具抽象	read/exec/edit/write核心工具	Function Calling、Tool Use、Plugin系统
多渠道接入	Telegram/Discord/Slack适配器	统一的Channel Interface

第二部分要给你的，就是这些底层概念的具体实现案例。

当你理解了OpenClaw的ReAct循环实现，看到LangGraph的节点设计时就会恍然大悟："哦，这是把循环的每个阶段显式建模为图节点"。当你理解了OpenClaw的提示词系统，再看任何新的Agent框架时都会本能地去寻找"它的系统提示词在哪里定义"。

这种能力不会过期。无论明年流行什么框架，你都能快速上手，因为你看穿的是本质，不是表象。

1.3 创造的可能性

这里有一个值得关注的事实：OpenClaw的官方Skills数量有限，但社区已经涌现出大量第三方Skills。

这些Skills是谁写的？是像你一样理解了底层机制的开发者。

• 编程助手Skill：让OpenClaw理解团队代码规范，自动生成符合规范的代码
• 股票分析Skill：连接交易API，每天早上推送定制化的市场分析报告
• 智能客服Skill：接入公司知识库，自动回答常见客户问题
• 个人知识管理Skill：自动整理笔记、提取待办事项、建立知识关联

这些不是OpenClaw官方提供的功能，而是社区开发者基于OpenClaw架构创造的。

当你理解了如何构建Skills、如何修改提示词、如何接入新的渠道，你就从"消费者"变成了"创造者"。

更进一步，如果你对某个特定场景有独特需求，现有的OpenClaw可能无法完美满足。这时候你可以选择：

• NanoClaw路线：用极小的代码量实现一个极简但专属于你的Agent
• Fork路线：基于OpenClaw源码修改，适配你的工作环境
• IronClaw路线：添加安全加固、审计日志、权限控制，满足合规要求

第二部分会展示这些路线的真实案例，让你看到从理解到创造的具体路径。

1.4 职业价值的延伸

让我们现实一点：学习这些能给你带来什么实际的好处？

根据AI开发市场的趋势观察：

• 能够熟练使用AI Agent工具的开发者，在就业市场上更具竞争力
• 能够开发定制Skills、接入企业系统的开发者，在自由市场上有较高的需求
• 能够基于Agent架构进行深度定制的技术顾问，项目价值通常在较高区间

这个市场的需求是真实的，且目前的供给相对不足。

更重要的是，这种技能具有累积效应。你今天理解的ReAct循环、明天掌握的Skill开发、后天学会的多渠道接入，这些能力会叠加在一起，让你在AI应用开发领域的竞争力指数级增长。

---

2. What：你会看到什么

第二部分不是源码阅读指南，而是一次架构探险。我们会从不同角度、不同深度来观察OpenClaw这个系统。

2.1 第一板块：解剖OpenClaw（第1-6章）

这一板块会像解剖精密仪器一样，逐层深入OpenClaw的核心机制。

第1章：核心定位与设计理念

探讨一个根本问题：Agent Runtime和Chatbot的本质区别是什么？

这不仅仅是"一个会执行一个不会"那么简单。你会发现：

• 为什么OpenClaw选择自托管而非云端托管
• 核心工具（read/exec/edit/write）背后的设计哲学
• WebSocket Gateway架构如何让系统保持松耦合
• 这些设计选择带来的优势与代价

第2章：整体架构解析

你会看到一张完整的架构图：

用户消息 → Gateway（WebSocket网关）→ Agent Runtime（决策核心）
                                              ↓
结果返回 ← Gateway ← 工具执行 ← LLM推理

我们会详细解释：

• Gateway如何处理来自不同渠道（Telegram/Discord/Web）的消息
• Command Queue如何管理命令队列、保证顺序、处理并发
• Agent Runtime如何分解任务、选择工具、管理状态
• Agent如何调用LLM、解析响应、处理错误

第3章：提示词系统

这是OpenClaw最独特的设计之一：用多个Markdown文件来定义Agent的"人格"和"知识"。

• SOUL.md：Agent的身份、性格、行为准则
• USER.md：用户画像、偏好、交互习惯
• AGENTS.md：多Agent协作时的角色分工
• TOOLS.md：工具的详细说明和使用指南
• MEMORY.md：长期记忆的存储格式
• HEARTBEAT.md：定时任务的触发条件
• skills/*.md：各个技能的特定指令

你会理解：

• 这些文件如何被组合成最终的系统提示词
• 热更新机制如何让修改立即生效
• 如何通过调整提示词来精细控制Agent行为
• Token限制的分配策略（多少给系统提示词，多少给对话历史）

第4章：工具系统

OpenClaw的核心能力来自于它的工具。我们会深入：

• 核心工具（read/exec/edit/write/memory_search/memory_get/subagent等）的实现原理
• 工具描述的撰写艺术（如何让LLM准确理解工具的用途）
• Skill的层次结构：从简单的描述到复杂的TypeScript实现
• 工具注册机制：动态加载、版本管理、冲突解决

第5章：消息循环与事件驱动

这是Agent的"心跳"。你会看到：

• Agent Loop的完整执行流程
• LLM如何根据当前状态选择下一个工具
• 心跳机制（Heartbeat）如何实现定时任务
• 错误处理与重试策略
• 超时控制与优雅降级

第6章：多渠道接入

OpenClaw可以同时运行在多个平台上。我们会探讨：

• Gateway如何集成不同平台的SDK（grammY、discord.js等）
• 消息格式的转换与标准化
• 跨渠道的状态同步
• 平台特定功能（如Telegram的按钮、飞书的卡片消息）的适配

2.2 第二板块：探索替代方案（第7-10章）

理解一个系统的最好方式，是看看其他人是如何解决同样问题的。

第7章：轻量化方案

• NanoClaw：极简TypeScript代码实现最核心的Agent Loop（第三方开源项目）
• Nanobot：精简版，接近生产可用（第三方开源项目）
• ZeroClaw：去除厂商依赖、完全本地运行的版本（第三方开源项目）

你会看到：复杂的功能可以被简化到什么程度？哪些功能是不可或缺的，哪些是可以牺牲的？

第8章：安全加固方案

• IronClaw：企业级安全架构（第三方开源项目）
  • 权限控制：哪些工具可以被调用、哪些文件可以被访问
  • 沙箱隔离：防止Agent执行危险操作
  • 审计日志：记录每一次工具调用和LLM交互
  • 敏感数据保护：API密钥、个人信息的加密存储

第9章：硬件方案

• PicoClaw：运行在树莓派上的低功耗版本（第三方开源项目）
  • 硬件选型：为什么选择ARM架构？
  • 功耗优化：如何让Agent在电池供电下运行数天
  • 离线能力：完全无网络环境下的本地推理

第10章：案例对比总结

我们会建立一个多维度的对比矩阵：

维度	OpenClaw	NanoClaw	IronClaw	PicoClaw
代码量	数万行	数百行	数万行	数千行
功能丰富度	极高	核心功能	高+安全	中
部署难度	中	极低	高	中
适用场景	通用	学习/原型	企业	边缘计算

以及一个决策树：根据你的需求（功能、安全、成本、硬件限制），应该选择哪个方案作为起点。

2.3 第三板块：创造你自己的（第11-15章）

这一板块是关于"动手"的，但不是枯燥的编码教程，而是基于真实场景的创造指南。

第11章：定制路径概览

不是四级难度的硬性分层，而是四种不同的"玩法"：

• 配置玩家：通过修改JSON和Markdown文件，零代码实现个性化
• Skill开发者：为社区贡献新的工具集成
• 架构调整者：修改核心模块，适配特殊需求
• 造轮子爱好者：从零开始，理解每一个细节

每种玩法都有它的乐趣和价值，你可以根据自己的目标选择，也可以在不同玩法之间切换。

第12章：配置文件级定制

• ~/.openclaw/openclaw.json的完整结构解析
• Providers配置：如何接入不同的LLM（Claude、GPT、本地模型）

• 工具白名单：限制Agent的能力范围
• 安全策略：文件访问控制、网络请求限制

第13章：Skill开发实战

从最简单的描述型Skill到复杂的TypeScript实现：

• SKILL.md的Frontmatter格式
• impl/目录中的实现代码
• 异步处理与错误边界
• 调试与测试技巧
• 发布到社区仓库的流程

第14章：渠道接入实战

• 飞书接入：Webhook、机器人、审批流程
• 飞书接入：事件订阅、消息格式、卡片模板
• 编写自定义渠道适配器
• 多渠道配置的协同与冲突处理

第15章：完整定制案例

三个从真实需求出发的完整案例：

• 编程助手型：深度集成VSCode，理解项目结构，生成符合团队规范的代码
• 个人效率助手型：整合邮件、日历、笔记、待办事项的智能助理
• 智能客服机器人型：基于知识库的多轮对话系统，支持人工接管

每个案例都会展示：需求分析→架构选型→开发过程→部署维护的完整周期。

---

3. How：如何探索这一部分

3.1 三条入口路径

我们设计了三个不同的入口，你可以根据自己的状态选择：

路径A：原理派

如果你好奇"它是怎么工作的"，从第1章开始，按顺序读到第6章。这是理解最系统的路径。

路径B：对比派

如果你已经有一些使用经验，想知道"还有什么其他可能"，跳到第7章看案例分析。看到NanoClaw的极简实现，你会对"什么是最小必要功能"有全新的认识。

路径C：需求派

如果你已经有一个具体的定制目标（"我想让它接入公司的XX系统"），直接跳到第11-15章。边读边做，在实践中有针对性地回头查原理。

3.2 理解的层次

对于每一个概念，你不需要"全都要"。根据你的目标，选择理解的深度：

深度	适合人群	学习方式
概念级	大多数读者	知道"有这个模块"、"它负责什么"就够了
原理级	想深入理解的读者	理解它是如何工作的、为什么这么设计
代码级	想定制开发的读者	阅读源码、理解实现细节、能修改

例如，对于命令队列（Command Queue）：

• 概念级：知道"Command Queue负责序列化命令执行"，了解它在架构图中的位置
• 原理级：理解队列调度、并发控制、泳道模型（队列模式按渠道配置：steer/followup/collect/steer-backlog/steer+backlog/queue/interrupt）
• 代码级：能阅读并修改Command Queue的实现，添加新的队列模式或处理器

你可以在不同概念上选择不同的深度。比如在提示词系统上深入（因为你想定制Agent性格），但在渠道接入上保持概念级（因为你只用Telegram）。

3.3 实践的建议

虽然我们没有强制的"课后作业"，但我们建议你：

读一章，改一点

• 读完提示词系统的章节，试着修改你的SOUL.md，看看Agent的回应风格如何变化
• 读完工具系统的章节，试着写一个最简单的Skill（比如一个返回当前时间的工具）
• 读完架构解析的章节，试着用openclaw logs观察一次完整的消息流转

带着问题读

如果你在使用OpenClaw时遇到了奇怪的行为，把它当作一个探索的契机：

• "为什么它这次没有调用我预期的工具？" → 去第4章看工具选择的机制
• "为什么它忘了我们之前的约定？" → 去第3章看记忆系统的设计
• "为什么响应这么慢？" → 去第5章看消息循环的执行流程

做笔记，画图表

学习复杂系统的最好方式，是用你自己的方式重新组织它：

• 画一张你自己的架构图（即使不准确，也是你理解的外化）
• 列出你关心的概念和它们的关联
• 记录你遇到的问题和找到的解决方案

---

4. The Tradeoff：代价与收益

在进入之前，我们需要诚实地谈谈代价。

4.1 你需要投入的

注意： 学习这部分内容需要投入更多精力，但回报是长期的。

点击展开：学习代价详情

时间

第二部分的内容量比第一部分多。完整阅读所有章节需要一定的投入时间。如果要动手实践，时间会更长。

但记住，这不是考试，没有截止日期。你可以用一个月，也可以用半年。

认知负荷

这部分内容涉及：

• TypeScript/JavaScript代码（OpenClaw使用Node.js开发）
• 系统设计概念（事件驱动、消息队列、状态管理）
• AI原理（LLM的行为特性、提示词工程、ReAct范式）

如果你在某些领域不熟悉，可能需要额外查资料。这很正常。

挫败感

理解复杂系统不是线性的。你可能花了一小时读某章，却感觉什么都没懂。或者你觉得自己懂了，动手时却发现完全不是那么回事。

这种挫败感是学习曲线的正常部分。每一个真正理解OpenClaw的人都经历过。

4.2 你会得到的

解决复杂问题的能力

当你遇到OpenClaw的奇怪行为时，诊断时间从几小时变成几分钟。当你需要定制功能时，你知道从哪里下手。

跨框架的迁移能力

明年出现新的Agent框架时，你能在几天内上手，因为你看穿的是本质。

创造的可能性

从修改配置到开发Skills，从Fork修改到从零构建，你有一整套工具来表达你的想法。

潜在的经济回报

无论是求职时的竞争力提升，还是作为自由职业者的技能储备，这都是一个有市场需求的能力。

4.3 一个诚实的建议

不是每个人都需要深入这一部分。

如果你使用OpenClaw的过程中：

• 现有Skills已经满足了你的大部分需求
• 你没有遇到"无法理解"的奇怪行为
• 你对"底层原理"没有强烈的好奇心
• 你的时间和精力有限

那么，停留在第一部分是完全合理的选择。你可以随时回来，当某个具体的问题驱动你深入时。

最好的学习动机是"我需要解决这个问题"，而不是"我应该学完这个教程"。

---

5. 从驾驶员到工程师

让我们回到那个汽车的比喻。

第一部分教你驾驶——踩油门、打方向、看仪表盘。这让你能快速到达很多地方。

第二部分带你打开引擎盖——看引擎如何燃烧、变速箱如何换挡、电路如何控制。这不会让你开得更快，但当你听到异响时，你知道问题在哪里。当你想要改装时，你知道从哪里下手。当你面对一辆陌生的车时，你能更快地理解它。

更重要的是，你开始具备设计和制造的能力。

也许你不会真的去造一辆车。但当你理解了引擎的原理，你对"移动"的理解就永远改变了。你不再是交通工具的被动消费者，而是有能力参与创造的人。

AI Agent正在成为一种基础设施工具，就像数据库、Web服务器、操作系统一样。今天理解它的底层机制，就像1995年理解HTTP协议、2005年理解Linux内核、2015年理解Docker容器。

这种理解不会立刻变现，但它是长期投资。它会在未来的某个时刻，让你看到一个别人看不到的机会，或者解决一个别人无法解决的问题。

---

现在，选择你想开始的地方：

• 第一章：核心定位与设计理念 —— 理解Agent Runtime的本质，看看OpenClaw为什么被设计成现在这样
• 第七章：轻量化方案 —— 看看NanoClaw如何用极简代码实现核心功能
• 第十一章：定制路径概览 —— 如果你已经有了具体的定制目标

或者，如果你还不确定，可以先翻翻目录，看看哪个章节标题引起了你的好奇心。

ไม่มีเส้นทางการเรียนรู้มาตรฐาน คำถาม ความอยากรู้อยากเห็น และความต้องการของคุณคือคำตอบที่ดีที่สุด

มาเริ่มกันเลย