Gemini CLI 配置

深度定制 Gemini CLI 的行为和功能

首页 > CLI 指南 > CLI 配置

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

配置层级

🔧 配置按以下优先级顺序应用（数字越大优先级越高）：

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

用户设置文件和项目设置文件

Gemini CLI 使用 settings.json 文件进行持久配置。这些文件有两个位置：

👤 用户设置文件

位置： ~/.gemini/settings.json

作用域： 适用于当前用户的所有 Gemini CLI 会话

📁 项目设置文件

位置： .gemini/settings.json （项目根目录内）

作用域： 仅在从该特定项目运行 Gemini CLI 时适用

📝 环境变量引用

settings.json 文件中的字符串值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量。加载设置时这些变量将自动解析。

settings.json 中的可用设置

theme (string)

描述： 设置 Gemini CLI 的视觉主题

默认值： "Default"

示例： "theme": "GitHub"

autoAccept (boolean)

描述： 控制 CLI 是否自动接受并执行被认为安全的工具调用（如只读操作），无需明确用户确认

默认值： false

示例： "autoAccept": true

sandbox (boolean | string)

描述： 控制是否以及如何为工具执行使用沙盒。如果设置为 true，Gemini CLI 使用预构建的沙盒 Docker 镜像

默认值： false

示例： "sandbox": "docker"

fileFiltering (object)

描述： 控制 @ 命令和文件发现工具的 git 感知文件过滤行为

属性：

  • respectGitIgnore (boolean): 是否在发现文件时遵守 .gitignore 模式
  • enableRecursiveFileSearch (boolean): 是否启用递归文件搜索
"fileFiltering": {
  "respectGitIgnore": true,
  "enableRecursiveFileSearch": true
}

mcpServers (object)

描述： 配置与一个或多个模型上下文协议 (MCP) 服务器的连接，用于发现和使用自定义工具

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["mcp_server.py", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "timeout": 5000
  }
}

coreTools (array)

描述： 指定应该对模型可用的核心工具名称列表。可用于限制内置工具集

示例： "coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]

excludeTools (array)

描述： 指定应该从模型中排除的核心工具名称列表

示例： "excludeTools": ["run_shell_command", "findFiles"]

安全注意： excludeTools 中的命令特定限制基于简单字符串匹配，容易绕过。这不是安全机制。

checkpointing (object)

描述： 配置检查点功能，允许您保存和恢复对话和文件状态

属性：

  • enabled (boolean): 启用时，/restore 命令可用

示例： "checkpointing": {"enabled": true}

telemetry (object)

描述： 配置 Gemini CLI 的日志记录和指标收集

属性：

  • enabled (boolean): 是否启用遥测
  • target (string): 收集的遥测数据的目标。支持值为 local 和 gcp
  • logPrompts (boolean): 是否在日志中包含用户提示的内容

示例 settings.json

{
  "theme": "GitHub",
  "sandbox": "docker",
  "autoAccept": false,
  "fileFiltering": {
    "respectGitIgnore": true,
    "enableRecursiveFileSearch": true
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    }
  },
  "checkpointing": {
    "enabled": true
  },
  "telemetry": {
    "enabled": false,
    "target": "local",
    "logPrompts": false
  }
}

环境变量和 .env 文件

环境变量是配置应用程序的常用方法，特别是对于敏感信息（如 API 密钥）或在不同环境之间可能变化的设置。

主要环境变量

变量名 描述 必需
GEMINI_API_KEY 您的 Gemini API 密钥 是
GOOGLE_CLOUD_PROJECT 您的 Google Cloud 项目 ID 条件
GEMINI_MODEL 指定要使用的默认 Gemini 模型 否
GEMINI_SANDBOX 替代 settings.json 中的 sandbox 设置 否
DEBUG 设置为 true 启用详细调试日志 否

.env 文件加载顺序

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

  1. 当前工作目录中的 .env 文件
  2. 如果未找到，在父目录中搜索，直到找到 .env 文件或到达项目根目录
  3. 如果仍未找到，查找 ~/.env（用户家目录）

命令行参数

传递给 CLI 的参数可以覆盖该特定会话的其他配置：

参数 短选项 描述
--model <model_name> -m 指定此会话使用的 Gemini 模型
--prompt <your_prompt> -p 直接传递提示到命令（非交互模式）
--sandbox -s 为此会话启用沙盒模式
--debug_mode -d 为此会话启用调试模式
--yolo 启用 YOLO 模式，自动批准所有工具调用
--checkpointing 启用检查点功能

上下文文件（分层指导上下文）

📋 GEMINI.md 文件

上下文文件（默认为 GEMINI.md，但可通过 contextFileName 设置配置）对于配置提供给 Gemini 模型的指导上下文至关重要。

分层加载和优先级

CLI 实现了复杂的分层内存系统，通过从多个位置加载上下文文件：

  1. 全局上下文文件： ~/.gemini/GEMINI.md
  2. 项目根和祖先上下文文件： 当前工作目录及其父目录
  3. 子目录上下文文件： 当前工作目录下的子目录

内存管理命令

  • /memory refresh - 强制重新扫描和重新加载所有上下文文件
  • /memory show - 显示当前加载的组合指导上下文
  • /memory add - 将文本添加到 AI 的内存

相关文档：

↑ 顶部