OpenClaw Sandboxing 指南：在 Docker 中安全執行工具

你有遇過這種情況嗎？當你給 AI 寫入檔案或執行指令的權限時，心裡總會毛毛的。萬一模型理解錯誤，改到了不該動的系統檔案，或是執行了預期之外的指令，你的開發環境可能瞬間就亂套了。

為了讓開發過程更安心，我們需要一個隔離層。Sandboxing 能讓你在 Docker 容器中執行工具，確保 AI 的操作被限制在特定範圍內，就算模型做了什麼蠢事，影響也會被控制在容器裡。

需要準備的東西

已安裝 Docker 的環境
OpenClaw Gateway
基礎的 JSON5 設定知識

快速開始

要在 5 分鐘內開啟基礎的 Sandbox 功能，請跟著以下步驟：

建置 Sandbox 映像檔：在終端機執行腳本來建立預設的 openclaw-sandbox:bookworm-slim 映像檔。
Terminal window
```
scripts/sandbox-setup.sh
```

開啟 Sandbox 設定：在你的設定檔中加入以下內容。這個設定會針對非主對話（non-main sessions）開啟隔離，並為每個 session 建立獨立的容器。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

(選填) 建置瀏覽器 Sandbox：如果你需要隔離的瀏覽器環境，請執行：
Terminal window
```
scripts/sandbox-browser-setup.sh
```

核心運作邏輯

哪些東西會被隔離？

當你開啟 Sandbox 後，大部分的工具執行（如 exec, read, write, edit 等）都會在容器內跑。如果你有設定 agents.defaults.sandbox.browser，瀏覽器也會被隔離。

請注意，Gateway 本身會留在 host 主機上，而標記為 tools.elevated 的工具會直接在 host 上執行並繞過 Sandbox。

存取權限控制

你可以透過 workspaceAccess 決定容器能看到多少東西：

"none": 工具只能看到 ~/.openclaw/sandboxes 下的隔離空間。
"ro": 以唯讀模式掛載 agent workspace 到 /agent。
"rw": 以讀寫模式掛載 agent workspace 到 /workspace。

自定義掛載 (Bind Mounts)

如果你需要讓容器存取 host 的特定目錄，可以使用 binds 設定。這會直接繞過 Sandbox 的檔案系統限制，請謹慎使用。

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

疑難排解

如果你在使用過程中遇到問題，可以先檢查以下幾點：

網路連線失敗：Sandbox 預設是 network: "none"。如果你在 setupCommand 裡需要安裝套件，請務必暫時開啟網路，否則會失敗。
無法寫入檔案：檢查是否開啟了 readOnlyRoot: true，或是你的 workspaceAccess 是否設為 "ro"。
找不到環境變數：Sandbox 執行時不會繼承 host 的 process.env。如果有 API key 等需求，請手動在 agents.defaults.sandbox.docker.env 中設定。
權限不足：如果你要在 setupCommand 安裝套件，必須確保 user 是 root（預設即是，或設為 "0:0"）。

你可以執行 openclaw sandbox explain 來檢查目前的隔離模式與工具政策，這能幫你快速釐清「為什麼這個工具被擋住了」。

如果你在設定上遇到困難，可以詢問 AI Setup Assistant 取得即時協助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。