相关技巧

关注公众号 jb51net

关闭
首页 > 网络编程 > 相关技巧 > OpenClaw架构的学习笔记

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

作者：shangjian007

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

背景

近期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)

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

核心组件：

渠道技术实现特点
WhatsAppBaileys需 QR 配对，支持多账号
TelegramgrammYBot Token，最简单
DiscordDiscord Bot API需启用 Message Content Intent
iMessageBlueBubbles API推荐方案，替代 legacy imsg
Signalsignal-cli隐私优先
SlackBolt SDK企业场景
WebChat内置 WebSocket UI浏览器直接访问
更多…插件系统Mattermost, LINE, Matrix 等

关键能力：

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

2.2 网关层 (Gateway Layer)

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

核心组件：

2.2.1 WebSocket 控制平面
2.2.2 消息路由引擎
2.2.3 多智能体路由
2.2.4 服务管理

2.3 智能体层 (Agent Layer)

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

核心组件：

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 消息处理流程

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 单一事实来源

4.2 隔离与安全

4.3 可扩展性

4.4 记忆与连续性

五、目录结构

~/.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

八、参考资料

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

您可能感兴趣的文章:
阅读全文