
Gemini CLI settings.json 怎么改:字段与层级
Gemini CLI 的配置集中在一个 settings.json 文件里。这个文件其实有三个层级,弄混了就会遇到「改了没生效」的怪现象。这篇按官方文档的实际字段给你讲清楚:配置文件放在哪、哪个优先级高、哪些字段最值得改、改完怎么验证,文末附 4 个高频报错速查。
前置:先分清三层 settings.json
Gemini CLI 有三个 settings.json,优先级从低到高是用户级、项目级、系统级。改之前先确认你在哪个文件里动手。
- 用户级:位于
~/.gemini/settings.json,作用于当前用户的所有会话,是最常用、通常也唯一需要改的文件。 - 项目级:位于项目根目录的
.gemini/settings.json,只在从该项目启动时生效,并覆盖用户级同名字段。 - 系统级:位于系统全局(如 macOS 的
/Library/Application Support/GeminiCli/settings.json),会覆盖用户级和项目级,通常由企业统一下发,非管理员很少需要碰。
判断一条规则落在哪个层级,记住一句话:项目级最常用来「为某个仓库单独开沙盒或换上下文」,其余默认改用户级。层级间还有一个进阶用法:系统级文件路径可以通过环境变量 GEMINI_CLI_SYSTEM_SETTINGS_PATH 改成别的位置,这在多人共用一台机器的场景下很实用。

第一步:定位并打开用户级配置文件
在终端执行下面的命令即可打开(不存在时会自动创建):
mkdir -p ~/.geminivim ~/.gemini/settings.json
如果你的机器上还没有这个文件,新建一个空 JSON 再逐节填字段即可。用户级文件几乎能覆盖九成的个人需求。
常用字段实测:认证、主题、上下文与模型
一个能直接用的最小配置长这样。对应关系是:环境变量里解决认证,JSON 里解决行为:
{
"selectedAuthType": "OAuth",
"theme": "dark",
"contextFileName": "GEMINI.md",
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/my/docs"]
}
}
}
几个关键字段的说明:
selectedAuthType(认证方式):默认使用gemini auth login走账号 OAuth 授权。如果你更想用 API Key 按量付费,先export GEMINI_API_KEY=你的key再登录,并把这个字段改为API_KEY。theme(主题):可填dark/light,配合终端明暗切换。部分版本还能识别终端继承的主题。contextFileName(上下文文件):默认GEMINI.md,改成AGENTS.md就能复用手头已有的编码规则文件,减少重复维护。mcpServers(MCP 服务器):逐个登记外部工具即可。command与args必须和工具本体的安装命令完全一致,否则连不上。
settings.json 常用字段对照表
| 字段 | 作用 | 示例值 |
|---|---|---|
selectedAuthType |
指定认证方式 | OAuth / API_KEY |
theme |
界面明暗主题 | dark / light |
contextFileName |
上下文文件名 | GEMINI.md / AGENTS.md |
mcpServers |
登记外部 MCP 工具 | filesystem / github |
bugCommand |
覆盖 /bug 跳转地址 | 自定义 issue 模板 URL |
sandbox |
沙盒容器配置 | 自定义 Dockerfile 路径 |
billing |
计费与用量选项 | 按文档配置 |
表中出现的值都可以直接替换使用。$VAR 或 ${VAR} 环境变量语法在 JSON 字符串里同样生效,适合把 API Key 这类敏感信息写在环境变量里而不是写死在文件中,避免把密钥提交进 Git 仓库。

怎么验证配置生效了
保存后重新 gemini 会话,输入 /config 就能看到当前应用到的字段值。想确认主题有没有改过来,直接问一句「当前主题是什么」,回复会调用配置内的字段。若仍显示旧值,九成是项目级或系统级文件把它覆盖了,优先去这两个里排查。
常见报错速查:现象与解法
| 现象 | 原因 | 解法 |
|---|---|---|
| 改了主题没生效 | 上层文件覆盖 | 检查项目级与系统级文件里同名属性 |
| 想用 API Key 却总进浏览器 | 未设置 GEMINI_API_KEY | 先 export 再 gemini auth init 选 key |
| JSON 报 Unexpected token | 多逗号或引号 | 用 jq . 校验 JSON 语法 |
| MCP 工具连不上 | command / args 写错 | 对照官方配置单独跑一遍命令验证 |
字段与路径以官方仓库 google-gemini/gemini-cli 和 Google Cloud Gemini CLI 参考文档 为准,版本迭代时以它们为准核验。

进阶:项目级配置只覆盖差异字段
同一个开发者常在不同仓库使用不同的上下文。你可以在仓库根目录放一份 .gemini/settings.json,只写该仓库想覆盖的少数字段(比如改上下文文件名或关掉某个工具),它在项目级生效且不影响其他项目,优先级高于用户级。这套「用户级放全局 + 项目级放差异」的思路,是团队协作里最不踩雷的写法。
如果你的目标是把 Gemini CLI 接入到自己的编辑器或 MCP 工作流,可以顺带读一下站内的 Gemini CLI 使用教程,模型选择与免费额度参考 Gemini CLI 免费额度说明。
想横向对比两款终端 Agent,可再看 Gemini CLI 与 Claude Code 对比。settings.json 就是它们共同的底座。
常见问题
Gemini CLI 的 settings.json 到底在哪
默认在 `~/.gemini/settings.json`;若项目内放一个 `.gemini/settings.json`,它优先于用户级;系统管理员可在系统级下发并覆盖一切。
改了 settings.json 没反应怎么回事
多半是优先级搞错:项目级或系统级把用户级覆盖了。用 /config 命令查看当前生效项,找到唯一源头再改。
settings.json 里能放环境变量吗
可以。字符串值里用 $VAR 或 ${VAR} 语法会在启动时展开,例如 "apiKey": "$MY_API_TOKEN"。
怎么把默认模型换掉
在用户级 settings.json 里写 model 相关字段指定模型名,重启会话生效;部分版本也能用模型选择命令交互式切换。
项目级和用户级哪个优先
项目级覆盖用户级。若要「全局统一 + 仓库微调」,默认只改用户级,项目级只写仓库独有的字段。

京ICP备2024094994号-29