33단계AGENTS.md와 권한: 승인 방식과 샌드박스

걸리는 시간 · 읽기 약 20분 · 따라 하기 약 45분 · 난이도 ★★★ 심화

이 단계를 마치면

• AGENTS.md를 알맞은 위치에 두고, 여러 단계의 파일이 어떻게 합쳐지는지 설명할 수 있습니다.
• 샌드박스 모드와 승인 정책의 이름과 뜻을 구분하고, 작업에 맞는 조합을 고를 수 있습니다.
• Codex가 한 일을 변경 내역으로 확인하고 Git 체크포인트로 되돌릴 수 있습니다.

23단계에서 여러분은 CLAUDE.md에 규칙을 적고, 28단계에서 무엇을 묻지 않고 허락할지 정리했습니다. Codex에도 같은 두 장치가 있습니다. 규칙은 AGENTS.md에 적고, 권한은 샌드박스와 승인 정책으로 정합니다. 이름과 설정 방식이 달라서 처음에는 헷갈리지만, 뜻을 한 번 잡아 두면 Claude Code에서 쓰던 감각이 그대로 통합니다.

AGENTS.md: 어디에 두고 어떻게 합쳐지나

Codex는 작업을 시작하기 전에 AGENTS.md를 읽습니다. CLAUDE.md처럼 마크다운으로 쓴 지침 파일입니다. 두는 곳은 세 층입니다.

읽는 순서는 이렇습니다. 먼저 전역 파일을 읽고, 이어서 저장소 맨 위 폴더부터 지금 Codex를 켠 폴더까지 한 층씩 내려가며 폴더마다 파일 하나씩을 읽습니다. 읽은 내용은 위쪽부터 차례로 이어 붙입니다. 그래서 지금 폴더에 가까운 파일이 뒤에 붙고, 앞의 내용과 부딪히면 뒤의 것이 앞섭니다. 폴더마다 AGENTS.override.md가 있으면 그 폴더에서는 AGENTS.md 대신 그것을 읽습니다. 잠깐 규칙을 바꿔 시험할 때 원래 파일을 건드리지 않고 쓰는 방법입니다. 빈 파일은 건너뛰고, 합친 크기가 기본 32KiB에 닿으면 그 뒤로는 더 읽지 않습니다. 규칙이 길어지면 뒤쪽 규칙이 통째로 빠질 수 있다는 뜻이니 짧게 유지하세요.

처음부터 직접 쓸 필요는 없습니다. Codex 입력창에 /init을 치면 지금 폴더를 훑어보고 AGENTS.md 초안을 만들어 줍니다. 초안은 대개 기술 설명 위주이므로, 23단계에서 했던 것처럼 우리 팀의 말로 규칙과 금지 사항을 보탭니다. 흐린 말 대신 확인할 수 있는 문장으로 쓰는 원칙도 같습니다. 공식 문서가 예로 드는 규칙도 모두 확인할 수 있는 문장입니다. "파일을 고친 뒤에는 테스트 명령을 실행한다", "새 도구를 추가하기 전에 확인을 받는다" 같은 식입니다. GitHub에서 @codex review를 쓸 때 적용할 검토 규칙은 ## Code Review Rules라는 제목 아래에 적습니다. 비밀번호나 인증키는 절대 적지 않습니다. AGENTS.md도 저장소에 함께 올라가 다른 사람이 읽는 파일입니다.

# 비품 신청 페이지

## 이 폴더는
경영지원팀이 쓰는 사내 비품 신청 페이지다. 직원들이 휴대폰으로 연다.

## 규칙
- 화면 문구는 모두 우리말로 쓴다.
- 신청자는 부서명만 보여 주고 이름은 보여 주지 않는다.
- 파일은 index.html 하나로 유지한다.

## 하지 말 것
- 새 도구나 패키지를 설치하기 전에 반드시 묻는다.
- 파일을 지우기 전에 반드시 묻는다.
- 인증키나 비밀번호를 파일에 적지 않는다.

