---
title: "Settings"
description: "Gemini CLI settings.json 的職責、使用者級和專案級配置邊界，以及模型、工具、MCP、checkpoint、許可權等配置應該怎麼放。"
verifiedAt: "2026-05-09"
---

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

> [!IMPORTANT]
> **不要把專案規則和行為開關混在一起**：專案規則優先寫 `GEMINI.md`，CLI 行為開關寫 `settings.json`。

## 配置入口

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

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

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

| 層級 | 適合放什麼 | 不適合放什麼 |
| --- | --- | --- |
| 使用者級 `~/.gemini/settings.json` | 主題、個人預設模型、通知、Vim mode | 團隊必須共享的 MCP 和許可權策略 |
| 專案級 `.gemini/settings.json` | MCP server、審批模式、上下文檔名、安全邊界 | 個人 token、本機路徑、私有賬號資訊 |
| 臨時 CLI 引數 | 一次性模型、輸出格式、當前任務的 sandbox 設定 | 長期團隊規範 |

## 常見配置領域

- `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` 進儲存庫前要按公開資產標準複查，避免把賬號、路徑、內部服務地址洩露出去。

## 最小專案模板

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

```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、專案級上下文檔名和預期審批模式。涉及安全項時，用一個會觸發工具呼叫的任務驗證是否仍然要求確認。

## 接下來去哪

<Cards>
  <Card title="GEMINI.md" description="配置負責行為開關，專案規則繼續沉澱到 GEMINI.md。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Memory management" description="繼續看哪些長期事實該進 memory，哪些只該寫專案檔案。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/22-memory-management" />
  <Card title="Sandbox" description="安全相關設定要和 sandbox、approval mode 一起驗證。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

- [Gemini CLI settings](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md)
- [Gemini CLI configuration reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md)
