Gemini CLI 配置

格式更新（2025-09-17）：settings.json 已迁移到新的分组结构。

  • 自 2025-09-10 起，稳定版将全面支持新格式。
  • 自 2025-09-17 起，CLI 会尝试自动将旧格式迁移为新格式。

如需回顾旧格式，请参阅旧版配置文档。

Gemini CLI 支持多种配置方式：环境变量、命令行参数以及设置文件。本页介绍新格式的结构与常用选项。

配置优先级

与旧版本一致，配置应用顺序如下（后者覆盖前者）：

  1. 应用默认值；
  2. 系统默认文件；
  3. 用户设置文件；
  4. 项目设置文件；
  5. 系统覆盖文件；
  6. 环境变量（含 .env）；
  7. 命令行参数。

设置文件位置

  • 系统默认：/etc/gemini-cli/system-defaults.json（Windows 对应 C:\ProgramData\gemini-cli\system-defaults.json，macOS 在 /Library/Application Support/GeminiCli/）。可用 GEMINI_CLI_SYSTEM_DEFAULTS_PATH 覆盖路径。
  • 用户设置：~/.gemini/settings.json
  • 项目设置：<project>/.gemini/settings.json
  • 系统覆盖：/etc/gemini-cli/settings.json（Windows C:\ProgramData\gemini-cli\settings.json）。可用 GEMINI_CLI_SYSTEM_SETTINGS_PATH 重定向。

在 settings.json 中可使用 $VAR / ${VAR} 引用环境变量。

.gemini 目录

除 settings.json 外，.gemini 目录还可存放自定义命令、GEMINI.md、沙箱文件等。

配置分类概览

新格式将所有设置分组到顶级类别对象中，以下为常见类别及字段示例：

general

  • preferredEditor：打开外部编辑器时的默认命令。
  • vimMode：是否启用 Vim 按键模式。
  • disableAutoUpdate / disableUpdateNag：控制自动更新及提示。
  • checkpointing.enabled：启用会话 checkpoint 功能。

output

  • format：输出格式，text 或 json。

ui

  • theme：主题名称或主题文件路径。
  • customThemes：自定义主题定义（结构与主题文档一致）。
  • showStatusInTitle、showModelInFooter 等 UI 显示选项。

context

  • fileName：允许的上下文文件名称列表（默认包含 GEMINI.md）。
  • discoveryMaxDirs：搜索子目录数量上限（默认 200）。
  • includeDirectories：额外包含上下文的目录。

memory

  • 控制 /memory 相关行为，如自动刷新、展示顺序等。

approvals

  • mode：工具审批模式，manual、auto_edit、yolo 等。
  • autoAcceptTools：自动批准的工具列表。

tools

  • core.allow / core.deny：原生工具允许/拒绝列表。
  • sandbox：true/docker/podman/sandbox-exec。
  • mcp.allowed：允许的 MCP server 列表。

mcpServers

  • 声明各 MCP server 的 command、args、env、timeout 等。

telemetry

  • enabled：是否启用遥测。
  • target：local/gcp。
  • otlpEndpoint、otlpProtocol、outfile 等参数参见遥测文档。

privacy

  • usageStatisticsEnabled：是否参与匿名使用统计。
  • logPrompts（在 telemetry 中也可控制）：是否将 Prompt 记录在遥测日志。

security

  • folderTrust.enabled：启用 Trusted Folders。
  • 其他安全相关选项。

env

  • 允许在配置中显式设置环境变量，如 GEMINI_API_KEY、代理设置等。

integrations

  • IDE 集成、扩展相关配置（如 ideContext）。

每个类别下还有更多细粒度字段，新格式在 settings.schema.json 中提供完整定义，并在 CLI 中附带校验提示。可通过运行 gemini --config-schema 输出最新 Schema。

Sandbox 配置

  • 通过 tools.sandbox、命令行 -s 或环境变量 GEMINI_SANDBOX 开启。
  • 默认使用预构建 gemini-cli-sandbox Docker 镜像。
  • 在项目 .gemini/sandbox.Dockerfile 中编写自定义镜像，运行前设置 BUILD_SANDBOX=1 自动构建。
  • macOS 支持 seatbelt profile，可在 sandbox.macos.profile 指定。

详情参见沙箱文档。

统计与遥测

  • 匿名使用统计（privacy.usageStatisticsEnabled）默认开启，可随时关闭。
  • 遥测配置详见遥测文档，支持本地文件、OTLP Collector 以及 Google Cloud。

.env 自动加载逻辑

CLI 会自当前目录向上查找 .env，若未找到则尝试 ~/.gemini/.env、~/.env。仅加载首个命中的文件。

/memory 与上下文文件

  • context.fileName 指定的文件会按“全局 → 项目根及祖先 → 当前目录以下子目录”顺序加载。
  • /memory show 可查看拼接后的上下文，页脚会显示加载数量。
  • 支持通过 @path/to/file.md 导入其他 Markdown，详见Memory Import Processor。

退出使用统计

若不希望发送匿名统计数据，可在任意层级的 settings.json 中设置：

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

建议：升级到 2025 年 9 月后的稳定版后，尽量使用新格式，并利用内置校验提升配置可靠性。若过程中需要参考旧配置，可结合 configuration-v1.md 与 --config-schema 校验输出逐步迁移。