Gemini CLI 的配置体系分为七层，从硬编码默认值到命令行参数依次覆盖。核心配置通过 settings.json 文件管理（4个文件位置），支持通过环境变量（30+个）和命令行参数按会话覆盖。本文是所有配置项的完整中文参考，包括所有分类字段定义、默认值和生效范围。

Gemini CLI 配置完整参考

配置优先级（从低到高）

优先级	来源	说明
1	应用内置默认值	代码中硬编码的默认值
2	系统默认配置文件（`system-defaults.json`）	系统范围的基础默认值
3	用户配置文件（`~/.gemini/settings.json`）	当前用户的全局设置
4	项目配置文件（`.gemini/settings.json`）	当前项目的专属设置
5	系统覆盖文件（`settings.json`）	系统范围的强制覆盖
6	环境变量	会话或系统级变量
7（最高）	命令行参数	单次启动的即时覆盖

配置文件路径

类型	路径	说明
系统默认文件	`/etc/gemini-cli/system-defaults.json`（Linux） `C:\ProgramData\gemini-cli\system-defaults.json`（Windows） `/Library/Application Support/GeminiCli/system-defaults.json`（macOS）	最低优先级，可被所有其他层覆盖
用户配置文件	`~/.gemini/settings.json`	当前用户的全局配置
项目配置文件	`<项目根目录>/.gemini/settings.json`	仅对该项目生效
系统覆盖文件	`/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 环境变量覆盖系统覆盖文件路径。

settings.json 中的环境变量引用：字符串值可使用 $VAR_NAME、${VAR_NAME} 或 ${VAR_NAME:-DEFAULT} 语法引用环境变量，会在加载时自动解析。

settings.json 配置项详解

用 /settings 命令直接在 CLI 内打开设置界面，也可手动编辑文件。

`policyPaths` / `adminPolicyPaths`

字段	类型	默认	说明
`policyPaths`	array	`[]`	额外加载的策略文件或目录路径（需重启）
`adminPolicyPaths`	array	`[]`	额外加载的管理员策略文件或目录（需重启）

`general` — 通用设置

字段	类型	默认	说明
`general.preferredEditor`	string	`undefined`	打开文件时使用的首选编辑器
`general.vimMode`	boolean	`false`	启用 Vim 键位绑定
`general.defaultApprovalMode`	enum	`"default"`	工具执行的默认批准模式：`default`（每次提示）、`auto_edit`（自动批准编辑工具）、`plan`（只读规划模式）。YOLO 模式只能通过命令行启用
`general.devtools`	boolean	`false`	启动时开启 DevTools 检查器
`general.enableAutoUpdate`	boolean	`true`	启用自动更新
`general.enableAutoUpdateNotification`	boolean	`true`	启用更新通知提示
`general.enableNotifications`	boolean	`false`	启用终端运行事件通知
`general.notificationMethod`	enum	`"auto"`	通知方式：`auto`、`osc9`、`osc777`、`bell`
`general.checkpointing.enabled`	boolean	`false`	启用会话检查点（需重启）
`general.plan.enabled`	boolean	`true`	启用 Plan Mode（需重启）
`general.plan.directory`	string	`undefined`	Plan Mode 规划产物的存储目录（需重启）
`general.plan.modelRouting`	boolean	`true`	Plan Mode 期间自动在 Pro/Flash 间路由（规划用 Pro，实现用 Flash）
`general.retryFetchErrors`	boolean	`true`	遇到 `fetch failed` 错误时自动重试
`general.maxAttempts`	number	`10`	主对话模型的最大请求次数，不超过 10
`general.sessionRetention.enabled`	boolean	`true`	启用自动会话清理
`general.sessionRetention.maxAge`	string	`"30d"`	自动删除超过此期限的会话（如 `30d`、`7d`、`24h`）
`general.sessionRetention.maxCount`	number	`undefined`	保留最近 N 个会话（与 maxAge 二选一）
`general.sessionRetention.minRetention`	string	`"1d"`	最短保留期（安全下限，默认 1 天）
`general.topicUpdateNarration`	boolean	`true`	启用主题与更新通信模型，减少冗余输出

`output` — 输出格式

字段	类型	默认	说明
`output.format`	enum	`"text"`	输出格式：`text`（可读文本）或 `json`（JSON）

`ui` — 界面显示

字段	类型	默认	说明
`ui.theme`	string	`undefined`	UI 颜色主题，详见主题定制
`ui.autoThemeSwitching`	boolean	`true`	根据终端背景色自动切换亮色/暗色主题
`ui.customThemes`	object	`{}`	自定义主题定义
`ui.inlineThinkingMode`	enum	`"off"`	内联显示模型思考：`off` 或 `full`
`ui.showStatusInTitle`	boolean	`false`	在终端窗口标题中显示当前状态
`ui.dynamicWindowTitle`	boolean	`true`	动态更新窗口标题（就绪: ◇，等待: ✋，工作中: ✦）
`ui.hideBanner`	boolean	`false`	隐藏启动横幅
`ui.hideTips`	boolean	`false`	隐藏界面提示
`ui.hideFooter`	boolean	`false`	隐藏底部状态栏
`ui.hideContextSummary`	boolean	`false`	隐藏输入框上方的上下文摘要（GEMINI.md、MCP 服务器）
`ui.compactToolOutput`	boolean	`true`	以紧凑格式显示工具输出（文件列表、读取结果等）
`ui.showLineNumbers`	boolean	`true`	在对话中显示行号
`ui.showCitations`	boolean	`false`	显示生成文本的引用来源
`ui.showModelInfoInChat`	boolean	`false`	在对话中显示每轮使用的模型名称
`ui.showUserIdentity`	boolean	`true`	显示已登录用户的身份（如邮箱）
`ui.escapePastedAtSymbols`	boolean	`false`	粘贴文本中的 `@` 符号自动转义，防止意外触发 @path 展开
`ui.loadingPhrases`	enum	`"off"`	模型工作时显示的内容：`tips`、`witty`、`all`、`off`
`ui.customWittyPhrases`	array	`[]`	自定义等待提示语（替换默认提示）
`ui.errorVerbosity`	enum	`"low"`	可恢复错误的显示级别：`low`（隐藏）或 `full`（完整）
`ui.useAlternateBuffer`	boolean	`false`	使用备用屏幕缓冲区，保留 Shell 历史（需重启）
`ui.footer.items`	array	`undefined`	底部状态栏显示的项目 ID 列表
`ui.footer.showLabels`	boolean	`true`	在底部状态栏项目上方显示标签头
`ui.accessibility.screenReader`	boolean	`false`	以纯文本渲染，提升屏幕阅读器兼容性（需重启）

`ide` — IDE 集成

字段	类型	默认	说明
`ide.enabled`	boolean	`false`	启用 IDE 集成模式（需重启）

`privacy` — 隐私

字段	类型	默认	说明
`privacy.usageStatisticsEnabled`	boolean	`true`	启用匿名使用统计收集（需重启）

`billing` — 计费

字段	类型	默认	说明
`billing.overageStrategy`	enum	`"ask"`	配额耗尽时的处理方式：`ask`（每次询问）、`always`（自动使用积分）、`never`（禁止使用积分）
`billing.vertexAi.requestType`	enum	`undefined`	Vertex AI 请求类型：`dedicated` 或 `shared`（需重启）
`billing.vertexAi.sharedRequestType`	enum	`undefined`	Vertex AI 共享请求类型：`priority` 或 `flex`（需重启）

`model` — 模型设置

字段	类型	默认	说明
`model.name`	string	`undefined`	使用的 Gemini 模型名称，如 `gemini-2.5-pro`，`auto` 表示自动选择
`model.maxSessionTurns`	number	`-1`	会话保留的最大对话轮数，-1 为不限制
`model.summarizeToolOutput`	object	`undefined`	工具输出摘要配置，按工具名指定 Token 预算，如 `{"run_shell_command": {"tokenBudget": 2000}}`
`model.compressionThreshold`	number	`0.5`	触发上下文压缩的使用率阈值（需重启）
`model.disableLoopDetection`	boolean	`false`	禁用死循环自动检测（需重启）

`agents` — 代理配置

字段	类型	默认	说明
`agents.overrides`	object	`{}`	特定代理的覆盖配置（需重启）
`agents.browser.sessionMode`	enum	`"persistent"`	浏览器会话模式：`persistent`（持久）、`isolated`（隔离）、`existing`（复用现有）（需重启）
`agents.browser.headless`	boolean	`false`	无头模式运行浏览器（需重启）
`agents.browser.allowedDomains`	array	`["github.com", "*.google.com", "localhost"]`	浏览器代理允许访问的域名列表（需重启）
`agents.browser.maxActionsPerTask`	number	`100`	每次浏览器任务的最大工具调用次数（硬限制）
`agents.browser.confirmSensitiveActions`	boolean	`false`	敏感操作（如表单填写）需要手动确认（需重启）

`context` — 上下文与文件过滤

字段	类型	默认	说明
`context.fileName`	string \| array	`undefined`	上下文文件名，默认为 `GEMINI.md`
`context.includeDirectoryTree`	boolean	`true`	初始请求时是否包含当前目录树
`context.discoveryMaxDirs`	number	`200`	GEMINI.md 发现时的最大目录扫描数
`context.memoryBoundaryMarkers`	array	`[".git"]`	标记记忆发现边界的文件/目录名，向上遍历时在此停止（需重启）
`context.includeDirectories`	array	`[]`	额外包含到工作区上下文的目录
`context.fileFiltering.respectGitIgnore`	boolean	`true`	搜索时遵守 `.gitignore`（需重启）
`context.fileFiltering.respectGeminiIgnore`	boolean	`true`	搜索时遵守 `.geminiignore`（需重启）
`context.fileFiltering.enableFuzzySearch`	boolean	`true`	搜索文件时启用模糊匹配（需重启）
`context.fileFiltering.customIgnoreFilePaths`	array	`[]`	额外的忽略文件路径（优先级高于 .geminiignore）（需重启）

`tools` — 工具控制

字段	类型	默认	说明
`tools.sandbox`	string	`undefined`	沙箱执行环境：`true`/`false`、`"docker"`、`"podman"`、`"lxc"` 或自定义路径（需重启）
`tools.sandboxAllowedPaths`	array	`[]`	沙箱额外允许访问的路径列表（需重启）
`tools.sandboxNetworkAccess`	boolean	`false`	沙箱是否允许网络访问（需重启）
`tools.shell.enableInteractiveShell`	boolean	`true`	使用 node-pty 提供交互式 Shell 体验（需重启）
`tools.shell.backgroundCompletionBehavior`	enum	`"silent"`	后台 Shell 命令完成时的行为：`silent`（静默）、`inject`（自动返回输出）、`notify`（显示简短通知）
`tools.shell.inactivityTimeout`	number	`300`	Shell 命令无输出最大等待时间（秒，默认 5 分钟）
`tools.core`	array	`undefined`	内置工具白名单，只允许列表中的工具（需重启）
`tools.allowed`	array	`undefined`	绕过确认对话框的工具名列表，如 `["run_shell_command(git)"]`（需重启）
`tools.confirmationRequired`	array	`undefined`	始终需要用户确认的工具（优先级高于 allowed）（需重启）
`tools.exclude`	array	`undefined`	禁止发现的工具名列表（已废弃，推荐使用 Policy Engine 的 deny 规则）（需重启）
`tools.useRipgrep`	boolean	`true`	文件内容搜索使用 ripgrep（性能更好）
`tools.truncateToolOutputThreshold`	number	`40000`	截断大型工具输出的最大字符数（0 或负数禁用截断）（需重启）
`tools.disableLLMCorrection`	boolean	`true`	禁用编辑工具的 LLM 自动纠错（需重启）

`mcp` — MCP 服务器管控

字段	类型	默认	说明
`mcp.allowed`	array	`undefined`	MCP 服务器白名单，只允许列表中的服务器（需重启）
`mcp.excluded`	array	`undefined`	MCP 服务器黑名单，排除列表中的服务器（需重启）

`security` — 安全设置

字段	类型	默认	说明
`security.disableYoloMode`	boolean	`false`	禁用 YOLO 模式（即使通过命令行参数也无法启用）（需重启）
`security.disableAlwaysAllow`	boolean	`false`	禁用工具确认对话框中的"始终允许"选项（需重启）
`security.enablePermanentToolApproval`	boolean	`false`	启用"对所有未来会话都允许"选项
`security.toolSandboxing`	boolean	`false`	工具级沙箱隔离（每个工具单独隔离，而非整个 CLI 进程）（需重启）
`security.blockGitExtensions`	boolean	`false`	禁止从 Git 安装和加载扩展（需重启）
`security.allowedExtensions`	array	`[]`	允许的扩展正则模式列表（覆盖 blockGitExtensions）（需重启）
`security.folderTrust.enabled`	boolean	`true`	启用文件夹信任机制（需重启）
`security.environmentVariableRedaction.enabled`	boolean	`false`	启用敏感环境变量自动脱敏（需重启）
`security.environmentVariableRedaction.allowed`	array	`[]`	始终不脱敏的环境变量列表（需重启）
`security.environmentVariableRedaction.blocked`	array	`[]`	始终脱敏的环境变量列表（需重启）
`security.auth.enforcedType`	string	`undefined`	强制认证类型，不匹配时提示重新认证（需重启）
`security.enableConseca`	boolean	`false`	启用基于 LLM 的上下文感知安全检查器（需重启）

`admin` — 管理员专用设置

这些设置通常放在系统级 settings.json 中由管理员配置：

字段	类型	默认	说明
`admin.secureModeEnabled`	boolean	`false`	禁用 YOLO 模式和"始终允许"选项
`admin.extensions.enabled`	boolean	`true`	是否允许安装和使用扩展
`admin.mcp.enabled`	boolean	`true`	是否允许使用 MCP 服务器
`admin.mcp.config`	object	`{}`	管理员配置的 MCP 服务器白名单
`admin.mcp.requiredConfig`	object	`{}`	管理员强制注入的 MCP 服务器
`admin.skills.enabled`	boolean	`true`	是否允许使用 Skills

`advanced` — 高级设置

字段	类型	默认	说明
`advanced.autoConfigureMemory`	boolean	`true`	自动配置 Node.js 内存限制（仅从全局用户配置文件读取）（需重启）
`advanced.excludedEnvVars`	array	`["DEBUG", "DEBUG_MODE"]`	从项目 `.env` 文件排除的环境变量
`advanced.bugCommand`	object	`undefined`	`/bug` 命令的配置（可重定向到内部工单系统）

`experimental` — 实验性功能

字段	类型	默认	说明
`experimental.modelSteering`	boolean	`false`	启用 Model Steering（任务执行中实时引导）
`experimental.worktrees`	boolean	`false`	启用自动 Git Worktree 管理（需重启）
`experimental.enableAgents`	boolean	`true`	启用本地和远程子代理（需重启）
`experimental.gemma`	boolean	`false`	启用 Gemma 4 模型访问（需重启）
`experimental.autoMemory`	boolean	`false`	后台自动从历史会话提取可复用技能（需重启）
`experimental.memoryV2`	boolean	`true`	使用新版记忆机制（通过 edit/write_file 直接管理 GEMINI.md）（需重启）
`experimental.jitContext`	boolean	`true`	启用 JIT 上下文加载（按需加载 GEMINI.md，而非启动时全量加载）（需重启）
`experimental.directWebFetch`	boolean	`false`	绕过 LLM 摘要的直接 Web 抓取（需重启）
`experimental.contextManagement`	boolean	`false`	启用上下文管理逻辑（需重启）
`experimental.taskTracker`	boolean	`false`	启用任务追踪工具（需重启）
`experimental.useOSC52Paste`	boolean	`false`	使用 OSC 52 协议粘贴（远程终端场景）
`experimental.useOSC52Copy`	boolean	`false`	使用 OSC 52 协议复制（远程终端场景）
`experimental.gemmaModelRouter.enabled`	boolean	`false`	启用本地 Gemma 模型路由（需配置本地端点）（需重启）

`skills` — Skills 功能

字段	类型	默认	说明
`skills.enabled`	boolean	`true`	启用 Agent Skills（需重启）
`skills.disabled`	array	`[]`	禁用的 Skills 列表（需重启）

`hooksConfig` — Hooks 系统控制

字段	类型	默认	说明
`hooksConfig.enabled`	boolean	`true`	启用 Hooks 系统（关闭后所有 Hook 停止执行）（需重启）
`hooksConfig.disabled`	array	`[]`	禁用的 Hook 名称列表
`hooksConfig.notifications`	boolean	`true`	Hook 执行时显示视觉指示器

`hooks` — Hook 事件绑定

每个字段都是一个命令数组（Hook 处理器列表）：

字段	触发时机	说明
`hooks.BeforeTool`	工具执行前	可拦截、验证或修改工具调用
`hooks.AfterTool`	工具执行后	处理结果、记录日志或触发后续操作
`hooks.BeforeAgent`	Agent 循环开始前	设置上下文或初始化资源
`hooks.AfterAgent`	Agent 循环完成后	清理或汇总结果
`hooks.Notification`	通知事件时（错误/警告/信息）	日志或告警
`hooks.SessionStart`	会话开始时	初始化会话资源
`hooks.SessionEnd`	会话结束时	清理或持久化会话数据
`hooks.PreCompress`	对话历史压缩前	备份或分析历史
`hooks.BeforeModel`	LLM 请求前	修改 Prompt、注入上下文
`hooks.AfterModel`	LLM 响应后	处理输出或提取信息
`hooks.BeforeToolSelection`	工具选择前	动态过滤可用工具

`mcpServers` — MCP 服务器配置

每个服务器用名称作为 key，值为服务器参数对象。服务器名不能包含下划线（使用连字符，如 my-server）：

json

{
  "mcpServers": {
    "my-server": {
      "command": "bin/mcp_server.py",
      "args": ["--verbose"],
      "env": { "API_KEY": "$MY_API_KEY" },
      "timeout": 5000,
      "trust": false,
      "includeTools": ["tool-a", "tool-b"],
      "excludeTools": ["dangerous-tool"]
    },
    "remote-server": {
      "httpUrl": "https://mcp-server.example.com",
      "headers": { "Authorization": "Bearer $TOKEN" }
    }
  }
}

参数	类型	说明
`command`	string	启动 MCP 服务器的命令（stdio 通信）
`args`	array	传递给命令的参数列表
`env`	object	服务器进程的环境变量
`cwd`	string	服务器启动的工作目录
`url`	string	使用 SSE 通信的 MCP 服务器 URL
`httpUrl`	string	使用可流式 HTTP 通信的 MCP 服务器 URL（优先于 `url` 和 `command`）
`headers`	object	HTTP 请求头（用于 url/httpUrl）
`timeout`	number	请求超时时间（毫秒）
`trust`	boolean	信任该服务器，绕过所有工具调用确认
`includeTools`	array	工具白名单，只暴露列表中的工具
`excludeTools`	array	工具黑名单（优先于 includeTools）

`telemetry` — 遥测配置

字段	类型	说明
`telemetry.enabled`	boolean	是否启用遥测
`telemetry.target`	string	遥测目标：`local`（本地文件）或 `gcp`（Google Cloud）
`telemetry.otlpEndpoint`	string	OTLP 导出器端点，默认 `http://localhost:4317`
`telemetry.otlpProtocol`	string	OTLP 协议：`grpc` 或 `http`
`telemetry.logPrompts`	boolean	是否在日志中包含用户 Prompt 内容（企业环境建议 `false`）
`telemetry.outfile`	string	`target: local` 时的日志输出文件路径
`telemetry.traces`	boolean	是否捕获带大属性的详细 trace（工具输出、文件读取等）默认 `false`

