Gemini CLI 配置

关于配置格式的说明，2025 年 9 月 17 日： settings.json 文件的格式已更新为新的、更具组织性的结构。
新格式将在 [2025 年 9 月 10 日] 的稳定版本中开始支持。
从旧格式到新格式的自动迁移将于 [2025 年 9 月 17 日] 开始。
有关先前格式的详细信息，请参阅 v1 配置文档。

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

配置层级

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

默认值： 应用程序内硬编码的默认值。
系统默认设置文件： 系统范围的默认设置，可以被其他设置文件覆盖。
用户设置文件： 当前用户的全局设置。
项目设置文件： 项目特定的设置。
系统设置文件： 系统范围的设置，覆盖所有其他设置文件。
环境变量： 系统范围或会话特定的变量，可能从 .env 文件加载。
命令行参数： 启动 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_CLI_SYSTEM_DEFAULTS_PATH 环境变量覆盖路径。
- 范围： 提供系统范围默认设置的基础层。这些设置的优先级最低，旨在被用户、项目或系统覆盖设置所覆盖。
用户设置文件：
- 位置： ~/.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_SYSTEM_SETTINGS_PATH 环境变量覆盖路径。
- 范围： 应用于系统上所有 Gemini CLI 会话，所有用户。系统设置充当覆盖，优先级高于所有其他设置文件。对于企业系统管理员来说，这可能有助于控制用户 Gemini CLI 的设置。

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

企业用户须知： 有关在企业环境中部署和管理 Gemini CLI 的指南，请参阅企业配置文档。

项目中的 `.gemini` 目录

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

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

`settings.json` 中可用的设置

设置按类别组织。所有设置都应放在 settings.json 文件中相应的顶级类别对象内。

`general`

general.preferredEditor (string):
- 描述： 打开文件的首选编辑器。
- 默认值： undefined
general.vimMode (boolean):
- 描述： 启用 Vim 键绑定。
- 默认值： false
general.disableAutoUpdate (boolean):
- 描述： 禁用自动更新。
- 默认值： false
general.disableUpdateNag (boolean):
- 描述： 禁用更新通知提示。
- 默认值： false
general.checkpointing.enabled (boolean):
- 描述： 启用会话检查点以进行恢复。
- 默认值： false

`output`

output.format (string):
- 描述： CLI 输出的格式。
- 默认值： "text"
- 值： "text", "json"

`ui`

ui.theme (string):
- 描述： UI 的颜色主题。有关可用选项，请参阅主题。
- 默认值： undefined
ui.customThemes (object):
- 描述： 自定义主题定义。
- 默认值： {}
ui.hideWindowTitle (boolean):
- 描述： 隐藏窗口标题栏。
- 默认值： false
ui.hideTips (boolean):
- 描述： 隐藏 UI 中的提示信息。
- 默认值： false
ui.hideBanner (boolean):
- 描述： 隐藏应用程序横幅。
- 默认值： false
ui.hideFooter (boolean):
- 描述： 从 UI 中隐藏页脚。
- 默认值： false
ui.showMemoryUsage (boolean):
- 描述： 在 UI 中显示内存使用信息。
- 默认值： false
ui.showLineNumbers (boolean):
- 描述： 在聊天中显示行号。
- 默认值： false
ui.showCitations (boolean):
- 描述： 在聊天中显示生成文本的引用。
- 默认值： true
ui.accessibility.disableLoadingPhrases (boolean):
- 描述： 禁用无障碍加载短语。
- 默认值： false
ui.customWittyPhrases (array of strings):
- 描述： 在加载状态期间显示的自定义短语列表。如果提供了此列表，CLI 将在此短语之间循环，而不是使用默认短语。
- 默认值： []

`ide`

ide.enabled (boolean):
- 描述： 启用 IDE 集成模式。
- 默认值： false
ide.hasSeenNudge (boolean):
- 描述： 用户是否已看到 IDE 集成提示。
- 默认值： false

`privacy`

privacy.usageStatisticsEnabled (boolean):
- 描述： 启用使用统计信息收集。
- 默认值： true

`model`

