1. 为什么你的 Gemini CLI 装好了却用不起来很多人第一次接触 Gemini CLI是被它「在终端里直接对话、读文件、跑命令」的能力吸引。安装过程通常很顺利npm install -g google/gemini-cli敲下去gemini命令也能正常启动。但真正开始用的时候问题就来了要么鉴权卡住要么请求发不出去要么返回一堆看不懂的报错。这个场景我见得太多了——CLI 装上了但端点没打通等于买了个漂亮的空壳。Gemini CLI 本质上是一个命令行客户端它需要三样东西才能跑起来一个能访问的 API 端点Base URL、一个有效的密钥API Key、一个明确的模型 IDModel ID。官方默认走的是 Google 自己的端点但在实际开发中很多团队会希望把请求指向自己的网关或聚合服务方便统一管理密钥、做用量统计、切换模型。这时候就需要改settings.json把这三样东西配置对。这篇手册聚焦的就是这个「最后一公里」你已经装好了 CLI但鉴权或端点还没打通。我会给你可复制的settings.json片段逐条命令拆解覆盖环境变量、Base URL 指向、模型选择最后用一次真实请求验证闭环。全程不需要你懂底层协议跟着敲就行。适合谁看已经装过 Gemini CLI 但没跑通的开发者想把 CLI 接到统一网关做密钥管理的团队以及想搞清楚settings.json每个字段到底管什么的人。如果你还没装 CLI先去官方仓库按 README 装好再回来跟着这篇走。核心检索词先明确Gemini CLI 的配置落地关键在settings.json里的baseUrl、apiKey、model三个字段配合环境变量做覆盖。下面从场景问题开始一步步拆。2. TaoToken 前置准备拿到 Base URL 和 Key在改配置之前你得先有一个可用的端点和密钥。这里我用 TaoToken 作为示例网关因为它对 Gemini CLI 的兼容做得比较直接配置字段和官方结构一致改起来不用绕弯。你需要准备两样东西Base URL 和 API Key。Base URL 是请求的根地址Gemini CLI 会在这个地址后面拼接具体的路径。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不带任何查询参数就是干净的根路径。API Key 则需要你登录后在控制台生成路径是 API Keys 页面。生成的时候建议给 Key 起个能认出来的名字比如gemini-cli-local方便以后排查是哪个客户端在用。拿到 Key 之后不要直接硬编码到settings.json里提交到 Git。正确做法是把它放进环境变量让 CLI 从环境变量读取。Gemini CLI 支持用GEMINI_API_KEY这个环境变量来覆盖配置里的密钥。你可以在~/.zshrc或~/.bashrc里加一行export GEMINI_API_KEY你的_TaoToken_Key然后source ~/.zshrc让它生效。验证一下echo $GEMINI_API_KEY能打印出你的 Key 就说明环境变量生效了。这一步看起来简单但后面很多「401」报错都是因为环境变量没生效或者 shell 会话没重新加载。我建议你每次改完环境变量都新开一个终端窗口再测避免旧会话缓存干扰。除了 Key你还需要确认模型 ID。TaoToken 支持多个模型Gemini CLI 场景下常用的有gemini-2.5-pro和gemini-2.5-flash。Pro 适合复杂推理和长上下文Flash 适合快速响应和批量任务。你可以在模型对话页面先试一下哪个模型可用再写进配置。模型 ID 必须和网关支持的完全一致写错了会报「model not found」。前置准备就这三样Base URL、API Key、Model ID。把它们记下来下一步写进settings.json。如果你还没有 Key先去控制台创建一个整个过程不到一分钟。3. 可复制配置settings.json 与命令逐条拆解Gemini CLI 的配置文件默认在~/.gemini/settings.json。如果目录不存在先创建mkdir -p ~/.gemini然后编辑settings.json。下面是一份可以直接复制的配置片段字段和官方结构保持一致只改了端点、密钥来源和模型{ theme: Default, selectedAuthType: gemini-api-key, apiKey: ${GEMINI_API_KEY}, baseUrl: https://taotoken.net/api, model: gemini-2.5-pro, temperature: 0.7, maxOutputTokens: 8192, contextFileName: GEMINI.md }逐条解释一下关键字段。selectedAuthType设为gemini-api-key表示用 API Key 鉴权而不是 OAuth 登录。apiKey用${GEMINI_API_KEY}引用环境变量这样配置文件里不出现明文密钥可以安全地纳入版本管理。baseUrl指向 TaoToken 的 API 根地址注意结尾不要加斜杠CLI 会自己拼接路径。model填你确认可用的模型 ID这里用gemini-2.5-pro做示例。temperature控制回答的随机性0.7 是比较均衡的值写代码建议调到 0.2 到 0.4创意类任务可以到 0.9。maxOutputTokens限制单次输出的最大 token 数8192 对大多数场景够用如果你要生成大段代码或长文档可以调到 16384。contextFileName指定项目级上下文文件的名字默认是GEMINI.md你可以在项目根目录放一个CLI 启动时会自动读取。配置写好后用命令验证 CLI 是否读到了正确的值。先看版本gemini --version再检查配置加载情况。Gemini CLI 没有直接的config get命令但你可以启动交互模式后用/config命令族查看。启动gemini进入交互界面后输入/config get baseUrl如果返回https://taotoken.net/api说明配置生效。再查模型/model list应该能看到你配置的模型在列表里。如果baseUrl返回的是官方默认地址说明settings.json没被读到检查文件路径和 JSON 格式是否正确。JSON 不允许尾随逗号这是最常见的格式错误。环境变量和配置文件的关系要理清环境变量优先级高于settings.json。也就是说如果你在 shell 里export GEMINI_API_KEYxxx它会覆盖配置文件里的apiKey字段。这个机制很有用——团队可以共享一份settings.json每个人用自己的环境变量注入密钥互不干扰。如果你用的是 Cline MCP 或 Claude Code 这类工具配置逻辑类似但字段名可能不同。Cline MCP 的配置在cline_mcp_settings.json需要写全 Base URL、Key、Model ID 三件套。Codex 的auth.json则是另一套结构。不管哪个工具核心都是这三样只是存放位置和字段名有差异。配置完成后不要急着问复杂问题。先用一个最简单的请求验证链路通不通下一节讲具体怎么测。4. 验证请求一次真实调用确认闭环配置写好了但「配置对」和「请求通」是两回事。很多人卡在这一步settings.json看起来没问题但一发请求就报错。所以必须做一次真实调用把整条链路走通。最直接的验证方式是用非交互模式发一个单次请求。Gemini CLI 支持-p参数直接传 promptgemini -p 用一句话说明什么是 API 网关如果配置正确你会看到模型返回的一句话解释。这个过程会走完整的链路CLI 读取settings.json→ 从环境变量取 Key → 向https://taotoken.net/api发请求 → 拿到响应 → 打印到终端。任何一环出问题都会在这里暴露。如果成功输出大概是这样API 网关是位于客户端和后端服务之间的中间层负责请求路由、鉴权、限流和监控。看到正常回答说明 Base URL、Key、Model ID 三样都对上了。这时候你可以进一步测试上下文能力。在项目目录下启动交互模式cd ~/your-project gemini然后用/context命令族加载文件/context file ./package.json再提问根据你读取的 package.json这个项目用了哪些主要依赖如果模型能基于文件内容回答说明上下文加载也正常。这一步验证的是 CLI 的「协同」能力不只是单次问答。再测一个/exec命令验证 shell 集成/exec git statusCLI 会执行git status并把输出喂给模型然后你可以追问根据上面的 git 状态帮我写一条 commit message这个流程走通说明你的 Gemini CLI 已经完整可用了。从安装到配置到验证闭环完成。验证时有个细节要注意如果你在代理环境下比如公司内网可能需要额外配置HTTPS_PROXY环境变量。但这里不展开因为大多数本地开发场景直连即可。如果请求超时先检查网络能否访问taotoken.net用curl测一下curl -I https://taotoken.net/api返回 200 或 401 都说明网络通401 只是没带 Key。如果连不上就是网络层的问题跟 CLI 配置无关。验证通过后建议把这次成功的命令记下来作为以后排查的基准。下次再出问题先用同样的命令测能快速定位是配置变了还是网络变了。5. 常见报错排查401、proxy failed、reading choices即使配置看起来没问题实际跑的时候还是会遇到各种报错。这一节把最常见的几类错误和排查路径列出来你对照着看。401 Unauthorized是最常见的。报错长这样Error: Request failed with status code 401 {error:{message:Invalid API key provided}}原因通常有三个环境变量没生效、Key 写错了、Key 被禁用或额度用完。排查顺序先echo $GEMINI_API_KEY确认环境变量有值再确认这个 Key 在控制台是启用状态最后检查settings.json里的apiKey字段是不是${GEMINI_API_KEY}如果写成了别的变量名就对不上。注意${}语法是 Gemini CLI 支持的变量引用方式不是所有工具都支持如果你换工具了要改。local proxy failed这类报错通常和网络层有关Error: connect ECONNREFUSED 127.0.0.1:7890这说明 CLI 试图走本地代理但代理没启动。检查你的HTTP_PROXY和HTTPS_PROXY环境变量如果设了但代理没开就会报这个。解决方法是取消这两个环境变量或者启动对应的代理服务。在本地开发场景直连通常没问题不需要代理。reading choices报错比较隐蔽TypeError: Cannot read properties of undefined (reading choices)这通常意味着响应结构不符合预期。可能原因Base URL 指向的端点返回的不是 OpenAI 兼容格式或者模型 ID 写错了导致网关返回了错误结构。排查方法用curl直接打端点看返回的 JSON 结构curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $GEMINI_API_KEY \ -H Content-Type: application/json \ -d {model:gemini-2.5-pro,messages:[{role:user,content:hi}]}如果返回里有choices字段说明端点正常问题在 CLI 配置如果没有说明端点或模型不对。注意这里的路径是/api/v1/chat/completionsCLI 会自己拼接你手动测的时候要写全。OAuth 相关报错比如Error: OAuth token expired说明selectedAuthType没设成gemini-api-keyCLI 还在尝试用 OAuth 登录。检查settings.json里这个字段改成gemini-api-key后重启 CLI。model not found报错Error: Model gemini-2.5-pro not found模型 ID 拼写错误或者网关不支持这个模型。去模型对话页面确认可用模型列表复制准确的 ID。注意大小写和连字符gemini-2.5-pro和gemini-2.5-Pro是不一样的。排查时有个通用方法把settings.json里的baseUrl临时改成官方地址如果官方能通而你的网关不通问题就在网关配置如果官方也不通问题在 CLI 本身或环境变量。这个对照法能快速缩小范围。还有一个容易忽略的点settings.json的权限。如果文件权限不对CLI 可能读不到。确保文件可读chmod 644 ~/.gemini/settings.json排查完记得把临时改动还原别把调试配置留在生产环境里。6. 把配置沉淀成可复用的工作流配置跑通只是开始真正提升效率的是把这套东西沉淀成可复用的工作流。我自己的做法是每个项目根目录放一个GEMINI.md写清楚这个项目的技术栈、目录结构、常用命令。CLI 启动时会自动读取模型一上来就有项目上下文不用每次手动/context加载。GEMINI.md的内容不用长几行就够# 项目上下文 - 技术栈Node.js 20 TypeScript Fastify - 包管理pnpm - 测试vitest - 常用命令pnpm dev / pnpm test / pnpm build - 代码规范ESLint Prettier提交前跑 pnpm lint这样每次启动 CLI模型就知道你在什么项目里工作回答会更贴合实际。配合/context file按需加载具体文件效率比每次从零解释高得多。另一个技巧是把常用 prompt 存成 shell 别名。比如你经常要让模型 review 代码可以在.zshrc里加alias greviewgemini -p review 以下代码指出潜在 bug 和性能问题然后cat file.js | greview就能快速 review。这种小工具积累多了CLI 就真正融入你的开发流程了。如果你需要长期跑编码任务或 Agent 类工作流可以考虑 Coding Plan它针对高频调用做了优化适合把 CLI 当成日常主力工具的场景。配置方式和单次调用一致只是用量策略不同。最后提醒一点settings.json里的apiKey用环境变量引用但环境变量本身要保管好。不要把 Key 提交到 Git不要在共享终端里export后忘记清理。团队协作时每个人用自己的 Key配置文件共享这是最安全的做法。整套流程走下来从安装到配置到验证到沉淀Gemini CLI 就真正可用了。核心就三样Base URL 指向https://taotoken.net/apiKey 从环境变量注入Model ID 写对。剩下的都是围绕这三样的调试和优化。