[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Sandbox, Tool Execution

Tool Sandbox

一句话定义

Tool Sandbox 是为高风险工具提供隔离执行环境的机制。执行用户提供的代码、读写文件、运行 Shell 命令时，这些操作应该在沙箱中执行。

角色边界

Sandbox 是通用隔离原语；本页只讨论 工具执行场景的策略化应用：哪些工具必须隔离、每类工具开放什么能力、怎样把最小权限与资源限制落到执行器。不要在这里重复维护容器、gVisor、Firecracker 等通用沙箱机制的完整说明。

核心原理

工具能力与隔离关注点（示例）

工具	风险	沙箱需求
execute_code	不可信代码	隔离执行与资源限额
read_file	路径遍历、数据泄露	路径和数据访问约束
write_file	文件覆盖	限定可写范围、权限与版本
run_shell	任意命令能力	隔离执行与能力限制
call_api	SSRF、数据泄露	出口和目标约束

策略如何落到执行器

配置表达的是意图，必须由实际后端实现和验证。工具层至少传递允许的路径/挂载、网络目的地、凭证范围、CPU/内存/进程数、输出量和截止时间。

例如 execute_code 可使用只读根文件系统、无网络、受限临时目录和资源配额；这些限制需分别配置到后端。Docker image、read_only 和 timeout 放在普通 Python 字典里，不会自动产生隔离；运行时必须把支持的字段映射到容器或 worker API，拒绝无法落实的要求。

chroot 只改变路径视图，不能独立作为不可信代码的安全沙箱。文件工具还要处理路径遍历、符号链接与检查后替换；call_api 需要出口、重定向和敏感数据控制，不能仅把“网络可选”当安全结论。

常见坑

1. 不做沙箱: 代码执行直接在宿主系统
2. 沙箱配置太松: 网络没隔离、资源没限制
3. 沙箱启动太慢: 每次都创建新容器

学习检查

1. 为什么同一个 Sandbox 后端仍需要按工具配置不同策略？
2. read_file、write_file、run_shell 的最小权限边界有什么不同？
3. Tool Sandbox 与 Tool Runtime 的职责边界是什么？
4. 哪些风险需要靠 Sandbox 解决，哪些仍需要参数校验与审批？

参考资料

• Sandbox
• Tool Executor