OpenClaw内部原理完全解析：从Gateway到记忆系统的AI Agent基础设施

OpenClaw（俗称 “龙虾 AI”）是一款本地优先、开源、可自托管的 AI 智能体执行网关，它一端对接 ChatGPT、Claude、Ollama 等主流大模型获取 “思考能力”，另一端连接本地设备、系统工具、通讯软件与第三方 API，让 AI 能将自然语言指令拆解为可执行步骤，自主完成文件管理、邮件处理、代码部署、日程安排等复杂任务，实现 “理解 — 规划 — 执行 — 反馈” 的全流程闭环。

OpenClaw：如何让AI真正成为能长期运行、可被信任的“数字伙伴”。

OpenClaw核心定位是：将即时通信渠道与编程智能体连接起来的Gateway网关系统，

作为消息入口、控制平面与节点协调中心存在。

本文将从架构、进程模型、调用链、记忆系统、定时机制、安全治理六个维度，层层拆解OpenClaw的内部原理。

---

一、整体架构：五层解耦的“AI操作系统”

OpenClaw最核心的设计哲学是**“云端大脑+本地肢体”**的结构。与LangChain等传统Agent框架不同，OpenClaw将系统拆分为五个清晰的层次，每层各司其职：

┌─────────────────────────────────────────────────────────────┐
│                    第一层：通道适配器                        │
│  WhatsApp / Telegram / Discord / iMessage / 飞书 / 微信    │
│              （将各渠道消息翻译为统一格式）                   │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    第二层：网关服务器                        │
│     ws://127.0.0.1:18789（控制平面）                        │
│     http://<gateway-host>:18793（Canvas主机）               │
│           路由 / 排队 / 调度 / 状态中心                      │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    第三层：智能体运行器                       │
│     会话管理器 → 上下文组装器 → 执行循环 → 记忆系统          │
│              （Pi Agent Runtime，RPC模式）                  │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    第四层：执行层                            │
│     本地节点（Shell/文件/浏览器） + 远端节点（iOS/Android）  │
│                 + 插件化技能系统（Skills）                   │
└─────────────────────────────────────────────────────────────┘

这种分层架构的价值在于低耦合：你想换一种工具实现，不用动上层决策逻辑；想换一个模型，也不用推翻整个执行系统。

---

二、Gateway网关：系统的“大脑”与单一事实源

2.1 进程模型与职责

OpenClaw的Gateway是一个长期运行的单进程服务，承担着整个系统的中枢职责：

• 维护所有消息渠道连接：WhatsApp、Telegram、Discord等渠道的长连接统一由Gateway持有
• 暴露WebSocket控制平面：默认监听ws://127.0.0.1:18789，提供实时双向通信
• 管理节点、会话与Canvas：协调所有连接的设备节点和UI界面
• 作为CLI、UI、移动节点的统一入口：所有客户端都通过Gateway接入

在工程上，Gateway同时扮演着状态中心、调度中心、安全边界集中点三个角色。任何系统级问题，最终都会回到Gateway。

2.2 网络模型与安全策略

OpenClaw官方推荐的部署模型是每台主机一个Gateway，原因非常明确：

• WhatsApp Web会话只能被单一进程安全持有
• Gateway本身维护关键运行状态
• 多Gateway场景必须做到强隔离

关键网络策略包括：

策略项	默认配置	说明
WebSocket绑定	127.0.0.1:18789	仅loopback，不对外暴露
Token认证	向导自动生成	即便是loopback也需token
Canvas端口	18793	HTTP文件服务，路径/__openclaw__/canvas/
非loopback绑定	需显式--bind tailnet --token	用于Tailnet或SSH隧道场景

节点（iOS/Android/UI）通过WebSocket连接Gateway，可经由LAN、Tailnet或SSH隧道接入。旧版TCP桥接已被弃用。

---

三、智能体核心：从Gateway到Pi-embedded的完整调用链

3.1 三层解耦：Orchestrator → Gateway → Pi-embedded

OpenClaw异于传统Agent框架的核心在于其**“云端大脑+本地肢体”**的架构：

• Orchestrator（大脑）：通常部署在GPU集群或云端，负责LLM推理和任务拆解
• Gateway（协议桥）：负责鉴权、流量整形，将LLM生成的JSON指令翻译成特定环境的指令集
• Pi-embedded（执行端）：运行在Mac/Linux或树莓派上，真正执行Python脚本、截图或鼠标操作

