跳转至

Sandbox CLI

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

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

命令

openclaw sandbox list

列出沙箱运行时,包括状态、后端、配置匹配、存在时长、空闲时间以及关联的会话/agent。

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

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

openclaw sandbox recreate

移除沙箱运行时,以强制使用当前配置重新创建。agent 下次使用时,运行时将自动重新创建。

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 重新创建运行时(匹配 agent:<id> 和 agent:<id>:*)
  • --browser:仅影响浏览器容器
  • --force:跳过确认提示

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

重新创建需要所选状态目录的独占离线所有权。如果其 Gateway 正在运行,该命令会在检查或移除运行时之前拒绝执行。通过其服务所有者停止 Gateway,等待所有权释放,然后重新运行该命令。离线所有权在确认和已接受的拆除过程中保持持有;正在启动的 Gateway 会等待清理结束。--force 不会绕过此所有权检查。

有关所有者发现、拒绝状态和兼容性边界,请参阅 本地状态所有者路由。

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

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

对于 ssh 和 OpenShell remote,recreate 比 Docker 更关键:初始播种后,远程工作区即为规范工作区;recreate 会删除所选作用域的该规范远程工作区,下次运行时会从当前本地工作区重新播种。

openclaw sandbox explain

检查有效的沙箱模式/作用域/工作区访问权限、沙箱工具策略,以及提权工具门控(附带 fix-it 配置键路径)。

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

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

与 recreate --session 不同,此命令接受短会话名称(例如 main),并会根据已解析的 agent 展开它们。对于没有隐式所有者的多 agent 集群,显式指定 --agent 即可;沙箱解释不要求也不猜测默认项。

为何需要 recreate

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

Tip

优先使用 openclaw sandbox recreate,而不是手动进行后端特定的清理。它会使用 Gateway 的运行时注册表,并在作用域或会话键发生变化时避免不匹配。

常见触发场景

在发生以下任意更改之后,运行 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> 重建一个 agent 而非全部

Note

agent 下次使用时,运行时将自动重新创建。

注册表迁移

沙箱运行时元数据存储在共享的 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
        },
      },
    },
  },
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw