OpenClaw学习笔记-01-架构篇

shangjian0072026-03-23 9:19

目的

为避免一学就会、一用就废，这里做下笔记

背景

近期openclaw如火如荼，作为当下AI领域的C位，有必要对其进行了解。前期虽已部署试水，但对其原理不甚了解，查看官网文档又发现大量内容看不懂，感觉是官网的知识组织方式不够友好。这里结合官网文档和AI问答，整理出其架构，以便快速理解。

OpenClaw 架构说明

一、架构总览

OpenClaw 是一个自托管的多渠道消息网关，将 WhatsApp、Telegram、Discord、iMessage 等聊天应用与 AI 智能体（如 Pi/Claude Code）连接起来。

复制代码 
┌─────────────────────────────────────────────────────────────────┐
│                      用户设备 / 消息渠道                          │
│   WhatsApp  │  Telegram  │  Discord  │  iMessage  │  Slack  │... │
└─────────────┴────────────┴───────────┴────────────┴─────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     渠道层 (Channels Layer)                      │
│  各渠道适配器 (Baileys/grammY/Bolt SDK/Signal-CLI/BlueBubbles)   │
│  负责：消息收发、配对认证、群组管理、媒体处理                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      网关层 (Gateway Layer)                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  WebSocket 控制平面 (默认 127.0.0.1:18789)                │   │
│  │  - 客户端连接 (CLI/Web UI/macOS App)                      │   │
│  │  - 节点连接 (iOS/Android/Headless)                        │   │
│  │  - 认证与配对管理                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  消息路由引擎                                             │   │
│  │  - Bindings 路由规则 (渠道→智能体)                         │   │
│  │  - 会话管理 (Session Store + JSONL Transcripts)          │   │
│  │  - 多智能体路由 (Multi-Agent Routing)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  服务管理                                                 │   │
│  │  - Cron 定时任务                                          │   │
│  │  - 健康检查与心跳                                          │   │
│  │  - 配置管理 (openclaw.json)                               │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     智能体层 (Agent Layer)                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  智能体运行时 (基于 pi-mono)                               │   │
│  │  - 工作空间 (Workspace): AGENTS.md, SOUL.md, USER.md     │   │
│  │  - 会话状态 (Sessions): JSONL 转录 + Session Store        │   │
│  │  - 认证配置 (Auth Profiles): 各模型提供商 API 密钥          │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  技能系统 (Skills)                                        │   │
│  │  - 内置技能：read, write, edit, exec, browser, web_search │   │
│  │  - 插件技能：从 clawhub.com 安装                          │   │
│  │  - 工作空间技能：~/workspace/skills/                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  记忆系统 (Memory)                                        │   │
│  │  - 长期记忆：MEMORY.md                                    │   │
│  │  - 日常日志：memory/YYYY-MM-DD.md                         │   │
│  │  - 工具笔记：TOOLS.md                                     │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     执行层 (Execution Layer)                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  工具执行 (Tools)                                         │   │
│  │  - 文件操作：read, write, edit                            │   │
│  │  - 系统命令：exec (支持沙箱/审批)                          │   │
│  │  - 网络访问：web_search, web_fetch, browser               │   │
│  │  - 会话管理：sessions_*, subagents, cron                  │   │
│  │  - 设备节点：nodes_* (camera, canvas, screen, location)   │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  节点系统 (Nodes)                                         │   │
│  │  - iOS/Android/macOS 节点 (WebSocket 连接)                │   │
│  │  - 能力：Canvas 展示、相机快照、屏幕录制、位置获取          │   │
│  │  - 远程执行：system.run (节点主机)                         │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  沙箱与安全 (Sandbox & Security)                          │   │
│  │  - Docker 沙箱 (可选)                                     │   │
│  │  - 执行审批 (Exec Approvals)                              │   │
│  │  - 工具白名单/黑名单                                       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

二、各层详解

2.1 渠道层 (Channels Layer)

定位：消息平台的适配器，负责与外部聊天服务的双向通信。

核心组件：

