摘要： OpenClaw（前身 Clawdbot → Moltbot）是 2026 年最受关注的开源个人 AI Agent 框架之一——不是又一个 LangChain 封装，而是一个从 Gateway 进程模型、Session 并发控制、Skills 按需加载、Memory 文件系统到 Heartbeat/Cron 定时引擎都做了独立设计的生产级 Agent 操作系统。本文从源码与架构文档出发，逐层拆解它的核心设计。

在这里插入图片描述

1. 为什么值得深入 OpenClaw 的架构

2025-2026 年，AI Agent 框架的数量已经超过"前端框架"的数量。但大部分框架做的事情差不多：给 LLM 调个 tool、封装个 ReAct 循环、加个 vector DB 就说自己是"记忆系统"。

OpenClaw 走了一条完全不同的路。

它不是"LLM + 工具调用"的薄封装，而是一个以 Gateway 为中心、IM 为第一入口、文件系统为持久记忆、心跳为主动引擎 的个人 AI 操作系统。它的设计回答了 Agent 框架最棘手的问题：

  • 多个 IM 渠道（WhatsApp/Telegram/Discord/微信/飞书…）的消息如何统一路由到同一个 Agent？
  • 并发消息如何排队而不产生竞态？
  • Agent 的"记忆"在无状态 LLM 之上如何可靠持久化？
  • Agent 如何从"被动响应"变成"主动工作"？
  • Skills 如何在不撑爆 context window 的前提下扩展能力？

这些问题，每个做 Agent 的团队都会遇到。OpenClaw 给出的答案，是一套经过生产验证的微架构设计。

2. 整体架构：一张图看懂

OpenClaw 整体架构全景图

图：OpenClaw 六层架构全景——从 Channel 消息入口到 Memory 持久化与 Schedule 主动工作引擎

OpenClaw 采用单进程 Gateway + 多 Agent 目录隔离的部署模型。一个 Gateway 进程托管所有 Agent、Session、Channel，通过路径隔离而非进程隔离来区分不同 Agent 的边界。

3. Gateway：微内核中枢

Gateway 是整个系统唯一的长驻进程，同时承担五个角色：

3.1 五大角色

角色 职责 关键技术细节
① 唯一长驻进程 持有所有 Channel 会话（如 WhatsApp WebSocket），避免多进程状态冲突 单进程事件循环
② 消息总线 所有 Channel / Client / Node 流量必经 Gateway WebSocket + HTTP 双协议
③ 多 Agent 路由 根据 SessionKey 前缀将消息路由到不同 Agent agent:<agentId>:main
④ 认证与信任边界 Challenge-Response + Ed25519 设备身份；loopback 自动信任，跨机强制 TLS + 指纹 Pinning Ed25519 签名
⑤ 嵌入式 HTTP Host 同端口提供 Agent 可操作的 UI（如 /canvas/、/a2ui/） 复用 18789 端口

Gateway 对外暴露 42 个 RPC 方法，通过同一个 WebSocket Schema 统一了 HTTP、SSE 和内部 RPC 调用。核心代码保持数千行，其余所有能力都以插件形式存在——这是经典的微内核哲学。

3.2 Gateway 不做什么

关键设计决策：Gateway 从不直接接触 LLM API。它的职责边界是：

  • ✅ 协议转换、路由、认证
  • ✅ 消息排队和会话管理
  • ❌ 不接触模型调用
  • ❌ 不执行工具
  • ❌ 不管理记忆

这种编排与执行分离的设计，使得 Gateway 的可靠性极高——即使 Agent 执行引擎崩溃或 LLM API 故障，Gateway 仍然存活，Channel 连接不断。

4. Channel：IM 为第一入口的协议适配层

Channel 不是简单的"消息适配器"，而是一个完整的IM 域协作单元。

4.1 ChannelPlugin 接口设计

type ChannelPlugin = {
  id: ChannelId;                    // telegram, discord, qqbot ...
  capabilities: ChannelCapabilities;
  config: ChannelConfigAdapter;

  messaging?: ChannelMessagingAdapter;     // 消息收发
  outbound?: ChannelOutboundAdapter;       // 回复投递
  streaming?: ChannelStreamingAdapter;     // 流式协议适配
  threading?: ChannelThreadingAdapter;     // 线程/话题

  auth?: ChannelAuthAdapter;               // 认证
  pairing?: ChannelPairingAdapter;         // 设备配对
  allowlist?: ChannelAllowlistAdapter;     // 白名单

  gateway?: ChannelGatewayAdapter;         // Gateway 协议绑定

  agentTools?: ChannelAgentToolFactory;    // ⭐ Channel 反向给 LLM 提供工具
};

