OpenClaw 架构设计与核心模块深度研究

一、项目定位与设计哲学

OpenClaw 不是 AI 模型，而是一个开源（MIT）的 AI Agent 运行时框架（Runtime Framework）——它坐在 AI 模型与外部世界之间，作为一个常驻运行的单体运行时网关（Gateway），负责把自然语言指令转化为真实的系统操作。

定位公式：

OpenClaw = Gateway（网关） + Agent Runtime（运行时） + Skills（技能） + Memory（记忆）

五项核心设计哲学：

理念	说明
Local-first（本地优先）	数据不离开用户设备，记忆为本地 Markdown，配置为 JSON；使用 Ollama/vLLM 本地模型时内容永不外传
网关而非框架	不是 SDK/库，而是独立运行的控制平面进程
模型无关（Model-Agnostic）	一行配置切换 Claude/GPT/Gemini/DeepSeek 等，按任务路由不同模型
插件化内核	Skills、Channels、Providers 均可热插拔（v2026.3.22+ 全面插件化）
工程化 Agent	从聊天机器人升级为任务调度执行系统，强默认不阉割能力，危险路径暴露为操作者可控开关

命名含义： Claw（龙虾钳子）= 抓取/操控/执行能力；Open = 完全开源、社区驱动。项目前身：WhatsApp Relay → Clawdbot → Moltbot → OpenClaw（2026 年 2 月定名，曾成为 GitHub 历史上增长最快的仓库之一，达 250K+ stars）。

二、整体架构：Gateway-Centric（网关中心化）

OpenClaw 采用单一长驻 Node.js 进程架构，在 LLM（“Brain”）、本地执行能力（“Hands”）、持久记忆（“Memory”）与外部消息通道（Channels）之间编排通信。无微服务、无容器依赖、无跨进程复杂通信，靠 Node.js 事件循环天然处理并发，部署只需”一个二进制 + 一个配置文件”。

2.1 官方高层组件图

