深度拆解 OpenClaw：一个开源 AI Agent 框架的架构设计
从技术视角全面剖析 OpenClaw 的系统架构，涵盖分层设计、智能体循环、双重记忆系统、安全机制等核心模块。
OpenClaw 是 2026 年初最热门的开源 AI Agent 框架之一，GitHub 星标在短短 4 个月内突破 14 万。它的核心能力是：让 AI 在本地运行、跨平台接入（WhatsApp、Telegram、Discord 等），并能真正操控电脑完成任务。
但多数人只看到了”用 WhatsApp 跟 AI 对话”的表象。本文从工程架构层面，把 OpenClaw 拆开来看。
一、技术本质：一个 TypeScript CLI 程序
很多人以为 OpenClaw 是 Python 项目，或者是 Web App——其实它是一个 TypeScript 编写的 CLI 应用程序，运行在你的本地机器上。
它做的事情：
- 在本地暴露一个 Gateway Server，处理来自各渠道（Telegram/WhatsApp/Slack 等）的消息
- 调用多种 LLM API（Anthropic、OpenAI、本地 Ollama 等）
- 在本地执行 工具（Tools）：读写文件、执行命令、操控浏览器
- 本地存储记忆，无需云端
这个定位决定了它的整体架构方向：本地优先、隐私可控、可扩展。
二、六层架构总览
整个系统从上到下分为 6 个层级：
flowchart LR
L1["🖥️ CLI 层\n启动入口、环境初始化"] --> L2["🌐 Gateway 层\nWebSocket + HTTP"]
L2 --> L3["🔌 通道 / 插件 / 路由层"]
L3 --> L4["🤖 Agent 执行层"]
L4 --> L5["🧠 AI Provider 层"]
L5 --> L6["💾 持久化层"]
classDef layer fill:#1e293b,stroke:#00D4FF,color:#e2e8f0
class L1,L2,L3,L4,L5,L6 layer
每一层职责清晰、互不耦合，这也是 OpenClaw 能快速扩展到 10+ 通道、支持十余种 LLM Provider 的根本原因。
三、Gateway 层：控制平面的心脏
Gateway 是整个系统最核心的组件，默认监听 127.0.0.1:18789，提供 WebSocket + HTTP 双协议服务。
四层 WebSocket 协议栈
flowchart TD
A["连接层\n握手认证"] --> B["协议层\n帧校验"]
B --> C["方法层\n权限分发"]
C --> D["事件层\n流式广播"]
classDef nodeStyle fill:#1e293b,stroke:#00D4FF,color:#e2e8f0
class A,B,C,D nodeStyle
三道”总闸”防护
| 总闸 | 作用 |
|---|---|
| 连接总闸 | 握手阶段保护，非授权连接直接拒绝 |
| 权限总闸 | 基于 role/scope 的细粒度鉴权 |
| 带宽总闸 | 防止单连接拖垮整个系统 |
配置热重载
Gateway 监听配置文件变化，可热更新的配置直接生效，不可热更新的配置请求进程重启——零停机变更。
四、Lane 队列：优雅的并发模型
这是 OpenClaw 架构里最有意思的设计之一。
传统 async/await 代码在处理多个并发 AI 请求时，很容易出现竞态条件（race condition）和日志混乱。OpenClaw 的解法是 Lane-based Command Queue（基于泳道的命令队列）：
flowchart LR
SA["Session A"] --> LA["Lane A"]
SB["Session B"] --> LB["Lane B"]
CJ["Cron Job"] --> PL["并行 Lane"]
classDef input fill:#1e293b,stroke:#8B5CF6,color:#e2e8f0
classDef lane fill:#0f172a,stroke:#00D4FF,color:#e2e8f0
class SA,SB,CJ input
class LA,LB,PL lane
核心原则：默认串行，需要时才显式并行。
每个会话拥有独占的 Session Lane，所有会话共享一个 Global Lane。系统支持 6 种调度模式：
| 模式 | 行为 |
|---|---|
interrupt | 中断当前任务，立即执行 |
steer | 追加上下文，引导当前任务 |
followup | 排队等待，顺序执行 |
collect | 防抖批处理，合并短时间内的多条消息 |
queue | 普通排队 |
steer-backlog | 向已有任务追加背景信息 |
五、智能体循环（Agentic Loop）
这是 OpenClaw 真正”智能”的核心：
flowchart TD
U["💬 用户消息"] --> S["系统提示组装"]
S --> L["🧠 LLM API 调用"]
L --> D{输出类型?}
D -->|"文本"| R["✅ 回复用户"]
D -->|"工具"| T["⚙️ 执行工具"]
T --> C["追加上下文"]
C --> L
classDef start fill:#1e293b,stroke:#00D4FF,color:#e2e8f0
classDef process fill:#1e293b,stroke:#8B5CF6,color:#e2e8f0
classDef core fill:#0f172a,stroke:#00D4FF,color:#00D4FF
classDef decision fill:#1e293b,stroke:#8B5CF6,color:#e2e8f0
classDef success fill:#064e3b,stroke:#10b981,color:#e2e8f0
class U start
class S,T,C process
class L core
class D decision
class R success
循环直到 LLM 输出最终文本，或达到最大轮数（默认约 20 轮）。
上下文窗口守护
当对话越来越长，上下文窗口会逐渐耗尽。OpenClaw 设有两道防线：
- 软警告线 32,000 tokens：触发历史压缩，生成摘要替换旧对话
- 硬红线 16,000 tokens：直接拒绝请求，防止 API 报错
六、双轨记忆系统
记忆系统是 OpenClaw 实现”长期记忆”的基础，采用简单而务实的双轨设计：
存储层
会话转录（JSONL） 记忆文件（Markdown）
每行一个 JSON 对象 ◄──── MEMORY.md / memory/ 目录
工具调用 + 结果 用户偏好 + 项目上下文
检索层
混合检索方案，两者互补：
- 向量检索：基于语义相似度，用 SQLite 存储向量
- 关键词检索：SQLite FTS5 全文检索，支持精确短语匹配
设计哲学
OpenClaw 的记忆系统刻意保持简单：
- 无记忆合并算法
- 无定期压缩
- 旧记忆与新记忆权重相同，没有”遗忘曲线”
- 文件是人类可读的，随时可以手动编辑
这种简单性是刻意为之的：可解释性 > 复杂度。
七、浏览器工具：语义快照
OpenClaw 操控浏览器的方式很有创意——它不依赖截图，而是基于页面的 Accessibility Tree（ARIA 可访问性树） 生成文本化快照：
# 普通截图
大小：~5 MB，需要视觉 token，成本高
# 语义快照（OpenClaw 的方案）
- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
大小：~50 KB，纯文本，token 成本低 100 倍
这个设计背后的洞察是：浏览网页本质上是信息获取任务，不是视觉任务。
八、安全架构
工具执行审批
危险工具（如 bash 命令执行）在运行前，会向用户推送审批请求，等待 approve/reject。用户可以选择”允许一次”或”永久允许”。
以下命令构造会被默认拦截：
# 命令替换
npm install $(cat /etc/passwd)
# 重定向到系统文件
cat input > /etc/hosts
# 逻辑或链式危险命令
rm -rf / || echo "done"
配对机制
陌生设备发来的消息，需要用户手动审批配对码，approve 后才加入白名单。这保证了只有你授权的设备才能与 AI 交互。
九、架构设计哲学总结
| 原则 | 实现方式 |
|---|---|
| 默认串行 | Lane 队列，消除并发复杂度 |
| 简单可解释 | JSONL + Markdown，无黑箱 |
| 本地优先 | 所有数据存本地，隐私可控 |
| 统一抽象 | 屏蔽 LLM 供应商差异 |
| 安全可控 | Allowlist 机制 + 配对审批 |
| 高效感知 | 语义快照替代截图 |
OpenClaw 的架构不追求”最高深”，而是追求清晰、可控、可扩展。这也是它能在短时间内获得大量开发者认可的根本原因——好的工程哲学，让代码说话。