CLI 命令
沙箱 CLI
管理用于隔离智能体执行的沙箱运行时：Docker 容器、SSH 目标或 OpenShell 后端。
命令
openclaw sandbox list
列出沙箱运行时及其状态、后端、配置匹配情况、存在时长、空闲时间和关联的会话/智能体。
openclaw sandbox listopenclaw sandbox list --browser # 仅浏览器容器openclaw sandbox list --jsonopenclaw sandbox recreate
移除沙箱运行时，以强制使用当前配置重新创建。下次使用智能体时，运行时会自动重新创建。
openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot # 包括 agent:mybot:* 子会话openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all # 仅浏览器容器openclaw sandbox recreate --all --force # 跳过确认选项：
--all：重新创建所有沙箱容器--session <key>：使用此精确作用域键（如sandbox list所示）重新创建运行时；不展开短名称--agent <id>：重新创建一个智能体的运行时（匹配agent:<id>和agent:<id>:*）--browser：仅影响浏览器容器--force：跳过确认提示
必须且只能传入 --all、--session 或 --agent 之一。
对于 ssh 和 OpenShell remote，重新创建比使用 Docker 时更重要：初始播种后，远程工作区是规范副本；recreate 会删除所选作用域的该规范远程工作区，下一次运行会从当前本地工作区重新播种。
openclaw sandbox explain
检查有效的沙箱模式/作用域/工作区访问权限、沙箱工具策略和提升权限工具的门控条件（并提供修复配置键路径）。
报告将 workspaceRoot 保留为已配置的沙箱根目录，并单独显示有效的主机工作区、后端运行时工作目录和 Docker 挂载表。对于 workspaceAccess: "rw"，有效的主机工作区是智能体工作区，而不是 workspaceRoot 下的目录。
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json与 recreate --session 不同，此命令接受短会话名称（例如 main），并根据解析出的智能体将其展开。
为什么需要重新创建
更新沙箱配置不会影响正在运行的容器：现有运行时会保留旧设置，而空闲运行时只有在 prune.idleHours 后才会被清理（默认 24h）。经常使用的智能体可能会无限期地保持过时运行时处于活动状态。openclaw sandbox recreate 会移除旧运行时，以便下次使用时根据当前配置重建。
常见触发条件
| 更改 | 命令 |
|---|---|
Docker 镜像更新（agents.defaults.sandbox.docker.image） |
openclaw sandbox recreate --all |
沙箱配置（agents.defaults.sandbox.*） |
openclaw sandbox recreate --all |
SSH 目标/身份验证（agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}） |
openclaw sandbox recreate --all |
OpenShell 源/策略/模式（plugins.entries.openshell.config.{from,mode,policy}） |
openclaw sandbox recreate --all |
setupCommand |
openclaw sandbox recreate --all（或对一个智能体使用 --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", // 关闭、非主会话、全部 "backend": "docker", // docker、ssh、openshell（由插件提供） "scope": "agent", // 会话、智能体、共享 "docker": { "image": "openclaw-sandbox:bookworm-slim", "containerPrefix": "openclaw-sbx-", // ... 更多 Docker 选项 }, "prune": { "idleHours": 24, // 空闲 24h 后自动清理 "maxAgeDays": 7, // 7 天后自动清理 }, }, }, },}