OpenClaw小龙虾架构原理解析

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

在这里插入图片描述

公众号：码海寻道

本文基于 openclaw 仓库 main 分支的本地源码快照分析：package.json 版本为 2026.4.25，本地最近一次提交时间为 2026-04-26。下文将 OpenClaw 简称为“小龙虾”。

很多人第一次看到 OpenClaw，会把它理解成“又一个 AI 聊天壳子”。但如果认真翻一遍它的仓库结构，你会发现它根本不是一个单纯的聊天前端，而是围绕 Gateway、Session、Agent Loop、Plugin、Node 搭起来的一套个人 AI 助手运行时。

它解决的问题也不是“怎么调用一次模型 API”，而是下面这些更偏系统设计的问题：

怎么把 AI 放进 WhatsApp、Telegram、Slack、Discord 这些真实渠道里；
怎么让 AI 在多设备之间共享一个统一的大脑；
怎么让不同会话、不同身份、不同工具权限尽量隔离；
怎么在支持大量扩展能力的同时，不把核心系统做成一团巨石。

如果用一句话概括小龙虾，我会说：

OpenClaw 不是一个聊天机器人，而是一个本地优先的 AI 助手控制平面。

先给一个简化后的脑图：

消息渠道 / 控制端 / 设备节点 WhatsApp / Telegram / Slack / Web UI / macOS / iOS / Android │ ▼ Gateway（统一控制平面，WS/HTTP） │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ Session 路由 Agent Loop Canvas / Nodes 队列 / 持久化 Prompt / Tools 设备与可视化能力 │ │ │ └──────────────┴──────────────┘ │ ▼ Plugins / Skills / Models / Sandbox

这张图里最重要的不是“大模型”本身，而是 Gateway 被放到了架构中心。

一旦 Gateway 成为唯一控制平面，很多复杂问题都能集中解决：

会话状态由 Gateway 统一保存；
渠道连接由 Gateway 统一维护；
CLI、Web UI、桌面端、移动端都通过统一协议接入；
工具权限、沙箱策略、设备配对、安全审计都在同一层治理。

这就是 OpenClaw 和很多“前端包一层 LLM API”的项目最大的区别。

从源码目录看，小龙虾是一个典型的 pnpm workspace 单仓工程：

openclaw-source/ ├─ src/ # 核心运行时：CLI、Gateway、Session、Channels、Plugins、Security ├─ extensions/ # 大量内置插件：模型、渠道、搜索、语音、图像等 ├─ ui/ # Control UI，基于 Lit + Vite ├─ apps/ # macOS / iOS / Android 端侧应用 ├─ packages/ # Plugin SDK 等可复用包 ├─ skills/ # Bundled skills，给 Agent 的“操作说明书” ├─ docs/ # 非常完整的架构与配置文档 └─ openclaw.mjs # CLI 启动入口

从 pnpm-workspace.yaml 和各子工程配置里，能很清楚看出它的技术栈：

