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