Codex Rules

• Codex에서 샌드박스 외부 명령 실행을 제어하는 선언적 규칙 시스템 (실험적 기능)
• .rules 파일에 prefix_rule()을 정의하면, 명령어 패턴별로 allow / prompt / forbidden 결정
• Starlark(Python 유사 언어)로 작성되며, 파일시스템 접근 없이 안전하게 평가
• 사용자가 터미널 UI에서 명령을 승인하면, 해당 패턴이 자동으로 규칙에 기록되어 이후 프롬프트 생략

해당 개념이 필요한 이유

• 보안 경계 설정: 어떤 명령이 승인 없이 실행되고, 어떤 명령이 차단되는지 명시적으로 선언
• 팀 표준 강제: 관리자가 requirements.toml로 제한적 규칙을 배포하여 조직 전체에 적용
• 반복 승인 제거: 한 번 승인한 명령 패턴을 규칙으로 저장하여 이후 자동 허용
• 복잡한 셸 스크립트 안전 처리: &&, | 등으로 연결된 명령을 개별 분리하여 각각 규칙 평가

AS-IS

# 매번 동일한 명령에 승인 프롬프트 반복
Codex: "gh pr view 7888 실행해도 될까요?" → 승인
Codex: "gh pr view 7889 실행해도 될까요?" → 또 승인
Codex: "gh pr list 실행해도 될까요?" → 또 승인

TO-BE

# ~/.codex/rules/default.rules (한 번만 정의)
prefix_rule(
    pattern=["gh", "pr", ["view", "list"]],
    decision="allow",
    justification="gh pr 조회 명령은 읽기 전용이므로 항상 허용",
)

# 이후에는 프롬프트 없이 바로 실행
Codex: gh pr view 7888 → ✅ 자동 실행
Codex: gh pr list → ✅ 자동 실행
Codex: gh pr merge → ⚠️ 매칭 안 됨 → 승인 요청

규칙 파일 위치

.rules 파일은 ~/.codex/rules/ 디렉토리에 저장하며, Codex가 시작 시 Team Config 계층의 모든 디렉토리를 스캔한다.

위치	경로	용도
User	~/.codex/rules/default.rules	개인 규칙
Admin	requirements.toml (managed config)	조직 전체 강제 규칙

prefix_rule() 작성법

필수 파라미터

파라미터	설명	예시
pattern	매칭할 명령어 접두사 (비어있지 않은 리스트)	["gh", "pr", "view"]

pattern 요소는 두 가지 형태:

• 리터럴 문자열: "pr" → 정확히 pr만 매칭
• 대안 유니언: ["view", "list"] → view 또는 list 매칭

# "gh pr view" 또는 "gh pr list"에 매칭
prefix_rule(
    pattern=["gh", "pr", ["view", "list"]],
    decision="allow",
)

선택 파라미터

파라미터	기본값	설명
decision	"allow"	"allow": 즉시 실행, "prompt": 매번 승인 요청, "forbidden": 차단
justification	-	사람이 읽을 수 있는 설명. 승인 프롬프트나 거부 메시지에 표시
match	-	이 규칙이 매칭해야 하는 예시 배열 (로딩 시 검증용)
not_match	-	이 규칙이 매칭하면 안 되는 예시 배열 (로딩 시 검증용)

decision 우선순위

여러 규칙이 동시에 매칭되면, 가장 제한적인 결정이 우선한다:

forbidden > prompt > allow

셸 명령 처리

안전한 체인 명령 분리

bash/zsh의 -c 또는 -lc 플래그로 실행되는 셸 명령이 안전한 연산자(&&, ||, ;, |)로 연결되고 단순 단어만 포함하면, Codex가 개별 명령으로 분리하여 각각 규칙을 평가한다:

# 이 명령은 "git status"와 "git diff"로 분리되어 각각 규칙 평가
bash -c "git status && git diff"

복잡한 스크립트 처리

리다이렉션, 치환, 환경변수, 와일드카드, 제어 흐름 등 고급 셸 기능을 사용하는 스크립트는 단일 호출로 취급한다:

# 전체 스크립트가 하나의 패턴으로 평가됨
["bash", "-lc", "<전체 스크립트>"]

이 보수적 접근은 복잡한 스크립트 안에 위험한 명령이 숨겨지는 것을 방지한다.

규칙 테스트

CLI로 규칙의 매칭 동작을 사전 검증할 수 있다:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

여러 규칙 파일을 조합하여 테스트 가능.

사용자 승인 자동 기록

터미널 UI에서 사용자가 명령을 승인하면, Codex가 prefix_rule 항목을 자동으로 ~/.codex/rules/default.rules에 기록한다. 이후 동일한 패턴의 명령은 프롬프트 없이 실행된다.

sequenceDiagram
    autonumber
    actor User
    participant Codex
    participant Rules as default.rules

    Codex->>User: "gh pr view 실행해도 될까요?"
    User->>Codex: 승인
    Codex->>Rules: prefix_rule(pattern=["gh","pr","view"],<br/>decision="allow") 자동 기록
    Note over Codex: 다음 번 "gh pr view" → 프롬프트 없이 실행

Smart Approvals (관리자 기능)

관리자가 managed config의 requirements.toml로 제한적 규칙을 강제할 수 있다. Smart approvals가 활성화되면(기본값), 사용자가 권한 상승을 요청할 때 Codex가 prefix_rule 항목을 제안하여 관리자 리뷰를 거친다.

규칙 언어: Starlark

.rules 파일은 Starlark로 작성한다. Starlark는 Python과 유사한 문법이지만, 부작용(side effect)이 없도록 설계되어 파일시스템 접근이 불가능하다. 이 덕분에 신뢰할 수 없는 환경에서도 안전하게 규칙을 평가할 수 있다.

Claude Code Permissions와 비교

항목	Codex Rules	Claude Code Permissions
정의 형식	.rules 파일 (Starlark)	settings.json (JSON)
규칙 단위	명령어 접두사 패턴 (prefix_rule)	도구 이름 + glob 패턴
결정 옵션	allow / prompt / forbidden	allow / deny
충돌 해결	가장 제한적인 결정 우선	deny가 allow보다 우선
자동 기록	승인 시 규칙 자동 생성	승인 시 allowlist에 자동 추가
셸 명령 분리	체인 명령을 개별 평가	해당 없음 (도구 단위 제어)
테스트 도구	codex execpolicy check CLI	해당 없음
규칙 언어	Starlark (Python-like)	JSON
관리자 강제	requirements.toml	Enterprise managed settings

참고 문서

• Codex Rules 공식 문서
• Codex Subagents - 하위 에이전트 (샌드박스 정책 상속)
• Codex Skills - 재사용 가능한 워크플로우 패키지