Gemini CLI 配置

关于配置格式，9/17/25 的说明： settings.json 文件的格式已更新为一种新的、更有序的结构。

新格式将从 [09/10/25] 的稳定版本开始支持。

从旧格式自动迁移到新格式的操作将于 [09/17/25] 开始。

有关之前格式的详细信息，请参阅 v1 配置文档。

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

配置层次

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

默认值： 应用程序中固化的默认设置。
系统默认文件： 可以被其他设置文件覆盖的全局默认设置。
用户设置文件： 当前用户的全局设置。
项目设置文件： 项目特定的设置。
系统设置文件： 覆盖所有其他设置文件的全局设置。
环境变量： 可能从 .env 文件加载的系统范围或会话特定的变量。
命令行参数： 启动 CLI 时传递的值。

设置文件

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

提示： JSON 支持的编辑器可以通过指向此仓库中生成的架构 schemas/settings.schema.json 来使用自动完成和验证功能。在仓库外部工作时，请引用托管在 https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.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 和 gemini-extension.json 文件中的字符串值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量。这些变量将在加载设置时自动解析。例如，如果您有一个环境变量 MY_API_TOKEN，您可以在 settings.json 中如下使用它： "apiKey": "$MY_API_TOKEN"。此外，每个扩展可以在其目录中拥有自己的 .env 文件，该文件将被自动加载。

企业用户注意： 有关在企事业单位环境中部署和管理 Gemini CLI 的指导，请参阅企业配置文档。

项目中的 `.gemini` 目录

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

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

`settings.json` 中可用的设置

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

`general`

general.previewFeatures (布尔值)：
- 描述： 启用预览功能（例如，预览模型）。
- 默认值： false
general.preferredEditor (字符串)：
- 描述： 偏好的编辑器用于打开文件。
- 默认值： undefined
general.vimMode (布尔值)：
- 描述： 启用 Vim 键绑定
- 默认值： false
general.disableAutoUpdate (布尔值)：
- 描述： 禁用自动更新
- 默认值： false
general.disableUpdateNag (布尔值)：
- 描述： 禁用更新通知提示。
- 默认值： false
general.checkpointing.enabled (布尔值)：
- 描述： 启用会话检查点以便恢复
- 默认值： false
- 需要重启： 是
general.enablePromptCompletion (布尔值)：
- 描述： 在键入时启用 AI 助力的提示完成建议。
- 默认值： false
- 需要重启： 是
general.retryFetchErrors (布尔值)：
- 描述： 在遇到 “exception TypeError: fetch failed sending request” 错误时重试。
- 默认值： false

以下是翻译后的简体中文文本：

general.debugKeystrokeLogging（布尔值）：

描述： 启用将按键操作记录到控制台的调试日志。
默认值： false

general.sessionRetention.enabled（布尔值）：

描述： 启用自动会话清理。
默认值： false

general.sessionRetention.maxAge（字符串）：

描述： 要保留的会话的最大时长（例如 “30d”、“7d”、“24h”、“1w”）。
默认值： undefined

general.sessionRetention.maxCount（数字）：

描述： 另一种选择：保留的最大会话数量（最近的）。
默认值： undefined

general.sessionRetention.minRetention（字符串）：

描述： 最小保留期限（安全限制，默认为 “1d”）。
默认值： "1d"

`output`

output.format（枚举）：

描述： CLI 输出的格式。
默认值： "text"
值： "text", "json"

`ui`

ui.theme（字符串）：

描述： UI 的颜色主题。有关可用选项，请参阅 CLI 主题指南。
默认值： undefined

ui.customThemes（对象）：

描述： 自定义主题定义。
默认值： {}

ui.hideWindowTitle（布尔值）：

描述： 隐藏窗口标题栏。
默认值： false
需要重启： 是

ui.showStatusInTitle（布尔值）：

描述： 在终端窗口标题中显示 Gemini CLI 状态和思考。
默认值： false

ui.hideTips（布尔值）：

描述： 在 UI 中隐藏有帮助的提示。
默认值： false

ui.hideBanner（布尔值）：

描述： 隐藏应用程序横幅。
默认值： false

ui.hideContextSummary（布尔值）：

描述： 隐藏输入上方的内容摘要（GEMINI.md，MCP 服务器）。
默认值： false

隐藏当前工作目录路径在页脚 (布尔值):

描述: 在页脚中隐藏当前工作目录路径。
默认值: false

隐藏沙盒状态指示器在页脚 (布尔值):

描述: 在页脚中隐藏沙盒状态指示器。
默认值: false

隐藏模型名称和上下文使用在页脚 (布尔值):

描述: 在页脚中隐藏模型名称和上下文使用情况。
默认值: false

隐藏上下文窗口剩余百分比 (布尔值):

描述: 隐藏界面中的上下文窗口剩余百分比。
默认值: true

从界面中隐藏页脚 (布尔值):

描述: 从用户界面中隐藏页脚。
默认值: false

在界面中显示内存使用信息 (布尔值):

描述: 在用户界面中显示内存使用信息。
默认值: false

在聊天中显示行号 (布尔值):

描述: 在聊天中显示行号。
默认值: true

在聊天中为生成的文本显示引用 (布尔值):

描述: 在聊天中为生成的文本显示引用。
默认值: false

在聊天中为每个模型轮次显示模型名称 (布尔值):

