Codex Rules

Codex를 쓰다 보면 “이 명령어는 바로 실행해도 될까?”, “이건 꼭 승인받고 실행해야 하지 않나?” 같은 고민이 생긴다.
Codex는 이를 해결하기 위해 Rules(규칙) 라는 실험적 기능을 제공한다.

Rules를 사용하면 sandbox 밖에서 실행되는 명령어를 세밀하게 제어할 수 있다.

---

Rules란 무엇인가?

Codex Rules는 Codex가 sandbox 외부에서 실행하려는 명령어에 대해

• 허용(allow)
• 실행 전 승인 요청(prompt)
• 완전 차단(forbidden)

중 어떤 동작을 할지 명령어 패턴 단위로 정의하는 기능이다.

⚠️ Rules는 현재 experimental 상태이며, 향후 변경될 수 있다.

---

Rules 파일 만들기

Rules는 .rules 파일로 관리한다.

1️⃣ Rules 디렉토리 생성

mkdir -p ~/.codex/rules

2️⃣ rules 파일 생성

예시:

~/.codex/rules/default.rules

Codex는 시작 시 모든 Team Config 위치의 rules/ 디렉토리를 스캔한다.

---

prefix_rule 예제: gh pr view 실행 전 승인 받기

다음은 gh pr view 명령을 sandbox 밖에서 실행할 때 항상 승인(prompt)을 요구하는 규칙이다.

# Prompt before running commands with the prefix `gh pr view` outside the sandbox.
prefix_rule(
    # The prefix to match.
    pattern = ["gh", "pr", "view"],

    # The action to take when Codex requests to run a matching command.
    decision = "prompt",

    # Optional rationale for why this rule exists.
    justification = "Viewing PRs is allowed with approval",

    # Inline unit tests
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
        "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
        # Does not match because the pattern must be an exact prefix
        "gh pr --repo openai/codex view 7888",
    ],
)

📌 포인트

• pattern은 정확한 prefix 매칭
• gh pr view 이후의 인자는 자유롭게 와도 매칭됨
• 순서가 바뀌면 매칭되지 않음

---

Codex 재시작

Rules 파일을 추가하거나 수정한 후에는 Codex를 재시작해야 한다.

codex restart

---

Rules가 적용되는 방식

Codex는 명령어를 argv 리스트 형태로 해석한다.
즉, 내부적으로는 다음과 같이 비교한다.

["gh", "pr", "view", "7888"]

이 리스트가 pattern의 prefix와 일치하면 rule이 적용된다.

---

Rule 필드 정리

prefix_rule()이 지원하는 필드는 다음과 같다.

🔹 pattern (필수)

• 비어 있지 않은 리스트
• 각 요소는:
  • 문자열 ("pr")
  • 또는 선택지 (["view", "list"])

pattern = ["gh", "pr", ["view", "list"]]

---

🔹 decision (기본값: "allow")

값의미

allow	묻지 않고 실행
prompt	실행 전 승인 요청
forbidden	무조건 차단

여러 rule이 동시에 매칭되면 가장 restrictive한 결정이 적용된다
forbidden > prompt > allow

---

🔹 justification (선택)

• 사람이 읽을 수 있는 설명
• 승인 팝업이나 차단 메시지에 표시됨
• forbidden일 경우 대안 명령을 포함하는 것이 권장

justification = "Use rg instead of grep"

---

🔹 match / not_match (선택)

• rule 로딩 시 검증되는 inline 테스트
• 실수로 잘못된 rule이 적용되는 것을 방지해줌

---

Shell wrapper 명령어는 어떻게 처리될까?

다음과 같은 명령을 생각해보자.

bash -lc "git add . && rm -rf /"

이건 굉장히 위험할 수 있다. Codex는 이런 경우를 특별 취급한다.

---

Codex가 스크립트를 분해하는 경우

다음 조건을 만족하면 Codex는 스크립트를 개별 명령으로 분해한다.

• 변수 없음 ($FOO, VAR=... ❌)
• 와일드카드 없음 (*, ? ❌)
• 리다이렉션 없음 (>, >> ❌)
• 단순 연산자만 사용 (&&, ||, ;, |)

git add . && rm -rf /

⬇️ 내부적으로 이렇게 분해됨

["git", "add", "."]
["rm", "-rf", "/"]

각 명령에 rule을 적용한 뒤 가장 restrictive한 결과가 전체 결과가 된다.

➡️ 그래서 git add를 허용해도
rm -rf / 때문에 전체 명령은 자동 허용되지 않는다

---

Codex가 스크립트를 분해하지 않는 경우

아래와 같은 기능이 포함되면 분해하지 않는다.

• 리다이렉션
• 서브쉘
• 환경 변수
• 와일드카드
• 제어 흐름 (if, for 등)

이 경우 전체를 하나의 명령으로 취급한다.

["bash", "-lc", "<full script>"]

➡️ 보수적으로 처리해서 보안을 우선한다는 설계다.

---

Rule 테스트하기

Rules가 실제로 어떻게 적용되는지 확인하려면 다음 명령을 사용한다.

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

출력:

• 최종 decision
• 매칭된 rule
• justification 포함한 상세 정보

여러 rules 파일을 동시에 검사할 수도 있다.

---

Rules 언어: Starlark

.rules 파일은 Starlark 문법을 사용한다.

• Python과 유사
• 하지만 부작용(side effect)이 없는 안전한 언어
• 파일 시스템 접근, 네트워크 호출 불가

👉 Codex가 신뢰할 수 있는 정책 엔진으로 rules를 실행할 수 있는 이유다.

---

마무리

Codex Rules는 단순한 allow/deny 설정이 아니라,

• 명령어 prefix 기반 제어
• 복합 shell 명령에 대한 안전한 분해
• 테스트 가능한 정책 정의

까지 포함한 꽤 정교한 실행 제어 메커니즘이다.

특히 팀 단위로 Codex를 쓰거나,
실수 한 번이 치명적인 환경에서는 거의 필수 기능에 가깝다.

개인적으로는 rm, kubectl delete, terraform apply 같은 것들은
무조건 prompt 또는 forbidden으로 두는 걸 추천 👀

---

원하면:

• “운영 환경용 rules 베스트 프랙티스”
• 위험한 명령어 추천 rules 세트
• Team Config / requirements.toml 예제

이런 것도 이어서 정리해줄게.