沙箱隔離

OpenClaw 可在沙箱後端中執行工具，以縮小影響範圍。沙箱預設為關閉，並由 agents.defaults.sandbox（全域）或 agents.list[].sandbox（個別代理程式）控制。閘道程序一律留在主機上；啟用沙箱後，只有工具執行會移入沙箱。

哪些項目會進入沙箱

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

不會進入沙箱的項目：

• 閘道程序本身。
• 透過 tools.elevated 明確允許在沙箱外執行的任何工具。提升權限的 exec 會略過沙箱，並在設定的逸出路徑上執行（預設為 gateway；當 exec 目標為 node 時則為 node）。若沙箱已關閉，tools.elevated 不會造成任何變化，因為 exec 本來就已在主機上執行。請參閱提升權限模式。

模式、範圍與後端

三項互相獨立的設定控制沙箱行為：

模式控制何時套用沙箱：

• off：不使用沙箱。
• non-main：除代理程式主要工作階段外，所有工作階段都使用沙箱。主要工作階段鍵一律為 agent:<agentId>:main（當 session.scope 為 "global" 時則為 global），且無法設定。群組／頻道工作階段使用各自的鍵，因此一律視為非主要工作階段並使用沙箱。
• all：每個工作階段都在沙箱中執行。

範圍控制建立多少個容器／環境：

• agent：每個代理程式使用一個容器。
• session：每個工作階段使用一個容器。
• shared：所有使用沙箱的工作階段共用一個容器（在此範圍下，會忽略個別代理程式的 docker／ssh／browser 覆寫設定）。

後端控制由哪個執行環境執行沙箱工具。SSH 專用設定位於 agents.defaults.sandbox.ssh；OpenShell 專用設定位於 plugins.entries.openshell.config。

Docker 後端

啟用沙箱後，Docker 是預設後端。它透過 Docker 常駐程式通訊端（/var/run/docker.sock）在本機執行工具與沙箱瀏覽器；隔離能力來自 Docker 命名空間。

預設值：network: "none"（無對外連線）、readOnlyRoot: true、capDrop: ["ALL"]，映像為 openclaw-sandbox:bookworm-slim。

若要將主機 GPU 提供給沙箱，請將 agents.defaults.sandbox.docker.gpus（或個別代理程式的覆寫設定）設為類似 "all" 或 "device=GPU-uuid" 的值。此值會傳遞至 Docker 的 --gpus 旗標，且需要相容的主機執行環境，例如 NVIDIA Container Toolkit。

沙箱瀏覽器

• 當瀏覽器工具需要沙箱瀏覽器時，它會自動啟動（確保可連線至 CDP）。可透過 agents.defaults.sandbox.browser.autoStart（預設為 true）與 autoStartTimeoutMs（預設為 12 秒）設定。
• 沙箱瀏覽器容器使用專用 Docker 網路（openclaw-sandbox-browser），而非全域 bridge 網路。可透過 agents.defaults.sandbox.browser.network 設定。
• agents.defaults.sandbox.browser.cdpSourceRange 使用 CIDR 允許清單限制容器邊界的 CDP 輸入流量（例如 172.21.0.1/32）。
• noVNC 觀察者存取預設受密碼保護；OpenClaw 會產生短效權杖網址，用於提供本機啟動頁面，並以網址片段中的密碼開啟 noVNC（不會放在查詢字串或標頭記錄中）。
• agents.defaults.sandbox.browser.allowHostControl（預設為 false）允許沙箱工作階段明確指定主機瀏覽器。
• 選用的允許清單會限制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。

SSH 後端

使用 backend: "ssh"，可在任何能透過 SSH 存取的機器上，對 exec、檔案工具及媒體讀取作業進行沙箱隔離。

{  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",          // 或使用 SecretRefs／行內內容，而非本機檔案：          // 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" },        },      },    },  },}

預設值：command: "ssh"、workspaceRoot: "/tmp/openclaw-sandboxes"、strictHostKeyChecking: true、updateHostKeys: true。

• 生命週期：OpenClaw 會在 sandbox.ssh.workspaceRoot 下建立各範圍專用的遠端根目錄。建立或重新建立後首次使用時，它會從本機工作區將內容植入該遠端工作區一次。此後，exec、read、write、edit、apply_patch、提示媒體讀取及輸入媒體暫存作業，都會透過 SSH 直接操作遠端工作區。OpenClaw 不會自動將遠端變更同步回本機工作區。
• 驗證資料：identityFile／certificateFile／knownHostsFile 參照現有的本機檔案。identityData／certificateData／knownHostsData 可接受行內字串或 SecretRefs，經由一般的祕密執行環境快照解析後，會以 0600 模式寫入暫存檔案，並於 SSH 工作階段結束時刪除。若同一項目同時設定 *File 與 *Data 變體，則該工作階段以 *Data 為準。
• 以遠端為準的影響：完成初始植入後，遠端 SSH 工作區會成為實際的沙箱狀態。在植入步驟完成後，於 OpenClaw 外部進行的主機本機編輯，在重新建立沙箱前都不會顯示於遠端。openclaw sandbox recreate 會刪除各範圍專用的遠端根目錄，並在下次使用時再次從本機植入。此後端不支援瀏覽器沙箱，且 sandbox.docker.* 設定不適用。

