最近在研究 AI 助手的自架方案，把 OpenClaw 的架構翻了個底朝天。這篇文章把我的理解整理出來，希望能幫到同樣在研究的朋友。
OpenClaw 是一個開源的 AI 助手執行時期平台，核心理念是：一個 Gateway 連接所有聊天平台，一個 Agent Runtime 調度所有 AI 模型。
你可以把它理解為「AI 助手的作業系統」——它不是一個聊天機器人，而是讓你在 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等十幾個平台上執行同一個 AI 助手的基礎設施。
跟 Dify、Coze 這類「拖拉式 AI 應用建構平台」不同，OpenClaw 更偏底層：它關心的是訊息怎麼路由、上下文怎麼組裝、工具怎麼執行、記憶怎麼持久化。
xujfcn
┌─────────────────────────────────────────────────────────┐
│ Control Plane │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ macOS App│ │ CLI │ │ Web UI │ │ WebChat │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ └──────────────┼──────────────┼─────────────┘ │
│ │ WebSocket │ │
│ ┌───────▼──────────────▼───────┐ │
│ │ GATEWAY │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Channel Adapters │ │ │
│ │ │ WhatsApp│Telegram│Slack │ │ │
│ │ │ Discord│Signal│iMessage │ │ │
│ │ └─────────────────────────┘ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Session Manager │ │ │
│ │ │ Auth │ Protocol │ Cron │ │ │
│ │ └─────────────────────────┘ │ │
│ └──────────────┬───────────────┘ │
│ │ │
│ ┌──────────────▼───────────────┐ │
│ │ AGENT RUNTIME │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │Memory│ │Tools │ │Canvas│ │ │
│ │ └──────┘ └──────┘ └──────┘ │ │
│ │ ┌──────────────────────────┐│ │
│ │ │ Model Providers ││ │
│ │ │ GPT│Claude│Gemini│DeepSeek││ │
│ │ └──────────────────────────┘│ │
│ └──────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ NODES │ │
│ │ macOS │ iOS │ Android │ Headless │ │
│ │ Camera│Screen│Location│Canvas │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
整個系統分為四層：
OpenClaw 的設計哲學是單 Gateway 架構：一台主機上只執行一個 Gateway 程序，它獨佔所有訊息通道的連線。
# 啟動 Gateway
openclaw gateway
# 預設監聽
# WebSocket: 127.0.0.1:18789
# HTTP (Canvas): 同埠
為什麼是單一程序？因為 WhatsApp（透過 Baileys 函式庫）要求單一工作階段連線，Telegram Bot 也是單一實例。與其搞複雜的分散式鎖，不如讓一個程序管所有事。
Gateway 的所有通訊都走 WebSocket，協定設計非常乾淨：
// 請求
{"type": "req", "id": "abc123", "method": "agent", "params": {...}}
// 回應
{"type": "res", "id": "abc123", "ok": true, "payload": {...}}
// 事件（伺服器推送）
{"type": "event", "event": "agent", "payload": {...}, "seq": 42}
關鍵設計決策：
connect：任何非 JSON 或非 connect 的首 frame 直接斷開send、agent）必須帶冪等性 Key，伺服器端維護短期去重快取OpenClaw 的安全模型分兩層：
裝置配對（Pairing）：
connect 時攜帶裝置身份platform + deviceFamily，中繼資料變更需要重新配對Token 認證：
OPENCLAW_GATEWAY_TOKEN 後，所有連線必須在 connect.params.auth.token 中提供匹配的 Token# SSH 通道遠端存取
ssh -N -L 18789:127.0.0.1:18789 user@host
OpenClaw 的工作階段（Session）是 Agent 執行時期的核心概念。每個聊天視窗、每個使用者對話都是一個獨立的工作階段。
工作階段的關鍵特性：
{
agents: {
defaults: {
compaction: {
reserveTokensFloor: 20000,
memoryFlush: {
enabled: true,
softThresholdTokens: 4000,
systemPrompt: "Session nearing compaction. Store durable memories now.",
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply NO_REPLY if nothing to store."
}
}
}
}
}
這個設計非常巧妙——在上下文被壓縮之前，給 AI 一次「臨終遺言」的機會，把重要資訊寫到檔案裡。
每次 Agent 回合，執行時期需要組裝完整的上下文：
SOUL.md、AGENTS.md、USER.md 等檔案載入MEMORY.md（僅主工作階段）和 memory/YYYY-MM-DD.md
OpenClaw 的工具執行是一個經典的 ReAct 迴圈：
使用者訊息 → 模型思考 → 呼叫工具 → 取得結果 → 模型繼續思考 → ... → 最終回覆
內建工具非常豐富：
exec：執行 Shell 命令read/write/edit：檔案操作web_search/web_fetch：網路搜尋和擷取browser：瀏覽器自動化memory_search/memory_get：記憶檢索message：跨平台訊息傳送sessions_spawn：子代理編排OpenClaw 的記憶系統是我最欣賞的設計之一。它沒有搞什麼複雜的向量資料庫，而是用純 Markdown 檔案作為記憶的載體。
workspace/
├── MEMORY.md # 長期記憶（人工策展）
└── memory/
├── 2026-03-05.md # 昨天的日誌
├── 2026-03-06.md # 今天的日誌
└── heartbeat-state.json
MEMORY.md：長期記憶，類似人的「長期記憶」。存放決策、偏好、重要事實。僅在主工作階段載入（安全考量）。memory/YYYY-MM-DD.md：每日日誌，類似人的「工作記憶」。追加寫入，每次工作階段載入今天和昨天的。雖然記憶是 Markdown 檔案，但 OpenClaw 在上面建了一層向量索引：
memory_search 工具做語意檢索這個設計選擇背後的哲學是：檔案是真相的唯一來源。
OpenClaw 的外掛系統圍繞四個核心插槽（Slot）設計：
| 插槽 | 職責 | 範例 |
|---|---|---|
| Channel | 訊息通道適配 | WhatsApp、Telegram、Discord、Slack、Signal、iMessage、IRC、Matrix、LINE... |
| Memory | 記憶儲存和檢索 | memory-core（預設）、自訂向量後端 |
| Tool | 工具能力擴充 | 瀏覽器控制、檔案操作、API 呼叫、飛書整合 |
| Provider | 模型提供者 | OpenAI、Anthropic、Google、DeepSeek... |
Channel 外掛的豐富程度令人印象深刻——從主流的 WhatsApp/Telegram/Discord，到小眾的 Nostr/IRC，甚至都支援。這意味著你可以在幾乎任何聊天平台上執行你的 AI 助手。
Gateway 的 HTTP 伺服器提供兩個特殊路徑：
/__openclaw__/canvas/：Agent 可以動態產生和編輯的 HTML/CSS/JS 頁面/__openclaw__/a2ui/：A2UI（Agent-to-UI）宿主Canvas 讓 AI 助手不再侷限於文字回覆——它可以產生互動式的 Web 介面、資料視覺化、甚至小應用程式。
Nodes 是 OpenClaw 最有想像力的設計之一。任何裝置（macOS、iOS、Android、Headless）都可以作為 Node 連接到 Gateway：
{
"role": "node",
"caps": ["camera", "screen", "location", "canvas"],
"commands": ["camera.snap", "screen.record", "location.get"]
}
這意味著你的 AI 助手可以：
讓我們追蹤一條訊息從使用者發送到 AI 回覆的完整路徑：
1. 使用者在 Telegram 傳送「幫我查一下今天的天氣」
│
2. Telegram Bot API → Gateway Channel Adapter (grammY)
│ 解析訊息、擷取文字、識別工作階段
│
3. Gateway Session Manager
│ 尋找/建立工作階段、檢查權限
│
4. Agent Runtime 開始新回合
│
├─ 4a. 組裝上下文
│ System Prompt + SOUL.md + MEMORY.md
│ + memory/2026-03-06.md + 工具定義 + 歷史訊息
│
├─ 4b. 呼叫 AI 模型
│ POST /v1/chat/completions
│ → 模型回傳：呼叫 weather 工具
│
├─ 4c. 執行工具
│ weather("台北") → 取得天氣資料
│
├─ 4d. 再次呼叫模型
│ 將工具結果注入上下文
│ → 模型產生最終回覆
│
5. Gateway 將回覆路由回 Telegram
│
6. 使用者在 Telegram 收到天氣資訊
| 特性 | OpenClaw | Dify | Coze | AutoGPT |
|---|---|---|---|---|
| 定位 | AI 助手執行時期 | AI 應用建構平台 | AI Bot 平台 | 自主 AI Agent |
| 部署方式 | 自架（單一程序） | 自架/雲端 | 雲端服務 | 自架 |
| 聊天平台 | 15+ 原生支援 | 需要額外整合 | 有限 | 無 |
| 記憶系統 | Markdown + 向量 | 向量資料庫 | 雲端 | 檔案系統 |
| 多端協同 | Canvas + Nodes | 無 | 無 | 無 |
| 開源 | ✅ | ✅ | ❌ | ✅ |
OpenClaw 的獨特優勢在於：
OpenClaw 需要設定 AI 模型的 API 才能運作。這裡推薦使用 Crazyrouter 作為統一的 API 閘道——一個 Key 呼叫 627+ 模型（GPT-5、Claude 4.6、Gemini 3、DeepSeek V3 等），價格約為官方的 55%。
設定方式：
{
providers: {
openai: {
baseUrl: "https://crazyrouter.com/v1",
apiKey: "sk-your-crazyrouter-key"
}
}
}
這樣設定後，OpenClaw 的所有模型呼叫都會透過 Crazyrouter 路由，自動享受負載平衡和 failover。
💡 Crazyrouter 支援 OpenAI/Anthropic/Gemini 三種 API 格式，跟 OpenClaw 的多模型架構天然契合。新使用者註冊送 $0.2 額度，額度永不過期。
如果你正在建構自己的 AI 助手系統，OpenClaw 的原始碼絕對值得一讀。
相關連結：
iThome鐵人賽
看影片追技術