DEEP RESEARCH · 2026-07-30

OpenClaw 架构设计 与
核心模块 深度解析

一个开源（MIT）的 AI Agent 运行时框架——坐在 LLM 与外部世界之间的常驻单体网关，将自然语言指令转化为真实系统操作。最新稳定版 v2026.7.1。

v2026.7.1最新稳定版 · 2026-07-13
250K+GitHub Stars
26+通道插件
13K+ClawHub 技能
01

项目定位与设计哲学

OpenClaw = Gateway + Agent Runtime + Skills + Memory

Local-first

本地优先，数据不离开设备；记忆为本地 Markdown，Ollama/vLLM 本地模型时内容永不外传。

网关而非框架

不是 SDK/库，而是独立运行的控制平面进程，统一编排 AI 与外部世界。

模型无关

一行配置切换 Claude/GPT/Gemini/DeepSeek，按任务路由不同模型。

插件化内核

Skills、Channels、Providers 均可热插拔（v2026.3.22+ 全面插件化）。

工程化 Agent

从聊天机器人升级为任务调度执行系统，危险路径暴露为操作者可控开关。

透明可审计

记忆可读、配置 JSON、WS 用 JSON 帧、审批显式展示命令，无黑箱。

命名含义：Claw（龙虾钳子）= 抓取/操控/执行；Open = 完全开源、社区驱动。前身：WhatsApp Relay → Clawdbot → Moltbot → OpenClaw（2026.02 定名）。
02

整体架构：Gateway-Centric

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

CLI 层 · entry.ts → run-main.ts → command-registry
CLI 启动入口
Gateway 层（控制平面）· WebSocket + HTTP · 通道管理 · 热重载
⚡ Gateway127.0.0.1:18789 · 常驻进程
Channel 层 · Routing 层 · Plugin 层
🔗 Channels26+ 平台桥接
🛣️ Routing会话键 + 多 Agent
🧩 Plugin工具/通道/Provider
Auto-Reply / Agent 执行层 · dispatch → get-reply → agent-runner
🤖 Agent 执行引擎Lane 并发 · QueueMode · 上下文守护
AI Provider 层 · 持久化 / 基础设施层
🧠 BrainLLM 推理 · 模型路由
🤖 Handsshell/file/browser/http
💾 Memory本地 Markdown + 混合检索
🫀 Heartbeat自治任务循环
03

核心模块逐一详解

Gateway控制平面src/gateway/

系统中心，必须常驻。默认监听 127.0.0.1:18789，暴露 WebSocket（主控制协议）与 HTTP（同端口）两个接口。

  • WebSocket 四层：连接层（握手/Challenge-Response/10s 超时）→ 协议层（AJV 帧校验）→ 方法层（authorizeGatewayMethod 鉴权）→ 事件层（流式广播/慢消费者丢弃）
  • 三道总闸：连接总闸（握手必须成功）/ 权限总闸（role+scope 不符拒绝）/ 带宽总闸（MAX_PAYLOAD_BYTES 防拖垮）
  • 配置热重载 startGatewayConfigReloader：可热更新直接 applyHotReload，否则请求进程重启
Brain推理引擎src/agents/ · src/providers/

LLM 负责理解、推理、决策；从不直接触碰文件系统/网络，仅通过结构化 tool-call 协议请求动作。

  • Prompt 装配：SOUL.md + AGENTS/TOOLS.md + Memory(混合检索) + 激活 Skills + 会话历史 + 通道消息（带 EXTERNAL_UNTRUSTED_CONTENT 边界）
  • 模型路由：心跳用 Haiku、对话用 Sonnet、复杂推理用 Opus、隐私敏感用本地模型
  • Provider 回退 runWithModelFallback()；子 Agent Bootstrap 作用域（v2026.5.22+）只加载 AGENTS+TOOLS 降本
  • 支持 Anthropic / OpenAI / Gemini / xAI / OpenRouter / DeepSeek / Ollama / Bedrock / Qwen / Moonshot 等
Hands执行环境src/agents/pi-tools.ts

执行 Brain 的决策。四类能力：Shell / Filesystem / Browser(Playwright) / HTTP。

  • Tool-Call 协议：tool_call → tool_result 结构化 JSON，可链式多工具调用并逐结果决策
  • Exec Approval Manager：执行前生成审批请求（规范化 argv/cwd/rawCommand），策略 always / on-miss / off
  • 工具权限 Profile（minimal/coding/messaging/full）+ 工具组 deny list；blocked_commands 拦截危险命令
  • Docker 沙箱隔离（scope: agent/session/shared；mode: off/non-main/all；workspace: none/ro/rw）
Memory记忆系统src/memory/

