Gemini CLI 中的沙箱操作

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)

跨平台的沙箱，具有完全的进程隔离。

注意：需要本地构建沙箱镜像，或使用组织注册表中发布的镜像。

快速入门

# Enable sandboxing with command flag
gemini -s -p "analyze the code structure"

# Use environment variable
export GEMINI_SANDBOX=true
gemini -p "run the test suite"

# Configure in 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   # Force host UID/GID
export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping

故障排除

常见问题

“操作不允许”

• 操作需要访问沙箱外的内容。
• 尝试使用更宽松的配置文件或添加挂载点。

缺少命令

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

网络问题

• 检查沙箱配置文件是否允许网络。
• 核验代理配置。

调试模式

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

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

检查沙箱

# Check environment
gemini -s -p "run shell command: env | grep SANDBOX"

# List mounts
gemini -s -p "run shell command: mount | grep workspace"

安全说明

• 沙箱可以降低风险，但不会消除所有风险。
• 使用允许您工作的最严格配置文件。
• 容器在首次构建后开销最小。
• GUI应用程序在沙箱中可能无法工作。

相关文档

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