沙盒化

OpenClaw 可以在沙箱後端內執行工具，以降低影響範圍。這是選用功能，並由設定控制（agents.defaults.sandbox 或 agents.list[].sandbox）。如果關閉沙箱化，工具會在主機上執行。Gateway 會留在主機上；啟用時，工具執行會在隔離的沙箱中執行。

會被沙箱化的內容

• 工具執行（exec、read、write、edit、apply_patch、process 等）。
• 選用的沙箱化瀏覽器（agents.defaults.sandbox.browser）。

不會被沙箱化：

• Gateway 程序本身。
• 任何明確允許在沙箱外執行的工具（例如 tools.elevated）。
  • 提權 exec 會繞過沙箱化，並使用已設定的逃逸路徑（預設為 gateway，或當 exec 目標為 node 時使用 node）。
  • 如果沙箱化已關閉，tools.elevated 不會改變執行方式（已經在主機上）。請參閱提權模式。

模式

agents.defaults.sandbox.mode 控制何時使用沙箱化：

範圍

agents.defaults.sandbox.scope 控制會建立多少容器：

• "agent"（預設）：每個 agent 一個容器。
• "session"：每個工作階段一個容器。
• "shared"：所有沙箱化工作階段共用一個容器。

後端

agents.defaults.sandbox.backend 控制由哪個執行階段提供沙箱：

• "docker"（啟用沙箱化時的預設值）：由本機 Docker 支援的沙箱執行階段。
• "ssh"：通用的 SSH 支援遠端沙箱執行階段。
• "openshell"：OpenShell 支援的沙箱執行階段。

SSH 專屬設定位於 agents.defaults.sandbox.ssh 之下。OpenShell 專屬設定位於 plugins.entries.openshell.config 之下。

選擇後端

Docker 後端

沙箱化預設關閉。如果你啟用沙箱化且未選擇後端，OpenClaw 會使用 Docker 後端。它會透過 Docker daemon socket（/var/run/docker.sock）在本機執行工具與沙箱瀏覽器。沙箱容器隔離由 Docker namespace 決定。

若要將主機 GPU 暴露給 Docker 沙箱，請設定 agents.defaults.sandbox.docker.gpus，或每個 agent 的覆寫值 agents.list[].sandbox.docker.gpus。該值會作為獨立引數傳遞給 Docker 的 --gpus 旗標，例如 "all" 或 "device=GPU-uuid"，並且需要相容的主機執行階段，例如 NVIDIA Container Toolkit。

SSH 後端

當你希望 OpenClaw 在任意可透過 SSH 存取的機器上沙箱化 exec、檔案工具與媒體讀取時，請使用 backend: "ssh"。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

OpenShell 後端

當你希望 OpenClaw 在 OpenShell 管理的遠端環境中沙箱化工具時，請使用 backend: "openshell"。完整設定指南、設定參考與工作區模式比較，請參閱專屬的 OpenShell 頁面。

OpenShell 會重用與通用 SSH 後端相同的核心 SSH 傳輸與遠端檔案系統 bridge，並加入 OpenShell 專屬生命週期（sandbox create/get/delete、sandbox ssh-config）以及選用的 mirror 工作區模式。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote          remoteWorkspaceDir: "/sandbox",          remoteAgentWorkspaceDir: "/agent",        },      },    },  },}

OpenShell 模式：

• mirror（預設）：本機工作區保持為準。OpenClaw 會在 exec 之前將本機檔案同步到 OpenShell，並在 exec 之後將遠端工作區同步回來。
• remote：沙箱建立後，OpenShell 工作區即為準。OpenClaw 會從本機工作區將遠端工作區播種一次，之後檔案工具與 exec 會直接對遠端沙箱執行，不會同步變更回來。

工作區模式

OpenShell 有兩種工作區模型。這是在實務上最重要的部分。

如果你把沙盒視為暫時的執行環境，請選擇 mirror。如果你把沙盒視為真正的工作區，請選擇 remote。

OpenShell 生命週期

OpenShell 沙盒仍透過一般沙盒生命週期管理：

