Gemini 3 完整指南（四）：彻底拆解CLI 配置

1. 引言

在前面的博客中，博主已经对 Gemini 做了一些简单的总结，有兴趣的同学可以阅读：

• 《Gemini 3 完整指南（一）：免费订阅、CLI 安装到 Agent 开发一次搞懂》
• 《Gemini 3 完整指南（二）：CLI 官方文档导航与速查索引》
• 《Gemini 3 完整指南（三）：CLI 功能特性及架构解密》

Gemini CLI 提供多种方式来配置其行为，包括环境变量、命令行参数和设置文件，配置按以下优先级顺序应用（较低编号会被较高编号覆盖）：

1. 默认值： 应用内硬编码的默认值。
2. 系统默认文件： 系统范围的默认设置，可被其他设置文件覆盖。
3. 用户设置文件： 当前用户的全局设置。
4. 项目设置文件： 项目特定设置。
5. 系统设置文件： 覆盖所有其他设置文件的系统范围设置。
6. 环境变量： 系统范围或会话特定变量，可能从 .env 文件加载。
7. 命令行参数： 启动 CLI 时传入的值。

2. 配置文件位置

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

【系统默认文件】： 提供一层系统范围的基础默认设置，这些设置的优先级最低，旨在被用户、项目或系统覆盖设置所覆盖。

【用户设置文件】：

• 位置： ~/.gemini/settings.json（其中 ~ 是你的主目录）。
• 作用域： 适用于当前用户的所有 Gemini CLI 会话。用户设置会覆盖系统默认设置。

【项目设置文件】：

• 位置： 项目根目录中的 .gemini/settings.json。
• 作用域： 仅当从该特定项目运行 Gemini CLI 时适用。项目设置会覆盖用户设置和系统默认设置。

除了项目设置文件之外，项目的 .gemini 目录还可以包含其他与 Gemini CLI 运行相关的项目特定文件，例如：自定义沙箱配置文件（.gemini/sandbox-macos-custom.sb、.gemini/sandbox.Dockerfile等）。

【系统设置文件】： 适用于系统上所有用户的所有 Gemini CLI 会话，系统设置作为覆盖项，优先级高于所有其他设置文件。对企业中的系统管理员控制用户的 Gemini CLI 设置可能很有用。

该路径可通过 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量覆盖。

关于设置中的环境变量说明： settings.json 和 gemini-extension.json 文件中的字符串值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量，这些变量会在加载设置时自动解析。例如，如果你有一个环境变量 MY_API_TOKEN，你可以在 settings.json 中这样使用它："apiKey": "$MY_API_TOKEN"。此外，每个扩展都可以在其目录中拥有自己的 .env 文件，并会自动加载。

3. settings.json 中的可用设置

3.1 general

3.2 output

3.3 ui

3.4 ide

3.5 privacy

3.6 model

3.7 modelConfigs

modelConfigs.aliases 示例

   {
     "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"
       }
     }
   }

3.8 agents

3.9 context

3.10 tools

3.11 mcp

3.12 useWriteTodos

3.13 security

3.14 advanced

3.15 experimental

3.16 skills

3.17 hooksConfig

3.18 hooks

3.19 admin

3.20 mcpServers

配置与一个或多个 Model-Context Protocol (MCP) 服务器的连接，用于发现并使用自定义工具。Gemini CLI 会尝试连接到每个已配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器
暴露了同名工具，则工具名称会带上你在配置中定义的服务器别名作为前缀（例如，
serverAlias__actualToolName）以避免冲突。

注意：为了兼容性，系统可能会从 MCP 工具定义中移除某些 schema 属性，必须至少提供 command、url 或 httpUrl 之一，如果指定了多个，优先级顺序为先 httpUrl，再 url，最后 command。

3.21 telemetry

为 Gemini CLI 配置日志记录与指标采集。

4. settings.json 示例

下面是一个具有嵌套结构的 settings.json 文件示例，该结构自v0.3.0 起提供：

{
  "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"]
  }
}

5. 命令历史记录

CLI 会保留你运行过的 shell 命令历史记录。为避免在不同项目之间发生冲突，该历史记录会存储在你用户主目录下的项目专用目录中。

