Sandbox CLI

管理基於 Docker 的沙箱容器，用於代理的隔離執行。

概覽

OpenClaw 可在隔離的 Docker 容器中執行代理以提升安全性。sandbox 指令群組可協助你管理這些容器，尤其在更新或設定變更之後。

指令

`openclaw sandbox explain`

檢視有效的沙箱模式/範圍/工作區存取、沙箱工具政策及提權閘道（附修正用的設定鍵路徑）。

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

`openclaw sandbox list`

列出所有沙箱容器及其狀態與設定。

openclaw sandbox list
openclaw sandbox list --browser  # 僅列出瀏覽器容器
openclaw sandbox list --json     # JSON 輸出

輸出包含：

容器名稱與狀態（執行中/已停止）
Docker 映像檔及是否與設定相符
存在時間（建立後經過的時間）
閒置時間（上次使用後經過的時間）
關聯的工作階段/代理

`openclaw sandbox recreate`

移除沙箱容器，強制以更新的映像檔/設定重新建立。

openclaw sandbox recreate --all                # 重建所有容器
openclaw sandbox recreate --session main       # 指定工作階段
openclaw sandbox recreate --agent mybot        # 指定代理
openclaw sandbox recreate --browser            # 僅重建瀏覽器容器
openclaw sandbox recreate --all --force        # 跳過確認提示

選項：

--all：重建所有沙箱容器
--session <key>：重建指定工作階段的容器
--agent <id>：重建指定代理的容器
--browser：僅重建瀏覽器容器
--force：跳過確認提示

重要： 容器會在代理下次使用時自動重新建立。

使用情境

更新 Docker 映像檔後

# 拉取新映像檔
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# 更新設定以使用新映像檔
# 編輯設定：agents.defaults.sandbox.docker.image（或 agents.list[].sandbox.docker.image）

# 重建容器
openclaw sandbox recreate --all

變更沙箱設定後

# 編輯設定：agents.defaults.sandbox.*（或 agents.list[].sandbox.*）

# 重建以套用新設定
openclaw sandbox recreate --all

變更 setupCommand 後

openclaw sandbox recreate --all
# 或只重建一個代理：
openclaw sandbox recreate --agent family

僅針對特定代理

# 只更新一個代理的容器
openclaw sandbox recreate --agent alfred

為什麼需要這個功能？

問題： 更新沙箱 Docker 映像檔或設定後：

現有容器會繼續使用舊的設定執行
容器僅在閒置 24 小時後才會被清理
經常使用的代理會讓舊容器無限期地持續執行

解法： 使用 openclaw sandbox recreate 強制移除舊容器。下次需要時它們會以目前的設定自動重建。

提示：建議使用 openclaw sandbox recreate 而非手動 docker rm，它使用 Gateway 的容器命名規則，避免當 scope/session key 變更時產生不一致。

設定

沙箱設定位於 ~/.openclaw/openclaw.json 的 agents.defaults.sandbox 下（各代理的覆寫設定放在 agents.list[].sandbox）：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... 更多 Docker 選項
        },
        "prune": {
          "idleHours": 24, // 閒置 24 小時後自動清理
          "maxAgeDays": 7, // 7 天後自動清理
        },
      },
    },
  },
}