---
title: "Enterprise config"
description: "Gemini CLI enterprise configuration：組織賬號、Cloud project、Vertex AI、許可、固定策略和團隊預設配置。"
verifiedAt: "2026-05-09"
---

企業配置的重點不是“裝上 CLI”，而是統一身份、專案、許可權、模型、日誌和成本邊界。

> [!NOTE]
> 企業配置要看最終合併結果，不只看某個 settings 檔案。使用者級、專案級、系統級和環境變數可能互相覆蓋。

官方企業文件的核心是兩層配置：系統級 settings 提供集中預設值和覆蓋值，Admin Controls 提供本地不可覆蓋的組織策略。系統級 settings 能防誤用，但不能防擁有本機管理員許可權的人刻意繞過。

## 企業使用者要先確認

- 賬號型別：Workspace / organization / personal。
- Gemini Code Assist license。
- Google Cloud Project。
- Vertex AI 是否啟用。
- IAM 角色。
- 計費和配額。
- telemetry 和合規要求。

## 系統級配置層級

Gemini CLI 企業配置會合並四類 settings。單值欄位按優先順序覆蓋：

1. System Defaults：`system-defaults.json`
2. User Settings：`~/.gemini/settings.json`
3. Workspace Settings：`<project>/.gemini/settings.json`
4. System Overrides：`settings.json`

System Overrides 擁有最終決定權。陣列和物件欄位會合並，例如 `includeDirectories` 可能拼接，`mcpServers` 可能按 key 合併。

Firecrawl 抓到的官方企業頁也強調：allowlist 比 blocklist 更穩，`tools.core` 適合明確允許哪些內建工具，`tools.exclude` 更適合少量補充限制。企業預設策略不要只靠 exclude。

系統級 settings 路徑：

- Linux：`/etc/gemini-cli/settings.json`
- macOS：`/Library/Application Support/GeminiCli/settings.json`
- Windows：`C:\ProgramData\gemini-cli\settings.json`

也可以用 `GEMINI_CLI_SYSTEM_SETTINGS_PATH` 指定路徑。企業落地時通常會用 wrapper script 固定這個環境變數，避免使用者隨意改到另一份 settings。

## 共享環境隔離

在 CI、共享構建機或實驗平臺上，不要複用預設 `~/.gemini` 狀態。官方支援用 `GEMINI_CLI_HOME` 把 Gemini CLI 的配置和歷史隔離到指定目錄：

```bash
export GEMINI_CLI_HOME="/tmp/gemini-job-123"
gemini
```

這樣能減少不同使用者、不同 job 之間的配置汙染。

## 配置建議

個人偏好不要覆蓋組織策略。團隊預設配置應透過專案級 settings 和企業系統級 settings 統一管理。高風險工具不要只靠口頭約定，應該結合 `tools.core` allowlist 和 policy engine 控制。

| 配置目標 | 推薦落點 |
| --- | --- |
| 個人 UI 偏好 | 使用者級 settings |
| 團隊 MCP 預設 | 專案級或系統級 settings |
| 企業不可繞過策略 | Admin controls / system overrides |
| CI 隔離 | `GEMINI_CLI_HOME` |
| 成本和審計 | telemetry + Cloud project |

## Rollout 順序

企業落地不要一次性全員強推。更穩的順序是：

1. 在測試機器上驗證系統級 settings。
2. 給一組試點使用者啟用預設配置。
3. 驗證 policy、MCP、telemetry、模型選擇和成本歸屬。
4. 再推廣到團隊或組織。
5. 保留回復路徑和配置版本記錄。

這樣可以把“配置語法正確”和“組織實際可用”分開驗收。

## 驗收方式

企業配置驗收要看“最終合併結果”，不能只看某一份檔案。至少驗證三件事：系統覆蓋是否高於使用者配置，MCP server 是否按企業配置生效，`GEMINI_CLI_HOME` 或系統 settings 路徑是否沒有洩露到普通使用者可寫目錄。

還要驗證使用者是否能透過環境變數改到另一份系統 settings。若使用 `GEMINI_CLI_SYSTEM_SETTINGS_PATH`，wrapper script 和終端入口都要統一，不要只改一臺測試機。

## 接下來去哪

<Cards>
  <Card title="Enterprise controls" description="繼續看組織級 controls、policy、telemetry 和不可覆蓋邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/63-enterprise-controls" />
  <Card title="Policy engine" description="工具許可權要進入 policy，而不是隻靠團隊口頭約定。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
  <Card title="Telemetry" description="企業落地還要設計日誌、審計和可觀測性。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/64-telemetry" />
</Cards>

## 官方來源

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