位置： ~/.gemini/tmp/<project_hash>/shell_history

• <project_hash> 是根据你项目的根路径生成的唯一标识符。
• 历史记录存储在名为 shell_history 的文件中。

6. 环境变量

环境变量是配置应用程序的常见方式，尤其适用于API key 等敏感信息，或用于可能因环境不同而变化的设置，CLI 会自动从 .env 文件加载环境变量，加载顺序为：

Step 1. 当前工作目录中的 .env 文件。

Step 2. 若未找到，则向上在父目录中搜索，直到找到
.env 文件或到达项目根目录（由 .git 文件夹标识）或
主目录。

Step 3. 若仍未找到，则查找 ~/.env（位于用户主目录中）。

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

6.1 变量参数

6.2 环境变量脱敏

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

默认打码规则：

• 按名称： 若变量名包含敏感词，如 TOKEN、SECRET、PASSWORD、KEY、AUTH``CREDENTIAL、PRIVATE 或 CERT，则会被打码。
• 按值： 若变量值匹配已知的秘密模式，则会被打码，例如：私钥（RSA、OpenSSH、PGP 等）、证书、包含凭据的 URL、API key 与 token（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"]
  }
}

7. 命令行参数

在运行 CLI 时直接传入的参数可以覆盖该会话中的其他配置。

• --model <model_name> (-m <model_name>):

  • 指定本次会话使用的 Gemini model。
  • 示例：npm start -- --model gemini-3-pro-preview

• --prompt <your_prompt> (-p <your_prompt>):

  • 用于将 prompt 直接传给命令。这会以非交互模式调用 Gemini CLI。
  • 对于脚本示例，使用 --output-format json 标志以获得结构化输出。

• --prompt-interactive <your_prompt> (-i <your_prompt>):

  • 启动交互会话，并将所提供的 prompt 作为初始输入。
  • prompt 会在交互会话中处理，而不是在此之前。
  • 当从 stdin 通过管道传入输入时不可用。
  • 示例：gemini -i "explain this code"

• --output-format <format>:

  • 描述： 指定非交互模式下 CLI 输出的格式。
  • 取值：
    • text:（默认）标准的人类可读输出。
    • json: 机器可读的 JSON 输出。
    • stream-json: 以流式方式输出 JSON，实时发出事件。
  • 注意： 对于结构化输出与脚本编写，请使用 --output-format json 或 --output-format stream-json 标志。

• --sandbox (-s): 为本次会话启用 sandbox 模式。

• --debug (-d): 为本次会话启用 debug 模式，提供更详细的输出。按 F12 打开debug 控制台以查看额外日志。

• --help（或 -h）: 显示命令行参数的帮助信息。

• --yolo: 启用 YOLO 模式，该模式会自动批准所有工具调用。

• --approval-mode <mode>:设置工具调用的批准模式。可用模式：

  • default: 每次工具调用都提示批准（默认行为）

  • auto_edit: 自动批准编辑工具（replace、write_file），其余仍提示

  • yolo: 自动批准所有工具调用（等同于 --yolo）

  • plan: 工具调用只读模式（需要启用实验性 planning）。

    注意： 该模式目前仍在开发中，尚未完全
    可用。

  • 不能与 --yolo 同时使用。新统一方式请使用 --approval-mode=yolo 代替--yolo。

  • 示例：gemini --approval-mode auto_edit

• --allowed-tools <tool1,tool2,...>:

  • 一个以逗号分隔的工具名称列表，将绕过确认对话框。
  • 示例：gemini --allowed-tools "ShellTool(git status)"

• --extensions <extension_name ...> (-e <extension_name ...>):

  • 指定本次会话要使用的扩展列表。若未提供，则使用所有可用扩展。
  • 使用特殊术语 gemini -e none 可禁用所有扩展。
  • 示例：gemini -e my-extension -e my-other-extension

• --list-extensions (-l): 列出所有可用扩展并退出。

