Sandbox 沙盒执行详解
世界上有一种安全叫沙盒，它把AI的"调皮"关进笼子里...
OpenClaw的Sandbox（沙盒）功能可以让工具在隔离的后端中运行，从而限制AI操作失误时的爆炸半径。这是可选功能，通过配置控制。如果关闭沙盒，工具会在主机上直接执行。
💡 核心概念：沙盒不是完美的安全边界，但能有效限制AI犯傻时对文件系统和进程访问的范围。
沙盒隔离的内容
会被沙盒化的操作：
- 工具执行 -
exec、read、write、edit、apply_patch、process等 - 可选的沙盒浏览器 -
agents.defaults.sandbox.browser
不会被沙盒化的操作：
- Gateway进程本身
- 明确允许在主机上运行的工具（如
tools.elevated）
⚠️ 重要：提升模式（Elevated exec）在主机上运行，绕过沙盒化。如果沙盒关闭，
tools.elevated不会改变执行方式。参见Elevated Mode。
隔离模式
agents.defaults.sandbox.mode控制何时使用沙盒：
| 模式 | 说明 |
|---|---|
"off" |
不使用沙盒（无隔离） |
"non-main" |
仅沙盒化非主会话（默认，如果你想在主机上正常聊天） |
"all" |
每个会话都运行在沙盒中 |
📝 说明：
"non-main"基于session.mainKey（默认"main"），而不是agent id。群组/频道会话使用自己的key，因此会被视为非主会话并沙盒化。
隔离范围
agents.defaults.sandbox.scope控制创建多少容器：
| 范围 | 说明 |
|---|---|
"session" |
每个会话一个容器（默认） |
"agent" |
每个Agent一个容器 |
"shared" |
所有沙盒会话共享一个容器 |
沙盒后端
agents.defaults.sandbox.backend控制使用哪个运行时提供沙盒：
| 后端 | 运行位置 | 特点 |
|---|---|---|
"docker" |
本地容器 | 完整隔离、支持浏览器沙盒 |
"ssh" |
任意SSH可访问主机 | 可卸载到远程机器 |
"openshell" |
OpenShell托管环境 | 托管远程沙盒，可选双向同步 |
Docker后端配置
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
backend: "docker",
scope: "session"
}
}
}
}SSH后端配置
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
scope: "session",
ssh: {
target: "user@gateway-host:22",
workspaceRoot: "/tmp/openclaw-sandboxes",
identityFile: "~/.ssh/id_ed25519"
}
}
}
}
}OpenShell后端配置
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "openshell",
scope: "session"
}
}
},
plugins: {
entries: {
openshell: {
enabled: true,
config: {
// OpenShell配置
}
}
}
}
}浏览器沙盒
OpenClaw支持沙盒化浏览器执行：
- 沙盒浏览器默认自动启动（当浏览器工具需要时确保CDP可达）
- 通过
agents.defaults.sandbox.browser.autoStart和autoStartTimeoutMs配置 - 默认使用专用Docker网络（
openclaw-sandbox-browser） - noVNC访问有密码保护
⚠️ 注意：浏览器沙盒仅Docker后端支持，SSH和OpenShell后端暂不支持。
安全配置
基本配置
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
backend: "docker",
scope: "session"
}
}
}
}严格安全配置
{
agents: {
defaults: {
sandbox: {
mode: "all", // 所有会话都沙盒化
backend: "docker",
scope: "session", // 完全隔离
browser: {
autoStart: true,
allowHostControl: false // 不允许控制主机浏览器
}
}
},
// 强制所有Agent使用沙盒
list: [
{
id: "default",
sandbox: { mode: "all" }
}
]
}
}网络控制
Docker后端网络配置：
sandbox.docker.network- Docker网络名称（默认：无网络）sandbox.docker.binds- 绑定挂载列表sandbox.browser.network- 浏览器容器网络（默认：openclaw-sandbox-browser）sandbox.browser.cdpSourceRange- 限制CDP入口的CIDR白名单
故障排除
| 问题 | 解决方案 |
|---|---|
| 沙盒容器启动失败 | 检查Docker是否运行，检查sandbox.docker.binds路径 |
| 工具无法访问文件 | 确认绑定挂载配置正确，工作空间已同步 |
| 浏览器沙盒不工作 | 确认使用Docker后端，检查CDP端口配置 |
| SSH后端连接失败 | 检查SSH密钥配置，确认目标主机可达 |
最佳实践
✅ 推荐配置：
- 开发测试：使用
mode: "non-main"，正常聊天在主机，测试会话沙盒化 - 生产环境：使用
mode: "all"，所有会话强制沙盒化 - 团队协作：使用SSH后端，将沙盒卸载到专用服务器
- 敏感操作：始终使用沙盒 + 最小权限原则