OpenClaw學(xué)習(xí)筆記：研究官網(wǎng)文檔后整理的架構(gòu)詳解

更新時間：2026年03月28日 09:14:12 作者：shangjian007

近期openclaw如火如荼,作為當(dāng)下AI領(lǐng)域的C位,有必要對其進(jìn)行了解,前期雖已部署試水,但對其原理不甚了解,查看官網(wǎng)文檔又發(fā)現(xiàn)大量內(nèi)容看不懂,感覺是官網(wǎng)的知識組織方式不夠友好,這里結(jié)合官網(wǎng)文檔和AI問答,整理出其架構(gòu),以便快速理解

背景

近期openclaw如火如荼，作為當(dāng)下AI領(lǐng)域的C位，有必要對其進(jìn)行了解。前期雖已部署試水，但對其原理不甚了解，查看官網(wǎng)文檔又發(fā)現(xiàn)大量內(nèi)容看不懂，感覺是官網(wǎng)的知識組織方式不夠友好。這里結(jié)合官網(wǎng)文檔和AI問答，整理出其架構(gòu)，以便快速理解。

一、架構(gòu)總覽

OpenClaw 是一個自托管的多渠道消息網(wǎng)關(guān)，將 WhatsApp、Telegram、Discord、iMessage 等聊天應(yīng)用與 AI 智能體（如 Pi/Claude Code）連接起來。

┌─────────────────────────────────────────────────────────────────┐
│                      用戶設(shè)備 / 消息渠道                          │
│   WhatsApp  │  Telegram  │  Discord  │  iMessage  │  Slack  │... │
└─────────────┴────────────┴───────────┴────────────┴─────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     渠道層 (Channels Layer)                      │
│  各渠道適配器 (Baileys/grammY/Bolt SDK/Signal-CLI/BlueBubbles)   │
│  負(fù)責(zé)：消息收發(fā)、配對認(rèn)證、群組管理、媒體處理                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      網(wǎng)關(guān)層 (Gateway Layer)                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  WebSocket 控制平面 (默認(rèn) 127.0.0.1:18789)                │   │
│  │  - 客戶端連接 (CLI/Web UI/macOS App)                      │   │
│  │  - 節(jié)點連接 (iOS/Android/Headless)                        │   │
│  │  - 認(rèn)證與配對管理                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  消息路由引擎                                             │   │
│  │  - Bindings 路由規(guī)則 (渠道→智能體)                         │   │
│  │  - 會話管理 (Session Store + JSONL Transcripts)          │   │
│  │  - 多智能體路由 (Multi-Agent Routing)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  服務(wù)管理                                                 │   │
│  │  - Cron 定時任務(wù)                                          │   │
│  │  - 健康檢查與心跳                                          │   │
│  │  - 配置管理 (openclaw.json)                               │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     智能體層 (Agent Layer)                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  智能體運行時 (基于 pi-mono)                               │   │
│  │  - 工作空間 (Workspace): AGENTS.md, SOUL.md, USER.md     │   │
│  │  - 會話狀態(tài) (Sessions): JSONL 轉(zhuǎn)錄 + Session Store        │   │
│  │  - 認(rèn)證配置 (Auth Profiles): 各模型提供商 API 密鑰          │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  技能系統(tǒng) (Skills)                                        │   │
│  │  - 內(nèi)置技能：read, write, edit, exec, browser, web_search │   │
│  │  - 插件技能：從 clawhub.com 安裝                          │   │
│  │  - 工作空間技能：~/workspace/skills/                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  記憶系統(tǒng) (Memory)                                        │   │
│  │  - 長期記憶：MEMORY.md                                    │   │
│  │  - 日常日志：memory/YYYY-MM-DD.md                         │   │
│  │  - 工具筆記：TOOLS.md                                     │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     執(zhí)行層 (Execution Layer)                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  工具執(zhí)行 (Tools)                                         │   │
│  │  - 文件操作：read, write, edit                            │   │
│  │  - 系統(tǒng)命令：exec (支持沙箱/審批)                          │   │
│  │  - 網(wǎng)絡(luò)訪問：web_search, web_fetch, browser               │   │
│  │  - 會話管理：sessions_*, subagents, cron                  │   │
│  │  - 設(shè)備節(jié)點：nodes_* (camera, canvas, screen, location)   │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  節(jié)點系統(tǒng) (Nodes)                                         │   │
│  │  - iOS/Android/macOS 節(jié)點 (WebSocket 連接)                │   │
│  │  - 能力：Canvas 展示、相機快照、屏幕錄制、位置獲取          │   │
│  │  - 遠(yuǎn)程執(zhí)行：system.run (節(jié)點主機)                         │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  沙箱與安全 (Sandbox & Security)                          │   │
│  │  - Docker 沙箱 (可選)                                     │   │
│  │  - 執(zhí)行審批 (Exec Approvals)                              │   │
│  │  - 工具白名單/黑名單                                       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