⚡ Gateway (ws://localhost:18789 / http)
   ├── 🔗 Channels (WhatsApp / Telegram / Discord / Slack / CLI / ...)
   ├── 💻 CLI (openclaw chat)
   ├── 🌐 WebChat (localhost:18789/chat)
   ├── 🧠 Brain (LLM)        ← 推理
   ├── 🤖 Hands (Exec)       ← 执行（shell / file / browser / http）
   ├── 💾 Memory (Local)     ← 记忆
   ├── 🫀 Heartbeat          ← 自治循环
   ├── 🧩 Skills             ← 能力扩展
   ├── 🛣️  Router            ← 消息分发（多 Agent）
   ├── 📡 Node Registry      ← 会话/节点追踪
   └── ✅ Exec Approval Manager ← 命令审批

2.2 源码级分层架构（src/）

┌──────────────────────────────────────────────────────────────────────────────────┐
│ CLI 层            entry.ts → run-main.ts → command-registry                      │
├──────────────────────────────────────────────────────────────────────────────────┤
│ Gateway 层（控制平面）  WebSocket 服务 · HTTP 服务 · 通道管理 · 热重载                 │
├──────────────┬──────────────┬────────────────────────────────────────────────────┤
│ Channel 层   │  Routing 层   │   Plugin 层                                        │
│ 多通道适配     │  路由+会话键   │  工具/通道/Provider 注册                            │
├──────────────┴──────────────┴────────────────────────────────────────────────────┤
│ Auto-Reply / Agent 执行层   dispatch → get-reply → agent-runner → embedded PI     │
├──────────────────────────────────────────────────────────────────────────────────┤
│ AI Provider 层    Anthropic · OpenAI · Ollama · Bedrock · ...                    │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 持久化 / 基础设施层   Config · Sessions · Media · Security · Cron · Daemon · Memory │
└──────────────────────────────────────────────────────────────────────────────────┘

三、核心模块逐一详解

3.1 Gateway —— 控制平面（核心进程）

源码位置：src/gateway/（主入口 server.impl.ts）
角色：系统中心，必须常驻运行。默认监听 127.0.0.1:18789，暴露两个接口：
- WebSocket：主控制协议（方法调用、事件推送）
- HTTP：同端口，用于 Hooks 回调、工具调用、Slack、OpenResponses
WebSocket 协议四层结构：
1. 连接层 ws-connection.ts + message-handler.ts：握手认证、Challenge/Response、10s 握手超时保护
2. 协议层 protocol/index.ts：AJV 帧结构校验、统一错误码
3. 方法层 server-methods.ts：authorizeGatewayMethod(role + scope) 鉴权 + 方法分发
4. 事件层 server-broadcast.ts + server-chat.ts：流式事件广播、慢消费者丢弃、幂等缓存

三个”总闸”（安全边界）：

总闸	源码	作用
连接总闸	`message-handler.ts`	`connect` 握手必须成功，否则关闭 WS
权限总闸	`authorizeGatewayMethod`	role/scope 不符直接拒绝
带宽总闸	`MAX_PAYLOAD_BYTES`	防止单连接拖垮系统

配置热重载 startGatewayConfigReloader：监听配置文件变化，可热更新的直接 applyHotReload，否则请求进程重启——无需手动杀死 Gateway 进程。

3.2 Brain —— 推理引擎（LLM）

源码位置：src/agents/、src/providers/、src/agents/auth-profiles/
角色：LLM 负责理解请求、推理、决定行动；Brain 从不直接触碰文件系统或网络，仅通过结构化 tool-call 协议向 Hands 请求动作。

Prompt Assembly（上下文装配）：每次 LLM 调用从多层组装上下文：

层级	来源	典型大小
系统身份	SOUL.md	200–1,000 tokens
Agent 指令	AGENTS.md, TOOLS.md	100–500 tokens
记忆	混合检索结果（`~/.openclaw/memory/`）	默认上限 2,000 tokens
激活技能	匹配的 SKILL.md 指令	每技能 100–500 tokens
会话历史	当前 session 近期消息	可变
通道消息	入站消息（带 `EXTERNAL_UNTRUSTED_CONTENT` 边界标记）	可变

模型路由（Model Routing）：按复杂度/成本把不同任务路由到不同模型（心跳用 Haiku、普通对话用 Sonnet、复杂推理用 Opus、隐私敏感用本地模型）。
Provider 回退：主 Provider 故障/限流时自动轮换候选 profile（runWithModelFallback()）。
Bootstrap 会话作用域（v2026.5.22+）：子 Agent 只加载 AGENTS.md+TOOLS.md，大幅降低 token 成本。
支持的 Provider：Anthropic、OpenAI、Google Gemini、xAI Grok、OpenRouter、DeepSeek、Ollama/vLLM（本地）、AWS Bedrock、Qwen、Moonshot、Together/HuggingFace、Cloudflare AI Gateway 等。

3.3 Hands —— 执行环境

源码位置：src/agents/pi-tools.ts、src/agents/openclaw-tools.ts

四类能力：

能力	说明	示例
Shell	终端命令	`ls` `git` `python` `curl` `docker`
Filesystem	读写改文件	建配置、改代码、管日志
Browser	Chromium 自动化（Playwright）	填表、爬页、截图
HTTP	API 请求	REST、webhook、API 集成

Tool-Call 协议：Brain 与 Hands 通过结构化 JSON 通信（tool_call → tool_result），可链式多工具调用并逐结果决策，循环直至产出最终文本。
执行审批（Exec Approval Manager）：命令执行前先生成 exec.approval.request（含规范化 argv、cwd、rawCommand），用户可见确切命令并批准/拒绝。策略：always / on-miss / off。
工具权限：命名 Profile（minimal / coding / messaging / full）+ 工具组 deny list（group:runtime 等）。
沙箱化：生产可把 Hands 隔离进 Docker（sandbox.type: docker），范围可为 agent/session/shared，模式 off/non-main/all；Workspace 访问级别 none/ro/rw。

3.4 Memory —— 记忆系统

源码位置：src/memory/
存储：本地 Markdown 文件（~/.openclaw/memory/），重启/更新/迁移后依然存活，随时间积累成知识库（preferences / contacts / projects / learnings / tools 等分类）。
混合检索（Hybrid Search，70/30）：
- 向量检索 70%：sqlite-vec 本地 embedding，无需外部 API
- BM25 关键词 30%：SQLite FTS5 全文检索
- 全部本地处理，不上传。
上下文预算：max_context_tokens（默认 2000）是最有效的降本杠杆。
Dreaming 模式（v2026.5+，memory-core 插件）：灵感来自睡眠阶段的后台记忆整合，在空闲时段去重、综合、组织记忆。三阶段：
- Light：摄入近 24h 日记，去明显冗余
- REM：7 天滑动窗口内识别模式与关联
- Deep：按 6 个信号（相关性/频率/新鲜度/多样性/可信度/效用）打分，晋升或归档
- 结果写入 DREAMS.md 供人工审阅。
可插拔后端：内置 Markdown、memory-core、PostClaw（Postgres+pgvector）、Redis、Qdrant、ChromaDB 等 12+ 选项。

3.5 Heartbeat —— 自治任务循环

角色：每个 Agent 的周期性自治任务循环（结合 Dreaming 集成），让 Agent 在无人干预时主动巡检、维护、推进待办。
配置：HEARTBEAT.md 定义自治任务；openclaw.json 里可指定心跳专用模型（如 Haiku 降本）。

3.6 Channels —— 通道（I/O 桥梁）

源码位置：src/channels/ + 各通道插件目录（src/discord/ src/imessage/ 等）
角色：消息的”入口”与”出口”，每个通道以插件形式注册（registerChannel({id, label, start, stop, send})）。
内置通道（部分）：Telegram、WhatsApp、Discord、IRC、Google Chat、Slack、Signal、iMessage 等共 26+ 平台桥接。
账号是一级实体：同一通道可运行多个 accountId，独立运行状态，故障隔离。

3.7 Router + Node Registry —— 路由与多 Agent

源码位置：src/routing/
路由匹配优先级（高→低）：peer 精确 → parent peer 继承 → guild+roles → guild → team → account → channel → default agent。
Session Key 设计（session-key.ts）：
- 私聊：agent:{agentId}:{channel}:{accountId}:direct:{peerId}
- 群聊：agent:{agentId}:{channel}:{accountId}:{peerKind}:{peerId}
- 作用：会话消息串联、并发按 session 隔离（Lane）、存储文件定位。
Node Registry：追踪已连接的执行会话与命令队列。

3.8 Auto-Reply / Agent 执行层 —— 最复杂的编排

源码位置：src/auto-reply/、src/agents/

执行流水线（5 子层）：

子层	文件	核心职责
调度控制	`dispatch.ts`	typing/block/final 事件、资源释放保证
消息编排	`dispatch-from-config.ts`	去重、Hooks、TTS
决策构建	`get-reply.ts`	路由解析、指令解析、媒体预处理
执行组装	`get-reply-run.ts`	系统前缀、队列策略、模型思考等级
Agent 调度	`pi-embedded-runner/run.ts`	Lane 排队、模型选择、执行循环
单次执行	`pi-embedded-runner/run/attempt.ts`	真实 LLM 调用 + 工具执行
事件订阅	`pi-embedded-subscribe.ts`	流式文本/工具事件分离收集
模型回退	`model-fallback.ts`	多候选模型轮换

Lane 并发模型：每个 Session 独占一个 Session Lane（队列），所有 Session 共享一个 Global Lane（全局并发控制）；消息先入 sessionLane 再入 globalLane。由 concurrency（最大并发）与 maxPending（最大排队）控制。
QueueMode（新消息处理策略）：interrupt（中断当前 run） / steer（追加到当前 run 上下文） / steer-backlog / followup（等当前 run 结束） / collect（合并批处理防抖） / queue（普通排队）。
上下文守护（防”越聊越炸”）：窗口预检 + 历史卫生 + 配对修复 + 压缩重试 + 超时快照兜底；硬红线 CONTEXT_WINDOW_HARD_MIN_TOKENS = 16000（触发拒绝），软警告 CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32000（触发压缩）。

3.9 Skills —— 能力扩展

角色：YAML+Markdown 定义的技能（来自 ClawHub 市场），教 Agent 何时/如何用工具。任何人都能写，是 Markdown 文件而非硬编码。
生态：ClawHub 上 13K+ 技能、162 个 Agent 模板（24 类），含 coding-agent、mcporter、notion、obsidian、browser、file、database、api 等。

3.10 Plugin 系统 —— 插件化骨架

源码位置：src/plugins/（loader.ts、registry.ts）
设计纪律（来自 AGENTS.md）：Core（src/**）必须对扩展不可知，扩展只能经 plugin-sdk、manifest、注入的 runtime helpers 与 api.ts/runtime-api.ts 跨越边界；Gateway 协议改动视为契约变更，须向后兼容或版本化。
v2026.3.22+：插件架构允许社区在不 fork core 的前提下扩展每一层（通道、工具、Provider、Hooks）。5.28 起进一步把重插件依赖移出 core，安装体积下降 52.8%、冷启动提速 5.1x。

3.11 持久化 / 基础设施层

子系统	源码	说明
Config	`src/config/io.ts`	TOML/JSON 配置，支持热重载
Sessions	`src/config/sessions/store.ts`	会话历史持久化，按 sessionKey 分区
Media	`src/media/store.ts`+`server.ts`	媒体文件管理，带 TTL 与安全校验
Security	`src/security/audit.ts`	操作审计日志
Cron	`src/cron/`	定时任务（会话清理、维护）
Daemon	`src/daemon/`	守护进程管理，保证 Gateway 常驻

四、请求生命周期（Request Lifecycle）

任意消息（来自通道/CLI/心跳）的路径：

1. 消息到达 → Router 按 channel/peer/account 匹配 Agent 绑定
2. 分发至该 Agent 的 Orchestrator
3. 加载相关记忆（混合检索）
4. 组装 Prompt（SOUL.md + memory + skills + history）
5. 发送至 LLM Provider
6. Provider 返回响应（含 tool calls）
7. Hands 执行工具调用（shell/file/browser/http）
8. 结果回喂 Brain（可循环）
9. 产出最终响应
10. 保存新观察 → 经原通道回复

外部消息全程包裹在 EXTERNAL_UNTRUSTED_CONTENT 边界标记中，防御 prompt injection。

五、六大设计原则

Single Process：单一 gateway 管理一切，垂直扩展为主。
Local-First：数据全落盘，除 LLM API 外无云依赖。
Model-Agnostic：换 Provider 只改一行配置，任务级模型路由。
Extensible：Skills 是 Markdown，Channels 是插件，从 ClawHub 按需安装。
Transparent：记忆可读 Markdown、配置 JSON、WS 用 JSON 文本帧、审批显式展示命令。
Security-Conscious：Gateway 默认绑定 localhost，challenge-response + 设备配对认证，外部内容加边界标记，工具执行走审批流（但安全姿态需主动配置）。

六、最新版本动态（截至 v2026.7.1，2026-07-13）

Control UI 大改版：对话/会话/工作区/用量统一管理；多 session 可并排、可拖拽分屏、刷新后保留布局；实时 Tasks 视图；Usage 页可对比各 Provider/模型/Agent/通道的花费占比（7/30/90 天图）。
官方移动端升级：iOS / Android / macOS App 重大更新；配对管理员可从 Control UI 生成移动端设置 QR/可复制码。
模型与 Provider 扩展：GPT-5.6 兼容、腾讯 Hy3（Tencent Hy3）、Meta Muse Spark 1.1、Gemini 3.1、GLM-5 等；更强的 Codex / coding-agent 工作流。
通道更新：Telegram / Slack / Discord / Apple Messages 各自大幅更新；远程浏览器控制、工作区终端、session、goals 改进。
稳定性：修复 Gateway crash loop、定时任务、session 等问题。
性能演进（5.22→5.28）：稳定冷启动提速 5.1x（9.8s→1.9s）、热启动 4.0x、峰值 RSS 降 15%、发布 tarball 缩小 59%、安装依赖数降至 300（较月峰值降 53%）。
安全修复：v2026.3.31 修补 Snyk 发现的文件沙箱 TOCTOU 漏洞（CVSS 9.4，GHSA-9p3r-hh9g-5cmg）——把文件操作移入 Docker 容器内而非主机侧校验路径；建议始终运行最新版。

七、安全机制小结

默认绑定 localhost；设备配对 + challenge-response 认证。
三层网关总闸（连接/权限/带宽）。
外部内容 EXTERNAL_UNTRUSTED_CONTENT 边界标记。
命令执行前显式审批（Exec Approval Manager）。
工具权限 Profile + 工具组 deny list；危险命令 blocked_commands（如 rm -rf /、dd）。
Docker 沙箱隔离 Hands；v2026.3.31 后文件操作在容器内校验。
安全审计日志（src/security/audit.ts）。

八、总结

OpenClaw 的本质是一个以 Gateway 为控制平面的单体 AI Agent 运行时：Brain（推理）、Hands（执行）、Memory（记忆）、Heartbeat（自治）、Channels（接入）、Skills（扩展）、Router（编排）各司其职又松耦合。其工程亮点在于本地优先 + 模型无关 + 彻底插件化 + 透明可审计，并依靠 Lane 并发模型、QueueMode、上下文守护等机制保证长时间可靠执行。v2026.7.x 系列在控制面 UI、移动端、模型生态与性能/安全上持续快速演进，是当下最活跃的开源 Agent 运行时之一。