• --resume [session_id] (-r [session_id]):

  • 恢复先前的聊天会话。对最近的会话使用 “latest”，提供会话索引编号，或提供完整的会话UUID。
  • 若未提供 session_id，则默认为 “latest”。
  • 示例：gemini --resume 5 或 gemini --resume latest 或 gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 或 gemini --resume

• --list-sessions:

  • 列出当前项目的所有可用聊天会话并退出。
  • 显示会话索引、日期、消息数量，以及第一条用户消息的预览。
  • 示例：gemini --list-sessions

• --delete-session <identifier>:

  • 通过索引编号或完整会话 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 模式启动 agent。

• --allowed-mcp-server-names: 允许的 MCP server 名称。

• --fake-responses: 指向包含伪造 model 响应的文件路径，用于测试。

• --record-responses: 指向用于记录 model 响应的文件路径，用于测试。

8. 上下文件

Context files 虽然并不严格用于配置 CLI 的 _behavior_，但它们（默认使用 GEMINI.md，也可通过 context.fileName 设置配置）对于配置提供给 Gemini model 的 _instructional context_（也称为“memory”）至关重要。这个强大功能允许你提供项目专用说明、编码风格指南或任何相关背景信息，使 AI 的响应更贴合且更准确地满足你的需求，CLI 还包含 UI 元素，例如页脚中的指示器显示已加载的 context files 数量，以便让你了解当前激活的context。

用途： 这些 Markdown 文件包含你希望 Gemini model 在交互期间知晓的说明、指南或 context，系统被设计为以分层方式管理此 instructional context。

8.1 示例 context file 内容

下面是一个概念性示例（例如 GEMINI.md），展示 TypeScript项目根目录中的 context file 可能包含的内容：

# 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.

这个示例展示了你如何提供通用的项目 context、特定的编码规范，甚至关于特定文件或组件的说明。你的 context files 越相关且精确，AI 就越能更好地协助你。强烈建议使用项目专用 context files 来建立约定与 context。

分层加载与优先级： CLI 通过从多个位置加载 context files（例如 GEMINI.md）来实现精巧的分层 memory 系统。该列表中越靠下（越具体）的文件内容通常会覆盖或补充越靠上（越通用）的文件内容。可使用 /memory show 命令检查具体的拼接顺序与最终 context。典型加载顺序为：

1. 全局 context file：
   • 位置：~/.gemini/<configured-context-filename>（例如
     用户主目录中的 ~/.gemini/GEMINI.md）。
   • 作用域：为所有项目提供默认说明。
2. 项目根目录及祖先目录的 context files：
   • 位置：CLI 会在
     当前工作目录中搜索配置的 context file，然后在每个父目录中继续搜索，直到
     项目根目录（由 .git 文件夹标识）或用户主目录。
   • 作用域：为整个项目或其重要部分提供相关 context。
3. 子目录 context files（上下文/本地）：
   • 位置：CLI 还会在
     当前工作目录 下方 的子目录中扫描配置的 context file（遵循 node_modules、.git 等常见
     忽略模式）。该搜索的广度默认限制为 200 个目录，但可通过 settings.json 中的
     context.discoveryMaxDirs 设置进行配置。
   • 作用域：为特定组件、模块或子区域提供高度具体的说明。

拼接与 UI 指示： 所有找到的 context files 的内容会被拼接（并带有分隔符以标明其来源与路径）并作为 system prompt 的一部分提供给 Gemini model。CLI 页脚会显示已加载 context files 的数量，让你能快速直观地了解当前激活的 instructional context。

导入内容： 你可以使用 @path/to/file.md 语法导入其他 Markdown 文件，从而模块化你的 context files。更多细节请参见

用于 memory 管理的命令：

• 使用 /memory refresh 强制重新扫描并重新加载所有 context files（来自所有已配置位置）。这会更新 AI 的 instructional context。
• 使用 /memory show 显示当前加载的 combined instructional context，以便你验证层级与正在被 AI 使用的内容。

通过理解并利用这些配置层与 context files 的分层特性，你可以有效管理 AI 的 memory，并将
Gemini CLI 的响应更好地定制为符合你的特定需求与项目。

9. 沙箱

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

Sandboxing 默认禁用，但你可以通过以下几种方式启用：

