1. 為什么你需要一份 Gemini 3 CLI 官方文檔速查索引Gemini 3 CLI 是 Google 官方推出的命令行 AI 工具能在終端里直接調(diào)用 Gemini 3 模型完成代碼生成、文件讀寫、Shell 執(zhí)行、Web 抓取等任務(wù)適合習(xí)慣在終端里工作的開發(fā)者、運(yùn)維和 Agent 應(yīng)用搭建者。它的官方文檔站點(diǎn)結(jié)構(gòu)龐大從快速開始、CLI 命令、核心工具到 Hooks、擴(kuò)展、IDE 集成模塊分散在十幾個(gè)路徑下實(shí)際查閱時(shí)經(jīng)常出現(xiàn)「知道有某個(gè)配置項(xiàng)但翻不到對(duì)應(yīng)頁面」的情況。我自己的做法是把官方文檔按功能域拆成一張速查表再配合一份本地可復(fù)制的配置文件骨架這樣從「檢索文檔」到「落地配置」只需要兩步。本文就按這個(gè)思路展開先給出文檔導(dǎo)航索引再交付settings.json與config.toml的可復(fù)制骨架最后用 TaoToken 統(tǒng)一 Key/API 通道做一次真實(shí)請(qǐng)求驗(yàn)證確保你拿到的不只是鏈接清單而是一條能跑通的路徑。需要說明的是Gemini CLI 的配置分兩層一層是 CLI 自身的settings.json控制模型選擇、工具開關(guān)、主題、遙測(cè)等另一層是模型接入側(cè)的config.toml或環(huán)境變量控制 Base URL、API Key、Model ID。很多人卡住不是因?yàn)椴粫?huì)寫配置而是沒分清這兩層各自管什么。下面會(huì)分別給出骨架并標(biāo)注每一項(xiàng)的作用。2. Gemini 3 CLI 官方文檔導(dǎo)航與速查索引官方文檔的入口在https://geminicli.com/docs/整體可以按「入門 → CLI 能力 → 核心機(jī)制 → 工具 → 擴(kuò)展 → 集成 → 開發(fā)」七段來記。下面按這個(gè)順序給出直達(dá)鏈接和一句話說明方便你直接收藏成書簽組。2.1 快速開始段安裝、認(rèn)證、配置、Gemini 3 接入這一段是新手最先要看的四個(gè)頁面。安裝頁https://geminicli.com/docs/get-started/installation/給出 npm 全局安裝方式認(rèn)證頁https://geminicli.com/docs/get-started/authentication/說明登錄態(tài)與 API Key 兩種模式配置頁https://geminicli.com/docs/get-started/configuration/是settings.json的字段總覽Gemini 3 專頁https://geminicli.com/docs/get-started/gemini-3/說明如何在 CLI 中指定 Gemini 3 模型?？焖偃腴T頁https://geminicli.com/docs/get-started/和示例頁https://geminicli.com/docs/get-started/examples/適合先跑一遍感受交互。2.2 CLI 能力段命令、模型選擇、會(huì)話、沙盒這一段是日常使用頻率最高的。命令頁https://geminicli.com/docs/cli/commands/列出所有斜杠命令模型選擇頁https://geminicli.com/docs/cli/model/說明如何切換模型會(huì)話管理頁https://geminicli.com/docs/cli/session-management/講上下文保存與恢復(fù)沙盒頁https://geminicli.com/docs/cli/sandbox/講隔離執(zhí)行設(shè)置頁https://geminicli.com/docs/cli/settings/是settings.json的權(quán)威參考Token 緩存頁https://geminicli.com/docs/cli/token-caching/對(duì)成本敏感的同學(xué)值得一看受信任文件夾頁https://geminicli.com/docs/cli/trusted-folders/解決「為什么某個(gè)目錄下工具不執(zhí)行」的問題。2.3 核心與工具段Tools API、文件系統(tǒng)、Shell、MCP核心段里Tools API 頁https://geminicli.com/docs/core/tools-api/講工具調(diào)用協(xié)議策略引擎頁https://geminicli.com/docs/core/policy-engine/講權(quán)限控制。工具段里文件系統(tǒng)頁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 服務(wù)器頁https://geminicli.com/docs/tools/mcp-server/各自獨(dú)立。MCP 那頁是接外部工具的關(guān)鍵建議單獨(dú)精讀。2.4 擴(kuò)展、Hooks、IDE 集成與開發(fā)段擴(kuò)展段從https://geminicli.com/docs/extensions/進(jìn)入講如何打包和發(fā)布擴(kuò)展。Hooks 段從https://geminicli.com/docs/hooks/進(jìn)入編寫鉤子看https://geminicli.com/docs/hooks/writing-hooks/參考手冊(cè)看https://geminicli.com/docs/hooks/reference/。IDE 集成段https://geminicli.com/docs/ide-integration/講編輯器伴隨進(jìn)程。開發(fā)段包含 NPM 頁https://geminicli.com/docs/npm/、發(fā)布頁https://geminicli.com/docs/releases/、集成測(cè)試頁https://geminicli.com/docs/integration-tests/。把上面這些鏈接按七段存進(jìn)瀏覽器書簽文件夾檢索成本會(huì)明顯下降。但光有索引還不夠真正落地時(shí)要寫配置文件下面進(jìn)入實(shí)操部分。3. 可復(fù)制的 settings.json 與 config.toml 骨架Gemini CLI 的配置分兩處。settings.json通常放在用戶目錄下的.gemini/文件夾里控制 CLI 行為模型接入側(cè)的 Base URL、API Key、Model ID 則通過環(huán)境變量或config.toml注入。下面給出兩份骨架路徑和字段名與官方文檔保持一致你可以直接復(fù)制后按需改。先看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指定默認(rèn)模型tools.allowed控制哪些工具可用trustedFolders決定哪些目錄下工具會(huì)被放行。如果你發(fā)現(xiàn)某個(gè)目錄里文件工具不執(zhí)行先檢查這里。再看模型接入側(cè)的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 通過環(huán)境變量TAOTOKEN_API_KEY注入Model ID 寫gemini-3-pro。缺任何一項(xiàng)都會(huì)在請(qǐng)求階段報(bào)錯(cuò)。環(huán)境變量這樣設(shè)置export TAOTOKEN_API_KEY你的KeyKey 可以在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentsettings_skeletonutm_campaignrewrite生成。如果你更習(xí)慣用環(huán)境變量直接配也可以跳過config.toml改用export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY你的Key兩種方式二選一即可不要同時(shí)配否則容易出現(xiàn)優(yōu)先級(jí)混亂。配置改完后建議重啟終端確保環(huán)境變量生效。4. 驗(yàn)證請(qǐng)求從文檔檢索到配置落地的完整動(dòng)作配置寫完必須驗(yàn)證否則你不知道是配置沒生效還是模型沒通。驗(yàn)證分三步先確認(rèn) CLI 能讀到配置再發(fā)一次最小請(qǐng)求最后看返回結(jié)構(gòu)。第一步檢查配置是否被正確加載gemini --version gemini config listconfig list會(huì)打印當(dāng)前生效的模型、Base URL 和工具開關(guān)。如果base_url顯示的不是你寫的地址說明config.toml沒被讀到檢查文件路徑和文件名拼寫。第二步發(fā)一次最小對(duì)話請(qǐng)求gemini -p 用一句話說明什么是 CLI如果配置正確終端會(huì)流式返回模型輸出。這一步能通說明 Base URL、Key、Model ID 三件套都對(duì)。第三步驗(yàn)證工具調(diào)用鏈路。讓 CLI 讀一個(gè)本地文件gemini -p 讀取當(dāng)前目錄下的 README.md 并總結(jié)三行如果返回了文件內(nèi)容摘要說明文件系統(tǒng)工具和模型接入都正常。如果報(bào)權(quán)限錯(cuò)誤回到settings.json檢查trustedFolders是否包含當(dāng)前目錄。實(shí)測(cè)下來最容易出問題的不是模型本身而是環(huán)境變量沒導(dǎo)出到當(dāng)前 shell。你可以用echo $TAOTOKEN_API_KEY確認(rèn)變量存在。如果為空說明export只寫進(jìn)了配置文件但沒 source執(zhí)行source ~/.zshrc或source ~/.bashrc即可。驗(yàn)證通過后你就有了一條從文檔檢索到配置落地的完整路徑。后續(xù)要換模型只改model_id一行要加工具只改tools.allowed數(shù)組。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置過程中有幾類報(bào)錯(cuò)反復(fù)出現(xiàn)這里按真實(shí)報(bào)錯(cuò)信息對(duì)照排查。401 Unauthorized最常見。原因通常是 Key 沒傳進(jìn)去或傳錯(cuò)。檢查echo $TAOTOKEN_API_KEY是否有值檢查config.toml里api_key_env寫的變量名和實(shí)際導(dǎo)出的變量名是否一致。如果用的是OPENAI_API_KEY方式確認(rèn)沒有和TAOTOKEN_API_KEY混用。local proxy failed / connection refused說明 Base URL 不可達(dá)。檢查base_url是否寫成https://taotoken.net/api注意結(jié)尾不要多加斜杠也不要用http。如果公司網(wǎng)絡(luò)有出口限制確認(rèn)該地址在允許列表內(nèi)。reading choices 相關(guān)報(bào)錯(cuò)這類通常出現(xiàn)在返回結(jié)構(gòu)解析階段說明請(qǐng)求發(fā)出去了但返回體不符合預(yù)期。常見原因是model_id寫錯(cuò)比如寫成了不存在的模型名?；氐絚onfig.toml確認(rèn)model_id拼寫并確認(rèn)該模型在當(dāng)前 Key 的可用范圍內(nèi)。OAuth 相關(guān)報(bào)錯(cuò)如果你之前用過登錄態(tài)認(rèn)證再切到 API Key 模式時(shí)可能殘留 OAuth 緩存。清理~/.gemini/下的認(rèn)證緩存文件重新用 Key 模式啟動(dòng)即可。注意不要同時(shí)啟用兩種認(rèn)證方式。工具不執(zhí)行 / permission denied不是網(wǎng)絡(luò)問題是權(quán)限問題。檢查settings.json的trustedFolders是否包含目標(biāo)目錄檢查tools.allowed是否包含對(duì)應(yīng)工具名。排查順序建議固定為先看環(huán)境變量再看 Base URL再看 Model ID最后看工具權(quán)限。這個(gè)順序能覆蓋九成以上的配置類報(bào)錯(cuò)。6. 把速查索引變成日常習(xí)慣文檔索引的價(jià)值在于減少重復(fù)搜索。我的做法是把本文第 2 節(jié)的七段鏈接存成一個(gè)書簽文件夾命名成「Gemini CLI 速查」需要查配置項(xiàng)時(shí)直接點(diǎn)「設(shè)置」那一條需要查工具時(shí)直接點(diǎn)「工具」那一條。配置文件則放在版本控制里換機(jī)器時(shí)直接拉下來改 Key 就能用。如果你后續(xù)要做長(zhǎng)期編碼或 Agent 開發(fā)可以把模型接入統(tǒng)一走 TaoToken 的 Coding Plan這樣 Key 和 Base URL 只需要維護(hù)一份換模型時(shí)改model_id即可。需要看模型實(shí)際對(duì)話效果可以直接在模型對(duì)話頁試需要生成和管理 Key去 API Keys 頁接入細(xì)節(jié)查接入文檔。這幾條路徑配合上面的配置骨架基本能覆蓋從檢索到落地的全部動(dòng)作。