Gemini CLI 配置

关于已弃用配置格式的说明

本文档描述了 settings.json 文件的旧版 v1 格式。此格式现已弃用。

• 新格式将在 [09/10/25] 开始的稳定版本中支持。
• 从旧格式到新格式的自动迁移将在 [09/17/25] 开始。

有关新的推荐格式的详细信息，请参阅当前配置文档。

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_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 中的可用设置：

• 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（布尔值）：在提示中完成 @ 前缀时是否启用在当前树下递归搜索文件名。
    • disableFuzzySearch（布尔值）：设置为 true 时，禁用搜索文件时的模糊搜索功能，这可以在有大量文件的项目中提高性能。
  • 示例：

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

文件搜索性能故障排除

如果您在文件搜索（例如 @ 补全）方面遇到性能问题，特别是在有大量文件的项目中，您可以按推荐顺序尝试以下几点：

1. 使用 .geminiignore： 在项目根目录创建 .geminiignore 文件，排除包含大量您不需要引用的文件的目录（例如构建产物、日志、node_modules）。减少爬取的文件总数是提高性能最有效的方法。

2. 禁用模糊搜索： 如果忽略文件还不够，您可以在 settings.json 文件中将 disableFuzzySearch 设置为 true 来禁用模糊搜索。这将使用更简单的非模糊匹配算法，速度更快。

3. 禁用递归文件搜索： 作为最后手段，您可以通过将 enableRecursiveFileSearch 设置为 false 来完全禁用递归文件搜索。这将是最快的选项，因为它避免了项目的递归爬取。但是，这意味着在使用 @ 补全时您需要输入文件的完整路径。

• coreTools（字符串数组）：

  • 描述： 允许您指定应该提供给模型的核心工具名称列表。这可以用来限制内置工具集。有关核心工具列表，请参阅内置工具。您还可以为支持它的工具（如 ShellTool）指定命令特定限制。例如，"coreTools": ["ShellTool(ls -l)"] 将只允许执行 ls -l 命令。
  • 默认值： 所有工具都可供 Gemini 模型使用。
  • 示例： "coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]。

• allowedTools（字符串数组）：

  • 默认值： undefined
  • 描述： 将绕过确认对话框的工具名称列表。这对于您信任并经常使用的工具很有用。匹配语义与 coreTools 相同。
  • 示例： "allowedTools": ["ShellTool(git status)"]。

• excludeTools（字符串数组）：

  • 描述： 允许您指定应该从模型中排除的核心工具名称列表。同时列在 excludeTools 和 coreTools 中的工具会被排除。您还可以为支持它的工具（如 ShellTool）指定命令特定限制。例如，"excludeTools": ["ShellTool(rm -rf)"] 将阻止 rm -rf 命令。
  • 默认值：不排除任何工具。
  • 示例： "excludeTools": ["run_shell_command", "findFiles"]。
  • 安全说明： run_shell_command 在 excludeTools 中的命令特定限制基于简单字符串匹配，很容易绕过。此功能不是安全机制，不应依赖它来安全执行不受信任的代码。建议使用 coreTools 明确选择可以执行的命令。

• allowMCPServers（字符串数组）：

  • 描述： 允许您指定应该提供给模型的 MCP 服务器名称列表。这可以用来限制要连接的 MCP 服务器集。注意，如果设置了 --allowed-mcp-server-names，这将被忽略。
  • 默认值： 所有 MCP 服务器都可供 Gemini 模型使用。
  • 示例： "allowMCPServers": ["myPythonServer"]。
  • 安全说明： 这使用对 MCP 服务器名称的简单字符串匹配，可以修改。如果您是系统管理员希望防止用户绕过此限制，请考虑在系统设置级别配置 mcpServers，使用户无法配置自己的任何 MCP 服务器。这不应用作严密的安全机制。

• excludeMCPServers（字符串数组）：

  • 描述： 允许您指定应该从模型中排除的 MCP 服务器名称列表。同时列在 excludeMCPServers 和 allowMCPServers 中的服务器会被排除。注意，如果设置了 --allowed-mcp-server-names，这将被忽略。
  • 默认值：不排除任何 MCP 服务器。
  • 示例： "excludeMCPServers": ["myNodeServer"]。
  • 安全说明： 这使用对 MCP 服务器名称的简单字符串匹配，可以修改。如果您是系统管理员希望防止用户绕过此限制，请考虑在系统设置级别配置 mcpServers，使用户无法配置自己的任何 MCP 服务器。这不应用作严密的安全机制。

• autoAccept（布尔值）：

  • 描述： 控制 CLI 是否自动接受并执行被认为安全的工具调用（例如只读操作），无需明确的用户确认。如果设置为 true，CLI 将绕过被认为安全的工具的确认提示。
  • 默认值： false
  • 示例： "autoAccept": true

