정책 엔진 (Policy engine)

Gemini CLI에는 도구 실행을 세밀하게 제어할 수 있는 강력한 정책 엔진이 포함되어 있습니다. 사용자와 관리자는 도구 호출을 허용, 거부 또는 사용자 확인을 필요로 할지 결정하는 규칙을 정의할 수 있습니다.

빠른 시작 (Quick start)

첫 번째 정책을 만들려면 다음 단계를 따르세요:

정책 디렉토리 생성 (존재하지 않는 경우):
```
mkdir -p ~/.gemini/policies
```
새 정책 파일 생성 (예: ~/.gemini/policies/my-rules.toml). .toml로 끝나는 파일 이름을 사용할 수 있으며, 이 디렉토리의 모든 파일이 로드되고 결합됩니다:
```
[[rule]]
toolName = "run_shell_command"
commandPrefix = "git status"
decision = "allow"
priority = 100
```
정책을 트리거하는 명령 실행 (예: Gemini CLI에 git status 요청). 이제 도구가 확인을 요청하지 않고 자동으로 실행됩니다.

핵심 개념 (Core concepts)

정책 엔진은 일련의 규칙에 따라 작동합니다. 각 규칙은 조건과 결과 결정의 조합입니다. 대규모 언어 모델이 도구를 실행하려고 할 때, 정책 엔진은 모든 규칙을 평가하여 도구 호출과 일치하는 가장 높은 우선순위 규칙을 찾습니다.

규칙은 다음과 같은 주요 구성 요소로 이루어져 있습니다:

조건 (Conditions): 규칙이 적용되기 위해 도구 호출이 충족해야 하는 기준입니다. 여기에는 도구 이름, 제공된 인수 또는 현재 승인 모드가 포함될 수 있습니다.
결정 (Decision): 규칙이 일치할 경우 취할 조치입니다 (allow, deny, 또는 ask_user).
우선순위 (Priority): 규칙의 우선 순위를 결정하는 숫자입니다. 숫자가 높을수록 우선합니다.

예를 들어, 다음 규칙은 git 명령을 실행하기 전에 사용자 확인을 요청합니다.

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

조건 (Conditions)

조건은 규칙이 적용되기 위해 도구 호출이 충족해야 하는 기준입니다. 주요 조건은 도구의 이름과 인수입니다.

도구 이름 (Tool Name)

규칙의 toolName은 호출되는 도구의 이름과 일치해야 합니다.

와일드카드: Model-hosting-protocol (MCP) 서버의 경우 와일드카드를 사용할 수 있습니다. my-server__*라는 toolName은 my-server MCP의 모든 도구와 일치합니다.

인수 패턴 (Arguments pattern)

argsPattern이 지정되면 도구의 인수는 안정적인 JSON 문자열로 변환된 다음, 제공된 정규식과 비교됩니다. 인수가 패턴과 일치하지 않으면 규칙이 적용되지 않습니다.

결정 (Decisions)

규칙이 강제할 수 있는 세 가지 결정이 있습니다:

allow: 도구 호출이 사용자 상호 작용 없이 자동으로 실행됩니다.
deny: 도구 호출이 차단되고 실행되지 않습니다.
ask_user: 사용자에게 도구 호출을 승인하거나 거부하라는 메시지가 표시됩니다. (비대화형 모드에서는 deny로 처리됩니다.)

우선순위 시스템 및 계층 (Priority system and tiers)

정책 엔진은 정교한 우선순위 시스템을 사용하여 여러 규칙이 하나의 도구 호출과 일치할 때 충돌을 해결합니다. 핵심 원칙은 간단합니다: 가장 높은 우선순위를 가진 규칙이 승리합니다.

명확한 계층 구조를 제공하기 위해 정책은 세 가지 계층으로 구성됩니다. 각 계층에는 최종 우선순위 계산의 기준이 되는 지정된 번호가 있습니다.

계층 (Tier)	기본값 (Base)	설명 (Description)
Default	1	Gemini CLI와 함께 제공되는 내장 정책입니다.
User	2	사용자가 정의한 사용자 지정 정책입니다.
Admin	3	관리자가 관리하는 정책입니다 (예: 엔터프라이즈 환경).

