Settings

settings.json 是 Gemini CLI 的行为配置入口。它适合放模型、工具、MCP、checkpoint、权限、UI 和其他 CLI 行为开关。

配置入口

Gemini CLI 可以通过 /settings 图形化编辑设置，也可以直接改 JSON 文件。官方路径是：

• 用户级：~/.gemini/settings.json
• 工作区级：<project>/.gemini/settings.json

工作区级会覆盖用户级。这个规则决定了团队项目的推荐做法：个人偏好放用户级，项目约束放仓库内 .gemini/settings.json。

常见配置领域

• general.defaultApprovalMode：默认工具审批模式。日常项目用 default，只读规划用 plan，不要把 yolo 当团队默认值。
• model.name、model.maxSessionTurns、model.compressionThreshold：模型、会话轮数和上下文压缩阈值。
• context.fileName：自定义上下文文件名，比如同时读取 AGENTS.md、CONTEXT.md、GEMINI.md。
• context.fileFiltering.respectGitIgnore：是否让上下文检索尊重 .gitignore。
• mcpServers：项目 MCP 入口，适合放需要随项目一起共享的服务定义。
• security.*：YOLO 禁用、永久授权、扩展来源、文件夹信任、环境变量脱敏等安全开关。
• telemetry.*：OpenTelemetry、本地日志或 Google Cloud telemetry 相关设置。
• ui.*：主题、页脚、模型信息、上下文百分比、可访问性等显示行为。

放置策略

用户级设置只放“我个人在哪个项目都想要”的偏好，例如主题、Vim mode、通知、默认模型。项目级设置只放“换一个人拉仓库也应该一致”的约束，例如 MCP server、工具审批、上下文文件名、安全边界、checkpoint 策略。

密钥不要写进 settings.json。Gemini API key、Google Cloud project、Vertex AI 开关这类运行差异，用环境变量或本机凭据管理。settings.json 进仓库前要按公开资产标准复查，避免把账号、路径、内部服务地址泄露出去。

最小项目模板

真实项目可以先从小模板开始：

{
  "general": {
    "defaultApprovalMode": "default"
  },
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "security": {
    "disableYoloMode": true
  }
}

需要团队共享 MCP 时，再补 mcpServers。需要自动化时，再补 output.format、headless 参数或 telemetry。不要一次复制官方完整 reference；字段越多，排错越难。

改配置的顺序

配置改动建议按这个顺序推进：

1. 先确定这是个人偏好还是项目约束。
2. 再决定写用户级、项目级，还是只用本次 CLI 参数。
3. 修改后重启或重新进入 Gemini CLI。
4. 用 /settings 检查最终生效值。
5. 用一个最小任务触发相关行为，确认不是只写了文件但没有生效。

如果配置项涉及安全、MCP、工具审批或 telemetry，不要只看 JSON 是否合法。必须实际触发一次对应能力：比如让工具请求 shell 执行、查看 MCP server 列表，或确认 telemetry 目标没有把私有内容打出去。

验收方式

改完后重启 Gemini CLI，进入项目目录运行 /settings 检查实际生效值。再让 Gemini CLI 执行一个只读任务，确认它加载的是项目级 MCP、项目级上下文文件名和预期审批模式。涉及安全项时，用一个会触发工具调用的任务验证是否仍然要求确认。

接下来去哪

官方来源

• Gemini CLI settings
• Gemini CLI configuration reference