OpenClaw 架構怎麼看：Gateway、Workspace、Bindings、Memory 與 Sandbox

OpenClaw 架構怎麼看：Gateway、Workspace、Bindings、Memory 與 Sandbox

OpenClaw 不是只靠一段 prompt 就能安全運作的代理系統。它的實際行為取決於 Gateway、workspace、channel binding、memory、工具權限與 sandbox 如何組合。把這些邊界先分清楚，才知道一個代理看得到什麼、能修改什麼、會把訊息送到哪裡。

文章實體化：OpenClaw 架構怎麼看：Gateway、Workspace、Bindings、Memory 與 Sandbox

本文以「OpenClaw 架構怎麼看：Gateway、Workspace、Bindings、Memory 與 Sandbox」為主線，補回模型／工具、輸入輸出、版本、成本、測試與使用邊界，讓技術名詞回到可執行的工作流程。

• 核心元件：把標題中的模型、工具、格式、企業或協定對應到實際輸入、輸出與依賴。
• 驗證方法：記錄版本、資料、環境、基準、錯誤案例與人工檢查，避免只引用功能宣稱。
• 治理邊界：說明權限、資料保存、成本、失敗回復與何時需要人工介入。

涉及版本、價格、企業資料或 API 行為時，以文章原始資料與供應商／公司最新文件核對。

五個核心概念

• Gateway：控制與路由層，承接連線、設定與執行協調。
• Workspace：代理工作檔案與指令的範圍；不等於整台主機。
• Bindings：把特定帳號、頻道或訊息路由到指定代理的規則。
• Memory：工作區內的日誌與長期筆記；記憶需要可檢查與可清理。
• Sandbox：限制工具與檔案存取的執行邊界，避免預設取得主機權限。

安全設定的起點

• 預設拒絕高風險工具與外部寫入；需要時再逐項放行。
• 讓公開訊息和私人工作使用不同代理、workspace 與權限。
• 把 credentials 放在受控設定或 secret 管理中，絕不寫進 prompt、記憶或對話紀錄。
• 對發訊息、付款、刪檔、部署等不可逆動作要求人工批准。
• 定期讀取執行紀錄，測試錯誤路由與提示注入情境。

Prompt 應該寫什麼？

好 prompt 要說明任務目標、可用資料、不可做的事、何時要求澄清與什麼條件下交給人類。它不是安全邊界的替代品：就算 prompt 說「不要刪檔」，仍必須用工具 allowlist、sandbox 與最小權限來真正限制能力。

先做一個可回復的試點

從只讀摘要、分類或草稿建議開始；用測試帳號與非敏感資料驗證路由、記憶與日誌。等到失敗模式清楚、人工覆核順暢，再考慮擴大權限。官方文件會更新，部署前請以當前版本文件及組織資安規範為準。

官方資料

• OpenClaw：Agents 與 bindings 設定
• OpenClaw：Agent workspace
• OpenClaw：Sandboxing

OpenClaw 的架構不適合只用「一個聊天機器人」來理解。從官方文件的分工來看，Gateway 負責把通道、控制面與代理執行串起來；Workspace 是代理使用檔案工具與上下文的工作家；Bindings 用來把不同訊息情境導向不同 agent；Memory 以工作區內的檔案與記憶流程保存可延續的資訊；Sandbox 則在需要隔離時限制工具能接觸的路徑與執行環境。這五個詞彼此有關，卻不能互相代換。真正排查問題時，先判斷故障是在入口、路由、檔案上下文、記憶檢索，還是權限隔離，會比盲目重啟整套系統有效。

先建立一張 OpenClaw 架構地圖

可以把一次訊息處理想成一條有邊界的路徑：訊息從已連接的 channel 進入 Gateway，Gateway 依目前的 session 與 routing 規則找到適合的 agent，agent 再使用自己的 workspace、模型、工具與記憶，最後把結果送回原本的通道。這是理解層次，不是宣稱每個 channel 或每種部署都完全相同的固定實作。實際欄位仍要以當前 schema、版本文件與已載入的 plugin 為準。

這張地圖的好處是把設定責任分開。Gateway 層關心服務如何啟動、如何驗證與如何接受訊息；agent 層關心模型、工具、技能與工作區；workspace 層關心代理每次會讀到哪些檔案；memory 層關心哪些內容值得長期保留；sandbox 層關心即使工具被呼叫時，程序仍能看到什麼。若把所有問題都歸咎於模型，通常會漏掉真正的設定或路由原因。

