10 · 設計覆盤：OpenClaw 為什麼這樣設計

前 9 篇講的是零件。這一篇講整機。

OpenClaw 的核心不是“更會聊天”，而是把一個 AI Agent 放進可執行、可審計、可限制、可恢復的本地系統裡。它用 Gateway 管入口，用 Session 管當前上下文，用 Workspace 管長期工作環境，用 Memory 管跨會話事實，用 Tool policy 和 Sandbox 管能力邊界，用 Heartbeat / Cron / Webhooks 把時間和外部事件接進來。

這套設計的底層目標很樸素：

1. 一張圖看完整系統

flowchart LR
  U[User / external system] --> C[Channel / Webhook / CLI]
  C --> G[Gateway]
  G --> R[Routing]
  R --> S[Session key]
  S --> L[Agent Loop]
  W[Workspace files] --> X[Context assembly]
  M[Memory files + search] --> X
  X --> L
  L --> P[Model]
  P --> T[Tools]
  TP[Tool policy] --> T
  SB[Sandbox / elevated] --> T
  T --> L
  L --> O[Reply / persistence]
  O --> C
  HB[Heartbeat] --> G
  CR[Cron] --> G
  BK[Background tasks ledger] --> G

按官方文件拆開：

2. 系統不變數

理解 OpenClaw，先記這幾條不變數：

• Gateway 是控制面：Messaging channels、Control UI、CLI、Nodes、WebChat 都圍繞 Gateway；clients 和 nodes 透過 WebSocket 接入。不要把某個聊天渠道當成系統核心。
• Agent Loop 按 session 序列：一次 run 是 intake -> context assembly -> model inference -> tool execution -> streaming replies -> persistence。同一 session 要避免互踩。
• Workspace 是工作環境：工具相對路徑以 workspace 為預設 cwd。Workspace 不是安全邊界。
• Memory 沒有隱藏層：模型只“記得”寫入磁碟的內容，memory search 只是幫它檢索材料。不要以為模型自動保留所有歷史。
• Context 不是 Memory：Context 是本次 run 發給模型的全部輸入，受視窗限制。不是存了 memory 就等於本輪一定看見。
• Security 預設是個人 operator boundary：shared Gateway 不等於敵對多租戶安全邊界。陌生使用者或客戶要拆 Gateway、credentials、OS user 或 host。

3. 取捨一：長駐 Gateway，而不是每個平臺各跑一套

OpenClaw 選擇單個長期執行的 Gateway 來管理平臺連線。

得到的是：

• WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等入口統一接入。
• CLI、macOS app、web UI、automations 走同一套 Gateway API。
• 健康狀態、presence、heartbeat、cron、agent run 都能在一個控制面觀察。

付出的代價是：

• Gateway 是關鍵程序，掛了就影響所有 channel。
• 配置和日誌集中在 ~/.openclaw，許可權管理必須嚴謹。
• 非 loopback 暴露會擴大攻擊面。

適用邊界很簡單：個人助理、小團隊、單 operator boundary 適合共享一個 Gateway；敵對多租戶或客戶共享 runtime 時應該拆 Gateway。

4. 取捨二：嵌入式 Agent Loop，而不是黑盒外包

OpenClaw 不是簡單把訊息轉給一個外部聊天 API。它有自己的 embedded agent runtime 和 agent loop。

這讓 OpenClaw 能控制：

• session resolution；
• model 和 auth profile 選擇；
• skills snapshot；
• prompt assembly；
• tool execution；
• streaming；
• compaction retry；
• transcript persistence；
• hooks；
• timeout 和 cancellation。

得到的是可觀察、可插拔、可約束。代價是系統概念變多：Agent Loop、Session、Context、Tool policy、Hooks 都需要理解。

這個取捨的實際意義：

5. 取捨三：Workspace 檔案，而不是隱藏配置面板

Workspace 裡放的是 Agent 可讀、可修改、可遷移的工作材料：

得到的是透明和可遷移：

• 讀檔案就能看到 Agent 的規則和記憶。
• 私有 git repo 就能做備份和回復。
• 遷移 workspace 比遷移資料庫更直觀。

代價是：

• Workspace 必須當作私密記憶處理。
• 不該把 secrets、raw chat dumps、~/.openclaw 裡的配置和 credentials 提交進去。
• Workspace 不是 sandbox，安全隔離要另配。

6. 取捨四：磁碟 Memory，而不是模型隱藏狀態

OpenClaw 的長期記憶不是“模型自己會記住”，而是寫入 workspace 檔案。

官方 Memory 體系的關鍵件包括：

• MEMORY.md：durable facts、preferences、decisions。
• memory/YYYY-MM-DD.md：daily notes。
• DREAMS.md：optional review diary and dreaming summaries。
• memory_search：semantic + keyword retrieval。
• memory_get：exact file / line range read。
• memory flush：compaction 前的 silent turn。

