Gemini CLI 策略引擎：如何控制 AI Agent 的行为

在将AI Agent部署到生产环境时,安全治理始终是绕不开的话题。

如何确保AI不会执行危险的系统命令?
如何限制AI对敏感数据的访问?
如何在保证灵活性的同时满足企业的合规要求?

Gemini CLI的策略引擎(Policy Engine)正是为解决这些问题而设计的企业级安全治理方案。

Gemini CLI的策略引擎

策略引擎提供了对工具执行的细粒度控制能力,通过预定义的规则来决定工具调用是被允许、拒绝还是需要用户确认。这种设计在AI Agent的自主性和安全可控性之间找到了平衡点。

在实际的企业环境中,策略引擎解决了以下问题:

安全风险管控: 通过规则限制AI可以执行的操作,防止误删除、误修改等高风险行为。例如,可以禁止AI执行rm -rf这类危险命令,或者要求对所有git操作进行人工确认。
分层权限管理: 策略引擎支持三个层级的规则定义——默认层(Default)、用户层(User)、管理员层(Admin),满足从个人配置到企业统一管控的不同需求。
合规性支持: 对于有严格数据访问和操作审计要求的企业,策略引擎提供了规则化的管控机制,可以记录和追溯AI的每一次敏感操作。

规则的基本结构

每条策略规则由三个核心要素组成:

1. 条件(Conditions)

条件定义了规则何时生效。可以根据以下维度来匹配工具调用:

工具名称: 通过toolName字段指定,支持精确匹配和通配符
工具参数: 通过argsPattern使用正则表达式匹配参数内容
命令前缀: 对shell命令使用commandPrefix进行前缀匹配
命令模式: 通过commandRegex使用正则表达式匹配完整命令
MCP服务器: 针对Model Context Protocol服务器的工具进行匹配

2. 决策(Decision)

决策定义了当条件满足时的执行策略,有三种类型:

allow: 自动允许执行,无需用户确认
deny: 直接拒绝执行,阻止操作
ask_user: 询问用户是否执行(在非交互模式下视为拒绝)

3. 优先级(Priority)

当多条规则同时匹配时,优先级最高的规则生效。

优先级系统

策略引擎采用了分层优先级系统,将规则分为三个组织层级:

层级	基础值	用途
Default	1	系统内置的默认策略
User	2	用户自定义的个性化策略
Admin	3	企业管理员的统一策略

最终优先级的计算公式是:

final_priority = tier_base + (toml_priority / 1000)

举例说明:

Default层的priority=50规则,最终优先级为1.050
User层的priority=100规则,最终优先级为2.100
Admin层的priority=20规则,最终优先级为3.020

由于 TOML 配置文件中配置的 priority 值(配置的值最大999)除以 1000 后只贡献小数部分(最多 0.999),而层级基础值占据整数部分,这就保证了高层级的规则永远优先。即使用户设置 priority=999(最终为 2.999),也无法超过管理员层级的任何规则(最低为 3.000)。

配置语法

策略规则使用TOML格式配置,每条规则使用 [[rule]] 块定义。下面是完整的字段说明。

规则字段说明

必需字段:

decision: 执行决策,可选值:
- "allow": 允许执行
- "deny": 拒绝执行
- "ask_user": 询问用户
priority: 优先级值,范围 0-999

条件字段(至少指定一个):

toolName: 工具名称,支持字符串或字符串数组,可使用通配符(如 "my-server__*")
mcpName: MCP 服务器名称
argsPattern: 正则表达式,匹配工具参数的 JSON 序列化结果

Shell 命令快捷字段(仅用于 run_shell_command 工具):

commandPrefix: 命令前缀匹配(字符串)
commandRegex: 命令正则匹配(注意: commandPrefix 和 commandRegex 不能同时使用)

可选字段:

modes: 字符串数组,指定规则在哪些运行模式下生效(如 ["autoEdit"])

注意事项:

条件字段采用"全部匹配"逻辑 - 所有指定的条件都必须满足,规则才会生效
argsPattern 匹配的是参数的完整 JSON 表示,正则锚点(如 ^ 和 $)应用于整个 JSON 字符串
当多条规则匹配时,优先级最高的规则生效

完整规则示例

下面是一个包含所有字段的示例规则(实际使用时根据需要选择字段):

[[rule]]
# 工具名称,字符串或字符串数组
toolName = "run_shell_command"

# (可选) MCP 服务器名称,可与 toolName 组合形成 "mcpName__toolName" 格式
mcpName = "my-custom-server"