描述: 在聊天中为每个模型轮次显示模型名称。
默认值: false

使用终端的整个宽度进行输出 (布尔值):

描述: 使用终端的整个宽度进行输出。
默认值: true

为用户界面使用备用屏幕缓冲区，保留 Shell 历史记录 (布尔值):

描述: 为用户界面使用备用屏幕缓冲区，保留 Shell 历史记录。
默认值: false
需要重启: 是

为用户界面启用增量渲染 (布尔值):

描述: 为用户界面启用增量渲染。此选项将减少闪烁，但可能导致渲染瑕疵。仅在启用 useAlternateBuffer 时支持。
默认值: true
需要重启: 是

自定义加载时显示的俏皮话（array）:

描述： 自定义在加载时显示的俏皮话。如果提供这些话，CLI 将会循环显示这些而不是默认值。
默认值： []

禁用加载时的俏皮话以提高可访问性（boolean）:

描述： 禁用加载时的俏皮话，以提高可访问性。
默认值： false
需要重启： 是

以纯文本形式渲染输出，以便屏幕阅读器更容易访问（boolean）:

描述： 以纯文本形式渲染输出，以便屏幕阅读器更容易访问。
默认值： false
需要重启： 是

`ide`

启用 IDE 集成模式（boolean）:

描述： 启用 IDE 集成模式。
默认值： false
需要重启： 是

用户是否已看到 IDE 集成提示（boolean）:

描述： 用户是否已看到 IDE 集成提示。
默认值： false

`privacy`

启用使用统计信息的收集（boolean）:

描述： 启用使用统计信息的收集。
默认值： true
需要重启： 是

`model`

用于对话的Gemini模型（string）:

描述： 用于对话的Gemini模型。
默认值： undefined

会话中保留的用户/模型/工具回合的最大数量（number）:

描述： 会话中保留的用户/模型/工具回合的最大数量。-1 表示无限。
默认值： -1

对象：

描述： 启用或禁用工具输出的总结。按工具配置令牌预算（例如 {“run_shell_command”: {“tokenBudget”: 2000}}）。目前只有 run_shell_command 工具支持总结。
默认值： undefined

触发上下文压缩的上下文使用率分数（number）:

描述： 触发上下文压缩的上下文使用率分数（例如 0.2，0.3）。
默认值： 0.5
需要重启： 是

【术语表】
- CLI: CLI(命令行界面)
- command-line interface: 命令行界面
- Shell: Shell
- Bash: Bash
- API: API
- endpoint: 端点
- token: 令牌
- Model Context Protocol: 模型上下文协议(MCP)
- MCP: MCP
- Markdown: Markdown
- JSON: JSON
- YAML: YAML
- Mermaid: Mermaid
- npm: npm
- pip: pip
- git: git
- repository: 仓库
- package: 包
- dependency: 依赖
- configuration: 配置
- environment variable: 环境变量
- workspace: 工作空间
- directory: 目录
- file: 文件
- script: 脚本
- plugin: 插件
- extension: 扩展
- integration: 集成
- authentication: 认证
- authorization: 授权
- credential: 凭证
- session: 会话
- context: 上下文
- prompt: 提示词
- completion: 补全
- streaming: 流式
- model: 模型
- provider: 提供商
- service: 服务
- request: 请求
- response: 响应
- header: 头部
- body: 主体
- payload: 负载
- error: 错误
- exception: 异常
- warning: 警告
- debug: 调试
- logging: 日志
- telemetry: 遥测
- analytics: 分析
- monitoring: 监控
- performance: 性能
- latency: 延迟
- throughput: 吞吐量
- concurrency: 并发
- thread: 线程
- process: 进程
- daemon: 守护进程
- background: 背景
- foreground: 前台
- interactive: 交互式
- batch: 批处理
- queue: 队列
- cache: 缓存
- database: 数据库
- storage: 存储
- memory: 内存
- disk: 磁盘
- network: 网络
- protocol: 协议
- HTTP: HTTP
- HTTPS: HTTPS
- WebSocket: WebSocket
- REST: REST
- GraphQL: GraphQL
- RPC: RPC
- SDK: SDK
- library: 库
- framework: 框架
- runtime: 运行时
- build: 构建
- deploy: 部署
- release: 发布
- version: 版本
- changelog: 更新日志
- migration: 迁移
- compatibility: 兼容性
- breaking change: 破坏性变更
- feature: 功能
- bug fix: 错误修复
- improvement: 改进
- enhancement: 增强
- refactor: 重构
- documentation: 文档
- tutorial: 教程
- example: 示例
- demo: 演示
- test: 测试
- unit test: 单元测试

【原文】
- **`model.skipNextSpeakerCheck`** (布尔值):
  - **描述:** 跳过下一次说话者检查。
  - **默认:** `true`

#### `modelConfigs`