完整示例 settings.json

json

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d"
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "loadingPhrases": "witty"
  },
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 50
  },
  "tools": {
    "sandbox": "docker",
    "allowed": ["run_shell_command(git)"],
    "exclude": []
  },
  "mcpServers": {
    "my-jira": {
      "command": "node",
      "args": ["jira-mcp.js"],
      "timeout": 10000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": "~/.gemini/telemetry.json",
    "logPrompts": false
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

环境变量速查

变量名	说明
`GEMINI_API_KEY`	Gemini API 密钥
`GEMINI_MODEL`	覆盖默认模型，如 `gemini-2.5-pro`
`GEMINI_CLI_HOME`	覆盖用户配置根目录（`.gemini` 的父目录）
`GEMINI_CLI_SYSTEM_SETTINGS_PATH`	覆盖系统覆盖配置文件路径
`GEMINI_CLI_SYSTEM_DEFAULTS_PATH`	覆盖系统默认配置文件路径
`GEMINI_CLI_TRUST_WORKSPACE`	设为 `true` 时信任当前工作区（跳过文件夹信任检查，适合 CI/CD）
`GEMINI_CLI_TRUSTED_FOLDERS_PATH`	覆盖 `trustedFolders.json` 的存储路径
`GEMINI_CLI_IDE_PID`	手动指定关联的 IDE 进程 PID
`GEMINI_CLI_SURFACE`	自定义 User-Agent 标签（用于 API 流量追踪）
`GEMINI_SANDBOX`	沙箱配置：`true`/`false`/`docker`/`podman`/自定义命令
`GEMINI_SYSTEM_MD`	覆盖系统提示词：`true` 使用 `.gemini/system.md`，其他值作为路径
`GEMINI_WRITE_SYSTEM_MD`	将当前内置提示词写入文件（运行一次即生成）
`GEMINI_TELEMETRY_ENABLED`	覆盖 `telemetry.enabled`
`GEMINI_TELEMETRY_TARGET`	覆盖 `telemetry.target`（`local` 或 `gcp`）
`GEMINI_TELEMETRY_OTLP_ENDPOINT`	覆盖 `telemetry.otlpEndpoint`
`GEMINI_TELEMETRY_LOG_PROMPTS`	覆盖 `telemetry.logPrompts`
`GEMINI_TELEMETRY_OUTFILE`	覆盖 `telemetry.outfile`
`GOOGLE_API_KEY`	Google Cloud API 密钥（Vertex AI Express 模式）
`GOOGLE_CLOUD_PROJECT`	Google Cloud 项目 ID（Code Assist 或 Vertex AI）
`GOOGLE_CLOUD_LOCATION`	Google Cloud 区域（Vertex AI 非 Express 模式必填）
`GOOGLE_APPLICATION_CREDENTIALS`	GCP 应用凭据 JSON 文件路径
`GOOGLE_GENAI_API_VERSION`	覆盖 Gemini API 版本（如 `v1`）
`GOOGLE_GEMINI_BASE_URL`	覆盖 Gemini API 基础 URL（用于代理）
`GOOGLE_VERTEX_BASE_URL`	覆盖 Vertex AI API 基础 URL（用于代理）
`OTLP_GOOGLE_CLOUD_PROJECT`	Google Cloud 遥测项目 ID
`SEATBELT_PROFILE`	macOS 沙箱配置文件：`permissive-open`、`restrictive-open`、`strict-open`、自定义
`DEBUG` / `DEBUG_MODE`	启用详细调试日志（默认从项目 .env 排除）
`NO_COLOR`	禁用所有颜色输出
`CLI_TITLE`	自定义 CLI 标题
`BUILD_SANDBOX`	自动构建自定义沙箱镜像（仅源码运行支持）

命令行参数速查

bash

# 基础启动
gemini [提示词]                    # 交互模式，可直接附带初始提示词
gemini -p "提示词"                 # 无头模式（单次提示，已废弃，推荐用 gemini "提示词"）
gemini -i "提示词"                 # 交互模式，提示词作为初始输入

# 模型与模式
gemini --model gemini-2.5-pro     # 指定模型（最高优先级）
gemini --approval-mode auto_edit  # 设置批准模式（default/auto_edit/yolo/plan）
gemini --yolo                     # YOLO 模式（自动批准所有工具）
gemini --sandbox / -s             # 启用沙箱

# 会话管理
gemini --list-sessions            # 列出所有可用会话
gemini --resume [session_id]      # 恢复会话（session_id 可为序号、UUID 或 latest）
gemini --delete-session <id>      # 删除指定会话

# 输出格式
gemini --output-format json       # JSON 输出（适合脚本）
gemini --output-format stream-json # 流式 JSON 输出

# 工具与 MCP
gemini --allowed-tools "run_shell_command(git)"  # 指定绕过确认的工具
gemini --allowed-mcp-server-names "my-server"   # 允许的 MCP 服务器名

# 扩展
gemini -e my-extension            # 使用指定扩展
gemini -e none                    # 禁用所有扩展
gemini --list-extensions          # 列出所有可用扩展

# 目录
gemini --include-directories /path1,/path2  # 包含额外目录（最多 5 个）

# 调试与帮助
gemini --debug / -d               # 启用调试模式
gemini --screen-reader            # 屏幕阅读器模式
gemini --version                  # 显示版本
gemini --help / -h                # 显示帮助

# 高级
gemini --acp                      # 以 ACP 模式启动（IDE 集成）

环境变量脱敏

Gemini CLI 在执行工具时自动脱敏可能包含敏感信息的环境变量。

默认脱敏规则（按名称）：名称包含 TOKEN、SECRET、PASSWORD、KEY、AUTH、CREDENTIAL、PRIVATE、CERT 的变量。

默认脱敏规则（按值）：RSA/OpenSSH/PGP 私钥、证书、包含凭据的 URL、GitHub/Google/AWS/Stripe/Slack 等平台的 API Token。

始终不脱敏：系统变量（PATH、HOME 等）、以 GEMINI_CLI_ 开头的变量、GitHub Actions 变量。

自定义配置：

json

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

GEMINI.md 上下文文件层级

上下文文件（默认名 GEMINI.md，可通过 context.fileName 配置）按以下顺序加载：

全局上下文：~/.gemini/GEMINI.md（对所有项目生效）
项目根及父目录：从当前目录向上查找，到 .git 目录或 home 目录为止
子目录上下文：当前目录下的子目录（最多 200 个，可通过 context.discoveryMaxDirs 配置）

所有找到的文件内容拼接后（附带文件路径标记）作为系统提示词传给模型。使用 /memory show 查看当前加载的完整上下文，用 /memory refresh 强制重新扫描。

沙箱配置

Gemini CLI 可以在沙箱中执行工具，防止意外操作影响系统。默认不启用，可通过以下方式开启：

--sandbox 或 -s 命令行标志
GEMINI_SANDBOX=true 环境变量
--yolo 模式默认启用沙箱

默认使用预置的 gemini-cli-sandbox Docker 镜像。创建项目级自定义 Dockerfile（.gemini/sandbox.Dockerfile）可定制沙箱环境：

dockerfile

FROM gemini-cli-sandbox

# 安装自定义依赖
USER root
RUN apt-get update && apt-get install -y some-package
USER node

常见问题

Q: settings.json 修改后需要重启 CLI 吗？

A: 部分设置标注了"需重启"，修改后需要退出并重新启动 CLI 才能生效。未标注的设置大多可以通过 /settings 命令实时生效，或等下一轮对话时生效。

Q: 如何查看当前所有生效的配置？

A: 使用 /settings 命令可以打开交互式设置界面，查看和修改所有配置项。/memory show 可以查看当前加载的 GEMINI.md 内容。

Q: 项目 settings.json 和用户 settings.json 冲突时以哪个为准？

A: 项目配置（.gemini/settings.json）优先级高于用户配置（~/.gemini/settings.json）。单值字段（如 theme）以更高优先级层为准；数组和对象字段（如 mcpServers）会合并。系统覆盖文件（/etc/gemini-cli/settings.json）优先级最高，覆盖所有其他文件。

Gemini CLI 配置完整参考 ​

配置优先级（从低到高） ​

配置文件路径 ​

settings.json 配置项详解 ​

policyPaths / adminPolicyPaths ​

general — 通用设置 ​

output — 输出格式 ​

ui — 界面显示 ​

ide — IDE 集成 ​

privacy — 隐私 ​

billing — 计费 ​

model — 模型设置 ​

agents — 代理配置 ​

context — 上下文与文件过滤 ​

tools — 工具控制 ​

mcp — MCP 服务器管控 ​

security — 安全设置 ​

admin — 管理员专用设置 ​

advanced — 高级设置 ​

experimental — 实验性功能 ​

skills — Skills 功能 ​

hooksConfig — Hooks 系统控制 ​

hooks — Hook 事件绑定 ​

mcpServers — MCP 服务器配置 ​

telemetry — 遥测配置 ​

完整示例 settings.json ​

环境变量速查 ​

命令行参数速查 ​

环境变量脱敏 ​

GEMINI.md 上下文文件层级 ​

沙箱配置 ​

常见问题 ​

Gemini CLI 配置完整参考

配置优先级（从低到高）

配置文件路径

settings.json 配置项详解

`policyPaths` / `adminPolicyPaths`

`general` — 通用设置

`output` — 输出格式

`ui` — 界面显示

`ide` — IDE 集成

`privacy` — 隐私

`billing` — 计费

`model` — 模型设置

`agents` — 代理配置

`context` — 上下文与文件过滤

`tools` — 工具控制

`mcp` — MCP 服务器管控

`security` — 安全设置

`admin` — 管理员专用设置

`advanced` — 高级设置

`experimental` — 实验性功能

`skills` — Skills 功能

`hooksConfig` — Hooks 系统控制

`hooks` — Hook 事件绑定

`mcpServers` — MCP 服务器配置

`telemetry` — 遥测配置

完整示例 settings.json

环境变量速查

命令行参数速查

环境变量脱敏

GEMINI.md 上下文文件层级

沙箱配置

常见问题