---
title: OpenClaw 專題：架構分析 🦞
date: "2026-02-24T16:37:11+08:00"
category: "OpenClaw"
description: 基於 v2026.3.8 原始碼，拆解一個自託管 AI 助手的工程骨架
tags: [AI, open-source, openclaw]
pinned: false
---

![OpenClaw](/images/openclaw-logo-text-dark.webp)

[上一篇](/zh-hant/posts/openclaw-ecosystem/)聊了生態，這一篇拆架構。

OpenClaw 的程式碼量不小：43 萬行 TypeScript。但真正值得看的不是程式碼量，是它的架構選擇。一個要同時接二十多個聊天平台、管幾個 Agent、還能調工具的 AI 助手，它是怎麼把這些東西塞到一起還不散架的？

## 0. 先認幾個詞

如果你沒有系統架構背景，也沒關係。先記住 6 個詞，後面會順很多：

- `架構`：系統如何分層、每層分別負責什麼。
- `Channel / 頻道層`：負責和外部聊天平台「說同一種協議」的適配層。
- `Gateway / 閘道`：中央調度者，負責路由訊息、管理會話和 Agent。
- `Node / 執行節點`：真正去拍照、跑命令、操作裝置的執行端。
- `workspace / 工作區`：Agent 的設定、記憶、技能和會話檔案所在的本地目錄。
- `sandbox / 沙箱`：把高風險操作隔離起來的受限執行環境。

## 1. 3 層架構：Channel → Gateway → Node

先看全景圖：

![OpenClaw Architecture](/images/openclaw-architecture-zh-hant.svg)

你可以把 OpenClaw 想成一家公司的 3 個部門：

| 誰 | 幹什麼 | 打個比方 |
|------|------|--------|
| **Channel（頻道層）** | 對接 WhatsApp、Telegram、Discord、飛書等 20+ 聊天平台 | 前台：負責接電話、收郵件、接待來訪 |
| **Gateway（閘道）** | 中央調度，管理所有會話和 Agent | 大腦：誰的訊息該給誰處理、怎麼回覆，全在這裡決定 |
| **Node（執行節點）** | 在裝置上幹活：拍照、錄螢幕、跑命令 | 手和腳：大腦說「拍張照」，它去執行 |

整個系統的核心就是 Gateway：一個常駐運行的程序，預設只監聽本機（`127.0.0.1:18789`），不對外網開放。想遠端存取？走 Tailscale 隧道，不直接暴露埠號。這個設計叫「Loopback-First」，安全上很討巧：什麼埠號都不開，就沒有攻擊面。

為什麼只用一個程序不搞分散式？原因很實際：WhatsApp 協議要求同一時間只能有一個裝置在線，你搞兩個程序反而會打架。與其為了「架構正確」多搞一堆協調邏輯，不如老老實實一個程序管到底。對絕大多數個人使用者來說，夠用了。

## 2. 一條訊息的旅程

你在 Telegram 上跟你的 OpenClaw 說了一句「幫我查下明天台北天氣」，發生了什麼？

**第 1 步：接入。** Telegram 適配器收到訊息，把 Telegram 格式的資料翻譯成 OpenClaw 內部統一格式。不管訊息從哪個平台來，翻譯完都長一個樣。

**第 2 步：驗身份、找路由。** 你是誰？允不允許跟 Agent 說話？如果是陌生人，先彈一個配對碼讓主人批准。通過後，路由引擎決定這條訊息交給哪個 Agent。

**第 3 步：組裝上下文。** 從磁碟讀出你之前的聊天記錄，載入 Agent 的性格設定（SOUL.md）、行為規則（AGENTS.md），再從記憶庫裡語義搜尋相關內容。組裝成一份完整的「大腦簡報」。

**第 4 步：問大模型。** 這份簡報發給 Anthropic、OpenAI、DeepSeek、MiniMax、GLM、Qwen、Gemini 等大模型提供商（你設定了哪個就用哪個），模型一個字一個字地串流吐出回覆。

**第 5 步：執行工具。** 如果模型說「我需要跑個命令查天氣」，執行時會攔截這個請求，根據安全策略決定在哪裡執行（管理員的命令直接跑，陌生人的命令丟到 Docker 沙箱裡跑），然後把結果餵回給模型繼續生成。

**第 6 步：回覆。** 最終答案按 Telegram 的格式要求（字數限制、Markdown 規則等）拆好，發回給你。聊天記錄寫入磁碟。

整個鏈路中，真正慢的是第 4 步：等大模型吐第一個字。其他步驟基本都是毫秒級。

## 3. 頻道適配層：一次開發，到處說話

OpenClaw 對接了二十多個聊天平台，但不是每個平台都從零寫一套。它抽象了一層「適配器」，每個平台的適配器只負責四件事：