- **`modelConfigs.aliases`** (对象):
  - **描述:** 模型配置的命名预设。可以用作模型名称，并可以使用 `extends` 属性从其他别名继承。
  - **默认:**

    ```json
    {
      "base": {
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 0,
            "topP": 1
          }
        }
      },
      "chat-base": {
        "extends": "base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "includeThoughts": true
            },
            "temperature": 1,
            "topP": 0.95,
            "topK": 64
          }
        }
      },
      "chat-base-2.5": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingBudget": 8192
            }
          }
        }
      },
      "chat-base-3": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingLevel": "HIGH"
            }
          }
        }
      },
      "gemini-3-pro-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "gemini-3-pro-preview"
        }
      },
      "gemini-3-flash-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "gemini-3-flash-preview"
        }
      },
      "gemini-2.5-pro": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "gemini-2.5-flash": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "gemini-2.5-flash-lite": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite"
        }
      },
      "gemini-2.5-flash-base": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "classifier": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 1024,
            "thinkingConfig": {
              "thinkingBudget": 512
            }
          }
        }
      },
      "prompt-completion": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "temperature": 0.3,
            "maxOutputTokens": 16000,
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "edit-corrector": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "summarizer-default": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "summarizer-shell": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "web-search": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [
              {
                "googleSearch": {}
              }
            ]
          }
        }
      },
      "web-fetch": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [
              {
                "urlContext": {}
              }
            ]
          }
        }
      },
      "web-fetch-fallback": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection-double-check": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "llm-edit-fixer": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "next-speaker-checker": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "chat-compression-3-pro": {
        "modelConfig": {
          "model": "gemini-3-pro-preview"
        }
      },
      "chat-compression-3-flash": {
        "modelConfig": {
          "model": "gemini-3-flash-preview"
        }
      },
      "chat-compression-2.5-pro": {
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "chat-compression-2.5-flash": {
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "chat-compression-2.5-flash-lite": {
        "modelConfig": {
          "model": "gemini-2.5-flash-lite"
        }
      },
      "chat-compression-default": {
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      }
    }
    ```

- **`modelConfigs.customAliases`** (对象):
  - **描述:** 自定义命名的模型配置预设。这些将与内置别名合并（并覆盖）。
  - **默认:** `{}`

- **`modelConfigs.customOverrides`** (数组):
  - **描述:** 自定义模型配置覆盖。这些将与内置覆盖合并（并添加到）。
  - **默认:** `[]`

- **`modelConfigs.overrides`** (数组):
  - **描述:** 根据匹配项应用特定配置覆盖，主键为模型（或别名）。将使用最具体的匹配项。
  - **默认:** `[]`

#### `context`

- **`context.fileName`** (字符串 | 字符串[]):
  - **描述:** 要加载到内存中的上下文文件或文件的名称。接受单个字符串或字符串数组。
  - **默认:** `undefined`

- **`context.importFormat`** (字符串):
  - **描述:** 导入内存时使用的格式。
  - **默认:** `undefined`

-

【翻译】
- **`context.fileFiltering.respectGitIgnore`**（布尔值）：
  - **描述：** 搜索时尊重 `.gitignore` 文件
  - **默认值：** `true`
  - **需要重启：** 是

- **`context.fileFiltering.respectGeminiIgnore`**（布尔值）：
  - **描述：** 搜索时尊重 `.geminiignore` 文件
  - **默认值：** `true`
  - **需要重启：** 是

- **`context.fileFiltering.enableRecursiveFileSearch`**（布尔值）：
  - **描述：** 在提示中完成 `@` 引用时，启用递归文件搜索功能
  - **默认值：** `true`
  - **需要重启：** 是

- **`context.fileFiltering.disableFuzzySearch`**（布尔值）：
  - **描述：** 在搜索文件时禁用模糊搜索
  - **默认值：** `false`
  - **需要重启：** 是

#### `tools`

- **`tools.sandbox`**（布尔值 | 字符串）：
  - **描述：** 沙盒执行环境。设置为布尔值以启用或禁用沙盒，或提供指向沙盒配置文件的字符串路径
  - **默认值：** `undefined`
  - **需要重启：** 是

- **`tools.shell.enableInteractiveShell`**（布尔值）：
  - **描述：** 使用 node-pty 获取交互式 Shell 体验。仍然会回退到 child_process。
  - **默认值：** `true`
  - **需要重启：** 是

- **`tools.shell.pager`**（字符串）：
  - **描述：** 用于 Shell 输出的分页命令。默认为 `cat`。
  - **默认值：** `"cat"`

- **`tools.shell.showColor`**（布尔值）：
  - **描述：** Shell 输出显示颜色。
  - **默认值：** `false`

- **`tools.shell.inactivityTimeout`**（数字）：
  - **描述：** Shell 命令允许的最大无输出时间（秒）。默认为 5 分钟。
  - **默认值：** `300`

- **`tools.shell.enableShellOutputEfficiency`**（布尔值）：
  - **描述：** 启用 Shell 输出效率优化以获得更好的性能。
  - **默认值：** `true`

**自动接受并执行工具调用** (boolean):
  - **描述:** 自动接受并执行被认为是安全的工具调用（例如，只读操作）。
  - **默认值:** `false`

**内置工具白名单** (array):
  - **描述:** 使用白名单限制内置工具集。匹配语义与 tools.allowed 相同；有关可用的名称，请参阅内置工具文档。
  - **默认值:** `undefined`
  - **需要重启:** 是

**绕过确认对话框的工具名称** (array):
  - **描述:** 绕过确认对话框的工具名称。对于受信任的命令很有用（例如 ["run_shell_command(git)", "run_shell_command(npm test)"]）。有关匹配详情，请参阅 shell 工具命令限制。
  - **默认值:** `undefined`
  - **需要重启:** 是