• theme（字符串）：

  • 描述： 设置 Gemini CLI 的视觉主题。
  • 默认值： "Default"
  • 示例： "theme": "GitHub"

• vimMode（布尔值）：

  • 描述： 启用或禁用输入编辑的 vim 模式。启用时，输入区域支持带有 NORMAL 和 INSERT 模式的 vim 风格导航和编辑命令。vim 模式状态显示在页脚中并在会话间持续。
  • 默认值： false
  • 示例： "vimMode": true

• 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 工具定义中删除某些架构属性以保持兼容性。必须提供 command、url 或 httpUrl 中的至少一个。如果指定多个，优先级顺序是 httpUrl，然后是 url，然后是 command。
  • 默认值： 空
  • 属性：
    • <SERVER_NAME>（对象）：命名服务器的服务器参数。
      • command（字符串，可选）：通过标准 I/O 启动 MCP 服务器要执行的命令。
      • args（字符串数组，可选）：传递给命令的参数。
      • env（对象，可选）：为服务器进程设置的环境变量。
      • cwd（字符串，可选）：启动服务器的工作目录。
      • url（字符串，可选）：使用服务器发送事件（SSE）进行通信的 MCP 服务器的 URL。
      • httpUrl（字符串，可选）：使用可流式 HTTP 进行通信的 MCP 服务器的 URL。
      • headers（对象，可选）：发送到 url 或 httpUrl 请求的 HTTP 头映射。
      • timeout（数字，可选）：此 MCP 服务器请求的超时时间（毫秒）。
      • trust（布尔值，可选）：信任此服务器并绕过所有工具调用确认。
      • description（字符串，可选）：服务器的简要描述，可用于显示目的。
      • includeTools（字符串数组，可选）：从此 MCP 服务器包含的工具名称列表。指定时，只有此处列出的工具才能从此服务器获得（允许列表行为）。如果未指定，默认情况下启用服务器的所有工具。
      • excludeTools（字符串数组，可选）：从此 MCP 服务器排除的工具名称列表。此处列出的工具将不可用于模型，即使它们被服务器公开。注意： excludeTools 优先于 includeTools - 如果工具在两个列表中，它将被排除。
  • 示例：

    "mcpServers": {
      "myPythonServer": {
        "command": "python",
        "args": ["mcp_server.py", "--port", "8080"],
        "cwd": "./mcp_tools/python",
        "timeout": 5000,
        "includeTools": ["safe_tool", "file_reader"],
      },
      "myNodeServer": {
        "command": "node",
        "args": ["mcp_server.js"],
        "cwd": "./mcp_tools/node",
        "excludeTools": ["dangerous_tool", "file_deleter"]
      },
      "myDockerServer": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"],
        "env": {
          "API_KEY": "$MY_API_TOKEN"
        }
      },
      "mySseServer": {
        "url": "http://localhost:8081/events",
        "headers": {
          "Authorization": "Bearer $MY_SSE_TOKEN"
        },
        "description": "基于 SSE 的 MCP 服务器示例。"
      },
      "myStreamableHttpServer": {
        "httpUrl": "http://localhost:8082/stream",
        "headers": {
          "X-API-Key": "$MY_HTTP_API_KEY"
        },
        "description": "基于可流式 HTTP 的 MCP 服务器示例。"
      }
    }

• 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

• hideTips（布尔值）：

  • 描述： 启用或禁用 CLI 界面中的有用提示。

  • 默认值： false

  • 示例：

    "hideTips": true

• hideBanner（布尔值）：

  • 描述： 启用或禁用 CLI 界面中的启动横幅（ASCII 艺术徽标）。

  • 默认值： false

  • 示例：

    "hideBanner": true

• maxSessionTurns（数字）：

  • 描述： 设置会话的最大轮数。如果会话超过此限制，CLI 将停止处理并开始新的聊天。
  • 默认值： -1（无限制）
  • 示例：

    "maxSessionTurns": 10

• summarizeToolOutput（对象）：

  • 描述： 启用或禁用工具输出的摘要。您可以使用 tokenBudget 设置指定摘要的令牌预算。
  • 注意：目前仅支持 run_shell_command 工具。
  • 默认值： {}（默认禁用）
  • 示例：

    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 2000
      }
    }

• excludedProjectEnvVars（字符串数组）：

  • 描述： 指定应该从项目 .env 文件加载中排除的环境变量。这防止项目特定的环境变量（如 DEBUG=true）干扰 gemini-cli 行为。来自 .gemini/.env 文件的变量永远不会被排除。
  • 默认值： ["DEBUG", "DEBUG_MODE"]
  • 示例：

    "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]

