Codex CLI 사용 가이드: AGENTS.md · config.toml · Skills

본문에서 에이전트 도구를 다룰 때 Claude Code 와 함께 자주 비교되는 또 한 명의 주연이 OpenAI Codex CLI 예요. 같은 카테고리의 도구지만 설계 철학과 설정 면이 미묘하게 달라서, 한쪽 감각으로 다른 쪽을 만지면 헛다리를 짚기 쉬워요. 이 부록은 Codex CLI 가 어떤 골격으로 짜여 있는지를 풀어내고, Claude Code 부록과 같은 줌 레벨에서 비교할 수 있는 좌표를 잡는 것이 목적이에요.

같이 보면 좋은 것: Claude Code 3대 설정 축 — CLAUDE.md · Hooks · Skills. 이 부록과 같은 구조로 짝을 이룹니다.

한 줄로 미리 보기: Codex CLI 도 결국 "정적 지침(AGENTS.md) + 환경 설정(config.toml) + 동적 확장(Skills · MCP · Plugins)" 의 3박자로 굴러갑니다. 이름과 파일 위치, 권한 모델만 다를 뿐 큰 그림은 Claude Code 와 비슷해요.

이 문서를 다 읽고 나면, 같은 작업을 Codex 에 시키려 할 때 "이건 AGENTS.md 감인가, config.toml 감인가, Skill 감인가" 를 한 박자에 답할 수 있게 됩니다.

0. 읽는 방법

이 부록은 Claude Code 3대 설정 축 과 좌우 대칭으로 읽도록 의도되었습니다.

개념·정의만 빠르게: §1~§2 (Codex 의 위치와 3축의 윤곽).
실제 파일 만질 때: §3 (AGENTS.md), §4 (config.toml · 샌드박스), §5 (Skills · MCP · Plugins).
두 도구를 골라야 할 때: §6 정량 비교표.
레퍼런스: §8 부록의 트리 템플릿·config.toml 샘플.

서술 기준: 본문 수치·필드명은 2026-05 기준 OpenAI 공식 문서(developers.openai.com/codex, github.com/openai/codex)에서 확인된 사실만 적었습니다. Codex CLI 는 갱신 주기가 짧으므로, 키 이름이 바뀐 듯하면 공식 문서를 한 번 더 확인하세요.

1. Codex CLI 의 위치와 정체

Codex 라는 이름이 두 번 등장한 적이 있다는 사실부터 짚습니다. 2021년의 옛 Codex(GPT-3 기반 코드 모델, OpenAI 가 한참 전에 폐기) 와, 지금 다루는 새 Codex CLI(2025년 이후 OpenAI 가 다시 들고 나온 터미널 에이전트) 는 이름만 같을 뿐 별개입니다. 이 문서는 모두 새 Codex CLI 이야기예요.

1.1 Codex CLI 의 자리

Codex CLI 는 OpenAI 가 직접 만든 터미널용 에이전트 하네스입니다.

CLI(터미널에서 실행하는 명령줄 도구) 형태가 메인. codex 커맨드로 진입.
내부적으로 OpenAI 모델(GPT-5 계열·o-시리즈 등)과 연결되어 동작.
설치는 npm install -g @openai/codex 또는 brew install --cask codex. GitHub Releases 에서 macOS · Linux 바이너리도 받을 수 있어요.
인증은 ChatGPT 계정 로그인(Plus/Pro/Business/Edu/Enterprise) 또는 OpenAI API 키.
본체는 Rust 로 작성되어 있어서 Node 의존성 없이 동작하는 점이 특이합니다(npm 은 어디까지나 배포 채널).

유사 도구 카테고리: Claude Code, Cursor, Aider, Continue, Roo Code 등. Codex CLI 는 Anthropic 의 Claude Code 와 가장 직접적으로 비교되는 자리에 서 있어요.

1.2 비유 — 두 명의 비서

Claude Code 와 Codex CLI 의 차이를 한 문장으로 잡으려면 "같은 비서 자격증을 가진 두 사람" 비유가 편합니다.

두 사람 다 "코드 읽기 · 파일 편집 · 셸 실행 · 테스트 돌리기" 까지 같은 자격증을 갖고 있어요.
그런데 출신 학교 (모델 제공자), 업무 매뉴얼 양식 (지침 파일 이름), 결재 절차 (승인·샌드박스 모델) 가 달라요.
처음엔 "둘 다 비서니까 같지" 싶지만, 실제로 한 자리에 같이 앉혀 보면 사인하는 칸·결재 올리는 흐름·반차 신청 양식이 달라서 한쪽 감각으로 다른 쪽을 다루면 어긋납니다.

비유의 한계: 비서 비유는 "둘 다 사람이지만 회사 양식이 다르다" 는 면을 잡기 좋지만, 실제 차이는 단순 양식이 아니라 권한 부여 모델 자체 가 다른 부분도 있습니다 (Codex 의 OS-레벨 샌드박스 vs Claude Code 의 allowlist 기반 permissions). §4·§6 에서 정확히 짚어요.

1.3 깜짝 사실 두 가지

깜짝 사실 1 — Codex CLI 의 본체는 Rust 로 짜여 있다. 배포 채널이 npm 이라 Node 도구처럼 보이지만 실제 바이너리는 Rust. 그래서 Node 가 없는 환경에서도 Homebrew · 직접 다운로드로 깔 수 있어요. 사내 폐쇄망 처럼 npm 접근이 막힌 환경에서 의외로 유리한 포인트.

