Gemini CLI 配置指南

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

配置层级

配置按以下优先级顺序应用（数字越小越容易被更高层级的配置覆盖）：

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

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

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

用户设置文件：
位置：~/.gemini/settings.json（其中 ~ 表示用户主目录）
作用范围：对当前用户的所有 Gemini CLI 会话生效
项目设置文件：
位置：项目根目录下的 .gemini/settings.json
作用范围：仅当从该项目运行 Gemini CLI 时生效。项目设置会覆盖用户设置

关于设置文件中的环境变量说明：在 settings.json 文件中，字符串值可以通过 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量。这些变量会在加载设置时自动解析。例如，如果您有一个环境变量 MY_API_TOKEN，可以在 settings.json 中这样使用："apiKey": "$MY_API_TOKEN"。

项目中的 `.gemini` 目录

除了项目设置文件外，项目的 .gemini 目录还可以包含与 Gemini CLI 操作相关的其他项目特定文件，例如：

自定义沙箱配置文件（如 .gemini/sandbox-macos-custom.sb、.gemini/sandbox.Dockerfile）。

`settings.json` 中的可用设置项：

contextFileName (字符串或字符串数组):
描述: 指定上下文文件的文件名（如 GEMINI.md、AGENTS.md）。可以是单个文件名或可接受的文件名列表。
默认值: GEMINI.md
示例: "contextFileName": "AGENTS.md"
bugCommand (对象):
描述: 覆盖 /bug 命令的默认 URL。
默认值: "urlTemplate": "https://github.com/google-gemini/gemini-cli/issues/new?template=bug_report.yml&title={title}&info={info}"
属性:
- urlTemplate (字符串): 可包含 {title} 和 {info} 占位符的 URL。

示例:

"bugCommand": {
  "urlTemplate": "https://bug.example.com/new?title={title}&info={info}"
}

fileFiltering (对象):
描述: 控制 @ 命令和文件发现工具的 git 感知文件过滤行为。
默认值: "respectGitIgnore": true, "enableRecursiveFileSearch": true
属性:
- respectGitIgnore (布尔值): 发现文件时是否遵循 .gitignore 模式。设为 true 时，git 忽略的文件（如 node_modules/、dist/、.env）会自动从 @ 命令和文件列表操作中排除。
- enableRecursiveFileSearch (布尔值): 在提示中补全 @ 前缀时，是否启用对当前目录树下的文件名进行递归搜索。

示例:

"fileFiltering": {
  "respectGitIgnore": true,
  "enableRecursiveFileSearch": false
}

coreTools (字符串数组):
描述: 允许指定应提供给模型使用的核心工具名称列表。可用于限制内置工具集。可用核心工具列表参见内置工具。
默认值: Gemini 模型可用的所有工具。
示例: "coreTools": ["ReadFileTool", "GlobTool", "SearchText"].
excludeTools (字符串数组):
描述: 允许指定应从模型中排除的核心工具名称列表。同时出现在 excludeTools 和 coreTools 中的工具会被排除。
默认值: 不排除任何工具。
示例: "excludeTools": ["run_shell_command", "findFiles"].
autoAccept (布尔值):
描述: 控制 CLI 是否自动接受并执行被视为安全的工具调用（如只读操作）而无需用户明确确认。设为 true 时，CLI 将绕过对安全工具的确认提示。
默认值: false
示例: "autoAccept": true
theme (字符串):
描述: 设置 Gemini CLI 的视觉主题。
默认值: "Default"
示例: "theme": "GitHub"
sandbox (布尔值或字符串):
描述: 控制是否以及如何使用沙箱执行工具。设为 true 时，Gemini CLI 使用预构建的 gemini-cli-sandbox Docker 镜像。更多信息参见沙箱化。
默认值: false
示例: "sandbox": "docker"
toolDiscoveryCommand (字符串):
描述: 定义用于从项目中发现工具的自定义 shell 命令。该 shell 命令必须在 stdout 返回一个函数声明的 JSON 数组。工具包装器是可选的。
默认值: 空
示例: "toolDiscoveryCommand": "bin/get_tools"
toolCallCommand (字符串):
描述: 定义用于调用通过 toolDiscoveryCommand 发现的特定工具的自定义 shell 命令。该 shell 命令必须满足以下条件：
- 必须将函数 name（与函数声明中完全一致）作为第一个命令行参数。
- 必须从 stdin 读取函数参数的 JSON，类似于 functionCall.args。
- 必须在 stdout 返回函数输出的 JSON，类似于 functionResponse.response.content。
默认值: 空
示例: "toolCallCommand": "bin/call_tool"
mcpServers (对象):
描述: 配置与一个或多个模型上下文协议（MCP）服务器的连接，用于发现和使用自定义工具。Gemini CLI 会尝试连接到每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露同名工具，工具名称将加上配置中定义的服务器别名前缀（如 serverAlias__actualToolName）以避免冲突。注意系统可能会从 MCP 工具定义中剥离某些模式属性以确保兼容性。
默认值: 空
属性:
- <SERVER_NAME> (对象): 指定服务器的参数。
- command (字符串，必需): 启动 MCP 服务器要执行的命令。
- args (字符串数组，可选): 传递给命令的参数。
- env (对象，可选): 为服务器进程设置的环境变量。
- cwd (字符串，可选): 启动服务器的工作目录。
- timeout (数字，可选): 对此 MCP 服务器请求的超时时间（毫秒）。
- trust (布尔值，可选): 信任此服务器并绕过所有工具调用确认。

