Gemini CLI settings.json 怎么改:字段与层级封面图
AI 编程约 8 分钟

Gemini CLI settings.json 怎么改:字段与层级

AI 指南··◉ 0 浏览

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 改成别的位置,这在多人共用一台机器的场景下很实用。

Gemini CLI 三层 settings.json 配置文件位置对比图

第一步:定位并打开用户级配置文件

在终端执行下面的命令即可打开(不存在时会自动创建):

  1. mkdir -p ~/.gemini
  2. vim ~/.gemini/settings.json

如果你的机器上还没有这个文件,新建一个空 JSON 再逐节填字段即可。用户级文件几乎能覆盖九成的个人需求。

常用字段实测:认证、主题、上下文与模型

一个能直接用的最小配置长这样。对应关系是:环境变量里解决认证,JSON 里解决行为:

{
  "selectedAuthType": "OAuth",
  "theme": "dark",
  "contextFileName": "GEMINI.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/my/docs"]
    }
  }
}

几个关键字段的说明:

  1. selectedAuthType(认证方式):默认使用 gemini auth login 走账号 OAuth 授权。如果你更想用 API Key 按量付费,先 export GEMINI_API_KEY=你的key 再登录,并把这个字段改为 API_KEY。
  2. theme(主题):可填 dark / light,配合终端明暗切换。部分版本还能识别终端继承的主题。
  3. contextFileName(上下文文件):默认 GEMINI.md,改成 AGENTS.md 就能复用手头已有的编码规则文件,减少重复维护。
  4. 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/settings.json 的截图

怎么验证配置生效了

保存后重新 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 CLI 终端内 /config 查看生效配置的示意

进阶:项目级配置只覆盖差异字段

同一个开发者常在不同仓库使用不同的上下文。你可以在仓库根目录放一份 .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 相关字段指定模型名,重启会话生效;部分版本也能用模型选择命令交互式切换。

项目级和用户级哪个优先

项目级覆盖用户级。若要「全局统一 + 仓库微调」,默认只改用户级,项目级只写仓库独有的字段。

评论 (0)

?
0/1

还没有评论,来发第一条吧

网站上的服务均为第三方提供,
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策