깜짝 사실 2 — Codex 의 "Skills" 는 Claude Code 의 Skills 와 거의 동일한 개념이다. 이름이 같은 정도가 아니라 둘 다 SKILL.md 라는 같은 파일명 에, 같은 디렉토리 구조 를 씁니다. OpenAI 가 "open agent skills standard" 위에 얹어 둔 결과로 두 도구가 같은 스킬 패키지를 (이론상) 나눠 쓸 수 있습니다. 자세한 건 §5.3.

2. Codex 설정의 3대 축

Claude Code 가 CLAUDE.md · Hooks · Skills 의 3축으로 굴러간다면, Codex CLI 는 다음 3축으로 굴러갑니다.

축	Codex 에서의 이름	역할	Claude Code 의 대응축
정적 지침	`AGENTS.md`	세션 시작 시 자동 주입되는 지침	`CLAUDE.md`
환경 설정	`~/.codex/config.toml` + 샌드박스 + 승인 정책	모델·권한·도구·MCP 의 종합 설정	`~/.claude/settings.json` + permissions
동적 확장	Skills · Plugins · MCP servers	필요할 때 꺼내 쓰는 특화 능력	Skills · Plugins · MCP servers

2.1 Claude Code 와 다른 점

3축 구조는 비슷하지만 결정적인 차이가 셋 있어요.

Hook 이벤트 수가 더 적음 — Claude Code 는 PreToolUse PostToolUse 등 20여 개 훅이 1급 시민(first-class)으로 결정적 자동화의 핵심을 차지합니다. Codex 도 1급 시민 Hooks 를 제공해요 (v0.129.0~, 2026-05). SessionStart · PreToolUse · PermissionRequest · PostToolUse · UserPromptSubmit · Stop 6개 이벤트를 [hooks] 테이블 또는 hooks.json 으로 등록할 수 있어요. Claude Code 가 20여 이벤트를 지원하는 데 비해 이벤트 수는 적지만, 동일 카테고리의 메커니즘이 존재한다는 점은 명확해요.
OS 레벨 샌드박스가 1급 시민 — Codex 는 macOS 의 Seatbelt, Linux 의 Landlock 같은 OS 권한 시스템을 직접 끼워 넣어 "쓰기 금지 디렉토리" 를 커널 수준에서 막아요. Claude Code 의 allowlist 기반 permissions 는 하네스(애플리케이션) 수준 차단이라는 점이 차이.
승인 정책과 샌드박스가 별도 축 — Codex 에선 approval_policy (사용자에게 물어볼지) 와 sandbox_mode (실제로 뭘 막을지) 가 두 개의 다른 키로 나뉘어 있어 조합이 가능해요. §4.2 에서 자세히.

2.2 의사결정 트리 — 새 행동을 어디에 둘까

Codex 환경에서 새 행동을 추가할 때 다음 흐름으로 자리를 잡으면 헤매지 않습니다.

flowchart TD Start(["새 행동을 추가 (add new behavior)"]) Q1{"LLM 컨텍스트에 항상 깔려야 하는 배경 규칙인가? (always-on background?)"} Q2{"세션 환경 설정 또는 권한 설정인가? (per-session env or permission?) (모델 / 승인 / 샌드박스 / MCP)"} Q3{"가끔 호출하는 긴 절차 / 플레이북인가? (long procedure / playbook?)"} A1["AGENTS.md (정적 규칙 / static rule)"] A2["config.toml + 샌드박스 / 승인 (sandbox / approval)"] A3["Skill (요청 시 호출 / on demand)"] A4["그냥 프롬프트로 지시 (just prompt)"] Start --> Q1 Q1 -->|"예 (yes)"| A1 Q1 -->|"아니오 (no)"| Q2 Q2 -->|"예 (yes)"| A2 Q2 -->|"아니오 (no)"| Q3 Q3 -->|"예 (yes)"| A3 Q3 -->|"아니오 (no)"| A4

(범례: "always-on background" = 매 세션 LLM 이 항상 깔고 가야 하는 배경 규칙. "per-session env or permission" = 모델 선택·승인 모드·샌드박스·MCP 같은 환경 설정. "long reusable procedure/playbook" = 가끔 호출하는 긴 절차.)

Part A — 핵심 골격: AGENTS.md

Codex 가 매 세션의 첫 페이지로 자동으로 펼치는 책. Claude Code 의 CLAUDE.md 와 정확히 같은 자리에 앉아 있는 파일입니다.

3. AGENTS.md

AGENTS.md 는 Codex 가 매 세션의 첫 페이지로 자동으로 펼치는 책 — 팀 규율집에 비유하면, 매일 아침 가장 먼저 읽어야 하는 페이지에 해당해요. Claude Code 의 CLAUDE.md 와 같은 자리, 같은 역할.

3.1 개념: 세션 시작 시 자동 주입되는 지침

Codex CLI 는 세션을 시작할 때 현재 작업 디렉토리에서 위로 거슬러 올라가며 AGENTS.md 파일을 찾아 LLM 컨텍스트에 주입합니다. Claude Code 의 CLAUDE.md 와 동일한 패턴이에요.

주입 순서: 전역(~/.codex/AGENTS.md) → 프로젝트 루트(AGENTS.md) → 하위 디렉토리(존재할 경우).
하위 파일이 상위 파일을 특화·오버라이드 합니다.
LLM 입장에서는 "내 세션이 시작될 때부터 몇 장의 지침서가 이미 펼쳐져 있는 상태" 가 됩니다.

이것이 "매 대화마다 같은 말을 다시 적지 않아도 되는" 비결입니다.

3.2 파일 위치 계층

Codex 가 AGENTS.md 를 찾는 자리는 다음 4 계층으로 정리됩니다.

