OpenClaw 源码分析

先说结论#

OpenClaw 这个仓库，不能把它理解成“一个 CLI 工具的源码”。

更准确地说，它是一个 个人 AI 助手平台的 monorepo，里面同时包含了：

Gateway 守护进程
浏览器 Control UI
CLI
多消息渠道接入层
技能系统
插件系统
多设备节点能力
模型认证与路由

项目整体定位#

官方 README 对它的定位非常明确：
OpenClaw 是一个运行在你自己设备上的个人 AI 助手，可以通过已经在用的渠道和它交互，而 Gateway 是控制平面。

这句话其实就决定了整个仓库的结构：

它必须有 常驻 Gateway
它必须有 多渠道适配
它必须有 浏览器和 CLI 控制面
它必须有 工作区 / 记忆 / 技能 / 插件
它必须有 设备节点和远程能力

所以 OpenClaw 的复杂度，不是因为“代码写乱了”，而是因为它要解决的问题本来就比普通代码 agent 大很多。

4 个核心概念#

1. Gateway#

Gateway 是整个系统的中心。

官方架构文档说明：

一个长期运行的 Gateway 持有所有消息面
CLI、macOS app、Web UI 都通过 WebSocket 连接它
节点设备也通过 WebSocket 连它
默认端口是 127.0.0.1:18789

这意味着 OpenClaw 不是“每次输入命令就临时跑一下”的架构，而是：

一个长期在线的 agent control plane。

2. Agent Workspace#

官方文档把 workspace 定义成“agent 的家”。

默认位置：

~/.openclaw/workspace

bash

它和 ~/.openclaw/ 的区别很关键：

~/.openclaw/ 更偏系统状态、配置、凭据、会话
~/.openclaw/workspace 更偏 agent 工作区、记忆、技能、上下文

这套设计说明 OpenClaw 把“agent 的长期状态”当成一等公民，而不是把所有内容都塞进进程内存。

3. Skills#

OpenClaw 的技能是 AgentSkills-compatible 的目录结构，本质是 SKILL.md + frontmatter + 指令。

这意味着它把“如何使用工具”这件事，显式建模成了可组合、可覆盖、可发布的技能系统，而不是全部硬编码在 prompt 里。

4. Plugins#

插件是 OpenClaw 的另一条主线。

官方插件文档写得很清楚，插件可以注册这些能力：

Gateway RPC
HTTP routes
Agent tools
CLI commands
Background services
Context engines
Skills

源码为什么会这么大#

OpenClaw 仓库大，不是单一原因造成的，而是多块东西叠加出来的。

1. 多渠道接入#

README 里列出的支持面非常多，像：

WhatsApp
Telegram
Discord
Slack
Signal
iMessage
WebChat

这些渠道的接入方式、消息模型、授权模式、媒体处理都不一样。
仅这一层就会拉高很多复杂度。

2. 多端节点能力#

官方架构文档里还提到节点可以暴露：

canvas.*
camera.*
screen.record
location.get

也就是说它不仅能“聊天”，还要能和宿主设备能力交互。

3. 插件和技能生态#

当一个系统支持：

内置能力
外部插件
工作区技能
本地技能
插件技能

它的目录和加载逻辑天然就会复杂起来。

4. 模型和认证系统#

OpenClaw 不是只绑定一个模型提供商。
它还支持模型认证、OAuth、API key、profile rotation、failover。

这部分一旦做成通用平台，复杂度就会明显高于单模型工具。

仓库目录#

`src/`#

可以把它理解成核心运行时与主流程胶水层。
像 Gateway、CLI 入口、主调度逻辑，通常会围绕这里展开。

`packages/`#

更适合放共享模块、公共能力、可复用运行时单元。
这类目录一般是 monorepo 的基础设施层。

`extensions/`#

这是 OpenClaw 的重点目录之一。
官方插件文档说明，很多功能是通过插件扩展进来的，所以这里很可能就是内置扩展与 provider / channel / tool 能力的核心承载位置。

`skills/`#

这里可以理解成 OpenClaw 自带的技能包。
这些技能负责教 agent 怎样用工具，而不是只靠系统提示死撑。

`ui/`#

对应浏览器端 Control UI。
文档明确写了它是一个小型 Vite + Lit 单页应用，由 Gateway 提供静态资源。

`apps/`#

这里通常会承载宿主应用层，例如桌面端或其它更高层的运行壳。

`docs/`#

官方文档本身也在仓库里。
OpenClaw 的功能面太大，所以 docs 在这个项目里不是“附属品”，而是理解系统不可绕开的主入口。

OpenClaw 的运行链路#

如果用一句话概括 OpenClaw 的主链路，大概是：

消息渠道 / Web UI / CLI 把输入交给 Gateway，Gateway 结合会话、工作区、技能、插件、模型与工具执行，再把结果回送到对应表面。

可以把它大致拆成这样：

用户输入
  ↓
渠道适配层 / Web UI / CLI
  ↓
Gateway
  ↓
会话路由 / Agent 选择 / 模型选择
  ↓
技能 + 工具 + 插件能力
  ↓
工作区 / 记忆 / 输出
  ↓
回到聊天界面、浏览器或消息渠道

text

这套链路和 Codex / Claude Code 那种“终端内 agent”不是一个量级的问题。

Workspace#

OpenClaw 的一个重要特点，是它明确区分了：

配置和凭据
工作区和记忆

官方文档把 workspace 当成 agent 的 home，还建议把它作为 私有 Git 仓库 备份。

这意味着 OpenClaw 并不是把长期状态完全交给模型上下文，而是努力把 agent 的“长期记忆”落在磁盘上、文件上、目录结构上。

这个思路非常工程化，也很适合长期运行的 personal assistant。

Skills 和 Plugins 的组合，是 OpenClaw 最像“平台”的地方#

很多 agent 项目会在这两件事里偏一边：

要么工具很多，但不会系统化成技能
要么 prompt 很多，但缺少真正的插件边界

OpenClaw 两边都做了：

Skills 负责“怎么教 agent 使用能力”
Plugins 负责“怎么把能力接进系统”

像一个：

带插件宿主、技能加载器、工作区和控制平面的 AI 操作系统雏形。

安全模型也影响了源码结构#

OpenClaw 一旦接入真实消息渠道和设备能力，安全模型就不能是“随便跑”。

从官方文档看，有几个安全点会直接影响架构：

1. DM pairing#

默认未知发件人不会直接通过，先走配对流程。

2. Dashboard 是管理面#

官方文档明确说 Control UI 是 admin surface，不能随便暴露公网。

3. Workspace 不是硬沙箱#

文档特别提醒：workspace 是默认 cwd，不等于强隔离。
如果你想要真正隔离，还要开启 sandbox。

这些设计都会反过来影响配置、认证、会话和工具执行层的代码形态。