# 沙箱扩展审批与故障定位

> 判断权限拒绝、镜像缺依赖或网络限制，并审阅单次扩展请求。

- 网址：https://funcoding.ai/agents/gemini-cli/configuration/sandbox-troubleshooting/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：Sandboxing](https://geminicli.com/docs/cli/sandbox)、[Gemini CLI 官方文档：Configuration reference](https://geminicli.com/docs/reference/configuration)、[官方设置 Schema（固定 revision）](https://github.com/google-gemini/gemini-cli/blob/ef59c532f07fbb3a58dd68bac024ae217e9c73ce/schemas/settings.schema.json)

---
沙箱失败可能来自访问范围、容器依赖、网络或宿主文件权限。先定位拒绝发生在哪一层，再决定是否扩大权限。

## 单次扩展请求

命令被沙箱拒绝，或 CLI 预先判断命令需要额外权限时，会显示 Sandbox Expansion Request，说明额外目录或网络访问。批准后以扩展权限执行该次命令；不要将一次批准理解成对任意后续命令的授权。

## 工具级隔离

当前配置参考和固定 Schema 中，`security.toolSandboxing` 默认 false，修改后需重启。它决定隔离单次工具还是采用其他执行方式，和 `tools.sandbox` 的整个进程沙箱配置应分别检查。沙箱专页的“如何关闭”段落不代表它在所有版本默认开启。

## 常见症状

| 症状 | 核对项 |
| --- | --- |
| Operation not permitted / Permission denied | 目标路径是否在允许范围、profile、挂载权限 |
| 命令不存在 | 镜像内是否安装该命令，是否需自定义预构建镜像 |
| 网络连接失败 | profile 是否允许网络，代理是否配置正确 |
| 文件归属异常 | Linux UID/GID 映射与宿主权限 |
| Windows 会话后权限仍不同 | 原生沙箱保留的 Low 完整性级别 |

不要把每个失败都改为全局无约束运行。确实缺少路径时，优先只补任务需要的挂载；镜像依赖缺失应修镜像。

## 调试日志

```bash
DEBUG=1 gemini -s -p "debug command"
```

项目普通 `.env` 的 DEBUG 默认被排除，专用 `.gemini/.env` 不受该排除规则影响。日志用于判断配置和拒绝原因；仅看到变量已设置不证明实际 provider 启动成功。

## 版本与平台检查

runsc 需显式选择，LXC 必须已有运行中的容器，BUILD_SANDBOX 自动构建仅适用于源码运行。不同安装方式出现差异时先核对这些前提，详见[提供方](https://funcoding.ai/agents/gemini-cli/configuration/sandbox-providers/)与[容器配置](https://funcoding.ai/agents/gemini-cli/configuration/sandbox-containers/)。