model.name (string):
- 描述： 用于对话的 Gemini 模型。
- 默认值： undefined
model.maxSessionTurns (number):
- 描述： 在会话中保留的最大用户/模型/工具轮次。-1 表示无限。
- 默认值： -1
model.summarizeToolOutput (object):
- 描述： 启用或禁用工具输出的摘要。您可以使用 tokenBudget 设置指定摘要的 token 预算。注意：目前仅支持 run_shell_command 工具。例如 {"run_shell_command": {"tokenBudget": 2000}}
- 默认值： undefined
model.chatCompression.contextPercentageThreshold (number):
- 描述： 将聊天历史压缩的阈值设置为模型总 token 限制的百分比。这是一个介于 0 和 1 之间的值，适用于自动压缩和手动 /compress 命令。例如，值为 0.6 时，当聊天历史超过 token 限制的 60% 时将触发压缩。
- 默认值： 0.7
model.skipNextSpeakerCheck (boolean):
- 描述： 跳过下一个说话者检查。
- 默认值： false

`context`

context.fileName (string or array of strings):
- 描述： 上下文文件的名称。
- 默认值： undefined
context.importFormat (string):
- 描述： 导入内存时使用的格式。
- 默认值： undefined
context.discoveryMaxDirs (number):
- 描述： 搜索内存的最大目录数。
- 默认值： 200
context.includeDirectories (array):
- 描述： 要包含在工作区上下文中的其他目录。缺失的目录将被跳过并发出警告。
- 默认值： []
context.loadFromIncludeDirectories (boolean):
- 描述： 控制 /memory refresh 命令的行为。如果设置为 true，则应从所有添加的目录加载 GEMINI.md 文件。如果设置为 false，则应仅从当前目录加载 GEMINI.md。
- 默认值： false
context.fileFiltering.respectGitIgnore (boolean):
- 描述： 搜索时尊重 .gitignore 文件。
- 默认值： true
context.fileFiltering.respectGeminiIgnore (boolean):
- 描述： 搜索时尊重 .geminiignore 文件。
- 默认值： true
context.fileFiltering.enableRecursiveFileSearch (boolean):
- 描述： 在提示中完成 @ 前缀时，是否启用递归搜索当前树下的文件名。
- 默认值： true

`tools`

tools.sandbox (boolean or string):
- 描述： 沙箱执行环境（可以是布尔值或路径字符串）。
- 默认值： undefined
tools.shell.enableInteractiveShell (boolean):
- 描述： 启用交互式终端以运行 shell 命令。如果无法启动交互式会话，它将回退到标准 shell。
- 默认值： true
tools.core (array of strings):
- 描述： 可用于通过允许列表限制内置工具集企业配置。有关核心工具列表，请参阅内置工具。匹配语义与 tools.allowed 相同。
- 默认值： undefined
tools.exclude (array of strings):
- 描述： 要从发现中排除的工具名称。
- 默认值： undefined
tools.allowed (array of strings):
- 描述： 一组工具名称，它们将绕过确认对话框。这对于您信任并经常使用的工具很有用。例如，["run_shell_command(git)", "run_shell_command(npm test)"] 将跳过确认对话框以运行任何 git 和 npm test 命令。有关前缀匹配、命令链等详细信息，请参阅 Shell 工具命令限制。
- 默认值： undefined
tools.discoveryCommand (string):
- 描述： 用于工具发现的要运行的命令。
- 默认值： undefined
tools.callCommand (string):
- 描述： 定义一个自定义 shell 命令，用于调用使用 tools.discoveryCommand 发现的特定工具。shell 命令必须满足以下条件：
  - 它必须将函数 name（与函数声明中的名称完全相同）作为第一个命令行参数。
  - 它必须像 functionCall.args 一样，通过 stdin 读取函数参数。
  - 它必须像 functionResponse.response.content 一样，通过 stdout 返回函数输出作为 JSON。
- 默认值： undefined

`mcp`

mcp.serverCommand (string):
- 描述： 启动 MCP 服务器的命令。
- 默认值： undefined
mcp.allowed (array of strings):
- 描述： 允许的 MCP 服务器的允许列表。
- 默认值： undefined
mcp.excluded (array of strings):
- 描述： 要排除的 MCP 服务器的拒绝列表。
- 默认值： undefined