flowchart TD Global["전역/개인(Global / Personal) ~/.codex/AGENTS.md 모든 세션, 개인 스타일"] Project["프로젝트 루트(Project Root) <repo-root>/AGENTS.md 레포 전역 규칙(스택·빌드)"] Sub["서브디렉토리(Subdirectory) <repo-root>//AGENTS.md 폴더 로컬 오버라이드"] Cwd["작업 디렉토리(Working Directory) $(pwd)/AGENTS.md 가장 구체적인 오버라이드"] Global --> Project --> Sub --> Cwd

(범례: Codex 는 현재 작업 디렉토리에서 시작해 위로 부모 디렉토리들을 훑으며 만나는 모든 AGENTS.md 를 누적해 주입합니다. 가장 가까운 파일이 가장 강한 우선순위.)

2026-05 기준 보정: Codex 의 하위 디렉토리 AGENTS.md 추가 로딩 동작은 빌드에 따라 다를 수 있어요 (관련 기능 플래그가 있는 경우 [features] 테이블에서 확인하세요). 우선순위·범위 안내가 시스템 메시지에 자동 첨부되는 빌드도 있습니다.

3.3 작성 패턴 — 무엇을 어디에 둘까

계층	쓰는 내용	쓰지 말아야 할 것
전역 (`~/.codex/AGENTS.md`)	호칭·말투·언어 규칙, 모든 프로젝트에 통하는 코드 스타일, 공용 커밋 정책	특정 프로젝트 한정 기술 스택
프로젝트 루트 (`<repo>/AGENTS.md`)	기술 스택, 빌드·테스트 명령, 디렉토리 맵, 프로젝트 고유 규칙	매 세션마다 바뀌는 임시 작업 메모
하위 디렉토리 (`<repo>/<sub>/AGENTS.md`)	해당 폴더의 특수 규칙 (예: `migrations/` 의 명명 규약, `infra/` 의 위험 명령 차단)	루트로 끌어올려도 되는 일반 규칙

3.4 AGENTS.md 작성 템플릿

# 프로젝트 X

## 기술 스택
- 백엔드: Node.js 20 + Fastify
- 프론트: React 19 + Vite
- DB: PostgreSQL 16

## 실행
- 개발 서버: `npm run dev` (포트 3000)
- 테스트: `npm test`
- 빌드: `npm run build`

## 디렉토리 구조
- `src/api/` — REST 라우트 정의
- `src/ui/` — React 컴포넌트
- `migrations/` — DB 마이그레이션 (파일명: `NNNN_description.sql`)

## 규칙
- 모든 API 응답은 `{ ok: boolean, data?: any, error?: string }` 형식
- 신규 마이그레이션은 절대로 기존 파일을 수정하지 않음. 새 파일만 추가.
- 커밋 메시지는 Conventional Commits 규약 (`feat:`, `fix:`, `chore:`)

(겉보기는 Claude Code 의 CLAUDE.md 와 똑같습니다. 일부러 같은 양식을 골랐어요 — Codex 든 Claude Code 든 한쪽 양식이 다른 쪽에 그대로 통한다는 점이 사실 가장 큰 실용 정보입니다.)

3.5 트리거·지연 로드 패턴

전역 AGENTS.md 가 길어지면 매 세션 정적 레이어가 비대해집니다. Claude Code 와 마찬가지로, 자주 쓰지 않는 큰 절차는 본문에 직접 적지 말고 별도 파일로 빼서 트리거로 호출 하는 것이 좋아요.

## 트리거 참조

- Postgres 마이그레이션 작업이면: `<repo>/docs/migration-protocol.md` 를 먼저 읽어라
- 보안 리뷰가 필요하면: `<repo>/docs/security-checklist.md` 를 먼저 읽어라

이렇게 두면 평소엔 짧은 트리거 라인만 컨텍스트에 올라가고, 실제로 그 작업이 발생할 때만 LLM 이 해당 문서를 read 도구로 직접 가져옵니다 — 정적 레이어를 가볍게 유지하면서 깊이 있는 절차를 보존하는 구조.

3.6 CLAUDE.md 와의 차이

같은 자리, 다른 디테일을 정리하면 다음과 같아요.

항목	Codex `AGENTS.md`	Claude Code `CLAUDE.md`
전역 위치	`~/.codex/AGENTS.md`	`~/.claude/CLAUDE.md`
프로젝트 위치	`<repo>/AGENTS.md`	`<repo>/CLAUDE.md`
하위 폴더 로딩	기능 플래그(`child_agents_md`) 로 토글	자동으로 누적
부속 파일 컨벤션	`~/.codex/` 디렉토리 안 임의 마크다운 (참조용)	`~/.claude/` 안 `active-projects.md` 등
최대 크기 제한	`project_doc_max_bytes` 로 명시 가능	명시적 한도 키 없음 (실용상 짧게 유지 권고)

실전 케이스 박스 — 어떤 줄을 어디에 둘까?

"한국어로 답해주세요" → 전역. 모든 세션에 통함.

"사내망에서는 외부 API 금지" → 환경별 작업 루트의 AGENTS.md.

"이 프로젝트의 빌드는 npm run build, 포트는 3000" → 프로젝트 루트.

"오늘 마이그레이션 4개 작업 중, 3번까지 끝남" → AGENTS.md 가 아닌 별도 인수인계 파일(예: CONTINUE.md).

Part B — 환경 설정: config.toml + 샌드박스

모델·승인·샌드박스·MCP·기능 플래그를 한 파일에 모은 컨트롤 패널. Claude Code 의 ~/.claude/settings.json 과 같은 자리지만, JSON 대신 TOML 을 쓰는 점, 그리고 OS 레벨 샌드박스가 1급 키 라는 점이 다릅니다.

