Gemini CLI 中的沙盒机制

本文档提供了 Gemini CLI 中沙盒机制的指南，包括先决条件、快速入门和配置。

先决条件

在使用沙盒机制之前，您需要安装并设置 Gemini CLI：

npm install -g @google/gemini-cli

要验证安装是否成功

gemini --version

沙盒机制概述

沙盒机制将潜在的危险操作（例如 shell 命令或文件修改）与您的主机系统隔离，在 AI 操作和您的环境之间提供安全屏障。

沙盒机制的优势包括：

• 安全性: 防止意外的系统损坏或数据丢失。
• 隔离性: 将文件系统访问限制在项目目录内。
• 一致性: 确保不同系统之间的可复现环境。
• 安全性: 降低处理不受信任的代码或实验性命令时的风险。

沙盒机制方法

您理想的沙盒机制方法可能因您的平台和首选容器解决方案而异。

1. macOS Seatbelt (仅限 macOS)

使用 sandbox-exec 进行轻量级、内置的沙盒机制。

默认配置文件: permissive-open - 限制写入项目目录之外的区域，但允许大多数其他操作。

2. 基于容器 (Docker/Podman)

跨平台的沙盒机制，具有完整的进程隔离。

注意: 需要在本地构建沙盒镜像或使用您组织注册表中已发布的镜像。

快速入门

# 使用命令标志启用沙盒机制
gemini -s -p "分析代码结构"

# 使用环境变量
export GEMINI_SANDBOX=true
gemini -p "运行测试套件"

# 在 settings.json 中配置
{
  "tools": {
    "sandbox": "docker"
  }
}

配置

启用沙盒机制（按优先级顺序）

1. 命令标志: -s 或 --sandbox
2. 环境变量: GEMINI_SANDBOX=true|docker|podman|sandbox-exec
3. 设置文件: 在 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 标签，您可以设置以下内容：

export SANDBOX_FLAGS="--security-opt label=disable"

可以提供多个标志，用空格分隔：

export SANDBOX_FLAGS="--flag1 --flag2=value"

Linux UID/GID 处理

沙盒会自动处理 Linux 上的用户权限。使用以下命令覆盖这些权限：

export SANDBOX_SET_UID_GID=true   # 强制使用主机 UID/GID
export SANDBOX_SET_UID_GID=false  # 禁用 UID/GID 映射

故障排除

常见问题

"Operation not permitted" (操作不允许)

• 操作需要访问沙盒外部。
• 尝试更宽松的配置文件或添加挂载点。

命令丢失

• 添加到自定义 Dockerfile 中。
• 通过 sandbox.bashrc 安装。

网络问题

• 检查沙盒配置文件是否允许网络访问。
• 验证代理配置。

调试模式

DEBUG=1 gemini -s -p "调试命令"

注意: 如果您的项目 .env 文件中有 DEBUG=true，由于自动排除，它不会影响 gemini-cli。请使用 .gemini/.env 文件来设置 gemini-cli 特定的调试设置。

检查沙盒

# 检查环境变量
gemini -s -p "运行 shell 命令: env | grep SANDBOX"

# 列出挂载点
gemini -s -p "运行 shell 命令: mount | grep workspace"

安全注意事项

• 沙盒机制可以减少但不能完全消除所有风险。
• 使用允许您工作的最严格的配置文件。
• 容器开销在首次构建后很小。
• GUI 应用程序可能无法在沙盒中运行。

相关文档

• 配置: 完整的配置选项。
• 命令: 可用命令。
• 故障排除: 一般故障排除。