夜雨聆风
【OpenClaw 全面解析:从零到精通】第 002 篇:解剖“龙虾“—— 核心技术原理全解析
系列说明：本系列共计 20 余篇，全面介绍 OpenClaw 开源 AI 智能体框架。本文为系列第 002 篇，聚焦于 OpenClaw 的核心技术架构与工作原理。建议先阅读 第 001 篇：OpenClaw 的诞生与历史背景。
摘要
OpenClaw 采用独特的”三层解耦”架构，将系统分为 Gateway 网关层、Agent 智能体层和 Channels 渠道层。核心 Agent 基于”Lobster Loop”（龙虾循环）实现思考-执行-观察-反馈的闭环自主行动。本文深入解析 OpenClaw 各核心组件的设计哲学与技术实现，帮助读者从原理层面理解这一 AI 智能体框架的运作机制。
一、架构全景：一张图看懂 OpenClaw
在深入细节之前，我们先从整体上把握 OpenClaw 的架构设计。
OpenClaw 的整个系统可以用一个简洁的比喻来理解：如果把 OpenClaw 比作一个有机体，那么：
- Gateway（网关）
是它的神经中枢，负责协调所有信号的传递和路由 - Agent（智能体）
是它的大脑，负责思考、决策和规划 - Skills（技能）
是它的手脚，是真正与现实世界交互的执行单元 - Channels（渠道）
是它的感官，负责接收来自不同平台的输入 - Nodes（节点）
是它分布在各处的末梢神经，提供本地设备能力
这五个核心组件共同构成了 OpenClaw 的”身体”，而连接它们的则是基于 WebSocket 的实时通信总线。
┌─────────────────────────────────────────────────────────┐│ OpenClaw 系统架构 │├─────────────────────────────────────────────────────────┤│ ││ Channels (渠道层) ││ WhatsApp | Telegram | Discord | 飞书 | iMessage | ... ││ │ ││ ┌──────▼──────┐ ││ │ Gateway │ ← 神经中枢 ││ │ :18789/ws │ (WebSocket服务器) ││ └──────┬──────┘ ││ │ ││ ┌────────────┼────────────┐ ││ ▼ ▼ ▼ ││ Agent Memory Skills ││ (大脑) (记忆系统) (手脚执行) ││ │ ││ LLM API ││ (GPT/Claude/本地模型) ││ ││ Nodes (分布式节点) ││ Mac | Linux | Raspberry Pi | Phone │└─────────────────────────────────────────────────────────┘
二、Gateway 网关层：系统的”神经中枢”
Gateway 是 OpenClaw 架构中最关键的组件，也是整个系统的协调核心。
2.1 技术实现
Gateway 本质上是一个基于 Node.js v22+ 构建的常驻后台守护进程（Daemon Process），默认监听在 127.0.0.1:18789 端口，通过 WebSocket 全双工通信协议与系统各组件保持长连接。
# Gateway 进程运行状态示例netstat -tlnp | grep 18789tcp 0 0 127.0.0.1:18789 0.0.0.0:* LISTEN 1234/node
Gateway 的核心职责包括：
① 连接管理：维护所有 Channels、Agents、Nodes 与 Gateway 之间的 WebSocket 长连接，处理连接的建立、心跳保活与断线重连。
② 消息路由：接收来自各 Channel 的用户输入，根据路由规则分发给对应的 Agent 处理；将 Agent 的输出结果路由回对应的 Channel 进行回复。
③ 会话管理：维护跨平台的会话状态，同一用户在不同渠道（如先在 WhatsApp 问了一个问题，再在 Telegram 继续追问）可以共享同一个会话上下文。
④ 权限与认证：处理设备注册、API Key 验证、工具调用权限检查等安全相关事务。
⑤ 记忆系统托管：Gateway 负责管理 Agent 的长期记忆存储，包括对话历史的持久化和检索。
2.2 消息协议
Gateway 内部采用严格定义的消息协议，通过 TypeBox Schema 进行数据校验，支持三种消息类型：
|
|
|
|
|---|---|---|
req
|
|
|
res
|
|
|
event
|
|
|
这种标准化的消息协议设计，是 OpenClaw 能够灵活支持多种接入方式和扩展能力的基础。
三、Agent 智能体层：系统的”大脑”
Agent 是 OpenClaw 的核心决策单元，负责理解用户意图、制定执行计划并调用各类工具完成任务。
3.1 Lobster Loop：龙虾循环
OpenClaw 最具创新性的设计之一是其 Agent 的执行循环机制——Lobster Loop（龙虾循环），也被称为 Pi Agent 运行时。这一循环实现了 AI 智能体的”感知-规划-执行-反馈”闭环，包含四个核心步骤：
┌─────────────────────────────────────────────┐│ Lobster Loop（龙虾循环） ││ ││ ┌─────────┐ ┌─────────┐ ││ │ Think │───▶│ Act │ ││ │ (思考) │ │ (执行) │ ││ └────▲────┘ └────┬────┘ ││ │ │ ││ ┌────┴────┐ ┌────▼────┐ ││ │ Reflect │◀───│ Observe │ ││ │ (反馈) │ │ (观察) │ ││ └─────────┘ └─────────┘ │└─────────────────────────────────────────────┘
① Think（思考）：Agent 将用户请求、会话历史、系统提示词和可用工具列表一并发送给 LLM，LLM 输出下一步的行动计划（通常是一系列结构化的工具调用指令）。
② Act（执行）：Agent Runtime 解析 LLM 的输出，执行对应的工具调用，例如读写文件、执行 Shell 命令、调用外部 API 等。
③ Observe（观察）：收集工具执行的结果，包括成功输出、错误信息、副作用等，构建观察报告。
④ Reflect（反馈）：将观察结果追加到上下文中，判断任务是否完成。如未完成，则回到 Think 步骤，开始新一轮循环；如已完成，则生成最终回复返回给用户。
这种循环机制赋予了 OpenClaw 强大的自主任务执行能力，使其能够处理需要多步骤操作的复杂任务，而不仅仅是简单的问答。
3.2 系统提示词工程
每个 OpenClaw Agent 都有一个精心设计的系统提示词（System Prompt），它定义了 Agent 的：
- 人格与角色
：Agent 的名称、性格特点、工作方式 - 核心指令
：Agent 应该如何行动、优先级排序 - 可用工具列表
：当前 Agent 拥有哪些工具（Skills） - 记忆注入
：相关的历史对话和长期记忆片段
系统提示词采用动态组装机制：在每次 LLM 调用之前，Gateway 会根据当前上下文（当前渠道、任务类型、用户偏好等）动态构建最优的系统提示词，而不是使用固定的静态提示词。这一设计大幅提升了 Agent 在不同场景下的表现一致性。
3.3 多 Agent 协作
OpenClaw 支持配置多个独立的 Agent，每个 Agent 可以有不同的专长、权限和工具集。通过路由配置，不同来源的请求可以被分发给最合适的 Agent 处理，实现任务委托和负载均衡。
四、Skills 技能系统：系统的”手脚”
如果说 Agent 是 OpenClaw 的大脑，那么 Skills（技能）就是它真正与现实世界交互的手脚。
4.1 Skills 的定义方式
每个 Skill 由一个标准化的 SKILL.md 文件定义，这是 OpenClaw 最精妙的设计之一——用人类可读的 Markdown 格式来定义 AI 可执行的工具，既方便人类理解和修改，也方便 LLM 在推理时理解工具的用途。
一个典型的 SKILL.md 文件结构如下：
---name: file-managerdescription: 文件系统操作技能，可以读写文件、创建目录、搜索内容version: 1.0.0author: communitypermissions:- file:read- file:write---# File Manager Skill## 可用工具### read_file读取指定路径的文件内容。参数：path (string) - 文件路径### write_file将内容写入指定路径的文件。参数：path (string), content (string)### search_files在目录中搜索包含特定内容的文件。参数：directory (string), query (string)
4.2 内置 Skills 与 ClawHub
OpenClaw 内置了一批核心 Skills，涵盖最常用的操作：
|
|
|
|---|---|
| 文件系统 |
|
| 终端命令 |
|
| 浏览器自动化 |
|
| 记忆管理 |
|
| 系统集成 |
|
除内置 Skills 外，ClawHub 作为社区技能市场，提供了超过 1 万个由社区贡献的扩展 Skill，覆盖从代码审查、数据分析到电商运营、内容创作等几乎所有主流使用场景。用户可以像安装 npm 包一样，一键安装所需的 Skill：
# 安装一个社区 Skillopenclaw skill install web-searchopenclaw skill install notion-syncopenclaw skill install github-assistant
4.3 技能权限与安全沙盒
每个 Skill 都需要声明所需的权限（如 file:read、network:http、shell:execute），Agent 只能调用其权限范围内的工具。
对于高风险的工具调用（如执行 Shell 命令、删除文件），OpenClaw 提供了命令审批机制：在执行前向用户展示将要执行的操作，用户确认后才会真正执行。这一机制在实用性与安全性之间取得了良好平衡。
五、Channels 渠道层：系统的”感官”
Channels 层是用户与 OpenClaw 交互的入口，支持超过 20 种通信平台：
|
|
|
|---|---|
| 即时通讯 |
|
| 企业协作 |
|
| 苹果生态 |
|
| 命令行 |
|
| 桌面客户端 |
|
| Web 界面 |
|
每个渠道通过对应的适配器与 Gateway 连接，适配器负责处理各平台的协议差异，统一转化为 OpenClaw 内部标准消息格式。例如：
- WhatsApp 适配器
基于开源的 Baileys 协议库实现 - Telegram 适配器
基于 grammY 框架 - Discord 适配器
基于 discord.js 库 - 飞书适配器
通过飞书开放平台 API 实现
5.1 跨渠道会话共享
OpenClaw 支持跨渠道的会话上下文共享。用户可以在 Telegram 上开始一个任务，在 WhatsApp 上继续，在命令行中查看进度——三个入口共享同一个会话状态，实现了真正意义上的”全渠道 AI 助手”体验。
六、记忆系统：让 AI 真正”记住”你
OpenClaw 的记忆系统是其超越普通聊天机器人的关键能力之一。它采用”文件即真相（File-as-Truth）“的设计哲学，以 Markdown 格式将记忆存储在本地文件系统中。
6.1 记忆的分层结构
memory/├── daily/│ ├── 2026-03-16.md # 今日对话日志│ └── 2026-03-15.md # 昨日对话日志├── long-term/│ ├── user-profile.md # 用户偏好和习惯│ ├── projects.md # 项目相关知识│ └── contacts.md # 联系人信息└── working-memory/└── current-task.md # 当前任务上下文
6.2 语义检索
OpenClaw 引入了向量语义搜索能力（基于 OpenAI text-embedding 模型或本地 Embedding 模型），能够在海量历史记忆中快速检索与当前对话相关的内容，将相关记忆片段动态注入系统提示词，实现真正的”长期记忆”效果。
七、本地优先架构的安全设计
OpenClaw 的”本地优先”不只是一句口号，而是贯穿整个架构设计的核心原则：
数据存储：所有对话记录、记忆文件、配置信息默认存储在用户本地的 ~/.openclaw/ 目录，不上传至任何云端服务器。
模型 API 代理：当使用云端 LLM（如 GPT、Claude）时，API 请求由用户自己的密钥发起，OpenClaw 的服务器不经手任何对话内容。
Gateway 本地化：Gateway 默认只监听 127.0.0.1（localhost），外部网络无法直接访问，从源头上规避了远程攻击风险。
Docker 沙盒隔离：对于需要执行高风险操作的 Agent，OpenClaw 支持将其运行在 Docker 容器中，通过容器级别的资源隔离保护宿主机安全。
八、技术栈总结
|
|
|
|
|---|---|---|
| 运行时 |
|
|
| 包管理 |
|
|
| 通信协议 |
|
|
| 数据校验 |
|
|
| 向量搜索 |
|
|
| 浏览器自动化 |
|
|
| 容器化 |
|
|
| 存储格式 |
|
|
| LLM 支持 |
|
|
九、架构设计的哲学思考
OpenClaw 的架构之所以能够在短时间内赢得如此众多开发者的青睐，很大程度上源于其背后清晰的工程哲学：
简单而非简陋：架构足够简单，让开发者能快速理解；但在简单之下，每个设计决策都经过深思熟虑，具备足够的扩展空间。
解耦而非孤立：三层解耦让各组件可以独立演进，但通过标准化的 WebSocket 协议和消息格式保持紧密协作。
安全而非封闭：在提供强大执行能力的同时，通过权限系统、审批机制和沙盒隔离确保安全，而不是以限制功能换取安全。
社区而非封闭：SKILL.md 的开放格式和 ClawHub 的生态市场，让整个系统能够借助社区力量无限扩展能力边界。
这些哲学，正是 OpenClaw 能够从众多 AI 工具中脱颖而出的深层原因。
十、小结
本文系统解析了 OpenClaw 的核心技术架构，涵盖 Gateway 网关层、Agent 智能体层（Lobster Loop）、Skills 技能系统、Channels 渠道层和记忆系统五大核心组件。这种”三层解耦 + 闭环执行”的设计，是 OpenClaw 能够实现 AI 自主执行能力的技术基础。
掌握了这些原理，读者将能更好地理解后续文章中关于安装配置、功能使用和高级开发的内容。
参考资料
-
OpenClaw 官方文档 -
OpenClaw 技术架构深度解析 – CSDN -
OpenClaw 系统架构分析 – CSDN -
OpenClaw 源码深度解读 – CSDN -
OpenClaw 完全指南：从原理到实现 – 搜狐 -
OpenClaw 架构解析 – CSDN