1. 为什么 Gemini-CLI 首次接入总卡在 settings.jsonGemini-CLI 是 Google 推出的本地命令行 AI 工具能在终端里直接读写项目文件、跑命令、做代码审查适合习惯在 shell 里干活的人。它默认走官方通道但很多国内开发者在首次配置时会遇到两个现实问题一是网络请求不稳定二是想统一管理多个 CLI 工具的 Key 和计费。TaoToken 提供统一 Key/API 通道把 base_url 指向https://taotoken.net/api就能让 Gemini-CLI 走这条通道。我试过在三个不同项目里配 Gemini-CLI最容易出错的环节不是命令本身而是settings.json的骨架写错——字段名拼错、层级放错、Key 占位没替换都会导致 CLI 启动后请求直接 401 或超时。这篇操作指南聚焦首次接入场景给出可复制的settings.json骨架、一条连通性验证命令和预期返回帮你确认配置真的生效了。适合读者本地命令行 AI 工具使用者、想把 Gemini-CLI 接入统一 API 通道的开发者、以及第一次配~/.gemini/settings.json的新手。下面从原问题拆解开始一步步走完配置和验证。2. 接入前的准备TaoToken Key 与 Gemini-CLI 环境2.1 确认 Gemini-CLI 已安装并能启动先确认本地环境。Gemini-CLI 需要 Node.js 20用 npm 全局安装node -v npm install -g google/gemini-cli gemini --version如果gemini --version能输出版本号说明 CLI 本体没问题。接下来所有配置都围绕~/.gemini/settings.json展开这个文件默认可能不存在需要手动创建。2.2 拿到 TaoToken 的 API KeyTaoToken 的统一 Key 在控制台生成。访问 API Keys 页面创建新 Key复制出来形如sk-xxxx的字符串。这个 Key 是后续所有请求的凭证不要提交到 Git 仓库。注意Key 只显示一次建议先存到本地密码管理器或临时文件再粘贴进配置。拿到 Key 后先别急着写settings.json用一条 curl 命令确认 Key 本身可用curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key | head -c 300如果返回 JSON 里包含模型列表说明 Key 和通道都正常。这一步能提前排除 Key 无效的问题避免后面把配置错误误判成 CLI 问题。2.3 理解 base_url 与 Gemini-CLI 的关系Gemini-CLI 默认请求 Google 的端点接入 TaoToken 的核心就是把请求地址改成https://taotoken.net/api。这个地址是 API 根路径不带 UTM 参数配置里只写这个。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end但配置文件中不要带查询参数否则可能导致路径拼接异常。3. settings.json 骨架可复制的完整配置3.1 文件位置与创建Gemini-CLI 的全局配置在~/.gemini/settings.json。如果目录不存在先创建mkdir -p ~/.gemini touch ~/.gemini/settings.json项目级配置可以放在项目根目录的.gemini/settings.json但首次接入建议先用全局配置跑通再考虑项目级覆盖。3.2 最小可用骨架下面是最小可用的settings.json骨架把sk-你的Key替换成实际 Key{ apiKey: sk-你的Key, baseUrl: https://taotoken.net/api, model: gemini-2.5-pro, autoAccept: false, checkpointing: { enabled: false }, sandbox: false, maxSessionTurns: -1 }字段说明字段作用建议值apiKey请求凭证你的 TaoToken KeybaseUrlAPI 根路径https://taotoken.net/apimodel默认模型gemini-2.5-pro 或按需autoAccept自动执行安全操作false首次接入保持手动checkpointing保存点功能先关跑通再开sandbox沙盒模式false需要时再开maxSessionTurns单会话最大轮数-1 表示不限3.3 带记忆与遥测的扩展骨架如果你需要项目级记忆和本地遥测可以用这个扩展版{ apiKey: sk-你的Key, baseUrl: https://taotoken.net/api, model: gemini-2.5-pro, autoAccept: false, checkpointing: { enabled: false }, sandbox: false, telemetry: { enabled: true, target: local, otlpEndpoint: http://localhost:16686, logPrompts: false }, maxSessionTurns: -1 }telemetry默认关闭开启后会把指标发到本地 OTLP 端点logPrompts设为 false 避免记录提示内容。记忆文件GEMINI.md放在~/.gemini/GEMINI.md是全局级放在项目根目录是项目级CLI 启动时会自动加载。3.4 环境变量方式作为备选有些版本对settings.json的字段解析不一致可以用环境变量兜底export GEMINI_API_KEYsk-你的Key export GEMINI_BASE_URLhttps://taotoken.net/api环境变量优先级通常高于配置文件适合临时调试。但长期使用还是建议写进settings.json避免每次开终端都要 export。4. 连通性验证一条命令确认配置生效4.1 用 gemini 命令发一条最小请求配置写好后最直接的验证是启动 CLI 并发一条简单 promptgemini -p 回复 OK 两个字母即可如果配置正确终端会返回类似OK这说明 CLI 已经通过https://taotoken.net/api成功请求到模型。如果返回 401检查 Key如果超时检查 baseUrl 是否写成了带路径的完整 URL。4.2 用 curl 直接验证通道想更精确地定位问题可以绕过 CLI 直接打 APIcurl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gemini-2.5-pro, messages: [{role: user, content: ping}] } | head -c 500预期返回是一段 JSON包含choices字段和模型回复内容。如果这里通了但 CLI 不通问题就在settings.json的字段名或层级上。4.3 验证模型列表是否可读再补一条模型列表请求确认 Key 有权限curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key返回的 JSON 里data数组会列出可用模型。如果这个请求 403说明 Key 权限不足或已过期需要回控制台重新生成。4.4 在 CLI 内用 /chat 验证会话进入交互模式后可以用/chat save tag保存当前会话用/chat resume tag恢复。注意 tag 不能含中文否则会出问题。验证配置生效时先发一条消息再/chat save test1退出后重新进入/chat resume test1如果能恢复上下文说明整条链路都通了。5. 常见报错排查从 401 到超时5.1 401 Unauthorized最常见的原因是 Key 没替换或复制时带了空格。检查settings.json里apiKey字段是否还是sk-你的Key占位符。另外确认 Key 没有过期回控制台看状态。5.2 404 Not Found多半是baseUrl写错了。正确值是https://taotoken.net/api不要写成https://taotoken.net/api/v1也不要带尾部斜杠。CLI 会自己在后面拼/v1/chat/completions这类路径。5.3 请求超时先确认网络能访问taotoken.net用curl -I https://taotoken.net/api看响应头。如果 curl 通但 CLI 超时检查是否有本地代理环境变量干扰比如HTTP_PROXY指向了不可用的地址。5.4 settings.json 解析失败JSON 对格式敏感多一个逗号或少一个引号都会导致解析失败。用python -m json.tool ~/.gemini/settings.json校验格式python -m json.tool ~/.gemini/settings.json如果输出格式化后的 JSON说明格式正确如果报错按提示定位行号。5.5 checkpointing 开启后崩溃如果 Git 版本低于 2.28开启checkpointing会导致 CLI 崩溃。先用git --version确认版本低于 2.28 就保持enabled: false或者升级 Git。5.6 模型名不被识别model字段要填 TaoToken 支持的模型名。如果填了不存在的模型请求会返回模型不存在的错误。先用/v1/models接口确认可用模型列表再填进配置。6. 跑通之后把配置固化下来配置跑通后建议把settings.json纳入本地 dotfiles 管理但 Key 不要硬编码。可以用环境变量引用{ apiKey: ${GEMINI_API_KEY}, baseUrl: https://taotoken.net/api, model: gemini-2.5-pro }然后在 shell 配置文件里 exportGEMINI_API_KEY。这样配置文件可以安全地同步到其他机器Key 单独管理。长期做编码和 Agent 任务的话可以了解 Coding Plan 的额度方案需要验证模型效果时用模型对话页面快速试接入文档里有完整的字段说明和示例。排障阶段优先看 API Keys 和接入文档确认 Key 状态和请求格式。最后留一个实用技巧每次改完settings.json先跑python -m json.tool校验格式再跑gemini -p ping验证连通两步都过再进交互模式。这样能把配置问题和模型问题分开排查效率高很多。