本次新增圖片來自 OpenClaw 官方 GitHub 的文件資產，作用是提供產品官方視覺識別與文章主題索引，不是某一個使用者的實際控制台截圖，也不能拿來證明你的設定已經成功。圖片的 alt 文字描述畫面用途，圖說標示官方來源，媒體描述保存原始網址、檔案尺寸與 SHA-256，讓內容證據與裝飾素材保持不同層次。

Gateway 是入口與控制面，不只是聊天轉發器

官方設定文件將 Gateway 放在整體運作的中心：它讀取 OpenClaw 設定，管理通道、代理預設、工具、sandbox 與自動化等跨功能選項。使用者看到的訊息雖然來自 Discord、Telegram、WebChat 或其他 channel，但訊息如何進入哪個 agent、使用哪一份工作區與哪些工具，必須經過 Gateway 的設定和 runtime 狀態共同決定。

因此，第一個診斷問題應該是「Gateway 是否活著並接受了這份設定」，而不是先問模型為什麼回答得不好。官方文件指出設定必須符合 schema；未知 key、錯誤型別或無效值可能讓 Gateway 拒絕啟動。設定檔也可能在 hot reload 時保留上一份已接受的 runtime，讓檔案看似改了、實際行為卻沒有跟著改。這時應先用官方提供的 status、health、doctor 或 logs 類診斷入口確認狀態。

另外要把「服務可連線」與「訊息可正確路由」分開。Gateway 回應正常，只代表入口還在；channel 的 allowFrom、DM policy、session 狀態、agent binding 或工具 policy 任何一項不合，都可能讓訊息被拒絕、送到錯的 agent，或只得到沒有檔案上下文的回答。

Workspace 是代理的家，也是上下文邊界

OpenClaw 官方文件把 workspace 定義為代理使用檔案工具和 workspace context 的工作目錄，預設位置是 ~/.openclaw/workspace，也可能由 profile、state directory、環境變數或設定覆寫。它與 ~/.openclaw/ 不同：後者放設定、憑證、session 與持久化狀態，不應因為「都在同一個根目錄」就混成一個可隨意提交的專案資料夾。

Workspace 內的檔案會影響代理的啟動上下文與行為，例如 AGENTS.md 可放操作規則，SOUL.md 可放人格與語氣，USER.md 可放穩定的使用者偏好，MEMORY.md 可放整理過的長期記憶，memory/YYYY-MM-DD.md 則適合每日紀錄。這些檔案不是裝飾，而是被載入、截斷、分層與隔離的上下文來源；大檔案可能受到 bootstrap 字數上限影響，缺少檔案時 runtime 可能注入缺失標記而繼續工作。

多 agent 部署尤其要留意 workspace 是否共用。官方文件指出，非 main agent 若沒有明確 workspace，可能解析到以 agent id 區分的工作區；若多個 profile 或舊安裝留下多個 workspace，使用者很容易在 A 目錄修改檔案、卻讓 B runtime 讀取另一份內容。遇到「剛改的規則沒有生效」時，先查 active workspace、profile、state directory 與 per-agent override，往往比重新寫一份 prompt 更重要。

Bindings 怎麼把訊息送到對的 agent

Bindings 可以理解成 routing 條件與 agent 目標之間的映射。它不是用來增加模型能力，而是決定某個來源、帳號、頻道、群組或其他訊息條件應該交給誰處理。當你需要讓私人對話、團隊群組、專案頻道或專用 agent 使用不同 workspace 和工具時，bindings 才是應該先檢查的層。

設計 binding 時，先把每條規則寫成可回答的句子：來源是什麼、條件是什麼、目標 agent 是什麼、沒有命中時的 fallback 是什麼。接著確認規則是否過寬、是否有重疊、是否把 shared context 誤送進 private agent。不要只看設定檔裡有沒有 bindings 陣列；還要用一個不敏感的測試訊息觀察 session key、agent identity、workspace 位置與回應能使用的工具集合。

Binding 命中不等於 workspace 權限已經正確。訊息可能被送到預期 agent，但該 agent 仍可能讀不到某個目錄，或因 sandbox workspaceAccess 不是 rw 而只看到沙盒複本。反過來，workspace 讀寫權限正確，也不代表某個 channel 一定路由到那個 agent。這正是把 routing、context 與 isolation 分開驗證的原因。

Memory 與 Workspace 的差別

Memory 不是「模型自動永遠記住一切」的承諾。官方文件把日常記憶與整理後的長期記憶放在 workspace 的檔案流程裡：每日筆記適合記錄當天事件，MEMORY.md 適合保存可重用的事實、決策與摘要，而且長期記憶只應在適合的 main、private context 中載入。這種檔案式記憶便於檢查、備份與修訂，也代表你必須管理檔案內容、敏感資料與載入範圍。