得到的是：

• 人能檢查、編輯、刪除。
• Git 能追蹤記憶變化。
• Memory 和 Context 分離，降低“當前視窗塞爆”的風險。

代價是：

• Agent 必須真的把重要資訊寫入檔案。
• Memory 質量取決於寫入和整理。
• 需要檢索時要用 memory_search 或結構化 wiki 外掛，而不是假設所有歷史自動可見。

正確心智模型：

7. 取捨五：確定性路由，而不是 AI 自己分發

Channel Routing 文件強調：模型不選擇 channel，host config 決定路由。

多 Agent 路由也類似：Exact peer、thread parent、guild roles、guild、team、account、channel、default agent，按固定順序匹配。

得到的是：

• 訊息不會因為模型判斷失誤發給錯誤 Agent。
• 審計時可以從配置倒推訊息流向。
• 安全規則能和路由規則繫結。

代價是：

• 需要配置 bindings。
• 使用者要知道在哪個 channel 或 thread 找哪個 Agent。
• 配錯路由時，系統會穩定地錯，需要人修配置。

這就是 OpenClaw 的一個核心立場：

8. 取捨六：Session 生命週期，而不是無限聊天

Session 管的是當前對話桶。它有 sessionKey 和當前 sessionId，transcript 以 JSONL 存在磁碟。

生命週期規則包括：

• Daily reset 預設在 Gateway host 本地時間凌晨 4 點後換新 session。
• Idle reset 可選。
• /new 和 /reset 手動換新 session。
• Daily 和 idle 同時配置時，先到期的生效。
• 舊 transcript 不等於刪除，memory 不等於 reset。

得到的是：

• 上下文不會無限增長。
• transcript 和當前執行狀態分開。
• compaction、pruning、session cleanup 有明確物件。

代價是：

• 新手會誤以為 reset 等於失憶。
• 重要事實必須進入 memory 或 workspace 檔案，不能只停留在舊 session 裡。

9. 取捨七：Context 有預算，而不是全量塞進去

Context 受模型視窗限制，OpenClaw 要構建 system prompt、注入 workspace files、帶 conversation history、工具結果和附件。

為了不讓 prompt 失控，OpenClaw 提供：

• /status 看視窗占用；
• /context list 看注入內容；
• /context detail 看更細的大小貢獻；
• compaction 總結長對話；
• pruning 從本次模型輸入裡移除舊工具結果，但不改 transcript；
• context engine 外掛介面。

得到的是可控成本和可解釋的上下文組成。

代價是你不能說“Agent 應該看到所有東西”。它只能看到這次 run 被裝進 context 的東西。

10. 取捨八：Heartbeat、Cron、Webhook 分開

OpenClaw 沒把所有自動化都塞進一個“任務系統”。

三者邊界：

Tasks 只負責記錄後臺工作：Cron executions、subagents、ACP runs、CLI operations 會建立 Task；Heartbeat、普通聊天、直接 slash command 不會因為“發生了”就自動變成 Task。

得到的是概念清晰。代價是新手一開始要分清“觸發機制”和“臺賬”。

11. 取捨九：Sandbox、Tool policy、Elevated 分開

這三個詞必須分清：

• Sandbox 控制工具在哪裡執行。
• Tool policy 控制哪些工具能被呼叫。
• Elevated 控制 sandboxed exec 是否能出沙箱到 host。

官方規則裡，deny 永遠優先，allow 非空時其他工具都 blocked。/exec 不能覆蓋被 deny 的 exec。Elevated 不授予額外工具，也不覆蓋 tool allow/deny。

得到的是精準控制：

• 私人 Agent 可以 full access。
• 家庭/團隊 Agent 可以 sandbox + read-only。
• 公共 Agent 可以 no filesystem/shell。

代價是配置複雜。但安全領域裡，複雜度比“所有人都拿 root 許可權”更可接受。

12. 取捨十：多 Agent 是邊界，不只是分工

多 Agent 不是把一個人拆成多個聊天視窗。官方多 Agent 模型裡，一個 Agent 是 workspace、agentDir、session store、模型/工具/許可權配置的 scope。

拆 Agent 的理由：

• persona 不同；
• workspace 不同；
• credentials 不同；
• sandbox/tool policy 不同；
• session store 不同；
• channel bindings 不同。

不該拆的理由：

• 只是同一個 Agent 的臨時後臺任務；
• 只是想並行分析一個問題；
• 只是想讓主 Agent 派一個子任務。

後者更適合 sub-agent 或 Cron isolated run。

13. 取捨十一：Hooks 和 Plugins 開擴充套件口

OpenClaw 有兩類 hook：Internal hooks 位於 Gateway 事件指令碼層，典型例子是 /new、/reset、/stop、agent:bootstrap、gateway:startup；Plugin hooks 位於 Agent/tool/gateway pipeline 內部擴充套件點，典型例子是 before_tool_call、before_prompt_build。