# (可选) 匹配工具参数的正则表达式
argsPattern = '"command":"(git|npm)'

# (可选) Shell 命令前缀匹配(字符串或字符串数组)
# 这是 `toolName = "run_shell_command"` + `argsPattern` 的语法糖
commandPrefix = "git "

# (可选) Shell 命令正则匹配
# 同样是 `toolName = "run_shell_command"` 的语法糖
# 注意: 此模式匹配的是参数的 JSON 表示(如 {"command":"<your_command>"}),
# 因此锚点 ^ 或 $ 应用于完整的 JSON 字符串,而非命令文本本身
# 不能与 commandPrefix 同时使用
commandRegex = "^git (commit|push)"

# 执行决策: "allow", "deny", 或 "ask_user"
decision = "ask_user"

# 优先级,范围 0-999
priority = 10

# (可选) 规则生效的运行模式数组
modes = ["autoEdit"]

实战场景

下面通过实际场景展示如何使用这些字段。

场景1: Git命令人工确认

在代码仓库操作中,我们希望AI执行git命令前都需要人工确认:

[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "ask_user"
priority = 100

这条规则会拦截所有以git 开头的shell命令,要求用户确认后才能执行。

场景2: 禁止删除操作

对于生产环境,我们需要完全禁止删除文件的操作:

[[rule]]
toolName = "run_shell_command"
commandRegex = "rm\\s+-rf.*"
decision = "deny"
priority = 200

注意commandRegex使用正则表达式,可以精确匹配命令模式。

场景3: 限制文件写入权限

只允许AI写入特定目录的文件:

[[rule]]
toolName = ["write_file", "replace"]
decision = "ask_user"
priority = 10

这里使用数组同时限制多个工具,对所有文件写入操作都需要确认。

场景4: MCP服务器权限管控

当使用Model Context Protocol集成外部工具时,可以针对特定服务器设置策略:

# 允许可信服务器的搜索功能
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

# 拒绝不可信服务器的所有工具
[[rule]]
mcpName = "untrusted-server"
decision = "deny"
priority = 500

MCP工具支持通配符匹配,例如toolName = "server__*"可以匹配某个服务器的所有工具。

场景5: 基于运行模式的策略

策略可以针对不同的运行模式生效。例如,只在autoEdit模式下限制某些操作:

[[rule]]
toolName = "run_shell_command"
decision = "ask_user"
priority = 10
modes = ["autoEdit"]

如果规则没有指定modes字段,则在所有模式下都生效。

规则匹配逻辑

理解规则的匹配逻辑对于正确配置策略至关重要:

全部条件满足: 规则中定义的所有条件字段都必须匹配,规则才会生效
最高优先级胜出: 当多条规则同时匹配时,选择优先级最高的规则
参数匹配: 如果指定了argsPattern,会将工具参数序列化为JSON后进行正则匹配
通配符支持: MCP工具名称支持通配符模式

例如,以下配置:

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["rm", "dd", "mkfs"]
decision = "deny"
priority = 500

这条规则会匹配所有以rm、dd或mkfs开头的shell命令,并直接拒绝执行。

运行模式与策略的关系

Gemini CLI 支持三种运行模式(approval mode),策略引擎可以根据模式调整行为:

运行模式说明

default 模式(标准模式): 默认模式,所有工具调用都会根据策略规则进行判断,未明确允许的操作需要用户确认。
auto_edit 模式: 自动批准文件编辑操作,但其他操作(如 shell 命令)仍需确认。适合频繁修改代码但需要控制系统命令的场景。
yolo 模式: 自动批准所有工具调用。在这个模式下,除非有明确的 deny 规则,否则所有操作都会自动执行。适合快速原型开发,但存在安全风险。

模式切换

启动时指定: gemini --approval-mode=yolo 或 gemini --yolo
运行时切换: 按 Ctrl+Y 切换 yolo 模式开关

modes 字段行为

规则中的 modes 字段用于限制规则在哪些模式下生效:

[[rule]]
toolName = "run_shell_command"
decision = "deny"
priority = 100
modes = ["yolo"]  # 只在 yolo 模式下生效

重要: 如果规则没有指定 modes 字段(或为空数组),则该规则在所有模式下都生效。这是默认行为。

通过 modes 字段,可以实现灵活的权限管控,例如:

在 yolo 模式下禁止某些危险操作
在 auto_edit 模式下对特定文件要求确认

默认策略行为

系统内置了一套合理的默认策略:

只读工具: read_file、glob等只读工具默认允许执行
写入工具: write_file、run_shell_command等写入工具默认需要用户确认
模式覆盖: 在yolo模式下允许所有操作,在autoEdit模式下允许无限制写入

这些默认策略位于Default层,优先级最低,用户和管理员可以通过配置覆盖这些行为。

启用策略引擎

策略引擎依赖消息总线集成功能,需要在配置文件中启用:

{
  "tools": {
    "enableMessageBusIntegration": true
  }
}

这个配置位于settings.json文件中。启用后,策略引擎会自动读取并应用策略规则。

最佳实践

基于策略引擎的特性,以下是一些实际部署的最佳实践:

1. 渐进式权限收紧

初期可以使用ask_user决策收集数据,了解AI实际使用哪些工具和命令。经过一段时间的观察后,再将安全的操作设置为allow,将危险操作设置为deny。

2. 分层管理策略

User层: 开发者根据个人工作流程配置便利性规则
Admin层: IT部门配置强制的安全规则,如禁止访问生产环境敏感数据

3. 使用高优先级保护关键规则

对于必须执行的安全规则,设置较高的priority值,确保不会被其他规则意外覆盖。

4. MCP工具的白名单管理

对于集成的MCP服务器,建议采用白名单策略:针对每个MCP服务器设置基础拒绝规则,然后为需要的工具开放权限。

# 基础规则：拒绝某个MCP服务器的所有工具（优先级较低）
[[rule]]
mcpName = "external-service"
decision = "deny"
priority = 900

# 例外规则：允许该服务器的特定工具（优先级更高）
[[rule]]
mcpName = "external-service"
toolName = "search"
decision = "allow"
priority = 950

5. 命令模式的精确控制

对于shell命令,优先使用commandPrefix而不是commandRegex,前者性能更好且更容易维护。只有在需要复杂模式匹配时才使用正则表达式。

配置文件位置

策略配置使用 .toml 文件格式。CLI 会从三个目录层级加载策略文件:

User 层(用户策略)

目录: ~/.gemini/policies/

在此目录下创建 .toml 文件即可定义用户级策略。例如:

~/.gemini/policies/my-rules.toml
~/.gemini/policies/git-rules.toml

Admin 层(管理员策略)

macOS: /Library/Application Support/GeminiCli/policies/
Windows: C:\ProgramData\gemini-cli\policies\
Linux: /etc/gemini-cli/policies/

管理员策略通常需要系统管理员权限进行配置,可通过环境变量 GEMINI_CLI_SYSTEM_SETTINGS_PATH 自定义路径，在"$GEMINI_CLI_SYSTEM_SETTINGS_PATH/policies"下

Default 层(默认策略)

位置: 内置在 Gemini CLI 安装包中(packages/core/src/policy/policies)

这些是系统预设的策略,不需要手动配置。

一个完整的策略配置文件示例:

# 策略配置文件示例

# 禁止删除操作
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["rm -rf", "dd", "mkfs"]
decision = "deny"
priority = 500

# Git操作需要确认
[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "ask_user"
priority = 100

# 允许安全的读取操作
[[rule]]
toolName = ["read_file", "glob", "list_directory"]
decision = "allow"
priority = 50

# MCP工具白名单
[[rule]]
mcpName = "github-server"
decision = "allow"
priority = 200

# 默认拒绝未知MCP服务器
[[rule]]
toolName = "mcp__*"
decision = "deny"
priority = 900

总结

Gemini CLI的策略引擎为AI Agent的企业级部署提供了必要的安全治理能力。通过灵活的规则配置、清晰的优先级系统和分层管理机制,它在保证AI自主性的同时,也确保了操作的安全可控。

对于正在考虑将AI Agent集成到生产环境的团队,策略引擎是一个值得深入研究和充分利用的工具。从基础的命令限制到复杂的MCP服务器权限管控,策略引擎都提供了完善的支持。

策略引擎通过分层执行强制实现了安全防护。管理员层的策略始终优先于用户层,这确保了企业级的安全管控不会被个人配置绕过。

值得注意的是,策略引擎在工具执行前进行检查,是一种预防性的安全机制。配合Gemini CLI的其他安全特性(如审计日志、沙箱执行等),可以构建完整的AI Agent安全防护体系。

建议在实际部署时,从保守的策略开始,逐步根据使用情况调整规则,最终找到适合自己团队的安全与效率的平衡点。

参考资料

Gemini CLI Policy Engine 官方文档