这个接口设计有一个非常重要的设计选择：agentTools。

Channel 不仅可以接收消息，还可以反向给 LLM 提供工具。例如 Telegram Channel 可以提供 send_telegram_message 工具，让 Agent 在执行任务后主动向特定聊天发送通知。

4.2 消息路由流程

外部平台消息
  ↓ Channel Adapter 标准化为内部 Inbound Message
  ↓ 访问控制 (dmPolicy / groupPolicy / allowFrom / pairing)
  ↓ 群聊激活判定 (mention gating)
  ↓ 路由匹配 (bindings → agentId)
  ↓ 生成 sessionKey
  ↓ Session Store 查/建会话
  ↓ Agent Run
  ↓ 生成 Reply Payload
  ↓ Channel Outbound 投递回原平台

路由决策不使用 LLM，完全基于确定性规则——保证 <1ms 延迟和完全可审计。

5. Bindings 路由引擎：确定性的 Agent 匹配

5.1 路由优先级

核心实现在 src/routing/resolve-route.ts，采用先层级、后顺序的匹配策略：

优先级 匹配维度 说明
1 binding.peer 精确用户匹配
2 binding.peer.parent 线程继承父会话绑定
3 binding.peer.wildcard 同类型通配
4 binding.guild + roles Discord 角色路由
5 binding.guild Discord 服务器匹配
6 binding.team Slack 团队匹配
7 binding.account Bot 账号匹配
8 binding.channel 整个通道匹配
9 default 回落默认 Agent

路由决策不使用 LLM——保证确定性、可审计、<1ms 延迟。这是 Agent 框架中少见的工程选择：LLM 不参与路由，因为路由必须是确定性的。

6. Session 与并发控制：两层 Lane 队列

6.1 Session Key——最核心的路由设计

OpenClaw 区分了两个关键概念：

概念 作用 稳定性
sessionKey 路由入口——“这条消息进哪个上下文桶” 稳定
sessionId 当前 transcript 文件 UUID 可变

sessionKey 格式（核心实现在 src/routing/session-key.ts）：

主会话:       agent:<agentId>:main
群聊:         agent:<agentId>:<channel>:group:<groupId>
频道/房间:    agent:<agentId>:<channel>:channel:<id>
DM（按人）:   agent:<agentId>:<channel>:direct:<peerId>
DM（按渠道）: agent:<agentId>:main  (dmScope=per-channel-peer)
Cron:         cron:<job.id>
Webhook:      hook:<uuid>

DM 隔离策略（dmScope）有四种粒度：默认 per-channel-peer（多人场景推荐）、per-peer、per-account-channel-peer、main（单用户场景）。

6.2 生命周期管理

用户消息 → 查 sessions.json → 找 sessionId
  → check daily reset   (sessionStartedAt, 默认凌晨 4:00)
  → check idle reset    (lastInteractionAt, 默认 60 分钟)
  → 到期 → 创建新 sessionId
  → 未到期 → 复用

支持 /new、/reset 手动切换 sessionId，/compact 手动压缩上下文。

6.3 两层 Lane 队列

这是 OpenClaw 并发控制的核心设计：

Session Lane:  每个 sessionKey 一条串行队列
               → 防止同一会话内的并发写入导致状态损坏
  ↓
Global Lane:   跨会话全局队列（默认并发度 4）
               → 防止单会话独占所有资源

队列模式有三种：

模式 行为
collect 合并积压消息
steer 注入当前回合
followup 下一回合排队

核心设计哲学：同一 session 内串行，跨 session 并发，全局有上限。

7. Agent 执行引擎：Pi Agent ReAct 循环

7.1 一次完整的 Agent Run

Agent Run 完整时序图

图：一次完整的 Agent Run——从 Gateway 接收消息到 ReAct 循环、工具执行、持久化和生命周期结束

7.2 并发隔离边界

OpenClaw 支持多 Agent，但隔离策略是路径隔离 + key 隔离而非进程隔离：

