Gemini CLI 的所有配置都存储在 ~/.gemini/settings.json（全局）或 项目/.gemini/settings.json（项目级）。本页是完整字段速查表，覆盖 General、UI、Output、MCP 服务器配置等所有选项。项目级配置会覆盖全局配置。

Gemini CLI 配置参考（settings.json）

配置文件位置

作用范围	文件路径
全局（所有项目）	~/.gemini/settings.json
项目级（当前项目）	项目根目录/.gemini/settings.json

项目级配置优先级更高，会覆盖全局配置中的同名字段。

修改配置的方式：

• 直接编辑文件
• 在 REPL 中使用 /settings 命令（图形化设置面板）

General 通用配置

字段	默认值	说明
general.vimMode	false	启用 Vim 键绑定
general.defaultApprovalMode	"default"	默认工具审批模式：default / auto_edit / plan
general.enableAutoUpdate	true	启用自动更新
general.enableNotifications	false	启用终端通知
general.notificationMethod	"auto"	通知方式
general.plan.enabled	true	启用 Plan Mode
general.plan.directory	undefined	计划文件存储目录（未设则用系统临时目录）
general.plan.modelRouting	true	规划阶段用 Pro 模型，执行阶段用 Flash
general.retryFetchErrors	true	遇到 fetch 报错时自动重试
general.maxAttempts	10	主聊天模型的最大重试次数（上限 10）
general.sessionRetention.enabled	true	启用自动清理旧会话
general.sessionRetention.maxAge	"30d"	保留会话时长（如 "7d"、"24h"、"1w"）
general.topicUpdateNarration	true	减少啰嗦输出，启用结构化进度报告

UI 界面配置

字段	默认值	说明
ui.autoThemeSwitching	true	根据终端背景色自动切换亮/暗主题
ui.hideWindowTitle	false	隐藏窗口标题栏
ui.inlineThinkingMode	"off"	显示模型思考过程：off / full
ui.dynamicWindowTitle	true	在终端标题栏显示状态图标（就绪/工作中/需操作）
ui.showHomeDirectoryWarning	true	在家目录运行时显示警告
ui.hideTips	false	隐藏界面中的提示信息
ui.compactToolOutput	true	紧凑模式显示工具输出（列目录、读文件等）
ui.hideBanner	false	隐藏启动 Banner
ui.hideContextSummary	false	隐藏输入框上方的上下文摘要
ui.hideFooter	false	隐藏底部状态栏
ui.showLineNumbers	true	在聊天中显示行号
ui.showUserIdentity	true	显示已登录账号（邮箱）信息
ui.useAlternateBuffer	false	使用交替屏幕缓冲区（保留 shell 历史）
ui.escapePastedAtSymbols	false	粘贴时自动转义 @ 符号，防止误触发文件引用

Output 输出配置

字段	默认值	说明
output.format	"text"	输出格式：text / json

MCP 服务器配置

在 settings.json 中添加 mcpServers 块来配置 MCP 服务器：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "my-http-service": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

详见MCP 服务器接入。

实验性功能

{
  "experimental": {
    "autoMemory": true,
    "worktrees": true
  }
}

字段	默认值	说明
experimental.autoMemory	false	启用 Auto Memory 自动技能提取
experimental.worktrees	false	启用 git worktree 支持（-w 参数）

完整配置示例

{
  "general": {
    "defaultApprovalMode": "auto_edit",
    "plan": {
      "enabled": true,
      "modelRouting": true
    },
    "sessionRetention": {
      "maxAge": "14d"
    }
  },
  "ui": {
    "hideTips": true,
    "hideBanner": true,
    "compactToolOutput": true
  },
  "output": {
    "format": "text"
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "context": {
    "fileName": ["GEMINI.md", "CLAUDE.md"]
  }
}

常见问题

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

A: 大部分 UI 和 General 设置通过 /settings 实时生效；MCP 服务器配置需要 /mcp reload 或重启；实验性功能需要完全重启。

Q: auto_edit 和 default 审批模式有什么差别？

A: default 模式下每次工具调用（包括读文件、写文件、Shell 命令）都询问确认；auto_edit 自动批准文件读写操作，但 Shell 命令和危险操作仍需确认。

Q: 项目级 settings.json 是否应该提交到 git？

A: 建议提交（不含敏感信息的部分）。MCP 服务器配置中用 ${ENV_VAR} 引用环境变量，不会把 token 写入配置文件。团队共享配置有助于统一开发体验。