1. 为什么要在 Gemini CLI 里折腾 settings.json
Gemini CLI 是 Google 开源的终端 AI Agent，能把 Gemini 2.5 Pro 的百万 token 上下文直接拉进命令行，读代码、跑 shell、抓网页、调 MCP 工具都能干。对需要生成「项目分析文档」的开发者来说，它最大的价值是：你站在仓库根目录敲一句话，它就能把目录结构、关键模块、依赖关系梳理成一份可读的 Markdown。但很多人第一次跑通之后会卡在同一个地方——认证和模型通道散落在环境变量、OAuth 缓存、~/.gemini/settings.json三处，换台机器或者换个项目就要重配一遍，团队里还没法统一。
我试过把 Key 硬编码进 shell profile，结果 CI 里跑 headless 模式时环境变量没继承，直接报 401；也试过每个项目单独写一份配置，维护成本高得离谱。后来改成用 TaoToken 做统一 Key/API 通道，把认证收敛到一个settings.json骨架里，本地和脚本化调用共用同一份配置，才算稳定下来。这篇就聚焦「项目分析文档」这个落地场景，给你一份可直接复制的settings.json配置骨架，加一条验证命令确认生效，再把我踩过的几个报错整理成排查表。
适合谁看：已经在本地装好 Node.js 20+、想用 Gemini CLI 批量生成项目分析文档、又不想每次手动 export Key 的开发者。读完你能拿到三样东西——一份能跑的配置、一条验证命令、一张排错对照表。
2. TaoToken 前置：统一 Key 与 API 通道怎么准备
Gemini CLI 默认走 Google 的认证体系，支持 OAuth、Gemini API Key、Vertex AI 三种方式。问题在于，如果你同时用多个模型通道（比如项目分析用 Gemini、日常编码用别的），Key 管理会变得很碎。TaoToken 在这里的角色是提供一个统一的 API 通道和 Key 管理入口，让你在settings.json里只维护一份凭证，切换模型或换项目时不用改代码。
你需要先拿到一个可用的 API Key。打开控制台页面，在 API Keys 管理里创建一个新 Key，复制出来备用。这个 Key 就是后面写进配置文件的凭证。注意不要把它提交到 Git 仓库，建议放在环境变量或本地未跟踪的配置文件里。
TaoToken 的 API 入口是https://taotoken.net/api，这个地址会作为 Gemini CLI 的 base URL 写进配置。模型对话相关的调试可以在模型对话页面直接验证 Key 是否可用，不用先装 CLI 就能确认通道通不通。如果你后续要做长期编码或 Agent 任务，可以了解 Coding Plan，它更适合高频调用场景；只是跑项目分析文档的话，按量用 API 就够了。
这里有个关键点：Gemini CLI 读取配置的优先级是「环境变量 >settings.json> 默认值」。所以你要么把 Key 写进settings.json，要么用环境变量注入，两者选其一，别混着来，否则排查起来很痛苦。我建议本地开发写settings.json，CI 里用环境变量覆盖。
3. 可复制的 settings.json 配置骨架
Gemini CLI 的配置文件默认在~/.gemini/settings.json，你也可以在项目根目录放一份.gemini/settings.json做项目级覆盖。下面这份骨架是我实测能跑通项目分析文档生成的版本，字段含义我逐行标了注释。
{ "theme": "Default", "selectedAuthType": "gemini-api-key", "apiKey": "你的_TaoToken_API_Key", "model": { "name": "gemini-2.5-pro", "maxSessionTurns": 50, "temperature": 0.3 }, "api": { "baseUrl": "https://taotoken.net/api", "timeout": 120000 }, "tools": { "autoAccept": false, "sandbox": false, "allowed": [ "read_file", "list_directory", "grep", "glob", "read_many_files" ] }, "context": { "fileName": "GEMINI.md", "includeDirectoryTree": true, "maxFileSize": 1048576 }, "output": { "format": "text", "streamOutput": true } }几个字段值得展开说。selectedAuthType设成gemini-api-key表示走 API Key 认证，不走 OAuth 弹窗，这对 headless 模式很关键。api.baseUrl指向 TaoToken 的 API 入口，这样所有请求都经过统一通道。model.temperature我压到 0.3，因为项目分析文档要的是稳定输出，不是创意发散，温度高了它容易在模块职责描述上编造。tools.allowed只放只读工具，生成分析文档不需要写文件或跑 shell，把write_file、run_shell_command排除掉，避免它自作主张改你的代码。context.includeDirectoryTree打开后，它会自动把目录树塞进上下文，省得你手动喂结构。
如果你要在项目里放项目级配置，把这份文件复制到<项目根>/.gemini/settings.json，然后把apiKey换成从环境变量读取的写法。Gemini CLI 支持在配置里用${ENV_VAR}语法引用环境变量：
{ "apiKey": "${TAOTOKEN_API_KEY}", "api": { "baseUrl": "https://taotoken.net/api" } }这样你只需要在 shell 里export TAOTOKEN_API_KEY="你的Key"，配置文件本身可以安全地提交到仓库，团队里每个人用自己的 Key。这一步做完，认证和通道就收敛完了。
4. 验证请求：一条命令确认配置生效
配置写完别急着跑完整分析，先用一条最小命令验证通道通不通。Gemini CLI 支持非交互模式，用-p直接传提示词：
gemini -p "只回复 OK 两个字母，不要任何其他内容" --output-format json如果配置生效，你会看到类似这样的 JSON 输出：
{ "response": "OK", "stats": { "models": { "gemini-2.5-pro": { "api": { "totalRequests": 1 }, "tokens": { "input": 12, "output": 2 } } } } }看到response字段有内容、totalRequests为 1，说明 Key、baseUrl、模型名三处都对上了。如果返回 401 或 403，说明 Key 或认证类型有问题；如果返回 404，多半是baseUrl或模型名写错了。
通道验证通过后，跑真正的项目分析文档生成。在仓库根目录执行：
gemini -p "分析当前项目，生成一份项目分析文档，包含：1. 项目概述与核心功能 2. 目录结构与模块划分 3. 关键文件说明 4. 技术栈 5. 数据流或核心流程。输出 Markdown 格式，不要执行任何写操作。" --output-format text > PROJECT_ANALYSIS.md这条命令会把分析结果直接重定向到PROJECT_ANALYSIS.md。实测下来，一个中等规模的 TypeScript 项目（约 200 个文件），Gemini 2.5 Pro 能在 40 秒左右输出一份结构完整的分析文档，目录树和关键文件说明基本准确。如果你想让输出更聚焦，可以在提示词里指定「只分析src/目录」或「重点看packages/core」。
验证环节还有一个细节：--output-format支持text、json、stream-json三种。生成文档用text最省事；如果你要把分析结果喂给下游脚本，用json方便解析；stream-json适合实时展示进度。我一般先用text出一版人工过目，确认质量后再用json做自动化流水线。
5. 本篇常见错排查
配置和验证过程中，我遇到过几个高频报错，整理成对照表，你按现象直接定位。
| 报错现象 | 可能原因 | 排查动作 |
|---|---|---|
401 Unauthorized | Key 无效或未生效 | 检查apiKey字段是否被环境变量覆盖为空；在模型对话页面用同一个 Key 发一条消息验证 |
403 Forbidden | 认证类型与 Key 不匹配 | 确认selectedAuthType是gemini-api-key，不是oauth |
404 Not Found | baseUrl 或模型名错误 | 确认api.baseUrl为https://taotoken.net/api，模型名用gemini-2.5-pro |
| 配置不生效 | 项目级配置覆盖了全局配置 | 检查<项目根>/.gemini/settings.json是否存在，优先级高于~/.gemini/settings.json |
| 输出被截断 | maxSessionTurns太小 | 调到 50 或更高；大项目分析建议配合context.maxFileSize放宽 |
| 工具调用被拒 | tools.allowed没包含所需工具 | 生成分析文档至少需要read_file、list_directory、grep、glob |
| 中文输出乱码 | 终端编码问题 | 设置export LANG=en_US.UTF-8或zh_CN.UTF-8 |
还有一个隐蔽的坑：如果你之前用 OAuth 登录过，~/.gemini/下会缓存 token，即使settings.json改了认证类型，CLI 可能还在用旧缓存。解决办法是删掉~/.gemini/cache/和~/.gemini/checkpoints/下的内容，重新跑一次验证命令。另外，GEMINI.md文件如果内容过长，会挤占上下文窗口，导致分析文档生成到一半就停。建议GEMINI.md只放项目说明和编码规范，控制在 2000 字以内。
如果你在 CI 里跑 headless 模式，记得把TAOTOKEN_API_KEY配成 CI 的 secret，不要写进配置文件。Gemini CLI 在非交互模式下不会弹 OAuth，所以selectedAuthType必须是gemini-api-key，否则会直接挂起等输入。
6. 把配置沉淀成团队可复用的骨架
跑通之后，我建议把这份settings.json骨架和验证命令一起放进项目的docs/或.gemini/目录，配一段简短的 README 说明怎么注入 Key。这样新同学 clone 下来，只需要export TAOTOKEN_API_KEY再跑一条验证命令，就能生成项目分析文档，不用重复踩认证的坑。
如果你后续要把项目分析文档接入自动化流程，比如每次 PR 合并后自动更新文档，可以用--output-format json拿到结构化结果，再用脚本转成 Markdown。需要长期跑编码或 Agent 任务的话，Coding Plan 在高频调用下更划算；只是偶尔生成分析文档，按量用 API 通道就够。Key 管理和通道配置的细节可以在接入文档里对照着看，模型对话页面则适合快速验证某个模型名或提示词效果，不用每次都开终端。
最后留一个实用技巧：生成分析文档时，在提示词末尾加一句「如果某个模块的职责无法从代码中确定，标注『待确认』而不是猜测」，能显著减少模型编造模块功能的情况。这个约束对项目分析文档的可信度提升很明显，尤其是面对那些命名不规范的遗留代码库。
