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_patchrw以读写方式挂载 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 网络cdpSourceRangeCDP 入口的 CIDR 白名单allowHostControl允许沙箱会话控制主机浏览器浏览器安全加固沙箱浏览器默认使用以下 Chromium 启动参数--no-sandbox--disable-gpu--disable-3d-apis--disable-extensions--renderer-process-limit2多代理沙箱配置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, processgroup:fs→ read, write, edit, apply_patchgroup:sessions→ sessions_list, sessions_history, sessions_send…group:memory→ memory_search, memory_getgroup:ui→ browser, canvasgroup:automation→ cron, gatewaygroup:messaging→ message调试命令查看沙箱配置openclaw sandbox explain openclaw sandbox explain--sessionagent:main:main openclaw sandbox explain--agentwork openclaw sandbox explain--json这会显示有效的沙箱模式/作用域/工作区访问当前会话是否沙箱化有效的沙箱工具 allow/denyelevated 门控和修复配置键路径列出沙箱容器openclaw sandbox list openclaw sandbox list--browser# 只看浏览器容器重建沙箱容器openclaw sandbox recreate--all# 重建所有openclaw sandbox recreate--sessionmain# 特定会话openclaw sandbox recreate--agentmybot# 特定 agentopenclaw sandbox recreate--browser# 只重建浏览器提示修改 Docker 镜像或配置后需要重建容器才能生效。常见问题解决“Tool X blocked by sandbox tool policy”修复方法禁用沙箱agents.defaults.sandbox.modeoff或者在沙箱中允许该工具从tools.sandbox.tools.deny中移除或添加到tools.sandbox.tools.allow“I thought this was main, why is it sandboxed?”在non-main模式下群组/频道的 key 不是 main。使用主会话 key 或切换到off模式。总结沙箱集成是 OpenClaw 安全架构的重要组成部分✅隔离执行将 AI 工具限制在 Docker 容器中✅可配置灵活的模式、作用域、工作区访问控制✅多代理支持不同 agent 不同安全策略✅浏览器隔离可选的沙箱浏览器✅工具策略细粒度的工具控制记住沙箱不是完美的安全边界但它能显著限制文件系统和进程访问防止 AI “犯傻” 时造成太大损失。相关文档Sandboxing 官方文档Sandbox vs Tool Policy vs ElevatedMulti-Agent Sandbox ToolsSandbox CLI小学子讲技术下期再见
小学子讲技术 - OpenClaw 沙箱集成详解
发布时间：2026/5/26 3:19:53
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_patchrw以读写方式挂载 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 网络cdpSourceRangeCDP 入口的 CIDR 白名单allowHostControl允许沙箱会话控制主机浏览器浏览器安全加固沙箱浏览器默认使用以下 Chromium 启动参数--no-sandbox--disable-gpu--disable-3d-apis--disable-extensions--renderer-process-limit2多代理沙箱配置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, processgroup:fs→ read, write, edit, apply_patchgroup:sessions→ sessions_list, sessions_history, sessions_send…group:memory→ memory_search, memory_getgroup:ui→ browser, canvasgroup:automation→ cron, gatewaygroup:messaging→ message调试命令查看沙箱配置openclaw sandbox explain openclaw sandbox explain--sessionagent:main:main openclaw sandbox explain--agentwork openclaw sandbox explain--json这会显示有效的沙箱模式/作用域/工作区访问当前会话是否沙箱化有效的沙箱工具 allow/denyelevated 门控和修复配置键路径列出沙箱容器openclaw sandbox list openclaw sandbox list--browser# 只看浏览器容器重建沙箱容器openclaw sandbox recreate--all# 重建所有openclaw sandbox recreate--sessionmain# 特定会话openclaw sandbox recreate--agentmybot# 特定 agentopenclaw sandbox recreate--browser# 只重建浏览器提示修改 Docker 镜像或配置后需要重建容器才能生效。常见问题解决“Tool X blocked by sandbox tool policy”修复方法禁用沙箱agents.defaults.sandbox.modeoff或者在沙箱中允许该工具从tools.sandbox.tools.deny中移除或添加到tools.sandbox.tools.allow“I thought this was main, why is it sandboxed?”在non-main模式下群组/频道的 key 不是 main。使用主会话 key 或切换到off模式。总结沙箱集成是 OpenClaw 安全架构的重要组成部分✅隔离执行将 AI 工具限制在 Docker 容器中✅可配置灵活的模式、作用域、工作区访问控制✅多代理支持不同 agent 不同安全策略✅浏览器隔离可选的沙箱浏览器✅工具策略细粒度的工具控制记住沙箱不是完美的安全边界但它能显著限制文件系统和进程访问防止 AI “犯傻” 时造成太大损失。相关文档Sandboxing 官方文档Sandbox vs Tool Policy vs ElevatedMulti-Agent Sandbox ToolsSandbox CLI小学子讲技术下期再见