• includeDirectories（字符串数组）：

  • 描述： 指定要包含在工作区上下文中的其他绝对或相对路径数组。缺失的目录默认会被跳过并显示警告。路径可以使用 ~ 引用用户的主目录。此设置可以与 --include-directories 命令行标志结合使用。
  • 默认值： []
  • 示例：

    "includeDirectories": [
      "/path/to/another/project",
      "../shared-library",
      "~/common-utils"
    ]

• loadMemoryFromIncludeDirectories（布尔值）：

  • 描述： 控制 /memory refresh 命令的行为。如果设置为 true，应该从所有添加的目录加载 GEMINI.md 文件。如果设置为 false，应该只从当前目录加载 GEMINI.md。
  • 默认值： false
  • 示例：

    "loadMemoryFromIncludeDirectories": true

• chatCompression（对象）：

  • 描述： 控制聊天历史压缩的设置，包括自动压缩和通过 /compress 命令手动调用时。
  • 属性：
    • contextPercentageThreshold（数字）：介于 0 和 1 之间的值，指定压缩的令牌阈值作为模型总令牌限制的百分比。例如，值 0.6 将在聊天历史超过令牌限制的 60% 时触发压缩。
  • 示例：

    "chatCompression": {
      "contextPercentageThreshold": 0.6
    }

• showLineNumbers（布尔值）：

  • 描述： 控制是否在 CLI 输出的代码块中显示行号。
  • 默认值： true
  • 示例：

    "showLineNumbers": false

• accessibility（对象）：

  • 描述： 配置 CLI 的辅助功能。
  • 属性：
    • screenReader（布尔值）：启用屏幕阅读器模式，调整 TUI 以更好地与屏幕阅读器兼容。这也可以通过 --screen-reader 命令行标志启用，该标志将优先于设置。
    • disableLoadingPhrases（布尔值）：禁用操作期间加载短语的显示。
  • 默认值： {"screenReader": false, "disableLoadingPhrases": false}
  • 示例：

    "accessibility": {
      "screenReader": true,
      "disableLoadingPhrases": true
    }

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,
  "hideTips": false,
  "hideBanner": false,
  "maxSessionTurns": 10,
  "summarizeToolOutput": {
    "run_shell_command": {
      "tokenBudget": 100
    }
  },
  "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"],
  "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
  "loadMemoryFromIncludeDirectories": true
}

Shell 历史

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

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

环境变量和 .env 文件

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

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

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

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

• 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 时需要。
  • 确保您具有必要的权限。
  • 示例：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（字符串）：
  • 描述： 您的 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"。
• 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 或自定义命令字符串。
• 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。
• --prompt-interactive <your_prompt>（-i <your_prompt>）：
  • 使用提供的提示作为初始输入启动交互会话。
  • 提示在交互会话内处理，而不是在会话之前。
  • 从 stdin 管道输入时不能使用。
  • 示例：gemini -i "explain this code"
• --sandbox（-s）：
  • 为此会话启用沙盒模式。
• --sandbox-image：
  • 设置沙盒镜像 URI。
• --debug（-d）：
  • 为此会话启用调试模式，提供更详细的输出。
• --all-files（-a）：
  • 如果设置，递归地将当前目录内的所有文件作为提示的上下文包含。
• --help（或 -h）：
  • 显示有关命令行参数的帮助信息。
• --show-memory-usage：
  • 显示当前内存使用情况。
• --yolo：
  • 启用 YOLO 模式，自动批准所有工具调用。
• --approval-mode <mode>：
  • 设置工具调用的批准模式。可用模式：
    • default：在每个工具调用上提示批准（默认行为）
    • auto_edit：自动批准编辑工具（replace、write_file），同时提示其他工具
    • 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：
  • 启用辅助功能的屏幕阅读器模式。
• --version：
  • 显示 CLI 的版本。

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

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

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

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

以下是 TypeScript 项目根目录的上下文文件可能包含的概念示例：

# 项目：我的出色 TypeScript 库

## 一般指令：

- 生成新 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/<contextFileName>（例如用户主目录中的 ~/.gemini/GEMINI.md）。
     • 范围：为您的所有项目提供默认指令。
  2. 项目根目录和祖先上下文文件：
     • 位置：CLI 在当前工作目录中搜索配置的上下文文件，然后在每个父目录中搜索，直到项目根目录（由 .git 文件夹标识）或您的主目录。
     • 范围：提供与整个项目或其重要部分相关的上下文。
  3. 子目录上下文文件（上下文/本地）：
     • 位置：CLI 还在当前工作目录 下方 的子目录中扫描配置的上下文文件（遵守常见的忽略模式，如 node_modules、.git 等）。此搜索的广度默认限制为 200 个目录，但可以通过 settings.json 文件中的 memoryDiscoveryMaxDirs 字段配置。
     • 范围：允许针对项目的特定组件、模块或子部分的高度具体指令。
• 连接和 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

# 在这里添加您的自定义依赖项或配置
# 例如：
# 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
}