沙箱 CLI

管理沙箱运行时，用于隔离的代理执行：Docker/Podman 容器、SSH 目标或 OpenShell 后端。

openclaw agent exec 会保留由继承的配置或 --config 选择的沙箱，包括其执行路由。在没有配置沙箱的情况下，其默认值允许在 Gateway 主机上完全执行，并将文件系统工具限制为 --cwd。--isolated 和 --auth-env-only 会跳过配置继承并使用这些默认值。

命令¶

openclaw sandbox list¶

列出沙箱运行时，包括状态、后端、配置匹配、年龄、空闲时间以及关联的会话/代理。

对于配置的插件提供的后端（如 OpenShell），CLI 会在检查实时运行时状态之前加载所属的后端插件。仅浏览器操作不需要激活后端插件。

openclaw sandbox list
openclaw sandbox list --browser  # browser containers only
openclaw sandbox list --json

openclaw sandbox recreate¶

移除沙箱运行时，以强制根据当前配置重建。代理下次使用时将自动重建运行时。

openclaw sandbox recreate --all
openclaw sandbox recreate --agent mybot        # includes agent:mybot:* sub-sessions
openclaw sandbox recreate --session "agent:main:main"
openclaw sandbox recreate --browser --all      # only browser containers
openclaw sandbox recreate --all --force        # skip confirmation

选项：

• --all：重建所有沙箱容器
• --session <key>：使用此确切的作用域键（如 sandbox list 所示）重建运行时；不进行短名称扩展
• --agent <id>：为一个代理重建运行时（匹配 agent:<id> 和 agent:<id>:*）
• --browser：仅影响浏览器容器
• --force：跳过确认提示

必须且只能传入 --all、--session 或 --agent 之一。

限定作用域的重建会在检查后端之前选择注册表条目。另一个 Podman 连接上的无关运行时或不可用的后端不会阻止 --session 或 --agent。所选运行时仍然要求其记录的目标处于活动状态且可访问；--force 仅跳过确认提示。仅浏览器的重建不会检查常规沙箱运行时。

当记录的 Podman 目标不同时，未限定作用域的 sandbox list 仍可能无法通过其目标检查。请恢复受影响运行时的原始连接，使用其已知的确切作用域键配合 recreate --session，并在确认前查看预览。如果你不知道确切的作用域，请保持注册表完整；不要猜测键、扩大为 --all，或重写其记录的目标以绕过验证。

对于 ssh 和 OpenShell remote，重建比 Docker 更重要：初始种子之后远程工作区即是规范工作区，recreate 会删除该所选作用域下的规范远程工作区，而下次运行会从当前本地工作区重新播种。

openclaw sandbox explain¶

检查有效的沙箱模式/作用域/工作区访问权限、沙箱工具策略，以及提权工具门槛（包含修复建议的配置键路径）。

报告将 workspaceRoot 保留为配置的沙箱根目录，并单独显示有效的主机工作区、后端运行时工作目录和 Docker 挂载表。对于 workspaceAccess: "rw"，有效的主机工作区是代理工作区，而不是 workspaceRoot 下方的目录。

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

与 recreate --session 不同，此命令接受简短的会话名称（例如 main），并针对已解析的代理进行扩展。对于没有隐式所有者的多代理集群，显式的 --agent 就足够了；沙箱解释不要求也不猜测默认所有者。

为什么需要重建¶

更新沙箱配置不会影响正在运行的容器：现有运行时保留其旧设置，闲置运行时仅在 prune.idleHours（默认 24 小时）后被清理。经常使用的代理可能会让过时的运行时无限期存活。openclaw sandbox recreate 会移除旧运行时，以便下次使用时根据当前配置重建。

常见触发条件¶

在以下任何更改之后运行 openclaw sandbox recreate --all：

• 容器沙箱镜像更新：agents.defaults.sandbox.docker.image
• 沙箱配置：agents.defaults.sandbox.*
• SSH 目标/认证：agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}
• OpenShell 源/策略/模式：plugins.entries.openshell.config.{from,mode,policy}
• setupCommand — --agent <id> 重建一个代理，而不是全部

注册表迁移¶

沙箱运行时元数据存储于共享的 SQLite 状态数据库中。较旧的安装可能包含遗留的注册表文件，常规读取不再重写这些文件：

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json
• 每个容器/浏览器在 ~/.openclaw/sandbox/containers/ 或 ~/.openclaw/sandbox/browsers/ 下有一个 JSON 分片

运行 openclaw doctor --fix 可将有效的遗留条目迁移到 SQLite。无效的遗留文件会被隔离，因此损坏的旧注册表无法隐藏当前的运行时条目。

配置¶

沙箱设置位于 ~/.openclaw/openclaw.json 中的 agents.defaults.sandbox 下（按代理覆盖项位于 agents.entries.*.sandbox）：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, podman, ssh; openshell is plugin-provided
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // auto-prune after 24h idle
          "maxAgeDays": 7, // auto-prune after 7 days
        },
      },
    },
  },
}

相关¶

• CLI 参考
• 沙箱化
• Agent 工作区
• Doctor：检查沙箱配置。
• OpenShell — 通过 openshell CLI 驱动的托管沙箱后端