安裝、認證和第一次啟動
Gemini CLI 起步流程：安裝方式、認證選擇、第一次執行和低風險只讀任務。
Gemini CLI 上手不要先追複雜配置。第一目標是：確認本機能啟動、認證能透過、能在一個專案裡完成低風險只讀任務。
第一次啟動的目標不是證明它“能改程式碼”，而是證明它能在你的環境裡穩定讀取上下文、遵守只讀邊界，並把下一步說清楚。
安裝前檢查
先用 node --version 和 npm --version 確認 Node 環境。
Gemini CLI 是 Node/npm 生態裡的 CLI。官方常見入口包括 npx（臨時執行 npm 包的命令）和全域性安裝。
起步時還要順手看三件事：
| 檢查項 | 為什麼要看 |
|---|---|
node --version | Node 過舊或來源混亂會導致 CLI 和依賴報錯 |
npm config get prefix | 全域性安裝後 gemini 是否能進 PATH |
| 當前網路 / 代理 | 登入、證書、npm 安裝和 web 工具都會受影響 |
執行方式
臨時執行（不寫入全域性 node_modules）：
npx @google/gemini-cli全域性安裝（每次直接 gemini 啟動）：
npm install -g @google/gemini-cli@latest
gemini全域性安裝適合長期使用；npx 適合臨時體驗或確認環境。兩者背後都是同一個官方包 @google/gemini-cli，按官方 安裝頁 的當前推薦為準。
認證方式怎麼選
常見認證入口有三類：
- Google 登入：適合個人體驗 Gemini Code Assist 能力。免費層每天約 1000 次模型請求，Gemini CLI 自動選模型。
- Gemini API Key：適合指令碼、第三方工具和輕量自動化（headless，無人值守環境）。注意 Free 層每天 250 次且只能用 Flash 模型——要用 Pro / Auto 必須切付費。
- Vertex AI：適合企業、雲專案、統一賬單和 IAM（Identity and Access Management，身份與訪問管理）治理。Express 模式免費但 90 天后必須 enable billing。
如果只是第一次學習，先用官方預設登入流程即可。要進入 CI、GitHub Action 或第三方 agent 整合時，再使用 API key 或 Vertex AI。
| 使用場景 | 更適合的認證入口 |
|---|---|
| 本機互動體驗 | Google 登入 |
| 簡單指令碼和 headless | Gemini API Key |
| 企業專案、統一賬單、IAM | Vertex AI |
| GitHub Action | Secret / Workload Identity / 專案級認證策略 |
第一次啟動
進入一個低風險目錄：
可以新建 gemini-cli-test 目錄，進入後執行 gemini。
第一次不要讓它修改檔案，先問只讀問題：
第一次 prompt 可以是：請只讀分析當前目錄，說明這裡有哪些檔案、你能看到什麼、下一步建議我怎麼組織專案。
如果當前目錄為空，可以讓它生成一個計劃，不要直接生成大量檔案。
第一次啟動後看什麼
啟動成功不等於配置完成。先檢查這幾個訊號：
- 它是否能說清當前目錄裡有什麼。
- 它是否遵守"只讀、不修改"的要求。
- 它是否會主動說明需要哪些檔案和驗證命令。
- 它是否把認證、配額或網路問題直接暴露出來。
- 它是否把不確定的地方標出來，而不是硬猜。
跑通第一條只讀任務後，立即用 /init 讓 Gemini CLI 自動生成首份 GEMINI.md。它會掃描專案結構、入口檔案、檢查命令，寫一份初稿放在專案根目錄。你只需要補"禁止觸碰的檔案 / 團隊協作邊界"等人類才知道的規則，比從零寫更省事。詳見 GEMINI.md 篇。
在真實專案裡第一條 prompt
進入真實專案後建議這樣開始：
進入真實專案後的第一條 prompt 建議是：請先只讀掃描當前專案，不要修改檔案，不要執行寫入命令。請說明專案技術堆疊、入口檔案、測試命令、構建命令和潛在風險。
這個 prompt 的關鍵不是措辭，而是邊界：只讀、不修改、不執行寫入命令、先產出判斷。
常見起步問題
geminicommand not found：檢查全域性 npm bin 是否在PATH。- 登入失敗：先看賬號地區、組織 entitlement、
GOOGLE_CLOUD_PROJECT環境變數。 - 429：說明請求或配額觸頂，先降低頻率。
- CI 裡不進互動模式：檢查
CI或CI_字首環境變數。
第一次成功標準
第一次成功不是“能開啟歡迎介面”，而是完成一條只讀任務，並能看到當前目錄、認證狀態、模型或配額提示、下一步建議。建議把這次結果截圖或記錄下來，作為後續排障基線。
如果後續換了 Node、npm prefix、代理、賬號或 Cloud project，先和這條基線對比。
認證基線
第一次啟動後要知道自己用的是哪條認證鏈路。Google 登入、Gemini API Key、Vertex AI、Cloud Shell 和 GitHub Action secret 的排錯路徑不同。比如 API key 更適合 headless 和指令碼，Vertex AI 更適合企業專案和 IAM，Google 登入更適合個人互動體驗。
教程裡不要把一種認證方式的 UI、配額和隱私邊界寫成所有讀者都會看到的結果。每篇涉及認證的頁面都要說明“以你的賬號實際可見為準”。
官方資料
- 官方安裝：docs/get-started/installation.mdx
- 官方認證：docs/get-started/authentication.mdx
- Quickstart：docs/get-started/index.md
- 配額與定價：docs/resources/quota-and-pricing.md