Codex 개요
승인·sandbox·AGENTS.md

Session 7 · Codex 실전 진입

두 갈래 배포 · 승인 3단계 · sandbox 3종 · AGENTS.md 3단 계층 · codex exec · Web UI · 실전 매핑

강사 박수현 · 🚀 젠아이랩스(GenAI Labs)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing two terminal windows side by side connected by a horizontal switching arrow in the middle. Left terminal has an angle-bracket prompt with a small label 'Claude Code' above it. Right terminal has an angle-bracket prompt with a small label 'Codex' above it. Above the arrow floats a short English caption 'Same hands, different tools'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

Session 7 · Codex 실전 진입

PART 1

Codex 등장 배경 — 두 갈래 배포·개념 대응

왜 Codex 인가 · CLI 와 Web 두 갈래 · Claude Code 와 같지 않은 세 가지.

Codex 두 갈래 — CLI 와 Web UI

Codex 는 두 갈래로 배포된다. 같은 모델·같은 AGENTS.md 규약을 공유하되 실행 환경과 승인 UX 가 다르다.

세 가지 차이 — 같지 않은 부분만

대부분의 개념은 Claude Code 와 동일하고 명칭·문법만 다르다 (전체 대응표는 마지막 정리 슬라이드). 같지 않은 것은 이 셋뿐.

PART 2

셋업 — 설치·인증·요금·모델

설치 2종 · Node 22+ · 인증 두 갈래 · 요금 6티어 · 모델 3계열 라우팅.

설치 경로 2종 — npm · Homebrew

Codex CLI 설치는 두 갈래다. Native installer 는 아직 없다. Node.js 22+ 필수.

npm install -g @openai/codex

brew install codex

설치 확인

codex --version
codex --help

인증 두 갈래 — ChatGPT 구독 · API 키

어느 쪽을 쓰느냐에 따라 요금 청구가 달라진다.

인증 성공 후 확인

codex
# 브라우저가 열리고 ChatGPT 로그인 → 성공 시 프롬프트가 뜸
> "이 리포 3줄로 요약해줘"

ChatGPT 요금 — 2026년 6월 기준

모델 3계열 — 실무 라우팅

모델 전환 두 가지 방법

# 1. 세션 시작 시
codex --model gpt-5.5
codex --model gpt-5.4-mini

# 2. 세션 안에서 (설정에 따라)
/model gpt-5.5

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — three stylized cars lined up left to right on a road, each with a distinct color and label above. Left car (teal) labeled 'GPT-5.5'. Middle car (purple) labeled 'GPT-5.4'. Right car (warm orange) labeled 'GPT-5.4-mini'. Above them a signpost caption 'Codex model routing'. Clean editorial style, 16:9. English ONLY, each label EXACTLY ONCE."

모델 3계열 — 실무 라우팅

PART 3

승인 모드 · sandbox — 두 축의 격자

두 축 · 프리셋 3개 · 승인 3단계 · sandbox 3종 + 네트워크 스위치 · CLI 예.

두 축의 격자 — 승인 × sandbox

Codex 의 실행 제어는 두 축 이 격자로 얽혀 있다. Claude Code 의 4개 permission mode 와 다르다.

2 × 3 격자 · 프리셋 위치 — 한눈에

대각선 3칸이 공식 프리셋 · 나머지 6칸은 커스텀 조합.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background — 3x3 grid. Top axis labels ONCE: 'Untrusted' | 'On-request' | 'Never' with subheader 'Approval policy'. Left axis labels ONCE: 'Read-only' / 'Workspace-write' / 'Danger-full-access' with sideheader 'Sandbox'. Nine cells with preset chips only where they exist (Read Only / Auto / Full Access). Clean editorial style, 16:9. English ONLY, each axis label appears EXACTLY ONCE (top only, not repeated bottom)."

승인 모드 3단계 — --ask-for-approval

