Gemini CLI 配置系统深度解析：settings.json 全量设置参考与多作用域合并机制

本文基于 gemini-cli 仓库中 docs/cli/settings.md 的官方设置参考，系统讲解 Gemini CLI 的 /settings 命令与 settings.json 配置体系：包括设置文件的存放位置、多作用域（System / User / Workspace）的合并优先级、全部设置项的完整参数表，以及配置校验、环境变量展开、废弃设置自动迁移等源码级机制。读完后你既能通过 /settings 对话快速调整行为，也能直接手写 settings.json 精确控制模型、工具、安全策略等核心能力。

一、/settings 命令与配置文件位置

Gemini CLI 的几乎所有可调行为都集中在一个 settings.json 文件中。在交互界面中执行 /settings 会打开一个设置对话框，覆盖 UI 外观、按键绑定、可访问性等类别的设置项，对应实现位于 SettingsDialog 组件。

除了对话框，你也可以在以下位置直接编辑 settings.json：

• User settings（用户级）：~/.gemini/settings.json，对用户的所有会话生效；
• Workspace settings（工作区级）：your-project/.gemini/settings.json，只对当前项目生效，且工作区设置覆盖用户设置。

从源码看（settings.ts），除了这两处，系统还支持另外两个作用域：

• System settings（系统级）：Linux 为 /etc/gemini-cli/settings.json，macOS 为 /Library/Application Support/GeminiCli/settings.json，Windows 为 C:\ProgramData\gemini-cli\settings.json，可用环境变量 GEMINI_CLI_SYSTEM_SETTINGS_PATH 覆盖，适合企业统一分发；
• System Defaults（系统默认级）：与系统设置同目录下的 system-defaults.json，可用 GEMINI_CLI_SYSTEM_DEFAULTS_PATH 覆盖。

这四个作用域最终合并成一份生效配置，具体逻辑见下文。

二、多作用域合并优先级与合并策略

在 settings.ts 的 mergeSettings 函数中，优先级（后者优先级更高）被明确注释为：

1. Schema Defaults（内置默认值，来自 settingsSchema 定义）
2. System Defaults
3. User Settings      （~/.gemini/settings.json）
4. Workspace Settings （项目 .gemini/settings.json）
5. System Settings     （作为最高优先级覆盖）

也就是说：内置默认值垫底，用户级覆盖默认值，工作区级覆盖用户级，而系统级配置（如企业管理策略）拥有最终话语权。合并由 customDeepMerge 完成，其特点是：

1. 按路径选择合并策略：每个设置项在 settingsSchema.ts 中声明了 mergeStrategy，可选 REPLACE（默认替换）、CONCAT（数组合并）、UNION（数组去重合并）、SHALLOW_MERGE（对象浅合并）。例如 customIgnoreFilePaths 这类列表设置在不同作用域间会按策略合并而非简单覆盖；
2. 防原型污染：合并时显式跳过 __proto__、constructor、prototype 键，避免恶意配置 JSON 注入原型链；
3. 信任门控：mergeSettings 接受 isTrusted 参数，当工作区未被信任时，工作区设置会被整体替换为空对象（safeWorkspace），即未信任目录下 .gemini/settings.json 不生效——这与 trustedFolders.ts 实现的目录信任机制联动。

此外，setValue 写入任何作用域后都会重算合并结果并广播 CoreEvent.SettingsChanged（settings.ts），UI 通过 useSyncExternalStore 订阅该事件实现设置变更的响应式刷新，因此 /settings 中修改的选项无需重启即可生效（个别声明了 requiresRestart 的设置除外）。

三、设置参考（按对话框分类全量列表）

以下表格完整继承自 docs/cli/settings.md 的自动生成区块（SETTINGS-AUTOGEN 标记之间），按 UI 分组排列。该区块由 generate-settings-doc.ts 从 settingsSchema.ts 自动生成，运行 npm run docs:settings 可重新生成。