3.2 指令流转全链路

以“帮我查一下CPU温度并生成图表”为例，完整调用链如下：

1. Orchestrator: 识别出需要System_Monitor技能
   → 生成JSON: {"action": "get_cpu_metrics", "format": "chart"}

2. Gateway: 验证指令签名 → 查找在线Pi节点
   → 封装Protobuf协议 → 通过WebSocket发送

3. Pi-embedded Receiver: 收到消息 → 解包

4. Sandbox: 启动临时Python进程 → 挂载本地传感器权限

5. Skill Execution: 执行get_temp.py → 生成图表

6. Callback: 结果（图片二进制流）原路返回

3.3 关键源码机制：上下文压缩

在Gateway的gateway/dispatcher.py中，有一个关键的@route_to_executor装饰器。Gateway在此执行上下文压缩（Context Pruning）：

defdispatch_task(payload):
    # 提取意图，过滤掉无用的对话历史
    intent=extractor.analyze(payload.content)
    # 匹配最合适的Pi节点（可能有多个执行端）
    node_id=registry.get_active_node(payload.affinity)
    returnforward_to_node(node_id, intent)

工程避坑点：指令没响应的常见原因是Gateway层的registry未更新。OpenClaw默认使用Redis维护节点心跳，若Redis挂了或网络延迟大，指令会堆积在Gateway。

3.4 Pi-embedded的沙箱机制：Cell Isolation

进入packages/pi-embedded/runtime，会发现OpenClaw实现了一套名为**“Cell Isolation”**的沙箱机制：

核心执行引擎包含两个模块：

• Environment Snapshot：执行前快照当前环境变量
• Skill Loader：动态加载.ocskill文件

注意：自定义Skill找不到第三方库，是因为Pi-embedded默认在独立venv中运行。需要在claws.yaml中明确定义dependencies，执行端会在启动时自动静默安装。

---

四、记忆系统：三级架构与混合检索

4.1 为什么需要三级记忆？

OpenClaw的记忆系统设计者认为：人的记忆是分层的，AI也应该这样。

工作区目录结构：

~/.openclaw/workspace/
├── MEMORY.md              # 长期记忆：偏好、决策、持久事实
├── memory/
│   ├── 2026-03-05.md      # 短期记忆：今日日志
│   ├── 2026-03-04.md      # 昨日日志
│   └── ...                # 历史日志
├── sessions/              # 近端记忆：会话存档
├── USER.md                # 用户身份
└── SOUL.md                # Agent人格设定

三层记忆的分工：

层级	存储形式	内容	加载策略
短期记忆	Daily Log（append-only）	当天发生的事	自动加载“今天+昨天”日志
近端记忆	Sessions存档	完整会话历史	对话压缩时冲刷至此
长期记忆	MEMORY.md等	偏好、决策、经验	每次私聊自动加载

4.2 存储层：SQLite + 向量的混合方案

每个Agent对应一个独立的SQLite数据库，位于~/.openclaw/memory/{agentId}.sqlite：

-- 文件元数据表
CREATETABLE files (
    id INTEGERPRIMARYKEY,
    path TEXTUNIQUE,
    mtime INTEGER,      -- 增量索引关键
    hashTEXT           -- 内容哈希去重
);

-- 文本块表
CREATETABLE chunks (
    id INTEGERPRIMARYKEY,
    file_id INTEGER,
    textTEXT,
    embedding TEXT      -- JSON序列化的向量
);

-- 全文搜索虚拟表（FTS5）
CREATEVIRTUALTABLE chunks_fts USING fts5(text, content=chunks);

-- 向量搜索虚拟表（sqlite-vec）
CREATEVIRTUALTABLE chunks_vec USING vec0(embedding float[1536]);

关键设计：

• 增量索引：通过mtime和hash只重新索引变更文件
• 去重存储：相同文本块只存一次向量
• 优雅降级：若sqlite-vec未安装，回退到JS暴力计算

4.3 检索层：BM25 + 向量混合检索

纯向量检索有盲区——懂语义但不懂精确匹配（如搜环境变量名DB_PASSWORD可能抓瞎）。OpenClaw采用加权平均的混合检索：