- **登入**：WhatsApp 掃 QR Code、Telegram 填 Bot Token、iMessage 用 macOS 原生能力：各平台各的規矩
- **翻譯進來的訊息**：不管是文字、圖片、回覆還是表情，統統翻譯成內部統一格式
- **管門禁**：誰能私聊、群裡要不要 @才回覆、哪些群允許
- **翻譯出去的回覆**：把 Agent 的回覆適配成各平台能顯示的格式

內建的有六個大平台（WhatsApp、Telegram、Discord、Slack、Signal、iMessage），其他三十多個（飛書、LINE、Matrix、Mattermost 等）透過外掛接入。

這層抽象最大的好處是：Agent 完全不需要知道訊息來自哪個平台。你在 WhatsApp 上聊的 Agent 和在 Telegram 上聊的是同一個，邏輯完全複用。頻道只是「傳話筒」，換一個傳話筒不影響說話的人。

## 4. Agent 執行時與工作區

Agent 執行時的核心來自 Pi-mono（一個開源程式設計 Agent），嵌入在 Gateway 裡面跑。

### 「一切皆文字」的工作區

這是 OpenClaw 最有意思的設計之一：每個 Agent 的所有組態，都是你能直接打開編輯的文字檔：

```
workspace/
├── AGENTS.md          # 定義 Agent 是誰、怎麼做事（相當於履歷+工作手冊）
├── SOUL.md            # 靈魂設定：性格、價值觀（寫好就不該改）
├── USER.md            # 記錄使用者資訊：你叫什麼、喜好是什麼
├── MEMORY.md          # 長期記憶：Agent 主動記下的重要事情
├── HEARTBEAT.md       # 定時任務：比如每天早上報天氣
├── memory/            # 日記本
│   └── YYYY-MM-DD.md  # 每天一頁，只追加不修改
├── skills/            # 技能包
└── sessions.json      # 會話記錄
```

沒有資料庫，沒有專用管理介面，純文字檔。想改 Agent 性格？打開 SOUL.md 改兩行就行。想看它記住了什麼？打開 MEMORY.md 直接看。這種「你能看到它的全部大腦」的透明感，是很多封閉 AI 產品做不到的。

### 每一輪對話怎麼跑

1. **分清身份**：你是管理員直聊、朋友私聊、還是群裡有人 @了它？不同來源，安全等級不同
2. **組裝記憶**：讀聊天記錄、載入性格和規則、搜尋相關的長期記憶，拼成一份完整上下文
3. **問大模型**：發給設定的模型，支援 fallback：主力模型掛了自動切備用
4. **幹活+記住**：執行工具呼叫，更新聊天記錄

上下文的組裝不是把所有東西一股腦塞進去。不相關的技能不載入、不需要的工具不注入：省 token 就是省錢。

## 5. 4 層記憶：讓 AI 真的「記住你」

普通聊天機器人關掉視窗就失憶了。OpenClaw 不會。它有 4 層記憶，從最深層的「我是誰」到最淺層的「剛才聊了啥」：

| 層 | 是什麼 | 打個比方 |
|------|--------|------|
| **SOUL** | 人格設定，永遠不變 | 你的性格：出生就定了 |
| **TOOLS** | 當前裝了哪些技能 | 你今天帶了哪些工具出門 |
| **USER** | 關於你的長期記憶 | 你的老朋友記得你愛吃什麼 |
| **Session** | 當前這次對話 | 此刻正在聊的話題 |

幾個巧妙的機制：

**每日日記。** 每天的對話會自動寫進 `memory/2026-03-12.md`（只追加，不覆蓋）。下次開聊時，Agent 會自動翻看今天和昨天的日記，保持連續感：「你昨天說要買的那本書，買了嗎？」

**自動搶救記憶。** 聊得太長，上下文快塞滿了怎麼辦？OpenClaw 會偷偷在背景跑一個隱形輪次，把重要資訊存進 MEMORY.md，然後壓縮掉舊內容。你察覺不到這個過程，但關鍵資訊不會丟。這個機制叫 Pre-Compaction。

**語義搜尋。** 你說「之前聊過的那個部署問題」，它能從記憶裡搜出來：不是靠關鍵字精確比對，而是靠語義理解。底層是向量搜尋（SQLite-vec）+ 傳統關鍵字搜尋（BM25）雙管齊下。

**跨平台認人。** 你在 Telegram 上跟它聊了半小時，切到 WhatsApp 繼續聊，它認得你。同一個人在不同平台的 ID 會被連結到同一個身份，共享同一份記憶。但群聊的記憶是隔離的：你在群裡說的話，不會洩露到私聊裡。

## 6. 工具系統：只給 4 把刀