General

UI Label	Setting	Description	Default
Vim Mode	general.vimMode	Enable Vim keybindings	false
Default Approval Mode	general.defaultApprovalMode	The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo).	"default"
Enable Auto Update	general.enableAutoUpdate	Enable automatic updates.	true
Enable Terminal Notifications	general.enableNotifications	Enable terminal run-event notifications for action-required prompts and session completion.	false
Terminal Notification Method	general.notificationMethod	How to send terminal notifications.	"auto"
Enable Plan Mode	general.plan.enabled	Enable Plan Mode for read-only safety during planning.	true
Plan Directory	general.plan.directory	The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.	undefined
Plan Model Routing	general.plan.modelRouting	Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.	true
Retry Fetch Errors	general.retryFetchErrors	Retry on "exception TypeError: fetch failed sending request" errors.	true
Max Chat Model Attempts	general.maxAttempts	Maximum number of attempts for requests to the main chat model. Cannot exceed 10.	10
Debug Keystroke Logging	general.debugKeystrokeLogging	Enable debug logging of keystrokes to the console.	false
Enable Session Cleanup	general.sessionRetention.enabled	Enable automatic session cleanup	true
Keep chat history	general.sessionRetention.maxAge	Automatically delete chats older than this time period (e.g., "30d", "7d", "24h", "1w")	"30d"
Topic & Update Narration	general.topicUpdateNarration	Enable the Topic & Update communication model for reduced chattiness and structured progress reporting.	true
Log RAG Snippets	general.logRagSnippets	Log full Code Customization (RAG) retrieved snippets to a local file for debugging.	false

其中 general.defaultApprovalMode 控制工具执行的默认审批模式：default 逐项询问、auto_edit 自动放行编辑类工具、plan 为只读规划模式；而全自动的 YOLO 模式只能通过命令行 --yolo 或 --approval-mode=yolo 开启，不能持久化到设置文件中——这是刻意设计的安全边界。

Output

UI Label	Setting	Description	Default
Output Format	output.format	The format of the CLI output. Can be text or json.	"text"

output.format 主要影响非交互（headless）模式下的输出形态，配合 --output-format json 便于脚本解析。

UI

