沙箱隔離

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

哪些項目會在沙箱中執行

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

不在沙箱中執行：

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

模式、範圍與後端

三項彼此獨立的設定控制沙箱行為：

模式控制何時套用沙箱：

• 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 會產生一個短效權杖 URL，用於提供本機啟動頁面，並在 URL 片段中帶入密碼開啟 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 模式仍會在每次 exec 回合之間以本機工作區為標準來源；remote 模式則會在初次植入後以遠端 OpenShell 工作區為標準；workspaceAccess: "ro"/"none" 仍會以相同方式限制寫入行為。

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

一個代理使用多個資料夾

當沙箱化代理需要存取主要工作區以外的資料夾時，請使用 Docker 繫結掛載。每個項目都會將主機資料夾對應至容器路徑，並明確指定存取模式：

host-directory:container-directory:rohost-directory:container-directory:rw

• ro 會讓掛載的資料夾在沙箱內為唯讀。
• rw 允許沙箱化工具和程序變更主機資料夾。
• 容器路徑是代理使用的路徑。主機路徑不會自動公開。

此範例為 research 代理提供可寫入的主要工作區、位於 /reference 的唯讀參考資料，以及位於 /drafts 的獨立可寫入輸出資料夾：

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // 必要，因為這些來源位於代理工作區之外。            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess 與繫結模式彼此獨立：

變更 workspaceAccess 不會將額外繫結從 ro 變更為 rw，反之亦然。全域和各代理的 docker.binds 會合併。各代理的繫結請保留 scope: "agent" 或 "session"；scope: "shared" 會忽略所有各代理 Docker 覆寫，並只使用全域繫結。

繫結掛載是受支援的多資料夾邊界，因為 Docker 會透過掛載隔離建構容器的檔案系統視圖，而 ro/rw 模式會套用至沙箱中的每個程序。此邊界涵蓋 exec、檔案系統工具、子程序和程式庫，不需要在每個 OpenClaw 程式碼路徑中重複進行路徑授權檢查。如果允許的殼層或相依套件可以直接存取檔案，主機端路徑允許清單就無法提供同等完整的邊界。

選擇啟用的 dangerouslyAllowExternalBindSources 僅允許工作區根目錄之外的來源。它不會停用 OpenClaw 對系統路徑、認證資訊、Docker 通訊端、符號連結父路徑或保留目標的封鎖檢查。請優先使用最小範圍的資料夾，除非需要寫入，否則請使用 ro，並在變更掛載後重新建立沙箱：

openclaw sandbox recreate --agent research

其他繫結行為

agents.defaults.sandbox.docker.binds 設定全域掛載。格式同樣採用 host:container:mode 形式（例如 "/home/user/source:/source:rw"）。

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.entries.*.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.entries.*.sandbox 和 agents.entries.*.tools（以及用於沙箱工具政策的 agents.entries.*.tools.sandbox.tools）。優先順序請參閱多代理程式沙箱與工具。

最小啟用範例

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

相關內容

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