当前位置：首页 > news >正文

小学子讲技术 - OpenClaw 沙箱集成详解

news 2026/5/11 19:49:51

OpenClaw 沙箱集成详解

📚 小学子讲技术系列

什么是沙箱集成？

Hey，小学子来啦！🎉 今天我们要聊一个非常重要的话题——OpenClaw 的沙箱集成。

想象一下，你让 AI 代理帮你执行一些操作，但它可能会"失控"或者做出一些不明智的决定。这时候，沙箱（Sandbox）就像是一个安全隔离区，把 AI 的操作限制在一个可控的范围内。即使 AI 做出了"傻事"，也不会对你的主机造成太大损害。

OpenClaw 的沙箱集成允许你在Docker 容器中运行工具，这样可以大大减少"爆炸半径"（blast radius）。这是可选功能，通过配置来控制。

沙箱集成核心概念

1. 什么会被沙箱化？

✅会被沙箱化的操作：

工具执行：exec、read、write、edit、apply_patch、process等
可选的沙箱浏览器：agents.defaults.sandbox.browser

❌不会被沙箱化的操作：

Gateway 进程本身
明确允许在主机上运行的工具（如tools.elevated）

⚠️重要提示：Elevated exec是在主机上运行的，会绕过沙箱！

2. 沙箱模式（Mode）

通过agents.defaults.sandbox.mode控制沙箱何时启用：

模式	说明
`"off"`	不使用沙箱，所有工具都在主机上运行
`"non-main"`	只对非主会话启用沙箱（默认选项）
`"all"`	所有会话都运行在沙箱中

💡小贴士："non-main"模式基于session.mainKey（默认"main"）来判断，不是 agent id。群组/频道会话使用自己的 key，所以会被沙箱化。

3. 沙箱作用域（Scope）

控制创建多少个容器：

作用域	说明
`"session"`	每个会话一个容器（默认）
`"agent"`	每个 agent 一个容器
`"shared"`	所有沙箱会话共享一个容器

4. 工作区访问权限

控制沙箱能看到什么：

权限	说明
`"none"`	工具只能看到沙箱工作区`~/.openclaw/sandboxes`（默认）
`"ro"`	以只读方式挂载 agent 工作区到`/agent`（禁用 write/edit/apply_patch）
`"rw"`	以读写方式挂载 agent 工作区到`/workspace`

沙箱配置详解

最小配置示例

{ agents: { defaults: { sandbox: { mode: "non-main", // 非主会话启用沙箱 scope: "session", // 每个会话一个容器 workspaceAccess: "none" // 不访问主机工作区 } } } }

自定义 Docker 镜像

默认镜像：openclaw-sandbox:bookworm-slim

如果需要包含常用工具（curl、jq、nodejs、python3、git），可以构建通用镜像：

scripts/sandbox-common-setup.sh

然后在配置中指定：

{ agents: { defaults: { sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } } } } }

绑定挂载（Bind Mounts）

可以挂载额外的主机目录到容器中：

{ agents: { defaults: { sandbox: { docker: { binds: [ "/home/user/source:/source:ro", // 只读挂载 "/var/data/myapp:/data:rw" // 读写挂载 ] } } } } }

⚠️安全警告：绑定挂载会穿透沙箱文件系统！请谨慎使用，敏感目录建议使用:ro只读模式。

沙箱浏览器

OpenClaw 支持在沙箱中运行浏览器，配置选项包括：

autoStart：浏览器工具需要时自动启动
network：沙箱浏览器使用的 Docker 网络
cdpSourceRange：CDP 入口的 CIDR 白名单
allowHostControl：允许沙箱会话控制主机浏览器

浏览器安全加固

沙箱浏览器默认使用以下 Chromium 启动参数：

--no-sandbox
--disable-gpu
--disable-3d-apis
--disable-extensions
--renderer-process-limit=2

多代理沙箱配置

OpenClaw 支持为不同的 agent 配置不同的沙箱策略：

示例：个人助手 + 受限家庭机器人

{agents:{list:[{id:"main",default:true,name:"Personal Assistant",sandbox:{mode:"off"}// 主机运行，完全信任},{id:"family",name:"Family Bot",sandbox:{mode:"all",scope:"agent"},tools:{allow:["read"],deny:["exec","write","edit","apply_patch","process","browser"]}}]}}

工具策略与沙箱的关系

OpenClaw 有三层安全控制：

沙箱 (Sandbox)- 决定工具在哪里运行（Docker vs 主机）
工具策略 (Tool Policy)- 决定哪些工具可用/禁止
Elevated 模式- exec 专用的"逃逸 hatch"，在主机上运行

工具策略层级

过滤顺序：

工具配置 (profile)
提供商工具配置
全局工具策略 (allow/deny)
提供商工具策略
Agent 专属工具策略
沙箱工具策略
子代理工具策略

工具组快捷方式

可以使用组名快速配置：

group:runtime→ exec, bash, process
group:fs→ read, write, edit, apply_patch
group:sessions→ sessions_list, sessions_history, sessions_send…
group:memory→ memory_search, memory_get
group:ui→ browser, canvas
group:automation→ cron, gateway
group:messaging→ message

调试命令

查看沙箱配置

openclaw sandbox explain openclaw sandbox explain--sessionagent:main:main openclaw sandbox explain--agentwork openclaw sandbox explain--json

这会显示：

有效的沙箱模式/作用域/工作区访问
当前会话是否沙箱化
有效的沙箱工具 allow/deny
elevated 门控和修复配置键路径

列出沙箱容器

openclaw sandbox list openclaw sandbox list--browser# 只看浏览器容器

重建沙箱容器

openclaw sandbox recreate--all# 重建所有openclaw sandbox recreate--sessionmain# 特定会话openclaw sandbox recreate--agentmybot# 特定 agentopenclaw sandbox recreate--browser# 只重建浏览器