一、介绍

隔离的受控执行环境，把不可信 / 高风险的代码、命令、工具关在一个 “虚拟盒子” 里运行，和宿主机彻底隔离，防止破坏系统、泄露数据或横向扩散。
实现方式：通过虚拟化或容器化技术，将代码的运行环境与主系统严格隔离。

二、沙箱Scope（粒度范围）

由 agents.defaults.sandbox.scope 控制：
agent（默认）：每个 Agent 一个独立容器（隔离最好）
session：每个会话一个容器（中等隔离）
shared：所有 Agent / 会话共享一个容器（性能最好，隔离最弱）

三、沙箱生命周期（从创建到销毁）

Agent 启动 / 会话创建 → 触发沙箱初始化
容器创建：拉取 openclaw/runtime 镜像，启动容器
挂载目录：把宿主机工作区映射到容器 /workspace
工具执行：exec/read/write 等在容器内运行
结果返回：工具输出传回 Gateway，容器保持（复用）
销毁（可选）：会话结束 / 超时 → 容器删除，数据清零

四、五大隔离维度（核心安全能力）

1. 文件系统隔离（最关键）
   虚拟根目录：沙箱内看到的 / 是容器独立文件系统，看不到宿主机真实目录
   只读 + 按需挂载：默认只读；仅显式挂载路径（如 /workspace）可读写
   自动清理：容器销毁时，所有写入数据一键删除，不留痕迹
2. 进程隔离
   沙箱内进程有独立 PID 命名空间，看不到宿主机进程
   无法 kill 宿主机进程、无法注入代码到宿主机程序
3. 网络隔离（默认无外网）
   默认 none 网络：容器内无法访问外网，防止恶意 C2 通信、数据外泄
   白名单放行：仅允许指定域名 / 端口（如 GitHub、内部 API）
4. 资源限制（防耗尽）
   CPU：限制核心数 / 使用率（如 1 核、50%）
   内存：最大内存（如 2GB），超限 OOM 杀死
   磁盘：读写配额，防止塞满硬盘
5. 权限隔离（最小权限原则）

五、优缺点总结

✅ 优点
大幅降风险：模型失控也碰不到宿主机
默认安全：开箱即用，无需复杂配置
灵活可控：粒度 / 模式 / 权限可按需调
性能够用：容器启动快（秒级），资源占用低
开源透明：Docker 镜像开源，可审计、可自建
❌ 缺点
不是绝对安全：容器逃逸理论上可能（需高权限 + 漏洞）
有性能开销：比直接宿主机慢 5%~20%
网络限制麻烦：需要外网时要手动加白名单
Windows 隔离较弱：Windows 上依赖目录限制，不如 Linux Namespace 强

六、沙箱的核心种类（按隔离技术划分）

1. 容器型沙箱（最主流，OpenClaw 用的就是这类）
   原理：基于 Linux Namespace + Cgroups，用 Docker/containerd 等创建独立文件系统、进程、网络、资源限制。
   特点：轻量、启动快（秒级）、隔离强、生态成熟。
   代表：Docker、Podman、K8s、OpenClaw 内置沙箱、Kuasar、gVisor。
2. 微虚拟机（MicroVM）沙箱（隔离最强）
   原理：轻量 Hypervisor + 极简 Guest OS，硬件级虚拟化隔离，防逃逸能力最强。
   特点：安全最高、启动较慢（秒～10 秒）、资源开销中等。
   代表：Kata Containers、Firecracker、QEMU（精简版）、OpenClaw 可选 MicroVM。
3. 用户态 / 进程级沙箱（轻量，开发常用）
   原理：系统调用拦截、文件 / 目录权限限制，无独立内核。
   特点：极快（毫秒）、开销小、隔离较弱（防误操作，难防逃逸）。
   代表：Firejail、AppArmor、Seccomp、Linux Namespace（无容器）、Claude Code 内置沙箱。
4. Wasm 沙箱（新兴，AI 轻量执行）
   原理：代码编译为 WebAssembly，在独立 Wasm 运行时执行，内存安全、无系统调用权限。
   特点：启动毫秒级、资源极低、跨平台、隔离极强；但生态有限、不支持系统级操作。
   代表：Wasmtime、WasmEdge、Pyodide、Modal（部分场景）。