**从发现中排除的工具名称** (array):
  - **描述:** 从发现中排除的工具名称。
  - **默认值:** `undefined`
  - **需要重启:** 是

**工具发现运行的命令** (string):
  - **描述:** 用于工具发现的命令。
  - **默认值:** `undefined`
  - **需要重启:** 是

**自定义调用发现工具的 Shell 命令** (string):
  - **描述:** 定义一个自定义 shell 命令来调用发现的工具。该命令必须将工具名称作为第一个参数，从 stdin 读取 JSON 参数，并在 stdout 上输出 JSON 结果。
  - **默认值:** `undefined`
  - **需要重启:** 是

**使用 ripgrep 进行文件内容搜索** (boolean):
  - **描述:** 使用 ripgrep 而不是备用实现进行文件内容搜索。提供更快的搜索性能。
  - **默认值:** `true`

**启用大型工具输出的截断** (boolean):
  - **描述:** 启用大型工具输出的截断。
  - **默认值:** `true`
  - **需要重启:** 是

**输出**

- **输出截断长度** (number):
  - **描述：** 如果工具输出超过此字符数，则进行截断。设置为 -1 以禁用。
  - **默认值：** `4000000`
  - **需要重启：** 是

- **保留行数** (number):
  - **描述：** 截断工具输出时保留的行数。
  - **默认值：** `1000`
  - **需要重启：** 是

- **启用钩子系统实验** (boolean):
  - **描述：** 启用钩子系统实验。禁用时，无论其他设置如何，钩子系统都会完全停用。
  - **默认值：** `true`
  - **需要重启：** 是

#### `mcp`

- **启动MCP服务器命令** (string):
  - **描述：** 启动MCP服务器的命令。
  - **默认值：** `undefined`
  - **需要重启：** 是

- **允许的MCP服务器列表** (array):
  - **描述：** 允许的MCP服务器列表。
  - **默认值：** `undefined`
  - **需要重启：** 是

- **排除的MCP服务器列表** (array):
  - **描述：** 排除的MCP服务器列表。
  - **默认值：** `undefined`
  - **需要重启：** 是

#### `useWriteTodos`

- **启用write_todos工具** (boolean):
  - **描述：** 启用 write_todos 工具。
  - **默认值：** `true`

#### `security`

- **禁用YOLO模式** (boolean):
  - **描述：** 即使通过标志启用，也禁用YOLO模式。
  - **默认值：** `false`
  - **需要重启：** 是

- **启用“允许所有未来会话”选项** (boolean):
  - **描述：** 在工具确认对话框中启用“允许所有未来会话”选项。
  - **默认值：** `false`

- **阻止从Git安装和加载扩展** (boolean):
  - **描述：** 阻止从Git安装和加载扩展。
  - **默认值：** `false`
  - **需要重启：** 是

版
本必须与英文版严格对应,不允许增删内容。

【翻译结果】
- CLI: CLI（命令行界面）
- command-line interface: 命令行界面
- Shell: Shell
- Bash: Bash
- API: API
- endpoint: 端点
- token: 令牌
- Model Context Protocol: 模型上下文协议（MCP）
- Markdown: Markdown
- JSON: JSON
- YAML: YAML
- Mermaid: Mermaid
- npm: npm
- pip: pip
- git: git
- repository: 仓库
- package: 包
- dependency: 依赖
- configuration: 配置
- environment variable: 环境变量
- workspace: 工作空间
- directory: 目录
- file: 文件
- script: 脚本
- plugin: 插件
- extension: 扩展
- integration: 集成
- authentication: 认证
- authorization: 授权
- credential: 凭证
- session: 会话
- context: 上下文
- prompt: 提示词
- completion: 补全
- streaming: 流式
- model: 模型
- provider: 提供商
- service: 服务
- request: 请求
- response: 响应
- header: 头部
- body: 主体
- payload: 负载
- error: 错误
- exception: 异常
- warning: 警告
- debug: 调试
- logging: 日志
- telemetry: 遥测
- analytics: 分析
- monitoring: 监控
- performance: 性能
- latency: 延迟
- throughput: 吞吐量
- concurrency: 并发
- thread: 线程
- process: 进程
- daemon: 守护进程
- background: 背景
- foreground: 前台
- interactive: 交互式
- batch: 批处理
- queue: 队列
- cache: 缓存
- database: 数据库
- storage: 存储
- memory: 内存
- disk: 磁盘
- network: 网络
- protocol: 协议
- HTTP: HTTP
- HTTPS: HTTPS
- WebSocket: WebSocket
- REST: REST
- GraphQL: GraphQL
- RPC: RPC
- SDK: SDK
- library: 库
- framework: 框架
- runtime: 运行时
- build: 构建
- deploy: 部署
- release: 发布
- version: 版本
- changelog: 更新日志
- migration: 迁移
- compatibility: 兼容性
- breaking change: 破坏性变更
- feature: 功能
- bug fix: 错误修复
- improvement: 改进
- enhancement: 增强
- refactor: 重构
- documentation: 文档
- tutorial: 教程
- example: 示例
- demo: 演示

