夜雨聆风
手搓一个最小的龙虾:OpenClaw 实战教程(上)
本教程旨在深入讲解如何从零构建一个最小化的 AI 代理（agent），基于开源项目 OpenClaw（俗称”小龙虾”）。
通过本教程，你将掌握：
-
🤖 AI 代理的基本概念及其演变历史，从 Cloud Code、Cursor 到 OpenClaw -
❤️ 小龙虾的核心设计机制：包括心跳（heartbeat）、记忆（memory）和技能（skill）系统 -
💻 手把手实现一个最小代理，涵盖代码结构、工具集成和部署方法 -
🚀 实践指南：如何在本地或云服务器上部署代理，并集成到即时通讯工具（如飞书） -
🏗️ 高级特性：代理团队（agent team）和任务系统的设计思路
一、OpenClaw 系统设计解析
核心架构：三个关键组件
OpenClaw 通过三个核心组件让 AI 具备”生命力”：
感知(Perceive) → 思考(Think) → 行动(Act) → 观察(Observe)
无尽循环，直至目标达成。
| 组件 | 作用 |
|---|---|
| 心跳（Heartbeat） | 定时触发，让 AI 主动”醒来”思考 |
| 记忆（Memory） | 让 AI 记住跨会话的重要信息 |
| 技能（Skill） | 可扩展的工具集，让 AI 调用各种能力 |
人格系统（Soul System）
Agent 的价值观与性格底座，决定了响应语气、处理偏好及行为边界：
-
定义回复语气（严肃/轻松/专业） -
设定核心任务优先级 -
配置禁忌与安全护栏
双层记忆架构
┌─────────────────────────────────────┐
│ SHORT-TERM Session 记忆 │ ← 维持当前对话上下文
├─────────────────────────────────────┤
│ LONG-TERM Vector 记忆 │ ← 语义检索，持久化存储
└─────────────────────────────────────┘
二、从 Cloud Code 到 OpenClaw：AI Agent 进化史
理解 OpenClaw 的创新，需要回顾 AI Agent 的发展历程：
| 阶段 | 代表产品 | 核心能力 | 局限 |
|---|---|---|---|
| 第一阶段 | Cursor | 代码补全 | 被动响应，无主动执行 |
| 第二阶段 | Claude Code | Agent Loop，工具调用 | 无定时调度，无记忆 |
| 第三阶段 | CoWork | 友好界面 | 能力有限 |
| 第四阶段 | OpenCode | 开源复刻 | 缺乏主动式机制 |
| 第五阶段 | OpenClaw | 心跳+记忆+技能+人格 | — |
OpenClaw 的核心创新：让 AI Agent 从”被动工具”变为”主动助手”——能主动思考、定时执行、持续记忆。
三、最小化 Agent 核心：Pi 框架
Pi 框架是 OpenClaw 的 Agent 核心，约 143 行代码实现四大核心工具：
四个基础工具
| 工具 | 作用 | 示例 |
|---|---|---|
| Bash | 执行系统命令 | pip install xxx |
| Read | 读取文件 | 查看配置文件 |
| Write | 创建/覆盖文件 | 生成代码 |
| Edit | 精确修改文件 | 改某一行 |
Agent Loop 执行流程
1. 接收用户输入消息
2. 拼接系统提示词 + 用户消息
3. 发送给大语言模型（LLM）
4. 模型决定调用哪个工具（如有）
5. Agent 执行工具调用，获取结果
6. 将结果返回给模型，生成最终回复
7. 将回复返回给用户
这种极简设计体现了”少即是多”——工具很少，但组合的可能性是无限的。
四、心跳机制（Heartbeat）：让 AI 主动思考
设计灵感
心跳机制的设计灵感来源于人类的心理活动——即使在安静的时刻，大脑也在后台处理各种信息：回顾今天发生的事情、思考未完成的任务、规划明天的安排。
执行流程
每30秒触发一次心跳检查：
✅ 检查是否有需要注意的事项
✅ 回顾记忆日志中的未完成任务
✅ 思考是否有值得主动做的事情
✅ 生成想法或行动计划
静默检查与去重
-
如果没有什么重要的事情，回复 HEARTBEAT_OK——静默结束，不打扰用户 -
去重机制：相同想法在 5 分钟内不重复提醒
开关机制
HEARTBEAT.md 文件存在 → 心跳启用
HEARTBEAT.md 文件删除 → 心跳关闭
非程序员也能通过简单的文件操作控制心跳！
五、人格注入（Soul System）
通过 SOUL.md 文件定义 Agent 的人格：
## 角色
You are Koda, a thoughtful AI assistant.
## 性格
Warm but not overly enthusiastic.
Prefer concise, clear explanations.
## 价值观
Honesty over comfort.
Depth over breadth.
将 SOUL.md 内容拼接在系统提示词最前面——大模型对开头部分注意力最强，人格定义影响所有后续输出。
六、双层记忆系统（Memory Store）
常驻记忆 vs 每日日志
| 类型 | 存储位置 | 内容 | 特点 |
|---|---|---|---|
| 常驻记忆 | MEMORY.md | 用户长期偏好 | 手动维护，长期有效 |
| 每日日志 | memory/YYYY-MM-DD.md | 当天重要事件 | 自动写入，按天归档 |
记忆读取
每次对话开始时，系统自动加载常驻记忆 + 当天日志，拼接到系统提示词中。Agent 不需要显式调用检索工具——记忆自动”在脑海中”。
七、定时调度（Cron）系统
三种调度类型
| 类型 | 命令格式 | 典型场景 |
|---|---|---|
| 一次性任务 | at 明天15:00 |
会议提醒 |
| 周期性任务 | every 3600（秒） |
每小时检查邮件 |
| Cron 表达式 | 0 9 * * 1-5 |
每周一到周五早9点 |
错误处理
-
连续错误 5 次 → 自动禁用任务 -
指数退避重试：1s → 2s → 4s
八、消息网关与多通道
Gateway 核心职责
消息接收 → 格式转换 → 消息路由 → 响应发送
支持的通道
飞书、Telegram、Slack、Discord、WhatsApp……每个通道有独立适配器，适配器模式让新增通道变得简单。
消息分页
不同平台有不同字数限制：
-
Telegram：4096 字符 -
Discord：2000 字符 -
飞书：根据类型变化
超长回复自动分页，不破坏代码块结构。
九、交付队列（Delivery Queue）
确保消息不丢失的核心机制：
消息进入队列 → DeliveryWorker 取出 → 发送
↓ 失败
指数退避重试（1s → 2s → 4s）→ 最多3次
↓ 仍失败
死信队列（Dead Letter Queue）
进程重启后，未发送的消息从持久化文件加载，自动继续发送。
十、下期预告
下一篇我们将手把手实现一个最小化的 OpenClaw Agent：
-
环境搭建与依赖安装 -
配置文件编写 -
第一个”Hello World” Skill -
接入飞书机器人 -
部署到服务器
敬请期待！
👉 欢迎关注我的公众号，获取更多 OpenClaw 实战教程