Within a TOML policy file, you assign a priority value from 0 to 999. The engine transforms this into a final priority using the following formula:

final_priority = tier_base + (toml_priority / 1000)

This system guarantees that:

Admin policies always override User and Default policies.
User policies always override Default policies.
You can still order rules within a single tier with fine-grained control.

For example:

A priority: 50 rule in a Default policy file becomes 1.050.
A priority: 100 rule in a User policy file becomes 2.100.
A priority: 20 rule in an Admin policy file becomes 3.020.

Approval modes

Approval modes allow the policy engine to apply different sets of rules based on the CLI's operational mode. A rule can be associated with one or more modes (e.g., yolo, autoEdit). The rule will only be active if the CLI is running in one of its specified modes. If a rule has no modes specified, it is always active.

규칙 일치 (Rule matching)

도구 호출이 이루어지면 엔진은 가장 높은 우선순위부터 시작하여 모든 활성 규칙과 비교하여 확인합니다. 일치하는 첫 번째 규칙이 결과를 결정합니다.

모든 조건이 충족되면 규칙이 도구 호출과 일치합니다:

도구 이름: 규칙의 toolName은 호출되는 도구의 이름과 일치해야 합니다.
- 와일드카드: Model-hosting-protocol (MCP) 서버의 경우 와일드카드를 사용할 수 있습니다. my-server__*라는 toolName은 my-server MCP의 모든 도구와 일치합니다.
인수 패턴: argsPattern이 지정되면 도구의 인수는 안정적인 JSON 문자열로 변환된 다음, 제공된 정규식과 비교됩니다. 인수가 패턴과 일치하지 않으면 규칙이 적용되지 않습니다.

구성 (Configuration)

정책은 .toml 파일에 정의됩니다. CLI는 기본(Default), 사용자(User) 및 (구성된 경우) 관리자(Admin) 디렉토리에서 이러한 파일을 로드합니다.

정책 위치 (Policy locations)

계층 (Tier)	유형 (Type)	위치 (Location)
User	사용자 지정	`~/.gemini/policies/*.toml`
Admin	시스템	아래 참조 (OS별)

시스템 전체 정책 (관리자) (System-wide policies (Admin))

관리자는 모든 사용자 및 기본 설정을 재정의하는 시스템 전체 정책(Tier 3)을 시행할 수 있습니다. 이러한 정책은 특정 보안 디렉토리에 위치해야 합니다:

OS	정책 디렉토리 경로 (Policy Directory Path)
Linux	`/etc/gemini-cli/policies`
macOS	`/Library/Application Support/GeminiCli/policies`
Windows	`C:\ProgramData\gemini-cli\policies`

보안 요구 사항 (Security Requirements):

권한 상승을 방지하기 위해 CLI는 관리자 디렉토리에 대해 엄격한 보안 검사를 시행합니다. 검사가 실패하면 시스템 정책은 무시됩니다.

Linux / macOS: root (UID 0) 소유여야 하며 그룹이나 타인에 의해 쓰기 가능해서는 안 됩니다 (예: chmod 755).
Windows: C:\ProgramData에 있어야 합니다. 표준 사용자(Users, Everyone)는 Write, Modify 또는 Full Control 권한을 가져서는 안 됩니다. 팁: 보안 경고가 표시되면 폴더 속성을 사용하여 비관리자 그룹의 쓰기 권한을 제거하세요. 고급 보안 설정에서 "상속 비활성화"가 필요할 수 있습니다.

TOML 규칙 스키마 (TOML rule schema)

다음은 TOML 정책 규칙에서 사용할 수 있는 필드에 대한 내역입니다:

[[rule]]
# 도구의 고유 이름 또는 이름 배열입니다.
toolName = "run_shell_command"
 
# (선택 사항) MCP 서버의 이름입니다. toolName과 결합하여
# "mcpName__toolName"과 같은 복합 이름을 형성할 수 있습니다.
mcpName = "my-custom-server"
 
# (선택 사항) 도구의 인수와 일치시킬 정규식입니다.
argsPattern = '"command":"(git|npm)'
 
