沙箱扩展审批与故障定位
判断权限拒绝、镜像缺依赖或网络限制，并审阅单次扩展请求。
This page has not been translated into English yet. The original Chinese version is shown below.
沙箱失败可能来自访问范围、容器依赖、网络或宿主文件权限。先定位拒绝发生在哪一层，再决定是否扩大权限。
单次扩展请求
命令被沙箱拒绝，或 CLI 预先判断命令需要额外权限时，会显示 Sandbox Expansion Request，说明额外目录或网络访问。批准后以扩展权限执行该次命令；不要将一次批准理解成对任意后续命令的授权。
工具级隔离
当前配置参考和固定 Schema 中，security.toolSandboxing 默认 false，修改后需重启。它决定隔离单次工具还是采用其他执行方式，和 tools.sandbox 的整个进程沙箱配置应分别检查。沙箱专页的“如何关闭”段落不代表它在所有版本默认开启。
常见症状
| 症状 | 核对项 |
|---|---|
| Operation not permitted / Permission denied | 目标路径是否在允许范围、profile、挂载权限 |
| 命令不存在 | 镜像内是否安装该命令，是否需自定义预构建镜像 |
| 网络连接失败 | profile 是否允许网络，代理是否配置正确 |
| 文件归属异常 | Linux UID/GID 映射与宿主权限 |
| Windows 会话后权限仍不同 | 原生沙箱保留的 Low 完整性级别 |
不要把每个失败都改为全局无约束运行。确实缺少路径时，优先只补任务需要的挂载；镜像依赖缺失应修镜像。
调试日志
DEBUG=1 gemini -s -p "debug command"项目普通 .env 的 DEBUG 默认被排除，专用 .gemini/.env 不受该排除规则影响。日志用于判断配置和拒绝原因；仅看到变量已设置不证明实际 provider 启动成功。
版本与平台检查
runsc 需显式选择，LXC 必须已有运行中的容器，BUILD_SANDBOX 自动构建仅适用于源码运行。不同安装方式出现差异时先核对这些前提，详见提供方与容器配置。