示例:

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["mcp_server.py", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "timeout": 5000
  },
  "myNodeServer": {
    "command": "node",
    "args": ["mcp_server.js"],
    "cwd": "./mcp_tools/node"
  },
  "myDockerServer": {
    "command": "docker",
    "args": ["run", "i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"],
    "env": {
      "API_KEY": "$MY_API_TOKEN"
    }
  },
}

checkpointing (对象):
描述: 配置检查点功能，允许保存和恢复对话及文件状态。详情参见检查点文档。
默认值: {"enabled": false}
属性:
- enabled (布尔值): 设为 true 时，/restore 命令可用。
preferredEditor (字符串):
描述: 指定用于查看差异的首选编辑器。
默认值: vscode
示例: "preferredEditor": "vscode"
telemetry (对象)
描述: 配置 Gemini CLI 的日志记录和指标收集。更多信息参见遥测。
默认值: {"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}
属性:
- enabled (布尔值): 是否启用遥测。
- target (字符串): 收集的遥测数据目标。支持值为 local 和 gcp。
- otlpEndpoint (字符串): OTLP 导出器的端点。
- logPrompts (布尔值): 是否在日志中包含用户提示内容。

示例:

"telemetry": {
  "enabled": true,
  "target": "local",
  "otlpEndpoint": "http://localhost:16686",
  "logPrompts": false
}

usageStatisticsEnabled (布尔值):
描述: 启用或禁用使用统计信息收集。更多信息参见使用统计。
默认值: true
示例:
```
"usageStatisticsEnabled": false
```

示例 `settings.json`:

{
  "theme": "GitHub",
  "sandbox": "docker",
  "toolDiscoveryCommand": "bin/get_tools",
  "toolCallCommand": "bin/call_tool",
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "usageStatisticsEnabled": true
}

Shell 历史记录

CLI 会保存您运行的 shell 命令历史。为避免不同项目间的冲突，这些历史记录会存储在用户主目录下特定于项目的文件夹中。

存储位置: ~/.gemini/tmp/<project_hash>/shell_history
<project_hash> 是根据项目根路径生成的唯一标识符
历史记录保存在名为 shell_history 的文件中

环境变量与 `.env` 文件

环境变量是配置应用程序的常用方式，特别适用于敏感信息（如 API 密钥）或可能因环境而异的设置。

CLI 会自动从 .env 文件加载环境变量，加载顺序如下：

当前工作目录中的 .env 文件
如果未找到，则向上搜索父目录，直到找到 .env 文件或到达项目根目录（由 .git 文件夹标识）或用户主目录
如果仍未找到，则查找 ~/.env（用户主目录中的文件）
GEMINI_API_KEY（必需）：
用于 Gemini API 的 API 密钥
运行关键：没有此密钥 CLI 将无法工作
可在 shell 配置文件（如 ~/.bashrc、~/.zshrc）或 .env 文件中设置
GEMINI_MODEL：
指定默认使用的 Gemini 模型
会覆盖硬编码的默认值
示例：export GEMINI_MODEL="gemini-2.5-flash"
GOOGLE_API_KEY：
您的 Google Cloud API 密钥
在 express 模式下使用 Vertex AI 时需要
确保拥有必要权限并设置 GOOGLE_GENAI_USE_VERTEXAI=true 环境变量
示例：export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
GOOGLE_CLOUD_PROJECT：
您的 Google Cloud 项目 ID
使用 Code Assist 或 Vertex AI 时需要
如果使用 Vertex AI，确保拥有必要权限并设置 GOOGLE_GENAI_USE_VERTEXAI=true 环境变量
示例：export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GOOGLE_APPLICATION_CREDENTIALS（字符串）：
描述：Google 应用凭据 JSON 文件的路径
示例：export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
OTLP_GOOGLE_CLOUD_PROJECT：
用于 Google Cloud 中遥测数据的项目 ID
示例：export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GOOGLE_CLOUD_LOCATION：
您的 Google Cloud 项目位置（如 us-central1）
在非 express 模式下使用 Vertex AI 时需要
如果使用 Vertex AI，确保拥有必要权限并设置 GOOGLE_GENAI_USE_VERTEXAI=true 环境变量
示例：export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
GEMINI_SANDBOX：
settings.json 中 sandbox 设置的替代方案
可接受 true、false、docker、podman 或自定义命令字符串
SEATBELT_PROFILE（macOS 专用）：
在 macOS 上切换 Seatbelt（sandbox-exec）配置文件
permissive-open：（默认）限制对项目文件夹的写入（以及其他少数文件夹，详见 packages/cli/src/utils/sandbox-macos-permissive-open.sb），但允许其他操作
strict：使用严格配置文件，默认拒绝操作
<profile_name>：使用自定义配置文件。要定义自定义配置文件，请在项目的 .gemini/ 目录中创建名为 sandbox-macos-<profile_name>.sb 的文件（例如 my-project/.gemini/sandbox-macos-custom.sb）
DEBUG 或 DEBUG_MODE（通常由底层库或 CLI 本身使用）：
设置为 true 或 1 可启用详细调试日志，有助于故障排除
NO_COLOR：
设置为任意值可禁用 CLI 中的所有彩色输出
CLI_TITLE：
设置为字符串可自定义 CLI 的标题
CODE_ASSIST_ENDPOINT：
指定代码辅助服务器的端点
这对开发和测试很有用

命令行参数

直接运行 CLI 时传递的参数可以覆盖该特定会话的其他配置。

--model <model_name> (-m <model_name>):
指定本次会话使用的 Gemini 模型。
示例：npm start -- --model gemini-1.5-pro-latest
--prompt <your_prompt> (-p <your_prompt>):
用于直接向命令传递提示。这将使 Gemini CLI 以非交互模式运行。
--sandbox (-s):
为本次会话启用沙盒模式。
--sandbox-image:
设置沙盒镜像 URI。
--debug_mode (-d):
为本次会话启用调试模式，提供更详细的输出信息。
--all_files (-a):
如果设置，将递归包含当前目录下的所有文件作为提示的上下文。
--help (或 -h):
显示关于命令行参数的帮助信息。
--show_memory_usage:
显示当前内存使用情况。
--yolo:
启用 YOLO 模式，自动批准所有工具调用。
--telemetry:
启用遥测功能。
--telemetry-target:
设置遥测目标。详见遥测文档。
--telemetry-otlp-endpoint:
设置遥测的 OTLP 端点。详见遥测文档。
--telemetry-log-prompts:
启用提示日志记录用于遥测。详见遥测文档。
--checkpointing:
启用检查点功能。
--version:
显示 CLI 版本信息。

虽然严格来说这不属于 CLI 行为的配置，但上下文文件（默认为 GEMINI.md，可通过 contextFileName 设置进行配置）对于配置提供给 Gemini 模型的 指令上下文（也称为"记忆"）至关重要。这一强大功能允许您向 AI 提供项目特定的指令、编码风格指南或任何相关的背景信息，使其响应更符合您的需求且更加准确。CLI 包含 UI 元素（例如页脚中显示已加载上下文文件数量的指示器），以便您了解当前激活的上下文。

用途： 这些 Markdown 文件包含您希望 Gemini 模型在交互过程中了解的指令、指南或上下文。该系统设计用于分层管理这些指令上下文。

上下文文件内容示例（例如 `GEMINI.md`）

以下是一个 TypeScript 项目根目录下上下文文件的概念性示例：

# 项目：我的 TypeScript 超棒库


## 通用指令：

- 生成新的 TypeScript 代码时，请遵循现有的编码风格。
- 确保所有新函数和类都有 JSDoc 注释。
- 在适当的情况下优先使用函数式编程范式。
- 所有代码应与 TypeScript 5.0 和 Node.js 18+ 兼容。


## 编码风格：

- 使用 2 个空格缩进。
- 接口名称应带有 `I` 前缀（例如 `IUserService`）。
- 私有类成员应带有下划线前缀（`_`）。
- 始终使用严格相等（`===` 和 `!==`）。


## 特定组件：`src/api/client.ts`

- 该文件处理所有出站 API 请求。
- 添加新的 API 调用函数时，确保包含健壮的错误处理和日志记录。
- 所有 GET 请求都使用现有的 `fetchWithRetry` 工具函数。

关于依赖项：

除非绝对必要，否则避免引入新的外部依赖项。

如果需要新的依赖项，请说明原因。

这个示例展示了如何提供项目通用上下文、特定编码规范，甚至是关于特定文件或组件的注释。您的上下文文件越相关且精确，AI 就能提供更好的协助。强烈建议使用项目特定的上下文文件来建立规范和上下文。

- **层级加载与优先级：** CLI 通过从多个位置加载上下文文件（如 `GEMINI.md`）实现了一个复杂的分层记忆系统。列表中较低位置（更具体）的文件内容通常会覆盖或补充较高位置（更通用）的文件内容。可以通过 `/memory show` 命令查看具体的连接顺序和最终上下文。典型的加载顺序是：
  1.  **全局上下文文件：**
      - 位置：`~/.gemini/<contextFileName>`（例如用户主目录中的 `~/.gemini/GEMINI.md`）。
      - 作用范围：为所有项目提供默认指令。
  2.  **项目根目录及上级目录上下文文件：**
      - 位置：CLI 会在当前工作目录及其每个父目录中搜索配置的上下文文件，直到项目根目录（由 `.git` 文件夹标识）或用户主目录。
      - 作用范围：提供与整个项目或其主要部分相关的上下文。
  3.  **子目录上下文文件（上下文/本地）：**
      - 位置：CLI 还会在当前工作目录的子目录中扫描配置的上下文文件（遵循常见的忽略模式，如 `node_modules`、`.git` 等）。
      - 作用范围：允许为项目的特定组件、模块或子部分提供高度具体的指令。
- **连接与 UI 指示：** 所有找到的上下文文件内容会被连接起来（带有标明其来源和路径的分隔符），并作为系统提示的一部分提供给 Gemini 模型。CLI 页脚会显示已加载上下文文件的数量，为您提供关于活动指令上下文的快速视觉提示。
- **内存管理命令：**
  - 使用 `/memory refresh` 强制重新扫描并重新加载所有配置位置的上下文文件。这会更新 AI 的指令上下文。
  - 使用 `/memory show` 显示当前加载的组合指令上下文，允许您验证 AI 正在使用的层级和内容。
  - 查看 [命令文档](./commands.md#memory) 了解 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详情。

通过理解和利用这些配置层及上下文文件的层级特性，您可以有效地管理 AI 的记忆，并根据您的特定需求和项目定制 Gemini CLI 的响应。

## 沙盒环境

Gemini CLI 可以在沙盒环境中执行潜在不安全的操作（如 shell 命令和文件修改），以保护您的系统安全。

沙盒功能默认关闭，但您可以通过以下方式启用：

- 使用 `--sandbox` 或 `-s` 参数
- 设置 `GEMINI_SANDBOX` 环境变量
- 在 `--yolo` 模式下默认启用沙盒

默认情况下，它使用预构建的 `gemini-cli-sandbox` Docker 镜像。

如需针对项目定制沙盒环境，您可以在项目根目录的 `.gemini/sandbox.Dockerfile` 中创建自定义 Dockerfile。该 Dockerfile 可以基于基础沙盒镜像：

```dockerfile
FROM gemini-cli-sandbox


# 在此添加您的自定义依赖或配置

# 例如：

# RUN apt-get update && apt-get install -y some-package

# COPY ./my-config /app/my-config

当存在 .gemini/sandbox.Dockerfile 文件时，您可以在运行 Gemini CLI 时使用 BUILD_SANDBOX 环境变量来自动构建自定义沙盒镜像：

BUILD_SANDBOX=1 gemini -s

使用统计

为了帮助我们改进 Gemini CLI，我们会收集匿名化的使用统计数据。这些数据有助于我们了解 CLI 的使用情况、识别常见问题并确定新功能的优先级。

我们收集的内容：

工具调用： 记录被调用工具的名称、执行成功或失败状态以及执行耗时。我们不会收集传递给工具的参数或工具返回的任何数据。
API 请求： 记录每次请求使用的 Gemini 模型、请求持续时间和是否成功。我们不会收集提示内容或响应内容。
会话信息： 收集 CLI 配置信息，例如启用的工具和审批模式。

我们不收集的信息：

个人身份信息 (PII)： 我们不会收集任何个人信息，例如您的姓名、电子邮件地址或 API 密钥。
提示与响应内容： 我们不会记录您输入的提示内容或 Gemini 模型返回的响应内容。
文件内容： 我们不会记录 CLI 读取或写入的任何文件内容。

如何退出统计：

您可以通过在 settings.json 文件中将 usageStatisticsEnabled 属性设为 false 来随时退出使用统计收集：

{
  "usageStatisticsEnabled": false
}