세션 안 승인 UX — 프롬프트가 뜨면 세 옵션.

[y] 이번만 허용
[a] 이 세션 내 자동 허용
[n] 거부

sandbox 3종 + 네트워크 스위치 — --sandbox

승인·sandbox CLI 예 — 상황별 세 조합

# 탐색·검토용 — 낯선 리포
codex --sandbox read-only --ask-for-approval untrusted

# 로컬 자기 리포 (기본 프리셋 = Auto)
codex --sandbox workspace-write --ask-for-approval on-request

# 격리 컨테이너 안 배치 (위험)
codex --sandbox danger-full-access --ask-for-approval never

로컬 CLI vs Codex Web — 언제 각각

PART 4

AGENTS.md — CLAUDE.md 대응

AGENTS.md 개념 · 3단 계층 · 32 KiB 상한 · 언어별 예 3개 · Claude 규약과 나란히.

AGENTS.md 가 뭔가 — AI 에이전트를 위한 README

AGENTS.md 는 Codex 가 리포에 진입할 때 자동으로 읽는 규약 파일이다. Claude Code 의 CLAUDE.md 와 개념이 같다.

AGENTS.md 3단 계층 — 전역·프로젝트·서브

예 1 — Python · FastAPI

# AGENTS.md — my-fastapi-app

## Setup
- Python 3.11+ (pyenv 관리)
- `pip install -r requirements.txt`
- `pip install -r requirements-dev.txt` for tests

## Commands
- Run: `uvicorn app.main:app --reload`
- Test: `pytest -x`
- Lint: `ruff check . && ruff format .`
- Type check: `mypy app/`

## Conventions
- Route 는 `app/routes/` 안에 도메인별 파일
- 응답 모델은 pydantic, 요청도 pydantic (Query/Body 강제)
- 새 엔드포인트 추가 시 `tests/routes/` 에 최소 1개 pytest 추가

## Do NOT
- `main` 브랜치 직접 커밋 금지 (feature 브랜치 → PR)
- Alembic 마이그레이션 파일 수동 편집 금지 (autogenerate 만)

예 2 — TypeScript · Next.js

# AGENTS.md — my-nextjs-app

