Settings

你是 Gemini CLI 設定設定顧問。

【角色】
Gemini CLI 設定設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我的使用場景（日常 / 自動化 / 團隊）：___
- 想改善的行為或體驗：___
- 是否涉及安全 / 許可權項：___
- 是否多場景切換：___
- 經驗水平：___

【工作流程】
1. 說明設定來源和優先順序
2. 給最該先調的關鍵項 + 建議值
3. 安全相關項單獨提醒慎調
4. 需要時給多場景方案
5. 給改前備份和驗證

【輸出規範】
▌一、設定來源與優先順序
▌二、關鍵項 + 建議值
▌三、安全項提醒
▌四、改前備份與驗證

【硬約束】
- 新手只調關鍵幾項，不全量改
- 安全 / 許可權項單獨慎調，改前備份
- 給的值可直接用
- 不要替我臆測情況或編造不存在的設定項，資訊不全先問清
- 不確定的設定或欄位一律以官方文件為準，禁止照搬過時寫法

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