沙箱

OpenClaw 可以在沙箱后端中运行工具执行，以缩小爆炸半径。沙箱功能默认关闭，由 agents.defaults.sandbox（全局）、agents.entries.*.sandbox（按智能体）或必需的创建者角色沙箱策略控制。Gateway 进程始终保留在主机上；启用后，只有工具执行才会移入沙箱。

Note

这并非完美的安全边界，但当模型做出某些愚蠢行为时，它能实质性地限制文件和进程的访问。

沙箱页面¶

本页是一个索引。沙箱参考内容分布在十二个页面中。请打开与您正在配置的内容相匹配的页面。

页面	何时阅读
哪些内容会被沙箱化	您想确切了解哪些执行会移入沙箱。
模式、范围和后端	您正在决定哪些会话将在沙箱中运行以及它们如何共享环境。
支持的能力矩阵	您正在比较 Docker、SSH 和 OpenShell，以便选择后端。
Docker 后端	您正在运行默认的本地后端，或启用沙箱浏览器。
Podman 后端	您正在使用 Podman 代替 Docker 进行沙箱化的工具执行。
SSH 后端	您正在通过 SSH 将沙箱化的工具执行卸载到远程机器上。
OpenShell 后端	您正在由 OpenShell 管理的远程环境中对工具进行沙箱化。
Crabbox 后端	您希望在 Crabbox 租用的云端盒子上执行工具，同时让智能体保持本地运行。
工作区访问	您正在决定沙箱可以看到智能体工作区的哪些内容。
单个智能体的多个文件夹	某个沙箱化的智能体需要的不仅是其主工作区。
镜像与设置	您需要构建或自定义沙箱镜像。
setupCommand（一次性容器设置）	您需要在新创建的沙箱容器内运行一次性设置。

各部分的迁移位置¶

此页面曾经发布的所有锚点都保留在此处，因此诸如 /gateway/sandboxing#images-and-setup 之类的现有链接仍然可以正常解析。每个条目都指向当前承载相应内容的页面。

工具策略与逃生通道¶

工具允许/拒绝策略仍然在沙箱规则之前生效。如果某个工具在全局或按智能体级别被拒绝，沙箱化不会让其重新生效。

tools.elevated 是一个显式的逃生通道，它会在沙箱之外运行 exec（默认情况下为 gateway，当 exec 目标为 node 时则为 node）。/exec 指令仅适用于经授权的发送者，并且按会话持续生效；要彻底禁用 exec，请使用工具策略中的拒绝（参见沙箱 vs 工具策略 vs 提升权限）。

调试：¶

openclaw sandbox list 显示沙箱容器、状态、镜像匹配、存在时长、空闲时间以及关联的会话/代理。
openclaw sandbox explain [--session <key>] [--agent <id>] 检查生效的沙箱模式、主机工作区、运行时工作目录、Docker 挂载、工具策略和 fix-it 配置键。其 workspaceRoot 字段仍保持为配置的沙箱根目录；effectiveHostWorkspaceRoot 则显示活动工作区的实际所在位置。
openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] 移除容器/环境，以便下次使用时按当前配置重新创建。
关于“为什么这被阻止了？”的心智模型，请参阅沙箱 vs 工具策略 vs 提升权限。

多代理覆盖¶

每个代理都可以覆盖沙箱 + 工具：agents.entries.*.sandbox 和 agents.entries.*.tools（以及用于沙箱工具策略的 agents.entries.*.tools.sandbox.tools）。有关优先级，请参阅多代理沙箱与工具。

最小启用示例¶

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

多代理沙箱与工具 -- 按代理的覆盖与优先级
OpenShell -- 托管沙箱后端设置、工作区模式与配置参考
沙箱配置
沙箱 vs 工具策略 vs 提升权限 -- 调试“为什么这被阻止了？”
安全
openclaw sandbox — 管理沙箱运行时并检查生效的沙箱策略
Cloud Workers — 将会话工作分派到一次性云机器；其托管工作区不是操作系统沙箱

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

沙箱