使用 Sandbox CLI 管理 Docker 隔離環境

開發 Agent 最煩人的事情之一，就是環境不一致。你明明更新了 Docker 映像檔或修改了配置，但 Agent 跑起來還是舊的樣子。這通常是因為舊的容器還在背景執行，而你又不想手動去翻 docker ps 一個個刪除。

手動管理這些隔離環境既浪費時間又容易出錯，特別是當你有多個 Session 或不同的 Agent 在跑的時候，你很難記得哪個容器對應哪個任務。透過 Sandbox CLI，你可以輕鬆解決這些版本遺留問題。

需要準備的東西

已安裝 OpenClaw 環境
Docker
已經配置好的 ~/.openclaw/openclaw.json

快速開始

如果你想快速清理並重新啟動你的 Sandbox 環境，只需兩個步驟：

分析與檢查狀態 確認目前的 Sandbox 模式、存取權限以及容器清單：
Terminal window
```
openclaw sandbox explain
openclaw sandbox list
```
強制重製環境 如果你更新了映像檔或配置，直接重啟所有容器：
Terminal window
```
openclaw sandbox recreate --all --force
```
容器會在 Agent 下次執行時自動重新建立。

常用的 Sandbox 指令

檢查配置：`openclaw sandbox explain`

這個指令讓你檢查「生效中」的 Sandbox 配置，包括工具政策和工作區存取權限。

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

監控容器：`openclaw sandbox list`

列出所有容器，並顯示它們是否與目前的配置匹配、已經跑了多久、以及閒置了多久。

openclaw sandbox list --browser  # 只列出瀏覽器容器
openclaw sandbox list --json     # 輸出為 JSON 格式

強制更新：`openclaw sandbox recreate`

當你更新了 openclaw.json 裡的 agents.defaults.sandbox.docker.image，或是改了 setupCommand，舊的容器不會自動更新。這時候就需要手動觸發重製。

openclaw sandbox recreate --all                # 重製所有容器
openclaw sandbox recreate --session main       # 針對特定 Session
openclaw sandbox recreate --agent mybot        # 針對特定 Agent
openclaw sandbox recreate --browser            # 只重製瀏覽器容器

為何需要這個工具？

當你更新 Sandbox 的 Docker 映像檔或設定時，會遇到以下狀況：

現有的容器會帶著舊設定持續執行。
容器只有在閒置 24 小時後才會被自動清理。
頻繁使用的 Agent 會導致舊容器無限期執行下去。

使用 openclaw sandbox recreate 可以強制移除這些舊容器，確保它們在下次啟動時套用最新的設定。

配置範例

Sandbox 設定位於 ~/.openclaw/openclaw.json 的 agents.defaults.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 天
        },
      },
    },
  },
}

疑難排解

問題：我更新了 Docker 映像檔，但 Agent 還是跑在舊環境。 解決方案： 這是因為現有容器不會自動重啟。請執行 openclaw sandbox recreate --all 來強制移除舊容器，Agent 下次執行時就會抓取新映像檔。

問題：手動使用 docker rm 刪除容器後，Agent 啟動異常。 解決方案： 建議優先使用 openclaw sandbox recreate 而不是手動操作 Docker。這個指令會遵循 Gateway 的容器命名規則，避免 Scope 或 Session Key 變更時產生的名稱衝突。

如果你在設定過程遇到問題，可以詢問 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。