渠道 技术实现 特点
WhatsApp Baileys 需 QR 配对，支持多账号
Telegram grammY Bot Token，最简单
Discord Discord Bot API 需启用 Message Content Intent
iMessage BlueBubbles API 推荐方案，替代 legacy imsg
Signal signal-cli 隐私优先
Slack Bolt SDK 企业场景
WebChat 内置 WebSocket UI 浏览器直接访问
更多... 插件系统 Mattermost, LINE, Matrix 等

关键能力：

  • 消息收发（文本 + 媒体）
  • 配对认证（Pairing/Allowlist）
  • 群组管理（Groups/Threads）
  • 反应/编辑/撤回（渠道相关）

配置位置 ：channels.<channel>.accounts

2.2 网关层 (Gateway Layer)

定位：系统的中枢神经，所有消息和控制的单一事实来源。

核心组件：

2.2.1 WebSocket 控制平面
  • 地址 ：默认 ws://127.0.0.1:18789
  • 客户端类型 ：
    • 操作客户端：CLI、Web UI、macOS App
    • 节点客户端：iOS/Android/Headless Nodes
  • 认证机制 ：
    • 设备配对（Device Pairing）
    • Gateway Token（OPENCLAW_GATEWAY_TOKEN）
    • 本地连接可自动批准
2.2.2 消息路由引擎

  • Bindings 系统：渠道→智能体的确定性路由

  • 路由优先级（从高到低）：

    1. peer 精确匹配（具体 DM/群组 ID）
    2. parentPeer 线程继承
    3. guildId + roles（Discord 角色）
    4. guildId（Discord 服务器）
    5. teamId（Slack）
    6. accountId 匹配
    7. 渠道级匹配（accountId: "*"）
    8. Fallback 到默认智能体

  • 会话管理：

    • 存储：~/.openclaw/agents/<agentId>/sessions/sessions.json
    • 转录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
    • 会话键格式：agent:<agentId>:<channel>:<type>:<id>
    • 维护策略：自动修剪/归档/轮转
2.2.3 多智能体路由
  • 场景：多个独立智能体（不同工作空间 + 认证 + 会话）
  • 隔离级别 ：
    • 独立工作空间（workspace）
    • 独立认证目录（agentDir）
    • 独立会话存储
  • 典型用例 ：
    • WhatsApp 日常聊天 → 快速模型
    • Telegram 深度工作 → Opus 模型
    • 家庭群组 → 受限工具策略
2.2.4 服务管理
  • Cron 调度器：定时任务（提醒、周期性检查）
  • 健康检查 ：/health 端点 + WebSocket 事件
  • 配置管理 ：~/.openclaw/openclaw.json

2.3 智能体层 (Agent Layer)

定位：AI 大脑，理解用户意图并调用工具执行任务。

核心组件：

2.3.1 智能体运行时
  • 基础：基于 pi-agent 的嵌入式运行时
  • 工作空间文件 （启动时注入）：
    • AGENTS.md --- 操作指令 + 记忆规则
    • SOUL.md --- 人格、语气、边界
    • USER.md --- 用户档案
    • IDENTITY.md --- 智能体身份
    • MEMORY.md --- 长期记忆（仅主会话）
    • BOOTSTRAP.md --- 首次启动引导（一次性）
2.3.2 技能系统 (Skills)

  • 内置技能：

    • 文件：read, write, edit
    • 系统：exec, process
    • 网络：web_search, web_fetch, browser
    • 会话：sessions_*, subagents, cron
    • 设备：nodes_*, canvas, tts
    • 消息：message

  • 技能来源：

    1. 内置技能（安装包自带）
    2. 本地技能（~/.openclaw/skills）
    3. 工作空间技能（<workspace>/skills）
    4. ClawHub（clawhub install 从 clawhub.com 获取）

  • 工具策略：

    • 白名单模式：tools.allow
    • 黑名单模式：tools.deny
    • 按提供商区分：tools.byProvider
2.3.3 记忆系统
  • 长期记忆 ：MEMORY.md（ curated，定期回顾更新）
  • 日常日志 ：memory/YYYY-MM-DD.md（原始记录）
  • 工具笔记 ：TOOLS.md（环境特定配置）
  • 心跳维护：定期审查并提炼到长期记忆
