跳到正文
FunCoding

搜索

搜索文档、智能体、博客、Skill 和 MCP

settings.json 与配置层级

Gemini CLI 的配置层级与优先级、settings.json 位置、/settings 命令、设置分类（general、output、ui、context、tools、mcp、security 等）与 .env 文件。

Gemini CLI 提供几种配置其行为的方式：环境变量、命令行参数和设置文件。

配置层级

配置按以下优先顺序应用（编号小的被编号大的覆盖）：

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

设置文件

用 /settings 命令打开对话框查看和编辑所有 Gemini CLI 设置，包括界面体验、键位绑定和无障碍功能。设置存储在 settings.json 文件里，除了 /settings，你也可以在这些位置直接编辑：

  • 用户设置：~/.gemini/settings.json
  • 工作区设置：你的项目/.gemini/settings.json

工作区设置覆盖用户设置。 企业部署时还有系统级的 system-defaults.json（基线）和系统覆盖 settings.json；位置可用 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量覆盖（见「策略引擎与企业配置」）。

设置分类

官方 Settings 页按它们在界面里出现的顺序，列出了所有可用设置（每项有 UI 标签、设置键、说明和默认值）。主要类别和代表性的键：

  • General：general.vimMode（Vim 键位）；general.defaultApprovalMode（工具执行的默认审批模式：default 提示审批、auto_edit 自动批准编辑类工具、plan 只读模式；YOLO 模式只能通过命令行启用）；general.enableAutoUpdate（自动更新）；general.enableNotifications 和 general.notificationMethod（终端运行事件通知）；general.plan.enabled、general.plan.directory、general.plan.modelRouting（计划模式）；general.maxAttempts（对主聊天模型请求的最大尝试次数，不能超过 10）；general.sessionRetention.enabled 和 general.sessionRetention.maxAge（自动清理旧会话，如 "30d"）；general.checkpointing.enabled（检查点）
  • Output：output.format（CLI 输出格式，text 或 json，默认 text）
  • UI：ui.autoThemeSwitching（根据终端背景色自动在默认浅色和深色主题间切换）；ui.inlineThinkingMode（内联显示模型思考：off 或 full）；ui.hideTips、ui.hideBanner、ui.hideContextSummary、ui.footer.*（隐藏各个界面元素）；ui.showLineNumbers、ui.showCitations、ui.showModelInfoInChat；ui.useAlternateBuffer（使用备用屏幕缓冲区，保留 shell 历史）；ui.accessibility.screenReader（以纯文本渲染输出，对屏幕阅读器更友好）
  • Context：context.fileName（上下文文件名，如 GEMINI.md），以及要包含的目录等
  • Tools / Security / MCP / Experimental 等：tools.sandbox（沙箱方式）；security.folderTrust.enabled（文件夹信任）；mcp.* 和 mcpServers（MCP 服务器）；experimental.worktrees（Git worktree）；hooks、agents.overrides 等

完整的键列表、每个键的类型和默认值，以官方 Settings 和 Configuration reference 页为准，用 /settings 可以在界面里搜索。

.env 文件

Gemini CLI 从 .env 文件加载环境变量：从当前目录向上搜索找到的第一个 .env 文件，然后是主目录的 .gemini/.env（如 ~/.gemini/.env）。变量从找到的第一个文件加载，不合并。注意：DEBUG 和 DEBUG_MODE 变量会自动从项目 .env 文件中排除，以免干扰 Gemini CLI 的行为，想用 DEBUG 要放在 .gemini/.env 里，或配置 advanced.excludedEnvVars 设置排除更少的变量。

配置企业环境

在企业里还可以用系统设置文件、策略引擎和 coreTools 白名单等强制策略，见「策略引擎与企业配置」页。