Gemini CLI 配置（v1 旧格式）

弃用说明：本文描述的 settings.json v1 格式已被弃用。

• 新格式将在 2025 年 9 月 10 日 起作为稳定版的一部分提供支持。
• 从 2025 年 9 月 17 日 起，CLI 会自动尝试将旧格式迁移为新格式。

若需了解推荐的最新配置格式，请参阅当前配置文档。

尽管 v1 格式已进入维护阶段，以下内容仍可帮助你理解旧版配置系统的行为及参数。

配置层级

配置按以下优先级依次覆盖（序号越大优先级越高）：

1. 应用内置默认值。
2. 系统默认文件（system-defaults.json）。
3. 用户设置文件（~/.gemini/settings.json）。
4. 项目设置文件（<project>/.gemini/settings.json）。
5. 系统覆盖文件（settings.json）。
6. 环境变量（包含 .env 自动加载的变量）。
7. 命令行参数。

设置文件位置与作用域

以上路径可通过 GEMINI_CLI_SYSTEM_DEFAULTS_PATH 与 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量重定向。

在 settings.json 中可使用 $VAR 或 ${VAR} 引用环境变量（例如："apiKey": "$MY_API_TOKEN"）。

.gemini 目录

项目根目录下的 .gemini 可包含：

• 项目配置 settings.json
• 自定义沙箱文件（如 sandbox.Dockerfile、.sb 文件）
• 自定义命令、记忆文件等

主要配置项速览（v1）

下列为常见配置项摘要，参数结构与默认值与旧版 CLI 行为一致：

• contextFileName：指定上下文文件名称，可为字符串或字符串数组，默认 "GEMINI.md"。
• bugCommand.urlTemplate：重定向 /bug 命令到自定义工单系统，支持 {title}、{info} 占位符。
• fileFiltering：控制 @ 命令及文件发现行为，例如 respectGitIgnore、enableRecursiveFileSearch。
• folderTrust：受信任目录相关设置，详见Trusted Folders。
• memory：上下文查找行为，比如 memoryDiscoveryMaxDirs、loadProjectContexts。
• tools：配置工具可用性与沙箱策略，包含 core 允许列表、MCP 设置、sandbox 模式等。
• telemetry：遥测上报目标（local/gcp）、是否记录 Prompt (logPrompts)、OTLP Endpoint 等。
• usageStatisticsEnabled：是否参与匿名使用统计（默认 true）。
• security.folderTrust.enabled：同 Trusted Folders。
• ui.theme / ui.customThemes：主题及自定义主题，详见主题文档。
• approvals / approvalMode：工具执行审批策略，如 auto_edit、yolo。
• sandbox.*：macOS seatbelt 配置、自定义 Docker 沙箱构建等。
• mcpServers：声明 MCP server 的启动命令、环境变量、超时时间等。
• env：为工具或 CLI 注入的环境变量，可用于引用外部凭据。

由于 v1 格式结构较为庞大，若需完整字段说明，请参考旧版源码或历史文档。升级到 v2 后，配置结构将显著精简，并提供更完善的校验与提示。

环境变量与 .env

CLI 会按以下顺序查找 .env：当前目录向上逐级直至根目录；若未找到，则尝试 ~/.gemini/.env、~/.env。仅加载首个命中的文件。

沙箱

CLI 支持通过沙箱执行潜在危险操作：

• 可用 -s/--sandbox、环境变量 GEMINI_SANDBOX、或在配置中设置 "tools": {"sandbox": true} 启用。
• 默认使用预构建的 gemini-cli-sandbox Docker 镜像。
• 项目可在 .gemini/sandbox.Dockerfile 中定义自定义镜像，运行时设置 BUILD_SANDBOX=1 构建。
• macOS 可使用 Seatbelt profiles（例如 permissive-open、restrictive-closed 等）。

详细说明见沙箱文档。

使用统计

默认会收集匿名统计信息（工具调用、请求耗时、配置状态等），不记录个人信息、Prompt 内容或文件内容。

可在任意层级的 settings.json 中设置：

{
  "usageStatisticsEnabled": false
}

以退订数据收集。

提示：建议尽快迁移至 v2 配置格式，以获得更好的结构化配置、自动补全与验证支持。安装新版本后，CLI 会在检测到旧格式时提示并引导迁移。