`security`

security.folderTrust.enabled (boolean):
- 描述： 用于跟踪文件夹信任是否启用的设置。
- 默认值： false
security.auth.selectedType (string):
- 描述： 当前选定的身份验证类型。
- 默认值： undefined
security.auth.enforcedType (string):
- 描述： 所需的身份验证类型（对企业有用）。
- 默认值： undefined
security.auth.useExternal (boolean):
- 描述： 是否使用外部身份验证流程。
- 默认值： undefined

`advanced`

advanced.autoConfigureMemory (boolean):
- 描述： 自动配置 Node.js 内存限制。
- 默认值： false
advanced.dnsResolutionOrder (string):
- 描述： DNS 解析顺序。
- 默认值： undefined
advanced.excludedEnvVars (array of strings):
- 描述： 要从项目上下文中排除的环境变量。
- 默认值： ["DEBUG","DEBUG_MODE"]
advanced.bugCommand (object):
- 描述： 错误报告命令的配置。
- 默认值： undefined

`mcpServers`

配置与一个或多个模型上下文协议 (MCP) 服务器的连接，用于发现和使用自定义工具。Gemini CLI 会尝试连接到每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器公开了同名的工具，则工具名称将加上您在配置中定义的服务器别名前缀（例如 serverAlias__actualToolName）以避免冲突。请注意，系统可能会为兼容性剥离 MCP 工具定义中的某些架构属性。至少需要提供 command、url 或 httpUrl 中的一个。如果指定了多个，则优先级顺序为 httpUrl，然后是 url，最后是 command。

mcpServers.<SERVER_NAME> (object): 命名服务器的服务器参数。
- command (string, optional): 通过标准 I/O 执行以启动 MCP 服务器的命令。
- args (array of strings, optional): 要传递给命令的参数。
- env (object, optional): 要为服务器进程设置的环境变量。
- cwd (string, optional): 启动服务器时要使用的当前工作目录。
- url (string, optional): 使用服务器发送事件 (SSE) 进行通信的 MCP 服务器的 URL。
- httpUrl (string, optional): 使用流式 HTTP 进行通信的 MCP 服务器的 URL。
- headers (object, optional): 要与发送到 url 或 httpUrl 的请求一起发送的 HTTP 标头映射。
- timeout (number, optional): 此 MCP 服务器请求的超时时间（以毫秒为单位）。
- trust (boolean, optional): 信任此服务器并绕过所有工具调用确认。
- description (string, optional): 服务器的简要描述，可用于显示目的。
- includeTools (array of strings, optional): 要从此 MCP 服务器包含的工具名称列表。指定后，只有此处列出的工具才可从此服务器获得（允许列表行为）。如果未指定，则默认启用服务器的所有工具。
- excludeTools (array of strings, optional): 要从此 MCP 服务器排除的工具名称列表。此处列出的工具将无法供模型使用，即使它们由服务器公开。注意： excludeTools 的优先级高于 includeTools - 如果一个工具同时出现在两个列表中，它将被排除。

`telemetry`

配置 Gemini CLI 的日志记录和指标收集。有关更多信息，请参阅遥测。

属性：
- enabled (boolean): 是否启用遥测。
- target (string): 收集遥测的目标。支持的值为 local 和 gcp。
- otlpEndpoint (string): OTLP Exporter 的端点。
- otlpProtocol (string): OTLP Exporter 的协议（grpc 或 http）。
- logPrompts (boolean): 是否在日志中包含用户提示的内容。
- outfile (string): 当 target 为 local 时要写入遥测的文件。
- useCollector (boolean): 是否使用外部 OTLP 收集器。

`settings.json` 示例

这是一个带有嵌套结构（v0.3.0 新增）的 settings.json 文件示例：

json

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of ’em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "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
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 10,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

Shell 历史记录

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

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

环境变量和 `.env` 文件

环境变量是配置应用程序的常用方法，尤其适用于 API 密钥等敏感信息，或可能在不同环境之间更改的设置。有关身份验证设置，请参阅身份验证文档，其中涵盖了所有可用的身份验证方法。

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