二、各層詳解

2.1 渠道層 (Channels Layer)

定位：消息平臺的適配器，負(fù)責(zé)與外部聊天服務(wù)的雙向通信。

核心組件：

渠道	技術(shù)實現(xiàn)	特點
WhatsApp	Baileys	需 QR 配對，支持多賬號
Telegram	grammY	Bot Token，最簡單
Discord	Discord Bot API	需啟用 Message Content Intent
iMessage	BlueBubbles API	推薦方案，替代 legacy imsg
Signal	signal-cli	隱私優(yōu)先
Slack	Bolt SDK	企業(yè)場景
WebChat	內(nèi)置 WebSocket UI	瀏覽器直接訪問
更多…	插件系統(tǒng)	Mattermost, LINE, Matrix 等

關(guān)鍵能力：

消息收發(fā)（文本 + 媒體）
配對認(rèn)證（Pairing/Allowlist）
群組管理（Groups/Threads）
反應(yīng)/編輯/撤回（渠道相關(guān)）

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

2.2 網(wǎng)關(guān)層 (Gateway Layer)

定位：系統(tǒng)的中樞神經(jīng)，所有消息和控制的單一事實來源。

核心組件：

2.2.1 WebSocket 控制平面

地址：默認(rèn) ws://127.0.0.1:18789
客戶端類型：
- 操作客戶端：CLI、Web UI、macOS App
- 節(jié)點客戶端：iOS/Android/Headless Nodes
認(rèn)證機制：
- 設(shè)備配對（Device Pairing）
- Gateway Token（OPENCLAW_GATEWAY_TOKEN）
- 本地連接可自動批準(zhǔn)

2.2.2 消息路由引擎

Bindings 系統(tǒng)：渠道→智能體的確定性路由
路由優(yōu)先級（從高到低）：
1. peer 精確匹配（具體 DM/群組 ID）
2. parentPeer 線程繼承
3. guildId + roles（Discord 角色）
4. guildId（Discord 服務(wù)器）
5. teamId（Slack）
6. accountId 匹配
7. 渠道級匹配（accountId: "*"）
8. Fallback 到默認(rèn)智能體
會話管理：
- 存儲：~/.openclaw/agents/<agentId>/sessions/sessions.json
- 轉(zhuǎn)錄：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
- 會話鍵格式：agent:<agentId>:<channel>:<type>:<id>
- 維護(hù)策略：自動修剪/歸檔/輪轉(zhuǎn)

2.2.3 多智能體路由

場景：多個獨立智能體（不同工作空間 + 認(rèn)證 + 會話）
隔離級別：
- 獨立工作空間（workspace）
- 獨立認(rèn)證目錄（agentDir）
- 獨立會話存儲
典型用例：
- WhatsApp 日常聊天 → 快速模型
- Telegram 深度工作 → Opus 模型
- 家庭群組 → 受限工具策略

2.2.4 服務(wù)管理

Cron 調(diào)度器：定時任務(wù)（提醒、周期性檢查）
健康檢查：/health 端點 + WebSocket 事件
配置管理：~/.openclaw/openclaw.json

2.3 智能體層 (Agent Layer)

定位：AI 大腦，理解用戶意圖并調(diào)用工具執(zhí)行任務(wù)。

核心組件：

2.3.1 智能體運行時

基礎(chǔ)：基于 pi-agent 的嵌入式運行時
工作空間文件（啟動時注入）：
- AGENTS.md — 操作指令 + 記憶規(guī)則
- SOUL.md — 人格、語氣、邊界
- USER.md — 用戶檔案
- IDENTITY.md — 智能體身份
- MEMORY.md — 長期記憶（僅主會話）
- BOOTSTRAP.md — 首次啟動引導(dǎo)（一次性）

2.3.2 技能系統(tǒng) (Skills)

內(nèi)置技能：
- 文件：read, write, edit
- 系統(tǒng)：exec, process
- 網(wǎng)絡(luò)：web_search, web_fetch, browser
- 會話：sessions_*, subagents, cron
- 設(shè)備：nodes_*, canvas, tts
- 消息：message
技能來源：
1. 內(nèi)置技能（安裝包自帶）
2. 本地技能（~/.openclaw/skills）
3. 工作空間技能（<workspace>/skills）
4. ClawHub（clawhub install 從 clawhub.com 獲?。?/li>
工具策略：
- 白名單模式：tools.allow
- 黑名單模式：tools.deny
- 按提供商區(qū)分：tools.byProvider

