1. 第一次跑 Gemini CLI为什么配置总是对不上很多人第一次装完 Gemini CLI敲下gemini之后遇到的不是「模型开始回答」而是一连串让人摸不着头脑的现象明明在.env里写了GEMINI_API_KEYCLI 却提示没有认证在settings.json里改了主题重启后还是老样子命令行加了--model结果会话里用的还是默认模型。这些问题的根源几乎都指向同一件事——Gemini CLI 的配置是有层级的不同来源的配置会互相覆盖。Gemini CLI 的配置体系可以类比成「洋葱模型」。最里面是程序硬编码的默认值往外依次是用户设置文件、项目设置文件、系统设置文件、环境变量最外层是命令行参数。越靠外层优先级越高越能覆盖内层。你写的东西没生效大概率是被更外层的东西盖掉了或者你写错了层。这篇指南面向第一次上手 Gemini CLI 的开发者把三件事讲透settings.json里到底有哪些字段值得配、环境变量的加载顺序和优先级怎么算、命令行参数如何临时覆盖前两者。每一节都给出可以直接复制的配置片段和逐项验证命令跑一遍就能确认自己的配置到底生效在哪一层。如果你正在用 Gemini CLI 做日常编码或者准备把它接进团队的项目流程这套配置逻辑值得先花二十分钟理清楚后面能省下大量「为什么又不生效」的排查时间。需要先说明的是Gemini CLI 默认走的是官方端点。如果你希望用统一的入口管理多个模型的调用、把 API Key 集中托管可以把它指向兼容的 API 网关。本文的配置示例会以标准字段为主你替换 Base URL 和 Key 即可字段结构完全一致。2. settings.json 字段全解析与可复制配置片段settings.json是 Gemini CLI 持久化配置的核心。它有三个位置优先级从低到高分别是用户级~/.gemini/settings.json、项目级项目根/.gemini/settings.json、系统级/etc/gemini-cli/settings.jsonLinux、C:\ProgramData\gemini-cli\settings.jsonWindows、/Library/Application Support/GeminiCli/settings.jsonmacOS。系统级路径可以用GEMINI_CLI_SYSTEM_SETTINGS_PATH环境变量覆盖。一个容易踩的坑项目级会覆盖用户级系统级会覆盖用户级和项目级。所以如果你在用户级配了theme项目里又配了另一个进项目后看到的是项目里的那个。排查「配置不生效」时第一件事就是确认当前生效的是哪一层。下面是一份可以直接复制、覆盖大部分常用场景的settings.json。我把它放在项目根目录的.gemini/settings.json这样只对当前项目生效不会污染全局。{ theme: GitHub, contextFileName: [GEMINI.md, AGENTS.md], fileFiltering: { respectGitIgnore: true, enableRecursiveFileSearch: true }, coreTools: [ReadFileTool, GlobTool, ShellTool(ls)], excludeTools: [ShellTool(rm -rf)], autoAccept: false, vimMode: false, sandbox: docker, checkpointing: { enabled: true }, preferredEditor: vscode, maxSessionTurns: 30, summarizeToolOutput: { run_shell_command: { tokenBudget: 2000 } }, excludedProjectEnvVars: [DEBUG, DEBUG_MODE, NODE_ENV], includeDirectories: [../shared-library, ~/common-utils], loadMemoryFromIncludeDirectories: true, chatCompression: { contextPercentageThreshold: 0.6 }, showLineNumbers: true, usageStatisticsEnabled: false, hideTips: false, hideBanner: false, mcpServers: { myPythonServer: { command: python, args: [mcp_server.py, --port, 8080], cwd: ./mcp_tools/python, timeout: 5000, includeTools: [safe_tool, file_reader] } } }逐项说明几个最值得关注的字段。contextFileName决定 CLI 去读哪个上下文文件默认是GEMINI.md你可以改成数组同时接受AGENTS.md方便和别的工具共用一份指令。fileFiltering.respectGitIgnore设为true时node_modules/、dist/、.env这些被 git 忽略的文件会自动从补全和文件发现里排除避免把一堆无关文件塞进上下文。coreTools是白名单只把列出的工具给模型excludeTools是黑名单。注意官方明确提示excludeTools对run_shell_command的命令限制是基于简单字符串匹配的容易被绕过它不是安全机制真正要限制就用coreTools显式选择。mcpServers用来接 MCP 服务器。每个服务器可以配command、args、env、cwd、timeout、trust以及includeTools/excludeTools做工具级白名单和黑名单。当多个服务器暴露同名工具时CLI 会用服务器别名做前缀比如serverAlias__实际工具名避免冲突。excludeTools优先于includeTools同时出现在两个列表里的工具会被排除。还有一个很实用的特性settings.json里的字符串值可以用$VAR_NAME或${VAR_NAME}引用环境变量加载时自动解析。比如{ mcpServers: { myDockerServer: { command: docker, args: [run, -i, --rm, -e, API_KEY, ghcr.io/foo/bar], env: { API_KEY: $MY_API_TOKEN } } } }这样 Key 就不用硬编码进配置文件配合环境变量管理更干净。验证配置是否被正确解析可以用/memory show看当前加载的上下文或者直接改一个显眼的字段比如theme重启 CLI 观察是否变化。3. 环境变量优先级与 .env 加载顺序实战环境变量是配置里最灵活、也最容易出问题的一层。Gemini CLI 会自动从.env文件加载环境变量加载顺序是这样的先看当前工作目录的.env没找到就向上逐级搜索父目录直到项目根通过.git文件夹识别或家目录如果还是没找到就找~/.env。这里有个关键细节部分环境变量会从项目.env里被自动排除默认是DEBUG和DEBUG_MODE目的是防止项目里的调试开关干扰 CLI 自身行为。但来自.gemini/.env的环境变量永远不会被排除。你可以通过settings.json里的excludedProjectEnvVars自定义这个排除列表。如果你确实需要为 CLI 单独设置DEBUG就把它写进.gemini/.env。常用的环境变量有这么几个。GEMINI_API_KEY是 API Key可以写在 shell 配置文件~/.bashrc、~/.zshrc或.env里。GEMINI_MODEL指定默认模型会覆盖硬编码默认值。GEMINI_SANDBOX是settings.json里sandbox设置的替代方案接受true、false、docker、podman或自定义命令字符串。NO_COLOR设为任意值可以禁用所有颜色输出。CLI_TITLE自定义 CLI 标题。如果你用的是兼容的 API 网关把 Base URL 和 Key 通过环境变量注入是最省事的做法。下面是一份.gemini/.env示例注意这个位置的文件不会被排除规则影响# .gemini/.env GEMINI_API_KEYsk-your-key-here GEMINI_MODELgemini-2.5-flash GEMINI_SANDBOXdocker NO_COLOR验证环境变量是否被正确加载可以这样操作。先确认当前 shell 里有没有这个变量echo $GEMINI_API_KEY如果为空说明 shell 没读到。再确认 CLI 实际用的是哪个模型启动后看页脚或执行gemini --version想看更详细的加载过程临时开调试DEBUG1 gemini注意这里是在命令行临时注入DEBUG而不是写进项目.env因为项目.env里的DEBUG会被排除。如果你希望它长期生效写进.gemini/.env。优先级要记牢环境变量会覆盖用户、项目、系统三层设置文件但会被命令行参数覆盖。所以当你发现settings.json里的sandbox没生效先检查是不是GEMINI_SANDBOX环境变量把它盖掉了。反过来如果你想让某个配置对所有项目生效又不想改文件环境变量是最快的办法。4. 命令行参数覆盖关系与逐项验证命令命令行参数是优先级最高的一层只对当前这次会话生效适合做临时覆盖和调试。它的好处是不动任何文件退出即失效特别适合「我就想试一下换个模型」这种场景。常用的参数里--model-m指定本次会话的模型--prompt-p直接传提示并以非交互模式运行--prompt-interactive-i用给定提示启动交互会话。--sandbox-s为本次会话启用沙盒--sandbox-image设置沙盒镜像 URI。--debug-d开调试输出。--all-files-a递归把当前目录所有文件作为上下文。--yolo自动批准所有工具调用--approval-mode设置批准模式可选default、auto_edit、yolo。注意--approval-modeyolo和--yolo不能同时用官方建议用前者这个统一的新方式。--include-directories可以在工作区里加入额外目录支持多次指定或逗号分隔最多加 5 个。--extensions-e指定本次会话用的扩展gemini -e none可以禁用所有扩展。--list-extensions-l列出所有可用扩展后退出。下面这组命令可以逐项验证覆盖关系。先看默认模型gemini -p 用一句话说明你是什么模型再用参数临时换模型观察输出是否变化gemini -m gemini-1.5-pro-latest -p 用一句话说明你是什么模型验证沙盒是否启用可以跑一个会写文件的命令看是否被限制在沙盒内gemini -s -p 在当前目录创建一个 test.txt 并写入 hello验证多目录上下文gemini --include-directories /path/to/project1,/path/to/project2 -p 列出你能看到的目录验证批准模式用auto_edit让编辑类工具自动通过、其他工具仍然询问gemini --approval-mode auto_edit如果你要把 CLI 接进兼容网关命令行也能直接覆盖端点相关配置。比如临时指定模型和 KeyGEMINI_API_KEYsk-your-key gemini -m gemini-2.5-flash -p hello这里环境变量和命令行参数同时出现命令行参数优先级更高。实测下来把「临时调试用命令行、长期配置用 settings.json、敏感信息用环境变量」这三条分开配置混乱的情况会少很多。5. 常见报错排查401、local proxy failed 与 reading choices配置过程中最耗时间的不是写配置而是报错之后不知道从哪查。下面按真实报错逐条拆解。401 Unauthorized / API key not valid。这是最常见的认证类报错通常有三种原因Key 没被读到、Key 写错了层、Key 本身无效。排查顺序是先用echo $GEMINI_API_KEY确认 shell 里有没有值再确认.env文件的位置对不对——项目.env会被向上搜索但.gemini/.env优先级更高且不受排除规则影响最后确认 Key 没有多余空格或引号。如果你用的是兼容网关还要确认 Base URL 和 Key 是配套的别把 A 家的 Key 配到 B 家的端点上。local proxy failed / connection refused。这类报错说明 CLI 尝试连接某个本地端点失败了。常见于你配置了自定义端点但服务没起来或者端口写错。检查settings.json或环境变量里的端点地址确认服务在监听。如果你在容器或沙盒里跑还要确认网络可达。注意不要配置任何绕过网络合规要求的方案走正规的 API 入口即可。Error reading choices / unexpected token in JSON。这个报错通常出现在 MCP 服务器返回的数据格式不对或者settings.json本身有语法错误。先用python -m json.tool .gemini/settings.json校验 JSON 合法性逗号、引号、括号是最容易出错的地方。如果是 MCP 相关检查服务器的command和args是否能独立跑通把timeout适当调大。OAuth / 认证流程卡住。如果你走的是 OAuth 认证卡在浏览器回调或 token 交换先确认本地回调端口没被占用再确认系统时间准确时间偏差会导致 token 校验失败。如果反复失败清掉缓存的凭据重新走一遍流程。配置不生效的通用排查法。按优先级从高到低问自己四个问题命令行参数有没有覆盖环境变量有没有覆盖项目级settings.json有没有覆盖用户级系统级有没有覆盖前面所有用/memory show看上下文加载情况用DEBUG1 gemini看详细日志。把每一层的实际值列出来对照问题基本就定位了。如果你在配置 MCP 服务器记得把三件套写全Base URL、Key、Model ID。缺任何一个都可能导致连接失败或工具不可用。下面是一个 MCP 服务器配置的完整示例注意env里用$VAR引用环境变量{ mcpServers: { myServer: { command: node, args: [mcp_server.js, --verbose], env: { API_KEY: $MY_API_TOKEN }, timeout: 5000, trust: false } } }trust设为true会绕过该服务器的所有工具调用确认生产环境慎用。includeTools和excludeTools用来做工具级过滤excludeTools优先。6. 把配置固定下来从临时调试到长期可用配置调通之后下一步是把它固定成可复用的形态。我的做法是分三层管理敏感信息Key、端点放.gemini/.env不进版本库项目相关的行为配置工具白名单、上下文文件、MCP 服务器放项目级.gemini/settings.json跟代码一起提交个人偏好主题、vim 模式、行号放用户级~/.gemini/settings.json不污染项目。这样团队协作时新人 clone 下来只需要补一个.gemini/.env填 Key其余配置直接生效。上下文文件用GEMINI.md写项目规范比如编码风格、依赖策略、特定文件的注意事项CLI 会分层加载并拼接成系统提示。用/memory refresh强制重新扫描用/memory show确认最终拼接结果。如果你希望把多个模型的调用统一到一个入口管理把 API Key 集中托管、按项目分配额度可以把它指向兼容的 API 网关。配置方式和上面完全一致只是把 Base URL 和 Key 换成网关提供的值。需要的话可以从 API Keys 页面拿到 Key接入细节看接入文档想先验证模型效果可以直接在模型对话里试长期做编码和 Agent 任务的话 Coding Plan 更合适。最后留一个实用习惯每次改完配置用一条最小命令验证比如gemini -p ok确认能正常返回再继续。配置这东西改一处验一处比一次性改一堆再排查要快得多。