# (선택 사항) 쉘 명령이 시작되어야 하는 문자열 또는 문자열 배열입니다.
# 이는 `toolName = "run_shell_command"`와 `argsPattern`을 위한 문법적 설탕(syntactic sugar)입니다.
commandPrefix = "git "
 
# (선택 사항) 전체 쉘 명령과 일치시킬 정규식입니다.
# 이것 또한 `toolName = "run_shell_command"`를 위한 문법적 설탕입니다.
# 참고: 이 패턴은 인수의 JSON 표현(예: `{"command":"<your_command>"}`)에 대해 테스트되므로 `^` 또는 `$`와 같은 앵커는 명령 텍스트뿐만 아니라 전체 JSON 문자열에 적용됩니다.
# 동일한 규칙에서 commandPrefix와 commandRegex를 모두 사용할 수 없습니다.
commandRegex = "^git (commit|push)"
 
# 취할 결정입니다. "allow", "deny" 또는 "ask_user"여야 합니다.
decision = "ask_user"
 
# 0에서 999까지의 규칙 우선순위입니다.
priority = 10
 
# (선택 사항) 이 규칙에 의해 도구 호출이 거부될 때 표시할 사용자 지정 메시지입니다.
# 이 메시지는 모델과 사용자에게 반환되며 *왜* 거부되었는지 설명하는 데 유용합니다.
deny_message = "Deletion is permanent"
 
# (선택 사항) 이 규칙이 활성화되는 승인 모드 배열입니다.
modes = ["autoEdit"]

배열(목록) 사용 (Using arrays (lists))

동일한 규칙을 여러 도구 또는 명령 접두사에 적용하려면 toolName 및 commandPrefix 필드에 문자열 배열을 제공할 수 있습니다.

예제:

이 단일 규칙은 write_file 및 replace 도구 모두에 적용됩니다.

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

`run_shell_command`를 위한 특별 구문 (Special syntax for `run_shell_command`)

run_shell_command에 대한 정책 작성을 단순화하기 위해 더 복잡한 argsPattern 대신 commandPrefix 또는 commandRegex를 사용할 수 있습니다.

commandPrefix: command 인수가 주어진 문자열로 시작하는 경우 일치합니다.
commandRegex: command 인수가 주어진 정규식과 일치하는 경우 일치합니다.

예제:

이 규칙은 git 명령을 실행하기 전에 사용자 확인을 요청합니다.

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

MCP 도구를 위한 특별 구문 (Special syntax for MCP tools)

mcpName 필드 또는 와일드카드 패턴을 사용하여 Model-hosting-protocol (MCP) 서버의 도구를 대상으로 하는 규칙을 만들 수 있습니다.

1. mcpName 사용

특정 서버의 특정 도구를 대상으로 하려면 mcpName과 toolName을 결합하세요.

# `my-jira-server` MCP의 `search` 도구 허용
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

2. 와일드카드 사용

특정 MCP 서버의 모든 도구에 적용되는 규칙을 만들려면 mcpName만 지정하세요.

# `untrusted-server` MCP의 모든 도구 거부
[[rule]]
mcpName = "untrusted-server"
decision = "deny"
priority = 500
deny_message = "This server is not trusted by the admin."

기본 정책 (Default policies)

Gemini CLI는 안전한 기본 경험을 제공하기 위해 일련의 기본 정책과 함께 제공됩니다.

읽기 전용 도구 (read_file, glob 등)는 일반적으로 허용됩니다.
에이전트 위임은 원격 에이전트가 확인을 요청할 수 있도록 **ask_user**가 기본값이지만, 로컬 하위 에이전트 작업은 조용히 실행되고 개별적으로 확인됩니다.
쓰기 도구 (write_file, run_shell_command 등)는 **ask_user**가 기본값입니다.
yolo 모드에서는 우선순위가 높은 규칙이 모든 도구를 허용합니다.
autoEdit 모드에서는 규칙이 확인 없이 특정 쓰기 작업이 발생하도록 허용합니다.

메모리 가져오기 프로세서 도구 API