OpenClaw 專題：架構分析 🦞

上一篇聊了生態，這一篇拆架構。

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

0. 先認幾個詞

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

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

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

先看全景圖：

OpenClaw Architecture

你可以把 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 的所有組態，都是你能直接打開編輯的文字檔：

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

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

每一輪對話怎麼跑

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

上下文的組裝不是把所有東西一股腦塞進去。不相關的技能不載入、不需要的工具不注入：省 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，各管各的。路由規則長這樣：

1
{
2
  "bindings": [
3
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
4
    { "agentId": "work", "match": { "channel": "slack" } },
5
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
6
  ]
7
}

翻譯一下：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 穩定性、沙箱真的能不能防住攻擊、跨頻道認人的邊界情況：需要更多真實使用資料來驗證。

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