OpenClaw 文件導讀：200+ 份文件，從哪讀起？
OpenClaw 有 200+ 份文件，這篇幫你搞懂全貌、知道每塊在講什麼、依你的角色決定從哪讀起。
32 篇文章
OpenClaw 文件導讀
把 OpenClaw 這套自架 AI 閘道器的 300+ 份官方文件拆成 32 篇讀完：從安裝與平台、模型供應商、agent 執行核心與記憶，到 24+ 聊天頻道、沙箱與威脅模型、工具與自動化、Gateway 營運、Plugin 與各種介面。
OpenClaw 安裝指南（上）：六種本機安裝方式怎麼選，以及會卡住的地方
OpenClaw 有六種本機安裝方式，差別不在指令而在你要不要可重現性、隔離、與自我更新。真正會卡住的是套件管理器的 lifecycle script 政策：npm 12 與 pnpm 全域安裝都預設擋掉 OpenClaw 的 build script。
OpenClaw 安裝指南（下）：雲端部署的四個決定，與 K8s 上的實際坑
雲端部署 OpenClaw 要決定的其實只有四件事：Gateway 綁哪裡、state 放哪裡、誰能連進來、壞了怎麼復原。平台選擇是最不重要的一項。
OpenClaw 桌面平台：Windows 現在有原生 Hub，而 Node 是硬性需求
Node 是必要的執行期，因為標準狀態儲存用 node:sqlite——Bun 只能拿來裝依賴。Windows 這邊變化最大：新增了原生的 Windows Hub companion app，不需要管理員權限，還能自己開一個 app 專屬的 WSL 發行版來裝 Gateway。
OpenClaw 行動平台：手機是周邊，不是 Gateway——連 Apple Watch 都有自己的傳輸
iOS 與 Android 的 app 是 node，不是 Gateway：它們不跑 Gateway 服務，Telegram 或 WhatsApp 的訊息也是落在 Gateway 上而不是手機上。Apple Watch 比較特別——因為 watchOS 擋掉一般 app 的低階網路，它改用簽章過的 HTTPS 輪詢。
OpenClaw 的模型需求與供應商生態：先搞懂 provider、model、runtime 是三件事
OpenClaw 對模型的硬需求是 tool use 加夠大的 context——onboarding 自動推薦本地模型的門檻是支援 tool 且 context 至少 16K。但更容易搞混的是 provider、model、agent runtime 其實是三層，`openai/*` 不等於走 Codex。
OpenClaw 的 60 個供應商：分類地圖，與接本地模型真正會踩的坑
官方 provider 目錄現在有 60 個條目。接本地模型最常見的失敗是把 Ollama 的 base URL 寫成 /v1——那會破壞 tool calling，模型會把 tool JSON 當純文字吐出來。
OpenClaw 模型進階：容錯的兩階段、冷卻的真實數字，與 Prompt Caching
OpenClaw 的容錯是兩階段：先在同一供應商內輪替 auth profile，再換模型。但真正決定行為的是「這個模型是誰選的」——你手動用 /model 選的模型是嚴格的，失敗就報錯，不會偷偷用別的模型回答你。
OpenClaw 多 Agent：一個 agent 是一整個人格邊界，而 agent 現在可以要求生出 agent
一個 agent 是完整的人格範圍——workspace、auth profile、模型登錄、session 儲存全部獨立。但隔離不是絕對的：次要 agent 的 OAuth 憑證過期時，OpenClaw 會回頭讀主 agent 的同名 profile，而 workspace 只是預設工作目錄，不是硬性沙箱。
OpenClaw Agent Runtime：系統 prompt 是組出來的，而它被一條快取邊界切成兩半
OpenClaw 每次執行都自己組系統 prompt，沒有執行期的預設 prompt。組出來的內容被一條內部快取邊界切開——穩定的 workspace 前綴在上面、每輪會變的頻道脈絡在下面——好讓有前綴快取的後端能跨頻道重用同一段前綴。
OpenClaw Agent Loop：序列化、寫入者宣告，與那個防止舊回合覆寫逐字稿的柵欄
Agent loop 是每個 session 序列化的執行。最值得學的是它處理並行的方式：每個被接受的回合會記下 activeWriterRunId 宣告，之後每次逐字稿寫入都要附上 expectedWriterRunId，在交易裡比對——被取代的回合因此無法提交過期資料。
OpenClaw 的 Session 與記憶：一條滾動的主對話，加上四個會被寫進磁碟的檔案
預設下所有 DM 匯進同一條「主 session」，群組活動與背景工作都往那裡回報。記憶則完全是磁碟上的 Markdown——模型只記得被寫下來的東西，沒有隱藏狀態。但如果不只你一個人能私訊它，DM 隔離是必須主動打開的。
OpenClaw 頻道總覽：31 個頻道幾乎都是 plugin，以及「誰能觸發」與「模型看得到什麼」是兩回事
OpenClaw 支援 31 個聊天頻道，但只有 WebChat 在核心裡——連 Slack 和 WhatsApp 都是要裝的 plugin。而群組安全其實有兩個獨立的軸：allowlist 管的是誰能觸發 agent，不管模型會看到哪些引用與歷史，後者要另外設 contextVisibility。
OpenClaw 主力頻道：WhatsApp、Telegram、Discord 各自會卡在哪一步
三個頻道各有一個「不知道就會卡住」的點：WhatsApp 是 QR 登入沒辦法遠端做、Telegram 是 bot 預設開著 Privacy Mode 收不到群組訊息（改完還要把 bot 退出再加回去）、Discord 是 Message Content Intent 沒開就收不到伺服器訊息。
OpenClaw 企業頻道：Slack 的三種傳輸模式，與「內建」這欄已經不存在了
企業頻道全部改成 plugin 了，包含以前內建的 Slack 與 Google Chat。Slack 現在有三種傳輸模式——Socket Mode、HTTP Request URLs、Relay——而官方明說它們在功能上已經對等，要按部署形狀選，不是按功能選。
OpenClaw 其他頻道：Signal、iMessage、LINE，以及讓兩個人的 agent 直接對話的 Reef
這批頻道裡最值得看的是 Reef——不同人的 OpenClaw agent 之間的端對端加密側頻道，訊息在你的機器上封裝、雙向都經過釘死模型的守衛審查，中繼站永遠讀不到內容。它是 bundled plugin，不用另外裝。
OpenClaw 沙箱機制：四種後端、三個獨立開關，與「以為在沙箱裡其實沒有」
沙箱由三個獨立設定決定：mode（何時套用）、scope（開幾個容器）、backend（在哪執行）。最容易出事的是預期落差——`tools.exec.host` 現在預設是 auto，所以「沒設就等於在沙箱裡」已經不成立，安全稽核有一條專門抓這個。
OpenClaw 的威脅模型：先講清楚它「不保護什麼」
OpenClaw 的安全文件現在開宗明義寫著：這是個人助理的信任模型，一個 Gateway 對應一個受信任的操作者。它明確「不是」多個互相敵對的使用者共用一個 agent 時的安全邊界——而且有一份『依設計不算漏洞』的清單把這件事寫死。
OpenClaw 存取控制：SecretRef 不是程序隔離，以及它到底解決了什麼
SecretRef 讓憑證不必以明文躺在設定檔裡，模型呼叫鏈上看到的是 process-local 的哨兵值。但官方講得很白：這不是程序隔離——真正的值仍在同一個程序的記憶體裡，而且 agent 讀得到的任何明文檔案都繞過了這層保護。
OpenClaw 工具篇（一）：一個專屬瀏覽器、三種附著方式，與被標成「不可信」的搜尋結果
OpenClaw 的瀏覽器是一個獨立的 agent 專用 profile，跟你的個人瀏覽器完全隔離。而 web_search 的回傳結構裡有一個 externalContent.untrusted 標記——搜尋結果在型別層就被標成不可信的外部內容。
OpenClaw 工具篇（二）：Skills 的六層優先順序，與子 agent 不給訊息工具的理由
Skills 從六個來源載入、同名時高優先者勝，而 per-agent 的清單是取代不是合併。子 agent 預設拿不到 session 與訊息工具——它回傳純文字給父 agent，人看得到的回覆權留在父 agent 手上。
OpenClaw 工具篇（三）：關掉檔案工具不會讓 exec 變成唯讀
exec 是一個會改變狀態的 shell 面：關掉 write、edit、apply_patch 這些檔案工具，完全不會讓它變成唯讀。而沙箱預設是關的，所以 host=auto 實際上會解析到 gateway——真的要沙箱就明確寫，它至少會 fail closed。
OpenClaw 工具篇（四）：當工具多到塞不進 prompt——Code Mode、Tool Search 與 MCP
工具目錄大到塞不進 prompt 時，OpenClaw 有兩個答案：Code Mode 只讓模型看到 exec 與 wait，由它寫小程式去搜尋與呼叫隱藏的目錄；Tool Search 則保留結構化的搜尋／描述／呼叫控制。兩者都不繞過工具政策。
OpenClaw 自動化（一）：六種機制怎麼選，以及「排程要準」與「順便看一下」是兩件事
Cron 已經改名為 Automations（openclaw cron 仍是別名），而自動化現在有六種機制。核心的取捨只有一條：Automations 給你精確時間與隔離執行，Heartbeat 給你完整的主 session 脈絡與大約每 30 分鐘一次的頻率。
OpenClaw 自動化（二）：Standing Orders 是授權書，Automations 是時鐘
Standing orders 給 agent 對某個「程式」的永久操作權限，寫在 AGENTS.md 裡、每個 session 自動注入。它定義的是「被授權做什麼」，時間點則交給 automations——兩者分工，而且 automation 的提示應該引用 standing order 而不是複製它。
OpenClaw Gateway 篇（一）：嚴格驗證會讓它拒絕啟動，以及那些擋住你自己的保護
OpenClaw 的設定驗證是嚴格的——多一個不認識的鍵、型別不對、值無效，Gateway 就拒絕啟動。它會保留最後已知良好的設定，但啟動與熱重載都不會自動還原，只有 doctor --fix 會。
OpenClaw Gateway 篇（二）：綁定、認證與那份憑證優先權契約
Gateway 預設只綁 loopback，而綁到 loopback 以外一律要求認證——這是它自己會擋的，不是建議。容器裡的有效預設是 auto，但 Tailscale serve/funnel 啟用時會強制回 loopback。
OpenClaw Plugin 系統：把安裝當成執行程式碼，以及冷檢查證明不了執行期
官方對安裝 plugin 的定調是「把它當成執行程式碼」——ClawHub 與內建目錄是受信任來源，任意的 npm、git、本地路徑在非互動安裝時需要 --force。而驗證要用 inspect --runtime，因為不帶旗標的 inspect 只是冷的 manifest 檢查。
OpenClaw Nodes 深入：核准綁的是計畫，不是你之後改過的指令
遠端 node 執行最值得看的是核准的綁定方式：exec 在核准前先備好一份標準化的 systemRunPlan，核准之後 gateway 轉發的是那份存起來的計畫，不是任何之後被呼叫端改過的指令、cwd 或 session 欄位——而且執行前會重新驗證工作目錄。
OpenClaw UI：新增的側欄可以問「這個 session 在幹嘛」而不打斷它
Control UI 加了一條 session rail：它用 utility model 產生執行摘要，還附一個唯讀的伴讀 thread，讓你問「這個 session 現在怎樣」而不會進入或打斷主 agent 執行。它的內容不會進入 chat.history。
OpenClaw 維運篇：前 60 秒的七行指令，與「感覺變笨了」通常不是模型的錯
官方的分診流程是七行指令跑一遍、兩分鐘出診斷。而「assistant 感覺受限、工具不見了」這個最常見的症狀，多半是工具 profile——minimal 只允許 session_status，coding 才是新本地設定的預設。
OpenClaw 參考篇：Pi 已經被吸收掉了——內建 runtime 現在就叫 openclaw
「OpenClaw 是 Pi 的 Gateway 殼」這個說法已經過期。官方文件現在寫的是：內建 runtime id 是 openclaw，而 pi 是會被正規化掉的 legacy 別名，「已經沒有外部 agent 框架套件」。留下的第三方 pi 相關依賴只剩一個終端機元件工具包。