跳转至

Gemini CLI 中的沙盒机制

本文档提供 Gemini CLI 中沙盒功能的使用指南，包括先决条件、快速入门和配置说明。

先决条件

使用沙盒功能前，您需要安装并设置 Gemini CLI：

# 使用 npm 安装 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 中配置
{
  "sandbox": "docker"
}

配置

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

  1. 命令标志：-s 或 --sandbox
  2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
  3. 配置文件：在 settings.json 中设置 "sandbox": true

macOS Seatbelt 安全配置文件

内置配置文件（通过 SEATBELT_PROFILE 环境变量设置）：

  • permissive-open（默认）：写入限制，允许网络访问
  • permissive-closed：写入限制，禁止网络访问
  • permissive-proxied：写入限制，通过代理访问网络
  • restrictive-open：严格限制，允许网络访问
  • restrictive-closed：最高级别限制

Linux UID/GID 处理机制

沙箱会自动处理 Linux 上的用户权限。可通过以下方式覆盖这些权限：

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

故障排除

常见问题

"操作不被允许"

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

命令缺失

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

网络问题

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

调试模式

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

检查沙箱环境

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


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

安全注意事项

  • 沙箱化能降低但无法消除所有风险
  • 使用能满足工作的最严格限制配置文件
  • 首次构建后容器开销极小
  • 图形界面应用可能在沙箱中无法运行

相关文档