Sandbox CLI

管理基于 Docker 的 Sandbox 容器，用于隔离 Agent 执行环境。

概述

OpenClaw 可以在隔离的 Docker 容器中运行 Agent，以提高安全性。sandbox 命令帮你管理这些容器，特别是在更新或配置变更后。

命令

`openclaw sandbox explain`

检查有效的 Sandbox 模式/作用域/Workspace 访问权限、Sandbox 工具策略和提升权限的 gates（包含修复配置的键路径）。

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

`openclaw sandbox list`

列出所有 Sandbox 容器及其状态和配置。

openclaw sandbox list
openclaw sandbox list --browser  # 只列出浏览器容器
openclaw sandbox list --json     # JSON 格式输出

输出内容包括：

容器名称和状态（运行中/已停止）
Docker 镜像以及是否与配置匹配
存在时长（自创建以来的时间）
空闲时长（自上次使用以来的时间）
关联的 Session/Agent

`openclaw sandbox recreate`

删除 Sandbox 容器，强制使用更新的镜像/配置重新创建。

openclaw sandbox recreate --all                # 重建所有容器
openclaw sandbox recreate --session main       # 重建特定 Session
openclaw sandbox recreate --agent mybot        # 重建特定 Agent
openclaw sandbox recreate --browser            # 只重建浏览器容器
openclaw sandbox recreate --all --force        # 跳过确认提示

选项：

--all：重建所有 Sandbox 容器
--session <key>：重建特定 Session 的容器
--agent <id>：重建特定 Agent 的容器
--browser：只重建浏览器容器
--force：跳过确认提示

重要提示： 容器会在 Agent 下次使用时自动重新创建。

使用场景

更新 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

修改 Sandbox 配置后

# 编辑配置：agents.defaults.sandbox.*（或 agents.list[].sandbox.*）

# 重建以应用新配置
openclaw sandbox recreate --all

修改 setupCommand 后

openclaw sandbox recreate --all
# 或者只重建一个 Agent：
openclaw sandbox recreate --agent family

只针对特定 Agent

# 只更新一个 Agent 的容器
openclaw sandbox recreate --agent alfred

为什么需要这个命令？

问题： 当你更新 Sandbox Docker 镜像或配置时：

现有容器会继续使用旧设置运行
容器只会在闲置 24 小时后被清理
经常使用的 Agent 会让旧容器一直运行

解决方案： 使用 openclaw sandbox recreate 强制删除旧容器。它们会在下次需要时自动使用当前设置重新创建。

提示：优先使用 openclaw sandbox recreate 而不是手动 docker rm。它使用 Gateway 的容器命名规则，避免在作用域/Session 键变更时出现不匹配。

配置

Sandbox 设置位于 ~/.openclaw/openclaw.json 的 agents.defaults.sandbox 下（单个 Agent 的覆盖配置在 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 天后自动清理
        },
      },
    },
  },
}