Gemini CLI 支持多种沙箱方式保护宿主系统安全：macOS 内置 Seatbelt（轻量）、Docker/Podman 容器（跨平台）、Windows 原生沙箱、gVisor（最强隔离，仅 Linux）、LXC（完整系统容器）。用 gemini -s 快速启用，或通过 GEMINI_SANDBOX 环境变量/settings.json 持久化配置。

沙箱安全隔离

沙箱将 AI 执行的危险操作（Shell 命令、文件修改）与宿主系统隔离，防止意外损坏或数据丢失。

沙箱的好处

• 安全：防止系统意外损坏或数据丢失
• 隔离：将文件系统访问限制在项目目录内
• 一致性：在不同系统上保证可复现的环境
• 安全边界：降低运行不可信代码或实验性命令时的风险

五种沙箱方式

1. macOS Seatbelt（仅 macOS）

使用系统内置的 sandbox-exec，轻量、无需额外安装。

默认 Profile：permissive-open——限制项目目录外的写入，其他操作基本放行。

2. Docker/Podman 容器（跨平台，推荐）

完整的进程级隔离，需要预先安装 Docker 或 Podman。

启用时需要本地构建沙箱镜像，或使用组织 registry 中的预发布镜像。

# 使用 Docker 沙箱
GEMINI_SANDBOX=docker gemini -p "分析代码结构"

# 使用 Podman 沙箱
GEMINI_SANDBOX=podman gemini -p "运行测试套件"

3. Windows 原生沙箱（仅 Windows）

使用 icacls 命令将文件设为"低完整性级别"。

注意：完整性级别的修改是持久化的——即使沙箱会话结束，沙箱创建/修改的文件仍保持"低"完整性级别。如需重置：

icacls "C:\path\to\dir" /setintegritylevel Medium

4. gVisor / runsc（仅 Linux，最强隔离）

在用户态内核中运行容器，拦截所有系统调用，提供最强安全边界。

前提条件：

• Linux 系统
• 已安装并运行 Docker
• 已配置 gVisor/runsc 运行时

export GEMINI_SANDBOX=runsc
gemini -p "build the project"

5. LXC/LXD（仅 Linux，实验性）

运行完整 Linux 系统的容器（含 systemd、snapd），适合需要完整系统的工具（如 Snapcraft、Rockcraft）。

前提条件：LXC/LXD 已安装，容器已创建并启动（Gemini CLI 不会自动创建容器）。

# 初始化 LXD（仅首次）
lxd init --auto

# 创建并启动 Ubuntu 容器
lxc launch ubuntu:24.04 gemini-sandbox

# 启用 LXC 沙箱
export GEMINI_SANDBOX=lxc
gemini -p "构建项目"

工具级沙箱

工具级沙箱只隔离单个工具执行（如 shell_exec、write_file），而非隔离整个 Gemini CLI 进程。非工具任务（UI 渲染、配置加载）在本地环境正常运行。

如需禁用工具级沙箱，在 settings.json 中设置：

{
  "security": {
    "toolSandboxing": false
  }
}

修改此设置需要重启 Gemini CLI 才能生效。

沙箱扩展请求

当沙箱操作因权限不足失败（如需要访问受限路径或网络），或者 Gemini CLI 主动识别到命令需要额外权限（如 npm install）时，会弹出"沙箱扩展请求"对话框。

批准后，该命令以扩展权限执行，无需手动调整沙箱配置。

快速启用

# 命令标志（最简单）
gemini -s -p "分析代码结构"

# macOS/Linux 环境变量
export GEMINI_SANDBOX=true
gemini -p "运行测试套件"

Windows（PowerShell）：

$env:GEMINI_SANDBOX="true"
gemini -p "运行测试套件"

写入 settings.json（持久化）：

{
  "tools": {
    "sandbox": "docker"
  }
}

配置详情

启用优先级（从高到低）：

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

macOS Seatbelt Profile（通过 SEATBELT_PROFILE 环境变量设置）：

Profile	说明
permissive-open（默认）	限制写入，网络放行
permissive-proxied	限制写入，网络走代理
restrictive-open	严格限制，网络放行
restrictive-proxied	严格限制，网络走代理
strict-open	读写均限制，网络放行
strict-proxied	读写均限制，网络走代理

常见问题

Q: 沙箱会影响 Gemini CLI 的正常功能吗？

A: 工具级沙箱（默认）只隔离 AI 执行的工具操作，UI 渲染、配置加载等本地功能不受影响。但全进程沙箱（容器模式）可能导致某些命令不可用，需在 Dockerfile 中添加。

Q: 在沙箱中遇到"Operation not permitted"怎么办？

A: 操作需要访问沙箱外部。可以尝试切换到更宽松的 Profile（如 permissive-open），或为容器添加额外挂载点。调试时可运行 DEBUG=1 gemini -s -p "debug command" 获取详细日志。

Q: Docker 沙箱首次构建镜像会很慢吗？

A: 是的，首次需要构建沙箱镜像，耗时较长。之后的会话会复用已构建的镜像，开销极低。