1. 为什么 Gemini-CLI 首次接入总卡在 settings.json
Gemini-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 Key
TaoToken 的统一 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_source=taotoken_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 Key |
| baseUrl | API 根路径 | https://taotoken.net/api |
| model | 默认模型 | 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_KEY="sk-你的Key" export GEMINI_BASE_URL="https://taotoken.net/api"环境变量优先级通常高于配置文件，适合临时调试。但长期使用还是建议写进settings.json，避免每次开终端都要 export。
4. 连通性验证：一条命令确认配置生效
4.1 用 gemini 命令发一条最小请求
配置写好后，最直接的验证是启动 CLI 并发一条简单 prompt：
gemini -p "回复 OK 两个字母即可"如果配置正确，终端会返回类似：
OK这说明 CLI 已经通过https://taotoken.net/api成功请求到模型。如果返回 401，检查 Key；如果超时，检查 baseUrl 是否写成了带路径的完整 URL。
4.2 用 curl 直接验证通道
想更精确地定位问题，可以绕过 CLI 直接打 API：
curl -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"验证连通，两步都过再进交互模式。这样能把配置问题和模型问题分开，排查效率高很多。
