跳转至

沙箱化

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 挂载、工具策略以及修复配置键。其 workspaceRoot 字段仍为已配置的沙箱根目录;effectiveHostWorkspaceRoot 显示活动工作区实际所在位置。
  • openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] 删除容器/环境,以便下次使用时按当前配置重新创建。
  • 请参阅 沙箱与工具策略与提权 以了解“为什么被阻止?”的心智模型。

多智能体覆盖

每个智能体都可以覆盖沙箱 + 工具:agents.entries.*.sandbox 和 agents.entries.*.tools(另加 agents.entries.*.tools.sandbox.tools 用于沙箱工具策略)。有关优先级,请参阅 多智能体沙箱与工具。

托管 GitHub 身份

沙箱执行默认排除智能体的托管 GitHub 身份。 在该智能体的托管身份上设置 agents.entries.<id>.tools.github.allowInSandbox: true, 以允许其在该智能体自己的 Docker 或 Podman 沙箱内使用。 OpenClaw 将所选配置文件以只读方式挂载到 /openclaw/github,将 GH_CONFIG_DIR 设置为该路径,并提供与主机执行相同的托管 token 和 Git 作者。 容器需要安装 gh 才能执行 GitHub CLI 命令。

此选择加入会将凭据暴露给沙箱中运行的代码;只读 挂载可防止配置文件被编辑,但不能防止读取凭据。openclaw security audit 会为每个已选择加入的智能体发出警告。生效的 scope: "shared" 会拒绝 身份注入,并记录一条指明该智能体的警告,因为该容器 可以为其他智能体提供服务。角色必需的沙箱保留其按创建者 隔离,并支持选择加入。其他沙箱后端在启用选择加入时会拒绝配置。请参阅 GitHub 身份。

最小启用示例

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

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