【其他内容翻译】
- **```json
    {
      "base": {
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 0,
            "topP": 1
          }
        }
      },
      "chat-base": {
        "extends": "base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "includeThoughts": true
            },
            "temperature": 1,
            "topP": 0.95,
            "topK": 64
          }
        }
      },
      "chat-base-2.5": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingBudget": 8192
            }
          }
        }
      },
      "chat-base-3": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingLevel": "HIGH"
            }
          }
        }
      },
      "gemini-3-pro-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "gemini-3-pro-preview"
        }
      },
      "gemini-3-flash-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "gemini-3-flash-preview"
        }
      },
      "gemini-2.5-pro": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "gemini-2.5-flash": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "gemini-2.5-flash-lite": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite"
        }
      },
      "gemini-2.5-flash-base": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "classifier": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 1024,
            "thinkingConfig": {
              "thinkingBudget": 512
            }
          }
        }
      },
      "prompt-completion": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "temperature": 0.3,
            "maxOutputTokens": 16000,
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "edit-corrector": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "summarizer-default": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "summarizer-shell": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-flash-lite",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "web-search": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [
              {
                "googleSearch": {}
              }
            ]
          }
        }
      },
      "web-fetch": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [
              {
                "urlContext": {}
              }
            ]
          }
        }
      },
      "web-fetch-fallback": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection-double-check": {
        "extends": "base",
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "llm-edit-fixer": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "next-speaker-checker": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "chat-compression-3-pro": {
        "modelConfig": {
          "model": "gemini-3-pro-preview"
        }
      },
      "chat-compression-3-flash": {
        "modelConfig": {
          "model": "gemini-3-flash-preview"
        }
      },
      "chat-compression-2.5-pro": {
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      },
      "chat-compression-2.5-flash": {
        "modelConfig": {
          "model": "gemini-2.5-flash"
        }
      },
      "chat-compression-2.5-flash-lite": {
        "modelConfig": {
          "model": "gemini-2.5-flash-lite"
        }
      },
      "chat-compression-default": {
        "modelConfig": {
          "model": "gemini-2.5-pro"
        }
      }
    }
    ```**:（代码块不翻译）
- “Setting to track whether Folder trust is enabled.”: 设置以跟踪是否启用了文件夹信任。
- “Default: ```json
    ["DEBUG", "DEBUG_MODE"]
    ```”: 默认：```json
    ["DEBUG", "DEBUG_MODE"]
    ```（代码块不翻译）
- “Requires restart: Yes”): 需要重启：是
- “Environment variables to always allow.”: 总是允许的环境变量。
- “Default: ```json
{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "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"]
  }
}
```”): 默认：```json
{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "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"]
  }
}
```（代码块不翻译）
- “Description: The currently selected authentication type.”: 描述：当前选择的认证类型。
- “Default: ```json
{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}
```”): 默认：```json
{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}
```（代码块不翻译）
- “Description: The order in which DNS resolution is attempted for host names.”: 描述：尝试解析主机名时DNS解析的顺序。
- “Default: ```markdown
# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.
```”): 默认：```markdown
# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.
```（代码块不翻译）

请注意，以上翻译结果遵循了您提供的翻译原则，包括代码块的保留、术语一致性、链接URL不翻译等规则。如果需要进一步翻译文档的其他部分，请提供相应的内容。

**布尔值**:
- **描述**: 启用本地和远程子代理。警告：这是一个实验性功能，对子代理使用YOLO模式。
- **默认值**: `false`
- **需要重启**: 是

- **描述**: 启用扩展管理功能。
- **默认值**: `true`
- **需要重启**: 是

- **描述**: 在CLI会话中启用扩展的加载/卸载。
- **默认值**: `false`
- **需要重启**: 是

- **描述**: 启用即时（JIT）上下文加载。
- **默认值**: `false`
- **需要重启**: 是

- **描述**: 启用代理技能（实验性）。
- **默认值**: `false`
- **需要重启**: 是

- **描述**: 启用代码库调查代理。
- **默认值**: `true`
- **需要重启**: 是

**数字**:
- **描述**: 代码库调查代理的最大轮次。
- **默认值**: `10`
- **需要重启**: 是

- **描述**: 代码库调查代理的最大时间（以分钟为单位）。
- **默认值**: `3`
- **需要重启**: 是

- **描述**: 代码库调查代理的思考预算。
- **默认值**: `8192`
- **需要重启**: 是

**字符串**:
- **描述**: 代码库调查代理要使用的模型。
- **默认值**: `"auto"`
- **需要重启**: 是

**布尔值**:
- **描述**: 使用OSC 52序列进行粘贴而不是clipboardy（对于远程会话很有用）。
- **默认值**: `false`

**布尔值** (boolean):
  - **描述:** 启用 CLI 帮助代理。
  - **默认值:** `true`
  - **需要重启:** 是

#### `skills`

- **数组** (array):
  - **描述:** 禁用的技能列表。
  - **默认值:** `[]`
  - **需要重启:** 是

#### `hooks`

- **布尔值** (boolean):
  - **描述:** 钩子系统的规范切换。禁用时，将不执行任何钩子。
  - **默认值:** `false`

- **数组** (array):
  - **描述:** 应该禁用的钩子名称（命令）列表。即使已配置，此列表中的钩子也不会执行。
  - **默认值:** `[]`

- **布尔值** (boolean):
  - **描述:** 当钩子执行时显示视觉指示器。
  - **默认值:** `true`

- **数组** (array):
  - **描述:** 在工具执行之前执行的钩子。可以拦截、验证或修改工具调用。
  - **默认值:** `[]`

