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