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 "analyze the code structure"

# 使用环境变量
export GEMINI_SANDBOX=true
gemini -p "run the test suite"

# 在 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：最严格配置。

自定义沙箱参数

在使用 Docker / Podman 时，可通过 SANDBOX_FLAGS 环境变量向底层命令追加参数，适用于高级配置（例如暂时关闭安全特性）。

示例（Podman）：

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 "debug command"

如果某项目的 .env 中设置了 DEBUG=true，不会影响 gemini-cli（该变量会被自动排除）。如需针对 CLI 启用调试，请在 .gemini/.env 中配置。

查看沙箱信息

# 查看环境变量
gemini -s -p "run shell command: env | grep SANDBOX"

# 查看挂载情况
gemini -s -p "run shell command: mount | grep workspace"

安全提示

  • 沙箱能降低风险，但无法消除所有风险。
  • 在满足需求的前提下，尽量选择限制最严格的配置。
  • 首次构建容器沙箱后，后续开销很小。
  • GUI 程序可能无法在沙箱中正常运行。

相关文档