得到的是可擴充套件：

• reset 時寫 memory；
• bootstrap 前注入檔案；
• tool call 前做 policy；
• plugin install 前做掃描；
• message dispatch 前後做處理。

代價是 hook/plugin 程式碼也進入 trust boundary。安裝 plugin 等於給 Gateway 增加程式碼能力，不能當普通配置看。

14. 什麼時候應該重新設計

OpenClaw 當前設計很適合個人助理、工作室、小團隊、自託管自動化。約束變了，取捨也要變。

需要拆更硬邊界的場景：

• 陌生使用者共享一個 Agent：shared authority 風險太高。
• 客戶資料不能混在一個 Gateway：Gateway 不是敵對多租戶邊界。
• Agent 有寫生產系統的能力：工具後果不可只靠 prompt 控制。
• 瀏覽器 profile 有真實後臺登入態：cookie 和登入態就是許可權。
• 合規要求每個部門單獨審計 credentials：憑據和日誌需要獨立臺賬。

這些場景下優先：

• 分 Gateway；
• 分 credentials；
• 分 OS user；
• 分 host 或 VPS；
• 公共入口只給 sandboxed + messaging-only tools；
• 關閉 elevated；
• 關閉 host browser control；
• 開啟 strict browser SSRF policy；
• 用 openclaw security audit --deep 做基線檢查。

不要用一句“我們配置了 prompt 防禦”來替代系統邊界。

15. 一句話解釋每個核心概念

你可以用這組句子自測：

• Gateway：所有 channel、client、node、automation 進入 OpenClaw 的控制面。
• Channel：把不同訊息平臺標準化，並把回覆送回確定目標。
• Agent：帶 workspace、session store、模型和工具邊界的執行主體。
• Agent Loop：一次訊息變成回覆和動作的完整執行鏈路。
• Workspace：Agent 的工作目錄和長期檔案環境，不是安全沙箱。
• Memory：寫在磁碟上的長期事實和檢索索引，不是模型隱藏記憶。
• Context：本次 run 實際發給模型的全部輸入。
• Session：當前對話桶，決定歷史、併發和當前 transcript。
• Compaction：把長對話壓成摘要，保留可繼續執行的上下文。
• Heartbeat：週期性主會話檢查。
• Cron：Gateway 精確排程器。
• Webhook：外部系統主動觸發 OpenClaw 的入口。
• Task：後臺工作的狀態臺賬。
• Tool policy：哪些工具可被呼叫。
• Sandbox：工具執行位置和檔案系統邊界。
• Elevated：sandboxed exec 的出沙箱開關。
• Hook：在特定 Gateway 或 Agent 生命週期點插入邏輯。

如果你能不用看前文解釋這些概念之間的關係，這個理解系列就完成了。

16. 給 Agent 的架構覆盤任務

把這段發給 OpenClaw Agent，做一次只讀架構審計：

请只读复盘当前 OpenClaw 部署架构，不要修改文件。

要求：
1. 运行 openclaw status、openclaw gateway status，说明 Gateway bind、port、remote/local mode。
2. 运行 openclaw sessions --json，总结当前 session 类型、活跃度、store path。
3. 运行 /context list 或 openclaw agent 侧可用命令，说明 workspace bootstrap 和主要 context 来源。
4. 检查 workspace 文件：AGENTS.md、SOUL.md、TOOLS.md、USER.md、IDENTITY.md、HEARTBEAT.md、MEMORY.md、memory/。
5. 检查 channels 配置，说明 DM policy、group policy、mention gating、context visibility。
6. 运行 openclaw sandbox explain --json，总结 sandbox、tool policy、elevated gates。
7. 检查 heartbeat、cron、webhook、tasks 配置和最近状态。
8. 输出一张文字版架构图：入口 -> Gateway -> route -> session -> agent loop -> tools -> persistence。
9. 标出三个最可能导致误用的边界，并给出最小修复建议。

17. 系列完成自檢

到這裡，你應該能回答：

1. 為什麼 OpenClaw 要用 Gateway 做控制面？
2. 為什麼 Agent Loop 需要按 session 序列？
3. Workspace 為什麼不是 sandbox？
4. Memory 和 Context 的邊界是什麼？
5. 為什麼 Channel routing 不能交給模型猜？
6. 為什麼 reset 不等於失憶？
7. 為什麼 Heartbeat、Cron、Webhook、Tasks 不能混成一個概念？
8. 為什麼 tool policy 比 prompt 防禦更硬？
9. 什麼場景必須拆 Gateway 或 host？
10. 你自己的 OpenClaw 部署裡，最危險的入口在哪裡？

18. 接下來去哪

19. 官方資料

• Gateway architecture
• Agent Runtime
• Agent Loop
• Agent workspace
• Memory overview
• Context
• Session management
• Channel Routing
• Automation & Tasks
• Security