组件 路径 内容
Workspace ~/.openclaw/workspace-<agentId>/ SOUL.md、USER.md、MEMORY.md
AgentDir ~/.openclaw/agents/<agentId>/agent/ 认证配置、模型注册
Sessions ~/.openclaw/agents/<agentId>/sessions/ sessions.json + JSONL transcript

每个 Agent 有独立的三件套。 sessionKey 以 agent:<agentId>:... 为前缀，天然隔离。

7.3 容错：五层纵深防御

OpenClaw 的五层错误处理在 Agent 框架中属于最高配置：

层 机制 说明
1 错误分类 统一标准化 20+ LLM 提供商的错误格式
2 智能重试 指数退避 + 抖动策略，最多 160 次重试
3 Auth 轮换 多 API Key 熔断器模式
4 模型回退 跨提供商故障转移链
5 上下文恢复 Compaction 自动压缩防止溢出

8. Skills 技能系统：元数据注入 + 按需加载

Skills 是 OpenClaw 最具创新性的设计之一。

8.1 为什么不把 skills 全部注入 prompt？

答案很直接：token 成本。

如果系统有 50 个 skill，每个 SKILL.md 平均 3KB，全注入就是 150K tokens——还没开始对话就已经烧了一大笔钱。

8.2 元数据注入策略

OpenClaw 的做法是：只注入 Skills 的目录，不注入内容：

<available_skills>
  <skill>
    <name>github-issue-creator</name>
    <description>Create GitHub issues from conversation context</description>
    <location>managed/github-issue-creator/SKILL.md</location>
  </skill>
  <skill>
    <name>weather</name>
    <description>Get current weather via wttr.in</description>
    <location>bundled/weather/SKILL.md</location>
  </skill>
</available_skills>

每个 skill 的元数据开销约 100-200 字符，50 个 skill 总共约 10K 字符——比全量注入节省了 15 倍。

8.3 “Read Before Acting” 模式

System prompt 中有一条关键指令：

  1. 浏览 <available_skills> 中的描述
  2. 如果恰好有一个 skill 匹配当前任务：read 那个 SKILL.md，然后按照指令执行
  3. 如果多个 skill 可能匹配：选择最相关的一个
  4. 如果没有明显匹配的：不读任何 skill
  5. 每次最多读一个 skill

这条规则很精妙：

  • Agent 自己做 skill 选择（非硬编码规则匹配）
  • 被读取的 skill 内容出现在对话历史中（和其他 tool result 一样）
  • 自动占用 context window 的"公平份额"
  • Agent 读了 skill 后如果不适用，可以再读另一个

8.4 三级优先级加载

workspace/skills/        ← 最高优先级（个人定制）
  ↓
~/.openclaw/skills/      ← 通过 CLI 安装的 skill
  ↓
bundled skills           ← 框架内置 50+ skill

同名 skill 按优先级覆盖，不需删除低优先级的版本。

9. Memory 记忆系统：文件系统作为长期记忆

9.1 设计哲学

OpenClaw 的记忆系统有一个核心设计原则：文件系统就是数据库。

不做向量数据库——至少在第一层不做。而是用 Markdown 文件 + Agent 直接读写。为什么？

  • Agent 已经会读写文件——不需要额外的工具
  • Markdown 是人类可读的——你可以直接打开 MEMORY.md 看 Agent 记住了什么
  • 不需要维护向量索引——文件系统已经做了
  • 备份就是 git commit——已有工具链复用

9.2 记忆文件全景

~/.openclaw/workspace/
├── AGENTS.md         ← 员工手册：安全红线、记忆策略、群聊规范
├── SOUL.md           ← 灵魂：人格和语气
├── USER.md           ← 用户画像：偏好和习惯
├── MEMORY.md         ← 长期记忆：持久事实和重要决策
├── IDENTITY.md       ← 工牌：名称和头像
├── HEARTBEAT.md      ← 巡逻清单：心跳周期执行的任务
├── TOOLS.md          ← 环境配置：设备名、SSH、语音偏好
├── BOOTSTRAP.md      ← 出生仪式：首次初始化后删除
├── DREAMS.md         ← Dreaming 摘要：供人工审阅
└── memory/
    └── YYYY-MM-DD.md ← 每日笔记：当天活动的原始记录

9.3 按会话类型的加载策略

不是所有文件在所有场景都加载：