## 끝났다고 말하기 전에
- 브라우저로 열어 신청 목록이 보이는지 확인하고, 확인한 방법을 적는다.

CLAUDE.md와 같이 두기. 한 폴더를 Claude Code와 Codex가 함께 쓰는 팀이 늘고 있습니다. 여기서 알아 둘 사실이 있습니다. Codex는 CLAUDE.md를 저절로 읽지 않습니다. 기본으로 찾는 이름은 AGENTS.override.md와 AGENTS.md뿐입니다. 방법은 세 가지입니다.

어느 방법이든 끝은 같습니다. Codex를 켜고 "지금 따르고 있는 규칙을 요약해 줘"라고 물어, 적어 둔 규칙이 돌아오는지 봅니다.

두 겹의 울타리: 샌드박스와 승인 정책

Codex의 권한은 두 층으로 되어 있습니다. 샌드박스는 기술적으로 무엇을 할 수 있는지를 정합니다. 승인 정책은 언제 멈추고 나에게 물을지를 정합니다. 28단계에서 Claude Code의 허락 규칙을 정리했던 일을 Codex에서는 이 두 층으로 나눠서 합니다.

샌드박스 모드(설정 이름 sandbox_mode, 실행할 때는 --sandbox)는 세 가지입니다.

승인 정책(설정 이름 approval_policy, 실행할 때는 --ask-for-approval 또는 -a)은 이렇습니다.

예전 자료에는 untrusted와 on-failure라는 값도 나옵니다. untrusted는 지원이 끝나 설정에 남아 있으면 실행이 안 될 수 있고, on-failure는 곧 없어질 값입니다. 인터넷에서 찾은 설정 예시에 이 두 값이 있으면 쓰지 마세요.

대표 조합은 두 가지만 기억하면 됩니다.

대화 중에 바꾸려면 CLI에서 /permissions를 입력하고 Auto와 Read Only 가운데 고릅니다. 지금 상태는 /status로 확인합니다. 늘 같은 조합을 쓰고 싶으면 설정 파일 config.toml에 적어 둡니다. 내 홈 폴더의 .codex/config.toml은 모든 폴더에, 작업 폴더 안의 .codex/config.toml은 그 폴더에만 적용됩니다. 작업 폴더의 설정은 내가 신뢰한다고 표시한 폴더에서만 읽힙니다. CLI, IDE 확장, 데스크톱 앱이 같은 설정을 함께 씁니다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

모든 제한을 없애는 --dangerously-bypass-approvals-and-sandbox(별칭 --yolo)도 있습니다. 공식 문서도 권하지 않습니다. 이름에 "위험하다"가 붙은 옵션은 쓰지 않는다고 정해 두세요. 회사 차원에서는 관리자가 requirements.toml로 이런 설정을 아예 금지할 수 있습니다.

workspace-write에서도 손대지 못하는 곳이 있습니다. 작업 폴더 안의 .git, .agents, .codex 폴더는 읽기 전용으로 보호됩니다. Git 기록과 Codex 설정을 Codex가 스스로 고치지 못하게 막아 두는 장치입니다.

앱의 권한 모드, 자동 검토, 네트워크

데스크톱 앱과 IDE 확장에서는 같은 내용을 세 가지 권한 모드로 고릅니다.

뒤의 두 모드는 설정의 권한 항목(General 아래 Permissions)에서 켜야 메뉴에 나타납니다. 화면 이름과 위치는 바뀔 수 있으니 앱에서 확인하세요. Approve for me(자동 검토)를 켜도 샌드박스 범위는 넓어지지 않습니다. 묻는 상대가 사람에서 검토 에이전트로 바뀔 뿐입니다. 검토 에이전트가 거절한 동작을 한 번만 다시 허용하려면 CLI에서 /approve를 씁니다. 처음 몇 주는 Ask for approval로 두고, 어떤 요청이 오는지 읽어 보는 편이 배우기에 좋습니다.