asyncfunctionhybridSearch(query, options= {}) {
    constvecWeight=0.7;   // 向量权重
    constbm25Weight=0.3;  // BM25权重
    
    constvectorResults=awaitvectorSearch(query);
    constbm25Results=awaitbm25Search(query);
    
    // 取并集，任一方法认为相关即可进入候选池
    constallChunkIds=newSet([...vectorResults.map(r=>r.id), ...bm25Results.map(r=>r.id)]);
    
    // 加权计算综合得分
    // ... 返回排序后的结果
}

核心思路：用并集而非交集，只要向量或BM25任一方法认为相关，就有机会入选。

4.4 写入策略：Agent自己决定该记什么

OpenClaw的原则很激进：由Agent自己判断。系统提示词明确写着：“如果有人说‘记住这个’，写到文件里（不要只存在内存中）”。

写入分类逻辑：

• “我以后都用深色模式” → 稳定偏好 → preferences.md
• 解决了一个复杂问题 → 可复用经验 → learnings.md
• 开始一个新项目 → 项目状态 → projects.md
• 提到一个重要的人 → 人物信息 → contacts.md

还有一个精妙的机制叫预压缩记忆冲刷：当会话token数逼近上下文窗口上限时，系统主动提示Agent：“快把重要东西写到磁盘上，不然等会儿被压缩了就没了”。

---

五、定时系统：从被动应答到主动行动

OpenClaw的定时系统由四个组件构成，解决“AI不该等你说话才干活”的问题。

5.1 四个组件的分工

组件	触发方式	适用场景
Heartbeat	固定间隔（如30分钟）	定期巡检、状态监控
Cron	精确时间点或周期	日报生成、定时任务
Hooks	内部事件	Skill执行后自动学习
Webhook	外部HTTP调用	GitHub PR触发代码审查

5.2 Heartbeat：AI的“巡逻值班制”

配置示例：

{
  "agent": {
    "heartbeat": {
      "every": "30m"
    }
  }
}

AI醒来后读取HEARTBEAT.md中的检查清单。没事回复HEARTBEAT_OK（极低Token消耗），有事则整理情况通知用户。

5.3 Cron：精确到秒的任务调度

支持三种调度方式：

• at 2026-03-20T09:00:00：一次性执行
• every 2h：固定间隔重复
• cron表达式：如"0 9 * * 1-5"表示工作日9点

执行链路：

CronStore（任务存储）→ CronTimer（计算触发时间）→ executeJob（执行）→ 输出

---

六、安全与治理：让系统相信证据，而不是说法

设计哲学

OpenClaw的创始人提出一个关键洞察：让Agent去处理音频，传统做法是封装ffmpeg API，但“这些代码永远不可能比ffmpeg更成熟、更稳定、更可审计”。因此OpenClaw的选择是——不重复造轮子，直接让Agent调用系统里已存在的好工具（ffmpeg、curl、git等）。

安全边界三层设定

OpenClaw在治理层面有几个务实的设定：

1. 网络边界：默认绑定127.0.0.1，攻击面最小化
2. 工具白名单：Agent不能想调什么调什么
3. 高风险操作确认：模型说“我需要删文件”时，系统要求用户确认

更关键的是**“让系统相信证据，而不是相信说法”**——执行完命令，系统会看退出码、输出内容、产物是否存在，而非单纯相信模型返回的“执行成功”。

配置示例：访问控制

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

这些配置本质上是访问控制与风险收敛策略，而非功能开关。

设计智慧

与其简单罗列不足，不如将其视为工程权衡的艺术：

• 安全与自由的博弈：命令审批机制是在“AI自主性”与“用户掌控力”之间寻求平衡的务实之举
• 资源与普惠的矛盾：本地部署对硬件的要求，未来需云计算与边缘计算结合解决

---

总结

OpenClaw的价值，不在于它让AI“更聪明”，而在于它让AI“更可靠”。它把重心从模型能力转移到系统工程能力：工具怎么编排、状态怎么管理、风险怎么控制。这些问题不性感，但真正落地的时候，每一个都是坎。

正如其架构所揭示的：AI Agent的核心竞争力不在于模型本身，而在于“通道适配+动态技能加载+记忆系统”的工程化封装。这或许是OpenClaw给所有AI Agent开发者最大的启发——能聊很重要，但能交付更重要。