## Setup
- Node.js 22+ (nvm 관리)
- `pnpm install`

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test` (Vitest)
- Lint: `pnpm lint` (ESLint + Prettier)

## Conventions
- App Router (`app/`) 사용, Pages Router 사용 금지
- Server component 를 기본, `"use client"` 는 필요 시에만
- Tailwind 유틸리티 우선, styled-components 는 legacy 만
- `components/ui/` 는 shadcn/ui 기반, 직접 편집 금지

## Do NOT
- `any` 타입 금지 (tsconfig strict)
- `.env` 파일 커밋 금지

예 3 — Go · CLI 도구

# AGENTS.md — mytool

## Setup
- Go 1.23+
- `go mod download`

## Commands
- Build: `go build -o mytool ./cmd/mytool`
- Test: `go test ./...`
- Bench: `go test -bench=. ./...`
- Lint: `golangci-lint run`

## Conventions
- `cmd/` 는 진입점만, 로직은 `internal/` 에
- Cobra 로 CLI, urfave/cli 사용 금지
- 에러는 `%w` 로 래핑, `errors.Is` · `errors.As` 로 검사

## Testing
- Table-driven tests 가 기본
- Golden file 은 `testdata/` 에

CLAUDE.md 와 나란히 — 중복 유지 전략 3

두 도구를 다 쓰는 팀에게 나오는 실무 질문 — 같은 규약을 두 파일에 중복 유지해야 하나.

# 리포 루트에서
ln -s CLAUDE.md AGENTS.md

<repo>/
├── AI_CONVENTIONS.md
├── CLAUDE.md    # @AI_CONVENTIONS.md
└── AGENTS.md    # @AI_CONVENTIONS.md

PART 5

감사 로그 · 배치 · 병렬 · MCP

로그 위치 · codex exec 배치 · 병렬 3갈래 · MCP 통합.

~/.codex/ — 로그·히스토리·설정

Codex 는 세션 활동을 두 곳에 남긴다. 하나는 사람용 히스토리, 다른 하나는 디버깅용 로그.

세션 재개

codex resume              # 최근 세션 목록에서 고르기
codex resume <session-id> # 특정 세션 ID 로 재개
codex fork <session-id>   # 새 브랜치로 fork

grep -iE "error|panic" ~/.codex/log/codex-tui.log | tail -20
grep "2026-06-15T14:" ~/.codex/log/codex-tui.log

codex exec — 배치 · 비대화형

Claude Code 의 claude -p 에 대응하는 배치 모드. 세션이 아니라 일회성 응답을 받는다. CI · 셸 파이프 · 스크립트용.

# 프롬프트 한 번 · 결과만 출력
codex exec "이 리포 3줄로 요약해줘"

# @file 참조
codex exec "@README.md 한 줄 요약"

# 셸 파이프
cat production.log | codex exec "이 로그의 에러 패턴 5가지"

# JSON Lines — 스크립트 파싱용
codex exec --json "test 실패 원인 분류" > result.jsonl
# 이벤트 스트림이 한 줄씩 · jq 로 `.type=="tool_use"` 등 필터링해 파이프 조합

# CI 안 · 격리 컨테이너
codex exec \
  --sandbox danger-full-access \
  --ask-for-approval never \
  "린트 자동 정리해줘"

병렬 세션 — 3갈래

큰 리포에서는 리팩토링·테스트·문서 정리를 병렬로 굴리고 싶다. Codex 는 세 갈래로 지원.

git worktree 조합 — 로컬 병렬의 표준 패턴

병렬 세션이 같은 파일을 동시에 만지면 편집 충돌이 난다. worktree 는 브랜치별로 작업 디렉토리를 격리해 각 세션이 자기 파일만 건드리게 한다.

git worktree add ../myrepo-auth feature/auth
git worktree add ../myrepo-db feature/db
git worktree add ../myrepo-ui feature/ui

cd ../myrepo-auth && codex
cd ../myrepo-db   && codex
cd ../myrepo-ui   && codex

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — three terminal windows arranged side by side in a row, each with an angle-bracket prompt. Left terminal has a small branch tag labeled 'feature/auth', middle terminal has a branch tag labeled 'feature/db', right terminal has a branch tag labeled 'feature/ui'. Each terminal shows a running spinner icon. Above the three terminals floats a short English caption '3 sessions equal 3x tokens'. A small stylized wallet icon with a rising cost arrow sits in the top right corner. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

병렬 세션 — 그림 한 장으로 읽기

MCP 통합 — 두 도구가 서버 공유

Codex 는 MCP (Model Context Protocol) 를 지원한다. Claude Code 에서 만들거나 붙였던 MCP 서버를 그대로 Codex 에서 쓸 수 있다.

설정 위치. ~/.codex/config.toml 에 [mcp_servers] 섹션.

# ~/.codex/config.toml

[mcp_servers.slack-summary]
command = "python"
args = ["-m", "slack_summary_bot"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

PART 6

Web UI · 실전 매핑 · 정리

Codex Web 세 화면 · 상황·조합 매트릭스 2 슬라이드 · Codex vs Claude · 미니 실습 3 · 정리 한 문장.

Codex Web UI 세 화면 — 세션·승인·Diff

Codex Web (chatgpt.com/codex) 은 세 화면이 핵심.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing three stacked browser window mockups arranged diagonally. Top window is a session list panel with three vertical cards, each labeled 'Task A', 'Task B', 'Task C'. Middle window is a chat detail with three inline approval buttons labeled 'Approve', 'Reject', 'View Diff'. Bottom window is a GitHub-style diff view with green and red hunks and a small inline comment box labeled 'Comment'. Each window has a small red circle highlight on its key UI element. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

Codex Web UI 세 화면 — 세션·승인·Diff

상황·조합 매트릭스 ① — 일상·개발

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — a vertical stack of five horizontal cards on the left, and to the right of each card a terminal-style command chip. Card 1 icon is a magnifying glass with tag 'Unknown Repo', card 2 icon is a laptop with tag 'Daily Repo', card 3 icon is a broom with tag 'Lint Sweep', card 4 icon is a blueprint with tag 'Refactor Plan', card 5 icon is a pull-request arrow with tag 'PR Review'. Each right-side chip shows a short 'codex ...' command in monospace type. A short English caption at the top reads 'Situation to command — wall map'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

상황·조합 매트릭스 ② — 자동화·격리·진단

Codex vs Claude Code — 팀·자동화·격리 시나리오

실습 1 — 첫 세션 · sandbox 관찰

# 1. 자기 사이드 프로젝트 리포로
cd ~/my-project

# 2. 세 sandbox 를 각각 시작해 감각 잡기
codex --sandbox read-only --ask-for-approval untrusted
> "이 리포 3줄로 요약해줘"
> "test.txt 만들어줘"   # 거부됨을 관찰
> Ctrl+C · Ctrl+C

codex   # 기본 = Auto (workspace-write · on-request)
> "test.txt 만들어줘"   # 승인 프롬프트 뜸

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — three vertical cards arranged side by side, each with a numbered badge in the top-left corner. Card 1 header 'Lab 1 — Sandbox Feel' shows a shield icon, a command chip 'codex --sandbox read-only', an observation bullet 'Same prompt, different outcome', and a time tag '3 min'. Card 2 header 'Lab 2 — AGENTS.md Draft' shows a document icon, a command chip 'draft AGENTS.md', an observation bullet 'Draft is only a draft', and a time tag '3 min'. Card 3 header 'Lab 3 — codex exec Batch' shows a gear icon, a command chip 'codex exec --json', an observation bullet 'No session, result only', and a time tag '2 min'. Above the cards floats a short English caption 'Three labs, one AGENTS.md on your laptop'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

실습 3개 개요

실습 2 — AGENTS.md 초안 작성

# Codex 세션 안에서
> "이 리포에 맞는 AGENTS.md 초안을 만들어줘.
   Setup · Commands · Conventions · Do NOT 4개 섹션으로."

# 결과를 AGENTS.md 로 저장 (Codex 가 저장을 제안하면 승인)

실습 3 — codex exec 배치

# 셸에서 세션 없이 바로
codex exec "@README.md 한 줄 요약"

# JSON 출력
codex exec --json "이 리포에서 pytest 실행 방법" | head -20

# 자기 셸 alias — `~/.zshrc` · `~/.bashrc` 에 등록해야 세션 넘어 유지
alias csum='codex exec "요약해줘"'

# 로그 요약
cat /tmp/app.log | csum

Codex vs Claude Code — 정리표

트러블슈팅 상위 3 — 참여자가 자주 부딪히는 문제

마무리 — 한 문장으로

이 세션이 끝났다. 노트북에서 Codex 가 뜨고, 승인 모드 3단계와 sandbox 3종을 상황별로 매핑할 수 있으며, 자기 리포에 AGENTS.md 초안이 놓였다.

상황이 애매하면 승인·sandbox 어느 축에서 결정할지, AGENTS.md 로 이미 답이 있는지부터 짚는다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing two stylized terminal windows side by side. Left terminal shows an angle-bracket prompt with a small label 'Claude Code' above it. Right terminal shows an angle-bracket prompt with a small label 'Codex' above it. A short English caption in the center reads 'Two tools, same axes, different labels'. Above each terminal floats a small icon set — approval shield, sandbox box, and map symbol — shared between them by a dotted line. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

마무리 — 두 도구, 같은 축, 다른 라벨