규칙

규칙은 Codex가 샌드박스 경계를 넘어 명령을 실행해야 할 때, 명령의 앞부분인 접두사를 기준으로 허용, 확인 요청, 차단 여부를 정하는 정책입니다. 예를 들어 gh pr view처럼 반복해서 쓰는 명령은 매번 묻지 않게 만들 수 있고, 위험한 명령은 항상 확인을 요구하거나 아예 막을 수 있습니다.

샌드박스와 승인 정책이 Codex의 전체 작업 범위를 정한다면, 규칙은 그 범위 위에 얹는 세밀한 예외 제어입니다. 워크플로에 필요한 명령만 좁게 지정할 수 있으므로, Codex에 전체 접근 권한을 주는 것보다 예측 가능하고 안전합니다.

규칙은 아직 실험적 기능이므로 향후 동작이나 형식이 바뀔 수 있습니다.

규칙 파일 만들기

활성 구성 계층의 rules/ 폴더 아래에 .rules 파일을 만듭니다. 예: ~/.codex/rules/default.rules.

규칙을 추가합니다. 다음 예시는 gh pr view를 샌드박스 밖에서 실행하도록 허용하기 전에 확인을 요청합니다.

# `gh pr view`로 시작하는 명령을 샌드박스 밖에서 실행하기 전에 확인합니다.
prefix_rule(
    # 이 규칙과 일치시킬 명령 접두사입니다.
    pattern = ["gh", "pr", "view"],

    # Codex가 일치하는 명령을 실행하려 할 때 적용할 동작입니다.
    decision = "prompt",

    # 이 규칙이 필요한 이유를 설명하는 선택 항목입니다.
    justification = "승인 후 PR 조회를 허용합니다.",

    # `match`와 `not_match`는 선택 항목이며, 규칙을 간단히 검증하는 예시입니다.
    # 각각 이 규칙과 일치해야 하는 명령, 일치하면 안 되는 명령을 적습니다.
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
        "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
        # `pattern`은 정확한 접두사여야 하므로 일치하지 않습니다.
        "gh pr --repo openai/codex view 7888",
    ],
)

Codex를 다시 시작합니다.

Codex는 시작할 때 활성화된 모든 구성 계층의 rules/ 폴더를 읽습니다.

터미널 UI(TUI)에서 명령을 허용 목록에 추가하면, Codex는 이후 실행에서 같은 확인을 건너뛸 수 있도록 사용자 계층의 ~/.codex/rules/default.rules에 그 내용을 기록합니다.

Smart approvals가 활성화되어 있으면, Codex가 권한 상승을 요청하는 과정에서 prefix_rule을 제안할 수 있습니다. 이는 기본 동작입니다. 제안을 수락하기 전에 포함된 명령 접두사가 지나치게 넓지 않은지 반드시 확인하십시오.

규칙 필드 이해

prefix_rule()은 다음 필드를 지원합니다.

pattern 필수: 일치시킬 명령 접두사를 담는 비어 있지 않은 목록입니다. 각 요소는 "pr" 같은 문자열이거나, 해당 인수 위치에서 허용할 대안을 묶은 ["view", "list"] 같은 목록입니다.
decision 기본값 "allow": 규칙이 일치했을 때 적용할 동작입니다. 둘 이상의 규칙이 일치하면 Codex는 가장 제한적인 결정을 따릅니다. 우선순위는 forbidden > prompt > allow입니다.
allow: 확인 없이 샌드박스 밖에서 명령을 실행합니다.
prompt: 일치하는 명령을 실행할 때마다 확인을 요청합니다.
forbidden: 요청을 확인 없이 차단합니다.
justification 선택 사항: 규칙이 필요한 이유를 사람이 읽을 수 있게 적는 값입니다. Codex는 승인 프롬프트나 거부 메시지에 이 값을 표시할 수 있습니다. forbidden을 사용할 때는 적절하다면 권장 대안을 함께 적으십시오. 예: "`grep` 대신 `rg`를 사용하십시오.".
match와 not_match 기본값 []: Codex가 규칙을 로드할 때 함께 검증하는 예시입니다. 규칙이 실제로 적용되기 전에 실수를 찾는 데 도움이 됩니다.

Codex는 명령 실행을 검토할 때 명령의 인수 목록을 pattern과 비교합니다. 내부적으로는 명령을 execvp(3)에 전달되는 인수 목록과 같은 형태로 다룹니다.

셸 래퍼와 복합 명령

일부 도구는 여러 셸 명령을 하나의 호출로 감쌉니다. 예:

["bash", "-lc", "git add . && rm -rf /"]

이런 형태는 하나의 문자열 안에 여러 동작을 숨길 수 있습니다. 그래서 Codex는 bash -lc, bash -c와 이에 대응하는 zsh/sh 호출을 별도로 처리합니다.

Codex가 스크립트를 안전하게 분할할 수 있는 경우

셸 스크립트가 다음만으로 구성된 선형 명령 체인이라면:

일반 단어만 사용합니다. 변수 확장, VAR=..., $FOO, * 같은 표현은 사용하지 않습니다.
안전한 연산자(&&, ||, ;, |)로 연결됩니다.

Codex는 이를 tree-sitter로 파싱한 뒤, 규칙을 적용하기 전에 개별 명령으로 나눕니다.

위 스크립트는 두 개의 별도 명령으로 취급됩니다.

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

그런 다음 각 명령을 규칙에 대조하고, 가장 제한적인 결과를 전체 호출에 적용합니다.

따라서 pattern=["git", "add"]를 허용해도 Codex는 git add . && rm -rf /를 자동으로 허용하지 않습니다. rm -rf / 부분이 별도로 평가되어 전체 호출의 자동 허용을 막기 때문입니다.

이 방식은 위험한 명령이 안전한 명령 뒤에 함께 숨어 들어가는 일을 막는 데 도움이 됩니다.

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

스크립트가 다음과 같은 고급 셸 기능을 사용하면:

리디렉션(>, >>, <)
명령 치환($(...), 백틱을 사용한 치환)
환경 변수(FOO=bar)
와일드카드 패턴(*, ?)
제어 흐름(if, for, 할당을 포함한 && 등)

Codex는 해당 스크립트를 해석하거나 개별 명령으로 나누려고 하지 않습니다.

대신 전체 호출을 다음과 같은 하나의 명령으로 봅니다.

["bash", "-lc", "{full script}"]

그리고 규칙은 이 하나의 호출에 적용됩니다.

이렇게 하면 안전하게 나눌 수 있는 경우에는 명령별로 세밀하게 평가하고, 확실하지 않은 경우에는 더 보수적으로 처리할 수 있습니다.

규칙 파일 테스트

codex execpolicy check를 사용하면 특정 명령에 어떤 규칙이 적용되는지 테스트할 수 있습니다.

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

이 명령은 가장 제한적인 결정과 그 결정으로 이어진 규칙을 JSON으로 출력합니다. 해당 규칙의 justification 값도 함께 표시됩니다. 여러 규칙 파일을 함께 테스트하려면 --rules 플래그를 여러 번 사용하고, 출력을 읽기 좋게 보려면 --pretty를 추가합니다.

규칙 언어 이해

.rules 파일은 Starlark 형식을 사용합니다. 자세한 내용은 언어 사양을 참고하십시오. 문법은 Python과 비슷하지만, 안전하게 실행되도록 설계되어 있습니다. 예를 들어 규칙 엔진은 파일 시스템을 변경하는 부작용 없이 이 파일을 실행할 수 있습니다.