UI Label	Setting	Description	Default
Auto Theme Switching	ui.autoThemeSwitching	Automatically switch between default light and dark themes based on terminal background color.	true
Terminal Background Polling Interval	ui.terminalBackgroundPollingInterval	Interval in seconds to poll the terminal background color.	60
Hide Window Title	ui.hideWindowTitle	Hide the window title bar	false
Inline Thinking	ui.inlineThinkingMode	Display model thinking inline: off or full.	"off"
Show Thoughts in Title	ui.showStatusInTitle	Show Gemini CLI model thoughts in the terminal window title during the working phase	false
Dynamic Window Title	ui.dynamicWindowTitle	Update the terminal window title with current status icons (Ready: ◇, Action Required: ✋, Working: ✦)	true
Show Home Directory Warning	ui.showHomeDirectoryWarning	Show a warning when running Gemini CLI in the home directory.	true
Show Compatibility Warnings	ui.showCompatibilityWarnings	Show warnings about terminal or OS compatibility issues.	true
Hide Tips	ui.hideTips	Hide helpful tips in the UI	false
Escape Pasted @ Symbols	ui.escapePastedAtSymbols	When enabled, @ symbols in pasted text are escaped to prevent unintended @path expansion.	false
Show Shortcuts Hint	ui.showShortcutsHint	Show the "? for shortcuts" hint above the input.	true
Compact Tool Output	ui.compactToolOutput	Display tool outputs (like directory listings and file reads) in a compact, structured format.	true
Hide Banner	ui.hideBanner	Hide the application banner	false
Hide Context Summary	ui.hideContextSummary	Hide the context summary (GEMINI.md, MCP servers) above the input.	false
Hide CWD	ui.footer.hideCWD	Hide the current working directory in the footer.	false
Hide Sandbox Status	ui.footer.hideSandboxStatus	Hide the sandbox status indicator in the footer.	false
Hide Model Info	ui.footer.hideModelInfo	Hide the model name and context usage in the footer.	false
Hide Context Window Percentage	ui.footer.hideContextPercentage	Hides the context window usage percentage.	true
Hide Footer	ui.hideFooter	Hide the footer from the UI	false
Show Memory Usage	ui.showMemoryUsage	Display memory usage information in the UI	false
Show Line Numbers	ui.showLineNumbers	Show line numbers in the chat.	true
Show Citations	ui.showCitations	Show citations for generated text in the chat.	false
Show Model Info In Chat	ui.showModelInfoInChat	Show the model name in the chat for each model turn.	false
Show User Identity	ui.showUserIdentity	Show the signed-in user's identity (e.g. email) in the UI.	true
Use Alternate Screen Buffer	ui.useAlternateBuffer	Use an alternate screen buffer for the UI, preserving shell history.	false
Render Process	ui.renderProcess	Enable Ink render process for the UI.	true
Terminal Buffer	ui.terminalBuffer	Use the new terminal buffer architecture for rendering.	false
Use Background Color	ui.useBackgroundColor	Whether to use background colors in the UI.	true
Incremental Rendering	ui.incrementalRendering	Enable incremental rendering for the UI. This option will reduce flickering but may cause rendering artifacts. Only supported when useAlternateBuffer is enabled.	true
Show Spinner	ui.showSpinner	Show the spinner during operations.	true
Loading Phrases	ui.loadingPhrases	What to show while the model is working: tips, witty comments, all, or off.	"off"
Error Verbosity	ui.errorVerbosity	Controls whether recoverable errors are hidden (low) or fully shown (full).	"low"
Screen Reader Mode	ui.accessibility.screenReader	Render output in plain-text to be more screen reader accessible	false

值得注意的是 ui.useAlternateBuffer 与 ui.incrementalRendering 的组合：增量渲染只能在启用备用屏幕缓冲区时降低闪烁，二者存在依赖关系。

IDE

UI Label	Setting	Description	Default
IDE Mode	ide.enabled	Enable IDE integration mode.	false

Billing

UI Label	Setting	Description	Default
Overage Strategy	billing.overageStrategy	How to handle quota exhaustion when AI credits are available. 'ask' prompts each time, 'always' automatically uses credits, 'never' disables credit usage.	"ask"

Model

UI Label	Setting	Description	Default
Model	model.name	The Gemini model to use for conversations.	undefined
Max Session Turns	model.maxSessionTurns	Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.	-1
Context Compression Threshold	model.compressionThreshold	The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3).	0.5
Disable Loop Detection	model.disableLoopDetection	Disable automatic detection and prevention of infinite loops.	false
Skip Next Speaker Check	model.skipNextSpeakerCheck	Skip the next speaker check.	true

model.compressionThreshold 决定上下文使用率达到多少比例时触发自动压缩，调低可更早压缩以保留窗口余量。model.name 未设置时使用当前登录方式对应的默认模型。

Agents

UI Label	Setting	Description	Default
Confirm Sensitive Actions	agents.browser.confirmSensitiveActions	Require manual confirmation for sensitive browser actions (e.g., fill_form, evaluate_script).	false
Block File Uploads	agents.browser.blockFileUploads	Hard-block file upload requests from the browser agent.	false

Context