네트워크 기본값. 내 컴퓨터에서 workspace-write로 일할 때 인터넷은 꺼져 있습니다. Codex가 무언가를 내려받거나 설치하려 하면 승인 요청이 옵니다. 늘 켜 두려면 설정의 [sandbox_workspace_write] 아래 network_access = true를 적지만, 회사 PC에서는 꺼 둔 채 요청이 올 때마다 읽고 판단하는 편이 안전합니다. 웹 검색은 기본값이 OpenAI가 미리 색인해 둔 결과를 쓰는 cached이고, 실시간 검색은 따로 켜야 합니다. 클라우드 작업도 에이전트가 일하는 동안에는 인터넷이 기본으로 막혀 있습니다.

되돌리기는 Git 체크포인트로

Claude Code에는 대화와 파일을 앞 시점으로 돌리는 기능이 있었습니다. Codex CLI에는 그런 되돌리기 명령이 없습니다. 명령 목록에 /undo도 없습니다. 공식 문서가 권하는 방법은 Git 체크포인트입니다. 맡기기 전에 커밋하고, 끝나면 확인한 뒤 다시 커밋합니다. git status가 깨끗한 상태에서 맡기라는 것도 같은 이유입니다. 26단계에서 익힌 커밋과 되돌리기가 여기서 안전장치 노릇을 합니다.

Codex 안에서 쓰는 확인 도구는 두 가지입니다. /diff는 지금까지 바뀐 내용을 보여 줍니다. Git이 아직 추적하지 않는 새 파일도 포함합니다. /review는 작업 중인 변경을 검토해 줍니다. 데스크톱 앱의 리뷰 화면에서는 바뀐 내용을 전체, 파일, 덩어리 단위로 골라 되돌릴(Revert) 수 있습니다. 마음에 들지 않는 변경은 이 화면이나 26단계의 Git 명령으로 되돌리고, 확인이 끝난 변경만 커밋합니다.

현장 장면

오세린 차장은 Claude Code로 만들었던 비품 신청 페이지 폴더를 Codex로 열었습니다. 31단계에서 적어 둔 궁금증부터 풀었습니다. "지금 따르고 있는 규칙을 요약해 줘." Codex는 폴더 구조만 설명할 뿐, CLAUDE.md에 적은 "신청자는 부서명만 보여 준다"는 규칙은 말하지 않았습니다. 오 차장은 /init으로 AGENTS.md 초안을 받고, CLAUDE.md의 규칙과 하지 말 것을 그대로 옮겨 적었습니다. 두 파일 맨 위에는 "규칙을 고치면 CLAUDE.md와 AGENTS.md를 함께 고친다"는 문장을 넣었습니다. 같은 질문을 다시 하자 이번에는 부서명 규칙이 돌아왔습니다.

다음으로 신청 목록에 날짜 정렬 기능을 붙여 달라고 했습니다. 맡기기 전에 git status가 깨끗한지 보고 커밋부터 했습니다. 작업 도중 승인 요청이 하나 왔습니다. 날짜를 다루는 도구를 인터넷에서 받아 설치하겠다는 내용이었습니다. AGENTS.md에 "새 도구를 설치하기 전에 반드시 묻는다"고 적어 둔 대로였습니다. 오 차장은 거절하고, 설치 없이 할 수 있는 방법으로 해 달라고 했습니다. Codex는 페이지 안에서 직접 정렬하는 방식으로 바꿔 끝냈습니다.

결과를 브라우저로 열어 보니 정렬은 됐지만 휴대폰 폭에서 표가 옆으로 밀려 있었습니다. /diff로 보니 정렬 말고도 표 스타일이 함께 바뀌어 있었습니다. 오 차장은 데스크톱 앱의 리뷰 화면에서 스타일이 바뀐 덩어리만 되돌리고 정렬 부분은 남겼습니다. 다시 열어 보니 표도 제자리였습니다. 그제야 커밋했습니다.

