1. 为什么你需要一份 Gemini 3 CLI 官方文档速查索引Gemini 3 CLI 是 Google 官方推出的命令行 AI 工具能在终端里直接调用 Gemini 3 模型完成代码生成、文件读写、Shell 执行、Web 抓取等任务适合习惯在终端里工作的开发者、运维和 Agent 应用搭建者。它的官方文档站点结构庞大从快速开始、CLI 命令、核心工具到 Hooks、扩展、IDE 集成模块分散在十几个路径下实际查阅时经常出现「知道有某个配置项但翻不到对应页面」的情况。我自己的做法是把官方文档按功能域拆成一张速查表再配合一份本地可复制的配置文件骨架这样从「检索文档」到「落地配置」只需要两步。本文就按这个思路展开先给出文档导航索引再交付settings.json与config.toml的可复制骨架最后用 TaoToken 统一 Key/API 通道做一次真实请求验证确保你拿到的不只是链接清单而是一条能跑通的路径。需要说明的是Gemini CLI 的配置分两层一层是 CLI 自身的settings.json控制模型选择、工具开关、主题、遥测等另一层是模型接入侧的config.toml或环境变量控制 Base URL、API Key、Model ID。很多人卡住不是因为不会写配置而是没分清这两层各自管什么。下面会分别给出骨架并标注每一项的作用。2. Gemini 3 CLI 官方文档导航与速查索引官方文档的入口在https://geminicli.com/docs/整体可以按「入门 → CLI 能力 → 核心机制 → 工具 → 扩展 → 集成 → 开发」七段来记。下面按这个顺序给出直达链接和一句话说明方便你直接收藏成书签组。2.1 快速开始段安装、认证、配置、Gemini 3 接入这一段是新手最先要看的四个页面。安装页https://geminicli.com/docs/get-started/installation/给出 npm 全局安装方式认证页https://geminicli.com/docs/get-started/authentication/说明登录态与 API Key 两种模式配置页https://geminicli.com/docs/get-started/configuration/是settings.json的字段总览Gemini 3 专页https://geminicli.com/docs/get-started/gemini-3/说明如何在 CLI 中指定 Gemini 3 模型。快速入门页https://geminicli.com/docs/get-started/和示例页https://geminicli.com/docs/get-started/examples/适合先跑一遍感受交互。2.2 CLI 能力段命令、模型选择、会话、沙盒这一段是日常使用频率最高的。命令页https://geminicli.com/docs/cli/commands/列出所有斜杠命令模型选择页https://geminicli.com/docs/cli/model/说明如何切换模型会话管理页https://geminicli.com/docs/cli/session-management/讲上下文保存与恢复沙盒页https://geminicli.com/docs/cli/sandbox/讲隔离执行设置页https://geminicli.com/docs/cli/settings/是settings.json的权威参考Token 缓存页https://geminicli.com/docs/cli/token-caching/对成本敏感的同学值得一看受信任文件夹页https://geminicli.com/docs/cli/trusted-folders/解决「为什么某个目录下工具不执行」的问题。2.3 核心与工具段Tools API、文件系统、Shell、MCP核心段里Tools API 页https://geminicli.com/docs/core/tools-api/讲工具调用协议策略引擎页https://geminicli.com/docs/core/policy-engine/讲权限控制。工具段里文件系统页https://geminicli.com/docs/tools/file-system/、Shell 页https://geminicli.com/docs/tools/shell/、Web 抓取页https://geminicli.com/docs/tools/web-fetch/、Web 搜索页https://geminicli.com/docs/tools/web-search/、记忆页https://geminicli.com/docs/tools/memory/、待办页https://geminicli.com/docs/tools/todos/、MCP 服务器页https://geminicli.com/docs/tools/mcp-server/各自独立。MCP 那页是接外部工具的关键建议单独精读。2.4 扩展、Hooks、IDE 集成与开发段扩展段从https://geminicli.com/docs/extensions/进入讲如何打包和发布扩展。Hooks 段从https://geminicli.com/docs/hooks/进入编写钩子看https://geminicli.com/docs/hooks/writing-hooks/参考手册看https://geminicli.com/docs/hooks/reference/。IDE 集成段https://geminicli.com/docs/ide-integration/讲编辑器伴随进程。开发段包含 NPM 页https://geminicli.com/docs/npm/、发布页https://geminicli.com/docs/releases/、集成测试页https://geminicli.com/docs/integration-tests/。把上面这些链接按七段存进浏览器书签文件夹检索成本会明显下降。但光有索引还不够真正落地时要写配置文件下面进入实操部分。3. 可复制的 settings.json 与 config.toml 骨架Gemini CLI 的配置分两处。settings.json通常放在用户目录下的.gemini/文件夹里控制 CLI 行为模型接入侧的 Base URL、API Key、Model ID 则通过环境变量或config.toml注入。下面给出两份骨架路径和字段名与官方文档保持一致你可以直接复制后按需改。先看settings.json骨架放在~/.gemini/settings.json{ theme: Default, model: { name: gemini-3-pro, maxSessionTurns: 50 }, tools: { sandbox: false, autoAccept: false, allowed: [ file-system, shell, web-fetch, web-search ] }, telemetry: { enabled: false }, trustedFolders: [ /Users/yourname/projects ] }这份骨架里model.name指定默认模型tools.allowed控制哪些工具可用trustedFolders决定哪些目录下工具会被放行。如果你发现某个目录里文件工具不执行先检查这里。再看模型接入侧的config.toml骨架放在~/.gemini/config.toml[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_id gemini-3-pro [request] timeout_seconds 120 max_retries 3这里三件套必须齐全Base URL 指向https://taotoken.net/apiAPI Key 通过环境变量TAOTOKEN_API_KEY注入Model ID 写gemini-3-pro。缺任何一项都会在请求阶段报错。环境变量这样设置export TAOTOKEN_API_KEY你的KeyKey 可以在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentsettings_skeletonutm_campaignrewrite生成。如果你更习惯用环境变量直接配也可以跳过config.toml改用export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY你的Key两种方式二选一即可不要同时配否则容易出现优先级混乱。配置改完后建议重启终端确保环境变量生效。4. 验证请求从文档检索到配置落地的完整动作配置写完必须验证否则你不知道是配置没生效还是模型没通。验证分三步先确认 CLI 能读到配置再发一次最小请求最后看返回结构。第一步检查配置是否被正确加载gemini --version gemini config listconfig list会打印当前生效的模型、Base URL 和工具开关。如果base_url显示的不是你写的地址说明config.toml没被读到检查文件路径和文件名拼写。第二步发一次最小对话请求gemini -p 用一句话说明什么是 CLI如果配置正确终端会流式返回模型输出。这一步能通说明 Base URL、Key、Model ID 三件套都对。第三步验证工具调用链路。让 CLI 读一个本地文件gemini -p 读取当前目录下的 README.md 并总结三行如果返回了文件内容摘要说明文件系统工具和模型接入都正常。如果报权限错误回到settings.json检查trustedFolders是否包含当前目录。实测下来最容易出问题的不是模型本身而是环境变量没导出到当前 shell。你可以用echo $TAOTOKEN_API_KEY确认变量存在。如果为空说明export只写进了配置文件但没 source执行source ~/.zshrc或source ~/.bashrc即可。验证通过后你就有了一条从文档检索到配置落地的完整路径。后续要换模型只改model_id一行要加工具只改tools.allowed数组。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth配置过程中有几类报错反复出现这里按真实报错信息对照排查。401 Unauthorized最常见。原因通常是 Key 没传进去或传错。检查echo $TAOTOKEN_API_KEY是否有值检查config.toml里api_key_env写的变量名和实际导出的变量名是否一致。如果用的是OPENAI_API_KEY方式确认没有和TAOTOKEN_API_KEY混用。local proxy failed / connection refused说明 Base URL 不可达。检查base_url是否写成https://taotoken.net/api注意结尾不要多加斜杠也不要用http。如果公司网络有出口限制确认该地址在允许列表内。reading choices 相关报错这类通常出现在返回结构解析阶段说明请求发出去了但返回体不符合预期。常见原因是model_id写错比如写成了不存在的模型名。回到config.toml确认model_id拼写并确认该模型在当前 Key 的可用范围内。OAuth 相关报错如果你之前用过登录态认证再切到 API Key 模式时可能残留 OAuth 缓存。清理~/.gemini/下的认证缓存文件重新用 Key 模式启动即可。注意不要同时启用两种认证方式。工具不执行 / permission denied不是网络问题是权限问题。检查settings.json的trustedFolders是否包含目标目录检查tools.allowed是否包含对应工具名。排查顺序建议固定为先看环境变量再看 Base URL再看 Model ID最后看工具权限。这个顺序能覆盖九成以上的配置类报错。6. 把速查索引变成日常习惯文档索引的价值在于减少重复搜索。我的做法是把本文第 2 节的七段链接存成一个书签文件夹命名成「Gemini CLI 速查」需要查配置项时直接点「设置」那一条需要查工具时直接点「工具」那一条。配置文件则放在版本控制里换机器时直接拉下来改 Key 就能用。如果你后续要做长期编码或 Agent 开发可以把模型接入统一走 TaoToken 的 Coding Plan这样 Key 和 Base URL 只需要维护一份换模型时改model_id即可。需要看模型实际对话效果可以直接在模型对话页试需要生成和管理 Key去 API Keys 页接入细节查接入文档。这几条路径配合上面的配置骨架基本能覆盖从检索到落地的全部动作。