概述
OpenClaw 的沙箱隔离环境是保障系统安全的关键组件。当 AI 代理执行工具操作时，沙箱确保这些操作不会影响宿主系统的安全和稳定。本文详细介绍沙箱的三大核心能力：工具路径约束、容器执行和浏览器桥接配置。
沙箱架构
由于 OpenClaw 直接嵌入 Pi 编码代理 SDK（而非以子进程方式调用），沙箱机制被深度集成到工具执行层。每个工具调用都会经过沙箱检查，在七阶段工具流水线的策略过滤阶段完成权限验证后，实际执行时还会受到沙箱的运行时约束。
工具路径约束
基本概念
路径约束（Path Constraints）限制了工具能够访问的文件系统范围。通过在配置文件中声明允许的路径前缀，你可以精确控制 AI 代理的文件操作边界。
配置方式
在 OpenClaw 的配置文件中，使用 sandbox.allowedPaths 字段声明允许访问的路径：
sandbox:
allowedPaths:
- /home/openclaw/workspace
- /tmp/openclaw
deniedPaths:
- /etc
- /var/log
- /home/openclaw/.ssh
maxFileSize: 10MB
maxDepth: 10
路径解析规则
沙箱在检查路径时会进行规范化处理：解析符号链接、消除 .. 路径遍历、统一路径分隔符。这意味着尝试通过 ../../etc/passwd 之类的路径来绕过约束是无效的。
临时文件处理
工具执行过程中产生的临时文件默认存放在 /tmp/openclaw/<session-id>/ 目录下。每个会话有独立的临时目录，会话结束后由沙箱自动清理。
容器执行
容器隔离模式
对于需要执行任意代码的场景（如代码执行技能），OpenClaw 支持将工具操作放入容器中执行。容器执行提供了比路径约束更强的隔离级别。
配置容器运行时
sandbox:
containerExec:
enabled: true
runtime: docker
image: openclaw/sandbox:latest
memoryLimit: 512m
cpuLimit: 1.0
networkMode: none
timeout: 30s
关键参数说明
- runtime：容器运行时，支持 Docker 和 Podman
- image：沙箱容器镜像，官方提供预构建镜像，包含常用编程语言运行时
- memoryLimit：内存上限，防止资源耗尽攻击
- cpuLimit：CPU 使用限制
- networkMode：网络模式，
none表示完全隔离网络，restricted允许有限的外部访问 - timeout：执行超时时间，超过后容器被强制终止
文件系统挂载
容器执行时，沙箱会将必要的文件以只读方式挂载到容器内部。工具产生的输出文件通过专用的输出目录映射回宿主系统。
sandbox:
containerExec:
mounts:
- source: /home/openclaw/workspace
target: /workspace
readonly: true
- source: /tmp/openclaw/output
target: /output
readonly: false
浏览器桥接
桥接机制
OpenClaw 的浏览器工具（browser tool）需要与真实的浏览器实例交互。沙箱通过浏览器桥接 URL 建立受控的通信通道，既允许 AI 代理操控浏览器，又防止浏览器操作逃逸出沙箱范围。
配置浏览器桥接
sandbox:
browserBridge:
enabled: true
bridgeUrl: "ws://localhost:9222"
allowedDomains:
- "*.example.com"
- "docs.openclaw.com"
blockedDomains:
- "*.internal.corp"
maxTabs: 3
maxPageLoadTime: 15s
screenshotFormat: png
screenshotQuality: 80
域名过滤
浏览器桥接支持域名白名单和黑名单。只有在允许列表中的域名才能被访问，这防止了 AI 代理通过浏览器访问内部网络资源或敏感服务。
桥接安全性
浏览器桥接使用 WebSocket 协议通信。连接建立时需要通过令牌验证，每个会话有独立的令牌。桥接层还会拦截危险操作，如下载可执行文件、访问 file:// 协议等。
沙箱监控
资源使用监控
沙箱运行时会持续监控资源使用情况：
- 文件系统操作次数和总数据量
- 容器的 CPU 和内存使用
- 浏览器桥接的网络流量
- 工具调用频率
告警配置
当资源使用接近限制时，系统会触发告警。你可以在配置中设置告警阈值和通知方式。
故障排查
常见的沙箱相关问题：
- 路径访问被拒绝：检查
allowedPaths是否包含目标路径，注意符号链接的解析 - 容器启动失败：确认容器运行时已安装且镜像已拉取
- 浏览器桥接超时：检查浏览器实例是否正常运行，桥接 URL 是否正确
- 资源超限：调整
memoryLimit和cpuLimit参数
总结
OpenClaw 的沙箱机制通过路径约束、容器执行和浏览器桥接三层防护，在保证 AI 代理能力的同时确保了系统安全。合理配置这三个维度，可以在安全性和功能性之间取得最佳平衡。