4. config.toml + 승인 모드 + 샌드박스

4.1 ~/.codex/config.toml 핵심 필드

전역 사용자 설정은 ~/.codex/config.toml, 프로젝트 한정 오버라이드는 <repo>/.codex/config.toml 에 둡니다. 핵심 필드를 그룹별로 정리하면 다음과 같아요.

그룹	키	의미
모델	`model`	사용할 모델 ID (예: `gpt-5.5`(권장) · `gpt-5.4`(fallback) · `gpt-5.3-codex`(코딩 특화 flagship) · `gpt-5.3-codex-spark`(ChatGPT Pro 한정 경량)
	`model_provider`	프로바이더 ID (기본 `openai`)
	`model_context_window`	사용 가능한 컨텍스트 토큰 수
	`model_reasoning_effort`	`minimal` / `low` / `medium` / `high` / `xhigh`
	`model_instructions_file`	빌트인 시스템 지침을 대체할 외부 파일 경로
승인	`approval_policy`	`untrusted` / `on-request` / `never` 또는 세부 토글 (§4.2)
	`approvals_reviewer`	`user` / `auto_review`
샌드박스	`sandbox_mode`	`read-only` / `workspace-write` / `danger-full-access`
AGENTS.md	`project_doc_max_bytes`	`AGENTS.md` 에서 읽어들일 최대 바이트
	`project_doc_fallback_filenames`	`AGENTS.md` 가 없을 때 대체로 시도할 파일명 목록
	`project_root_markers`	프로젝트 루트로 인식할 마커 파일명
웹 검색	`web_search`	`disabled` / `cached` / `live`, 추가로 `context_size`·`allowed_domains`·`location`
MCP	`[mcp_servers]` 테이블	외부 MCP 서버 등록 (§5.2)
기능 플래그	`[features]` 테이블	`shell_tool`·`multi_agent`·`memories`·`undo`·`unified_exec`·`personality`·`fast_mode`·`web_search`
기타	`service_tier`	`flex` / `fast`
	`personality`	`none` / `friendly` / `pragmatic`
	`profile`	시작 시 기본 프로필

(2026-05 기준 OpenAI 공식 문서 — Codex 는 갱신 빈도가 높아 키 추가·이름 변경이 잦음. 새 키가 필요하면 developers.openai.com/codex/config-reference 에서 확인.)

4.2 승인 모드(approval_policy)

approval_policy 는 "Codex 가 어떤 작업을 사용자에게 물어보고 진행할지" 를 정합니다. 큰 모드 세 개와 그 안의 세부 토글로 나뉘어요.

(/permissions 슬래시의 UI 라벨로는 Auto / Read-only / Full Access 로 노출되며, config.toml 의 approval_policy 키 값으로는 untrusted / on-request / never 가 매칭돼요.)

모드	의미
`untrusted`	거의 모든 작업을 사용자 확인 후에만 실행. 새 환경·낯선 코드에 가장 안전
`on-request`	위험 가능성이 있는 작업 (쓰기·외부 명령) 만 확인. 일반 작업 흐름의 기본값
`never`	묻지 않고 모두 진행. CI 파이프라인이나 비대화식 자동화에 적합

세부 토글(객체로 줄 수 있음): sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval. 예를 들어 "샌드박스 변경은 무조건 묻고, MCP 호출은 자동 통과" 같은 조합을 만들 수 있어요.

비유: 승인 모드는 출입문 종류 를 고르는 일에 가까워요. untrusted 는 매번 신분증을 보여주는 회전문, on-request 는 카드를 찍는 자동문, never 는 활짝 열린 문. 어떤 문이 적당한지는 그 방 안에서 무슨 일이 벌어지느냐에 따라 달라요.

4.3 샌드박스 모드(sandbox_mode) — Codex 의 결정적 안전장치

sandbox_mode 는 승인을 통과한 작업이 실제로 시스템에 어디까지 손댈 수 있는지 의 OS 레벨 한계를 정합니다.

모드	의미
`read-only`	모든 쓰기·외부 네트워크 차단. 코드 읽기·분석 전용
`workspace-write`	작업 디렉토리 트리 안만 쓰기 허용. 외부 디렉토리·시스템 위치 차단
`danger-full-access`	샌드박스 비활성. 시스템 전체 접근 가능 — CI · 컨테이너 안 같이 격리된 환경에서만 권장

Codex 는 이걸 OS 의 권한 시스템에 직접 위임 합니다 — macOS 에서는 Seatbelt(앱 단위 샌드박스 정책), Linux 에서는 Landlock(파일 시스템 액세스 제어 LSM) 을 사용해 커널 수준에서 차단해요. Claude Code 의 permissions.allow 가 하네스(애플리케이션) 수준 검열이라면, Codex 의 샌드박스는 OS 수준 격벽이라는 차이가 있습니다.

승인 vs 샌드박스 — 두 축의 조합:

approval_policy ＼ sandbox_mode	`read-only`	`workspace-write`	`full-access`
`untrusted`	safest (가장 안전)	safe (안전)	risky (위험)
`on-request`	annoying (성가심)	sweet spot (스윗 스팟)	typical (일반)
`never`	useless (무의미)	automation (자동화)	CI sandbox (CI 격리)

"스윗 스팟" 인 on-request + workspace-write 가 일상 개발의 기본 추천 조합이에요. CI 같은 비대화식 자동화는 never + workspace-write, 격리된 컨테이너 안이라면 never + danger-full-access 가 합리적이에요.

4.4 기능 플래그(`[features]`)

Codex 는 빠르게 변하는 기능들을 [features] 테이블의 토글로 관리합니다. 2026-05 기준 노출되는 플래그는 다음과 같아요.

플래그	켜면 활성화되는 것
`shell_tool`	셸 명령 도구
`multi_agent`	서브에이전트 병렬 실행 (현재 빌드는 기본 활성, 일부 빌드에서 토글로 노출)
`memories`	세션 간 지속 기억
`undo`	작업 되돌리기
`unified_exec`	통합 실행 인터페이스
`personality`	응답 톤 설정
`fast_mode`	빠른 응답 모드
`web_search`	웹 검색 도구

4.5 config.toml 샘플 (최소 + 일반 + CI)

C-1. 최소 구성

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

C-2. 일반 개발 (MCP 1개 + 기능 플래그)

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
shell_tool = true
memories = true
undo = true
web_search = true

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

C-3. CI · 비대화식 (`codex exec` 용)

model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "workspace-write"
service_tier = "fast"

4.6 Claude Code permissions 와의 비교

항목	Codex (`config.toml`)	Claude Code (`settings.json`)
형식	TOML	JSON
권한 차단 위치	OS 수준 (Seatbelt · Landlock)	하네스 수준 (allowlist 매칭)
차단 단위	디렉토리 트리 · 네트워크 (광역)	명령어 패턴 (`Bash(git status:*)` 등 세밀)
승인 모드	`approval_policy` (별도 키)	`permissions.defaultMode`
자동 트리거	`[hooks]` 테이블 / `hooks.json` (1급 시민, 6 이벤트)	`hooks` (1급 시민, 20여 이벤트)

거칠게 말하면: Codex 는 광역 차단 + 세밀 승인, Claude Code 는 세밀 차단 + 광역 승인 으로 비대칭입니다. 어느 쪽이 더 좋다기보다, 같은 안전 목표를 다른 추상 레벨에서 잡고 있어요.

Part C — 확장: 도구 · MCP · Skills · Plugins

평소엔 안 쓰지만 특정 작업에 꺼내 쓰는 전문가 모드. Skills · Plugins · MCP 가 이 자리에 모여 있고, Codex 는 이 셋을 비교적 깔끔하게 분리해 둡니다.

5. 동적 확장 축

5.1 내장 도구

기본 활성 상태에서 Codex 는 다음과 같은 내장 도구를 LLM 에 노출해요 ([features] 토글로 일부 끄고 켤 수 있음).

도구	역할
파일 읽기·쓰기	작업 트리 안 파일 편집 (`workspace-write` 이상에서 활성)
셸 실행	`shell_tool` 플래그 — 명령 실행
웹 검색	`web_search` 플래그 — 모드: `disabled` / `cached` / `live`
이미지 입력·생성	스크린샷 첨부, 인라인 이미지 생성
서브에이전트	`multi_agent` — 큰 작업을 여러 에이전트로 분기
코드 리뷰	`/review` — 작업 트리 또는 staged diff 분석

서브에이전트 메커니즘

본문 §4 서브에이전트(컨텍스트를 위임하라) 에서 다룬 위임 메커니즘이 Codex 에서는 [agents] TOML 테이블로 에이전트를 정의하고 /agent 슬래시 커맨드로 호출하는 형태로 굴러가요. 위임 도구로는 spawn_agents_on_csv 같은 게 등장하고, max_threads · max_depth · job_max_runtime_seconds 로 분기 깊이 / 동시성 / 시간 한도를 잡아요. 기본 활성 이라 별도 플래그 없이 즉시 사용 가능 — Claude Code 의 Task 도구와 같은 자리예요.

5.2 MCP 서버 연동

Codex 는 MCP(Model Context Protocol) 를 1급으로 지원합니다. config.toml 의 [mcp_servers.<이름>] 테이블에 등록하면 그 서버의 도구가 자동으로 LLM 에 노출돼요.

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

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

세션 안에서 /mcp 슬래시 커맨드로 현재 등록된 서버 · 노출된 도구 목록을 확인할 수 있고, MCP elicitation(서버가 사용자에게 추가 입력을 요청하는 흐름) 의 자동 통과 여부는 approval_policy.mcp_elicitations 토글로 제어합니다.

참고: MCP 서버 정의 형식은 Claude Code · Cursor · Codex 등 여러 도구가 거의 동일한 스키마(command/args/env)를 공유합니다 — 한 번 만든 서버를 여러 도구에서 같이 쓸 수 있는 이유.

5.3 Skills — Codex 에도 있다

Codex CLI 에는 Claude Code 와 거의 같은 형태의 Skills 시스템이 있습니다. 둘 다 "open agent skills standard" 위에 얹혀 있어서 디렉토리 구조와 파일명이 거의 호환됩니다.

저장 위치 (검색 우선순위)

스코프	경로	용도
작업 디렉토리	`<cwd>/.agents/skills/`	폴더 한정 워크플로
리포지토리 루트	`<repo-root>/.agents/skills/`	리포 전체 공통
사용자	`$HOME/.agents/skills/`	개인 스킬 (모든 리포 공용)
시스템/관리자	`/etc/codex/skills/`	머신 단위 기본값

최소 구조

my-skill/
+-- SKILL.md          (required: name, description; body acts as instructions)
+-- scripts/          (optional: executable code)
+-- references/       (optional: documentation)
+-- assets/           (optional: templates)
+-- agents/openai.yaml (optional: UI metadata)

호출 방식

명시적: 사용자가 /skills 로 목록을 보거나 $skillname 형태로 호출.
자동(implicit): Codex 가 작업 설명을 보고 매칭되는 스킬을 자동 선택.

컨텍스트 효율 — 깜짝 사실

Codex 는 세션 시작 시 모든 스킬의 이름 + description 만 컨텍스트에 올립니다. 공식 문서 기준 "전체 컨텍스트 윈도우의 약 2%, 또는 8000 자" 한도 안에서만 차지하고, 실제 SKILL.md 본문은 Codex 가 그 스킬을 선택했을 때만 로드돼요. 그래서 스킬을 수십 개 등록해도 평소 정적 레이어가 폭주하지 않습니다 — Claude Code 의 Skills 와 같은 지연 로딩 패턴이에요.

5.4 Plugins — Skills 의 배포 단위

Plugins 는 Skills + MCP 설정 + UI 자산을 한 패키지로 묶은 배포 단위 입니다. 한 명이 만든 워크플로를 팀에 뿌릴 때 쓰는 그릇이라고 보면 돼요.

세션 안에서 /plugins 로 설치된 · 설치 가능한 플러그인 목록 확인.
한 플러그인 안에 여러 스킬 · 여러 MCP 서버 정의가 함께 묶일 수 있음.

5.5 슬래시 커맨드

세션 안에서 직접 호출하는 명령들. 자주 쓰는 것 위주로 정리하면:

표가 길어 보이지만 실전에서 자주 쓰는 건 위 12개 정도예요 — /init · /model · /permissions · /plan · /review · /compact · /clear · /new · /fork · /resume · /status · /exit. 나머지는 사전처럼.

커맨드	역할
`/init`	현재 디렉토리에 `AGENTS.md` 스캐폴드 생성
`/permissions`	묻지 않고 허용할 작업 범위 설정
`/sandbox-add-read-dir`	샌드박스에 추가 읽기 권한 부여
`/model`	활성 모델 + reasoning effort 변경
`/fast`	Fast 모드 토글 (지원 모델 한정)
`/personality`	응답 톤 변경
`/plan`	플랜 모드 진입
`/review`	작업 트리/diff 리뷰 요청
`/diff`	미트래킹 포함 git diff 표시
`/compact`	대화를 요약해 토큰 확보
`/clear`	터미널 초기화 + 새 채팅
`/new`	같은 세션 안에서 새 대화 시작
`/fork`	현재 대화를 새 스레드로 분기
`/side`	일회용 사이드 대화
`/resume`	저장된 대화 재개
`/agent`	활성 에이전트 스레드 전환
`/mcp`	등록된 MCP 도구 목록
`/plugins`	플러그인 목록
`/apps`	앱·커넥터 삽입
`/mention`	파일 첨부
`/skills`	사용 가능한 스킬 목록·호출
`/hooks`	등록된 라이프사이클 hook 목록·토글 (v0.129.0~)
`/memories`	메모리 주입·생성 제어
`/ps` `/stop`	백그라운드 터미널 관리
`/status`	세션 설정·토큰 사용량
`/statusline` `/title` `/keymap`	TUI 커스터마이징
`/feedback`	로그를 메인테이너에게 전송
`/logout` `/exit` `/quit`	종료·로그아웃

호출 흐름 한 장: /init 으로 AGENTS.md 골격 → /model 로 모델 선택 → /permissions 로 자주 쓰는 명령 자동 통과 → 작업 시작 → 도중에 /plan 또는 /review 로 시점 제어 → /compact 로 컨텍스트 정리 → /resume 으로 다음 세션에 복귀.

5.5.1 계획 모드 (`/plan`)

본문 §7 작업 워크플로우 에서 다룬 계획 모드는 Codex 에서 /plan 슬래시 커맨드 또는 작업 시작 시 자동 제안되는 플랜으로 진입해요. 코드 수정 전에 텍스트로 계획만 제안하는 모드 — Claude Code 의 Plan Mode (Shift+Tab) 와 동등.

5.6 비대화식 모드 — `codex exec`

Codex 는 Claude Code 와 마찬가지로 비대화식 실행도 지원합니다. codex exec "<prompt>" 형태로 호출하면 한 번 응답을 받고 종료해요. CI · 스크립트 · cron 자동화에 어울리고, 이때는 approval_policy = "never" + 적절한 sandbox_mode 조합이 일반적.

6. Claude Code vs Codex CLI 정량 비교

같은 카테고리 두 도구를 한 표에 펼치면 다음과 같습니다. 이 표만 봐도 양쪽의 설계 철학 차이가 한눈에 들어와요.

항목	Claude Code	Codex CLI
제작	Anthropic	OpenAI
본체 언어	Node.js / TypeScript	Rust
설치	`npm` · 공식 설치 스크립트	`npm install -g @openai/codex` · `brew install --cask codex` · GitHub Releases
주 모델	Claude (Opus / Sonnet / Haiku)	OpenAI (GPT-5 계열, o-시리즈)
정적 지침 파일	`CLAUDE.md` (전역 `~/.claude/CLAUDE.md`, 프로젝트, 하위 폴더)	`AGENTS.md` (전역 `~/.codex/AGENTS.md`, 프로젝트, 하위 폴더)
환경 설정 파일	`~/.claude/settings.json` (JSON)	`~/.codex/config.toml` (TOML)
권한 모델	하네스 수준 allowlist (`Bash(git status:*)`)	OS 수준 샌드박스 (Seatbelt / Landlock) + `approval_policy`
자동 트리거 (Hook)	1급 시민. 20여 이벤트 (`PreToolUse` `PostToolUse` 등)	1급 시민 (v0.129.0~). 6 이벤트 (`SessionStart` · `PreToolUse` · `PermissionRequest` · `PostToolUse` · `UserPromptSubmit` · `Stop`)
승인 단계	`permissions.defaultMode`	`approval_policy`: `untrusted` / `on-request` / `never` (+ 세부 토글)
샌드박스 단계	(별도 OS 샌드박스 키 없음)	`sandbox_mode`: `read-only` / `workspace-write` / `danger-full-access`
MCP 지원	1급 시민 (`settings.json` 의 `mcpServers`)	1급 시민 (`config.toml` 의 `[mcp_servers]`)
Skills	1급 시민 (`~/.claude/skills/`, `<proj>/.claude/skills/`, plugin marketplace)	1급 시민 (`~/.agents/skills/`, `<repo>/.agents/skills/`, `/etc/codex/skills`) — open agent skills standard
Plugins	Skills + Hooks + MCP 묶음	Skills + MCP + UI 자산 묶음
슬래시 커맨드	자주 쓰는 워크플로 + Skill 호출	약 48종 (`/init` `/model` `/plan` `/review` `/hooks` 등)
비대화식 실행	`claude -p "<prompt>"`	`codex exec "<prompt>"`
인증	Anthropic API 키 또는 Claude.ai 계정	OpenAI API 키 또는 ChatGPT 로그인
추론 강도 조절	thinking effort (모델별)	`model_reasoning_effort`: `minimal` ~ `xhigh`
컨텍스트 한도	모델별 (Claude 4.x 계열 200K~1M)	모델별 (`model_context_window` 로 명시)
응답 톤 설정	(CLAUDE.md 안 텍스트 지시로)	`personality` 키 (`none` / `friendly` / `pragmatic`)
대화 분기	Skills + 별도 세션	`/fork` `/side` `/resume` 슬래시 커맨드
가격	Claude 구독 또는 API 종량제	ChatGPT 구독 (Plus/Pro/Business/Edu/Enterprise) 또는 API 종량제

6.1 어느 쪽을 골라야 할까

표만으로는 답이 안 나옵니다. 실무에서 갈리는 지점은 보통 다음 셋이에요.

사용 중인 LLM 생태계: 이미 ChatGPT 구독을 쓰고 있다면 Codex 가 가성비, Claude 구독을 쓰고 있다면 Claude Code 가 자연스러움.
자동화의 결정성을 어디서 잡을 것인가: 위험 명령 차단·자동 린터 같은 결정적 자동화는 양쪽 다 Hooks 로 가능하지만 이벤트 수가 다릅니다 — 20여 이벤트로 잘게 끼어들고 싶으면 Claude Code 가, 6 이벤트로 충분하고 OS 수준 격벽 광역 차단을 같이 깔고 싶으면 Codex 의 샌드박스+Hooks 조합이 자연스러워요.
권한의 세밀도: 명령어 패턴 단위로 잘게 통과·차단하고 싶으면 Claude Code, 디렉토리 트리·네트워크 단위로 광역 통제하고 싶으면 Codex.

한 줄 결론: 두 도구는 승패가 아니라 추상 레벨이 다른 동등한 사례 입니다. 한쪽 감각으로 다른 쪽을 다루지 말고, 위 표의 대응관계를 머릿속에 두고 옮겨 쓰면 되어요.

7. 실전 팁 모음

원칙은 §3~§5 에서 다 나왔지만, 실제로 키보드 앞에서 흔들리는 지점은 따로 있어요. 그 지점만 따로 뽑아뒀어요.

AGENTS.md 작성 요령

"하지 마" 보다 "이렇게 해" — 금지형보다 지시형이 LLM 에 더 잘 먹힙니다.
구체적·짧게 — "친절하게 응답" 같은 추상 지시는 효과가 낮아요. "코드 블록 앞에 한 줄 요약" 같이 구체적으로.
예시를 같이 주기 — 원하는 출력 형식은 짧은 샘플을 함께 넣으세요.
project_doc_max_bytes 를 의식 — 큰 자료는 AGENTS.md 에 직접 적지 말고 트리거 라인 + 별도 파일로 빼세요.
임시방편 규칙 금지 — "만약 X 에러가 나면 무시해" 같은 예외를 누적하면 LLM 이 모순된 지침 사이에서 환각을 일으킵니다. 근본 원인을 고치세요.

config.toml 작성 요령

승인과 샌드박스를 분리해서 사고 — approval_policy 는 "물어볼지", sandbox_mode 는 "할 수 있는지". 두 축을 별개로 결정하세요.
CI 환경엔 별도 프로필 — profile 키로 일상용·CI용을 분리해 두면 환경 전환이 안전합니다.
approval_policy = "never" + sandbox_mode = "danger-full-access" 조합은 컨테이너·VM 안에서만.
민감 정보는 env 파일로 — [mcp_servers.X.env] 에 토큰을 직접 적지 말고 환경 변수 참조 또는 외부 파일을 거치세요.

Skill 작성 요령

description 을 트리거 지향으로 — "이런 상황·이런 키워드가 나오면 이 스킬을 써라" 를 한 줄에 담습니다.
부작용이 큰 스킬은 명시적 호출만 — 배포·커밋·알림 전송처럼 잘못 호출되면 곤란한 작업은 description 에 "사용자 명시 호출 시에만" 같이 못 박아 두세요.
본문은 짧게, 나머지는 부속 파일로 — references/ 와 scripts/ 를 활용해서 SKILL.md 자체는 짧게 유지.

세션 간 인수인계

임시 상태는 별도 인수인계 파일 — 오늘 작업 진행도, 미해결 이슈, 다음 단계는 AGENTS.md 가 아닌 CONTINUE.md 같은 파일로.
영속 지식은 AGENTS.md — 아키텍처, 기술 스택, 규칙.
memories 플래그가 켜져 있으면 자동 학습 메모도 별도 영역에서 누적 — 너무 신뢰하진 말고, 핵심 사실은 AGENTS.md 에 못 박아 두세요.

8. 부록

A. 디렉토리 트리 템플릿

자기 환경에 맞게 "프로젝트" 이름과 "리포 루트" 를 치환해서 쓰면 됩니다.

~/.codex/
+-- AGENTS.md                  <- Global guidance
+-- config.toml                <- Global config (model, sandbox, MCP)
+-- log/                       <- Session logs (managed by Codex)

~/.agents/
+-- skills/                    <- Personal cross-repo skills
    +-- my-skill/
        +-- SKILL.md
        +-- scripts/
        +-- references/

<repo-root>/
+-- AGENTS.md                  <- Repo-wide rules
+-- .codex/
|   +-- config.toml            <- Project-scoped overrides
+-- .agents/
    +-- skills/                <- Repo-local skills
        +-- repo-skill/
            +-- SKILL.md

B. 용어 사전

용어	설명
AGENTS.md	Codex CLI 가 세션 시작 시 자동 주입하는 정적 지침 파일. 전역 + 프로젝트 + 하위 폴더 계층.
config.toml	Codex 의 환경 설정 파일. `~/.codex/config.toml` (전역), `<repo>/.codex/config.toml` (프로젝트).
approval_policy	"사용자에게 물어볼지" 의 정책. `untrusted` / `on-request` / `never`.
sandbox_mode	"OS 수준에서 어디까지 손댈 수 있는지" 의 정책. `read-only` / `workspace-write` / `danger-full-access`.
Seatbelt	macOS 의 앱 단위 샌드박스 정책 시스템. Codex 가 macOS 에서 샌드박스를 구현하는 기반.
Landlock	Linux 커널의 액세스 제어 LSM. Codex 가 Linux 에서 샌드박스를 구현하는 기반.
Skill	`~/.agents/skills/<name>/SKILL.md` 형태로 정의되는 특화 워크플로.
Plugin	Skills + MCP 설정 + UI 자산을 한 패키지로 묶은 배포 단위.
MCP (Model Context Protocol)	외부 시스템과 LLM 을 연결하는 표준 프로토콜. Codex · Claude Code 등이 공유.
codex exec	비대화식 실행 모드. CI · 스크립트용.
child_agents_md	하위 디렉토리의 `AGENTS.md` 를 추가 로딩하는 기능 플래그.

C. 자주 쓰는 슬래시 커맨드 한 장 요약

Initialize        :  /init
Model & tone      :  /model    /personality   /fast
Permissions       :  /permissions    /sandbox-add-read-dir
Plan & review     :  /plan     /review        /diff
Context hygiene   :  /compact  /clear         /new
Branching         :  /fork     /side          /resume
Extensions        :  /mcp      /plugins       /skills
Status            :  /status   /ps            /stop
Exit              :  /quit     /exit          /logout

D. AGENTS.md 시작 골격 (복사·변형용)

# <Project Name>

## Stack
- Backend: <runtime + framework>
- Frontend: <framework>
- DB: <engine + version>

## Build & Run
- Dev: `<command>`
- Test: `<command>`
- Build: `<command>`

## Layout
- `src/...`
- `tests/...`
- `docs/...`

## Rules
- <one rule per line, imperative form>
- <next rule>

## Triggers
- For migration work, read `docs/migration-protocol.md` first.
- For security review, read `docs/security-checklist.md` first.

마무리

Codex CLI 의 3축을 한 줄로 다시 정리합니다.

AGENTS.md 는 "항상 깔리는 배경 규칙", config.toml + 샌드박스 는 "어디까지 손댈 수 있는지의 환경 계약", Skills · Plugins · MCP 는 "필요할 때 꺼내는 전문가 모드"

좋은 Codex 설정도, 좋은 Claude Code 설정과 같은 원리로 굴러갑니다 — 정적 지침 · 환경 계약 · 동적 확장 셋을 역할에 맞게 분배 하는 것. 모든 것을 AGENTS.md 에 욱여넣으면 정적 레이어가 비대해지고, 모든 것을 config.toml 의 권한 토글로 풀어놓으면 안전 가정이 무너지며, 모든 것을 Skill 로 만들면 호출 시점이 분산돼서 매번 찾아 헤매게 돼요.

내 작업 흐름에서 무엇이 "항상" 이고, 무엇이 "환경 계약" 이고, 무엇이 "가끔" 인지 — 이 질문에 답할 수 있으면 Codex 든 Claude Code 든 같은 감각으로 다룰 수 있습니다.

다음 화 예고 — 어떤 도구가 더 맞는가

Claude Code 와 Codex CLI 둘 중 무엇을 골라야 하는가는 사실 도구의 능력이 아니라 자기 작업 패턴 의 문제입니다. 위험 명령 차단을 코드로 잘게 짜고 싶다면 20여 이벤트의 Hooks 를 쓰는 Claude Code 가, OS 수준 광역 격벽 + 6 이벤트 Hooks 조합으로 잡고 싶다면 샌드박스가 1급인 Codex 가 어울립니다. 두 도구를 같이 쓰는 것도 가능 — AGENTS.md 와 CLAUDE.md 는 거의 같은 양식이라, 한 번 잘 만든 정적 지침을 양쪽에 동시에 두고 가는 흐름이 사내 환경에서 의외로 자주 보입니다.

같은 LLM·같은 카테고리 도구라도 — 3축이 어떻게 채워졌느냐 가 에이전트의 실질 능력을 거의 결정합니다. 모델 업그레이드보다 설정 정교화가 먼저 나오는 이유가 여기 있어요. 본문 §5 하네스가 체급을 이긴다 와도 같은 이야기입니다.