会话类型 加载文件 排除
主会话 全部核心文件 BOOTSTRAP（用后删除）
子 Agent / Cron 核心 5 个 MEMORY, HEARTBEAT, BOOTSTRAP
心跳模式 仅 HEARTBEAT.md 其余全部
群聊 核心文件 MEMORY（防止隐私泄露）

预算控制：单文件 ≤ 20K 字符，总计 ≤ 150K 字符。

9.4 Dreaming：后台记忆整合

“Dreaming” 是 OpenClaw 的后台记忆压缩机制，定期（默认每夜）执行：

核心原则：Daily files are raw notes; MEMORY.md is curated wisdom.

这个设计的巧妙之处在于——Agent 的日常笔记可能很啰嗦（raw notes），但 Dreaming 后提炼出的记忆是精炼的（curated）。人类记忆其实也是这么工作的：每天经历很多事，睡一觉后只记住重要的。

最新进展：Dreaming 已从 heartbeat 路径解耦，改为独立 isolated agent turns，解决 heartbeat 关闭时 dreaming 被跳过的问题。

9.5 Pre-compaction Memory Flush

当上下文接近窗口限制需要进行 Compaction（摘要压缩）时，Agent 会先静默执行一个 memory flush turn——提醒模型把重要信息写入磁盘，然后再压缩上下文。这确保关键信息不会在压缩过程中丢失。

10. Heartbeat + Cron：主动工作的双引擎

这是 OpenClaw 区别于"被动响应型"AI 助手的最关键设计。

10.1 Heartbeat：巡逻模式

维度 说明
频率 约每 30 分钟
执行位置 主会话（拥有完整对话历史）
触发内容 读取 HEARTBEAT.md，执行巡逻任务
静默机制 如果无事发生，回复 HEARTBEAT_OK，框架自动吞掉，用户无感知
成本 一个回合批量检查 N 件事

类比：保安巡逻——定时巡视一圈，没异常就默默记录，有异常才上报。

10.2 Cron：精确定时任务

维度 说明
精度 精确到秒
执行模式 systemEvent（注入主 session）或 agentTurn（独立 isolated session）
持久化 存在 ~/.openclaw/cron/jobs.json，Gateway 重启自动恢复
防尖峰 整点 stagger，最多随机延迟 5 分钟
失败处理 指数退避 + 自动禁用 + 告警

类比：闹钟——精确到秒，到点就做。

10.3 两者的本质区别

维度 Heartbeat Cron
时间精度 模糊（~30min） 精确到秒
执行位置 主会话 可隔离
静默机制 HEARTBEAT_OK 自动吞 按 delivery 配置
典型用法 “有空看看邮件” “每周一 9 点发周报”
上下文 全量 可精简 (lightContext)

11. Context Engine：可插拔的上下文管理

OpenClaw 提供了 ContextEngine 插件接口，让上下文管理策略可以完全替换：

interface ContextEngine {
  ingest(params): Promise<void>;           // 实时摄入单条消息
  assemble(params): AssembledContext;      // 构建模型运行上下文
  compact(params): CompactedContext;       // 摘要/压缩上下文
  info: EngineInfo;                        // id, name, ownsCompaction

  bootstrap?(params): Promise<void>;       // 初始化会话状态
  afterTurn?(params): Promise<void>;       // 回合后生命周期
  prepareSubagentSpawn?(params);           // 子 Agent 上下文准备
  onSubagentEnded?(params);                // 子 Agent 结束清理
}

关键细节：

  • assemble() 在运行时系统 prompt pipeline 之后执行——它精炼已处理的消息而不是替代 pipeline
  • 如果 afterTurn 已实现，运行时的回退摄入链不会触发——引擎接管所有摄入责任
  • 当 ownsCompaction: true 时，Pi Agent 的内置压缩被禁用——引擎全权控制

ContextEngine 的 promptAuthority 字段控制预检策略：

  • "assembled"（默认）——仅检查 assembled prompt 的 token 估算
  • "preassembly_may_overflow"——取 assembled 估算和会话历史估算中较大的值

11.1 上下文溢出的多级防护

第一级：Tool-result Compaction
  → 在工具循环内，压缩单个 tool result（保留头+尾）
  → 目标：75% 上下文窗口

第二级：溢出检测
  → Post-enforcement check at 90% of context window
  → 触发完整 session compaction

