OpenClaw 架構：自託管 AI 助手的工程骨架 🦞

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

OpenClaw 的程式碼量不小：43 萬行 TypeScript。但這篇文章不看程式碼量，看複雜性怎麼被分配。一個自託管 AI 助手要同時處理二十多個聊天入口、多個 Agent、工具呼叫和權限邊界；架構問題不是「功能怎麼塞進去」，而是「哪些複雜性應該留在執行時，哪些應該推給模型、CLI 和策略層」。

0. 先認幾個詞

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

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

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

先看全景圖：

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

整個系統的核心就是 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 裡面跑。

「一切皆文字」的工作區

這裡的關鍵設計是：每個 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 產品做不到的。

每一輪對話怎麼跑

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

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

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

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

幾個巧妙的機制：

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

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

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

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

6. 工具系統：把複雜性轉移到 CLI

OpenClaw 的工具系統很克制。

很多 AI Agent 框架會預置大量專用工具。OpenClaw 只保留 4 個核心工具：

這條路線的前提是：命令列已經封裝了大量現實世界能力。查天氣可以呼叫 curl，寄信可以呼叫 CLI，查資料庫可以走 psql。系統不為每個場景預製工具，而是把通用執行介面交給模型。

代價也很明確：模型必須知道該呼叫什麼命令、如何組合命令、什麼時候停止。複雜性沒有消失，只是從工具清單轉移到了模型能力、CLI 生態和權限策略。

在這 4 個核心工具之上，還有 55 個內建 Skills 和 ClawHub 技能市場。Skills 負責把高頻流程封裝起來，避免每次都從 Bash 層重新規劃。

MCP 被放在旁路，而不是主路徑。 MCP 是 Anthropic 推出的工具協議標準，很多 AI 框架都在接入。OpenClaw 的主路徑選擇 CLI/Unix，並用內建的 mcporter 做橋接。這不是單純反標準，而是把工具生態的中心放在命令列可組合性上。

自我擴展把能力沉澱成 skill。 OpenClaw Agent 遇到不會做的事，可以生成 skill、安裝、再在發現問題時修改重新載入。關鍵不在「自動變強」，而在臨場解法能否沉澱成可複用流程。

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 個核心工具的路線是一場複雜性轉移。 它賭的不是「工具越少越好」，而是模型能力、CLI 生態和權限策略加在一起，能比大量預製工具更可擴展。如果模型能力不足，Bash 會變成風險入口；如果權限收得住，這條路線會把工具系統做得很薄。

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

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