---
title: "10 · 設計覆盤：OpenClaw 為什麼這樣設計"
description: "把 Gateway、Agent Loop、Workspace、Memory、Session、Channel、Automation 與 Security 收束成一張架構圖。"
verifiedAt: "2026-05-06"
---

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

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

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

> [!TIP]
> 讓 Agent 能長期執行，但仍然可理解；讓 Agent 能做事，但仍然可限制；讓 Agent 能記住你，但不製造隱藏狀態。

## 1. 一張圖看完整系統

```mermaid
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
```

按官方文件拆開：

| 模組 | 官方定位 | 覆盤時看什麼 |
| --- | --- | --- |
| Gateway | 長期執行的控制面，維護訊息平臺連線，提供 typed WebSocket API，預設監聽 `127.0.0.1:18789` | 入口和控制面是否集中可審計 |
| Channel | 入站訊息和出站投遞，模型不選擇 channel | 路由是否確定 |
| Session key | 決定訊息進入哪段上下文，也決定併發 lane 和部分執行姿態 | 是否串上下文 |
| Agent Loop | intake、context assembly、model inference、tool execution、streaming replies、persistence | 一次 run 是否可觀察 |
| Workspace | Agent 的工作目錄和人格/指令檔案所在處 | 不要誤當成硬沙箱 |
| Memory | workspace 裡的 Markdown 檔案和索引 | 不要誤當成模型隱藏狀態 |
| Tool policy | 決定哪些工具能被呼叫 | 能力邊界是否明確 |
| Sandbox | 決定工具在哪裡執行 | 執行環境是否隔離 |
| Elevated | sandboxed exec 的出沙箱機制，隻影響 `exec` | 是否存在高風險逃逸口 |
| Heartbeat / Cron / Webhooks | 三類不同觸發機制 | 時間和外部事件是否分清 |
| Tasks | 後臺工作臺賬 | 不要誤當成排程器 |

## 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。

> [!IMPORTANT]
> OpenClaw 的設計不是把 AI 變神秘，而是把每次執行拆成可解釋的控制面、上下文、工具和持久化鏈路。

## 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 都需要理解。

這個取捨的實際意義：

> [!NOTE]
> OpenClaw 不是“把訊息發給模型”，而是“把一次模型執行納入本地 runtime 管理”。

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

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

| 檔案/目錄 | 放什麼 | 不放什麼 |
| --- | --- | --- |
| `AGENTS.md` | 操作規則和記憶使用方式 | persona 細節 |
| `SOUL.md` | persona、邊界、語氣 | 工具授權 |
| `USER.md` | 使用者資訊 | 憑據 |
| `IDENTITY.md` | Agent 名字和身份 | 執行配置 |
| `TOOLS.md` | 工具使用約定 | 工具是否可用的硬授權 |
| `HEARTBEAT.md` | 心跳檢查清單 | 長指令碼和 secrets |
| `BOOT.md` | Gateway startup 時可執行的短清單 | 長期記憶 |
| `BOOTSTRAP.md` | 首次啟動 ritual | 常駐規則 |
| `memory/` | daily notes | raw chat dump |
| `MEMORY.md` | curated long-term memory | 臨時噪音 |
| `skills/` | workspace highest-precedence skills | 全域性 managed skills |

得到的是透明和可遷移：

- 讀檔案就能看到 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 外掛，而不是假設所有歷史自動可見。

正確心智模型：

> [!TIP]
> Context 是現在看見什麼；Memory 是以後還能找回什麼。

## 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 的一個核心立場：

> [!IMPORTANT]
> AI 負責生成內容，規則負責系統秩序。

## 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 沒把所有自動化都塞進一個“任務系統”。

三者邊界：

| 機制 | 邊界 | 適合什麼 |
| --- | --- | --- |
| Heartbeat | 週期性主會話 turn | inbox、calendar、notifications 這類近似時間檢查 |
| Cron | Gateway scheduler | 精確時間、一次性提醒、isolated background run |
| Webhook | 外部 HTTP 事件入口 | GitHub、監控、郵件推送這類外部系統觸發 |

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，做一次只讀架構審計：

```text
请只读复盘当前 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 部署裡，最危險的入口在哪裡？

> [!IMPORTANT]
> 過關標準：能從入口、路由、session、context、workspace、memory、tools、sandbox、automation、安全邊界十個角度複述 OpenClaw 的設計取捨。

## 18. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw" title="回到 OpenClaw 總覽" description="從系列總覽重新選擇官方教程或深度理解路徑。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/09-channel-security" title="09 · Channel 與安全" description="回到安全邊界，繼續核對入口、工具、沙箱、日誌和 Gateway 暴露面。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/architecture" title="官方教程：Gateway 架構" description="對照官方架構頁繼續看 Gateway、Agent runtime 和控制面。" />
</Cards>

## 19. 官方資料

- [Gateway architecture](https://docs.openclaw.ai/concepts/architecture)
- [Agent Runtime](https://docs.openclaw.ai/concepts/agent)
- [Agent Loop](https://docs.openclaw.ai/concepts/agent-loop)
- [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Memory overview](https://docs.openclaw.ai/concepts/memory)
- [Context](https://docs.openclaw.ai/concepts/context)
- [Session management](https://docs.openclaw.ai/concepts/session)
- [Channel Routing](https://docs.openclaw.ai/channels/channel-routing)
- [Automation & Tasks](https://docs.openclaw.ai/automation)
- [Security](https://docs.openclaw.ai/gateway/security)