• openclaw sandbox list 會顯示 OpenShell runtime 以及 Docker runtime
• openclaw sandbox recreate 會刪除目前的 runtime，並讓 OpenClaw 在下次使用時重新建立它
• 清理邏輯也會感知後端

對 remote 模式而言，重新建立尤其重要：

• 重新建立會刪除該作用域的權威遠端工作區
• 下次使用時會從本機工作區初始化新的遠端工作區

對 mirror 模式而言，重新建立主要是重設遠端執行環境，因為本機工作區無論如何仍是權威來源。

工作區存取

agents.defaults.sandbox.workspaceAccess 控制沙盒可以看到什麼：

使用 OpenShell 後端時：

• mirror 模式在 exec 回合之間仍使用本機工作區作為權威來源
• remote 模式在初始初始化後使用遠端 OpenShell 工作區作為權威來源
• workspaceAccess: "ro" 和 "none" 仍會以相同方式限制寫入行為

傳入媒體會複製到作用中的沙盒工作區（media/inbound/*）。

自訂繫結掛載

agents.defaults.sandbox.docker.binds 會將其他主機目錄掛載到容器中。格式：host:container:mode（例如 "/home/user/source:/source:rw"）。

全域與每代理的繫結會被合併（不是取代）。在 scope: "shared" 下，會忽略每代理的繫結。

agents.defaults.sandbox.browser.binds 只會將其他主機目錄掛載到沙盒瀏覽器容器。

• 設定時（包括 []），它會取代瀏覽器容器的 agents.defaults.sandbox.docker.binds。
• 省略時，瀏覽器容器會退回使用 agents.defaults.sandbox.docker.binds（向後相容）。

範例（唯讀來源 + 額外資料目錄）：

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

映像與設定

預設 Docker 映像：openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

預設情況下，Docker 沙盒容器執行時沒有網路。可用 agents.defaults.sandbox.docker.network 覆寫。

Docker 安裝與容器化 Gateway 位於此處：Docker

對於 Docker Gateway 部署，scripts/docker/setup.sh 可以啟動沙盒設定。設定 OPENCLAW_SANDBOX=1（或 true/yes/on）即可啟用該路徑。你可以用 OPENCLAW_DOCKER_SOCKET 覆寫 socket 位置。完整設定與環境參考：Docker。

setupCommand（一次性容器設定）

setupCommand 會在沙盒容器建立後執行一次（不是每次執行都執行）。它會透過 sh -lc 在容器內執行。

路徑：

• 全域：agents.defaults.sandbox.docker.setupCommand
• 每代理：agents.list[].sandbox.docker.setupCommand

工具政策與逃生出口

工具允許/拒絕政策仍會先於 sandbox 規則套用。如果工具已在全域或個別 agent 被拒絕，sandboxing 不會把它恢復。

tools.elevated 是明確的逃生出口，會在 sandbox 外執行 exec（預設為 gateway，或當 exec 目標為 node 時使用 node）。/exec 指令只適用於已授權的傳送者，並會在每個 session 中持續生效；若要強制停用 exec，請使用工具政策拒絕（請參閱 Sandbox vs Tool Policy vs Elevated）。

偵錯：

• 使用 openclaw sandbox explain 檢查有效的 sandbox 模式、工具政策，以及修正用的設定鍵。
• 請參閱 Sandbox vs Tool Policy vs Elevated，了解「為什麼這被封鎖？」的思考模型。

保持鎖定。

多 agent 覆寫

每個 agent 都可以覆寫 sandbox + tools：agents.list[].sandbox 和 agents.list[].tools（以及用於 sandbox 工具政策的 agents.list[].tools.sandbox.tools）。請參閱 Multi-Agent Sandbox & Tools 了解優先順序。

最小啟用範例

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

相關

• Multi-Agent Sandbox & Tools — 個別 agent 覆寫與優先順序
• OpenShell — 受管理的 sandbox 後端設定、workspace 模式與設定參考
• Sandbox configuration
• Sandbox vs Tool Policy vs Elevated — 偵錯「為什麼這被封鎖？」
• Security