2.3.3 記憶系統(tǒng)

長期記憶：MEMORY.md（ curated，定期回顧更新）
日常日志：memory/YYYY-MM-DD.md（原始記錄）
工具筆記：TOOLS.md（環(huán)境特定配置）
心跳維護(hù)：定期審查并提煉到長期記憶

2.3.4 會話管理

DM 范圍（session.dmScope）：
- main（默認(rèn)）：所有 DM 共享主會話
- per-peer：按發(fā)送者隔離
- per-channel-peer：按渠道 + 發(fā)送者隔離（推薦多用戶）
- per-account-channel-peer：按賬號 + 渠道 + 發(fā)送者隔離
重置策略：
- 每日重置：默認(rèn)凌晨 4 點
- 空閑重置：idleMinutes
- 手動觸發(fā)：/new, /reset, /compact

2.4 執(zhí)行層 (Execution Layer)

定位：將智能體意圖轉(zhuǎn)化為實際動作。

核心組件：

2.4.1 工具執(zhí)行

文件工具：
- read：讀取文件（支持文本/圖片）
- write：創(chuàng)建/覆蓋文件
- edit：精確文本替換
系統(tǒng)工具：
- exec：執(zhí)行 shell 命令（支持 PTY、后臺、超時）
- process：管理后臺進(jìn)程（poll/log/write/send-keys/kill）
網(wǎng)絡(luò)工具：
- web_search：Brave Search API
- web_fetch：提取網(wǎng)頁內(nèi)容
- browser：瀏覽器自動化（Playwright）
會話工具：
- sessions_list/history/send/spawn/yield
- subagents：子智能體編排
- cron：定時任務(wù)管理
消息工具：
- message：跨渠道發(fā)送消息
- tts：文本轉(zhuǎn)語音

2.4.2 節(jié)點系統(tǒng) (Nodes)

節(jié)點類型：
- iOS/Android 移動節(jié)點
- macOS 節(jié)點（菜單欄應(yīng)用）
- Headless 節(jié)點（跨平臺）
節(jié)點能力：
- canvas.*：WebView 展示/導(dǎo)航/截圖/A2UI
- camera.*：拍照/錄像
- screen.record：屏幕錄制
- location.get：位置獲取
- notifications.*：通知管理
- device.*：設(shè)備狀態(tài)/信息/權(quán)限
- system.run：遠(yuǎn)程命令執(zhí)行
連接方式：
- 本地網(wǎng)絡(luò)（LAN）
- Tailscale VPN
- SSH 隧道

2.4.3 沙箱與安全

沙箱模式：
- off：無沙箱
- all：始終沙箱
- Docker 容器（每智能體或共享）
執(zhí)行審批：
- ask：每次詢問
- allowlist：白名單自動批準(zhǔn)
- full：完全開放
安全邊界：
- 工作空間內(nèi)：自由操作
- 工作空間外：只讀，修改需授權(quán)
- 外部動作（郵件/推文）：必須先問

三、組件交互流程

3.1 消息處理流程

1. 用戶發(fā)送消息 (WhatsApp/Telegram/Discord...)
         │
         ▼
2. 渠道層接收消息，標(biāo)準(zhǔn)化為內(nèi)部格式
         │
         ▼
3. 網(wǎng)關(guān)層路由引擎根據(jù) Bindings 選擇智能體
         │
         ▼
4. 創(chuàng)建/加載會話 (Session Store + JSONL)
         │
         ▼
5. 智能體運行時處理消息：
   - 讀取工作空間文件 (AGENTS.md, SOUL.md, MEMORY.md...)
   - 調(diào)用工具 (read/exec/web_search...)
   - 可能 spawn 子智能體
         │
         ▼
6. 智能體生成回復(fù)
         │
         ▼
7. 網(wǎng)關(guān)層通過原渠道發(fā)送回復(fù)
         │
         ▼
8. 更新會話狀態(tài) + 轉(zhuǎn)錄記錄

3.2 節(jié)點交互流程

1. 智能體調(diào)用 nodes.* 工具
         │
         ▼
2. 網(wǎng)關(guān)層通過 WebSocket 轉(zhuǎn)發(fā)到節(jié)點
         │
         ▼
3. 節(jié)點執(zhí)行命令 (canvas/camera/screen/location...)
         │
         ▼
4. 節(jié)點返回結(jié)果 (base64 媒體/JSON 數(shù)據(jù))
         │
         ▼