当前工作目录中的 .env 文件。
如果未找到，它会在父目录中向上搜索，直到找到 .env 文件或到达项目根目录（由 .git 文件夹标识）或主目录。
如果仍未找到，它会在用户主目录中查找 ~/.env。

环境变量排除： 某些环境变量（如 DEBUG 和 DEBUG_MODE）默认会从项目 .env 文件中排除加载，以防止干扰 gemini-cli 的行为。.gemini/.env 文件中的变量永远不会被排除。您可以使用 settings.json 文件中的 advanced.excludedEnvVars 设置来自定义此行为。

GEMINI_API_KEY：
- 您的 Gemini API 密钥。
- 几种可用的身份验证方法之一。
- 在您的 shell 配置文件（例如 ~/.bashrc, ~/.zshrc）或 .env 文件中设置。
GEMINI_MODEL：
- 指定要使用的默认 Gemini 模型。
- 覆盖硬编码的默认值。
- 示例：export GEMINI_MODEL="gemini-2.5-flash"
GOOGLE_API_KEY：
- 您的 Google Cloud API 密钥。
- 在使用 Vertex AI 的 express 模式时需要。
- 确保您拥有必要的权限。
- 示例：export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"。
GOOGLE_CLOUD_PROJECT：
- 您的 Google Cloud 项目 ID。
- 使用 Code Assist 或 Vertex AI 时需要。
- 如果使用 Vertex AI，请确保在此项目中拥有必要的权限。
- Cloud Shell 注意： 在 Cloud Shell 环境中运行时，此变量默认为分配给 Cloud Shell 用户的特殊项目。如果您在 Cloud Shell 的全局环境中设置了 GOOGLE_CLOUD_PROJECT，它将被此默认值覆盖。要在 Cloud Shell 中使用其他项目，您必须在 .env 文件中定义 GOOGLE_CLOUD_PROJECT。
- 示例：export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"。
GOOGLE_APPLICATION_CREDENTIALS (string):
- 描述： 您的 Google Application Credentials JSON 文件的路径。
- 示例： export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
OTLP_GOOGLE_CLOUD_PROJECT：
- 用于 Google Cloud 中遥测的 Google Cloud 项目 ID。
- 示例：export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"。
GEMINI_TELEMETRY_ENABLED：
- 设置为 true 或 1 以启用遥测。任何其他值都视为禁用。
- 覆盖 telemetry.enabled 设置。
GEMINI_TELEMETRY_TARGET：
- 设置遥测目标（local 或 gcp）。
- 覆盖 telemetry.target 设置。
GEMINI_TELEMETRY_OTLP_ENDPOINT：
- 设置遥测的 OTLP 端点。
- 覆盖 telemetry.otlpEndpoint 设置。
GEMINI_TELEMETRY_OTLP_PROTOCOL：
- 设置 OTLP 协议（grpc 或 http）。
- 覆盖 telemetry.otlpProtocol 设置。
GEMINI_TELEMETRY_LOG_PROMPTS：
- 设置为 true 或 1 以启用或禁用用户提示的日志记录。任何其他值都视为禁用。
- 覆盖 telemetry.logPrompts 设置。
GEMINI_TELEMETRY_OUTFILE：
- 当目标为 local 时，设置写入遥测的文件路径。
- 覆盖 telemetry.outfile 设置。
GEMINI_TELEMETRY_USE_COLLECTOR：
- 设置为 true 或 1 以启用或禁用使用外部 OTLP 收集器。任何其他值都视为禁用。
- 覆盖 telemetry.useCollector 设置。
GOOGLE_CLOUD_LOCATION：
- 您的 Google Cloud 项目位置（例如，us-central1）。
- 在使用 Vertex AI 的非 express 模式时需要。
- 示例：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 以启用详细的调试日志记录，这有助于故障排除。
- 注意： 这些变量默认会从项目 .env 文件中排除，以防止干扰 gemini-cli 的行为。如果您需要为 gemini-cli 特别设置这些变量，请使用 .gemini/.env 文件。
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。
- 对于脚本示例，请使用 --output-format json 标志以获取结构化输出。
--prompt-interactive <your_prompt> (-i <your_prompt>):
- 启动一个交互式会话，并将提供的提示作为初始输入。
- 提示在交互式会话中处理，而不是在此之前处理。
- 不能与从 stdin 管道输入一起使用。
- 示例：gemini -i "explain this code"
--output-format <format>:
- 描述： 指定非交互模式下 CLI 输出的格式。
- 值：
  - text: (默认) 标准的人类可读输出。
  - json: 机器可读的 JSON 输出。
