Sandbox
Gemini CLI sandbox 的用途：隔离工具执行、降低不可信代码风险、Docker sandbox 和 --sandbox 使用边界。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Sandbox | 沙箱 | 限制 Agent 技术上能做什么。 |
| 模式 | mode | 不同的沙箱隔离级别。 |
| 平台差异 | platform | 各系统沙箱实现差异。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你为 Gemini CLI 任务选对沙箱模式、守住执行边界。
你是 Gemini CLI 沙箱配置顾问。
【角色】
Gemini CLI 沙箱配置顾问，按最小够用、安全合规优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 任务性质和环境：___
- 操作系统 / 平台：___
- 是否涉及联网 / 写操作：___
- 风险容忍度：___
- 经验水平：___
【工作流程】
1. 按任务选沙箱模式
2. 说明各模式的边界
3. 单独判断网络访问
4. 提示平台差异
5. 给配置和验证
【输出规范】
▌一、推荐沙箱模式
▌二、模式边界
▌三、网络访问判断
▌四、平台差异 + 验证
【硬约束】
- 默认最小权限，能只读不写
- 网络单独判断，默认关
- 高风险动作配合审批
- 不要替我臆测情况或编造不存在的配置，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述Sandbox 用来隔离工具执行，尤其适合不可信代码、新项目、陌生仓库和可能有副作用的命令。
Sandbox 降低本机执行风险，但不能替你判断命令是否应该访问远端服务、账号、账单或生产数据。
gemini --sandbox也可以用短参数 -s，或者通过环境变量 GEMINI_SANDBOX 和 settings.json 固化配置。实际优先级是：命令行参数最高，其次是环境变量，最后是配置文件。
官方页面给出的环境变量形式包括 GEMINI_SANDBOX=true、docker、podman、sandbox-exec。settings.json 里则放在 tools.sandbox。教程里要把命令行临时启用和配置文件长期启用分开写。
适合场景
- 下载来的陌生代码。
- 需要跑未知脚本。
- 需要探索依赖和测试。
- 想降低文件系统副作用。
支持方式
官方文档把 sandbox 分成几类：
- macOS Seatbelt：macOS 内置，轻量，适合限制项目外写入。
- Docker / Podman：跨平台容器隔离，适合需要完整进程隔离的项目。
- Windows native sandbox：使用 Windows 权限机制，注意完整性级别可能持久化。
- gVisor / runsc：Linux 上更强隔离，适合高风险命令。
- LXC / LXD：实验能力，适合标准 Docker 不适配的完整系统容器。
macOS Seatbelt 常见 profile 包括 permissive-open、permissive-closed、permissive-proxied、restrictive-open、restrictive-closed，可用 SEATBELT_PROFILE 指定。默认 profile 不等于最严格 profile，真实项目要按风险选择。
选择方式时先看你的平台，再看风险级别。普通本地探索可以从默认 sandbox 开始；陌生仓库、未知脚本或供应链风险更高时，优先使用容器隔离。
| 风险场景 | 推荐控制 |
|---|---|
| 陌生仓库跑测试 | 开 sandbox，先只读扫描 |
| 需要安装依赖 | 容器 sandbox，确认网络和缓存 |
| 可能写项目外路径 | sandbox + policy 双重限制 |
| 涉及生产凭据 | 不注入 sandbox，单独人工确认 |
| 需要部署 / 删除远端资源 | sandbox 不足够，必须审批和回滚方案 |
使用前检查
- Docker 或 Podman 是否已启动。
- 当前目录是否就是要分析的项目根目录。
- sandbox 内是否能访问项目需要的依赖、测试命令和包管理器。
- 是否需要网络访问；如果需要，profile 或容器网络要允许。
- 是否会写到项目外路径；sandbox 可能阻断这类操作。
边界
Sandbox 降低风险，但不是万能保险。生产密钥、账单、部署、数据删除仍然需要人工确认。
不要在 sandbox 里注入生产密钥。sandbox 隔离的是执行环境，不是替你判断命令是否应该运行。涉及远程删除、部署、付款、发消息、改权限这类外部副作用时，必须单独确认。
验收方式
第一次启用 sandbox 后，不要直接跑复杂任务。先让 Gemini CLI 执行只读项目分析，再跑一个最小测试命令。确认文件写入、网络访问和依赖路径都符合预期后，再扩大任务范围。
如果需要 Docker sandbox，还要先确认镜像来源、网络策略和缓存目录。容器隔离能限制进程环境，但如果你把生产凭据作为环境变量注入进去，风险仍然存在。
常见排错
如果 sandbox 后测试失败，先判断失败是不是隔离导致的：依赖无法访问、网络被阻断、写入项目外路径失败、GUI 或浏览器无法启动、缓存目录不可写。不要为了让测试通过直接关闭 sandbox。
正确路径是先收窄任务，再调整 profile 或容器配置。只有确认失败与隔离无关，才回到代码和测试本身。
教程里要保留关闭 sandbox 的回退说明，但不能把关闭当成默认修复，也不能把它当成安全策略或上线方案。上线前必须复测。
接下来去哪
Policy engine
sandbox 管执行环境，policy 管工具能不能执行。
Shell 工具
回看 shell 命令、后台进程和失败处理边界。
Trusted folders
sandbox 前还要判断 workspace 是否可信。