沙盒化

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"（預設）：每個代理程式一個容器。
• "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 或每個代理程式的 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 傳輸和遠端檔案系統橋接，並加入 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 執行環境以及 Docker 執行環境
• openclaw sandbox recreate 會刪除目前執行環境，並讓 OpenClaw 在下次使用時重新建立
• prune 邏輯也會感知後端

對於 remote 模式，recreate 特別重要：

• recreate 會刪除該 scope 的 canonical 遠端工作區
• 下次使用時會從本機工作區初始化全新的遠端工作區

對於 mirror 模式，recreate 主要會重設遠端執行環境，因為本機工作區仍然是 canonical。

# 工作區存取

agents.defaults.sandbox.workspaceAccess 控制沙箱能看到什麼：

使用 OpenShell 後端時：

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

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

# 自訂 bind 掛載

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

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

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-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["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 可以 bootstrap 沙箱設定。設定 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

# 工具政策與逃生出口

工具允許/拒絕政策仍會在沙盒規則之前套用。如果某個工具在全域或每個代理層級被拒絕，沙盒化不會把它恢復。

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

除錯：

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

保持鎖定狀態。

# 多代理覆寫

每個代理都可以覆寫沙盒與工具：agents.list[].sandbox 和 agents.list[].tools（另有 agents.list[].tools.sandbox.tools 用於沙盒工具政策）。請參閱 多代理沙盒與工具 了解優先順序。

# 最小啟用範例

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

# 相關

• 多代理沙盒與工具 — 每個代理的覆寫與優先順序
• OpenShell — 受管理的沙盒後端設定、工作區模式與設定參考
• 沙盒設定
• 沙盒 vs 工具政策 vs Elevated — 除錯「為什麼這被封鎖？」
• 安全性