本地 Markdown 文件（~/.openclaw/memory/），重启/更新后依然存活，随时间积累成知识库。

  • 混合检索 70/30：向量检索 70%（sqlite-vec 本地 embedding，无外部 API）+ BM25 30%（SQLite FTS5）
  • 上下文预算 max_context_tokens（默认 2000）是最有效降本杠杆
  • Dreaming 模式（v2026.5+）：Light→REM→Deep 三阶段后台整合，6 信号打分晋升/归档，结果写入 DREAMS.md
  • 可插拔后端：内置 / memory-core / PostClaw / Redis / Qdrant / ChromaDB 等 12+
Channel · Router · Heartbeat接入与编排src/channels/ · src/routing/
  • Channels：消息入口/出口，插件化注册；26+ 平台；账号是一级实体，故障隔离
  • Router：8 级匹配优先级（peer→parent→guild+roles→guild→team→account→channel→default）；Session Key 设计实现会话串联与并发隔离
  • Heartbeat：每个 Agent 周期性自治任务循环（结合 Dreaming），HEARTBEAT.md 定义任务
  • Node Registry：追踪已连接执行会话与命令队列
Auto-Reply / Agent 执行层最复杂编排src/auto-reply/ · src/agents/

5 子层流水线：dispatch → dispatch-from-config → get-reply → get-reply-run → pi-embedded-runner。

  • Lane 并发：每 Session 独占 Session Lane，共享 Global Lane；concurrency + maxPending 控制
  • QueueMode：interrupt / steer / steer-backlog / followup / collect(防抖批处理) / queue
  • 上下文守护：硬红线 16,000 tokens（拒绝）/ 软警告 32,000 tokens（压缩）；预检+卫生+修复+重试+快照兜底
  • 模型回退 model-fallback.ts 多候选轮换
Skills · Plugin · 持久化扩展与底座src/plugins/ · src/config/
  • Skills：YAML+Markdown 定义（ClawHub 13K+ 技能、162 Agent 模板），教 Agent 何时/如何用工具
  • Plugin 系统：Core 对扩展不可知，扩展仅经 plugin-sdk/manifest/api.ts 跨越边界；v2026.3.22+ 社区可扩展每一层
  • 持久化层：Config(TOML/JSON+热重载) / Sessions(按 key 分区) / Media(TTL) / Security(审计) / Cron / Daemon(常驻)
04

请求生命周期

1
消息到达
2
Router 匹配 Agent
3
分发 Orchestrator
4
加载记忆
5
组装 Prompt
6
发送至 LLM
7
Hands 执行工具
8
结果回喂 Brain
9
产出最终响应
10
保存并回复
外部消息全程包裹在 EXTERNAL_UNTRUSTED_CONTENT 边界标记中，防御 prompt injection。工具调用可在步骤 6→8 间循环，直至 Brain 产出最终文本。
05

六大设计原则

01

Single Process

单一 gateway 管理一切，垂直扩展为主，部署极简。

02

Local-First

数据全落盘，除 LLM API 外无云依赖。

03

Model-Agnostic

换 Provider 只改一行，任务级模型路由。

04

Extensible

Skills 是 Markdown，Channels 是插件，按需从 ClawHub 安装。

05

Transparent

记忆可读、配置 JSON、审批显式展示命令。

06

Security-Conscious

localhost 绑定 + 设备配对 + 边界标记 + 执行审批。

06

最新版本动态（v2026.7.1 · 2026-07-13）

Control UI 大改版对话/会话/工作区/用量统一管理；多 session 并排分屏、刷新保留布局；实时 Tasks 视图；Usage 页对比各 Provider/模型花费占比（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 各自大幅更新；远程浏览器控制、工作区终端改进；修复 Gateway crash loop、定时任务。
性能演进（5.22→5.28）冷启动提速 5.1x（9.8s→1.9s）、热启动 4.0x、峰值 RSS 降 15%、tarball 缩小 59%、安装依赖降至 300。
安全修复v2026.3.31 修补 Snyk 文件沙箱 TOCTOU 漏洞（CVSS 9.4），文件操作移入 Docker 容器内校验；建议始终运行最新版。
07

安全机制

🔒
绑定与认证默认绑定 localhost；设备配对 + challenge-response 认证。
🚧
三层网关总闸连接 / 权限 / 带宽总闸，越界直接拒绝或限流。
🛡️
注入防御外部内容 EXTERNAL_UNTRUSTED_CONTENT 边界标记。
✅
执行审批Exec Approval Manager 执行前显式展示确切命令。
🚫
权限与拦截工具 Profile + deny list；blocked_commands 拦截 rm -rf /、dd 等。
📦
沙箱隔离Docker 沙箱；v2026.3.31 后文件操作在容器内校验（修复 TOCTOU）。