2.3.4 会话管理

  • DM 范围 （session.dmScope）：

    • main（默认）：所有 DM 共享主会话
    • per-peer：按发送者隔离
    • per-channel-peer：按渠道 + 发送者隔离（推荐多用户）
    • per-account-channel-peer：按账号 + 渠道 + 发送者隔离

  • 重置策略：

    • 每日重置：默认凌晨 4 点
    • 空闲重置：idleMinutes
    • 手动触发：/new, /reset, /compact

2.4 执行层 (Execution Layer)

定位：将智能体意图转化为实际动作。

核心组件：

2.4.1 工具执行

  • 文件工具：

    • read：读取文件（支持文本/图片）
    • write：创建/覆盖文件
    • edit：精确文本替换

  • 系统工具：

    • exec：执行 shell 命令（支持 PTY、后台、超时）
    • process：管理后台进程（poll/log/write/send-keys/kill）

  • 网络工具：

    • web_search：Brave Search API
    • web_fetch：提取网页内容
    • browser：浏览器自动化（Playwright）

  • 会话工具：

    • sessions_list/history/send/spawn/yield
    • subagents：子智能体编排
    • cron：定时任务管理

  • 消息工具：

    • message：跨渠道发送消息
    • tts：文本转语音
2.4.2 节点系统 (Nodes)

  • 节点类型：

    • iOS/Android 移动节点
    • macOS 节点（菜单栏应用）
    • Headless 节点（跨平台）

  • 节点能力：

    • canvas.*：WebView 展示/导航/截图/A2UI
    • camera.*：拍照/录像
    • screen.record：屏幕录制
    • location.get：位置获取
    • notifications.*：通知管理
    • device.*：设备状态/信息/权限
    • system.run：远程命令执行

  • 连接方式：

    • 本地网络（LAN）
    • Tailscale VPN
    • SSH 隧道
2.4.3 沙箱与安全

  • 沙箱模式：

    • off：无沙箱
    • all：始终沙箱
    • Docker 容器（每智能体或共享）

  • 执行审批：

    • ask：每次询问
    • allowlist：白名单自动批准
    • full：完全开放

  • 安全边界：

    • 工作空间内：自由操作
    • 工作空间外：只读，修改需授权
    • 外部动作（邮件/推文）：必须先问

三、组件交互流程

3.1 消息处理流程

复制代码 
1. 用户发送消息 (WhatsApp/Telegram/Discord...)
         │
         ▼
2. 渠道层接收消息，标准化为内部格式
         │
         ▼
3. 网关层路由引擎根据 Bindings 选择智能体
         │
         ▼
4. 创建/加载会话 (Session Store + JSONL)
         │
         ▼
5. 智能体运行时处理消息：
   - 读取工作空间文件 (AGENTS.md, SOUL.md, MEMORY.md...)
   - 调用工具 (read/exec/web_search...)
   - 可能 spawn 子智能体
         │
         ▼
6. 智能体生成回复
         │
         ▼
7. 网关层通过原渠道发送回复
         │
         ▼
8. 更新会话状态 + 转录记录

3.2 节点交互流程

复制代码 
1. 智能体调用 nodes.* 工具
         │
         ▼
2. 网关层通过 WebSocket 转发到节点
         │
         ▼
3. 节点执行命令 (canvas/camera/screen/location...)
         │
         ▼
4. 节点返回结果 (base64 媒体/JSON 数据)
         │
         ▼
5. 网关层将结果作为工具响应返回智能体
         │
         ▼
6. 智能体处理结果，可能附加媒体到回复

3.3 多智能体路由流程

复制代码 
1. 消息到达网关
         │
         ▼
2. 路由引擎按优先级匹配 Bindings：
   a. 检查 peer 精确匹配
   b. 检查 guildId/roles 匹配
   c. 检查 accountId 匹配
   d. Fallback 到默认智能体
         │
         ▼
3. 消息路由到目标智能体的主会话或独立会话
         │
         ▼
4. 各智能体独立处理（不同工作空间/模型/工具策略）

四、关键设计原则

