沙箱化
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 之类的现有链接仍然可以解析。每个条目都指向当前承载该内容的页面。
- 哪些内容会被沙箱化
- 模式、范围和后端
- 支持的能力矩阵
- Docker 后端
- 沙箱化浏览器
- Podman 后端
- SSH 后端
- OpenShell 后端
- Crabbox 后端
- 工作区访问
- 一个代理的多个文件夹
- 其他绑定行为
- 镜像和设置
- 构建默认镜像
- 可选:构建通用镜像
- 可选:构建沙箱浏览器镜像
- 沙箱浏览器 Chromium 默认设置
- 网络安全默认设置
- setupCommand(一次性容器设置)
- 常见陷阱
工具策略与逃生通道¶
工具允许/拒绝策略仍然先于沙箱规则生效。如果某个工具在全局或按代理被拒绝,沙箱不会使其重新可用。
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",
},
},
},
}
相关¶
- 多智能体沙箱与工具 -- 按智能体覆盖和优先级
- OpenShell -- 托管沙箱后端设置、工作区模式和配置参考
- 沙箱配置
- 沙箱与工具策略与提权 -- 调试“为什么被阻止?”
- 安全
openclaw sandbox— 管理沙箱运行时并检查生效的沙箱策略- 云工作器 — 将会话工作分发到一次性云机器;其托管工作区不是操作系统沙箱
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw