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