把所有聊天逐字塞進 MEMORY.md 不是好的記憶策略。更可靠的分層是：短期事件留在日期檔，跨日仍有價值的決策才整理進長期記憶，秘密、token、OAuth 憑證與原始敏感附件則不放進 workspace repo。當代理「忘記」一件事，應依序檢查檔案是否存在、是否被 bootstrap 上限截斷、目前 session 是否允許讀取、memory search 是否找到，以及 agent 是否真的使用了搜尋結果，而不是直接把責任推給模型權重。

Memory 也要與 session state 分開。session transcript、agent sqlite、credentials 與 runtime auth 是系統狀態，不是適合公開提交的長期知識。備份 workspace 時可以使用私有 git，但官方文件同樣提醒不要把 ~/.openclaw/、API key、OAuth token、密碼或原始聊天傾印放進 repo。可恢復性和資料最小化必須一起設計。

Sandbox、Workspace Access 與工具權限

Workspace 預設是代理的工作目錄，但它本身不是硬 sandbox。官方文件明確區分「相對路徑以 workspace 為基準」和「程序無法碰到 workspace 之外的路徑」；後者必須靠 sandbox 設定與工具 policy 來達成。這個差異很關鍵，因為看到代理能在 workspace 建立檔案，不代表它已經被限制只能在該目錄工作。

啟用 sandbox 後，workspaceAccess 會影響工具看到的是 host workspace、唯讀映射，還是位於 ~/.openclaw/sandboxes 下的隔離工作區。官方說明中的 mirror 與 remote 等模式也有不同同步語意：有的模式在 exec 前後同步，有的模式只在建立時把內容種入遠端。若本機剛改的檔案沒有出現在代理眼前，應先查 sandbox 模式、recreate 條件與同步邊界，而不是再次修改檔案。

安全配置要遵守最小權限。能用唯讀 workspace 就不要直接給 rw；需要寫入時限制可寫目錄；需要額外工具時只開放必要的 tool group；Gateway 對外連線則優先使用有驗證、有限來源的方式，避免把未驗證的服務綁在公開網路介面。Sandbox 不是萬能防護，仍要同時檢查 tool policy、elevated 模式、掛載路徑、symbolic link 行為與 secrets 是否被帶入上下文。

常見故障：看起來像模型問題，其實是邊界問題

第一種是「代理說找不到檔案」。先確認它進入哪個 agent，再確認該 agent 的 workspace 絕對路徑，最後確認 sandbox workspaceAccess 和同步模式。第二種是「改了 AGENTS.md 卻沒有生效」。除了確認路徑，還要考慮 bootstrap 檔案總字數、session 是否已經建立、profile 是否不同，以及是否有另一份同名 workspace 被 runtime 使用。

第三種是「群組訊息跑到私人 agent」。查 channel identity、binding 條件、規則優先序與 session key，並避免用真實個資做測試。第四種是「設定檔改完 Gateway 不起來」。不要不斷重試或刪掉設定；先保留 rejected 檔案與診斷輸出，對照 schema 找出未知 key、型別錯誤或破壞性覆寫，再用最小變更修復。

第五種是「記憶內容混到不該出現的上下文」。檢查 MEMORY.md 是否放了私人資料、shared/group context 是否被錯誤載入、agent binding 是否共用了不該共用的 workspace，以及搜尋索引是否仍保留舊內容。記憶治理不是最後才補的功能，而是 workspace、session、routing 與 privacy 邊界的共同結果。

設定變更前後要保存哪些證據

如果要修改 Gateway、agent 或 sandbox 設定，先保存修改前的有效設定、目前使用的 profile、config path、相關 workspace 路徑與 Gateway 狀態。秘密欄位應該先遮罩，不要把完整 token 或 credentials 寫進報告。接著只改一個能清楚描述的範圍，例如先改 workspace，再測試檔案讀取；或先改 binding，再用兩個不含敏感資料的訊息測試路由。一次改很多欄位，出問題時就無法知道是哪一條邊界失效。

修改後保存四類結果：設定是否通過 schema、Gateway 是否重新載入、測試訊息命中的 agent 與 session、工具實際看到的 workspace 或 sandbox 路徑。若設定被拒絕，保留 rejected 檔案和 doctor、logs 的錯誤摘要；若設定成功，也要確認成功不是只代表檔案被寫入，而是 runtime 真的採用新值。這樣未來回滾時可以用同一組觀測點驗證，而不必靠印象判斷。

