---
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="/docs/gemini-cli/official/06-security-enterprise/62-enterprise-config" />
  <Card title="MCP 设置" description="MCP 写工具也要受 policy 和最小权限控制。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Sandbox" description="policy 管权限，sandbox 管执行环境，两者配合使用。" href="/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)
