OpenClaw 架构原理与核心机制深度解析
OpenClaw 是一款本地优先的开源 AI 助手框架,支持多消息平台接入。其核心采用 Gateway 控制平面架构,通过 WebSocket 调度所有渠道、会话及工具调用。系统包含 Pi Agent 嵌入式运行时、会话模型、多渠道适配器、Skills 扩展平台及多 Agent 协作机制。安全方面提供多层防护,包括沙箱隔离、权限控制及故障转移策略。支持主流 AI 模型及本地部署,适合开发者研究 AI Agent 框架设计与工程实践。

OpenClaw 是一款本地优先的开源 AI 助手框架,支持多消息平台接入。其核心采用 Gateway 控制平面架构,通过 WebSocket 调度所有渠道、会话及工具调用。系统包含 Pi Agent 嵌入式运行时、会话模型、多渠道适配器、Skills 扩展平台及多 Agent 协作机制。安全方面提供多层防护,包括沙箱隔离、权限控制及故障转移策略。支持主流 AI 模型及本地部署,适合开发者研究 AI Agent 框架设计与工程实践。

OpenClaw 是一款运行在个人设备上的开源 AI 助手框架,支持 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等 20+ 主流消息平台。本文基于其源码(openclaw-main)对其整体架构、核心子系统及关键设计原理进行深度解析。
OpenClaw 采用本地优先(Local-First)的 Gateway 控制平面架构,核心思想是:所有消息渠道、AI 会话、工具调用都通过一个统一的本地 WebSocket 服务(Gateway)进行调度。
WhatsApp / Telegram / Slack / Discord / Signal / iMessage / ...
│
▼
┌───────────────────────────────┐
│ Gateway │
│ (控制平面 / Control Plane) │
│ ws://127.0.0.1:18789 │
└──────────────┬────────────────┘
│
├─ Pi Agent(嵌入式 AI 运行时,RPC 模式)
├─ CLI(openclaw 命令行)
├─ WebChat UI(内置 Web 界面)
├─ macOS 菜单栏 App
└─ iOS / Android 节点(Nodes)
设计哲学:
127.0.0.1),安全优先openclaw-main/
├── src/ # 核心源码
│ ├── gateway/ # Gateway 服务(WebSocket 控制平面)
│ ├── agents/ # Agent 运行时(Pi 嵌入式 Runner)
│ ├── sessions/ # 会话管理
│ ├── channels/ # 消息渠道适配器
│ ├── providers/ # AI 模型提供商
│ ├── skills/ # Skills 平台
│ ├── browser/ # 浏览器控制工具
│ ├── canvas-host/ # Canvas 可视化工作区
│ └── ...
├── extensions/ # 扩展插件(Discord、Feishu、Matrix 等)
├── skills/ # 内置 Skills 目录
├── ui/ # WebChat 前端(TypeScript + Vite)
├── apps/ # 平台 App(macOS、iOS、Android)
└── packages/ # 共享包
Gateway 是整个系统的神经中枢,负责:
源码 src/gateway/server-startup.ts 揭示了启动序列:
1. 加载配置(openclaw.json)
2. 初始化认证模块(auth.ts)
3. 启动 HTTP 服务(server-http.ts)
4. 升级 WebSocket 连接(server-ws-runtime.ts)
5. 初始化渠道连接(server-channels.ts)
6. 启动 Cron 调度器(server-cron.ts)
7. 注册工具目录(tool-catalog.ts)
8. 加载 Skills(skills.ts)
9. 启动内存服务(server-startup-memory.ts)
Gateway 使用自定义 WS 协议,核心方法分为:
sessions.list、sessions.patch、config.get、config.patchchat.send、chat.abort、chat.compacttools.invoke、node.invoke、browser.actionagent.text、agent.tool_call、session.update方法权限通过 method-scopes.ts 进行细粒度控制,不同角色(owner/user/guest)拥有不同的方法访问权限。
Pi Agent 是 OpenClaw 的 AI 执行引擎,采用嵌入式 RPC 模式运行,与 Gateway 通过内部 RPC 通信,而非外部 HTTP 调用。
核心文件:
src/agents/pi-embedded-runner.ts:主运行循环src/agents/pi-embedded-subscribe.ts:流式响应订阅处理src/agents/pi-embedded-helpers.ts:辅助工具函数用户消息到达
│
▼
构建 System Prompt(SOUL.md + AGENTS.md + Skills + 上下文)
│
▼
调用 AI 模型 API(支持 Anthropic / OpenAI / Gemini / Ollama 等)
│
▼
流式接收响应(pi-embedded-subscribe.ts)
│
├─ 文本块 → 实时推送到渠道
├─ 工具调用 → 执行工具 → 结果注入上下文
└─ 思考块(Reasoning)→ 可选显示
│
▼
会话历史持久化(session-utils.fs.ts)
工具调用采用**策略管道(Policy Pipeline)**设计:
工具调用请求
│
▼
tool-policy-pipeline.ts(策略检查)
├─ 沙箱策略(sandbox-tool-policy.ts)
├─ 文件系统策略(tool-fs-policy.ts)
├─ 路径策略(path-policy.ts)
└─ 自定义策略
│
▼
工具执行(bash-tools.exec.ts / browser / canvas 等)
│
▼
结果返回 + 持久化(session-tool-result-guard.ts)
当会话历史超过模型上下文窗口时,自动触发压缩:
src/agents/compaction.ts:压缩主逻辑compaction.identifier-preservation.ts)compaction.retry.ts)compaction.token-sanitize.ts)OpenClaw 的会话分为两类:
| 类型 | 说明 |
|---|---|
main | 主会话,用于与用户直接对话,拥有完整工具权限 |
| 非 main | 群组/渠道会话,可配置沙箱隔离 |
非 main 会话(群组、陌生人 DM)可运行在 Docker 沙箱中:
{"agents":{"defaults":{"sandbox":{"mode":"non-main"}}}}
沙箱内默认:
bash、read、write、edit、sessions_*browser、canvas、nodes、cron会话数据存储在文件系统:
~/.openclaw/sessions/<session-key>/session-transcript-repair.ts)session-write-lock.ts 防止并发写入冲突每个渠道(WhatsApp、Telegram、Discord 等)实现统一的渠道接口,核心职责:
入站消息
│
▼
渠道适配器(解析 + 标准化)
│
▼
routing/(路由决策)
├─ 确定目标 Agent(基于 sender/group 配置)
├─ 安全检查(allowFrom / dmPolicy)
└─ 会话键生成(session-key-utils.ts)
│
▼
会话队列(lanes.ts)
│
▼
Pi Agent 处理
│
▼
回复分块(streaming/chunking)→ 发送回渠道
dmPolicy):默认要求配对码验证,防止陌生人滥用openclaw doctor 自动检测危险配置OpenClaw 支持几乎所有主流 AI 提供商:
src/agents/auth-profiles.ts 实现了多 API Key 的智能轮换:
请求到来
│
▼
resolve-auth-profile-order.ts(排序策略)
├─ 按 lastUsed 时间排序(避免单 Key 过热)
├─ 跳过冷却中的 Key(rate limit 后自动冷却)
└─ 优先使用 lastGood Key
│
▼
执行请求
│
├─ 成功 → 更新 lastUsed
└─ 失败 → 标记冷却 → 自动切换下一个 Key
src/agents/model-fallback.ts 实现了模型级别的故障转移:
Skills 是 OpenClaw 的扩展机制,本质是注入到 System Prompt 的指令文件(SKILL.md)+ 可选的脚本/工具。
三种 Skills 类型:
| 类型 | 位置 | 说明 |
|---|---|---|
| 内置 Skills | skills/ 目录 | 随 OpenClaw 发布 |
| 托管 Skills | ~/.openclaw/skills/ | 通过 ClawHub 安装 |
| 工作区 Skills | workspace/skills/ | 用户自定义 |
启动时扫描 Skills 目录
│
▼
解析 SKILL.md(提取 description、触发条件)
│
▼
构建 Skills 快照(buildworkspaceskillsnapshot.ts)
│
▼
注入 System Prompt(build-workspace-skills-prompt.ts)
│
▼
Agent 根据用户意图选择并加载对应 Skill
支持从 ClawHub(clawhub.com)在线安装:
skills-install-download.ts)skills-install-extract.ts)skill-vetter 内置 Skill)OpenClaw 内置了丰富的工具:
| 工具 | 说明 |
|---|---|
exec / bash | Shell 命令执行,支持 PTY |
read / write / edit | 文件系统操作 |
browser | Chrome/Chromium 浏览器控制(CDP) |
canvas | Agent 驱动的可视化工作区 |
nodes | 移动设备控制(相机、屏幕录制、位置) |
sessions_* | 多 Agent 协作工具 |
memory_search / memory_get | 语义记忆检索 |
web_search / web_fetch | 网络搜索与内容抓取 |
bash-tools.exec.ts 是最复杂的工具之一:
background: true 异步执行exec-approval-manager.ts)bash-process-registry.ts 管理所有后台进程生命周期基于 Chrome DevTools Protocol(CDP):
OpenClaw 支持 Agent 间协作,主 Agent 可以 spawn 子 Agent 执行并行任务:
主 Agent
├─ sessions_spawn() → 子 Agent A(独立会话)
├─ sessions_spawn() → 子 Agent B(独立会话)
└─ sessions_send() → 向其他会话发消息
src/agents/subagent-registry.ts 管理所有子 Agent 的生命周期:
subagent-depth.ts):防止无限递归 spawnsubagent-announce.ts):子 Agent 完成后自动通知父 Agentsubagent-registry-cleanup.ts):超时或失败的子 Agent 自动清理src/acp/ 实现了与外部编码 Agent(Codex、Claude Code 等)的集成协议,支持:
OpenClaw 的记忆系统基于文件:
MEMORY.md:长期记忆(主会话专用)memory/YYYY-MM-DD.md:每日日志SOUL.md、AGENTS.md、USER.md:身份与行为定义src/agents/memory-search.ts 实现了向量语义搜索:
extensions/memory-lancedb/)extensions/memory-core/)memory_search 工具暴露给 Agent外部请求
│
▼
网络层:默认绑定 127.0.0.1(不暴露公网)
│
▼
认证层:Token / Password / Tailscale 身份
│
▼
授权层:角色权限(owner/user/guest)+ 方法作用域
│
▼
渠道层:allowFrom 白名单 + dmPolicy 配对
│
▼
工具层:沙箱隔离 + 路径策略 + 审批机制
│
▼
Agent 层:Prompt 注入防护 + 内容清理
非 main 会话可在 Docker 容器中运行:
Dockerfile.sandbox:基础沙箱镜像Dockerfile.sandbox-browser:含浏览器的沙箱镜像bash-tools.exec-host-gateway.ts 代理到容器内执行主配置文件:~/.openclaw/openclaw.json(JSON5 格式)
核心配置项:
{
"agent": {
"model": "anthropic/claude-opus-4-6"
},
"gateway": {
"bind": "loopback",
"port": 18789
},
"channels": {
"telegram": { "botToken": "..." },
"discord": { "token": "..." },
"whatsapp": { "allowFrom": ["..."] }
},
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "non-main" }
}
}
}
src/gateway/config-reload.ts 实现配置热重载:
config-reload-plan.ts)OpenClaw 的架构设计体现了以下核心理念:
对于想深入研究 AI Agent 框架设计的开发者,OpenClaw 的源码是一份极具价值的参考实现,涵盖了从 WebSocket 协议设计、流式响应处理、工具安全策略到多 Agent 协作的完整工程实践。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online