OpenAI Codex 완전가이드 2편 — 승인 모드 3가지, 샌드박스, AGENTS.md 프레임워크별 예시

 

1편에서 설치하고 첫 세션 실행했습니다. 이번 2편은 Codex를 제대로 쓰기 위한 설정입니다. 승인 모드를 잘못 설정하면 불필요한 확인창이 100번 뜨거나 반대로 아무 확인 없이 파일이 삭제됩니다. AGENTS.md를 안 쓰면 매번 프로젝트 규칙을 처음부터 설명해야 합니다. 두 가지를 제대로 설정하는 것만으로 Codex 사용 경험이 완전히 달라집니다.

---

핵심 요약

→ 승인 모드 3가지: suggest(전부 확인) / auto-edit(파일 자동, 명령 확인) / full-auto(전부 자동)
→ 샌드박스 2가지: workspace-write(기본, 작업 폴더만) / read-only(읽기 전용)
→ 일반 개발 권장 조합: auto-edit + workspace-write
→ AGENTS.md: 프로젝트 루트에 두면 모든 세션에 자동 적용 — 한 번 써두면 끝
→ AGENTS.md 계층 구조: 글로벌(~/.codex/) → 프로젝트 루트 → 하위 디렉토리
→ AGENTS.override.md: 하위 폴더에서 상위 규칙 덮어쓰기
→ AGENTS.md 최대 크기: 32 KiB (초과 시 잘림)
→ AGENTS.md는 크로스 툴 표준 — Copilot, Cursor, Claude Code, Gemini CLI 모두 지원
→ 좋은 AGENTS.md: 명령어 먼저, 설명 나중
→ config.toml: 기본값 고정 설정 파일 (~/.codex/config.toml)

---

실전 1 — 승인 모드 3가지 완전 이해

왜 승인 모드가 중요한가

Codex는 실제로 파일을 수정하고 터미널 명령을 실행합니다.
실수로 잘못된 파일을 지우거나 DB를 날릴 수도 있습니다.
승인 모드는 "Codex가 얼마나 자율적으로 움직이는지"를 결정합니다.

모드별 동작 비교

상황 suggest auto-edit full-auto

파일 읽기	자유	자유	자유
파일 수정	⏸ 확인 요청	✅ 자동	✅ 자동
파일 생성	⏸ 확인 요청	✅ 자동	✅ 자동
파일 삭제	⏸ 확인 요청	✅ 자동	✅ 자동
터미널 명령	⏸ 확인 요청	⏸ 확인 요청	✅ 자동
네트워크 요청	❌ 차단	❌ 차단	❌ 차단

네트워크는 모든 모드에서 기본 차단입니다. 활성화하려면 별도 설정 필요.

---

suggest 모드 실전

codex --approval-mode suggest "인증 모듈 분석해줘"
# 또는 단축 플래그
codex -a suggest "인증 모듈 분석해줘"

화면에서 보이는 것:

Codex가 utils/auth.js 수정을 제안합니다:

─────────────── auth.js ────────────────
- function login(user, pass) {
-   return db.check(user, pass)
- }
+ async function login(user, pass) {
+   try {
+     return await db.check(user, pass)
+   } catch (err) {
+     logger.error('Login failed:', err)
+     throw err
+   }
+ }
────────────────────────────────────────

[A]pply  [S]kip  [Q]uit  [D]iff 전체보기

키 하나로 결정:

A → 이 변경 적용
S → 이 변경 스킵, 다음으로
Q → 세션 종료
D → 전체 diff 보기

언제 suggest 쓰나:

✅ Codex 처음 쓸 때 (뭘 하는지 익히는 단계)
✅ 익숙하지 않은 레거시 코드베이스
✅ 프로덕션 환경 직접 연결된 경우
✅ 보안이 중요한 금융/의료 코드

---

auto-edit 모드 실전 (일반 개발 권장)

codex --approval-mode auto-edit "에러 핸들링 개선해줘"
# 또는
codex -a auto-edit "에러 핸들링 개선해줘"

동작 방식:

파일 수정 → 자동 적용 (확인창 없음)
터미널 명령 → 확인창 뜸

예시:
Codex: "auth.js 수정합니다..." → 바로 적용
Codex: "npm test 실행할까요?" → 확인창 뜸

[Run]  [Don't run]

가장 많이 쓰는 이유:

→ 파일 수정 시 확인 피로 없음 (작업 흐름 방해 안 함)
→ 터미널 명령은 여전히 내가 컨트롤
→ git으로 언제든 롤백 가능 → 파일 수정 자동 적용 안전

auto-edit 전 반드시 할 것:

# 작업 전 git commit — 롤백 기준점
git add -A && git commit -m "before codex: auth refactor"

# 작업 후 diff 확인
git diff HEAD

---

full-auto 모드 실전

codex --approval-mode full-auto "테스트 실행하고 실패하면 전부 수정해줘"
# 또는
codex -a full-auto "테스트 실행하고 실패하면 전부 수정해줘"

주의사항:

⚠️ 파일 수정 + 터미널 명령 전부 자동
⚠️ rm, drop table, 환경변수 변경도 자동
⚠️ 반드시 git commit 후 사용
⚠️ DB 연결된 환경에서는 사용 금지

full-auto 안전하게 쓰는 상황:

✅ 테스트 코드 자동 실행 + 수정 루프
✅ 린팅 에러 자동 수정
✅ 임시 브랜치에서 실험적 리팩토링
✅ CI/CD 파이프라인 (격리된 컨테이너 안)

---

실전 2 — 샌드박스 설정

승인 모드가 "언제 확인하냐"라면, 샌드박스는 "어디까지 접근할 수 있냐"입니다.

샌드박스 레벨

레벨 파일 접근 네트워크 사용 시점

workspace-write	작업 폴더만 쓰기	❌ 차단	기본값, 일반 개발
read-only	읽기만	❌ 차단	코드 분석만, 수정 불필요
danger-full-access	전체 시스템	✅ 허용	외부 컨테이너 안에서만

승인 모드 + 샌드박스 조합

# 권장 조합 1: 일반 개발
codex -a auto-edit -s workspace-write "기능 구현해줘"

# 권장 조합 2: 코드 분석만
codex -a suggest -s read-only "이 코드 어떻게 개선하면 돼?"

# 권장 조합 3: CI/CD 완전 자동 (컨테이너 안에서만)
codex -a full-auto -s danger-full-access "빌드하고 테스트 다 통과시켜줘"

# 권장 조합 4: 네트워크 허용 (패키지 설치 등)
codex -a auto-edit \
  --config sandbox_workspace_write.allow_network=true \
  "최신 패키지 설치하고 마이그레이션해줘"

OS별 샌드박스 구현

macOS:    Apple Seatbelt (sandbox-exec) — 커널 레벨 격리
Linux:    Bubblewrap (bwrap) — 네임스페이스 격리
Windows:  AppContainer 토큰 기반 (experimental)
WSL2:     Linux Bubblewrap 사용

---

실전 3 — config.toml: 기본값 고정

매번 플래그 입력하기 귀찮으면 기본값을 파일에 저장합니다.

파일 위치

# 글로벌 설정 (모든 프로젝트에 적용)
~/.codex/config.toml

# 프로젝트별 설정 (이 프로젝트에만 적용)
{프로젝트 루트}/.codex/config.toml

설정 파일 만들기

mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
# 기본 승인 모드
approval_policy = "auto-edit"

# 기본 샌드박스
sandbox_mode = "workspace-write"

# 기본 모델
model = "gpt-5.4"

# 네트워크 차단 (기본값, 명시적으로 써두기)
[sandbox_workspace_write]
allow_network = false
EOF

프로젝트별 다른 설정

# 민감한 프로젝트 (더 엄격하게)
cat > my-fintech-app/.codex/config.toml << 'EOF'
approval_policy = "suggest"
sandbox_mode = "read-only"
EOF

# 테스트 자동화 프로젝트 (더 자유롭게)
cat > my-test-project/.codex/config.toml << 'EOF'
approval_policy = "full-auto"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
allow_network = true
EOF

프로젝트 config.toml이 글로벌 config.toml보다 우선 적용됩니다.

---

실전 4 — AGENTS.md: Codex에게 프로젝트 규칙 알려주기

AGENTS.md가 없으면:

매 세션마다:
"이 프로젝트는 TypeScript 씁니다. ESLint 규칙 지켜줘.
 테스트는 Jest 씁니다. 함수마다 타입 힌트 붙여줘..."

→ 매번 반복 입력 → 귀찮고 빠트리기 쉬움

AGENTS.md가 있으면:

한 번만 작성 → 이후 모든 세션에 자동 적용
→ "기능 추가해줘" 한 마디만 해도 프로젝트 규칙 자동 준수

---

AGENTS.md 계층 구조

~/.codex/AGENTS.md              ← 글로벌 (모든 프로젝트)
my-project/
├── AGENTS.md                   ← 프로젝트 전체
├── src/
│   ├── AGENTS.md               ← src 이하
│   └── api/
│       └── AGENTS.override.md  ← api만 (상위 규칙 덮어씀)
└── tests/
    └── AGENTS.md               ← tests 이하만

우선순위 (높음 → 낮음)

AGENTS.override.md > AGENTS.md (같은 폴더)
가까운 폴더 > 먼 폴더
프로젝트 > 글로벌

---

글로벌 AGENTS.md 만들기

모든 프로젝트에 공통으로 적용되는 개인 작업 방식을 저장합니다.

cat > ~/.codex/AGENTS.md << 'EOF'
# 글로벌 작업 규칙

## 기본 원칙
- 코드 수정 후 반드시 테스트 실행
- 커밋 메시지: feat/fix/refactor/docs/test 접두사 사용
- 한국어 주석 허용, 에러 메시지는 영어
- console.log 디버그 코드 남기지 말 것

## 보안
- 하드코딩된 비밀키, 토큰, 비밀번호 절대 금지
- .env 파일 절대 수정하지 말 것
- 민감 정보 로그 출력 금지

## Git
- 작업 전 git status 확인
- 파일 삭제 전 반드시 확인 요청
EOF

---

프로젝트별 AGENTS.md 작성 — 프레임워크별 예시

Node.js/Express + TypeScript

cat > my-express-app/AGENTS.md << 'EOF'
# Express API 프로젝트 규칙

## 실행 명령
- 개발 서버: npm run dev
- 테스트: npm test
- 린팅: npm run lint
- 빌드: npm run build

## 기술 스택
- Node.js 22, TypeScript 5.5 strict
- Express 5, Prisma ORM, PostgreSQL
- Jest + supertest, ESLint + Prettier

## 코딩 규칙
- 모든 함수에 반환 타입 명시 필수
- any 타입 사용 금지 → unknown 사용
- async 함수 전부 try/catch 감싸기
- 에러는 logger.error() 사용 (console.log 금지)
- 새 API 엔드포인트 추가 시 JSDoc 주석 필수

## 프로젝트 구조
src/
  routes/     # Express 라우터
  services/   # 비즈니스 로직
  models/     # Prisma 모델
  middleware/ # 미들웨어
  utils/      # 유틸리티

## API 응답 형식
성공: { success: true, data: {...} }
실패: { success: false, error: "메시지" }

## 테스트
- 새 서비스 함수 만들 때 테스트 파일 함께 생성
- 파일명: *.test.ts
- describe/it 구조, 한국어 테스트 설명
EOF

React + TypeScript (프론트엔드)

cat > my-react-app/AGENTS.md << 'EOF'
# React 프론트엔드 규칙

## 실행 명령
- 개발: npm run dev (포트 3000)
- 테스트: npm test
- 빌드: npm run build
- 린팅: npm run lint

## 기술 스택
- React 19, TypeScript 5.5
- Vite, TanStack Query, Zustand
- Tailwind CSS, shadcn/ui
- Vitest + React Testing Library

## 컴포넌트 규칙
- 함수형 컴포넌트만 사용
- Props 타입은 파일 상단에 별도 type으로 정의
- 파일 하나에 컴포넌트 하나 (index.ts로 re-export)
- 200줄 넘어가면 분리 고려

## 네이밍
- 컴포넌트: PascalCase (UserProfile.tsx)
- 훅: use 접두사 (useUserData.ts)
- 유틸: camelCase (formatDate.ts)
- 상수: UPPER_SNAKE_CASE

## 상태 관리
- 로컬 상태: useState
- 서버 상태: TanStack Query
- 전역 상태: Zustand (store/)

## 스타일
- Tailwind 클래스 우선
- 인라인 스타일 금지
- 반응형: mobile-first (sm: md: lg:)
EOF

Python/FastAPI

cat > my-fastapi-app/AGENTS.md << 'EOF'
# FastAPI 프로젝트 규칙

## 실행 명령
- 개발 서버: uvicorn app.main:app --reload
- 테스트: pytest tests/ -v
- 린팅: ruff check .
- 타입 체크: mypy app/
- 의존성 설치: pip install -r requirements.txt

## 기술 스택
- Python 3.12, FastAPI, SQLAlchemy 2.0
- Alembic (DB 마이그레이션), Pydantic v2
- pytest, httpx (테스트)

## 코딩 규칙
- 모든 함수에 타입 힌트 필수
- Pydantic 모델로 입출력 검증
- async def 우선 사용
- 에러: HTTPException 사용, 로그는 logger 사용
- 환경변수: .env 파일, pydantic-settings로 로드

## 프로젝트 구조
app/
  api/        # 라우터
  core/       # 설정, 보안
  models/     # SQLAlchemy 모델
  schemas/    # Pydantic 스키마
  services/   # 비즈니스 로직
tests/
  unit/
  integration/

## DB 규칙
- 직접 SQL 금지, SQLAlchemy ORM 사용
- 마이그레이션: alembic revision --autogenerate
- 트랜잭션: async with session.begin() 패턴
EOF

---

하위 폴더별 다른 규칙: AGENTS.override.md

결제 모듈처럼 특별히 엄격한 규칙이 필요한 폴더에 씁니다.

cat > my-app/src/payments/AGENTS.override.md << 'EOF'
# 결제 모듈 전용 규칙 (상위 AGENTS.md 덮어씀)

## 절대 금지
- API 키, 토큰 하드코딩 절대 금지
- 결제 금액 관련 로직 임의 수정 금지
- 테스트 없이 코드 변경 금지

## 필수 사항
- 모든 변경 전 notify_security_channel() 호출 코드 추가
- 결제 로직 변경 시 idempotency 체크 필수
- 테스트: make test-payments 사용 (npm test 아님)
- 로그에 카드번호, CVV, 개인정보 절대 출력 금지

## 코드 리뷰
- 이 폴더 변경사항은 반드시 /review 실행 후 제출
EOF

---

실전 5 — 좋은 AGENTS.md vs 나쁜 AGENTS.md

❌ 나쁜 AGENTS.md (추상적)

# 프로젝트 규칙

## 코딩
좋은 코드를 작성해줘.
에러 처리를 잘 해줘.
테스트를 작성해줘.

✅ 좋은 AGENTS.md (구체적 + 명령 먼저)

# 프로젝트 규칙

## 명령어 (먼저 읽어라)
- 테스트: npm test
- 린팅: npm run lint && npm run type-check
- 서버: npm run dev

## 에러 처리 (구체적)
모든 async 함수:
try {
  // 로직
} catch (err) {
  logger.error({ err, context: '함수명' }, '에러 설명')
  throw new AppError('사용자용 메시지', 500)
}

## 테스트 작성 기준
- 새 함수 추가 시 테스트 파일 함께 생성 (*.test.ts)
- 최소 커버리지: 정상 케이스 1개 + 에러 케이스 2개
- 테스트 파일 실행: jest src/utils/my-util.test.ts

핵심 원칙:

1. 명령어 먼저 → Codex가 실행 방법을 바로 파악
2. 예시 포함 → 추상적 설명보다 코드 예시 1줄이 낫다
3. 금지 사항 명시 → "하지 말 것"을 명확하게
4. 32 KiB 이하로 유지 → 초과 시 잘림

---

실전 6 — 세션 중 승인 모드 바꾸기

작업 중간에 위험한 작업이 생기면 모드를 즉시 바꿀 수 있습니다.

# 세션 중 슬래시 명령어로 변경
/permissions

# 팝업 표시:
현재 모드: auto-edit
변경할 모드 선택:
  ● suggest     (파일 수정도 확인)
  ○ auto-edit   (현재)
  ○ full-auto   (전부 자동)

실전 시나리오:

일반 작업: auto-edit으로 시작
→ "DB 마이그레이션 파일 수정" 요청 오면
→ /permissions → suggest로 전환
→ 마이그레이션 완료 후 다시 auto-edit 복귀

---

실전 7 — 자주 겪는 문제 해결

문제 1: "AGENTS.md가 적용이 안 돼요"

# 현재 CODEX_HOME 확인
echo $CODEX_HOME

# 비어 있으면 기본값 ~/.codex 사용
# 다른 값이 있으면 거기 AGENTS.md 있는지 확인

# Codex가 AGENTS.md 찾는 경로 확인
codex
> 현재 적용된 AGENTS.md 내용이 뭐야?

문제 2: "파일 크기 초과 경고 뜸"

Instructions truncated 경고 = AGENTS.md가 32 KiB 초과

해결:
1. AGENTS.md 내용 줄이기
2. 또는 여러 폴더로 분산
   프로젝트/AGENTS.md (핵심만)
   프로젝트/src/AGENTS.md (소스코드 규칙)
   프로젝트/tests/AGENTS.md (테스트 규칙)

문제 3: "터미널 명령 실행 거부됨"

샌드박스에서 차단된 경우:
1. 어떤 명령인지 확인 (네트워크 요청? 외부 폴더 접근?)
2. 필요하면 config.toml에서 허용 추가:

[sandbox_workspace_write]
allow_network = true                    # 네트워크 허용
writable_roots = ["/tmp", "/home/..."] # 추가 쓰기 경로 허용

문제 4: "auto-edit인데 파일 수정이 확인 창 뜸"

작업 폴더 밖의 파일 수정 시 확인창 뜸 (정상 동작)
→ workspace-write 샌드박스가 외부 경로 차단하는 것
→ 필요하면 writable_roots에 해당 경로 추가

---

마무리

상황 추천 조합

Codex 처음 씀	suggest + workspace-write
일반 개발 (기본)	auto-edit + workspace-write
코드 분석만	suggest + read-only
테스트 자동화	full-auto + workspace-write
CI/CD 파이프라인	full-auto + danger-full-access (컨테이너 안)
결제/보안 코드	suggest + read-only

AGENTS.md는 처음 프로젝트 시작할 때 30분 투자해서 작성해두면, 이후 수십 시간의 반복 설명을 없앨 수 있습니다. 특히 명령어 먼저, 예시 포함, 금지사항 명시 이 세 가지만 지켜도 Codex 응답 품질이 눈에 띄게 좋아집니다.

3편에서는 Codex의 최강 기능인 Git Worktree 병렬 에이전트를 실전으로 다룹니다. 브랜치 하나에서 기능 3개를 동시에 구현하는 방법, 충돌 없이 머지하는 패턴까지 씁니다.

---

•  

관련 글

• OpenAI Codex 완전가이드 1편 — 설치부터 첫 실행까지
• OpenAI Codex 완전가이드 2편 — 승인 모드, 샌드박스, AGENTS.md
• OpenAI Codex 완전가이드 3편 — Git Worktree 병렬 에이전트
• OpenAI Codex 완전가이드 4편 — Codex App, Cloud, MCP 연동
• OpenAI Codex 완전가이드 5편 — 가격, CI/CD 자동화, Claude Code vs Codex 최종 비교

 

---