5. 云沙箱服务（托管，免运维）
   原理：第三方提供云端隔离环境，通过 API 调用执行代码 / 命令。
   特点：零运维、弹性扩缩、天然隔离；成本高、数据过外网、延迟不确定。
   代表：Modal、Replit、AWS Lambda、Google Cloud Functions、Azure Functions、GitHub Codespaces。
6. 安全分析沙箱（恶意软件 / 文件检测）
   原理：全系统模拟 / VM，动态分析样本行为（病毒、木马、恶意文档）。
   特点：隔离极强、深度行为分析、慢；用于安全厂商 / 企业威胁检测。
   代表：Cuckoo Sandbox、FireEye、奇安信、深信服、启明星辰。
7. 浏览器沙箱（网页隔离）
   原理：浏览器内核内隔离标签页 / 插件，限制脚本权限。
   代表：Chrome Sandbox、Firefox Sandbox、Edge Sandbox。

七、openswe项目沙箱 - 详情

该项目采用可插拔的云沙箱架构，为 AI 编码智能体提供隔离的执行环境。

支持的沙箱提供商（5种）

提供商	状态	实现文件	优点	缺点
LangSmith（默认）	26.03上线	agent/integrations/langsmith.py	功能全面、健康检查机制
Modal	2022生产	agent/integrations/modal.py	轻量简洁
Daytona	2025-03	agent/integrations/daytona.py
Runloop	2024-05	agent/integrations/runloop.py
Local （本地）	开发用	agent/integrations/local.py	无成本、延迟低，适合本地开发调试，数据安全性高	自己运维

关键特性：

1. 线程级隔离 - 每个线程维护独立的沙箱，跨消息复用
2. 自动重建 - 沙箱不可达时自动重新创建
3. GitHub 代理认证 - 通过 LangSmith proxy-config API 配置
4. 并行执行 - 多任务并行运行，各自在独立沙箱中
5. 路径解析 - 自动解析沙箱内的可写工作目录

八、openswe项目沙箱 - 代码

沙箱完整生命周期

1、沙箱类型选择

项目支持多种沙箱提供商，通过 SANDBOX_TYPE 环境变量选择：

# agent/utils/sandbox.py
SANDBOX_FACTORIES = {
    "langsmith": create_langsmith_sandbox,   # 默认，云端
    "daytona": create_daytona_sandbox,       # 云端
    "modal": create_modal_sandbox,           # 云端
    "runloop": create_runloop_sandbox,        # 云端
    "local": create_local_sandbox,           # 本地
}

2、沙箱创建流程

入口点 ： get_agent() 函数 ( server.py:190-257 )

3、沙箱的完整流程遵循以下核心原则：

1. 按需创建 ：只有当线程需要时才会创建沙箱
2. 缓存复用 ：同一线程复用同一个沙箱实例
3. 健康检查 ：使用前进行全面检查，确保资源充足
4. 自动重建 ：检测到不健康时自动创建新沙箱
5. 安全认证 ：通过代理机制安全地处理 GitHub 认证
6. 灵活切换 ：通过环境变量支持多种云端和本地沙箱

4、ModalSandbox类的属性和方法：

核心属性：

属性	类型	说明
id	str	沙箱唯一标识符
sandbox	modal.Sandbox	底层 Modal 沙箱实例

核心方法
根据 SandboxBackendProtocol 接口定义， ModalSandbox 提供以下方法：
shell命令执行、文件操作、目录操作

方法	用途	示例
execute(command)	执行 shell 命令	sandbox.execute(“git clone ”)
read_file(file_path, offset=0, limit=100)	读取文件内容	sandbox.read_file(“/app/main.py”)
write_file(file_path, content)	写入文件	sandbox.write_file(“/app/main.py”, “code”)
edit_file(file_path, old_string, new_string)	编辑文件	sandbox.edit_file(“/app/main.py”, “old”, “new”)
ls(path)	列出目录内容	sandbox.ls(“/app”)
glob(pattern)	查找匹配文件	sandbox.glob(“**/*.py”)

5、代码提交流程

是一个 自动化的一站式过程 ：

1. Agent 调用 commit_and_open_pr 工具
2. 工具通过 sandbox_backend.execute 在沙箱内执行 git 命令
3. GitHub 认证通过沙箱代理自动处理
4. 最后通过 GitHub API 创建 Pull Request

整个过程无需人工干预，完全由 Agent 自动完成。