UI Label	Setting	Description	Default
Memory Discovery Max Dirs	context.discoveryMaxDirs	Maximum number of directories to search for memory.	200
Load Memory From Include Directories	context.loadMemoryFromIncludeDirectories	Controls how /memory reload loads GEMINI.md files. When true, include directories are scanned; when false, only the current directory is used.	false
Respect .gitignore	context.fileFiltering.respectGitIgnore	Respect .gitignore files when searching.	true
Respect .geminiignore	context.fileFiltering.respectGeminiIgnore	Respect .geminiignore files when searching.	true
Enable Recursive File Search	context.fileFiltering.enableRecursiveFileSearch	Enable recursive file search functionality when completing @ references in the prompt.	true
Enable Fuzzy Search	context.fileFiltering.enableFuzzySearch	Enable fuzzy search when searching for files.	true
Custom Ignore File Paths	context.fileFiltering.customIgnoreFilePaths	Additional ignore file paths to respect. These files take precedence over .geminiignore and .gitignore. Files earlier in the array take precedence over files later in the array, e.g. the first file takes precedence over the second one.	[]

Tools

UI Label	Setting	Description	Default
Sandbox Allowed Paths	tools.sandboxAllowedPaths	List of additional paths that the sandbox is allowed to access.	[]
Sandbox Network Access	tools.sandboxNetworkAccess	Whether the sandbox is allowed to access the network.	false
Enable Interactive Shell	tools.shell.enableInteractiveShell	Use node-pty for an interactive shell experience. Fallback to child_process still applies.	true
Show Color	tools.shell.showColor	Show color in shell output.	true
Use Ripgrep	tools.useRipgrep	Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.	true
Tool Output Truncation Threshold	tools.truncateToolOutputThreshold	Maximum characters to show when truncating large tool outputs. Set to 0 or negative to disable truncation.	40000
Disable LLM Correction	tools.disableLLMCorrection	Disable LLM-based error correction for edit tools. When enabled, tools will fail immediately if exact string matches are not found, instead of attempting to self-correct.	true

沙箱相关项（tools.sandboxAllowedPaths、tools.sandboxNetworkAccess）与 security.toolSandboxing 共同构成工具隔离策略，默认沙箱无网络访问，可按需在受信任工作区中放开。

Security

UI Label	Setting	Description	Default
Tool Sandboxing	security.toolSandboxing	Tool-level sandboxing. Isolates individual tools instead of the entire CLI process.	false
Disable YOLO Mode	security.disableYoloMode	Disable YOLO mode, even if enabled by a flag.	false
Disable Always Allow	security.disableAlwaysAllow	Disable "Always allow" options in tool confirmation dialogs.	false
Allow Permanent Tool Approval	security.enablePermanentToolApproval	Enable the "Allow for all future sessions" option in tool confirmation dialogs.	false
Auto-add to Policy by Default	security.autoAddToPolicyByDefault	When enabled, the "Allow for all future sessions" option becomes the default choice for low-risk tools in trusted workspaces.	false
Blocks extensions from Git	security.blockGitExtensions	Blocks installing and loading extensions from Git.	false
Extension Source Regex Allowlist	security.allowedExtensions	List of Regex patterns for allowed extensions. If nonempty, only extensions that match the patterns in this list are allowed. Overrides the blockGitExtensions setting.	[]
Folder Trust	security.folderTrust.enabled	Setting to track whether Folder trust is enabled.	true
Enable Environment Variable Redaction	security.environmentVariableRedaction.enabled	Enable redaction of environment variables that may contain secrets.	false
Enable Context-Aware Security	security.enableConseca	Enable the context-aware security checker. This feature uses an LLM to dynamically generate and enforce security policies for tool use based on your prompt, providing an additional layer of protection against unintended actions.	false

security.disableYoloMode 值得单独强调：即使命令行传入 --yolo，只要该设置为 true，YOLO 模式依然会被禁用，因此企业可以在系统级设置中强制关闭高危行为。

Advanced

UI Label	Setting	Description	Default
Auto Configure Max Old Space Size	advanced.autoConfigureMemory	Automatically configure Node.js memory limits. Note: Because memory is allocated during the initial process boot, this setting is only read from the global user settings file and ignores workspace-level overrides.	true
Ignore Local .env	advanced.ignoreLocalEnv	Whether to ignore generic .env files in the project directory.	false