OpenShell 後端

使用 backend: "openshell"，可在 OpenShell 管理的遠端環境中隔離工具。OpenShell 會重複使用與一般 SSH 後端相同的 SSH 傳輸與遠端檔案系統橋接，並加入 OpenShell 生命週期（sandbox create/get/delete/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        },      },    },  },}

mode: "mirror"（預設）以本機工作區為準：OpenClaw 會在執行 exec 前將本機內容同步至沙箱，並於執行後同步回本機。mode: "remote" 會從本機將內容植入遠端工作區一次，之後直接對遠端工作區執行 exec／read／write／edit／apply_patch，而不會同步回本機；植入後的本機編輯在執行 openclaw sandbox recreate 前都不會顯示。使用 scope: "agent" 或 scope: "shared" 時，該遠端工作區會在相同範圍內共用。目前的限制：尚不支援沙箱瀏覽器，且 sandbox.docker.binds 不適用於此後端。

openclaw sandbox list／recreate／prune 對 OpenShell 執行環境與 Docker 執行環境採用相同處理方式；清理邏輯會辨識後端。

如需完整的先決條件、設定參考、工作區模式比較與生命週期詳細資訊，請參閱 OpenShell。

工作區存取權限

agents.defaults.sandbox.workspaceAccess 控制沙箱可查看的內容：

使用 OpenShell 後端時，mirror 模式仍會在各次執行之間使用本機工作區作為標準來源；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 只會將額外的主機目錄掛載到沙箱瀏覽器容器。設定時（包括 []），它會取代瀏覽器容器的 docker.binds；省略時，瀏覽器容器會退回使用 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 安裝與容器化閘道的資訊位於：Docker

對於 Docker 閘道部署，scripts/docker/setup.sh 可以啟動沙箱設定。將 OPENCLAW_SANDBOX=1（或 true/yes/on）設為啟用該路徑。可使用 OPENCLAW_DOCKER_SOCKET 覆寫通訊端位置。完整設定與環境變數參考：Docker。

setupCommand（單次容器設定）

setupCommand 會在建立沙箱容器後執行一次（並非每次執行時）。它會透過 sh -lc 在容器內執行。

路徑：

• 全域：agents.defaults.sandbox.docker.setupCommand
• 各代理程式：agents.list[].sandbox.docker.setupCommand

工具政策與逃生機制

工具允許／拒絕政策仍會先於沙箱規則套用。如果工具在全域或各代理程式層級遭拒絕，沙箱機制不會讓它恢復可用。

tools.elevated 是明確的逃生機制，可在沙箱外執行 exec（預設為 gateway；當執行目標為 node 時則為 node）。/exec 指示僅適用於已授權的傳送者，並會在各工作階段中持續生效；若要徹底停用 exec，請使用工具政策拒絕（請參閱沙箱與工具政策及提升權限執行的比較）。

偵錯：

• openclaw sandbox list 會顯示沙箱容器、狀態、映像相符情況、存續時間、閒置時間及相關工作階段／代理程式。
• openclaw sandbox explain [--session <key>] [--agent <id>] 會檢查有效的沙箱模式、主機工作區、執行環境工作目錄、Docker 掛載、工具政策及修正用設定鍵。其 workspaceRoot 欄位會維持為設定的沙箱根目錄；effectiveHostWorkspaceRoot 則會顯示使用中的工作區實際所在位置。
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] 會移除容器／環境，使其在下次使用時依照目前設定重新建立。
• 如需理解「為何這會被封鎖？」的思考模型，請參閱沙箱與工具政策及提升權限執行的比較。

多代理程式覆寫

每個代理程式都可以覆寫沙箱與工具：agents.list[].sandbox 和 agents.list[].tools（另加沙箱工具政策的 agents.list[].tools.sandbox.tools）。如需優先順序，請參閱多代理程式沙箱與工具。

最小啟用範例

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

相關內容

• 多代理程式沙箱與工具 -- 各代理程式的覆寫設定與優先順序
• OpenShell -- 受管理沙箱後端設定、工作區模式與設定參考
• 沙箱設定
• 沙箱與工具政策及提升權限的差異 -- 偵錯「為什麼這會被封鎖？」
• 安全性