沙盒功能

目录

概述

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

前提条件： 在使用沙盒之前，您需要安装和设置 Gemini CLI：

# 使用 npm 安装 gemini-cli
npm install -g @google/gemini-cli

# 验证安装
gemini --version

功能优势

🛡️ 安全性

防止意外系统损坏或数据丢失

🔒 隔离

限制文件系统访问仅限于项目目录

🔄 一致性

确保跨不同系统的可重现环境

✨ 安全性

降低处理不可信代码或实验命令的风险

沙盒方法

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

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 "调试命令"

检查沙盒

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

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

安全注意事项

重要提醒：

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