---
title: "Policy engine"
description: "Gemini CLI policy engine 的用途：細粒度控制工具執行、替代簡單 allowed tools、適合團隊和企業治理。"
verifiedAt: "2026-05-09"
---

Policy engine 用來更細粒度地控制工具能否執行、在什麼條件下執行。官方 CLI cheatsheet 裡也提示 `--allowed-tools` 已 deprecated，建議使用 policy engine。

> [!IMPORTANT]
> 許可權邊界要寫進 policy，不要只寫進 prompt。Prompt 是建議，policy 是執行前攔截。

它的核心不是“開或關某個工具”，而是按規則決定工具呼叫應該 `allow`、`deny` 還是 `ask_user`。規則寫在 TOML 檔案中，可以匹配工具名、引數、互動模式和優先順序。

Policy 的價值在於執行前攔截。尤其是 shell、MCP 寫工具、subagent 和自動化任務，越不能靠“模型會聽話”來控制。規則要能被負例測試觸發。

## 適合控制

- 哪些工具可用。
- 哪些命令需要確認。
- 哪些目錄禁止寫。
- 哪些 MCP server 可以用。
- 團隊預設安全策略。

## 基本規則

最常見的規則結構包含四個欄位：

- `toolName`：匹配工具名，例如 `run_shell_command`。
- `commandPrefix` 或 `argsPattern`：匹配命令或引數。
- `decision`：`allow`、`deny` 或 `ask_user`。
- `priority`：數字越大優先順序越高。

例如高風險 shell 字首應當直接 deny；常見但有副作用的 `git`、`npm`、`pnpm`、`docker` 命令可以先設為 `ask_user`。

## 決策含義

- `allow`：工具直接執行，不再詢問。
- `ask_user`：讓使用者確認；headless 場景裡通常等同於 deny。
- `deny`：阻斷工具呼叫。對於全域性 deny，工具還會從模型可見工具列表中排除，這比只靠 prompt 要可靠。

## 優先順序與層級

Policy engine 有 Default、Extension、Workspace、User、Admin 等層級。官方文件特別說明：Workspace tier 當前不可用，專案級 `.gemini/policies` 不會生效，應使用 User 或 Admin policies。

團隊環境裡，Admin policy 應該壓過個人配置；個人本機可以用 `~/.gemini/policies/*.toml` 做預設保護。

## 使用建議

個人專案可以先用預設確認；團隊專案應該把 policy 寫清楚，避免每個人用不同的許可權模型。

不要只靠“請不要刪除檔案”這種 prompt 管許可權。真正的許可權邊界應該進入 policy：危險 shell 字首、未知 MCP 寫操作、生產目錄寫入、部署和刪除命令都應明確規則。

| 風險 | 建議 decision |
| --- | --- |
| `git status`、`rg`、只讀診斷 | `allow` 或預設確認 |
| `npm install`、`docker`、遷移命令 | `ask_user` |
| `rm -rf`、生產目錄寫入 | `deny` |
| 未知 MCP 寫操作 | `ask_user` 或 `deny` |
| headless 中需要人工確認的動作 | `deny` |

## 驗收方式

寫完 policy 後要主動觸發測試：讓 Gemini CLI 嘗試一個應該被攔截的命令，確認它被 deny 或 ask_user；再測試一個應該允許的只讀命令，確認沒有誤傷。否則 policy 只是“看起來安全”。

還要做反向測試：確認高優先順序 deny 不會被低優先順序 allow 覆蓋，確認 headless 中 `ask_user` 不會變成靜默允許。團隊環境裡，每次改 policy 都應該留下測試用例和預期結果。

企業環境還應把 policy 版本化，避免各機器漂移。

如果一個動作在互動模式下是 `ask_user`，在無互動 headless 場景裡要按不可確認處理。自動化任務不應該依賴人工彈出視窗；需要人工確認的動作要在 CI 之前拆成審批步驟。

## 最小上線組合

個人專案可以從三條規則開始：允許只讀診斷，詢問安裝依賴和 Git 寫操作，拒絕刪除、部署和生產目錄寫入。團隊專案再補 MCP allowlist、subagent 限制和 Admin policy。

Policy 不需要一次寫成“大而全”。先覆蓋最危險的誤操作，再用日誌和失敗案例補規則，反而更容易維護。

## 接下來去哪

<Cards>
  <Card title="Enterprise config" description="團隊和企業要把 policy 放進統一配置與管理路徑。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/62-enterprise-config" />
  <Card title="MCP 設定" description="MCP 寫工具也要受 policy 和最小許可權控制。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Sandbox" description="policy 管許可權，sandbox 管執行環境，兩者配合使用。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

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