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

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

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

背景

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

一、架構(gòu)總覽

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

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

二、各層詳解

2.1 渠道層 (Channels Layer)

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

核心組件：

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

關(guān)鍵能力：

消息收發(fā)（文本 + 媒體）
配對(duì)認(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)，所有消息和控制的單一事實(shí)來(lái)源。

核心組件：

2.2.1 WebSocket 控制平面

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

2.2.2 消息路由引擎

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

2.2.3 多智能體路由

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

2.2.4 服務(wù)管理

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

2.3 智能體層 (Agent Layer)

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

核心組件：

2.3.1 智能體運(yùn)行時(shí)

基礎(chǔ)：基于 pi-agent 的嵌入式運(yùn)行時(shí)
工作空間文件（啟動(dòng)時(shí)注入）：
- AGENTS.md — 操作指令 + 記憶規(guī)則
- SOUL.md — 人格、語(yǔ)氣、邊界
- USER.md — 用戶檔案
- IDENTITY.md — 智能體身份
- MEMORY.md — 長(zhǎng)期記憶（僅主會(huì)話）
- BOOTSTRAP.md — 首次啟動(dòng)引導(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
- 會(huì)話：sessions_*, subagents, cron
- 設(shè)備：nodes_*, canvas, tts
- 消息：message
技能來(lái)源：
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)

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

2.3.4 會(huì)話管理

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

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

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

核心組件：

2.4.1 工具執(zhí)行

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

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

節(jié)點(diǎn)類型：
- iOS/Android 移動(dòng)節(jié)點(diǎn)
- macOS 節(jié)點(diǎn)（菜單欄應(yīng)用）
- Headless 節(jié)點(diǎn)（跨平臺(tái)）
節(jié)點(diǎn)能力：
- 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：無(wú)沙箱
- all：始終沙箱
- Docker 容器（每智能體或共享）
執(zhí)行審批：
- ask：每次詢問(wèn)
- allowlist：白名單自動(dòng)批準(zhǔn)
- full：完全開放
安全邊界：
- 工作空間內(nèi)：自由操作
- 工作空間外：只讀，修改需授權(quán)
- 外部動(dòng)作（郵件/推文）：必須先問(wè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)建/加載會(huì)話 (Session Store + JSONL)
         │
         ▼
5. 智能體運(yùn)行時(shí)處理消息：
   - 讀取工作空間文件 (AGENTS.md, SOUL.md, MEMORY.md...)
   - 調(diào)用工具 (read/exec/web_search...)
   - 可能 spawn 子智能體
         │
         ▼
6. 智能體生成回復(fù)
         │
         ▼
7. 網(wǎng)關(guān)層通過(guò)原渠道發(fā)送回復(fù)
         │
         ▼
8. 更新會(huì)話狀態(tài) + 轉(zhuǎn)錄記錄

3.2 節(jié)點(diǎn)交互流程

1. 智能體調(diào)用 nodes.* 工具
         │
         ▼
2. 網(wǎng)關(guān)層通過(guò) WebSocket 轉(zhuǎn)發(fā)到節(jié)點(diǎn)
         │
         ▼
3. 節(jié)點(diǎn)執(zhí)行命令 (canvas/camera/screen/location...)
         │
         ▼
4. 節(jié)點(diǎn)返回結(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)先級(jí)匹配 Bindings：
   a. 檢查 peer 精確匹配
   b. 檢查 guildId/roles 匹配
   c. 檢查 accountId 匹配
   d. Fallback 到默認(rèn)智能體
         │
         ▼
3. 消息路由到目標(biāo)智能體的主會(huì)話或獨(dú)立會(huì)話
         │
         ▼
4. 各智能體獨(dú)立處理（不同工作空間/模型/工具策略）

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

4.1 單一事實(shí)來(lái)源

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

4.2 隔離與安全

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

4.3 可擴(kuò)展性

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

4.4 記憶與連續(xù)性

文件即記憶：所有重要信息寫入文件，不依賴"心理筆記"
定期維護(hù)：心跳機(jī)制定期審查和提煉記憶
會(huì)話持久化：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é)點(diǎn)主機(jī)配置

{
  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>

# 會(huì)話管理
openclaw sessions list --active 60
openclaw sessions cleanup --dry-run

# 節(jié)點(diǎn)管理
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
技能市場(chǎng)：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)容請(qǐng)搜索腳本之家以前的文章或繼續(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 智能體運(yùn)行時(shí)

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

2.3.3 記憶系統(tǒng)

2.3.4 會(huì)話管理

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

2.4.1 工具執(zhí)行

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

2.4.3 沙箱與安全

三、組件交互流程

3.1 消息處理流程

3.2 節(jié)點(diǎn)交互流程

3.3 多智能體路由流程

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

4.1 單一事實(shí)來(lái)源

4.2 隔離與安全

4.3 可擴(kuò)展性

4.4 記憶與連續(xù)性

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

六、配置示例

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

6.2 多智能體配置

6.3 節(jié)點(diǎn)主機(jī)配置

七、常用命令

八、參考資料

相關(guān)文章

最新評(píng)論

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

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

常用在線小工具

一、架構(gòu)總覽

三、組件交互流程

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

六、配置示例

八、參考資料