Gemini CLI 中的沙盒机制
本文档提供了 Gemini CLI 中沙盒机制的指南，包括先决条件、快速入门和配置。
先决条件
在使用沙盒机制之前，您需要安装并设置 Gemini CLI：
bash
npm install -g @google/gemini-cli要验证安装是否成功
bash
gemini --version沙盒机制概述
沙盒机制将潜在的危险操作（例如 shell 命令或文件修改）与您的主机系统隔离，在 AI 操作和您的环境之间提供安全屏障。
沙盒机制的优势包括：
- 安全性: 防止意外的系统损坏或数据丢失。
- 隔离性: 将文件系统访问限制在项目目录内。
- 一致性: 确保不同系统之间的可复现环境。
- 安全性: 降低处理不受信任的代码或实验性命令时的风险。
沙盒机制方法
您理想的沙盒机制方法可能因您的平台和首选容器解决方案而异。
1. macOS Seatbelt (仅限 macOS)
使用 sandbox-exec 进行轻量级、内置的沙盒机制。
默认配置文件: permissive-open - 限制写入项目目录之外的区域，但允许大多数其他操作。
2. 基于容器 (Docker/Podman)
跨平台的沙盒机制，具有完整的进程隔离。
注意: 需要在本地构建沙盒镜像或使用您组织注册表中已发布的镜像。
快速入门
bash
# 使用命令标志启用沙盒机制
gemini -s -p "分析代码结构"
# 使用环境变量
export GEMINI_SANDBOX=true
gemini -p "运行测试套件"
# 在 settings.json 中配置
{
"tools": {
"sandbox": "docker"
}
}配置
启用沙盒机制（按优先级顺序）
- 命令标志:
-s或--sandbox - 环境变量:
GEMINI_SANDBOX=true|docker|podman|sandbox-exec - 设置文件: 在
settings.json文件的tools对象中设置"sandbox": true（例如{"tools": {"sandbox": true}}）。
macOS Seatbelt 配置文件
内置配置文件（通过 SEATBELT_PROFILE 环境变量设置）：
permissive-open(默认): 写入限制，网络允许permissive-closed: 写入限制，无网络permissive-proxied: 写入限制，通过代理访问网络restrictive-open: 严格限制，网络允许restrictive-closed: 最大限制
自定义沙盒标志
对于基于容器的沙盒机制，您可以使用 SANDBOX_FLAGS 环境变量将自定义标志注入 docker 或 podman 命令。这对于高级配置非常有用，例如为特定用例禁用安全功能。
示例 (Podman):
要为卷挂载禁用 SELinux 标签，您可以设置以下内容：
bash
export SANDBOX_FLAGS="--security-opt label=disable"可以提供多个标志，用空格分隔：
bash
export SANDBOX_FLAGS="--flag1 --flag2=value"Linux UID/GID 处理
沙盒会自动处理 Linux 上的用户权限。使用以下命令覆盖这些权限：
bash
export SANDBOX_SET_UID_GID=true # 强制使用主机 UID/GID
export SANDBOX_SET_UID_GID=false # 禁用 UID/GID 映射故障排除
常见问题
"Operation not permitted" (操作不允许)
- 操作需要访问沙盒外部。
- 尝试更宽松的配置文件或添加挂载点。
命令丢失
- 添加到自定义 Dockerfile 中。
- 通过
sandbox.bashrc安装。
网络问题
- 检查沙盒配置文件是否允许网络访问。
- 验证代理配置。
调试模式
bash
DEBUG=1 gemini -s -p "调试命令"注意: 如果您的项目 .env 文件中有 DEBUG=true，由于自动排除，它不会影响 gemini-cli。请使用 .gemini/.env 文件来设置 gemini-cli 特定的调试设置。
检查沙盒
bash
# 检查环境变量
gemini -s -p "运行 shell 命令: env | grep SANDBOX"
# 列出挂载点
gemini -s -p "运行 shell 命令: mount | grep workspace"安全注意事项
- 沙盒机制可以减少但不能完全消除所有风险。
- 使用允许您工作的最严格的配置文件。
- 容器开销在首次构建后很小。
- GUI 应用程序可能无法在沙盒中运行。