构建篇：打开引擎盖

本篇目标： 从“驾驶员”进阶为“工程师”，理解 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如何用极简代码实现核心功能
• 第十一章：定制路径概览 —— 如果你已经有了具体的定制目标

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

Không có con đường tiêu chuẩn để học tập. Câu hỏi của bạn, sự tò mò và nhu cầu của bạn là sự điều hướng tốt nhất.

Hãy bắt đầu.