Gemini CLI 配置

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

配置层

配置按以下优先级顺序应用（数字越小，越会被数字大的覆盖）：

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

设置文件

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

  • 用户设置文件：
    • 位置:~/.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 目录

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

在 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 (字符串数组):

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

  • excludeTools（字符串数组）：

    • **描述：** 允许您指定应从模型中排除的核心工具名称列表。同时出现在 excludeTools 和 coreTools 中的工具将被排除。您还可以为支持该功能的工具指定特定命令的限制，例如 ShellTool。例如， "excludeTools": ["ShellTool(rm -rf)"] 将阻止 rm -rf 命令。
    • **默认值：** 不排除任何工具。
    • 示例： "excludeTools": ["run_shell_command", "findFiles"] .
    • **安全提示：** 特定命令的限制在 excludeTools 对于 run_shell_command 是基于简单的字符串匹配，并且容易被绕过。这个功能 不是一个安全机制 ，不应依赖于它来安全地执行不受信任的代码。建议使用 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 (字符串):

    • 描述: 定义一个自定义 shell 命令，用于调用使用 toolDiscoveryCommand 发现的特定工具。该 shell 命令必须满足以下条件：
    • 默认: 空白
    • 示例: "toolCallCommand": "bin/call_tool"

  • mcpServers (对象):

    • 描述: 配置连接到一个或多个模型上下文协议（MCP）服务器，以发现和使用自定义工具。Gemini CLI 会尝试连接到每个配置的 MCP 服务器以发现可用的工具。如果多个 MCP 服务器公开了同名的工具，则工具名称将使用配置中定义的服务器别名（例如，serverAlias__实际工具名称 ）进行前缀，以避免冲突。 请注意，系统可能会为了兼容性而从 MCP 工具定义中删除某些模式属性。

    • 默认: 空白

    • 属性：

      • <SERVER_NAME>（对象）：指定服务器的参数。
        • command（字符串，必需）：用于启动 MCP 服务器的命令。
        • args（字符串数组，可选）：传递给命令的参数。
        • env（对象，可选）：为服务器进程设置的环境变量。
        • cwd (字符串，可选)：启动服务器的工作目录。
        • timeout (数字，可选)：对此 MCP 服务器的请求的超时时间（毫秒）。
        • trust (布尔值，可选)：信任此服务器并绕过所有工具调用确认。
        • 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"
    }
  }
}

  • 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

示例 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 的您的 API 密钥。
    • 几种可用的认证方法之一。
    • 在您的 shell 配置文件（例如 ~/.bashrc、~/.zshrc）或 .env 文件中设置。
  • GEMINI_MODEL:
    • 指定要使用的默认 Gemini 模型。
    • 覆盖硬编码的默认值
    • 示例： export GEMINI_MODEL="gemini-2.5-flash"
  • GOOGLE_API_KEY:
    • 您的 Google Cloud API 密钥。
    • 在 Express 模式下使用 Vertex AI 时必需。
    • 确保您拥有必要的权限。
    • 示例： export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" 。
  • GOOGLE_CLOUD_PROJECT:
    • 您的 Google Cloud 项目 ID。
    • 使用代码辅助或 Vertex AI 时必需。
    • 如果使用 Vertex AI，请确保您在这个项目中拥有必要的权限。
    • 云 Shell 注意： 在云 Shell 环境中运行时，此变量默认为为云 Shell 用户分配的特殊项目。如果您在云 Shell 的全局环境中设置了 GOOGLE_CLOUD_PROJECT，它将被此默认值覆盖。要在云 Shell 中使用不同的项目，您必须在 .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 项目 ID，用于 Google Cloud 中的遥测
    • 示例： export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" 。
  • GOOGLE_CLOUD_LOCATION:
    • 您的 Google Cloud 项目位置（例如，us-central1）。
    • 在非 express 模式下使用 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 "解释这段代码"
  • --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
  • --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
  • --version：
    • 显示 CLI 的版本。

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

虽然不是严格意义上的 CLI 行为配置，但上下文文件（默认为 GEMINI.md，但可通过 contextFileName 设置进行配置）对于配置提供给 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 命令检查确切的连接顺序和最终上下文。典型的加载顺序是：
    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

# 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 文件中将 usageStatisticsEnabled 属性设置为 false 来选择退出使用统计数据的收集：

{
  "usageStatisticsEnabled": false
}
# AI
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

MCP 加持下的零代码逆向：全自动化绕过 APP 验签与加密实战

本文提出了一种结合Frida动态分析与IDAPro+MCP的移动应用安全测试新方法，通过AI自动化分析加密与签名逻辑，实现对高防护APP的高效逆向工程。文章首先识别了请求体加密与请求头签名的防护特征，然后利用Frida脚本定位关键加密点，获取AES密钥和签名参数。针对混淆代码，采用MCP技术让AI自动解析参数排序和拼接逻辑。最后通过AI生成的Python中间件脚本，实现BurpSuite请求的自动

avatar 2048 AI社区
cover

2026年创业之年，AI时代一人公司、小规模团队如何快速收入百万美元？

avatar 2048 AI社区
cover

【愚公系列】《AI+直播营销》020-直播的选品策略（供应链的需求和供给管理）

avatar 2048 AI社区