4.1 单一事实来源

  • 网关是中心：所有会话状态、路由决策、渠道连接都由网关管理
  • 客户端无状态：CLI/Web UI/macOS App 只查询网关，不直接读文件

4.2 隔离与安全

  • 智能体隔离 ：每个 agentId 有独立的工作空间、认证、会话
  • 沙箱选项：Docker 容器限制工具执行范围
  • 执行审批：敏感命令需用户批准或白名单

4.3 可扩展性

  • 插件系统：渠道、技能、工具都可通过插件扩展
  • 多账号支持：同一渠道可配置多个账号（如两个 WhatsApp 号码）
  • 远程部署：支持 SSH 隧道/Tailscale 远程访问

4.4 记忆与连续性

  • 文件即记忆：所有重要信息写入文件，不依赖"心理笔记"
  • 定期维护：心跳机制定期审查和提炼记忆
  • 会话持久化：JSONL 转录永久保存（可配置修剪）

五、目录结构

复制代码 
~/.openclaw/
├── openclaw.json              # 主配置文件
├── workspace/                 # 默认工作空间
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── USER.md
│   ├── IDENTITY.md
│   ├── MEMORY.md
│   ├── TOOLS.md
│   ├── HEARTBEAT.md
│   ├── memory/
│   │   └── YYYY-MM-DD.md
│   └── skills/                # 工作空间技能
├── agents/
│   └── <agentId>/
│       ├── agent/
│       │   └── auth-profiles.json
│       └── sessions/
│           ├── sessions.json
│           └── <SessionId>.jsonl
├── skills/                    # 本地共享技能
├── credentials/               # 渠道认证
│   └── <channel>/
└── logs/                      # 日志

六、配置示例

6.1 基础配置（单智能体）

json5 复制代码 
{
  channels: {
    whatsapp: {
      allowFrom: ["+8613800138000"],
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-sonnet-4-5",
    },
  },
}

6.2 多智能体配置

json5 复制代码 
{
  agents: {
    list: [
      {
        id: "chat",
        name: "日常聊天",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "coding",
        name: "编码助手",
        workspace: "~/.openclaw/workspace-coding",
        model: "anthropic/claude-opus-4-6",
        sandbox: { mode: "all" },
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "coding", match: { channel: "telegram" } },
  ],
}

6.3 节点主机配置

json5 复制代码 
{
  tools: {
    exec: {
      host: "node",
      security: "allowlist",
      node: "build-node",
    },
  },
}

七、常用命令

bash 复制代码 
# 网关管理
openclaw gateway status
openclaw gateway start|stop|restart

# 渠道管理
openclaw channels login --channel whatsapp
openclaw channels status

# 智能体管理
openclaw agents list --bindings
openclaw agents add <id>

# 会话管理
openclaw sessions list --active 60
openclaw sessions cleanup --dry-run

# 节点管理
openclaw nodes status
openclaw devices list|approve|reject

# 配置管理
openclaw config get|set|unset <path>

# 日志
openclaw logs --follow

八、参考资料

相关推荐
少许极端2 小时前
算法奇妙屋(三十四)-贪心算法学习之路 1
学习·算法·贪心算法
code 小楊2 小时前
深度解析RAG系统与AI Agent：原理、架构及协同落地
人工智能·架构
无忧智库2 小时前
破局与重构：大型集团财务共享业财一体化的数字基因革命（PPT）
大数据·架构
551只玄猫2 小时前
【基于python的金融分析和风险管理 学习笔记】中阶篇 第6章 分析利率和汇率
笔记·python·学习·金融·学习笔记·汇率·利率
孤独的小丑2 小时前
OpenClaw学习资源汇编
汇编·学习
ljt27249606612 小时前
Flutter笔记--加水印
笔记·flutter
show2142 小时前
Memos 开源笔记的使用
笔记
weixin199701080162 小时前
《淘宝双11同款：基于 Sentinel 的微服务流量防卫兵实战》
微服务·架构·sentinel
悠哉悠哉愿意2 小时前
【单片机学习笔记】第十二届国赛经验复盘
笔记·单片机·嵌入式硬件·学习
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07OpenClaw Control UI安全上下文访问配置08UV安装并设置国内源09AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）