- **数组** (array):
  - **描述:** 在工具执行之后执行的钩子。可以处理结果、记录输出或触发后续动作。
  - **默认值:** `[]`

- **数组** (array):
  - **描述:** 在代理循环开始之前执行的钩子。可以设置上下文或初始化资源。
  - **默认值:** `[]`

- **数组** (array):
  - **描述:** 在代理循环完成后执行的钩子。可以执行清理或总结结果。
  - **默认值:** `[]`

- **数组** (array):
  - **描述:** 在通知事件（错误、警告、信息）上执行的钩子。可以在特定条件下记录或警报。
  - **默认值:** `[]`

**会话开始时的钩子** (`session_start`):
  - **描述**: 当会话开始时执行的钩子。可以初始化特定于会话的资源或状态。
  - **默认值**: `[]`

**会话结束时的钩子** (`session_end`):
  - **描述**: 当会话结束时执行的钩子。可以执行清理或持久化会话数据。
  - **默认值**: `[]`

**聊天历史压缩前的钩子** (`before_chat_history_compression`):
  - **描述**: 在聊天历史压缩之前执行的钩子。可以在压缩前备份或分析对话。
  - **默认值**: `[]`

**LLM 请求前的钩子** (`before_LLM_requests`):
  - **描述**: 在 LLM 请求之前执行的钩子。可以修改提示词，注入上下文，或控制模型参数。
  - **默认值**: `[]`

**LLM 响应后的钩子** (`after_LLM_responses`):
  - **描述**: 在 LLM 响应后执行的钩子。可以处理输出，提取信息，或记录交互。
  - **默认值**: `[]`

**工具选择前的钩子** (`before_tool_selection`):
  - **描述**: 在工具选择之前执行的钩子。可以动态地过滤或优先选择可用的工具。
  - **默认值**: `[]`

#### `admin`

- **禁止使用 yolo 模式** (`disallow_yolo_mode`):
  - **描述**: 如果为真，禁止使用 yolo 模式。
  - **默认值**: `false`

- **禁止安装或使用扩展** (`disallow_extensions`):
  - **描述**: 如果为假，禁止安装或使用扩展。
  - **默认值**: `true`

- **禁止使用 MCP 服务器** (`disallow_MCP_servers`):
  - **描述**: 如果为假，禁止使用 MCP 服务器。
  - **默认值**: `true`
  <!-- SETTINGS-AUTOGEN:END -->

#### `mcpServers`

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

**（对象）**: 服务器针对命名服务器的参数。
  - **（字符串，可选）**：通过标准 I/O 启动 MCP 服务器的命令。
  - **（字符串数组，可选）**：传递给命令的参数。
  - **（对象，可选）**：为服务器进程设置的环境变量。
  - **（字符串，可选）**：启动服务器的工作目录。
  - **（字符串，可选）**：使用服务器发送事件（SSE）进行通信的 MCP 服务器的 URL。
  - **（字符串，可选）**：使用可流式 HTTP 进行通信的 MCP 服务器的 URL。
  - **（对象，可选）**：与请求一起发送到 **或** 的 HTTP 头映射。
  - **（数字，可选）**：对此 MCP 服务器请求的超时时间（以毫秒为单位）。
  - **（布尔值，可选）**：信任此服务器并绕过所有工具调用确认。
  - **（字符串，可选）**：服务器的简短描述，可用于显示目的。
  - **（字符串数组，可选）**：从此 MCP 服务器包含的工具名称列表。指定后，只有这里的工具可以从这个服务器使用（白名单行为）。如果未指定，默认启用服务器的所有工具。
  - **（字符串数组，可选）**：要从此 MCP 服务器排除的工具名称列表。这里列出的工具将不可用于模型，即使服务器公开了这些工具。**注意：** 优先于  —— 如果一个工具在两个列表中都存在，它将被排除。

####

配置 Gemini CLI 的日志记录和指标收集。更多信息，请参见 [遥测](../cli/telemetry.md)。

**属性：**
  - **启用遥测** (布尔值)：是否启用遥测功能。
  - **遥测目的地** (字符串)：收集的遥测数据的目的地。支持的值有 `local` 和 `gcp`。
  - **OTLP 导出器端点** (字符串)：OTLP 导出器的端点。
  - **OTLP 导出器协议** (字符串)：OTLP 导出器的协议（`grpc` 或 `http`）。
  - **在日志中包含用户提示内容** (布尔值)：是否在日志中包含用户提示的内容。
  - **遥测写入文件** (字符串)：当 `target` 为 `local` 时，写入遥测数据的文件。
  - **使用外部 OTLP 收集器** (布尔值)：是否使用外部 OTLP 收集器。

### 示例 `settings.json`

以下是一个自 v0.3.0 起新增的具有嵌套结构的 `settings.json` 文件示例：

