沙箱 CLI

管理基于 Docker 的沙箱容器，为 agent 提供隔离执行环境。

概览

OpenClaw 可以在隔离的 Docker 容器中运行 agent，提升安全性。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 镜像及是否与配置匹配
创建时间
空闲时间（距上次使用的时长）
关联的 session / agent

`openclaw sandbox recreate`

移除沙箱容器，强制使用更新后的镜像 / 配置重新创建。

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：重建所有沙箱容器
--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

修改沙箱配置后

# 编辑配置：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

为什么需要这么做？

问题： 更新沙箱 Docker 镜像或配置后：

现有容器会继续使用旧的设置运行
容器只有在空闲 24 小时后才会被清理
频繁使用的 agent 会让旧容器一直跑着

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

建议用 openclaw sandbox recreate 而不是手动 docker rm。它使用 Gateway 的容器命名规则，避免 scope / session key 变更时出现不匹配。

配置

沙箱设置在 ~/.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 天后自动清理
        },
      },
    },
  },
}