核心运行时是 Node.js + TypeScript + ESM；
仓库采用 monorepo，根包、ui 和 extensions/* 一起管理；
Web 控制台使用 Lit + Vite + Vitest；
macOS / iOS 端有独立的 Swift 工程和共享的 OpenClawKit；
Android 端使用 Kotlin + Jetpack Compose；
插件系统覆盖模型、渠道、搜索、语音、图像、视频、设备、内存等一整片能力面。

这意味着 OpenClaw 的定位根本不是一个“给模型套个网页”的小项目，而是一套可以长期运行的 AI 产品底座。

官方架构文档对 Gateway 的定位非常明确：一个长生命周期的 Gateway 拥有所有 messaging surfaces。

这里的 surface 不只是 WhatsApp、Telegram 这种聊天渠道，也包括：

CLI；
Web 控制台；
macOS 菜单栏应用；
iOS / Android 节点设备；
自动化任务与 Webhook；
Canvas / A2UI 这类可视化交互界面。

1. Gateway 统一持有连接和状态

在小龙虾里，客户端不是“各自直连模型”，而是都连接到 Gateway。Gateway 负责：

维护第三方渠道连接；
暴露统一的 WebSocket API；
校验请求与事件协议；
广播 agent、chat、presence、health 等事件；
管理 Session、路由、工具执行和设备状态。

这样做的好处很直接：

状态不分散：聊天记录和会话生命周期不会散落在各个客户端里。
接入一致：CLI、Web UI、移动端、桌面端都走同一套协议。
安全边界更清晰：认证、配对、审计都集中在 Gateway。
更适合常驻运行：它从设计上就更像一个 daemon，而不是一次性脚本。

2. Gateway 同时也是多端统一的协议中心

从文档看，控制端和节点设备都走同一个 WebSocket 服务，只是角色不同：

控制端：CLI、macOS app、Web admin 等；
节点端：macOS / iOS / Android / headless node，连接时声明 role: node。

这说明 OpenClaw 并没有把“移动端”做成一个单纯聊天壳，而是把手机、桌面、节点设备都看作 Gateway 网络中的能力节点。这就是它和一般聊天应用最不一样的地方。

如果把 OpenClaw 当成“AI 消息中间件”，它的主流程会非常清晰：

用户从某个渠道发来一条消息；
渠道适配器把消息交给 Gateway；
Gateway 根据绑定规则找到对应 Agent；
Agent 再解析到具体 Session；
Session 进入队列，按串行/并行规则调度；
Agent Loop 组装 Prompt、加载 Skills、调用模型、执行工具；
结果通过事件流返回；
如果开启了回复投递，再由对应渠道发回用户。

可以把它抽象成下面这条链：

Channel Inbound -> Binding Resolve -> Session Resolve -> Queue -> Agent Loop -> Tool Calls / Model Stream -> Persist Transcript -> Channel Outbound

1. Session 是它的上下文单元

OpenClaw 不是简单按“聊天窗口”记忆，而是按 Session 管理上下文。不同来源默认有不同的会话粒度：

私聊：默认共享 Session；
群聊：按群隔离；
房间 / 频道：按房间隔离；
Cron：每次新 Session；
Webhook：按 Hook 隔离。

这里有个非常关键的设计点：默认所有 DM 共享一个 Session。对单用户场景来说，这样很顺滑；但如果多人都能私聊同一个 bot，就可能串上下文。所以官方文档明确建议，多人场景应改成：

{ session: { dmScope: "per-channel-peer" } }

也就是说，小龙虾并没有把“连续性”和“隔离性”写死，而是交给 Session Scope 去配置。

2. Agent Loop 才是真正的执行主线

文档对 Agent Loop 的描述非常完整，它不是一次普通的 LLM 调用，而是一条完整流水线：

校验 agent 请求参数；
解析 Session 和运行上下文；
加载技能快照；
进入 runEmbeddedPiAgent；
订阅流式事件；
执行工具调用；
持久化 transcript；
产出最终回复或错误状态。

这条链路里有三个设计值得特别注意：

每个 Session 串行执行，避免多个 Agent Run 同时写同一份状态；
运行过程全程事件化，assistant / tool / lifecycle 都能被流式观察；
runId 和 wait 分离，调用方可以先拿到“已受理”确认，再决定是否等待结果。

这就让 OpenClaw 更像一个“可观察的任务系统”，而不是一次同步问答。

3. Queue 机制解决了真实通信环境里的消息风暴

OpenClaw 不是把每条新消息都立即扔给模型，而是加了一个 lane-aware queue。

核心规则很简单：

同一个 Session 的运行必须串行；
系统还可以设置全局并发上限；
渠道可以配置不同的队列模式，例如 collect、steer、followup。

这套设计很有现实意义。因为一旦 AI 真跑在 Telegram、Slack、WhatsApp 这种真实环境里，消息绝不会像 Playground 那样一来一回、整整齐齐。队列系统实际上是在解决真实通信环境中的三件事：

多条消息瞬间涌入时的并发冲突；
工具调用尚未结束时的上下文乱序；
会话文件、日志和执行状态的竞争写入。

这是我看小龙虾源码时很有感的一点：它明确强调自己的 system prompt 是 OpenClaw-owned，不是某个 agent runtime 的默认 prompt。

这意味着它把“模型如何被驱动”当成框架核心能力，而不是底层 SDK 的附属物。

1. Prompt 是多层拼装的

从系统提示文档看，小龙虾会为每次运行动态拼出一份 prompt，主要包括：

Tooling 说明；
Execution Bias；
Safety 约束；
Skills 列表；
Workspace 信息；
文档路径；
当前日期与时区；
Runtime 信息；
Heartbeat / Reasoning 等附加内容。

这背后的含义很明确：OpenClaw 不是把 Agent 理解成一个抽象的聊天体，而是一个 运行在特定工作区、带技能、带工具、带时空上下文的执行体。

2. Workspace 文件会被直接注入上下文

它默认会把下面这些文件作为 bootstrap context 注入：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
MEMORY.md

这件事非常关键。很多项目的“个性化”只是往 system prompt 里塞一句人设；但 OpenClaw 是把工作区本身当成 Agent 身份的一部分。也就是说，Agent 的人格、规则、工具说明、工作约束和记忆都可以文件化管理。

这也是为什么它更适合长期运行，而不只是临时问答。

3. Skills 不是功能模块，而是“给模型看的操作手册”

在 OpenClaw 里，Skill 的本质不是一段代码，而是一个带 SKILL.md 的目录。它更像：

对模型的额外操作指南；
对工具使用方式的长文档补充；
一种可装载、可过滤、可按 Agent 限定的 prompt 扩展层。

这比把所有工具说明都塞进 system prompt 更灵活，也比把能力完全硬编码在代码里更容易演化。

OpenClaw 的另一个鲜明特点，是 核心尽量瘦，能力尽量插件化。

从 VISION.md 和插件文档看，项目明确鼓励：

Core 保持精简；
可选能力优先通过 plugin 提供；
如果某个能力还不能插件化，优先扩展 Plugin API，而不是往 core 里硬塞一段定制逻辑。

这其实是非常成熟的架构观。

1. 插件分两类

OpenClaw 支持两种插件形式：

Native Plugin：带 openclaw.plugin.json 和运行时代码，真正参与进程内扩展；
Bundle Plugin：兼容 Codex / Claude / Cursor 风格目录，映射成 OpenClaw 可识别的能力包。

也就是说，它不是只支持“Node 模块插件”，还兼容更偏 AI 工具生态的 bundle 结构。

2. 插件覆盖面非常大

从 extensions/ 目录能看到，插件覆盖的不是某一个点，而是一整片能力面：

模型 Provider；
消息 Channel；
Browser / Search / Web Fetch；
语音、TTS、Realtime；
图像和视频生成；
Memory 后端；
Agent Harness；
设备配对、控制和自动化。

比如：

openai 插件不仅声明了 openai 和 openai-codex provider，还绑定了 codex-cli 后端；
whatsapp 插件则直接声明自己拥有 whatsapp channel。

这说明 OpenClaw 的插件不是 UI 级别的小装饰，而是 框架一级的能力注入点。

3. Hook 机制把扩展点前移到了执行链路里

插件还能挂很多 Hook，例如：

before_model_resolve
before_prompt_build
before_tool_call
after_tool_call
before_agent_reply
agent_end
message_received
message_sending
gateway_start
gateway_stop

这意味着 OpenClaw 的扩展模型不是“事后补丁”，而是 直接在 Agent 生命周期的关键节点做拦截和改写。从工程上看，这种设计的上限远高于只暴露几个工具注册接口。

很多开源 AI Agent 项目做到 CLI 就停了，但 OpenClaw 显然不是。

1. Web 控制台是一个独立 UI 工程

ui/package.json 很清楚地显示，控制台使用的是：

Lit
Vite
Vitest
Markdown 预览相关库

也就是说，它没有用 React 套一个庞大后台，而是选择了更轻的 Web Component / Lit 路线。对于一个“控制面 UI”来说，这个选择很合理：轻、快、依赖少、适合长期维护。

2. macOS / iOS 不是 WebView 壳子

apps/macos/Package.swift 和 apps/shared/OpenClawKit/Package.swift 说明，苹果端是相当认真地在做原生工程：

使用 Swift 6.x / Swift Tools 6.2；
抽出了共享的 OpenClawKit、OpenClawProtocol、OpenClawChatUI；
macOS 提供菜单栏应用和独立 CLI；
iOS 通过 project.yml 管理工程，并带 Share Extension、Live Activity、Watch App。

这说明 OpenClaw 在苹果生态里追求的是“原生节点和控制端”，而不是“手机上再包一个网页”。

3. Android 明确走的是 Kotlin + Compose 路线

apps/android/app/build.gradle.kts 里能直接看到：

Kotlin Compose 插件；
buildFeatures { compose = true }；
material3；
CameraX；
Kotlin 序列化、加密、Markdown、网络等完整依赖。

再结合 README 的描述，Android 节点支持的不只是聊天，还包括：

Connect / Chat / Voice；
Canvas；
Camera；
Screen capture；
Android 设备命令族。

这再次说明：小龙虾的“Node”不是被动客户端，而是 Gateway 可调度的能力终端。

OpenClaw 的安全文档写得相当坦率：它默认服务的是 personal assistant 场景，也就是单一信任边界下的个人助手，而不是敌对多租户平台。

这点非常重要。

1. 它的假设是“一个可信 operator 边界”

官方文档明确强调：

一个 Gateway 最好对应一个信任边界；
不建议多个互不信任的人共享同一个 Gateway / Agent；
如果要做敌对隔离，应该拆成多个 Gateway、多个 OS 用户，甚至多个主机。

这其实是成熟工程的表现。很多项目嘴上说“企业级”，实际根本没把威胁模型讲清楚；OpenClaw 至少在文档里把边界说透了。

2. Pairing 是第一层安全阀

小龙虾里的 pairing 分两类：

DM pairing：谁可以私聊触发 bot；
Node pairing：哪个设备可以加入 Gateway 网络。

默认策略下，陌生 DM 不会直接进入 Agent，而是先拿到一个配对码，等 owner 批准后才放行。这比“只要知道 bot 地址就能直接对话”的模型稳健得多。

3. Sandbox 是第二层安全阀

OpenClaw 允许把工具执行放进沙箱里，而不是永远直接跑宿主机。常见模式有：

off
non-main
all

并支持 Docker、SSH、OpenShell 等不同后端。

需要注意的是：被沙箱化的是工具执行，不是 Gateway 本身。Gateway 仍然是宿主机上的控制平面。这个设计很务实，因为真正需要降低 blast radius 的是 exec、文件读写、浏览器控制这些高风险能力，而不是把整个系统都塞进重隔离里。

如果只从“能不能接大模型”这个角度看，OpenClaw 并不是最轻的方案；但如果从“如何把 AI 变成一个长期在线、跨渠道、跨设备、可扩展的个人助手系统”这个角度看，它非常有代表性。

我觉得它最值得研究的地方，主要有五点：

1. Gateway-first

它不是前端优先，也不是模型优先，而是控制平面优先。

2. Session-first

它真正把“上下文如何隔离、如何复用、如何持久化”当成架构问题来处理。

3. Plugin-first

它让渠道、模型、工具、语音、设备能力都落到统一插件体系里，而不是把特性四处写死在 core 中。

4. Device-first

它把 macOS、iOS、Android 当作节点，而不是单纯的聊天窗口。

5. Security-aware

它没有假装自己是完美隔离平台，而是明确给出适用边界和加固路径。

当然，它的代价也同样明显：

体系复杂，理解门槛高；
配置面大，运维意识要求更高；
一旦接入真实渠道和真实工具，安全责任会立刻上升。

换句话说，小龙虾不是“开箱即用的玩具”，而是“愿意为真实能力付复杂度成本的一套 AI runtime”。

如果让我给 OpenClaw 一个更准确的定位，我会说：

它是一套面向个人 AI 助手的本地优先运行时：用 Gateway 统一渠道、设备、会话、工具和插件，再用 Session、Queue、Prompt、Sandbox 把这套系统真正跑稳。

所以，OpenClaw 最有价值的地方，不是它能接多少模型，而是它已经把“AI 助手从单轮对话升级为长期运行系统”这件事，做出了比较完整的工程答案。

GitHub: https://github.com/openclaw/openclaw
官网: https://openclaw.ai
文档: https://docs.openclaw.ai
架构文档: https://docs.openclaw.ai/concepts/architecture
插件文档: https://docs.openclaw.ai/tools/plugin

如果你愿意，我下一篇还可以继续写两条延展稿：

《OpenClaw 源码漫游：从一条 WhatsApp 消息到 Agent 回复，中间到底发生了什么》
《OpenClaw 插件机制拆解：如何给小龙虾增加新的 Channel / Tool / Provider》