---
title: "Sandbox"
description: "Gemini CLI sandbox 的用途：隔离工具执行、降低不可信代码风险、Docker sandbox 和 --sandbox 使用边界。"
verifiedAt: "2026-05-09"
---

Sandbox 用来隔离工具执行，尤其适合不可信代码、新项目、陌生仓库和可能有副作用的命令。

> [!WARNING]
> Sandbox 降低本机执行风险，但不能替你判断命令是否应该访问远端服务、账号、账单或生产数据。

```bash
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 的回退说明，但不能把关闭当成默认修复，也不能把它当成安全策略或上线方案。上线前必须复测。

## 接下来去哪

<Cards>
  <Card title="Policy engine" description="sandbox 管执行环境，policy 管工具能不能执行。" href="/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
  <Card title="Shell 工具" description="回看 shell 命令、后台进程和失败处理边界。" href="/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="Trusted folders" description="sandbox 前还要判断 workspace 是否可信。" href="/docs/gemini-cli/official/02-context-config/28-trusted-folders" />
</Cards>

## 官方来源

- [Gemini CLI sandboxing](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md)
- [Gemini CLI configuration reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md)
