Google 的開源 Gemini CLI——將 Gemini 帶入你的殼層的終端型 AI 代理——自推出以來快速成熟，現在已支援豐富的設定、專案情境檔案（GEMINI.md / .gemini）、自訂斜線命令，以及工作區目錄控管。該專案在 GitHub（官方儲存庫）上持續演進，已進入具備寬鬆配額的公開預覽階段，並正在整合到其他開發者工具（編輯器整合與 CI/Actions）。但當團隊擴大，或你在跨磁碟或限制性環境（容器、公司管控筆電、Cloud Shell、Windows 系統）中工作時，很快就會遇到一個實務問題：Gemini 將其檔案儲存在何處？以及如何變更 Gemini 讀寫的目錄？
什麼是 Gemini CLI？
Gemini CLI 是 Google 的開源命令列 AI 代理，將 Gemini 模型的能力直接帶入你的終端機。它提供互動式代理功能，用於程式碼協助、檔案與專案檢視、執行殼層命令（具保護機制），以及整合 Google Search、Model Context Protocol（MCP）擴充、與隨 Gemini 釋出的媒體產生工具。CLI 設計為輕量、可編寫腳本且可擴充；可從官方儲存庫取得，並已打包便於安裝。
為什麼目錄很重要
Gemini CLI 會將設定（例如 settings.json）、系統提示或情境（GEMINI.md）、快取的憑證、遙測識別碼，以及其他持久狀態存放在 .gemini 目錄中。此目錄所在位置會影響：
- CLI 載入哪些設定（全域 vs. 專案層級），
- 代理會讀取哪些「記憶」檔案，
- 憑證快取位置（影響登入行為），
- 當你要提供自訂設定儲存庫時的跨機器或 CI 可重現性。
了解並（在必要時）變更此目錄，有助於多專案工作流程、CI、容器化部署，以及具有集中化設定儲存的團隊。
Gemini CLI 預設將設定儲存在哪裡？
預設情況下，CLI 使用 .gemini 目錄。對大多數使用者安裝而言，這會解析到 ~/.gemini（家目錄中的 .gemini 資料夾）。CLI 也支援專案層級的 .gemini 檔案（例如專案根目錄中的 .gemini/settings.json），當你在該專案資料夾中操作時，這些會覆寫使用者設定。系統層級設定會在適用時，從特定作業系統位置讀取（例如 Linux 的 /etc/ 或 Windows 的 %PROGRAMDATA%）。典型路徑：
- Linux / macOS：
~/.gemini/（例如/home/alice/.gemini或/Users/alice/.gemini）。 - Windows：
%USERPROFILE%\.gemini（例如C:\Users\Alice\.gemini）。
在.gemini中，你通常會看到settings.json、GEMINI.md、commands/，以及本機快取。CLI 也會讀取專案根目錄中的.gemini/資料夾以取得專案層級設定。
此預設很重要：歷史上，設定目錄一直是硬編碼為家目錄中的 .gemini
如何變更或重新導向 Gemini CLI 的設定目錄？
有幾種實務方法——從最簡單（在期望的資料夾中工作）到更健壯（環境變數或檔案系統重新導向）。請根據你是否掌控執行環境（本機開發機 vs. CI）、所使用的作業系統，以及你偏好暫時或永久變更來選擇做法。
1) 使用專案層級的 .gemini（建議用於每專案設定）
若你希望每專案有不同設定，請在專案根目錄建立 .gemini 子目錄，並將 settings.json、GEMINI.md 與其他專案檔案放置其中。當你在該專案目錄中啟動 gemini 時，CLI 會優先載入專案設定：
your-project/├─ .gemini/│ ├─ settings.json│ └─ GEMINI.md└─ src/
在你的殼層位於 your-project/ 時啟動 gemini，CLI 會從該樹狀結構中拾取 .gemini 檔案（它會向上搜尋以找到專案情境）。這是每專案設定最安全且明確的方法。
2) 使用有文件記載的環境變數（在支援時）
Gemini CLI 的程式碼庫與文件提到數個用於調整行為的環境變數。其中一些用於系統設定或特殊檔案覆寫：
GEMINI_API_KEY、GEMINI_MODEL等，常用於驗證與模型選擇。- 程式碼庫與文件中提到如
GEMINI_CLI_SYSTEM_SETTINGS_PATH（用來覆寫系統設定路徑）與像GEMINI_CONFIG_DIR的常數（程式碼中預設的.gemini名稱）。社群的需求與 PR 有提議新增或支援GEMINI_CONFIG_DIR環境變數，以便使用者搬移整個設定目錄。
範例（bash / macOS / Linux）：
# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"# Then rungemini
PowerShell（Windows）：
$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini
重要注意事項：根據最新的社群討論與議題，
GEMINI_CONFIG_DIR雖已在部分地方被提出與引用——但據報在特定平台（尤其是 Windows）存在錯誤與行為不一致。這表示基於環境變數的重新導向，可能在各平台或版本上未必可靠。若你依賴此方式，請檢查你所安裝版本的 Gemini CLI 版本資訊與儲存庫議題。
3) 在工作階段內新增 Gemini 的工作區目錄
如果你想讓 Gemini 能感知其他目錄（以便讀取檔案作為情境），可以使用互動式的 /directory 指令集。例如：
/directory add path/to/another/project/directory list
這不會移動設定目錄，但允許代理在其工作區情境中納入其他目錄的檔案。當你希望代理參考其他儲存庫、且不變更全域設定時，這很有用。
4) 建立符號連結或檔案系統繫結（務實的替代方案）
如果 CLI 無法接受環境覆寫，或你需要一個可靠的跨程序解法，可使用檔案系統重新導向：
在 Unix/macOS：
# move the original config foldermv ~/.gemini ~/gemini_backup# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini
在 Windows（PowerShell 系統管理員提示字元）：
# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig
此作法強制 CLI 從你指定的位置讀取，而不需 CLI 原生支援。注意：符號連結/目錄接點需要適當的檔案系統權限，且在容器或 Windows 環境中行為可能有所不同。請謹慎使用。（見下文「特定於 Windows 的說明」。）
5) 變更該程序的有效家目錄（容器/CI 小技巧）
在 CI、容器或短暫環境中執行時，你可以為 gemini 程序變更 $HOME（Unix）或 %USERPROFILE%（Windows）環境變數，使其預設的 ~/.gemini 解析到你控制的路徑：
# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini
這有助於 CI 的可重現性，但請留意：變更 HOME 可能影響其他工具與驗證流程（例如 Google OAuth 快取），因此請將此技巧限制在隔離的容器或程序層級包裝中。
如何透過 CometAPI 安裝並使用 Gemini CLI？
簡短答案：你有兩條務實路徑——（A）透過 CometAPI 直接呼叫 Gemini 模型（建議且最簡單），或（B）讓官方 Gemini CLI 與 CometAPI 溝通：使用支援自訂基底 URL 的某些 Gemini-CLI 版本（部分版本/PR 有新增），或執行一個小型本機代理，將 Gemini-CLI 的請求轉換為 CometAPI/OpenAI 風格的呼叫。
什麼是 CometAPI？
CometAPI 是一個 API 聚合/閘道，透過 OpenAI 風格的 HTTP API 對外提供數百個第三方模型（包含 Google 的 Gemini 系列）。你註冊、取得 Bearer API 金鑰，然後呼叫像是 https://api.cometapi.com/v1/chat/completions 的端點。CometAPI 在 Authorization 標頭中使用標準的 Bearer 權杖。
為什麼使用 CometAPI？它提供比官方 API 更低的價格以便於整合。Gemini CLI 安裝與使用指南：
如何透過 CometAPI 直接呼叫 Gemini 模型？（建議）
如果你的目標是使用 Gemini 模型而不嚴格需要 Gemini CLI 的功能，直接呼叫 CometAPI 十分直接且可靠。
export COMET_KEY="sk-xxxx"curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \ -H "Authorization: Bearer $COMET_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-2.5-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the 3 key benefits of unit tests."} ], "max_tokens": 300 }' | jq .
這些直接呼叫讓你能將 CometAPI 整合到腳本、應用程式或 CI，而不需依賴 Gemini CLI。
可以讓 Gemini CLI 使用 CometAPI 嗎？
某些 Gemini CLI 版本/PR 新增了用於覆寫 Gemini API 基底 URL 的環境變數。若你安裝的 gemini 支援設定自訂的 Gemini 基底 URL 且可使用 CometAPI 金鑰，你可以將其指向 CometAPI，並將 CometAPI 金鑰設為 GEMINI_API_KEY（CLI 期望使用名為 GEMINI_API_KEY 的變數來進行 Gemini API 金鑰驗證）。
範例：
# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx" # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1" # if supportedgemini # run the CLI; it will use the configured base URL
疑難排解：常見問題與修復
問題：Gemini 無法看到另一個存放庫中的檔案
- 啟動時嘗試
gemini --include-directories /path/to/repo。或在工作階段中：/directory add /path/to/repo。 - 如果存放庫位於網路掛載上，請檢查權限，以及 CLI 程序使用者是否能讀取這些檔案。
- 如果你使用符號連結來移動
.gemini，請確認 CLI 是否會追蹤GEMINI.md與settings.json的連結（部分版本出於安全性不追蹤特定符號連結）。
問題：gemini 在 Windows 上無法建立 ~/.gemini（EPERM）
這通常表示你的程序沒有權限寫入 %USERPROFILE%。修復方式：
- 以系統管理員執行終端機或調整資料夾權限。
- 透過符號連結設定自訂設定位置，或在支援時透過環境變數（留意未來對
GEMINI_CONFIG_DIR的支援）。
問題：cd 無法在殼層模式中改變工作目錄
這在部分平台上是已知問題。建議：改為在 Gemini CLI 程序外執行殼層命令，或透過 /directory add 新增目錄。
問題：CometAPI 模型名稱與預期不符
呼叫 /v1/models 端點並檢視 JSON。模型 ID 通常包含精確的變體字串（例如 gemini-2.5-flash-preview-04-17）。請在請求中使用完全相同的字串。
結論
Gemini CLI 的預設設計偏向合理且易於理解：使用者層級的 ~/.gemini 作為全域預設，以及專案層級的 .gemini 作為每個儲存庫的覆寫。社群一直在推動更原生的可設定性（明確的環境變數或旗標），以使工具更適合多使用者、容器化與企業環境。
如何變更 Gemini CLI 目錄：
概述：Gemini CLI 會將使用者層級的設定與情境檔案儲存在 .gemini 目錄（通常為 ~/.gemini）中。你可以透過以下方式影響 CLI 使用的目錄：（1）在目前工作目錄中依賴專案層級的 .gemini，（2）在支援時使用環境變數或 CLI 選項，（3）在互動工作階段中新增工作區目錄，或（4）在缺少原生選項時使用檔案系統技術（符號連結、繫結掛載，或變更家目錄/使用者設定變數）。
開始之前，請在 Playground 探索 Gemini 模型（例如 Gemini 3 Pro）的功能，並參考 API guide 以取得詳細說明。在存取之前，請確保你已登入 CometAPI 並取得 API 金鑰。CometAPI 提供遠低於官方價格的方案，以協助你進行整合。
準備好了嗎？→ 免費試用 gemini 模型！