備份也要有範圍。workspace 的 AGENTS.md、SOUL.md、USER.md、ID、工具說明與 memory 檔案可以在私有 repository 中管理，但應先檢查個資和秘密；session sqlite、credentials、模型登入資料與 channel 狀態則應依 OpenClaw 的 state 和 credential 邊界分開備份。把所有東西打包成一個 zip 並不等於可安全恢復，反而可能讓洩漏面與回滾風險一起變大。

用小型測試確認 routing 與隔離

一個實用的測試組合至少包含兩個 agent 或兩條可區分的 route，以及一個只放測試文字的檔案。第一則訊息確認來源 A 是否進入 agent A，第二則確認來源 B 是否進入 agent B；接著讓兩個 agent 分別讀取自己的測試檔案，確認不會因為共用預設 workspace 而看見對方內容。最後在 sandbox 開啟與關閉的受控環境比較工具可見路徑，但不要用真實憑證或個人對話做實驗。

若測試結果不一致，先把原因分類為 route mismatch、workspace mismatch、sync delay、tool policy deny 或 memory retrieval mismatch。這些分類看起來相近，修法卻完全不同：route mismatch 要看 bindings，workspace mismatch 要看 agent override，sync delay 要看 sandbox 模式，tool policy deny 要看 allow／deny 群組，記憶找不到則要看檔案分層和搜尋流程。將失敗分類後，修復才不會變成反覆放寬權限。

讀者也可以把這套測試當成部署前檢查表：每新增一個 channel，就做一次來源到 agent 的最小驗證；每新增一個 agent，就確認它的 workspace 與 memory 可見範圍；每開一項高權限工具，就保存工具 policy 和反向測試；每次升級 OpenClaw，就重新查看官方 schema 與 sandbox 文件。功能名稱可能改變，但「入口、路由、上下文、隔離、回讀」這五個驗證問題仍然成立。

一套可重複的 OpenClaw 架構檢查順序

可以把排查流程固定成七步。第一，記錄版本、profile、state directory 與實際 config path。第二，確認 Gateway health、logs 與 schema 狀態。第三，用不敏感訊息確認 channel 和 binding 命中哪個 agent。第四，讓 agent 回報目前 workspace 的非敏感路徑與必要檔案是否存在。第五，檢查 sandbox 模式、workspaceAccess、掛載和 tool policy。第六，分開檢查日期記憶、長期記憶與 session state，不把它們混成一份備份。第七，才檢查模型、prompt 或回答品質。

每一步都要留下「觀察到的事實」與「尚未證明的推測」。例如，看到官方 workspace 文件說預設位置是 ~/.openclaw/workspace，不等於你的 profile 目前就使用那個路徑；看到 binding 規則存在，也不等於測試訊息真的命中它；看到 sandbox 啟用，也不等於所有工具都被同一套限制。把證據範圍寫窄，才能避免一個設定畫面被誤報成整套部署已安全。

結語：用邊界理解 OpenClaw，而不是只記名詞

Gateway、Workspace、Bindings、Memory 與 Sandbox 其實是在回答五個不同問題：訊息從哪裡進來、代理在哪裡工作、要交給哪個 agent、哪些資訊可以延續，以及工具能接觸到什麼。把它們放在同一張架構圖上，能讓你以較小的變更定位故障，也能在增加 channel、agent 或自動化時維持清楚的安全邊界。

OpenClaw 的文件與設定會持續演進，所以欄位名稱、預設值與功能狀態應以當前官方文件和本機 schema 為準。本文的價值不是替你的環境保證一份固定配置，而是提供一種可查核的方法：先看 Gateway，再看 binding，再看 workspace 與 memory，最後看 sandbox 和工具權限。每次變更都保存前後狀態、測試訊息與可回復備份，才是真正可維護的架構治理。

資料來源與圖片邊界

• OpenClaw 官方 Configuration 文件：用於 Gateway、設定檔、schema、hot reload 與診斷邊界。
• OpenClaw 官方 Agents 設定文件：用於 agent 預設、workspace 與 bindings 的設定脈絡。
• OpenClaw 官方 Agent workspace 文件：用於 workspace 路徑、檔案地圖、記憶檔案與備份注意事項。
• OpenClaw 官方 Memory 文件：用於每日記憶、長期記憶與 private context 的界線。
• OpenClaw 官方 Sandboxing 文件：用於 sandbox workspace、workspaceAccess、工具與隔離限制。
• OpenClaw 官方 GitHub 文件資產：新增圖片來源；圖片為官方 hero asset，不是使用者環境的介面截圖。