這是 OpenClaw 最「叛逆」的設計。

別的 AI Agent 框架恨不得內建一百個工具。OpenClaw 只給了 4 個：

| 工具 | 一句話 |
|------|------|
| **Read** | 讀檔案 |
| **Write** | 寫檔案 |
| **Edit** | 改檔案 |
| **Bash** | 跑命令 |

就這？就這。

創辦人的邏輯是：有了命令列（Bash），你能幹任何事。想查天氣？`curl` 一下。想寄信？調個 CLI 工具。想操作資料庫？`psql` 命令搞定。不需要為每個場景預製一個專用工具。

這就是 Unix 哲學：小工具、可組合、文字流。代價是什麼？你需要一個夠聰明的模型，能自己想出該調什麼命令。所以 OpenClaw 推薦用 Claude Opus 這個級別的模型。弱模型可能搞不定。

在這 4 個核心工具之上，還有 55 個內建 Skills（技能）和 ClawHub 技能市場。Skills 是可以安裝和移除的：相當於給你的 Agent 裝 App。

**有意思的是，它故意不支援 MCP。** MCP 是 Anthropic 搞的工具協議標準，現在滿世界的 AI 框架都在接。OpenClaw 偏不。Peter 原話是：「MCP 是垃圾，不能 scale。你知道什麼能 scale？CLI。Unix。」替代方案是用內建的 `mcporter` 做橋接。

**更有意思的是自我擴展。** OpenClaw Agent 遇到不會幹的事，會自己寫一個 skill 來完成，寫完自動裝上。發現 skill 有 bug？自己改自己重新載入。這意味著你的 Agent 會在使用過程中越來越強：它在「養自己」。

## 7. 多 Agent 路由：一個大腦，多個人格

一個 Gateway 可以同時跑好幾個 Agent，各管各的。路由規則長這樣：

```json
{
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "slack" } },
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
  ]
}
```

翻譯一下：WhatsApp 私人號來的訊息給「家庭助手」處理，Slack 的給「工作助手」，Discord 某個伺服器的給「社群機器人」。三個 Agent 完全隔離：各自有自己的性格、記憶、技能和安全策略。

## 8. 安全：3 道門

你的 Agent 跑在你自己的伺服器上，能執行命令、讀寫檔案：安全當然是大事。OpenClaw 的安全模型分 3 道門：

**第一道門：你是誰？（私聊配對）** 陌生人給你 Agent 發訊息，Agent 不會直接回。它會發一個 6 位配對碼，你在已認證的頻道裡確認了，對方才能用。這是預設行為：關掉就意味著任何知道你號碼的人都能白嫖你的 API 額度。

**第二道門：VIP 通道（白名單）。** 信任的人可以直接加到白名單裡（`allowFrom`），跳過配對直接聊。

**第三道門：群裡別亂回（群組規則）。** 群聊裡 Agent 預設只在被 @ 時才回覆，不會對著群裡每條訊息都冒泡：既省 token，又不擾民。

再往下還有縱深防禦：工具權限五層過濾、Docker 沙箱隔離（陌生人的命令在沙箱裡跑）、安全稽核命令（`openclaw security audit`）。這些層是獨立的：配對碼洩露了？沙箱還在。沙箱被繞過了？工具策略還限制著能調什麼。

## 9. 幾個判斷

**單程序不是偷懶，是務實。** 對個人使用者來說，一個程序管到底比搞分散式靠譜得多。這個架構的天花板在哪？大概是同時在線的訊息量超過單機處理能力的時候：對絕大多數人來說，這一天不會來。

**頻道抽象層是最值錢的一層。** 二十多個平台的差異全封裝在適配器裡，Agent 完全不操心訊息從哪來。想加一個新平台？寫個適配器就行，Agent 邏輯一行不改。這個解耦做得非常乾淨。

**安全設計是認真的，但落地仍有差距。** 架構上從身份、沙箱到工具策略做了縱深防禦。但 Kaspersky 稽核發現了 512 個漏洞（8 個嚴重級別），說明藍圖畫得好和實際安全之間，隔著持續的工程投入。

**4 個核心工具的極簡路線是一場賭注。** 賭的是模型能力會持續上升，強到不需要預製工具就能「萬物皆可 Bash」。如果大模型的天花板卡住了，這條路會很難走。但如果模型能力繼續提升，這可能是最優雅的方案。

**最終的檢驗標準不是架構有多漂亮，而是跑得穩不穩。** 這篇分析基於原始碼靜態閱讀。實際效果：高併發下的 Gateway 穩定性、沙箱真的能不能防住攻擊、跨頻道認人的邊界情況：需要更多真實使用資料來驗證。

架構只是骨架，生產環境才是考場。