OpenClaw学习笔记：研究官网文档后整理的架构详解_其他编程

背景

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

一、架构总览

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 基础配置（单智能体）

{
  channels: {
    whatsapp: {
      allowfrom: ["+8613800138000"],
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-sonnet-4-5",
    },
  },
}

6.2 多智能体配置

{
  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 节点主机配置

{
  tools: {
    exec: {
      host: "node",
      security: "allowlist",
      node: "build-node",
    },
  },
}

七、常用命令

# 网关管理
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

八、参考资料

官方文档：c:\users\83767\appdata\local\pnpm\global\5\.pnpm\openclaw@2026.3.13_@napi-rs_e5f2bb93bf52304d09fd1d7f29f705c6\node_modules\openclaw\docs
在线文档：https://docs.openclaw.ai
源码：https://github.com/openclaw/openclaw
技能市场：https://clawhub.com
社区：https://discord.com/invite/clawd

到此这篇关于openclaw学习笔记：研究官网文档后整理的架构详解的文章就介绍到这了,更多相关openclaw架构的学习笔记内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

OpenClaw学习笔记：研究官网文档后整理的架构详解

2026年03月28日 • 其他编程 •我要评论

背景

一、架构总览

二、各层详解

2.1 渠道层 (channels layer)

2.2 网关层 (gateway layer)

2.2.1 websocket 控制平面

2.2.2 消息路由引擎

2.2.3 多智能体路由

2.2.4 服务管理

2.3 智能体层 (agent layer)

2.3.1 智能体运行时

2.3.2 技能系统 (skills)

2.3.3 记忆系统

2.3.4 会话管理

2.4 执行层 (execution layer)

2.4.1 工具执行

2.4.2 节点系统 (nodes)

2.4.3 沙箱与安全

三、组件交互流程

3.1 消息处理流程

3.2 节点交互流程

3.3 多智能体路由流程

四、关键设计原则

4.1 单一事实来源

4.2 隔离与安全

4.3 可扩展性

4.4 记忆与连续性

五、目录结构

六、配置示例

6.1 基础配置（单智能体）

6.2 多智能体配置

6.3 节点主机配置

七、常用命令

八、参考资料

相关文章:

发表评论


验证码：