Settings

settings.json 是 Gemini CLI 的行為配置入口。它適合放模型、工具、MCP、checkpoint、許可權、UI 和其他 CLI 行為開關。

配置入口

Gemini CLI 可以透過 /settings 圖形化編輯設定，也可以直接改 JSON 檔案。官方路徑是：

• 使用者級：~/.gemini/settings.json
• 工作區級：<project>/.gemini/settings.json

工作區級會覆蓋使用者級。這個規則決定了團隊專案的推薦做法：個人偏好放使用者級，專案約束放儲存庫內 .gemini/settings.json。

常見配置領域

• general.defaultApprovalMode：預設工具審批模式。日常專案用 default，只讀規劃用 plan，不要把 yolo 當團隊預設值。
• model.name、model.maxSessionTurns、model.compressionThreshold：模型、會話輪數和上下文壓縮閾值。
• context.fileName：自定義上下文檔名，比如同時讀取 AGENTS.md、CONTEXT.md、GEMINI.md。
• context.fileFiltering.respectGitIgnore：是否讓上下文檢索尊重 .gitignore。
• mcpServers：專案 MCP 入口，適合放需要隨專案一起共享的服務定義。
• security.*：YOLO 停用、永久授權、擴充套件來源、資料夾信任、環境變數脫敏等安全開關。
• telemetry.*：OpenTelemetry、本地日誌或 Google Cloud telemetry 相關設定。
• ui.*：主題、頁尾、模型資訊、上下文百分比、可訪問性等顯示行為。

放置策略

使用者級設定只放“我個人在哪個專案都想要”的偏好，例如主題、Vim mode、通知、預設模型。專案級設定只放“換一個人拉儲存庫也應該一致”的約束，例如 MCP server、工具審批、上下文檔名、安全邊界、checkpoint 策略。

金鑰不要寫進 settings.json。Gemini API key、Google Cloud project、Vertex AI 開關這類執行差異，用環境變數或本機憑據管理。settings.json 進儲存庫前要按公開資產標準複查，避免把賬號、路徑、內部服務地址洩露出去。

最小專案模板

真實專案可以先從小模板開始：

{
  "general": {
    "defaultApprovalMode": "default"
  },
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "security": {
    "disableYoloMode": true
  }
}

需要團隊共享 MCP 時，再補 mcpServers。需要自動化時，再補 output.format、headless 引數或 telemetry。不要一次複製官方完整 reference；欄位越多，排錯越難。

改配置的順序

配置改動建議按這個順序推進：

1. 先確定這是個人偏好還是專案約束。
2. 再決定寫使用者級、專案級，還是隻用本次 CLI 引數。
3. 修改後重啟或重新進入 Gemini CLI。
4. 用 /settings 檢查最終生效值。
5. 用一個最小任務觸發相關行為，確認不是隻寫了檔案但沒有生效。

如果配置項涉及安全、MCP、工具審批或 telemetry，不要只看 JSON 是否合法。必須實際觸發一次對應能力：比如讓工具請求 shell 執行、檢視 MCP server 列表，或確認 telemetry 目標沒有把私有內容打出去。

驗收方式

改完後重啟 Gemini CLI，進入專案目錄執行 /settings 檢查實際生效值。再讓 Gemini CLI 執行一個只讀任務，確認它載入的是專案級 MCP、專案級上下文檔名和預期審批模式。涉及安全項時，用一個會觸發工具呼叫的任務驗證是否仍然要求確認。

接下來去哪

官方來源

• Gemini CLI settings
• Gemini CLI configuration reference