그날 저녁 영업본부의 동료 하나가 "매번 묻는 거 귀찮으니 Full access로 켜 두면 편하다"고 조언했습니다. 오 차장은 고맙다고만 하고 설정을 그대로 두었습니다. 오늘 거절한 설치 요청 하나가 그 이유였습니다.

따라 하기

1. 작업 폴더에서 git status를 확인하고, 깨끗하지 않으면 커밋부터 합니다. 성공 기준: git status에 바뀐 파일이 없습니다.
2. Codex를 켜고 /init으로 AGENTS.md 초안을 받은 뒤, "이 폴더는", "규칙", "하지 말 것", "끝났다고 말하기 전에"를 채웁니다. 성공 기준: 모든 규칙이 확인할 수 있는 문장이고, 비밀 값이 없습니다.
3. CLAUDE.md가 있는 폴더라면 위 세 방법 가운데 하나를 골라 적용합니다. 성공 기준: "지금 따르고 있는 규칙을 요약해 줘"에 두 파일의 핵심 규칙이 모두 돌아옵니다.
4. /status로 지금 샌드박스와 승인 정책을 확인하고, /permissions에서 Read Only와 Auto를 한 번씩 바꿔 봅니다. 성공 기준: 바꿀 때마다 /status의 표시가 달라집니다.
5. Auto 상태에서 작은 수정 하나를 맡기고, 끝나면 /diff로 바뀐 내용을 봅니다. 성공 기준: 바뀐 파일 목록을 말할 수 있고, 시키지 않은 변경이 있으면 찾아냅니다.
6. 마음에 들지 않는 변경 하나를 앱의 리뷰 화면이나 Git으로 되돌린 뒤, 나머지를 커밋합니다. 성공 기준: 되돌린 부분만 원래대로 돌아오고 git log에 새 커밋이 보입니다.

복사해 쓰는 프롬프트

이 폴더의 AGENTS.md를 정리해 줘. 아직 파일은 고치지 말고 초안만 보여 줘.
이 폴더는 [무엇을 하는 곳인지 한 문장]이고, 쓰는 사람은 [누가, 어떤 화면으로]야.
지킬 규칙: [규칙 두세 개].
하지 말 것: 새 도구나 패키지 설치 전에 묻기, 파일 지우기 전에 묻기, [그 밖의 금지 사항].
끝났다고 말하기 전에: [직접 확인할 방법].
CLAUDE.md가 있으면 그 규칙과 부딪히는 곳이 없는지도 알려 줘.
한 화면 안에 들어오게 짧게 써 줘.

지금 너의 권한 상태를 알려 줘. 고치지는 말고 보고만.
1. 샌드박스 모드와 승인 정책
2. 쓰기가 허용된 폴더
3. 인터넷을 쓸 수 있는지
4. 지금 따르고 있는 규칙 파일 이름과 그 요점

막히면 이렇게

스스로 점검

• ☐ AGENTS.md가 어느 폴더에 있고, 여러 파일이 있을 때 어느 쪽이 앞서는지 설명할 수 있습니까?
• ☐ 샌드박스 모드와 승인 정책이 각각 무엇을 정하는지 구분하고, Auto가 어떤 조합인지 말할 수 있습니까?
• ☐ 맡기기 전에 커밋하고, 끝난 뒤 /diff로 확인하고, 필요 없는 변경을 되돌려 봤습니까?

기억할 것

• AGENTS.md는 전역, 저장소 맨 위, 하위 폴더 순으로 이어 붙고 가까운 파일이 앞섭니다. Codex는 CLAUDE.md를 저절로 읽지 않습니다.
• 샌드박스는 할 수 있는 범위를, 승인 정책은 묻는 시점을 정합니다. 평소에는 Auto(workspace-write + on-request), 처음 보는 폴더는 읽기 전용입니다.
• 되돌리기는 Git 체크포인트로 합니다. 맡기기 전에 커밋하고, /diff로 확인한 변경만 남깁니다.

더 알아보기

• AGENTS.md 사용법
• 승인과 보안
• 앱의 권한 모드