```json
{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "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 的 API 密钥。
可用的几种认证方法之一。
在您的 shell 配置文件中设置（例如，~/.bashrc，~/.zshrc）或 .env 文件中。

GEMINI_MODEL:

指定要使用的默认 Gemini 模型。
覆盖硬编码的默认值。
示例：export GEMINI_MODEL="gemini-2.5-flash"。

GOOGLE_API_KEY:

您的 Google Cloud API 密钥。
使用 Vertex AI 快速模式时需要。
确保您拥有必要的权限。
示例：export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"。

GOOGLE_CLOUD_PROJECT:

您的 Google Cloud 项目 ID。
使用 Code Assist 或 Vertex AI 时需要。
如果使用 Vertex AI，请确保在此项目中拥有必要的权限。
云壳提示： 在云壳环境中运行时，此变量默认为为云壳用户分配的特殊项目。如果在云壳的全局环境中设置了 GOOGLE_CLOUD_PROJECT，它将被此默认值覆盖。要在云壳中使用不同的项目，必须在 .env 文件中定义 GOOGLE_CLOUD_PROJECT。
示例：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 中遥测的 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 协议（__CODE_BLOCK_384）。

以下是翻译后的简体中文文本：

日志用户提示：
- 设为 true 或 false 以启用或禁用用户提示的日志记录。任何其他值将被视为禁用。
- 覆盖了 telemetry.logPrompts 设置。
GEMINI_TELEMETRY_OUTFILE：
- 当目标为 local 时，设置写入遥测数据的文件路径。
- 覆盖了 telemetry.outfile 设置。
使用外部OTLP收集器：
- 设为 true 或 false 以启用或禁用使用外部OTLP收集器。任何其他值将被视为禁用。
- 覆盖了 telemetry.useCollector 设置。
GOOGLE_CLOUD_LOCATION：
- 您的 Google Cloud 项目位置（例如，us-central1）。
- 在非快速模式下使用 Vertex AI 时需要。
- 示例：export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"。
GEMINI_SANDBOX：
- settings.json 中 sandbox 设置的替代方案。
- 接受 true、false、docker、podman 或自定义命令字符串。
系统提示替代：
- 使用 Markdown 文件中的内容替换内置系统提示。
- true/false：使用项目默认路径 ./.gemini/system.md。
- 任何其他字符串：视为路径（支持相对/绝对路径，~ 展开）。
- default/null 或未设置：使用内置提示。请参阅系统提示替代。
导出系统提示：
- 将当前的内置系统提示写入文件以供审查。
- true/false：写入 ./.gemini/system.md。否则将值视为路径。
- 使用此设置运行 CLI 一次以生成文件。
SEATBELT_PROFILE（仅限 macOS）：
- 在 macOS 上切换 Seatbelt (sandbox-exec) 配置文件。
- default：（默认）限制写入项目文件夹（及少数其他文件夹，请参阅 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：
- 指定代码辅助服务器的端点。
- 这对于开发和测试很有用。

环境变量脱敏

为了防止敏感信息意外泄露，Gemini CLI 在执行工具时（如 shell 命令）会自动从环境变量中脱敏潜在的机密信息。这种“尽力而为”的脱敏适用于从系统继承的变量或从 .env 文件加载的变量。

默认脱敏规则：

按名称： 如果变量的名称包含敏感词汇，如 TOKEN，SECRET，PASSWORD，KEY，AUTH，CREDENTIAL，PRIVATE 或 CERT，则会被脱敏。
按值： 如果变量的值与已知的机密模式匹配，例如：
- 私钥（RSA，OpenSSH，PGP 等）
- 证书
- 包含凭据的 URL
- API 密钥和令牌（GitHub，Google，AWS，Stripe，Slack 等）
特定黑名单： 某些变量如 CLIENT_ID，DB_URI，DATABASE_URL 和 CONNECTION_STRING 默认始终会被脱敏。

白名单（从不脱敏）：

常见系统变量（例如，PATH，HOME，USER，SHELL，TERM，LANG）。
以 GEMINI_CLI_ 开头的变量。
GitHub Action 特定变量。

配置：

您可以在 settings.json 文件中自定义此行为：

security.allowedEnvironmentVariables：一个变量名称列表，即使它们与敏感模式匹配，也从不脱敏。
security.blockedEnvironmentVariables：一个变量名称列表，即使它们不匹配敏感模式，也始终脱敏。

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

命令行参数

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

【翻译】

__CODE_BLOCK_459__ (__CODE_BLOCK_460__):
- 指定此会话要使用的 Gemini 模型。
- 示例：__CODE_BLOCK_461__
__CODE_BLOCK_462__ (__CODE_BLOCK_463__):
- 用于直接向命令传递提示词。这会在非交互模式下调用 Gemini CLI。
- 对于脚本示例，使用 __CODE_BLOCK_464__ 标志以获取结构化输出。
__CODE_BLOCK_465__ (__CODE_BLOCK_466__):
- 使用提供的提示词作为初始输入开始一个交互式会话。
- 提示词将在交互式会话内处理，而不是在会话之前。
- 当从 stdin 管道输入时不能使用。
- 示例：__CODE_BLOCK_467__
__CODE_BLOCK_468__
- **描述：**指定非交互模式下 CLI 输出的格式。
- 值：
  - __CODE_BLOCK_469__：(默认) 标准的人类可读输出。
  - __CODE_BLOCK_470__: 可供机器读取的 JSON 输出。
  - __CODE_BLOCK_471__: 发出实时事件的流式 JSON 输出。
- **注意：**对于结构化输出和脚本编写，请使用 __CODE_BLOCK_472__ 或 __CODE_BLOCK_473__ 标志。
__CODE_BLOCK_474__ (__CODE_BLOCK_475__):
- 为此会话启用沙盒模式。
__CODE_BLOCK_476__ (__CODE_BLOCK_477__):
- 为此会话启用调试模式，提供更详细的信息输出。

以下是翻译后的简体中文文本：

__CODE_BLOCK_478__（或**__CODE_BLOCK_479__**）：

显示关于命令行参数的帮助信息。
__CODE_BLOCK_480__：
- 启用YOLO模式，自动批准所有工具调用。
__CODE_BLOCK_481__：
- 设置工具调用的批准模式。可用模式：
  - __CODE_BLOCK_482__: 每个工具调用时提示批准（默认行为）
  - __CODE_BLOCK_483__: 自动批准编辑工具（replace, write_file），其他工具调用时提示
  - __CODE_BLOCK_484__: 自动批准所有工具调用（等同于__CODE_BLOCK_485__）
- 不能与__CODE_BLOCK_486__一起使用。使用__CODE_BLOCK_487__代替__CODE_BLOCK_488__以实现新的统一方法。
- 示例：__CODE_BLOCK_489__
__CODE_BLOCK_490__：
- 一个逗号分隔的工具名称列表，这些工具将绕过确认对话框。
- 示例：__CODE_BLOCK_491__
__CODE_BLOCK_492__（__CODE_BLOCK_493__）：
- 指定会话要使用的扩展列表。如果未提供，将使用所有可用的扩展。
- 使用特殊术语__CODE_BLOCK_494__以禁用所有扩展。
- 示例：__CODE_BLOCK_495__
__CODE_BLOCK_496__（__CODE_BLOCK_497__）：
- 列出所有可用的扩展并退出。
__CODE_BLOCK_498__（__CODE_BLOCK_499__）：
- 恢复先前的聊天会话。使用“latest”恢复最近的会话，提供会话索引号，或提供完整的会话UUID。
- 如果未提供session_id，默认为“latest”。
- 示例：__CODE_BLOCK_500__或__CODE_BLOCK_501__或__CODE_BLOCK_502__或__CODE_BLOCK_503__
- 有关详细信息，请参阅会话管理。
__CODE_BLOCK_504__：
- 列出当前项目的所有可用聊天会话并退出。
- 显示会话索引、日期、消息计数以及第一条用户消息的预览。
- 示例：__CODE_BLOCK_505__
__CODE_BLOCK_506__：
- 通过索引号删除特定的聊天会话。

选择会话索引或完整的会话 UUID：
- 首先使用 --list-sessions 查看可用的会话、它们的索引和 UUID。
- 示例：gemini --delete-session 3 或 gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890
--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 的版本。
--experimental-acp：
- 以 ACP 模式启动代理。
--allowed-mcp-server-names：
- 允许的 MCP 服务器名称。
--fake-responses：
- 用于测试的包含虚假模型响应的文件路径。
--record-responses：
- 用于记录模型响应以进行测试的文件路径。

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

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

目的： 这些 Markdown 文件包含了您希望 Gemini 模型在交互过程中了解的指令、指南或上下文。系统设计为以分层方式管理此指令上下文。

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

以下是位于 TypeScript 项目根目录的上下文文件的概念示例：

# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

此示例演示了如何提供项目通用上下文、特定的编码约定，甚至关于特定文件或组件的说明。您的上下文文件越相关且精确，AI 的辅助作用就越好。强烈建议使用特定于项目的上下文文件来建立约定和上下文。

分层加载与优先级： CLI 通过从多个位置加载上下文文件（例如，GEMINI.md）实现了一个复杂的分层内存系统。此列表中较低位置的文件（更具体）的内容通常会覆盖或补充较高位置文件（更一般）的内容。可以使用 /memory show 命令检查确切的连接顺序和最终的上下文。典型的加载顺序如下：

全局上下文文件：
- 位置：~/.gemini/<configured-context-filename>（例如，在您的用户主目录中的 ~/.gemini/GEMINI.md）。
- 范围：为您的所有项目提供默认指令。
项目根目录及祖先上下文文件：
- 位置：CLI 在当前工作目录中搜索配置的上下文文件，然后在上层目录中搜索，直至项目根目录（由 .git 文件夹标识）或您的家目录。
- 范围：提供与整个项目或其重要部分相关的上下文。
子目录上下文文件（上下文/本地）：
- 位置：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可以基于基本的沙盒镜像：

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环境变量来自动构建自定义沙盒镜像：

BUILD_SANDBOX=1 gemini -s

使用统计

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

我们收集的内容：

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

我们不收集的内容：

个人信息（PII）: 我们不收集任何个人信息，例如您的姓名、电子邮件地址或API密钥。 提示语和响应内容: 我们不记录您提供的提示语或来自Gemini模型的响应内容。 文件内容: 我们不记录通过CLI读取或写入的任何文件的内容。

如何选择退出:

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

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

Gemini CLI 配置

Gemini CLI 配置

配置层次

设置文件

项目中的 .gemini 目录

settings.json 中可用的设置

general

output

ui

ide

privacy

model

Shell 历史记录

环境变量和 .env 文件

环境变量脱敏

命令行参数

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

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

沙盒环境

使用统计

项目中的 `.gemini` 目录

`settings.json` 中可用的设置

`general`

`output`

`ui`

`ide`

`privacy`

`model`

环境变量和 `.env` 文件

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