5. 網(wǎng)關(guān)層將結(jié)果作為工具響應(yīng)返回智能體
         │
         ▼
6. 智能體處理結(jié)果，可能附加媒體到回復(fù)

3.3 多智能體路由流程

1. 消息到達(dá)網(wǎng)關(guān)
         │
         ▼
2. 路由引擎按優(yōu)先級匹配 Bindings：
   a. 檢查 peer 精確匹配
   b. 檢查 guildId/roles 匹配
   c. 檢查 accountId 匹配
   d. Fallback 到默認(rèn)智能體
         │
         ▼
3. 消息路由到目標(biāo)智能體的主會話或獨立會話
         │
         ▼
4. 各智能體獨立處理（不同工作空間/模型/工具策略）

四、關(guān)鍵設(shè)計原則

4.1 單一事實來源

網(wǎng)關(guān)是中心：所有會話狀態(tài)、路由決策、渠道連接都由網(wǎng)關(guān)管理
客戶端無狀態(tài)：CLI/Web UI/macOS App 只查詢網(wǎng)關(guān)，不直接讀文件

4.2 隔離與安全

智能體隔離：每個 agentId 有獨立的工作空間、認(rèn)證、會話
沙箱選項：Docker 容器限制工具執(zhí)行范圍
執(zhí)行審批：敏感命令需用戶批準(zhǔn)或白名單

4.3 可擴(kuò)展性

插件系統(tǒng)：渠道、技能、工具都可通過插件擴(kuò)展
多賬號支持：同一渠道可配置多個賬號（如兩個 WhatsApp 號碼）
遠(yuǎn)程部署：支持 SSH 隧道/Tailscale 遠(yuǎn)程訪問

4.4 記憶與連續(xù)性

文件即記憶：所有重要信息寫入文件，不依賴"心理筆記"
定期維護(hù)：心跳機制定期審查和提煉記憶
會話持久化：JSONL 轉(zhuǎn)錄永久保存（可配置修剪）

五、目錄結(jié)構(gòu)

~/.openclaw/
├── openclaw.json              # 主配置文件
├── workspace/                 # 默認(rèn)工作空間
│   ├── 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/               # 渠道認(rèn)證
│   └── <channel>/
└── logs/                      # 日志

六、配置示例

6.1 基礎(chǔ)配置（單智能體）

{
  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 節(jié)點主機配置

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

七、常用命令

# 網(wǎng)關(guān)管理
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

# 節(jié)點管理
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
社區(qū)：https://discord.com/invite/clawd

到此這篇關(guān)于OpenClaw學(xué)習(xí)筆記：研究官網(wǎng)文檔后整理的架構(gòu)詳解的文章就介紹到這了,更多相關(guān)OpenClaw架構(gòu)的學(xué)習(xí)筆記內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章:

最新国产好看的视频,伊人天堂AV在线,国产Aaaaaa视频,蜜臀视频在线观看一区,人妻av色图,密臀久久久精品影片,青青视频免费观看毛片,久草在线观看视,国产三级精品色情在线

OpenClaw學(xué)習(xí)筆記：研究官網(wǎng)文檔后整理的架構(gòu)詳解

目錄

背景

一、架構(gòu)總覽

二、各層詳解

2.1 渠道層 (Channels Layer)

2.2 網(wǎng)關(guān)層 (Gateway Layer)

2.2.1 WebSocket 控制平面

2.2.2 消息路由引擎

2.2.3 多智能體路由

2.2.4 服務(wù)管理

2.3 智能體層 (Agent Layer)

2.3.1 智能體運行時

2.3.2 技能系統(tǒng) (Skills)

2.3.3 記憶系統(tǒng)

2.3.4 會話管理

2.4 執(zhí)行層 (Execution Layer)

2.4.1 工具執(zhí)行

2.4.2 節(jié)點系統(tǒng) (Nodes)

2.4.3 沙箱與安全

三、組件交互流程

3.1 消息處理流程

3.2 節(jié)點交互流程

3.3 多智能體路由流程

四、關(guān)鍵設(shè)計原則

4.1 單一事實來源

4.2 隔離與安全

4.3 可擴(kuò)展性

4.4 記憶與連續(xù)性

五、目錄結(jié)構(gòu)

六、配置示例

6.1 基礎(chǔ)配置（單智能體）

6.2 多智能體配置

6.3 節(jié)點主機配置

七、常用命令

八、參考資料

相關(guān)文章

最新評論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

一、架構(gòu)總覽

二、各層詳解

三、組件交互流程

五、目錄結(jié)構(gòu)

六、配置示例

七、常用命令