- 注意： 对于结构化输出和脚本，请使用 --output-format json 标志。
--sandbox (-s):
- 为此会话启用沙箱模式。
--sandbox-image:
- 设置沙箱镜像 URI。
--debug (-d):
- 为此会话启用调试模式，提供更详细的输出。
--all-files (-a):
- 如果设置，则递归地将当前目录下的所有文件作为上下文包含在提示中。
--help (或 -h):
- 显示有关命令行参数的帮助信息。
--show-memory-usage:
- 显示当前内存使用情况。
--yolo:
- 启用 YOLO 模式，该模式会自动批准所有工具调用。
--approval-mode <mode>:
- 设置工具调用的批准模式。可用模式：
  - default: 提示批准每个工具调用（默认行为）
  - auto_edit: 自动批准编辑工具（替换、写入文件），同时提示其他工具
  - yolo: 自动批准所有工具调用（等同于 --yolo）
- 不能与 --yolo 一起使用。请使用 --approval-mode=yolo 而不是 --yolo 来实现新的统一方法。
- 示例：gemini --approval-mode auto_edit
--allowed-tools <tool1,tool2,...>:
- 一个逗号分隔的工具名称列表，这些工具将绕过确认对话框。
- 示例：gemini --allowed-tools "ShellTool(git status)"
--telemetry:
- 启用遥测。
--telemetry-target:
- 设置遥测目标。有关更多信息，请参阅遥测。
--telemetry-otlp-endpoint:
- 设置遥测的 OTLP 端点。有关更多信息，请参阅遥测。
--telemetry-otlp-protocol:
- 设置遥测的 OTLP 协议（grpc 或 http）。默认为 grpc。有关更多信息，请参阅遥测。
--telemetry-log-prompts:
- 启用提示的日志记录以进行遥测。有关更多信息，请参阅遥测。
--checkpointing:
- 启用检查点。
--extensions <extension_name ...> (-e <extension_name ...>):
- 指定要用于会话的扩展列表。如果未提供，则使用所有可用扩展。
- 使用特殊术语 gemini -e none 来禁用所有扩展。
- 示例：gemini -e my-extension -e my-other-extension
--list-extensions (-l):
- 列出所有可用扩展并退出。
--proxy:
- 设置 CLI 的代理。
- 示例：--proxy http://localhost:7890。
--include-directories <dir1,dir2,...>:
- 在工作区中包含其他目录以支持多目录。
- 可以多次指定或作为逗号分隔的值。
- 最多可以添加 5 个目录。
- 示例：--include-directories /path/to/project1,/path/to/project2 或 --include-directories /path/to/project1 --include-directories /path/to/project2
--screen-reader:
- 启用屏幕阅读器模式，该模式会调整 TUI 以更好地兼容屏幕阅读器。
--version:
- 显示 CLI 的版本。

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

虽然严格来说不是 CLI 行为的配置，但上下文文件（默认为 GEMINI.md，但可通过 context.fileName 设置进行配置）对于配置提供给 Gemini 模型的 指令上下文（也称为“内存”）至关重要。此强大功能允许您为 AI 提供项目特定的指令、编码风格指南或任何相关背景信息，从而使模型的响应更具针对性且准确地满足您的需求。CLI 包含 UI 元素，例如显示已加载上下文文件数量的页脚指示器，让您随时了解活动上下文。

目的： 这些 Markdown 文件包含您希望 Gemini 模型在交互期间了解的指令、指南或上下文。系统旨在分层管理此指令上下文。

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

以下是一个概念示例，展示了 TypeScript 项目根目录下的上下文文件可能包含的内容：

markdown

# 项目：My Awesome TypeScript Library

## 一般说明：

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

## 编码风格：