Experimental

UI Label	Setting	Description	Default
Gemma Models	experimental.gemma	Enable access to Gemma 4 models via Gemini API.	true
Voice Mode	experimental.voiceMode	Enable experimental voice dictation and commands (/voice, /voice model).	false
Voice Activation Mode	experimental.voice.activationMode	How to trigger voice recording with the Space key.	"push-to-talk"
Voice Transcription Backend	experimental.voice.backend	The backend to use for voice transcription. Note: When using the Gemini Live backend, voice recordings are sent to Google Cloud for transcription.	"gemini-live"
Whisper Model	experimental.voice.whisperModel	The Whisper model to use for local transcription.	"ggml-base.en.bin"
Voice Stop Grace Period (ms)	experimental.voice.stopGracePeriodMs	How long to wait for final transcription after stopping recording.	4000
Enable Git Worktrees	experimental.worktrees	Enable automated Git worktree management for parallel work.	false
Use OSC 52 Paste	experimental.useOSC52Paste	Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it).	false
Use OSC 52 Copy	experimental.useOSC52Copy	Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it).	false
Model Steering	experimental.modelSteering	Enable model steering (user hints) to guide the model during tool execution.	false
Direct Web Fetch	experimental.directWebFetch	Enable web fetch behavior that bypasses LLM summarization.	false
Enable Gemma Model Router	experimental.gemmaModelRouter.enabled	Enable the Gemma Model Router (experimental). Requires a local endpoint serving Gemma via the Gemini API using LiteRT-LM shim.	false
Auto-start LiteRT Server	experimental.gemmaModelRouter.autoStartServer	Automatically start the LiteRT-LM server when Gemini CLI starts and the Gemma router is enabled.	false
Auto Memory	experimental.autoMemory	Automatically extract memory patches and skills from past sessions in the background. Every change is written as a unified diff .patch file under <projectMemoryDir>/.inbox/<kind>/ and held for review in /memory inbox; nothing is applied until you approve it.	false
Use the generalist profile to manage agent contexts.	experimental.generalistProfile	Suitable for general coding and software development tasks.	false
Enable Context Management	experimental.contextManagement	Enable logic for context management.	false

Skills

UI Label	Setting	Description	Default
Enable Agent Skills	skills.enabled	Enable Agent Skills.	true

HooksConfig

UI Label	Setting	Description	Default
Enable Hooks	hooksConfig.enabled	Canonical toggle for the hooks system. When disabled, no hooks will be executed.	true
Hook Notifications	hooksConfig.notifications	Show visual indicators when hooks are executing.	true

除上述对话框可编辑项外，settings.json 还包含 mcpServers、telemetry、extensions 等手动维护的顶层配置（在文档生成脚本 generate-settings-doc.ts 中被标记为 MANUAL_TOP_LEVEL 而不进入自动表格），完整字段说明参见 docs/reference/configuration.md。

四、配置加载流程：校验、环境变量展开与 .env 加载

从 settings.ts 的 _doLoadSettings 可以看到完整的加载管线：

1. 解析与容错：设置文件先用 stripJsonComments 去除注释再 JSON.parse，因此 settings.json 可以写注释；顶层必须是 JSON 对象，否则记为致命错误并抛出 FatalConfigError，直接阻止启动；
2. 环境变量展开：解析后通过 resolveEnvVarsInObject 展开引用（如 "apiKey": "${GEMINI_API_KEY}"），避免把密钥明文写入文件；
3. Zod 校验：settings-validation.ts 中的 validateSettings 对展开后的结构做严格校验，非法字段会产生 warning 级错误并在 UI 中提示，而不是静默接受；
4. 信任判断先行：首次信任检查只使用 User + System 设置（避免工作区设置自我"洗白"），据此决定工作区设置是否参与合并，随后才调用 loadEnvironment 加载 .env；
5. .env 加载规则（loadEnvironment）：优先查找 工作区/.gemini/.env，其次逐级向上查找 .env；工作区未受信任时只允许白名单变量（GEMINI_API_KEY、GOOGLE_API_KEY、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）且值会被 sanitizeEnvVar 清洗（仅保留字母数字及 -_.\/）以防注入；已存在于进程环境中的变量不会被 .env 覆盖；advanced.ignoreLocalEnv 或 --ignore-env 可跳过项目级 .env。

