Gemini CLI 配置

Gemini CLI 提供多种配置其行为的方式，包括环境变量、命令行参数和设置文件。本文档概述了不同的配置方法和可用设置。

配置层级

配置按以下优先级顺序应用（较低数字被较高数字覆盖）：

1. 默认值： 应用程序内的硬编码默认值。
2. 系统默认文件： 可被其他设置文件覆盖的系统范围默认设置。
3. 用户设置文件： 当前用户的全局设置。
4. 项目设置文件： 项目特定设置。
5. 系统设置文件： 覆盖所有其他设置文件的系统范围设置。
6. 环境变量： 系统范围或会话特定变量，可能从 .env 文件加载。
7. 命令行参数： 启动 CLI 时传递的值。

设置文件

Gemini CLI 使用 JSON 设置文件进行持久配置。这些文件有四个位置：

• 系统默认文件：

  • 位置： /etc/gemini-cli/system-defaults.json（Linux）、C:\ProgramData\gemini-cli\system-defaults.json（Windows）或 /Library/Application Support/GeminiCli/system-defaults.json（macOS）。
  • 范围： 提供系统范围默认设置的基础层。

• 用户设置文件：

  • 位置： ~/.gemini/settings.json（~ 是你的主目录）。
  • 范围： 适用于当前用户的所有 Gemini CLI 会话。

• 项目设置文件：

  • 位置： 项目根目录中的 .gemini/settings.json。
  • 范围： 仅在从该特定项目运行 Gemini CLI 时适用。

• 系统设置文件：

  • 位置： /etc/gemini-cli/settings.json（Linux）、C:\ProgramData\gemini-cli\settings.json（Windows）或 /Library/Application Support/GeminiCli/settings.json（macOS）。
  • 范围： 适用于系统上所有用户的所有 Gemini CLI 会话。

主要设置类别

general - 通用设置

• general.previewFeatures：启用预览功能（默认：false）
• general.vimMode：启用 Vim 键绑定（默认：false）
• general.checkpointing.enabled：启用会话检查点恢复（默认：false）

ui - 界面设置

• ui.theme：UI 的颜色主题
• ui.hideBanner：隐藏应用程序横幅（默认：false）
• ui.hideTips：隐藏 UI 中的提示（默认：false）

model - 模型设置

• model.name：用于对话的 Gemini 模型
• model.maxSessionTurns：会话中保留的最大轮次（默认：-1 无限制）

tools - 工具设置

• tools.sandbox：沙箱执行环境
• tools.autoAccept：自动接受安全工具调用（默认：false）
• tools.allowed：绕过确认对话框的工具名称列表

mcp - MCP 服务器设置

• mcp.serverCommand：启动 MCP 服务器的命令
• mcp.allowed：允许的 MCP 服务器列表
• mcp.excluded：排除的 MCP 服务器列表

mcpServers - MCP 服务器配置

配置与一个或多个 Model-Context Protocol (MCP) 服务器的连接：

{
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  }
}

示例 settings.json

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true
  },
  "tools": {
    "sandbox": "docker"
  },
  "model": {
    "name": "gemini-2.5-pro"
  }
}

环境变量

CLI 自动从 .env 文件加载环境变量。加载顺序：

1. 当前工作目录中的 .env 文件。
2. 如果未找到，向上搜索父目录直到找到 .env 文件或到达项目根目录。
3. 如果仍未找到，查找 ~/.env。

主要环境变量

• GEMINI_API_KEY：Gemini API 的 API 密钥
• GEMINI_MODEL：指定默认使用的 Gemini 模型
• GOOGLE_API_KEY：Google Cloud API 密钥
• GOOGLE_CLOUD_PROJECT：Google Cloud 项目 ID
• GOOGLE_CLOUD_LOCATION：Google Cloud 项目位置
• GEMINI_SANDBOX：沙箱设置（true、false、docker、podman）
• DEBUG：设置为 true 启用详细调试日志

命令行参数

• --model <model_name>（-m）：指定此会话使用的模型
• --prompt <your_prompt>（-p）：直接传递提示（非交互模式）
• --sandbox（-s）：为此会话启用沙箱模式
• --debug（-d）：启用调试模式
• --yolo：自动批准所有工具调用
• --resume [session_id]（-r）：恢复之前的聊天会话
• --help（-h）：显示帮助信息
• --version：显示 CLI 版本

上下文文件

上下文文件（默认为 GEMINI.md）用于配置提供给 Gemini 模型的指令上下文。

层级加载

1. 全局上下文文件： ~/.gemini/GEMINI.md
2. 项目根目录和祖先上下文文件： 从当前目录向上搜索
3. 子目录上下文文件： 当前目录下的子目录

内存管理命令

• /memory refresh：强制重新扫描和重新加载所有上下文文件
• /memory show：显示当前加载的组合指令上下文

沙箱

Gemini CLI 可以在沙箱环境中执行潜在不安全的操作以保护你的系统。

启用沙箱的方式：

• 使用 --sandbox 或 -s 标志
• 设置 GEMINI_SANDBOX 环境变量
• 使用 --yolo 时默认启用沙箱

对于项目特定的沙箱需求，可以在项目根目录创建 .gemini/sandbox.Dockerfile。

使用统计

为帮助改进 Gemini CLI，我们收集匿名使用统计。你可以通过在 settings.json 中设置来选择退出：

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