- 使用 2 个空格进行缩进。
- 接口名称应以 `I` 开头（例如 `IUserService`）。
- 私有类成员应以 `_` 开头。
- 始终使用严格相等（`===` 和 `!==`）。

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

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

## 关于依赖项：

- 除非绝对必要，否则避免引入新的外部依赖项。
- 如果需要新的依赖项，请说明原因。

此示例演示了如何提供一般项目上下文、特定的编码约定，甚至有关特定文件或组件的注释。您的上下文文件越相关和精确，AI 就能更好地为您提供帮助。强烈建议使用项目特定的上下文文件来建立约定和上下文。

分层加载和优先级： CLI 通过从多个位置加载上下文文件（例如 GEMINI.md）来实现复杂的分层内存系统。来自列表中较低位置（更具体）的文件内容通常会覆盖或补充来自较高位置（更通用）的文件内容。确切的连接顺序和最终上下文可以使用 /memory show 命令进行检查。典型的加载顺序是：
1. 全局上下文文件：
  - 位置：~/.gemini/<configured-context-filename>（例如，用户主目录中的 ~/.gemini/GEMINI.md）。
  - 范围：为您的所有项目提供默认指令。
2. 项目根目录和祖先上下文文件：
  - 位置：CLI 在当前工作目录中搜索配置的上下文文件，然后在每个父目录中搜索，直到项目根目录（由 .git 文件夹标识）或您的主目录。
  - 范围：提供与整个项目或其重要部分相关的上下文。
3. 子目录上下文文件（上下文/本地）：
  - 位置：CLI 还会扫描当前工作目录下方的子目录中的配置上下文文件（尊重常见的忽略模式，如 node_modules、.git 等）。此搜索的范围默认限制为 200 个目录，但可以在 settings.json 文件中使用 context.discoveryMaxDirs 设置进行配置。
  - 范围：允许为特定组件、模块或项目子部分提供高度具体的指令。
连接和 UI 指示： 所有找到的上下文文件的内容都会被连接起来（带有指示其来源和路径的分隔符），并作为系统提示的一部分提供给 Gemini 模型。CLI 页脚显示已加载上下文文件的数量，让您快速直观地了解活动的指令上下文。
导入内容： 您可以通过使用 @path/to/file.md 语法导入其他 Markdown 文件来模块化您的上下文文件。有关更多详细信息，请参阅内存导入处理器文档。
内存管理命令：
- 使用 /memory refresh 强制重新扫描并重新加载所有配置位置的所有上下文文件。这将更新 AI 的指令上下文。
- 使用 /memory show 显示当前加载的组合指令上下文，让您验证 AI 使用的分层和内容。
- 有关 /memory 命令及其子命令（show 和 refresh）的完整详细信息，请参阅命令文档。

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

沙箱

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

沙箱默认禁用，但您可以通过以下几种方式启用它：

使用 --sandbox 或 -s 标志。
设置 GEMINI_SANDBOX 环境变量。
默认情况下，使用 --yolo 或 --approval-mode=yolo 时会启用沙箱。

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

对于项目特定的沙箱需求，您可以在项目根目录的 .gemini/sandbox.Dockerfile 创建一个自定义 Dockerfile。此 Dockerfile 可以基于基础沙箱镜像：

dockerfile

FROM gemini-cli-sandbox

# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

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

bash

BUILD_SANDBOX=1 gemini -s

使用统计信息

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

我们收集的内容：

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

我们不收集的内容：

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

如何选择退出：

您可以随时通过在 settings.json 文件中的 privacy 类别下将 usageStatisticsEnabled 属性设置为 false 来选择退出使用统计信息收集：

json

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

Gemini CLI 配置 ​

配置层级 ​

设置文件 ​

项目中的 .gemini 目录 ​

settings.json 中可用的设置 ​

general ​

output ​

ui ​

ide ​

privacy ​

model ​

context ​

tools ​

mcp ​

security ​

advanced ​

mcpServers ​

telemetry ​

settings.json 示例 ​

Shell 历史记录 ​

环境变量和 .env 文件 ​

命令行参数 ​

上下文文件（分层指令上下文） ​

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

沙箱 ​

使用统计信息 ​