五、废弃设置的自动迁移

设置体系演进过程中，旧键名会被自动迁移。migrateDeprecatedSettings 在每次加载时对 User / Workspace / System / SystemDefaults 四个作用域执行：

• general.disableAutoUpdate → general.enableAutoUpdate（取反迁移）；
• general.disableUpdateNag → general.enableAutoUpdateNotification；
• ui.accessibility.disableLoadingPhrases → ui.accessibility.enableLoadingPhrases，且 enableLoadingPhrases: false 会迁移为 ui.loadingPhrases: "off"；
• context.fileFiltering.disableFuzzySearch → context.fileFiltering.enableFuzzySearch；
• tools.approvalMode → general.defaultApprovalMode；
• experimental.plan → general.plan.enabled，experimental.codebaseInvestigatorSettings / cliHelpAgentSettings → agents.overrides.*。

迁移对可写作用域会直接改写文件并删除旧键；对只读的系统作用域则发出 warning 提示管理员手工更新。若新旧键同时存在，以新键为准。

六、Schema 单一事实源：JSON Schema 与文档自动生成

整套设置以 settingsSchema.ts 中的 SETTINGS_SCHEMA 为单一事实源：

• Settings TypeScript 类型由该对象的结构推断，/settings 对话框的分组、标签、枚举选项（如 loadingPhrases 的 tips/witty/all/off）、requiresRestart 标记均取自 schema；
• 仓库根目录的 schemas/settings.schema.json 由脚本从同一 schema 导出，可供编辑器做 JSON 补全与校验；
• generate-settings-doc.ts 将 schema 渲染为表格，注入到 docs/cli/settings.md 与 docs/reference/configuration.md 的 SETTINGS-AUTOGEN 标记之间，--check 模式用于 CI 中检测文档漂移；schema 文件头部也明确提示修改设置后应运行 npm run docs:settings。

因此本文的默认值与官方文档始终一致：任何设置变更都必须先改 schema，文档随之再生成。

七、实战示例

在工作区级别启用 Vim 模式、关闭模糊搜索、限制会话轮数，并配置 MCP 服务（手动维护项）：

{
  // 工作区设置：your-project/.gemini/settings.json
  "general": {
    "vimMode": true,
    "plan": { "enabled": true }
  },
  "context": {
    "fileFiltering": { "enableFuzzySearch": false }
  },
  "model": {
    "maxSessionTurns": 30,
    "compressionThreshold": 0.6
  },
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"]
    }
  }
}

而在用户级文件中把安全策略收紧：

{
  // ~/.gemini/settings.json
  "security": {
    "disableYoloMode": true,
    "allowedExtensions": ["^https://registry\\.example\\.com/"]
  },
  "tools": {
    "sandboxNetworkAccess": false
  }
}

若需要企业级统一策略，将同等结构写入系统级路径（如 Linux 的 /etc/gemini-cli/settings.json），它将以最高优先级覆盖所有工作区与用户配置。

小结

Gemini CLI 的配置体系由三个部分组成：以 settingsSchema.ts 为单一事实源的声明式 schema、以 settings.ts 为核心的四作用域加载与合并管线（校验、信任门控、环境展开、废弃迁移），以及 /settings 对话框提供的人机交互入口。日常调整优先用 /settings；批量或企业级管控直接编辑对应作用域的 settings.json；理解合并优先级（System 最终覆盖 Workspace）后再决定配置写在哪一层，就能让每份配置各归其位。