• 使用 --sandbox 或 -s 标志。
• 设置 GEMINI_SANDBOX 环境变量。
• 在使用 --yolo 或 --approval-mode=yolo 时默认启用 sandbox。

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

对于项目专用的 sandboxing 需求，你可以在项目根目录创建自定义 Dockerfile，路径为.gemini/sandbox.Dockerfile。该 Dockerfile 可以基于基础 sandbox image：

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环境变量来自动构建自定义sandbox image：

BUILD_SANDBOX=1 gemini -s

10. 使用统计

为了帮助我们改进 Gemini CLI，我们会收集匿名化的 usage statistics。该数据帮助我们了解 CLI 的使用方式、识别常见问题，并确定新功能的优先级。

我们收集的内容：

• 工具调用： 我们记录被调用的工具名称、它们是否成功或失败，以及执行耗时。我们不收集传递给工具的参数或任何返回数据。
• API 请求： 我们记录每次请求所使用的 Gemini model、请求耗时，以及是否成功。我们不收集prompts 或响应的内容。
• 会话信息： 我们收集有关 CLI 配置的信息，例如启用的工具与 approval mode。

我们不收集的内容：

• 个人身份信息（PII）： 我们不收集任何个人信息，例如你的姓名、邮箱地址或 API key。
• Prompt 与响应内容： 我们不会记录 prompts 的内容或 Gemini model 的响应内容。
• 文件内容： 我们不会记录由 CLI 读取或写入的任何文件内容。

如何选择退出：

你可以随时通过将 settings.json 文件中 privacy 类别下的usageStatisticsEnabled 属性设置为 false 来选择退出 usage statistics 收集：

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

11. 文末

到这里，Gemini CLI 的整体配置体系就完整串起来了，理解它的关键，并不是记住所有配置项，而是掌握**“在什么场景下，用哪种方式配置”**，读者们可以按下面这个思路来使用 Gemini CLI：

一、长期稳定的偏好，用 settings.json

如果某个配置 每天都会用、希望一直生效，那就放进 settings.json：

• 常用模型（model.name）
• UI 行为（主题、是否隐藏 Banner、是否显示上下文信息）
• 是否启用 sandbox
• 工具白名单 / 自动批准策略
• 会话保留策略、上下文压缩策略等

个人使用： 放在 ~/.gemini/settings.json

项目使用 / 团队协作： 放在项目根目录 .gemini/settings.json，让所有人 clone 后即生效

二、敏感或环境相关的值，用环境变量

凡是 API Key、Credential、不同机器不一样的配置，都不要写死在配置文件中：

• GEMINI_API_KEY
• GOOGLE_APPLICATION_CREDENTIALS
• Telemetry / Sandbox / Debug 开关
• CI 环境下的特殊参数

推荐做法是：

• 本地：使用 .env 或 shell 配置文件
• 项目：使用 .gemini/.env
• CI/CD：使用平台提供的 Secret / Env 配置

这样既安全，又不会污染仓库。

三、只想临时改一次，用命令行参数

只是这一次想换模型、开 debug、跑脚本，不需要动任何配置文件：

• 临时切模型：--model
• 非交互调用：--prompt
• 机器可读输出：--output-format json
• 强制 sandbox / debug / resume 会话

命令行参数始终拥有最高优先级，适合测试、排错和自动化脚本。

四、真正提升效果的关键 Context Files（GEMINI.md）

如果希望 Gemini 更懂你的项目，而不仅仅是“能回答问题”，那么一定要使用 GEMINI.md 或自定义 context files：

• 项目背景说明
• 编码规范 / 风格约定
• 目录结构说明
• 工具使用约束
• 团队协作规则

这部分内容会作为 system prompt 注入模型，是影响回答质量最直接、性价比最高的配置手段。

五、一句话使用原则

• 默认行为不满意 → settings.json
• 涉及密钥和环境差异 → 环境变量
• 只想改一次 → CLI 参数
• 想让模型“更聪明” → context files

理解并善用这套分层配置机制，就可以把 Gemini CLI 从“能用”，调教到“顺手、可控、可复用”。希望能帮助到大家，感谢阅读，本文完！