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 后被清理（默认 24 小时）。经常使用的智能体可能会让过时的运行时无限期存活。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.list[].sandbox）：
{ "agents": { "defaults": { "sandbox": { "mode": "all", // off、non-main、all "backend": "docker", // docker、ssh、openshell（由插件提供） "scope": "agent", // session、agent、shared "docker": { "image": "openclaw-sandbox:bookworm-slim", "containerPrefix": "openclaw-sbx-", // ... 更多 Docker 选项 }, "prune": { "idleHours": 24, // 空闲 24 小时后自动清理 "maxAgeDays": 7, // 7 天后自动清理 }, }, }, },}