第三级：Pre-flight 压力估算
  → LLM-boundary pressure heuristic
  → 避免在 tool-heavy sessions 中低估实际消耗

第四级：Compaction 回退
  → summarizeInStages: 分块摘要 → 合并摘要
  → summarizeWithFallback: 超大消息的特殊处理

12. System Prompt 工程：行为契约而非角色设定

OpenClaw 的 system prompt 不是"你是一个 helpful assistant"这种角色扮演——它是一份工程级别的行为规范文档：

模块 作用
Safety Rails 非协商性安全约束（注入防御、敏感操作确认）
Tool Call Style 默认不叙述低风险操作，减少废话
URL 处理生命周期 强制 skill → web_fetch → browser 三级回退
Memory Recall 记忆召回规则——何时读 MEMORY.md
Runtime 元信息 host / model / channel 上下文
Skill Loading “Read Before Acting” 指令
Silence Rules NO_REPLY 判定条件

这不是 prompt engineering 的艺术——这是 prompt engineering 的工程。

13. 多 Agent 协作

OpenClaw 支持主 Agent 将子任务分派给子 Agent：

主 Agent (Coordinator)
  ├── 子 Agent 1 (独立 workspace + session)
  ├── 子 Agent 2 (独立 workspace + session)
  └── 子 Agent 3 (独立 workspace + session)

关键机制：

  • 通过 sessions_send / sessions_spawn 工具实现
  • 四种协作模式：Supervisor / Router / Pipeline / Parallel
  • 子 Agent 拥有独立的上下文和记忆空间
  • 会话线程 (SessionThread) 支持 per-subagent 的事件流

14. 核心设计哲学——OpenClaw 教给我们的事

回顾 OpenClaw 的整体设计，有七条核心原则贯穿始终：

14.1 微内核 + 插件化

Gateway 保持数千行核心代码，Channel/Tool/Provider/Memory 全是插件。新增一个 IM 平台不需要动核心——写一个 ChannelPlugin 就行。

14.2 文件系统 > 数据库

对于个人 Agent 来说，Markdown 文件 + Agent 直接读写 = 最简单的持久记忆。不需要 schema migration、不需要 vector DB、不需要维护索引。备份就是 git commit。

14.3 确定性的路由，非确定性的执行

消息路由（bindings）是确定性的规则匹配——不用 LLM。但 Agent 的行为（ReAct 循环）是 LLM 驱动的——非确定性。两个层级的边界非常清晰。

14.4 串行化 = 并发安全

同一 session 内串行执行，跨 session 并发。两层 Lane 队列的设计确保了任何时候都不会出现同一会话的并发写入。

14.5 给 AI “沉默权”

NO_REPLY 机制让 Agent 选择"不回复"——在群聊场景中这至关重要。不是每条消息都需要 Agent 回应，让 Agent 自己判断。

14.6 系统提示词是第一道工程

把所有需要 AI 遵守的规则、流程、边界都像写规范文档一样写进 system prompt。这不是临时性的 prompt tweak——这是 Agent 的"行为契约"。

14.7 主动比被动更强大

Heartbeat + Cron 让 Agent 从"等你说"变成"我去做"。这是从工具到助手的质变。

15. 写在最后

OpenClaw 不是又一个 LangChain 封装。它从进程模型、并发控制、记忆持久化、技能加载、定时引擎这五个维度，给出了一套生产级 Agent 框架的完整答案。

如果你正在设计或评估 Agent 框架，OpenClaw 的微架构至少值得你在以下四个方面对标：

  1. 路由层是否确定性和可审计？
  2. 并发控制是否基于串行化模型？
  3. 记忆系统是"真记忆"还是"把对话历史塞进 vector DB"？
  4. Agent 是否具备主动工作能力，而不仅仅是响应？

从一个工程师的视角来看，OpenClaw 最令人信服的地方在于：它的架构复杂度严格对应它所解决的问题的复杂度——没有过度设计，也没有简化到不可用。

编辑日期：2026-06-13

参考资料：OpenClaw 官方文档 (docs.openclaw.ai)，GitHub 源码 (github.com/openclaw/openclaw)，社区架构分析文章。

# 架构 # gateway # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

AtomCode 全新上线万亿代码模型 LongCat-2.0。限时 7 天免费体验！

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区