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

目录

• 背景
• 一、架构总览
• 二、各层详解
• 2.1 渠道层 (Channels Layer)
• 2.2 网关层 (Gateway Layer)
• 2.3 智能体层 (Agent Layer)
• 2.4 执行层 (Execution Layer)
• 三、组件交互流程
• 3.1 消息处理流程
• 3.2 节点交互流程
• 3.3 多智能体路由流程
• 四、关键设计原则
• 4.1 单一事实来源
• 4.2 隔离与安全
• 4.3 可扩展性
• 4.4 记忆与连续性
• 五、目录结构
• 六、配置示例
• 6.1 基础配置（单智能体）
• 6.2 多智能体配置
• 6.3 节点主机配置
• 七、常用命令
• 八、参考资料

近期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)                              │   │
│  │  - 工具白名单/黑名单                                       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

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

核心组件：

渠道	技术实现	特点
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

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

核心组件：

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

• 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>
  • 维护策略：自动修剪/归档/轮转

• 场景：多个独立智能体（不同工作空间 + 认证 + 会话）
• 隔离级别：
  • 独立工作空间（workspace）
  • 独立认证目录（agentDir）
  • 独立会话存储
• 典型用例：
  • WhatsApp 日常聊天 → 快速模型
  • Telegram 深度工作 → Opus 模型
  • 家庭群组 → 受限工具策略

• Cron 调度器：定时任务（提醒、周期性检查）
• 健康检查：/health 端点 + WebSocket 事件
• 配置管理：~/.openclaw/openclaw.json

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

核心组件：

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

• 内置技能：

  • 文件：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

• 长期记忆：MEMORY.md（ curated，定期回顾更新）
• 日常日志：memory/YYYY-MM-DD.md（原始记录）
• 工具笔记：TOOLS.md（环境特定配置）
• 心跳维护：定期审查并提炼到长期记忆

• DM 范围（session.dmScope）：

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

• 重置策略：

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

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

核心组件：

• 文件工具：

  • 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：文本转语音

• 节点类型：

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

• 节点能力：

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

• 连接方式：

  • 本地网络（LAN）
  • Tailscale VPN
  • SSH 隧道

• 沙箱模式：

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

• 执行审批：

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

• 安全边界：

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

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. 更新会话状态 + 转录记录

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

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

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

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

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

• 文件即记忆：所有重要信息写入文件，不依赖"心理笔记"
• 定期维护：心跳机制定期审查和提炼记忆
• 会话持久化：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/                      # 日志

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

{
  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" } },
  ],
}

{
  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:Users83767AppDataLocalpnpmglobal5.pnpmopenclaw@2026.3.13_@napi-rs_e5f2bb93bf52304d09fd1d7f29f705c6node_modulesopenclawdocs
• 在线文档：https://docs.openclaw.ai
• 源码：https://github.com/openclaw/openclaw
• 技能市场：https://clawhub.com
• 社区：https://discord.com/invite/clawd

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

您可能感兴趣的文章:

• 使用Python打造一个极简OpenClaw Agent
• Python结合OpenClaw编写第一个控制程序的实战指南
• 通过Docker和Nginx实现OpenClaw在Ubuntu服务器上的完整部署流程
• OpenClaw在不同平台（Windows、macOS、Linux）和安装方式（npm、pnpm）下的完整卸载教程
• 安装内网穿透工具cpolar将本地运行的OpenClaw突破局域网限制实现随时访问
• OpenClaw核心组件Gateway原理解析：聊天渠道的连接、消息路由、会话状态维护以及安全认证
• OpenClaw配置SKILL指南：Clawhub命令行工具和VercelFindSkill语义搜索工具
• 使用Docker部署OpenClaw的完整流程
• 借助OpenClaw实现快速生成Python脚本并调试BUG
• 使用Docker安全地部署OpenClaw(龙虾)的详细步骤
• OpenClaw集成Elasticsearch实现智能数据操作与分析
• 基于Java + OpenClaw搭建本地大模型私有化的方案
• SpringBoot整合OpenClaw技能系统的实战指南