文件夹信任与沙箱

受信任的文件夹

「受信任的文件夹」是一项安全设置，让你控制哪些项目可以使用 Gemini CLI 的全部能力。它在 CLI 加载某个文件夹里任何项目特定配置之前，先要求你批准该文件夹，从而防止潜在的恶意代码运行。该功能默认关闭，需要先在用户 settings.json 里启用：

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

启用后，第一次从某个文件夹运行 Gemini CLI 时会自动出现对话框让你选择：Trust folder（对当前文件夹授予完全信任）、Trust parent folder（对父目录授予信任，其所有子目录自动受信，适合把所有安全项目放在一起时）、Don't trust（把文件夹标记为不受信任，CLI 在受限的「安全模式」下运行）。你的选择保存在中心文件 ~/.gemini/trustedFolders.json，所以每个文件夹只会问一次。你选择之前，Gemini CLI 先做一次发现阶段，扫描文件夹里的潜在配置并显示在信任对话框里帮你做决定：命令（自定义 .toml 命令定义）、MCP 服务器、hooks、skills、设置覆盖。对话框还会突出显示需要注意的关键信息：安全警告（如自动批准某些工具或禁用安全沙箱的危险设置）和发现错误（如格式错误的 settings.json）。

不受信任的工作区会禁用：忽略工作区设置（不加载项目的 .gemini/settings.json）；忽略环境变量（不加载项目里的任何 .env 文件）；限制扩展管理（不能安装、更新或卸载扩展）；禁用工具自动接受（即使全局启用了自动接受，运行任何工具前也总会提示你）；禁用自动记忆加载；MCP 服务器不连接；不加载自定义命令（包括项目特定和全局用户命令）。授予文件夹信任就解锁了该工作区的全部功能。

无头和自动化环境：在无法交互提示的无头环境（如 CI/CD 流水线）里，信任对话框无法显示；文件夹不受信任且启用了文件夹信任功能时，CLI 会抛出 FatalUntrustedWorkspaceError 并退出。要在这些环境里继续，可以绕过信任检查：用命令行标志 --skip-trust，或设置环境变量 GEMINI_CLI_TRUST_WORKSPACE=true；这些方法会在会话期间信任当前工作区而不提示。默认信任设置保存在 ~/.gemini/trustedFolders.json，可以用 GEMINI_CLI_TRUSTED_FOLDERS_PATH 环境变量指定其他绝对路径。要更改当前文件夹的信任，在 CLI 里运行 /permissions 命令，会打开同样的交互对话框。

沙箱

沙箱把潜在危险的操作（如 shell 命令或文件修改）与你的宿主系统隔离，在 AI 操作和你的环境之间提供安全屏障。好处：安全（防止意外的系统损坏或数据丢失）、隔离（把文件系统访问限制在项目目录）、一致（在不同系统间保证可重现的环境）、安全感（处理不受信任的代码或实验性命令时降低风险）。

启用

可以用命令标志、环境变量或配置文件启用沙箱（按优先顺序）：

1. 命令标志：-s 或 --sandbox，如 gemini -s -p "analyze the code structure"
2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc，如 export GEMINI_SANDBOX=true
3. 设置文件：settings.json 的 tools 对象里的 "sandbox": true（如 {"tools": {"sandbox": true}}），也可以写具体方式：{"tools": {"sandbox": "docker"}}

沙箱方式

1. macOS Seatbelt（仅 macOS）：用 sandbox-exec 的轻量内置沙箱。默认配置 permissive-open：默认拒绝操作，把写入限制在项目目录，同时允许广泛的文件读取和网络访问。内置配置（用 SEATBELT_PROFILE 环境变量设置）：permissive-open（默认，限制写入、允许网络）、permissive-proxied（限制写入、网络经代理）、restrictive-open（严格限制、允许网络）、restrictive-proxied、strict-open（限制读写、允许网络）、strict-proxied。

2. 基于容器（Docker/Podman）：用容器技术的跨平台沙箱，完全的进程隔离，默认用 ghcr.io/google/gemini-cli:latest 镜像。需要安装并运行 Docker 或 Podman。沙箱容器里，你当前的工作目录以与宿主机完全相同的绝对路径挂载，让 AI 能无缝读写你的项目文件同时与系统其余部分隔离。快速设置：

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

自定义沙箱镜像：项目需要特定依赖时，可以指定自定义镜像名（用 settings.json 里 tools.sandbox 的对象形式 {"command": "docker", "image": "..."}，或设置 GEMINI_SANDBOX_IMAGE 环境变量），或让 Gemini CLI 自动构建：在项目根创建 .gemini/sandbox.Dockerfile，用设置了 BUILD_SANDBOX 环境变量的命令运行，如 BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build"（沙箱镜像需要有 bash 等标准 shell 工具）。

3. Windows 原生沙箱（仅 Windows）：用 icacls 命令给它需要写入的文件和目录设置「Low Mandatory Level」。这些完整性级别的更改在文件系统上是持久的，沙箱会话结束后，沙箱创建或修改的文件仍保留「Low」完整性级别；需要重置时用 icacls "C:\path\to\dir" /setintegritylevel Medium；沙箱管理器出于安全会自动跳过系统文件夹（如 C:\Windows）。

4. gVisor / runsc（仅 Linux）：可用的最强隔离：通过 gVisor 在用户空间内核里运行容器，拦截所有容器系统调用并由用 Go 编写的沙箱内核处理，在 AI 操作和宿主操作系统之间提供强安全屏障。需要 Linux、安装并运行 Docker、配置好 gVisor/runsc 运行时。

沙箱启用后出现「Operation not permitted」「Permission denied」等错误，说明 Gemini CLI 尝试了被沙箱配置限制的操作（如写到项目目录或系统临时目录之外），按沙箱配置文档调整。