沙箱裡找不到宿主機已安裝的命令怎麼辦？

容器映象與宿主機是兩套根檔案系統；要麼把工具做進沙箱映象，要麼透過配置暴露額外路徑/掛載。不要把「我 SSH 進機器有」與「沙箱內 PATH 有」混為一談。

退出碼 137 是否一定等於 OOM？

在 Docker/容器場景裡 137 常表示 SIGKILL，OOM killer 是常見原因但不是唯一原因；應結合 dmesg、container exit、構建階段一起判斷。

何時應關掉沙箱？

在可信環境、僅只讀操作為主的場景可評估關閉或換 SSH/OpenShell 後端；需要隔離任意命令執行時仍應保留沙箱並收緊映象與網路。

2026 OpenClaw Agent 沙箱（Sandbox）實操：Docker 映象、`docker.user` 與卷許可權、工具不可見與 OOM/137 分診

你已經能用 Docker / Compose 跑 OpenClaw Gateway，但一開啟 Agent 沙箱就出現：容器起不來、工作區只讀/不可寫、沙箱裡明明缺命令、一構建就 OOM 退出 137。本文把 2026 年主流落地路徑壓成可執行順序：關→開→驗→排障，用配置鍵位、卷許可權與 `docker.user` 對齊、映象構建與 OOM 分診表和站內已有「Docker 安裝/卷許可權/doctor」類文章明確分工。讀完你應能判斷：是映象問題、掛載 UID 問題、還是資源上限與日誌關鍵字問題。

痛點：為什麼沙箱一開會變成「我本地明明有，容器裡就是找不到」

根因往往不在「OpenClaw 裝壞了」，而在程序邊界：

根檔案系統不是宿主機：沙箱是獨立映象；你在宿主機 brew install 的東西不會自動出現在沙箱的 PATH，除非進映象或額外掛載/層。
工作區是 bind mount 進來的：如果宿主機上目錄屬主是 501:20、容器裡程序是 1000:1000 跑，常出現只讀失敗或寫拒絕，日誌裡以 Permission denied 或 EROFS 呈現。
沙箱是另一套安全邊界：即便 Gateway 有網路，沙箱內 DNS、出站策略與工具集仍應單獨設計；和「能 SSH 進機器裝軟體」是兩條運維路徑。

與 SSH/OpenShell/無沙箱：一屏對照，避免選錯後端

模式	適合什麼	你付出的成本	常見誤判
Docker 沙箱	要對不可信命令/指令碼做硬隔離，復現「乾淨環境」	映象體積、拉取/構建、UID/GID/卷要對齊	以為宿主機工具自動繼承
SSH / 遠端 shell	在你信任的遠端 Mac上直接跑（例如獨佔構建機），需要完整工具鏈	暴露面與賬戶模型變大	把本機當沙箱、忘記審計
無沙箱 / 全本地	內網、低危、可快速排障	任一程式碼被模型執行時風險高	在 CI/生產也長期關閉

配置入口：`agents.defaults.sandbox.docker` 與 `sandbox-setup.sh` 怎麼配合

概念上分兩層：用哪個沙箱實現（Docker 映象/執行時）和映象從哪來。官方倉庫通常提供 scripts/sandbox-setup.sh（名稱以你本地克隆版本為準）來預構建/拉取作為宿主機上 docker CLI 能識別的映象。配置裡 agents.defaults.sandbox.docker.image 指向要執行會話的那個映象；兩者不一致時，典型症狀是「Gateway 認為沙箱已啟用，但 docker run 報 manifest not found 或 pull access denied」。

info

和已有文章怎麼分工？ 若你卡在 OPENCLAW_IMAGE 或 Control UI 入口，先按官方 Docker 一鍵與 GHCR 映象；若你卡在資料卷、許可權、持久化與 Skills 路徑，對照 Docker 卷與許可權檢查表。本篇只盯 沙箱子系統 + OOM/137。

`docker.user` 與 `OPENCLAW_HOME` 掛載：按症狀對齊，而不是亂 `chmod 777`

推薦順序：

在宿主機上確認要掛載的 workspace 目錄屬主/屬組，以及 Gateway 程序實際以何身份執行；
在配置裡設定 docker.user 為 與卷可寫性一致的 UID:GID（以文件鍵名為準，若你版本用巢狀表結構則對應到 sandbox.docker 下）；
若公司策略禁止對倉庫根目錄大面 chown，優先調整掛載到容器內的子目錄，而不是放開整個磁碟。

對 Linux 與遠端 Mac 的細微差別是：命名卷、繫結掛載、SELinux 標籤（在部分發行版上）會放大「在 compose 裡看著對、進容器就錯」的現象。此時要在 Gateway/沙箱容器的啟動日誌中抓首條 I/O 錯誤行，而不是在模型對話裡試運氣。

「工具在宿主機有、沙箱裡無」的最短分診 4 問

該執行檔是否在**映象 PATH 的目錄**中？docker exec 到沙箱裡跑 command -v 比口述可靠。
是否依賴**動態庫或直譯器**路徑（例如特定 Node/Python minor）而映象中不存在？
是否需要只讀繫結宿主機的 ~/.cache 之類路徑才能跑？若是，要評估把快取放進映象/公共層，而不是從宿主隨意穿越。
該工具是否與 Gateway 同網路策略，需要額外 HTTP(S)_PROXY？網路失敗常被誤報成 command not found。

OOM 與 `exit 137`：在 Docker 裡如何讀「被殺」與「不夠記憶體」

137 = 128 + 9 (SIGKILL) 在實踐裡常和 OOM killer 相關，但你也可能看到 人為 docker kill 或 cgroup 記憶體限制 觸頂。分診上至少做三件事：看 構建階段是 docker build 還是 docker run；在引擎側看 concurrent build 是否讓 Docker Desktop / VM 記憶體打滿；對遠端 Mac/專用機則看系統真實可用記憶體與 swap 壓力，而不是隻盯單容器 limits。另有一類易混訊號是退出碼 1 或 2卻伴隨大量 Cannot allocate memory 文本，也要併入「記憶體/磁碟臨時空間」同一張表，避免在模型側反覆調參卻不動容器。

對「構建時 OOM」的通用減負順序：關並行層（--parallel 等）、用多階段構建減少編譯峰、提高 Docker VM 分配、換帶更多記憶體的 獨佔遠端 Mac 檔位 作為穩定基座。這與「在筆記本上開多個 IDE + 本地大模型 + Docker」的偶然成功不是一類事件。若團隊已上共享儲存，額外關注inode 與後設資料小檔案爆發導致的「像 OOM 一樣卡死」現象，必要時分卷或改清理策略。

落地 6 步：從 0 到能穩定開沙箱跑一輪工具

確認 Docker/Compose 健康 與 Gateway 能啟動（參考 Gateway/模型層分診與 doctor 銜接）。
跑官方/隨倉庫的 sandbox-setup 構建或拉取映象，記錄**映象名與 ID** 與配置一致。
在測試 workspace 上啟用沙箱，刻意執行「只寫小檔案」與「讀大目錄」各一次，抓許可權錯誤。
對 docker.user 與掛載做 A/B：只改一個變數、保留 diff，避免同時改三處後無法回滾。
壓一箇中等強度構建，同時觀察宿主機與容器記憶體，記錄是否 137。
把 Runbook 寫進團隊 Wiki：含最小復現、日誌片段、與「何時關沙箱/何時必須開」的邊界。

config 片段（示意鍵名，以你版本 openclaw.json/文件為準）

{
  "agents": {
    "defaults": {
      "sandbox": { "mode": "docker" },
      "docker": { "user": "1000:1000" }
    }
  }
}
// 實際專案可能為巢狀在 sandbox.docker 下，請先 openclaw doctor / 對照官方文件

可引用技術資訊：3 條寫進評審/容量筆記的引數量級

exit 137 與 128+訊號：在排障單裡**同時記錄** docker events 或引擎日誌、宿主機 memory pressure，避免把業務 OOM 與 docker build 並行 OOM 混為同一類事故。
使用者名稱空間/UID 對映：在 bind mount 場景，chown -R 1000:1000 單個專案目錄 與「動整個家目錄」風險不同，變更要有工單與回滾點。
沙箱冷啟動時延：大映象的 extract 層、首次 pip 索引、以及無持久層時的重複下載，會把「能跑通一次」和「能跑通一百次」的成本拉開，應在容量評審裡給首啟時間一個數字。

為何「筆記本臨時配 Docker + 大模型 + Xcode」常撐不住企業級沙箱節奏

這類替代拓撲通常輸在記憶體與 I/O 的同時峰值與可重複的環境邊界上：你昨天能構建，是僥倖沒有併發；而生產 Agent 在高峰會穩定觸發 137 與寫放大。對需要7×24 Gateway + 沙箱的團隊，更可控的組合是 獨佔的 Apple Silicon 雲主機、清晰磁碟與日誌策略、可預期的租期。在這種前提下，MACCOME 的遠端 Mac 雲算力更適合作為 OpenClaw 的常駐基座——你減少的是與隨機本地環境搏鬥的時間，把精力放回工具鏈與產品交付。