Codex CLI: 완벽한 기술 레퍼런스

요약: Codex는 여러 환경에서 작동하는 코딩 에이전트입니다. 코드베이스를 읽고, 운영체제 수준의 샌드박스에서 명령을 실행하고, 파일을 패치하고, 작업을 클라우드에 위임합니다. config.toml, 샌드박스 및 승인 모델, AGENTS.md, MCP, skills라는 5가지 시스템을 익히면 생산성을 크게 높일 수 있습니다. 기본 모델로는 GPT-5.6 Sol을 권장합니다(“Power” 설정, 중간 수준 추론). 이전 세대 플래그십 모델인 GPT-5.5는 Codex에서 400K, API에서 1M 컨텍스트를 제공합니다.⁸³¹¹⁷ 처음 사용하시나요? 바로 설치와 빠른 시작으로 이동하세요. 릴리스를 확인하고 계신가요? 최신 안정 버전은 v0.147.0(2026년 8월 7일)입니다. 최근 버전의 주요 변화는 릴리스 주요 내용에서, 모든 업데이트는 변경 기록에서 확인하세요.¹¹⁶

Codex는 코드를 작성하는 챗봇이 아니라 여러 환경에서 작동하는 코딩 에이전트입니다. CLI는 코드베이스를 읽고, 샌드박스에서 명령을 실행하고, 파일을 패치하고, MCP를 통해 외부 서비스에 연결하고, 장시간 실행되는 작업을 클라우드에 위임합니다. 로컬에서 실행되지만 전체 작업 환경을 아우르며 사고합니다. 동일한 지능이 작업 방식에 따라 5가지 환경에서 활용되며, 여기에는 브라우저를 대신 조작하지 않고도 브라우저 안에서 Codex를 실행하는 새로운 Chrome 확장 프로그램도 포함됩니다.⁹⁰

Codex를 가볍게 사용하는 것과 효과적으로 활용하는 것의 차이는 5가지 핵심 시스템을 얼마나 잘 다루느냐에 달려 있습니다. 이를 익히면 Codex로 생산성을 크게 높일 수 있습니다.

1. 설정 시스템: config.toml을 통해 동작을 제어합니다
2. 샌드박스 및 승인 모델: Codex가 수행할 수 있는 작업을 제한합니다
3. AGENTS.md: 프로젝트 수준의 운영 규칙을 정의합니다
4. MCP 프로토콜: 외부 서비스로 기능을 확장합니다
5. Skills 시스템: 재사용할 수 있는 분야별 전문 지식을 패키지로 구성합니다

저는 수개월 동안 프로덕션 코드베이스, CI/CD 파이프라인, 팀 워크플로 전반에서 Codex와 Claude Code를 함께 사용했습니다. 이 가이드에는 처음 시작할 때 있었으면 했던 완전한 참고 자료를 만들기 위해 그 경험을 집약했습니다. 모든 기능에 실제 구문과 실용적인 설정 예시를 담았으며, 숙련된 사용자도 놓치기 쉬운 예외 상황까지 다룹니다.

핵심 요점

• 5가지 환경, 하나의 두뇌: CLI, 데스크톱 앱, IDE 확장 프로그램, 클라우드 작업, 새로운 Chrome 확장 프로그램은 모두 동일한 GPT-5.x-Codex 지능을 공유하므로, 작업 흐름에 맞는 환경을 선택하세요.⁹⁰
• 운영체제 수준의 샌드박스: Codex는 컨테이너 내부가 아니라 커널 수준에서 파일 시스템과 네트워크 제한을 적용합니다(macOS에서는 Seatbelt, Linux에서는 Landlock + seccomp).
• AGENTS.md는 여러 도구에서 호환됩니다: 프로젝트 지침은 Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed와 60,000개 이상의 오픈 소스 프로젝트에서 작동합니다. 한 번 작성해 어디서나 사용하세요.
• 프로필로 작업 전환 부담을 줄일 수 있습니다: 이름이 지정된 설정 프리셋(fast, careful, auto)을 정의하고 --profile로 전환하세요.
• 컨텍스트 관리가 중요합니다: GPT-5.6 제품군(Sol, Terra, Luna)은 272K 컨텍스트 창을 사용하며, 이전 세대의 대표 모델인 GPT-5.5는 Codex에서 400K, API에서 1M을 제공합니다. /compact, 초점이 명확한 프롬프트, @file 참조를 활용해 토큰 예산을 미리 관리하세요.⁸³¹¹²

이 가이드 활용법

이 가이드는 3,300줄이 넘는 참고 자료입니다. 자신의 경험 수준에 맞는 부분부터 시작하세요.

마지막의 빠른 참조 카드에서는 모든 주요 명령을 한눈에 확인할 수 있습니다.

릴리스 주요 내용: 최근 변경 사항

Codex의 릴리스 흐름을 추적하는 독자를 위한 버전별 설명입니다. 처음 방문하셨다면 이 부분을 건너뛰고 빠른 시작을 살펴본 뒤 다시 돌아오세요. 생산적으로 활용하는 데 꼭 필요한 내용은 없습니다.

GPT-5.6 Sol은 Codex의 권장 기본 모델입니다. 기본값은 중간 수준 추론을 사용하는 “Power” 설정이며, Smarter 또는 Faster 쪽으로 조정할 수 있습니다. GPT-5.5(2026년 4월 23일: Codex에서 400K 컨텍스트, API에서 1M, MTok당 $5/$30, Terminal-Bench 2.0에서 82.7%로 SOTA)는 이전 세대의 대표 모델입니다.⁸³¹¹⁷ CLI v0.147.0(안정 버전, 2026년 8월 7일)부터 codex exec --full-auto가 제거되었습니다(v0.128부터 사용 중단 예정). 이제 이 옵션을 계속 전달하는 스크립트에서는 오류가 발생하므로, --sandbox workspace-write와 승인 플래그 또는 프로필의 조합으로 교체하세요. v0.147.0에는 승인 프롬프트를 자동 검토 단계에서 판정하는 --approve-for-me, 로컬, 개인, 작업 공간 및 원격 카탈로그를 모두 검색할 수 있는 이식 가능한 Agent Plugins, 페이지 단위 탐색, 여러 차례의 요청, 서버의 논블로킹 시작을 지원하는 선택형 MCP 2026-07-28 프로토콜, 긴 기록을 정리하는 대화 섹션도 포함되었습니다.¹¹⁶ v0.146.0(안정 버전, 7월 29일)에서는 설정된 프록시가 모든 전송 계층에 적용되도록 변경하고, Agent Plugins 매니페스트와 Amazon Bedrock 및 Claude Code 마켓플레이스, 스레드 고정을 지원하는 세션 이름 지정, 실행기가 제공하는 skills를 추가했습니다. v0.146.1(8월 5일)에서는 사이버 기능을 갖춘 모델의 자동 검토 기본값을 강화했습니다.¹¹⁴¹¹⁵ CLI v0.145.0(안정 버전, 2026년 7월 21일)부터 /import는 Claude Code뿐 아니라 Cursor에서도 이전을 지원합니다. 설정, MCP 서버, 플러그인, 세션, 명령, 프로젝트 범위 메모리를 이전할 수 있습니다. 음성 기능은 스트리밍 실시간 V3 대화로 돌아왔으며, 일반적인 로컬 형식의 오디오 입력과 오디오 도구 출력을 지원합니다. 선택형 멀티 에이전트 v2 환경은 안정화되었으며 하위 에이전트의 모델, 추론 수준, 동시 실행 수를 설정할 수 있습니다. 실험적인 페이지 단위 스레드 기록을 통해 효율적인 재개와 검색, 저장되는 이름, 하위 에이전트 지원, 메모리 기능을 사용할 수 있습니다. 실험적인 Amazon Bedrock 로그인에는 사용자 지정 엔드포인트와 인증 지원이 포함되며, GPT-5.6 Sol이 기본 Bedrock 모델로 사용됩니다. 번들 GPT-5.4 모델 선택 항목은 GPT-5.6 Terra 및 Luna 변형으로 이전되었습니다. v0.144.6(7월 18일)에서는 GPT-5.6 Sol/Terra/Luna의 컨텍스트 창을 272,000토큰으로 수정했습니다.¹¹¹¹¹² CLI v0.140.0(안정 버전, 2026년 6월 15일)부터 /usage에서 일간, 주간, 누적 계정 토큰 활동을 확인할 수 있고, codex delete 및 /delete로 세션을 영구 삭제할 수 있으며 확인 보호 절차가 적용됩니다. /import는 Claude Code의 설정, 프로젝트 구성, 최근 채팅을 선택적으로 이전하며, @를 입력하면 기본적으로 파일, 플러그인, skills를 아우르는 통합 멘션 메뉴가 열립니다. 관리형 Amazon Bedrock API 키 인증도 추가되었으며, CLI 및 MCP OAuth 자격 증명은 로컬에 암호화되어 저장됩니다. 실험적인 /realtime 음성 제어 기능은 TUI에서 제거되었습니다. 음성 기능은 이후 v0.145.0에서 스트리밍 실시간 V3로 돌아왔습니다.¹⁰²¹¹² CLI v0.139.0(안정 버전, 2026년 6월 9일)부터 코드 모드에서 독립형 웹 검색을 직접 호출할 수 있으며 중첩된 JavaScript 도구 호출에서도 사용할 수 있고, 결과는 일반 텍스트로 받을 수 있습니다. 이제 도구 및 커넥터 입력 스키마에서 oneOf/allOf 구문을 보존해 대규모 스키마 및 MCP 호환성을 높입니다. codex doctor에는 편집기와 페이저 환경 정보가 추가되며 JSON에서는 민감한 값이 가려집니다. 플러그인 마켓플레이스는 codex plugin marketplace list --json에서 소스를 표시하고, 캐시된 카탈로그 목록을 더 빠르게 불러옵니다.¹²² v0.138.0(6월 8일)에서는 macOS와 Windows에서 CLI 세션을 데스크톱 앱으로 넘기는 /app을 추가하고, 모델이 로컬 이미지 경로를 확인할 수 있도록 했으며, 추론 수준 선택의 유연성을 높이고, 플러그인 자동화에 구조화된 JSON 출력을 제공했습니다. 또한 멀티 에이전트 v2에서 상위 에이전트가 하위 에이전트에 전달하는 작업 텍스트를 암호화하기 시작해, 위임 지침이 더 이상 로컬 세션 로그에 일반 텍스트로 표시되지 않습니다(멀티 에이전트 항목 참조).¹²³¹⁰⁸ v0.137.0(6월 4일)에서는 멀티 에이전트 v2를 출시해 스레드별로 런타임을 유지하고, 후속 요청과 메타데이터 기본값을 정리했으며, hide_spawn_agent_metadata의 기본값을 true로 설정했습니다. F13~F24 TUI 키 바인딩과 턴마다 카탈로그를 확인하는 v1 skills 확장 기능도 추가되었습니다.¹²⁴ CLI v0.135.0(2026년 5월 28일)부터 codex doctor는 환경, Git, 터미널, 앱 서버, 스레드 목록을 더 자세히 보고합니다. TUI가 원격으로 연결된 경우 /status에 원격 연결 세부 정보와 서버 버전이 표시됩니다. vim 모드에는 텍스트 객체 편집, 개선된 단어 및 줄 끝 동작, 설정 가능한 턴 중단 기능이 추가되었습니다. 이제 /permissions는 이름이 지정된 권한 프로필을 인식하고 사용자 지정 프로필도 표시합니다. 패키징된 Codex 빌드는 지원되는 macOS에서 번들로 제공되는 패치된 zsh 도우미를 찾아 사용합니다. Python SDK는 스레드와 턴 API를 위한 이해하기 쉬운 Sandbox 프리셋을 제공합니다.¹²⁶ v0.134.0(2026년 5월 26일)에서는 대소문자를 구분하지 않는 콘텐츠 일치와 결과 미리 보기를 지원하는 로컬 대화 기록 검색을 도입했습니다. CLI, TUI 권한, 샌드박스 흐름 전반에서 --profile을 기본 프로필 선택 옵션으로 지정했으며, 기존 프로필 설정은 이전 안내와 함께 거부됩니다. 서버별 환경 대상 지정과 스트리밍 가능한 HTTP 서버의 OAuth 옵션을 통해 MCP 설정을 개선했습니다. 로컬 $ref/$defs를 보존하고 지나치게 큰 스키마를 압축해 커넥터 도구 스키마의 안정성을 높였습니다. 읽기 전용 MCP 도구가 readOnlyHint를 알리면 동시에 실행할 수 있도록 했습니다. 확장 도구에 대화 기록을 제공하는 등 확장 기능과 hooks의 컨텍스트도 더 풍부해졌습니다.¹⁰¹ v0.133.0(2026년 5월 21일)에서는 전용 저장소와 진행 상황 추적 기능을 갖춘 목표 기능을 기본으로 활성화했습니다. codex remote-control에는 포그라운드 준비 상태 및 상태 표시와 데몬 방식의 시작 및 중지 기능이 추가되었습니다. 권한 프로필에는 목록 API, 상속, 관리형 requirements.toml, 런타임 새로 고침, 강화된 Windows 샌드박스 통합이 추가되었습니다. 플러그인 탐색에서는 설치된 버전, 마켓플레이스 루트, 원격 컬렉션을 표시합니다. 확장 기능은 하위 에이전트 시작 및 중지, 도구 실행, 턴 메타데이터, 비동기 승인 및 턴 처리를 관찰할 수 있습니다. 5월 21일 Codex 앱 업데이트에서는 맨 앞에 열린 Mac 창을 위한 Appshots, 앱, IDE, CLI 전반에서 정식 출시된 Goal mode, 개선된 앱 내 브라우저 주석 기능, 대상 Mac 사용자를 위한 선택형 잠금 Computer Use 기능을 추가했습니다.⁹⁹¹⁰⁰ v0.132.0(2026년 5월 20일)에서는 Python SDK의 정식 인증, 더 단순한 텍스트 전용 턴 API, 더 풍부한 TurnResult, codex exec resume --output-schema, 더 빠른 TUI 시작, 인증 기반 원격 실행기 등록, 앱 서버 턴의 이미지 품질 보존을 추가했습니다. 명시적인 샌드박스 및 승인 플래그나 권한 프로필을 사용하세요. 기존 --full-auto는 v0.147.0부터 제거되었으며, js_repl도 계속 제거된 상태입니다.^{86878991969798116}

안정성 참고 사항: [EXPERIMENTAL] 또는 under development로 표시된 기능은 릴리스 사이에 변경될 수 있습니다. v0.133.0(2026년 5월 21일)부터 목표 기능은 기본으로 활성화되고, 권한 프로필은 정식 관리 환경이 되었으며, 플러그인 탐색 정보를 더 자세히 확인할 수 있고, remote-control은 포그라운드 또는 데몬화된 앱 서버 명령으로 더 쉽게 실행할 수 있습니다. Codex Cloud와 코드 모드는 계속 실험 단계이거나 개발 중입니다. 반면 핵심 CLI, 샌드박스, AGENTS.md, config.toml, Skills, hooks, 멀티 에이전트 도구, 플러그인, Browser, Computer Use, Appshots는 플랫폼과 요금제에 따라 안정적인 기능이거나 사용자 대상 기능으로 문서화되어 있습니다. v0.132.0에서는 Python SDK 인증과 구조화된 재개 자동화를 보완했습니다. v0.131.0에서는 codex doctor, 통합 @ 멘션 검색, 마켓플레이스 CLI 명령, 버전을 인식하는 플러그인 공유, 런타임 활성화 및 비활성화를 지원하는 데몬 관리형 remote-control, 레지스트리 기반 환경, 추가 Windows 샌드박스 강화 기능을 도입했습니다.⁹⁶⁹⁷⁹⁸ 기존 --full-auto는 v0.128부터 사용 중단 예정이었으며 v0.147.0에서 제거되었습니다. js_repl도 계속 제거된 상태입니다.^8687116

Codex 작동 방식: 멘탈 모델

기능을 살펴보기 전에 Codex의 아키텍처가 사용 방식 전반에 어떤 영향을 미치는지 이해해야 해요. 이 시스템은 공통 지능 계층을 기반으로 하는 5가지 인터페이스에서 작동해요.

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │  Chrome  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions             │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                             │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens         │
└─────────────────────────────────────────────────────────┘

핵심 계층: GPT-5.x 모델 제품군이 모든 기능을 구동해요. 2026년 8월 기준으로 gpt-5.6-sol이 권장 기본 모델이에요. 중간 수준의 추론을 사용하는 “Power” 설정이며, 일상적인 작업을 위한 Terra와 빠르고 저렴한 Luna도 함께 제공돼요. gpt-5.5는 이전 세대의 대표 모델로, Codex에서는 400K, API에서는 1M 컨텍스트를 지원해요. gpt-5.4는 2026년 8월 31일에 Codex에서 지원이 종료돼요.⁸³¹¹⁷ 이 계층은 파일을 읽고, 패치를 작성하고, 셸 명령을 실행하며, 코드베이스를 분석해요. 컨텍스트가 가득 차면 Codex는 공간을 확보하기 위해 대화를 압축해요. 이 계층에서는 토큰이 소모돼요.

보안 계층: Codex가 실행하는 모든 명령은 운영체제 수준의 sandbox를 거쳐요. macOS에서는 Apple의 Seatbelt 프레임워크가 커널 수준의 제한을 적용해요. Linux에서는 Landlock와 seccomp가 파일 시스템 및 시스템 호출 접근을 필터링해요. sandbox는 컨테이너 내부가 아니라 커널 수준에서 작동해요. 그다음 approval policy가 언제 사용자에게 확인을 요청할지 결정해요.

확장 계층: MCP는 외부 서비스(GitHub, Figma, Sentry)를 연결해요. skills는 Codex가 필요할 때 불러오는 재사용 가능한 워크플로를 패키지로 제공해요. Apps는 ChatGPT 커넥터에 연결해요. 웹 검색은 인터넷에서 실시간 컨텍스트를 추가해요.

인터페이스 계층: CLI는 터미널 고급 사용자와 자동화를 위한 인터페이스예요. Desktop app은 여러 스레드로 프로젝트를 관리할 때 사용해요. IDE 확장 기능은 편집, 컴파일, 테스트를 반복하는 작업에 적합해요. Cloud에서는 독립적으로 실행되는 비동기 작업을 처리해요.

핵심 요점: 대부분의 사용자는 한 가지 인터페이스만 사용해요. 고급 사용자는 5가지를 모두 활용해요. 오래 실행되는 작업에는 Cloud, 예측 가능한 저장소 작업에는 CLI, 빠르게 반복하는 코딩 작업에는 IDE 확장 기능, 계획과 조율에는 Desktop app, 로그인된 브라우저 작업에는 Chrome을 사용해요.

목차

1. Codex는 어떻게 설치하나요?
2. 빠른 시작: 첫 번째 세션
3. 핵심 상호작용 인터페이스
4. 설정 시스템 자세히 알아보기
5. 어떤 모델을 선택해야 하나요?
6. Codex의 비용은 얼마인가요?
7. 의사 결정 프레임워크
8. Sandbox와 승인 시스템은 어떻게 작동하나요?
9. AGENTS.md는 어떻게 작동하나요?
10. Hooks
11. MCP(Model Context Protocol)란 무엇인가요?
12. Code Mode
13. JavaScript REPL 런타임
14. Skills란 무엇인가요?
15. Plugins
16. Plan Mode와 협업
17. 메모리 시스템
18. 세션 관리
19. 비대화형 모드(codex exec)
20. Codex Cloud와 백그라운드 작업
21. Codex Desktop App
22. GitHub Action과 CI/CD
23. Codex SDK
24. 성능 최적화
25. 문제는 어떻게 디버깅하나요? – codex doctor 포함
26. 기업 배포
27. 모범 사례와 피해야 할 패턴
28. 워크플로 활용법
29. 마이그레이션 가이드
30. 빠른 참조 카드
31. 변경 내역
32. 참고 자료

Codex는 어떻게 설치하나요?

패키지 관리자

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

Codex CLI을 업데이트하거나 다운그레이드하거나 제거하려면 어떻게 하나요?

Codex는 v0.128.0부터 자체 업데이트 명령을 제공하며, 그 밖의 작업은 Codex를 설치한 패키지 관리자를 통해 진행해요.⁸⁶ v0.146.0부터 릴리스 아티팩트, 채널 메타데이터, 설치 프로그램 별칭은 OpenAI가 호스팅하는 릴리스 인프라에서 제공되며, GitHub은 대체 경로로 사용돼요.¹¹⁴ 네트워크에서 Codex 설치 및 업데이트를 위해 GitHub을 허용 목록에 등록했다면 OpenAI 릴리스 호스트도 추가하세요. 대체 경로가 있으므로 허용 목록에서 누락되더라도 명확한 오류 없이 조용히 성능이 저하될 수 있어요.

# Check what you are running
codex --version                          # -> codex-cli 0.147.0
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

릴리스로 인해 문제가 발생했다면 버전을 고정하는 것이 올바른 방법이에요. Codex의 안정 버전은 빠르게 갱신되므로 정확한 버전을 설치하는 것이 가장 빠른 롤백 방법이에요. 문제를 보고하고 버전을 고정한 다음 계속 진행하세요. PATH에 가려진 두 번째 설치가 있으면 이전 바이너리가 계속 실행될 수 있으므로 codex --version으로 롤백이 적용되었는지 확인하세요. codex doctor는 Environment에서 바로 이 문제를 표시해요.

패키지를 제거해도 상태 데이터는 삭제되지 않아요. 인증, 설정, 세션 기록은 ~/.codex/에 저장돼요. 다시 설치할 때도 로그인과 기록을 유지하려면 그대로 두세요. 완전히 초기화해야 할 때만 삭제하세요. rm -rf ~/.codex를 실행하면 config.toml, auth.json과 저장된 모든 세션도 함께 삭제돼요.

직접 설치 스크립트(v0.106.0 이상)

macOS와 Linux에서는 GitHub 릴리스 자산으로 제공되는 한 줄짜리 설치 스크립트를 사용할 수 있어요.⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

스크립트는 플랫폼과 아키텍처를 자동으로 감지하고 올바른 바이너리를 다운로드한 다음 PATH에 배치해요.

바이너리 다운로드

npm이나 Homebrew를 사용할 수 없는 환경에서는 GitHub Releases¹에서 플랫폼별 바이너리를 다운로드하세요.

시스템 요구 사항

• macOS: Apple Silicon 또는 Intel(Seatbelt를 통한 전체 샌드박스 지원)
• Linux: x86_64 또는 arm64(Landlock + seccomp를 통한 샌드박스)
• Windows: 제한된 토큰을 사용하는 네이티브 샌드박스(v0.100.0에서 실험 기능을 벗어나 정식으로 전환됨). WSL도 지원해요.²

인증

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

인증 방법은 2가지예요.

1. ChatGPT 계정(권장): 기존 Plus, Pro, Team, Business, Edu 또는 Enterprise 구독으로 로그인하세요. 클라우드 작업을 비롯한 모든 기능을 사용할 수 있어요.
2. API 키: CODEX_API_KEY 환경 변수 또는 codex login --with-api-key로 설정하세요. 일부 기능(클라우드 스레드)은 사용하지 못할 수 있어요.

전문가 팁: config.toml의 cli_auth_credentials_store를 사용해 자격 증명 저장 방식을 설정할 수 있어요. 선택지는 file(기본값), keyring(운영 체제 키체인), auto(사용할 수 있으면 키체인, 그렇지 않으면 파일)예요.

Amazon Bedrock 로그인(v0.145.0, 실험 기능): Amazon Bedrock을 통해 모델에 접근하는 팀은 맞춤형 엔드포인트와 인증을 지원하는 실험적 로그인 방식을 사용할 수 있어요. 기존의 관리형 API 키 인증(v0.140.0 이상) 및 AWS 자격 증명 체인과 함께 제공돼요(Custom Model Providers 참고). 기본 Bedrock 모델은 GPT-5.6 Sol이에요.¹¹²

셸 자동 완성

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

설치 확인

codex --version
# codex-cli 0.147.0

빠른 시작: 첫 번째 세션

5분 안에 처음부터 실제 작업을 시작해 보세요.

1. 설치하고 인증하세요.

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. 프로젝트로 이동하세요.

cd ~/my-project                  # Any git repo works

3. Codex를 시작하세요.

codex

대화형 TUI가 표시돼요. Codex는 프로젝트 구조를 자동으로 읽어요.

4. 질문하세요.

> What does this project do? Summarize the architecture.

Codex는 주요 파일을 읽고 코드베이스를 설명해요. 이와 같은 질문은 아무것도 변경하지 않아요. Codex는 변경을 요청할 때만 파일을 수정하며, 먼저 승인을 요청해야 하는 시점은 샌드박스와 승인 정책에 따라 결정돼요.

5. 변경을 요청하세요.

> Add input validation to the login endpoint

Codex는 수정 사항을 diff로 제안해요. 검토한 뒤 y로 승인하거나 n으로 거부하세요.

6. slash command를 사용하세요.

> /plan Refactor the database layer to use connection pooling

Codex는 실행하지 않고 계획만 만들어요. 계획을 검토한 다음 승인하여 실행을 시작하세요.

7. 작업 내용을 확인하세요.

> /diff

Codex가 현재 세션에서 변경한 모든 내용을 확인하세요.

다음 단계: - 프로젝트 지침을 담은 AGENTS.md를 설정하세요(AGENTS.md는 어떻게 작동하나요? 참고). - 작업 흐름에 맞는 프로필을 설정하세요(프로필 참고). - 비대화형 자동화에 codex exec를 사용해 보세요(비대화형 모드 참고).

핵심 상호작용 환경

Codex는 동일한 지능을 기반으로 하는 5가지 인터페이스를 제공합니다. 각 환경은 서로 다른 작업 흐름에 최적화되어 있어요.

1. 대화형 CLI (터미널 UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

터미널 UI는 다음 요소로 구성된 전체 화면 애플리케이션이에요.

• 작성기: 프롬프트를 입력하고, @로 파일을 첨부하며, ! 접두사로 셸 명령어를 실행할 수 있어요
• 출력 창: 모델 응답, 도구 호출, 명령어 출력을 실시간으로 표시해요
• 상태 표시줄: 모델, 토큰 사용량, git 브랜치, 샌드박스 모드를 표시해요

주요 TUI 단축키:

상태 표시줄 변경 사항(v0.121.0): 기존의 상태 표시줄 컨텍스트 창 측정기가 컨텍스트 창이 얼마나 찼는지 보여 주는 컨텍스트 백분율 표시기로 바뀌었어요. 상태 표시줄을 분석하는 스크립트나 hooks가 있다면 이 형식 변경을 확인하세요.⁸² 새 버전이 나오면 Codex가 CLI 업데이트 알림도 표시해요.

TUI에서 사용할 수 있는 Slash commands:

작업 흐름 선택기 개편(v0.129.0): 새롭게 디자인된 선택기에서 재개와 분기 기능에 더 쉽게 접근할 수 있어요. 명령어나 모델 출력을 원문 그대로 복사해야 할 때 렌더링되지 않은 기록을 스크롤할 수 있는 새로운 원시 스크롤백 모드도 추가되었어요. 긴 디버깅 세션을 분류하거나 출력을 다른 도구로 전달할 때 유용해요.⁸⁹

통합 @ 멘션 메뉴(v0.140.0): 이제 작성기에 @를 입력하면 파일 전용 첨부 흐름 대신 파일, 플러그인, skills를 아우르는 단일 멘션 메뉴가 기본으로 열려요. 키 한 번으로 어떤 프로젝트 리소스든 참조할 수 있어요.¹⁰²

2. Codex Desktop App (macOS + Windows)

codex app                    # Launch desktop app (auto-installs if missing)

데스크톱 앱에는 CLI에 없는 다음 기능이 추가돼요.

• 다중 작업: 서로 다른 프로젝트에서 여러 병렬 에이전트를 동시에 실행할 수 있어요
• Git worktree 격리: 각 스레드는 저장소의 격리된 복사본에서 작업해요
• 인라인 diff 검토: 앱을 벗어나지 않고 변경 사항을 스테이징하고, 되돌리고, 커밋할 수 있어요
• 통합 터미널: 명령어를 실행할 수 있는 스레드별 터미널을 제공해요
• 대화 분기: 대화를 분기해 다른 접근 방식을 탐색할 수 있어요
• 플로팅 팝아웃 창: 대화를 분리해 이동 가능한 창으로 열 수 있어요
• 자동화: 반복 작업을 예약할 수 있어요(문제 분류, CI 모니터링, 알림 대응)
• Appshots: 화면 맨 앞에 있는 Mac 앱 창의 스크린샷과 사용 가능한 텍스트를 스레드에 첨부할 수 있어요
• 앱 내 브라우저 댓글: 로컬 또는 공개 페이지를 미리 보고, 요소나 영역에 댓글을 남기며, Codex가 구체적인 시각적 피드백을 반영하도록 할 수 있어요
• Computer Use: 범위가 정해진 GUI 작업에서 Codex가 허용된 Mac 앱을 조작하도록 할 수 있어요. 잠금 상태에서의 사용은 자격이 있는 원격 Mac Computer Use 차례에서 선택적으로 활성화해야 해요

GPT-Live 기반 ChatGPT 음성 기능(데스크톱 26.715, 2026년 7월 23일): 이제 음성으로 데스크톱 앱을 조작할 수 있어요. 입력하지 않고 말로 작업을 진행하며 Chat, Work, Codex 전반의 작업을 조율할 수 있어요. macOS에서 화면 컨텍스트를 켜면 화면 맨 앞에 있는 창의 appshot이 대화에 공유되므로, 보고 있는 내용을 직접 설명하지 않고 질문할 수 있어요. Plus, Pro, Business, Edu, Enterprise에서 이용할 수 있으며, 데스크톱 앱과 iOS의 Remote를 통해 제공돼요. 이는 데스크톱 환경의 음성 기능이며, CLI 자체의 스페이스바 음성 받아쓰기 기능은 별도의 실험적 기능이에요.¹¹³

앱과 CLI의 사용 시점: 여러 작업 흐름을 조율하거나 시각적인 diff 검토가 필요하면 데스크톱 앱을 사용하세요. 터미널 조합성, 스크립팅, CI/CD 통합이 필요하면 CLI를 사용하세요.

3. IDE 확장 프로그램 (VS Code, Cursor, Windsurf)

Codex IDE 확장 프로그램은 편집기에 직접 통합돼요.

• 기본 에이전트 모드: 파일을 읽고, 편집하고, 명령어를 실행해요
• 인라인 편집: 현재 활성화된 파일에서 컨텍스트를 고려한 제안을 제공해요
• 공유 세션: CLI와 IDE 확장 프로그램 사이에서 세션이 동기화돼요
• 동일한 인증: ChatGPT 계정 또는 API 키로 로그인할 수 있어요

VS Code Marketplace 또는 Cursor/Windsurf 확장 프로그램 스토어에서 설치하세요.³

4. Codex Cloud [EXPERIMENTAL]

클라우드 작업은 OpenAI가 관리하는 환경에서 비동기식으로 실행돼요.

• 실행 후 맡겨 두기: 로컬 컴퓨터와 독립적으로 실행되는 작업을 대기열에 추가할 수 있어요
• 병렬 실행: 여러 클라우드 작업을 동시에 실행할 수 있어요
• PR 생성: Codex가 완료된 작업에서 pull request를 생성해요
• 로컬 적용: codex apply <TASK_ID>로 클라우드 결과를 로컬 저장소에 가져올 수 있어요

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

chatgpt.com/codex에서도 클라우드 작업에 접근할 수 있어요.⁴

5. Chrome용 Codex [NEW]

Codex는 Chrome 브라우저 확장 프로그램으로도 제공되며, CLI, 데스크톱 앱, IDE 확장 프로그램, 클라우드에 이어 5번째 환경을 제공해요. 이 확장 프로그램은 평소의 브라우징을 장악하지 않고 곁에서 함께 작동하도록 설계되었어요. Codex는 백그라운드에서 여러 탭에 걸쳐 병렬로 작업하며, 어떤 사이트에 접근할지는 사용자가 직접 제어해요.⁹⁰

• 병렬 탭 실행: Codex는 전면 탭을 잠그지 않고 여러 탭에서 동시에 작업해요.
• 사이트별 제어: Codex가 상호작용할 수 있는 웹사이트를 허용 목록에 추가할 수 있으며, 기본값은 접근 권한 없음이에요.
• 작업대로 활용하는 브라우저: 이 확장 프로그램은 관리 콘솔, 내부 대시보드, 콘텐츠 관리 UI, 티켓 시스템처럼 페이지가 기준 정보가 되는 앱과 웹사이트 작업에 적합해요. 로컬 저장소에서 사용하는 CLI를 대체하지는 않아요.
• 동일한 지능: Chrome용 Codex는 다른 환경과 동일한 GPT-5.x-Codex 지능을 사용하므로, CLI에서 작동하는 AGENTS.md 또는 skills 구성을 브라우저 기반 작업에도 같은 규칙으로 적용할 수 있어요.

Codex Chrome 확장 프로그램 문서에서 설치하세요.⁹⁰

구성 시스템 자세히 알아보기

Codex는 구성에 TOML을 사용해요. 우선순위 계층을 이해해야 설정이 충돌할 때 어떤 설정이 적용되는지 알 수 있어요.

우선순위 (높은 순서부터 낮은 순서까지)

1. 세션 재정의 (가장 높음): CLI 플래그 (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) 및 -c key=value 재정의
2. 프로젝트 구성 (.codex/config.toml, CWD에서 프로젝트 루트까지 상위 디렉터리를 탐색해 찾으며 가장 가까운 디렉터리의 구성이 적용됨)
3. 사용자 구성 ($CODEX_HOME/config.toml, 기본값은 ~/.codex/config.toml)
4. 시스템 구성 (Unix에서는 /etc/codex/config.toml)
5. 기본 제공 설정 (가장 낮음)

requirements.toml은 일반적인 구성 병합이 끝난 후 사용자가 선택할 수 있는 값을 제한하는 정책 제약 계층으로 작동해요. 기업 배포를 참고하세요.

구성 파일 위치

전문가 팁: CODEX_HOME 환경 변수는 기본 ~/.codex 디렉터리를 재정의해요. CI/CD 또는 여러 계정을 사용하는 환경에 유용해요.

Desktop 여러 폴더 프로젝트 (26.715, 2026년 7월 23일): 이제 ChatGPT Desktop App의 로컬 프로젝트는 서로 관련된 여러 폴더로 구성할 수 있으며, 그중 하나를 기본 폴더로 지정할 수 있어요(프로젝트 메뉴 → 프로젝트 편집). config.toml 자동 탐색은 기본 폴더만을 대상으로 실행돼요. 보조 폴더에서도 파일을 검색하고 읽고 편집할 수 있지만, 해당 폴더의 구성은 반영되지 않아요. 보조 폴더에 있는 .codex/config.toml은 Codex가 읽을 수 있는 파일일 뿐, 불러오는 구성 파일은 아니에요. 이는 Desktop App의 프로젝트 범위 지정 방식이며 위 우선순위 규칙이 변경된 것은 아니에요. CLI는 여전히 현재 작업 디렉터리에서 상위 디렉터리로 이동하며 프로젝트 구성을 찾아요.¹¹³

전체 구성 레퍼런스

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.6-sol"                  # Recommended default (the "Power" setting)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Chrome extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed networking proxy (experimental)
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

프로필

서로 다른 작업 모드에 사용할 수 있는 이름이 지정된 구성 프리셋이에요.

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

프로필을 활성화하세요.

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

전문가 팁: 구성의 최상위에 profile = "fast"를 설정하면 기본 프로필로 사용할 수 있어요. 세션별로 재정의하려면 --profile을 사용하세요.

사용자 지정 모델 제공자

Azure, AWS Bedrock, 로컬 모델 또는 프록시 서비스에 연결할 수 있어요.

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

경고: chat/completions 유선 API (wire_api = "chat")는 OpenAI 호스팅 모델에서 지원 중단되었으며, OpenAI는 2026년 2월에 제거한다고 발표했어요.³⁴ 로컬 제공자(Ollama, LM Studio)는 이 형식을 계속 지원할 수 있어요. OpenAI 엔드포인트에는 대신 wire_api = "responses"를 사용하세요.

--oss 플래그를 사용해 로컬 모델을 실행하세요.

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

또는 구성에서 설정하세요.

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

인라인 구성 재정의

명령줄에서 원하는 구성 값을 재정의할 수 있어요.

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

어떤 Model을 선택해야 하나요?

사용 가능한 Model (2026년 8월)

GPT-5.5(2026년 4월 23일)는 출시 당시 복잡한 코딩, 컴퓨터 사용, 지식 작업, 연구 워크플로 등 대부분의 Codex 작업에 OpenAI가 권장한 Model이었습니다. 4월 23일부터 ChatGPT Plus / Pro / Business / Enterprise / Edu / Go 사용자는 Codex CLI / 웹 / 데스크톱에서 이용할 수 있었고, OpenAI API에서는 4월 24일부터 제공되었습니다. 컨텍스트 창은 Codex에서 400K, API에서 1M입니다. Codex는 구독 등급 전반에서 처리량과 비용의 균형을 맞추기 위해 컨텍스트 창을 400K로 제한하지만, API에서는 전체 1M을 제공합니다. 가격(API)은 MTok당 입력 $5 / 출력 $30로 GPT-5.4 요금의 2배입니다. OpenAI는 토큰 효율 개선을 반영한 실질 인상률이 약 20%라고 밝혔습니다. 벤치마크 결과는 Terminal-Bench 2.0 82.7%(공개 Model 가운데 현재 최고 기록), GDPval 84.9%(44개 직종), OSWorld-Verified 78.7%, Tau2-bench Telecom 98.0%(프롬프트 조정 없음)입니다. OpenAI는 출시 전에 GPT-5.5와 Codex를 내부적으로 활용해 서비스 인프라를 다시 작성했으며, 그 결과 토큰 생성 속도가 20% 향상되었습니다.⁸³

GPT-5.4와 GPT-5.4 mini는 2026년 8월 31일에 Codex에서 지원 종료됩니다.¹¹⁷ 그전까지는 모든 Codex 환경에서 GPT-5.4를 선택할 수 있습니다.⁶⁴ 정확한 Model 목록은 계정과 배포 상태에 따라 달라집니다. 로컬 캐시 ~/.codex/models_cache.json을 확인하세요.

지원 중단 안내(2026년 3월 11일): GPT-5.1 Model은 더 이상 ChatGPT에서 사용할 수 없습니다. 기존 대화는 GPT-5.3 Instant, GPT-5.4 Thinking 또는 GPT-5.4 Pro에서 자동으로 이어집니다. GPT-5.1-Codex-Mini는 2026년 7월 23일에 종료될 때까지 API와 CLI에서 계속 사용할 수 있었습니다.⁷¹⁸⁸

무료 등급 안내(2026년 5월 5일): GPT-5.5 Instant는 2026년 5월 5일에 ChatGPT 무료 등급에 출시되었습니다. 이에 따라 GPT-5.5 제품군의 사용자층이 유료 요금제 밖으로 확대되었지만, Codex CLI를 이용하려면 자격을 갖춘 Plus / Pro / Business / Enterprise / Edu / Go 구독 또는 API 키가 여전히 필요합니다.⁹²

GPT-5.4 mini(2026년 3월 17일): GPT-5.4보다 작고 빠른 변형으로, 400K 컨텍스트를 제공하며 요금은 MTok당 $0.75/$4.50입니다. GPT-5.4 할당량의 30%만 사용합니다. 하위 에이전트 위임에 적합합니다. GPT-5.4가 계획과 조율을 맡고, GPT-5.4 mini 하위 에이전트가 코드베이스 검색, 파일 검토, 문서 처리처럼 범위가 좁은 하위 작업을 병렬로 처리하도록 구성할 수 있습니다.⁷⁶

Bedrock GPT-5.6(Sol, Terra, Luna)(v0.143.0, 2026년 7월 8일): Codex에 Amazon Bedrock에서 호스팅되는 GPT-5.6 Model 변형 3종을 위한 정식 지원과 max 추론 수준 지원이 추가되었습니다. Bedrock 공급자를 통해 Model을 이용하는 팀은 다른 사용자 지정 공급자 Model과 같은 방식으로 이 Model들을 선택할 수 있습니다(사용자 지정 Model 공급자 참조). max 수준은 가장 어려운 추론 및 에이전트형 작업을 대상으로 합니다.¹⁰⁶ v0.144.6(2026년 7월 18일)에서는 Sol, Terra, Luna의 번들 지침을 갱신하고 컨텍스트 창을 272,000토큰으로 수정했습니다.¹¹¹ v0.145.0(2026년 7월 21일)에서는 사용자 지정 엔드포인트와 인증을 지원하는 실험적 Bedrock 로그인이 추가되고, GPT-5.6 Sol이 기본 Bedrock Model로 지정되며, 번들 GPT-5.4 Model 선택 항목이 각각 대응하는 Terra와 Luna 변형으로 이전됩니다.¹¹²

Model 선택 흐름도

Is this a quick fix or simple question?
├─ Yes → gpt-5.6-luna (fastest, most affordable)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.6-luna (the bundled subagent pick since v0.145.0)
   │     │  └─ No
   │     │     ├─ Everyday coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.6-terra (everyday model, 272K context)
   │     │     │  └─ No → gpt-5.6-sol (flagship — the default "Power" setting)
   └─ Still unsure? → gpt-5.6-sol

추론 수준

Model이 응답하기 전에 어느 정도로 깊이 “생각”할지 조절할 수 있습니다.

지원되는 수준은 Model에 따라 다릅니다. minimal은 GPT-5 Model에서만 사용할 수 있습니다. 모든 Model이 모든 수준을 지원하는 것은 아닙니다.

codex -c model_reasoning_effort="xhigh" "find the race condition"

전문가 팁: 같은 프롬프트라도 xhigh 추론은 medium보다 3~5배 많은 토큰을 사용할 수 있습니다. 추가 추론의 효과가 분명한 어려운 문제에만 사용하세요.

TUI 빠른 추론 조절 기능(v0.124.0 이상).⁸⁵ 대화형 TUI 세션에서 Alt+,를 누르면 추론 수준이 한 단계 낮아지고, Alt+.를 누르면 한 단계 높아집니다. 세션 도중 어려운 문제가 나타났을 때 /effort나 -c를 사용하지 않고도 일시적으로 medium → high → xhigh 순서로 높일 수 있어 유용합니다. 세션 도중 Model 업그레이드를 수락하면 이전 추론 수준이 유지되지 않고 새 Model의 기본값으로 초기화됩니다.

Model 전환

세션 도중 /model slash commands로 Model을 전환하거나, 실행할 때마다 --model / -m으로 설정할 수 있습니다.

codex -m gpt-5.3-codex-spark "pair with me on this component"

Codex 비용은 얼마인가요?

기능은 모델 선택을, 작업별로 적합한 모델을 선택하는 방법은 결정 프레임워크를 함께 참고하세요.

ChatGPT 플랜을 통한 이용

Codex 이용 가능 범위는 ChatGPT 플랜과 조직 설정에 따라 달라져요.⁵¹

2026년 4월 가격 변경: Business 연간 결제 가격이 좌석당 월 $25에서 $20로 인하됐어요. 이제 Business와 Enterprise 작업 공간에서 사용량에 따라 결제하는 Codex 전용 좌석을 이용할 수 있어요. 고정 좌석 요금 없이 토큰 사용량에 따라 청구돼요.⁷⁹ 이제 가격 페이지에는 2026년 2월 Desktop App 출시 당시의 프로모션 2x 배수 대신 모델별 한도 범위가 게시돼요(위 표 참고).¹⁶¹¹⁹

2026년 5월 사용량 한도 상향(2026년 5월 31일 종료): Plus 플랜의 Codex에는 25×의 5시간 한도가 적용됐고(기본 상향 폭은 20×), 같은 기간에 월 $100 등급의 한도는 2배로 늘어났어요.⁸⁹

크레딧 비용

Codex 작업은 플랜에 할당된 크레딧을 사용해요.

실제로 “GPT-5.6 사용량은 메시지당 평균 5~40크레딧”이에요. 지원되는 모델에서 빠른 모드를 사용하면 크레딧이 더 빠르게 소모되며, 이미지 생성은 비슷한 텍스트 전용 대화보다 포함된 한도를 3~5배 빠르게 소모해요.¹¹⁹

Enterprise와 Edu 플랜의 크레딧은 계약 할당량에 따라 조정돼요. 현재 사용량은 TUI에서 /status로 확인하세요.

API 요금 청구

API을 통해 Codex를 사용하면 OpenAI는 선택한 모델의 표준 OpenAI API 가격에 따라 토큰별로 사용료를 청구해요. 해당하는 경우 프롬프트 캐싱 할인도 적용돼요. 현재 요금은 공식 API 가격 페이지에서 확인하세요.²⁰

비용 최적화 전략

1. 프로필을 사용하세요: 일상적인 작업에는 gpt-5.6-luna와 model_reasoning_effort = "low"를 사용하는 fast 프로필을 만드세요
2. 높은 추론 수준은 꼭 필요할 때만 사용하세요: xhigh는 토큰을 3~5배 더 사용하므로, 정말 어려운 문제에만 사용하세요
3. --ephemeral을 사용하세요: CI/CD에서 세션 저장을 생략해 추가 비용을 줄이세요
4. 추론 요약을 최소화하세요: 설명이 필요하지 않다면 model_reasoning_summary = "none"으로 설정하세요
5. exec 모드로 일괄 처리하세요: codex exec를 사용하면 자동화 작업 흐름에서 TUI의 추가 비용을 피할 수 있어요
6. 사용량을 모니터링하세요: TUI의 /status와 조직의 요금 청구 대시보드를 확인하세요

실제 비용 예시

일반적인 작업의 대표적인 API 비용이에요(2026년 중반 gpt-5.3-codex 가격을 기준으로 하며 추론 수준은 medium이에요. 모델이 달라도 상대적인 비용 규모는 비슷해요).

비용은 추론 수준, 캐싱, 대화 길이에 따라 달라져요. 일상적인 작업에는 gpt-5.6-luna를 사용해 비용을 크게 줄이세요. 캐시된 입력 토큰에는 할인된 요금이 적용돼요.

숨겨진 토큰 추가 사용량

도구를 호출할 때마다 화면에 표시되는 프롬프트 외에 토큰이 추가로 사용돼요.

전문가 팁: TUI의 /status에서 실제 사용량을 모니터링하세요. 토큰 수에는 화면에 표시되는 메시지뿐만 아니라 모든 추가 사용량이 포함돼요. 예상보다 비용이 많이 나온다면 연결된 MCP 서버 수를 확인하세요. 각 서버의 도구 정의가 모든 API 호출에 추가돼요.

팀 비용 관리

팀 비용 관리 전략: - requirements.toml을 설정하세요 — 조직 전체에 모델과 추론 수준 제한을 적용하세요 - CI/CD에는 gpt-5.6-luna를 사용하세요 — 자동화 파이프라인에는 최고 수준의 추론이 필요한 경우가 드물어요 - 프로필 기반으로 예산을 관리하세요 — 비용 상한이 적절히 설정된 ci, review, dev 프로필을 정의하세요 - OpenTelemetry로 모니터링하세요 — Enterprise 배포 환경에서는 사용량 원격 측정 데이터를 기존 관측성 스택으로 내보낼 수 있어요

결정 프레임워크

각 인터페이스를 사용해야 할 때

각 sandbox 모드를 사용해야 할 때

각 추론 수준을 사용해야 할 때

Plan 모드와 직접 실행 비교

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer 모드: Enter와 Tab

경험 법칙: Enter = “멈추고 지금 이 내용을 들어주세요.” Tab = “현재 작업이 끝나면 이 작업도 해주세요.”

Desktop App과 CLI 비교

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

어떤 프로필을 선택해야 하나요?

작업에 맞는 사전 구성 프로필을 선택하세요.

config.toml 설정:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

세션별로 프로필을 전환하세요: codex --profile careful

Sandbox 및 승인 시스템은 어떻게 작동하나요?

Codex는 기술적으로 가능한 작업과 Codex가 사용자 승인을 요청하는 시점을 구분하는 2계층 보안 모델을 사용해요. 이 방식은 Claude Code의 권한 시스템과 근본적으로 달라요. Codex는 운영 체제 커널 수준에서 제한을 적용해요.⁵ 관리자가 조직 전체에 적용하는 requirements.toml 제약 조건은 엔터프라이즈 배포도 참고하세요.

계층 1: Sandbox(가능한 작업)

Sandbox는 운영 체제에서 기본으로 제공하는 메커니즘을 사용해 파일 시스템과 네트워크 접근을 제어해요.

플랫폼별 적용 방식:

• macOS: 런타임에 컴파일된 모드별 프로필과 sandbox-exec를 통해 Apple의 Seatbelt 프레임워크를 사용하며, 커널에서 제한을 적용해요.⁶ v0.121.0부터 macOS Sandbox 프로필에서 특정 Unix 소켓(예: docker.sock, 편집기 IPC 소켓)을 허용 목록에 추가할 수 있으며, 비공개 DNS 확인도 더 이상 기본적으로 차단되지 않아요.⁸²
• Linux: 파일 시스템 제한에는 Landlock을, 시스템 호출 필터링에는 seccomp를 사용해요. 별도의 도우미 프로세스인 codex-linux-sandbox가 다중 방어 격리를 제공해요.⁵ Bubblewrap(bwrap)은 Linux 빌드에 포함되어 함께 컴파일돼요. v0.100.0부터 선택 사항이 아닌 기본 구성 요소가 되었어요.⁷ v0.117.0에서는 이전 커널 구성을 사용하는 오래된 배포판에서 Sandbox 안정성이 개선되었어요.⁷⁵ v0.129.0에서는 Linux의 Sandbox 시작 절차가 강화되었고, 포함된 Bubblewrap이 상위 프로젝트의 보안 패치를 적용한 0.11.2로 업데이트되었어요. v0.130.0에서는 시작 절차가 추가로 강화되었어요.⁸⁹⁹¹
• Windows: 제한된 토큰을 사용하는 네이티브 Sandbox를 제공해요. v0.100.0부터 실험 기능이 아닌 정식 기능이 되었어요. WSL도 지원하며 Linux의 Landlock 및 seccomp를 그대로 사용해요. v0.117.0에는 더 나은 프로세스 격리를 위한 제한 토큰 Sandbox 개선 사항이 포함되어 있어요.⁷⁵ v0.130.0에서는 Sandbox 사용자에게 데스크톱 런타임 바이너리 캐시 접근 권한을 부여해, 작업 공간 Sandbox 사용자가 Windows Sandbox에서 런타임 바이너리를 안정적으로 찾을 수 있게 되었어요.⁹¹

이 점이 중요한 이유: 컨테이너 기반 Sandbox(Docker)와 달리, 운영 체제 수준의 Sandbox는 더 빠르고 가벼우며 탈출하기도 더 어려워요. Codex가 시스템 호출을 확인하기도 전에 커널에서 제한을 적용해요.

보안 수정 사항: - zsh 포크 Sandbox 우회(v0.106.0): zsh 포크를 통한 셸 실행으로 Sandbox 제한을 우회할 수 있었던 취약점을 수정했어요.⁶⁰ 이전 버전을 사용하고 있다면 즉시 업그레이드하세요. - 입력 크기 제한(v0.106.0): 지나치게 큰 페이로드로 인한 멈춤을 방지하기 위해 Codex가 약 100만 자의 입력 제한을 적용해요.⁶⁰ - 안전한 개발 컨테이너 프로필(v0.121.0): Docker 개발 컨테이너를 위한 새롭게 강화된 고객용 프로필은 컨테이너 내부의 Sandbox에 Bubblewrap을 사용해요. WSL2는 지원하지만 WSL1은 명시적으로 거부해요. Bubblewrap이 WSL1의 커널 호환 계층과 호환되지 않기 때문이에요.⁸² - Guardian 검토 및 hooks(v0.121.0): 도구 실행 전후의 hooks가 Guardian 하위 에이전트의 판단을 방해하지 않도록 Guardian 검토 세션에서는 hooks가 비활성화돼요.⁸² 로깅이나 검증에 hooks를 사용한다면 Guardian 검토에서 이를 건너뛴다는 점에 유의하세요. 완전한 감사 기록이 필요하면 앱 서버 관측 기능을 대신 사용하세요. - Linux /dev 파일 시스템(v0.105.0): 이제 Linux에서 Sandbox로 실행되는 명령에 최소 구성의 /dev 파일 시스템을 제공해, 장치 노드가 있다고 가정하는 도구와의 호환성을 높였어요.⁶¹

ReadOnlyAccess 정책(v0.100.0 이상): 세밀한 읽기 접근 제어를 위한 구성 가능한 정책 형식이에요. workspace-write 모드에서도 Codex가 읽을 수 있는 디렉터리를 제한할 때 사용하세요.

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

계층 2: 승인 정책(요청 시점)

승인 정책은 Codex가 언제 작업을 멈추고 사용자에게 확인을 요청할지 결정해요.

일부 오래된 예시와 호환성 경로에는 여전히 on-failure가 나타나지만, 현재 OpenAI 구성 문서에서는 이를 더 이상 권장하지 않는 항목으로 표시해요. 대화형 실행에는 on-request를, 외부 안전 경계가 이미 마련된 비대화형 실행에는 never를 사용하세요.⁸⁷

개별 승인 ID(v0.104.0 이상)

이제 Codex는 여러 단계로 구성된 셸 실행 안의 각 명령에 서로 다른 승인 ID를 할당해요. 따라서 승인이 세분화되어, 한 명령을 승인해도 같은 셸 호출에 포함된 다음 명령이 자동으로 승인되지는 않아요.⁴⁹

유연한 승인 제어(v0.105.0 이상)

이제 승인 흐름에서 추가 Sandbox 권한과 세분화된 거부를 지원해요.⁶¹

• 추가 Sandbox 권한: 명령에 현재 Sandbox 모드의 범위를 벗어난 접근 권한이 필요하면, Codex는 전체 모드를 변경하도록 요구하는 대신 필요한 추가 권한만 요청할 수 있어요.
• 세분화된 거부: 개별 도구 호출을 피드백과 함께 거부할 수 있어, Codex가 같은 명령을 단순히 다시 시도하지 않고 접근 방식을 조정할 수 있어요.

런타임 권한 요청(v0.113.0 이상)

이제 Codex에는 모델이 런타임에 추가 권한을 요청할 수 있는 내장 request_permissions 도구가 포함되어 있어요.⁶⁹ 모델이 높은 수준의 접근 권한이 필요한 작업을 만나면 조용히 실패하거나 사용자가 다른 플래그로 다시 시작하게 하는 대신, TUI 승인 흐름을 통해 구체적인 권한(파일 시스템 경로, 네트워크 접근 등)을 정식으로 요청할 수 있어요.

앱 승인 모드 writes(v0.144.0 이상)

앱과 커넥터에 중간 단계의 승인 방식이 추가되었어요. writes 앱 승인 모드에서는 앱이 읽기 전용으로 선언한 작업은 확인 없이 실행하고, 쓰기가 발생하는 작업에서는 계속 멈추고 승인을 요청해요.¹⁰⁷ 이전에는 앱 승인이 전부 허용하거나 전부 차단하는 방식에 가까웠지만, writes는 대부분의 운영자가 연동 기능에 실제로 원하는 신뢰 방식과 잘 맞아요. 조회는 자유롭게 하고, 변경할 때는 물어보는 방식이에요.

자동 검토 승인: --approve-for-me(v0.147.0 이상)

새로운 --approve-for-me CLI 플래그는 승인 요청을 자동 검토 승인으로 바꿔요. 각 요청으로 사용자를 방해하는 대신, 검토 절차가 요청을 판단해 사용자를 대신하여 승인하거나 거부해요.¹¹⁶ 이 방식은 “모두 승인”(--full-auto가 권장하던 방식이며 현재는 제거됨)과 “모든 작업에서 사용자에게 확인” 사이에 있어요. 승인 요청은 여전히 판단 지점으로 존재하지만 검토자가 대신 답해요. 이 플래그에는 v0.146.1에서 도입된 사이버 작업 가능 모델용 안전한 자동 검토 기본값이 적용되므로 함께 활용하세요. 다른 권한 위임과 마찬가지로 신중히 사용해야 해요. 사용자 개입이 중단으로 이어지는 장시간 무인 실행에는 적합하지만, 직접 검토해야 하는 자격 증명이나 프로덕션 상태를 다루는 세션에는 적합하지 않아요.

권한 프로필(v0.113.0 이상, v0.128.0 및 v0.133.0에서 확장)

권한 프로필은 파일 시스템과 네트워크 Sandbox 정책을 이름이 있고 재사용 가능한 섹션으로 분리해요. default_permissions를 :read-only, :workspace 같은 내장 프로필로 설정하거나 사용자 정의 [permissions.<name>] 테이블을 가리키도록 설정하세요.⁸⁷ v0.133.0에서는 프로필이 관리형 기능으로 확장되었어요. 목록 APIs에서 사용 가능한 프로필 메타데이터를 제공하고, 프로필끼리 상속할 수 있으며, 관리형 requirements.toml에서 권한 요구 사항을 선언할 수 있어요. 활성 프로필은 런타임에 새로 고쳐지고, Windows Sandbox 설정도 별도의 임시 정책 대신 최종 결정된 프로필을 사용해요.⁹⁸

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

프로젝트 루트에 쓰기 권한이 있더라도 읽을 수 없어야 하는 민감한 파일과 글롭에는 none을 사용하세요. 일회성 명령 예외에는 프로필 범위를 넓게 확장하기보다 규칙을 사용하는 편이 좋아요.⁸⁷

이전 --full-auto 안내

이전 가이드에서는 --full-auto를 다음 설정의 편의용 별칭으로 설명했어요.

codex --sandbox workspace-write --ask-for-approval on-request

v0.128.0 릴리스 노트에서는 --full-auto를 더 이상 권장하지 않는 항목으로 표시하며, 현재 CLI 도움말도 대화형 실행 옵션으로 이를 표시하지 않아요. 대신 위의 명시적 플래그나 이름이 지정된 권한 프로필을 사용하세요.⁸⁶

v0.147.0에서 제거가 완료되어 codex exec --full-auto를 더 이상 사용할 수 없어요. 이 플래그를 계속 전달하는 스크립트는 이제 실행되지 않고 오류가 발생해요. 마이그레이션은 간단해요. --sandbox workspace-write로 교체하고, 기존 호출이 --full-auto의 승인 동작에 의존했다면 승인 플래그나 프로필을 추가하세요. 업그레이드하기 전에 codex exec를 호출하는 모든 자동화를 점검하세요. 이 문제는 더 이상 권장하지 않는다는 경고가 아니라 파이프라인 실패로 나타나요.¹¹⁶

Sandbox 안정성(v0.129.0): Linux Sandbox 시작 절차 강화로 느린 파일 시스템이나 심볼릭 링크로 연결된 체크아웃에서 발생하는 경합을 줄였어요. Windows Sandbox 안정성 개선으로 장시간 실행 중 발생하던 여러 예외 상황의 충돌을 해결했으며, 포함된 Bubblewrap은 상위 프로젝트의 보안 패치가 적용된 0.11.2로 업데이트되었어요. 구성 변경은 필요하지 않아요. codex update를 실행해 업데이트하세요.⁸⁹

권장 구성

일상적인 개발(안전한 기본값):

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

고급 사용자(전체 접근 권한, 사용자가 승인 과정에 참여):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

커뮤니티에서는 이 조합을 최대 권한을 제공하면서도 모든 명령에 승인을 요구하는 가장 균형 잡힌 설정으로 권장해요.⁸

CI/CD 자동화:

sandbox_mode = "workspace-write"
approval_policy = "never"

Guardian 하위 에이전트를 활용한 지능형 승인(v0.115.0 이상)

지능형 승인은 모든 작업에서 사용자 승인을 요구하는 대신 검토 요청을 Guardian 하위 에이전트로 전달할 수 있어요. Guardian 세션은 승인 과정 전체에서 유지되므로 프롬프트 캐시를 재사용하고 시작 비용을 줄여요. 각 검토에는 깨끗한 기록이 제공되어 이전 판단이 이후 검토에 영향을 주지 않아요.⁷³

config.toml에서 검토자를 설정하세요.

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

모든 작업을 일괄적으로 approval_policy = "never"로 설정하는 대신 추론을 포함한 자동 검토를 적용하려는 CI/CD 작업 흐름에 특히 유용해요.

PowerShell 분류기 강화(v0.142.2): 이제 안전 분류기가 검사할 수 없는 실행 가능 AST 영역이 포함된 PowerShell 명령은 자동 승인을 통과하지 않고 승인을 요구해요. 이를 통해 난독화되었거나 동적으로 구성된 PowerShell이 Windows에서 분류를 피할 수 있었던 허점을 막았어요.¹⁰⁵

위험 명령 감지 확대(v0.144.5): 이제 더 다양한 강제 rm 형식을 감지하며, 거부된 명령에는 불분명한 거부 메시지 대신 더 명확한 거부 이유가 표시돼요. 승인 정책을 조정하면서 명령이 차단된 이유를 파악해야 할 때 유용해요.¹¹⁰

네트워크 접근 활성화

Codex는 workspace-write 모드에서 네트워크 접근을 기본적으로 차단해요. 필요할 때 다음과 같이 활성화하세요.

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocket 프록시 지원(v0.104.0 이상)

WebSocket 트래픽을 프록시로 전달하는 기업 환경을 위해 이제 Codex에서 WS_PROXY와 WSS_PROXY 환경 변수를 지원해요.⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

이 변수는 기존 HTTPS_PROXY 및 SOCKS5 프록시 지원(v0.93.0 이상)을 보완해요.

v0.146.0은 실제로 “모든 전송 계층”에서 프록시를 지원하게 된 릴리스예요. 이제 구성한 프록시가 인증, 플러그인 다운로드, MCP 권한 부여, 원격 실행, WebSocket 연결, HTTP 리디렉션, LM Studio 연결에 모두 적용돼요. 변경 기록에 따르면 이전에는 이 7개 경로가 프록시를 무시했어요.¹¹⁴ v0.146.0 이전에 기업 프록시 뒤에서 Codex를 실행할 때 일반 모델 호출은 작동하지만 로그인이나 플러그인 설치가 실패했다면 이 지원 공백이 원인일 가능성이 높아요.

macOS 시스템 프록시(v0.142.2 이상): respect_system_proxy를 활성화하면 macOS 인증 클라이언트가 시스템 프록시, PAC, WPAD 설정을 따라요. 따라서 프로필로 프록시 구성을 배포하는 기업용 Mac에서는 인증 트래픽을 위해 셸마다 프록시 환경 변수를 설정할 필요가 없어요.¹⁰⁵ v0.143.0부터 이 지원은 Windows와 Responses API 트래픽으로 확장되었어요. Codex는 인증과 Responses API 호출을 모두 macOS 또는 Windows 시스템 프록시로 전달하며 PAC 및 WPAD 자동 구성도 지원해요. 이를 통해 두 운영 체제의 통제된 기업 네트워크에 남아 있던 마지막 지원 공백을 해소했어요.¹⁰⁶

Sandbox 테스트

Sandbox를 신뢰하기 전에 동작을 확인하세요.

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

Sandbox가 올바르게 작동한다면 작업 공간 범위 프로필에서 두 명령 모두 권한 거부 오류와 함께 실패해야 해요. 하나라도 성공한다면 Sandbox 구성을 점검해야 해요.

AGENTS.md는 어떻게 작동하나요?

AGENTS.md는 Codex의 프로젝트 지침 시스템으로, 현재 Linux Foundation의 Agentic AI Foundation이 관리하는 공개 표준⁹이에요. Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode와 60,000개 이상의 오픈 소스 프로젝트가 지원해요. AGENTS.md는 특정 저장소나 디렉터리에서 Codex가 어떻게 작동할지 정의해요. AGENTS.md를 보완하는 재사용 가능한 전문 지식 패키지는 skills를 참고하세요.

탐색 계층 구조

Codex는 세션을 시작할 때 디렉터리 트리를 순회하며 지침 체인을 구성해요.

1. 전역 (~/.codex/): AGENTS.override.md > AGENTS.md
2. 프로젝트 (git 루트부터 현재 디렉터리까지): 각 단계에서 AGENTS.override.md > AGENTS.md > 대체 파일 이름 순으로 확인
3. 병합: 파일은 루트부터 아래로 이어 붙여져요. 현재 위치에 가까운 파일일수록 프롬프트 뒤쪽에 배치되어 앞선 지침을 재정의해요.

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Desktop의 여러 폴더 프로젝트 (26.715, 2026년 7월 23일): 위의 순회 방식은 현재 작업 디렉터리를 기준으로 모든 항목을 해석하는 CLI에 해당해요. 이제 ChatGPT desktop app에서는 하나의 로컬 프로젝트에 서로 관련된 여러 폴더를 포함할 수 있지만, 탐색 기준으로 사용하는 폴더는 정확히 하나예요. “새 채팅, Git 작업, AGENTS.md, skills, config.toml의 자동 탐색에는 기본 폴더가 사용됩니다. 보조 폴더에서도 파일 검색, 읽기, 편집은 계속할 수 있습니다.” 프로젝트 메뉴의 프로젝트 편집에서 기본 폴더를 선택할 수 있어요.¹¹³

이 설정 하나가 Codex의 5가지 핵심 시스템 가운데 3가지를 동시에 제어해요. 지침, skills, 설정은 모두 기본 폴더를 따라요. 실제로 보조 폴더의 AGENTS.md는 Codex가 열 수 있는 파일일 뿐, 자동으로 불러오는 운영 규칙은 아니에요. 규칙이 담긴 저장소를 두 번째로 연결했다면 해당 저장소를 기본 폴더로 지정하거나, 그 규칙을 기본 폴더의 AGENTS.md에 다시 작성하세요. 자동으로 검색될 것으로 예상했던 저장소의 skill 폴더도 마찬가지예요. CLI의 디렉터리 순회 방식은 바뀌지 않았으며, 이는 desktop app의 프로젝트 범위 설정에 관한 변화예요.

훌륭한 AGENTS.md의 조건

Codex가 직접 제공한 지침과 커뮤니티에서 사용되는 패턴¹⁰을 바탕으로 정리했어요.

권장 사항: - 구체적으로 작성하세요. "Use rg --files for discovery"가 "search efficiently"보다 나아요. - 완료 조건을 정의하세요. “완료”가 무엇을 의미하나요? (테스트 통과, 린트 오류 없음 등) - 명령어를 포함하세요. 빌드, 테스트, 린트, 포맷에 사용할 정확한 명령을 작성하세요. - 작업별로 구성하세요. 코딩, 검토, 릴리스, 사고 대응과 디버깅 섹션으로 나누세요. - 문제 발생 시 대응 방법을 정의하세요. 작업이 막히거나 예상하지 못한 상태를 발견했을 때 무엇을 해야 하는지 명시하세요.

피해야 할 사항: - 실행 규칙 없이 전체 스타일 가이드를 쏟아 넣지 마세요. - 모호한 지시를 사용하지 마세요. (“주의하세요”, “최적화하세요”) - 서로 충돌하는 우선순위를 섞지 마세요. (속도 + 철저한 검증 + 실행 시간 예산 없음) - 설명용 문서를 작성하지 마세요. (AGENTS.md는 운영 정책이며 README가 아니에요.)

예시: 프로덕션 AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

에이전트 세션의 비밀 정보 처리

Codex에 노출되는 기록은 단순한 소스 코드가 아니라 보안 표면으로 다뤄야 해요. Codex 릴리스 노트에는 셸 스냅샷과 환경 변수 가림 처리 작업이 기록되어 있고, 메모리 시스템도 메모리에 기록되는 내용을 검사해 비밀 정보를 찾아요. 하지만 이러한 보호 기능이 있다고 해서 명령 출력, 세션 기록, 셸 스냅샷, 로컬 로그 또는 보조 스크립트에 자격 증명을 출력해도 안전한 것은 아니에요.³⁷⁵⁵⁹⁵

운영 규칙은 간단해요. 모델이 살펴볼 수 있는 곳에 비밀 정보를 출력하지 마세요. 보조 도구의 자격 증명은 환경에서 요구하는 설정에 보관하세요. 감사할 때는 실행 가능한 소스, 문서, 생성된 캐시, 세션 기록, 셸 스냅샷, 로그와 의도적으로 사용하는 비밀 정보 저장소를 서로 구분하세요. 비밀 정보일 가능성이 높은 형식이 나타나면 로컬 기록에서 가림 처리하고, 수동 위생 관리 절차가 검증된 뒤에만 예방 hooks를 도입하세요. 공개해야 할 교훈은 보안 표면의 범위와 승인 기준이지, 비공개 토큰 값이나 정확한 경로, 탐지기의 내부 구현이 아니에요.⁹⁵

재정의 방식

어떤 디렉터리 단계에서든 AGENTS.override.md는 해당 범위의 일반 AGENTS.md를 대체해요. 다음과 같은 상황에 사용하세요.

• 릴리스 동결: “새 기능은 금지하고 수정만 허용”
• 사고 대응 모드: “모든 변경 사항은 당직 담당자의 검토 필수”
• 임시 보안 강화: “이번 스프린트에서는 의존성 업데이트 금지”

설정

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

기본 구조 생성

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

또는 지침 체인을 확인하세요.

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex는 v0.99.0에서 hooks의 AfterAgent를, v0.100.0에서 AfterToolUse를 도입했어요. 이후 v0.114.0에서는 SessionStart와 Stop 이벤트를 제공하는 실험적 hooks 엔진을 추가했어요.⁷⁰ v0.124.0 (2026년 4월 23일)부터 hooks는 안정화되었어요.⁸⁵ 이제 별도의 hook 스크립트 파일 없이 config.toml과 requirements.toml에서 직접 설정할 수 있으며, apply_patch와 장시간 실행되는 Bash 세션뿐 아니라 MCP 도구도 감시해요. 이제 이 시스템은 세션 수명 주기와 도구 단위 자동화를 모두 지원해 Claude Code의 hook 모델과의 격차를 해소했어요.

사용할 수 있는 Hook 이벤트

Hook 설정

Hooks는 .codex/config.toml에서 설정해요.

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

SessionStart hook의 표준 출력은 모델의 컨텍스트에 전달되므로, 세션을 시작할 때 날짜, 브랜치 이름, 환경 변수 같은 동적 정보를 주입하기에 적합해요.

Claude Code Hook 패턴 재현하기

Claude Code에서 이전하는 경우 다음과 같이 유사한 자동화를 구현할 수 있어요.

전문가 팁: v0.124.0 (2026년 4월 23일)부터 hooks 엔진은 안정화되었어요. 새 hook 이벤트는 이후 릴리스에도 계속 추가되므로 Codex 변경 기록을 확인하세요.

TUI 내부 hook 브라우저 (v0.129.0): TUI에서 /hooks를 실행하면 사용할 수 있는 hooks를 살펴보고, 현재 활성화된 hooks를 확인하며, config.toml을 편집하지 않고 개별 hook을 켜거나 끌 수 있어요. 플러그인에 포함된 hook이 오작동할 때 문제를 해결하거나, 편집에 집중하는 동안 AfterToolUse 린터를 잠시 비활성화할 때 유용해요.⁸⁹

MCP (Model Context Protocol)이란? [EXPERIMENTAL]

MCP는 외부 도구 및 서비스에 연결하여 Codex의 기능을 확장합니다. 현재 codex mcp 명령 그룹은 실험적 기능으로 표시되어 있으며, 릴리스에 따라 명령과 설정 형식이 변경될 수 있습니다. Codex는 STDIO(로컬 프로세스)와 Streamable HTTP(원격 서버)라는 2가지 전송 방식을 지원합니다.¹¹

v0.121.0 MCP 변경 사항: 이제 도구가 네임스페이스와 함께 등록되므로 목록의 도구 이름이 단독 이름이 아닌 <server>:<tool> 형식으로 표시됩니다. 정규화되지 않은 도구 이름을 grep하는 스크립트나 프롬프트가 있다면 업데이트하세요. 포함된 MCP에 새로운 supports_parallel_tool_calls 플래그가 전달되며, 지원을 선언한 서버에서는 병렬 실행을 사용할 수 있습니다. 이제 샌드박스 상태 메타데이터가 MCP 도구 메타데이터를 통해 전달되므로 서버가 상황에 맞게 동작할 수 있습니다(예: read-only 샌드박스에서 실행 중일 때 경고). 사용자 지정 codex/sandbox-state 요청은 제거되었습니다. 대신 메타데이터 경로를 사용하세요. MCP Apps 출시의 3단계에는 도구 호출 지원이 포함되며, 이제 지연 호출 패턴을 사용하는 서버에서 평면화된 지연 도구 호출도 지원됩니다.⁸²

v0.142.2 MCP 변경 사항(2026년 6월 25일): 이제 MCP 도구는 지원되는 경우 기본적으로 도구 검색을 사용합니다. 모든 도구 정의를 미리 불러오는 대신 Codex가 필요할 때 도구를 탐색하므로, 이전 모델 및 공급자와의 호환성을 유지하면서 도구가 많은 환경의 탐색 성능을 개선합니다. 원격 stdio MCP 서버는 원격 플랫폼의 경로 형식으로 작성된 절대 작업 디렉터리도 허용합니다(macOS 클라이언트의 Windows 형식 경로나 그 반대의 경우도 지원합니다).¹⁰⁵

v0.147.0 MCP 변경 사항(2026년 8월 7일): Codex에 MCP 2026-07-28 프로토콜 개정판을 선택적으로 지원하는 기능이 추가되었습니다. 여기에는 페이지로 나눈 탐색(대규모 도구 카탈로그를 지나치게 큰 단일 목록 대신 여러 페이지로 스트리밍), 다중 라운드 요청(서버가 하나의 논리적 요청 안에서 여러 단계의 교환을 유지), 비차단 서버 시작이 포함됩니다. 서버가 시작을 마치기 전에 캐시된 MCP 도구를 노출하므로 느린 서버가 더 이상 세션 시작을 지연시키지 않습니다. 선택적으로 활성화하는 기능이므로 이전 개정판을 사용하는 서버도 변경 없이 계속 작동합니다.¹¹⁶

MCP 서버 설정

STDIO 서버(로컬 프로세스):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP 서버(원격):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI 관리

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

세션에서는 /mcp를 통해 활성 서버와 사용 가능한 도구를 확인할 수 있습니다. /mcp verbose(v0.123.0 이상)⁸⁴는 전체 서버 진단 정보, 리소스, 리소스 템플릿을 반환합니다. 서버를 불러오지 못하거나 예상한 위치에 도구가 나타나지 않을 때 유용합니다. 일반 /mcp는 계속 빠르게 작동합니다. v0.144.0부터 MCP 도구는 실험적 기능을 별도로 활성화하지 않아도 대화형으로 인증을 요청할 수 있습니다. 세션 도중 인증이 필요한 서버는 codex mcp login으로 미리 인증할 때까지 실패하는 대신 일반 인증 흐름을 통해 사용자에게 인증을 요청합니다.¹⁰⁷

플러그인 MCP 로딩(v0.123.0 이상)은 .mcp.json에서 표준 mcpServers 스키마와 최상위 서버 맵을 모두 허용하므로, 어느 규칙에 맞춰 작성된 플러그인이든 문제없이 불러올 수 있습니다.⁸⁴

Codex를 MCP 서버로 실행

Codex는 다중 에이전트 오케스트레이션을 위해 자체 기능을 MCP 서버로 제공할 수 있습니다.¹²

codex mcp-server                        # Start as MCP server (stdio transport)

서버는 2가지 도구를 제공합니다: 1. codex(): 프롬프트, 샌드박스, 모델, 승인 매개변수로 새 세션 시작 2. codex-reply(): threadId와 프롬프트로 기존 세션 계속 진행

Agents SDK에서 사용(Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

주요 MCP 서버

실용적인 패턴

패턴 1: 컨텍스트 인식 개발 — Codex가 항상 최신 API 참조 자료를 활용할 수 있도록 Context7을 프레임워크 문서와 함께 사용하세요:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

패턴 2: 출력 제한 — MCP 도구 응답은 기본적으로 약 25K자에서 잘립니다. 대용량 페이로드를 반환하는 도구(데이터베이스 쿼리, 로그 캡처)의 경우 enabled_tools로 사용할 도구를 제한하여 응답이 필요한 내용에 집중되도록 하세요.

패턴 2a: 멀티모달 도구 출력(v0.107.0) — 이제 사용자 지정 도구는 텍스트와 함께 멀티모달 출력(이미지, 리치 콘텐츠)을 반환할 수 있습니다. 따라서 스크린샷, 다이어그램, 렌더링된 차트와 같은 시각 자료를 생성하는 도구가 결과물을 모델에 직접 전달하여 분석하도록 할 수 있습니다.⁶²

패턴 3: 기업용 MCP 거버넌스 — 개발자가 사용할 수 있는 MCP 서버를 requirements.toml로 제한하세요:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

requirements.toml의 식별 정보와 일치하지 않는 서버는 시작 시 차단됩니다. 전체 정책 설정은 기업 배포를 참조하세요.

Code Mode [EXPERIMENTAL]

Code Mode(v0.114.0)는 에이전트의 범위를 코드 중심 작업으로 제한하여 더 격리된 코딩 워크플로를 제공합니다.⁷⁰ 이 기능을 활성화하면 에이전트는 더 광범위한 시스템 상호 작용 없이 코드 읽기, 쓰기, 테스트에 집중합니다.

v0.139.0부터 Code Mode는 중첩된 JavaScript 도구 호출을 포함하여 독립 실행형 웹 검색을 직접 호출하고 일반 텍스트 결과를 받을 수 있으므로, Code Mode 흐름은 샌드박스로 격리된 코딩 컨텍스트를 벗어나지 않고도 실시간 정보를 가져올 수 있습니다.¹²² v0.146.0에서는 독립 실행형 웹 검색이 호환되는 사용자 지정 모델 공급자까지 확장되어, 더 이상 OpenAI에서 호스팅하는 모델로만 기능이 제한되지 않습니다.¹¹⁴

v0.146.0부터 app-server는 WebSocket을 통해 원격 Code Mode 호스트에 연결할 수 있으므로, Code Mode 런타임이 클라이언트와 같은 컴퓨터에 있을 필요가 없습니다.¹¹⁴

이 기능은 실험적입니다. 업데이트는 릴리스 노트를 확인하세요.

JavaScript REPL 런타임 [REMOVED]

Codex v0.100.0에서는 실험적인 JavaScript REPL 런타임(js_repl)이 추가되었고, v0.106.0에서는 /experimental 화면을 통해 사용할 수 있게 되었습니다.⁶⁰ 이제 이 안내는 과거 기록에 해당합니다. v0.128.0 릴리스 변경 기록에는 “js_repl 기능 제거”가 포함되어 있으며, 현재 기능 목록에서는 js_repl과 js_repl_tools_only가 모두 제거된 것으로 표시됩니다.⁸⁶

새 설정에는 features.js_repl = true를 추가하지 마세요. 반복 실행 가능한 로직이 필요할 때는 셸 명령, 저장소에 포함된 스크립트, MCP 도구 또는 scripts/ 디렉터리가 있는 Codex skill을 사용하세요.

Skills란 무엇인가요?

Skills는 Codex가 필요할 때 불러오는 재사용 가능한 작업별 기능 패키지예요. 공개 에이전트 Skills 표준을 따릅니다.¹³

Skill 구조

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

검색 위치

Codex는 사용자가 설치한 Skills를 $CODEX_HOME/skills(기본값: ~/.codex/skills)에 저장하며, .system/ 아래에는 기본 제공 시스템 Skills가 포함돼요. Codex는 심볼릭 링크로 연결된 Skill 폴더도 지원해요.

Skill 만들기

SKILL.md 형식:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

메타데이터(agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Skills 호출하기

• 명시적 호출: /skills 메뉴를 사용하거나 프롬프트에서 $skill-name을 언급
• 암시적 호출: Codex가 작업 설명을 바탕으로 일치하는 Skills를 자동으로 감지(allow_implicit_invocation: true인 경우)
• 만들기: $skill-creator를 사용해 대화형으로 새 Skill 만들기
• 설치하기: $skill-installer install <name>을 사용해 커뮤니티 Skills 설치
• 실행기 제공(v0.146.0): Codex는 실행기가 제공하는 Skills를 검색하고, 사용자가 명시적으로 선택한 Skills를 포함해 연결된 리소스를 읽어요¹¹⁴

컨텍스트 예산에 따라 Skill 카탈로그가 잘릴 수 있어요. v0.146.0은 컨텍스트가 부족할 때도 더 많은 Skills를 유지하며, 카탈로그를 잘라야 할 경우 경고를 표시해요.¹¹⁴ 이전에는 대규모 Skill 라이브러리가 아무 알림 없이 잘릴 수 있었기 때문에, 범위에 포함될 것으로 예상한 Skill이 아예 제공되지 않기도 했어요. 많은 Skills에서 암시적 호출을 사용한다면 이 경고가 표시되는지 확인하세요.

활성화/비활성화

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills와 Slash Commands 비교

Skills 디버깅하기

Skill이 활성화되지 않는다면 다음을 확인하세요.

1. 검색 여부 확인: TUI의 /skills 목록에 표시돼야 해요
2. 경로 확인: Skill 폴더가 인식되는 위치(~/.codex/skills/, 프로젝트 루트 또는 /etc/codex/skills/)에 있는지 확인하세요
3. enabled 확인: config.toml에서 enabled = false로 설정된 Skills는 불러오지 않아요
4. 암시적 활성화 확인: 자동 감지를 사용한다면 agents/openai.yaml에 allow_implicit_invocation: true가 설정되어 있는지 확인하세요
5. 키워드 사용: 암시적 일치 정확도를 높이려면 프롬프트에 Skill의 description에 있는 용어를 포함하세요

실제 운영 예시: 배포 Skill

참조 자료와 스크립트가 함께 작동하는 완전한 다중 파일 Skill의 예시예요.

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

호출 방법: $deploy to staging 또는 $deploy production with canary rollout

Plugins

Plugins는 skills, MCP 항목, hooks, 앱 커넥터를 하나의 설치 가능한 패키지로 통합합니다(v0.110.0+).⁶⁵ v0.117.0부터 plugins는 핵심 기능으로 제공됩니다. 제품 범위 plugins는 시작 시 자동으로 동기화되며, /plugins에서 검색 및 관리를 위한 TUI 내 브라우저를 제공합니다.⁷⁵ v0.128.0에서는 marketplace 설치, 원격 번들 캐싱, 원격 제거 APIs, plugin에 포함된 hooks, hook 활성화 상태, 외부 에이전트 설정 가져오기로 plugin 워크플로를 확장했습니다.⁸⁶ v0.129.0(2026년 5월 7일)에는 plugin workspace 공유(다시 게시하지 않고 팀원에게 plugin 세트 푸시), 공유 액세스 제어(수신자별 활성화/비활성화, 해제), 소스 필터링(workspace가 가져올 marketplaces 제한), 그리고 CLI 대신 /plugins 브라우저에서 직접 호출할 수 있는 marketplace 작업이 추가되었습니다.⁸⁹ v0.133.0(2026년 5월 21일)에서는 plugin 검색 결과를 더 쉽게 감사할 수 있습니다. 목록 출력이 marketplace를 인식하고, 설치된 버전이 표시되며, marketplace 루트가 나열되고, 결과가 어느 registry에서 왔는지 추측하지 않아도 원격 plugin 컬렉션을 확인할 수 있습니다.⁹⁸ v0.130.0(2026년 5월 8일)에서는 plugin 패키징의 투명성과 공유 워크플로의 제어 기능을 강화했습니다.⁹¹

• Plugin 세부 정보에서 번들 hooks 표시. 이제 /plugins 세부 보기에서 plugin이 번들로 제공하는 모든 수명 주기 hook(SessionStart, UserPromptSubmit, Stop 등)을 나열합니다. plugin을 설치하기 전에 세션에 등록할 hooks를 정확히 확인할 수 있으므로, 도구만 믿고 설치한 plugin의 예기치 않은 hook 부작용을 피할 수 있습니다.
• shareContext의 plugin 공유 메타데이터. workspace에서 plugin을 공유하면 이제 공유 링크 페이로드가 링크 메타데이터(생성자, 범위, 최신성)를 노출하므로, 수신 세션에서 출처를 표시하고 수락 여부를 결정할 수 있습니다.
• 공유 설정의 검색 가능성 제어. 공유 설정에서 검색 가능성 토글을 제공하므로, 팀은 조직 전체에서 일반적으로 목록화하지 않고도 특정 workspaces 또는 수신자 목록에 plugins를 게시할 수 있습니다.

v0.143.0(2026년 7월 8일)은 원격 plugins를 기본으로 활성화합니다. 이제 opt-in 플래그 없이 원격 plugins가 활성화되며, /plugins 카탈로그에는 더 풍부한 행이 추가됩니다(npm marketplace 소스를 git 및 로컬 소스와 함께 표시). 또한 각 항목은 원격 버전과 로컬에 설치된 버전을 모두 보여 주어 차이를 한눈에 확인할 수 있습니다.¹⁰⁶ 공유 plugin 세트를 표준화하는 팀이라면 원격 기본 활성화로 인해 기존에 배포를 가로막던 컴퓨터별 활성화 단계가 사라집니다.

Plugin 소스

v0.147.0부터 plugin 검색은 한 쿼리에서 로컬, 개인, workspace, 원격 카탈로그를 모두 아우릅니다. 보유한 카탈로그가 아니라 필요한 기능을 검색합니다. 이식 가능한 Agent Plugin 패키지와 결합하면 한 환경에서 만든 plugin을 다른 환경에 깔끔하게 설치할 수 있으며, 작성된 컴퓨터나 workspace에 묶이지 않습니다.¹¹⁶

Plugin 검색

Codex는 세션 시작 시 어떤 plugins가 활성화되어 있는지 모델에 알려 설치된 MCPs, 앱, skills의 검색성을 높입니다(v0.111.0).⁶⁵ 모델은 작업 맥락에 따라 세션 중 관련 plugins를 제안할 수 있습니다. v0.117.0에서는 제품 범위 plugins를 시작 시 동기화하여 수동 개입 없이 최신 plugin 카탈로그를 사용할 수 있도록 합니다.⁷⁵ v0.142.0부터 /plugins 메뉴는 원격 plugins를 OpenAI Curated, Workspace, Shared with me 섹션으로 구성하며, 적합한 턴에서는 관련 plugins를 인라인으로 추천하고 설치할 수 있습니다.¹⁰⁴

@plugin 멘션(v0.112.0+)

채팅에서 @plugin-name으로 설치된 plugin을 직접 참조할 수 있습니다.⁶⁸ plugin을 멘션하면 해당 맥락(기능, 도구, 설정)이 모델의 컨텍스트 창에 자동으로 포함되므로, plugin의 기능을 따로 설명할 필요가 없습니다.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

이 기능은 사용자 지정 skills, MCP servers, 앱 커넥터를 포함한 모든 설치된 plugin에서 작동합니다.

Plugin Marketplace(v0.113.0+)

이제 plugin marketplace에는 메타데이터, 카테고리, 평점을 포함한 더 풍부한 검색 기능이 제공됩니다.⁶⁹ 설치 시 인증 검사는 API keys 또는 OAuth가 필요한 plugins에 설치 전에 유효한 자격 증명이 있는지 확인합니다. 제거 endpoint는 plugins와 관련 설정을 깔끔하게 제거합니다.

Third-Party Marketplaces 추가(v0.121.0+)

현재 OpenAI Codex 문서에서는 marketplace 소스 관리를 codex plugin marketplace 아래에서 제공합니다. 이는 OpenAI의 자체 marketplace를 넘어 third-party plugin 배포를 공식화하며, GitHub repo 축약형, HTTP(S) Git URLs, SSH URLs, 로컬 marketplace 루트 디렉터리를 지원합니다. Git ref를 고정하려면 --ref를 사용하고, Git 기반 marketplace repos에만 --sparse PATH를 반복 사용하세요.⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

추가한 뒤에는 해당 marketplace의 plugins가 기본 항목과 함께 /plugins 브라우저에 표시됩니다. App-server 호출자(IDE/desktop 통합)에는 marketplaces를 프로그래밍 방식으로 등록하는 병렬 endpoint도 있습니다.⁸²

보안 고려 사항: Third-party marketplaces는 Codex 권한으로 임의의 plugin 코드를 실행합니다. 추가하기 전에 소스를 검토하고, 처음 실행할 때는 sandboxed 실행을 사용하는 것이 좋습니다.

Agent Plugins: 여러 공급업체를 위한 표준(v0.146.0–v0.147.0)

“Agent Plugins”는 단순한 Codex 기능 이름이 아닙니다. 이는 2026년 8월 6일 Agent Plugins 1.0.0으로 공개된 개방형 공급업체 중립 패키징 표준이며, 공식 사이트에서는 이를 “AI agents를 확장하는 재사용 가능한 구성 요소를 위한 이식 가능한 패키지 형식”이라고 요약합니다.¹¹⁸ plugin은 필수 plugin.json manifest로 구성된 디렉터리입니다. 이 manifest는 정확히 10개의 최상위 필드만 허용하는 폐쇄형 schema입니다. $schema, name, version, description, author, homepage, repository, license, keywords, extensions이며, “Clients MUST report and ignore each unknown field”를 따릅니다. 선택적으로 skills/ 폴더를 포함할 수 있고(직접 하위 디렉터리마다 SKILL.md가 있으면 하나의 skill), stdio, Streamable HTTP 또는 legacy HTTP+SSE servers를 선언하는 선택적 mcp.json, 그리고 다른 클라이언트가 “MUST ignore”해야 하는 선택적 역도메인 client-namespace 디렉터리도 포함할 수 있습니다. 이 표준의 규범적 범위는 패키징입니다. 사양은 “defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins”라고 정의하며, Agent Skills와 MCP는 그 아래에서 각자의 사양을 유지합니다.¹¹⁸

거버넌스가 핵심입니다. Vercel이 제안을 시작했고 Amazon, Anysphere(Cursor), GitHub, Microsoft, OpenAI와 함께 1.0 사양을 개발했습니다. 사양 repository의 유지 관리자 명단에는 Amazon, Cursor, Microsoft, OpenAI, Vercel이 포함되며, Google은 출시일에 핵심 유지 관리자에 합류한다고 발표했습니다.¹¹⁸ 명시된 출시 클라이언트에는 ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, VS Code가 포함됩니다. 한 가지 눈에 띄는 부재가 있습니다. 기본 Agent Skills 형식과 MCP 자체를 만든 Anthropic는 유지 관리자에 포함되지 않았습니다. Claude Code는 자체 plugin 형식을 유지하고, Codex는 Claude Code marketplace source(v0.146.0)와 /import를 통해 자체적으로 이 간극을 연결합니다.¹¹⁸

Codex 관점에서 보면 v0.146.0에는 Agent Plugins manifests, workspace plugin 게시, 그리고 Amazon Bedrock 및 Claude Code라는 2개의 추가 plugin marketplaces가 추가되었고,¹¹⁴ v0.147.0에서는 이식 가능한 Agent Plugins 설치와 로컬, 개인, workspace, 원격 카탈로그 전반의 검색으로 이 과정을 완성했습니다.¹¹⁶ workspace 게시 기능은 팀에 특히 실용적입니다. 공개 marketplace를 구축하거나 모든 개발자에게 Git source를 직접 추가하도록 요청하는 대신, 자체 workspace에 plugins를 게시할 수 있습니다.

릴리스 노트는 Codex 표면 기능을 발표하지만 설정 keys 또는 CLI 문법은 공개하지 않습니다. 이 항목은 기능이 도입되었다는 사실과 표준의 명세를 기록하며, Codex에서 이를 구동하는 방법은 다루지 않습니다. OpenAI 문서에서 다루기 전까지 manifest 작성 워크플로 및 모든 codex plugin publish 호출은 검증되지 않은 것으로 취급하세요.

Plugins 관리

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

TUI에서는 /plugins(v0.117.0+)를 사용해 세션을 벗어나지 않고도 개별 plugins를 대화형으로 탐색, 설치, 제거할 수 있습니다.⁷⁵

전문가 팁: Plugins는 예전에 별도의 MCP 설정, skill 설치, 앱 커넥터 설정이 필요했던 기능을 통합합니다. 하나의 plugin에 세 가지를 모두 묶을 수 있으므로 팀 온보딩이 더 빨라지고 설정의 이식성도 높아집니다.

Plan Mode 및 협업

Plan mode를 사용하면 Codex가 변경 사항을 실행하기 전에 접근 방식을 설계할 수 있어요. 기본적으로 활성화되어 있습니다(v0.94.0부터).¹⁴ “Plan Mode와 직접 실행” 결정 트리는 결정 프레임워크를 참고하세요.

Plan Mode 시작하기

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

Plan mode에서 Codex는 다음과 같이 작동해요. - 파일을 읽고 코드베이스를 분석해요 - 구현 계획을 제안해요 - 사용자가 승인할 때까지 변경 사항을 적용하지 않아요 - 전용 TUI 화면에서 계획을 실시간으로 보여 줘요

Steer Mode

Steer mode는 Codex가 현재 작업을 중단하지 않고 계속 수행하는 동안 새로운 지시를 전달할 수 있는 기능이에요(v0.98.0부터 기본적으로 활성화됨).¹⁴

지시를 전달하는 방법은 2가지예요.

실용적인 예시:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Steer mode는 TUI에서 항상 활성화되어 있어요. Codex가 작업을 마친 뒤 지시하고 싶다면 턴이 완료된 후 평소처럼 입력하면 돼요. 별도의 모드는 필요하지 않아요.

TUI 개선 사항(v0.105.0–v0.106.0)

구문 강조(v0.105.0): 이제 TUI는 펜스로 감싼 코드 블록과 diff의 구문을 화면 안에서 강조해요. /theme으로 색 구성표를 선택하세요.⁶¹

새로운 TUI 명령어(v0.105.0 이상):⁶¹

음성 받아쓰기(v0.105.0, 실험적 기능): 스페이스바를 누르면 음성 받아쓰기로 프롬프트를 말할 수 있어요. 이 기능은 실험 단계이며 마이크 권한이 필요할 수 있어요.⁶¹ v0.107.0부터 실시간 음성 세션에서 마이크와 스피커 장치를 선택할 수 있어 특정 오디오 입출력 하드웨어를 지정할 수 있어요.⁶² v0.140.0에서 제거되었다가 v0.145.0에서 돌아옴: 실험적인 /realtime 음성 제어 기능과 관련 오디오 의존성은 v0.140.0에서 TUI에서 제거되었어요(스페이스바 음성 받아쓰기는 영향을 받지 않았어요).¹⁰² v0.145.0에서는 새로운 형태로 음성 기능이 돌아왔어요. 일반적인 로컬 오디오 형식의 오디오 입력과 오디오 도구 출력, 그리고 스트리밍 실시간 V3 대화를 지원해요.¹¹²

기타 개선 사항: - 이제 긴 링크가 여러 TUI 줄에 걸쳐 표시되어도 클릭할 수 있어요(v0.105.0)⁶¹ - 로컬 파일 링크가 더 나아진 형식으로 표시돼요(v0.106.0)⁶⁰ - TUI markdown은 OSC 8 메타데이터를 사용해 웹 링크를 클릭 가능한 상태로 유지하며, 공간이 부족한 표는 링크 대상을 잃지 않고 읽기 쉬운 키와 값 형식으로 표시돼요(v0.136.0)¹²⁵ - 하위 에이전트의 Ctrl+C 처리가 수정되어 자식 프로세스가 올바르게 종료돼요(v0.106.0)⁶⁰

Memory 시스템

Codex에는 세션 간에 사실, 선호 사항, 프로젝트 맥락을 저장하는 영구 Memory 시스템(v0.100.0 이상)이 있어요.²⁴

Memory 명령어

Memory는 ~/.codex/memory/ 아래의 markdown 파일에 저장돼요. Codex는 세션이 시작될 때 이를 불러오고 이후 모든 세션에서 동작을 결정하는 데 활용해요.

저장하면 좋은 내용

Memory는 계속 유지해야 하는 선호 사항과 프로젝트 정보에 가장 적합해요.

• 프로젝트 규칙: “이 프로젝트에서는 공백 대신 탭을 사용해요” 또는 “API 응답에는 항상 meta 필드가 포함돼요”
• 도구 선호 사항: “npm 대신 pnpm을 사용해요” 또는 “pytest -x --tb=short로 테스트를 실행해요”
• 아키텍처 결정 사항: “인증 모듈은 src/middleware/가 아니라 src/core/auth/에 있어요”
• 작업 흐름 선호 사항: “diff를 보여 주기 전에 항상 린터를 실행해요”

파이프라인의 Memory

codex exec를 실행하면 Memory가 자동으로 불러와져요. 따라서 CI/CD 파이프라인과 스크립트에서도 대화형 세션과 같은 맥락을 활용할 수 있으며, 실행할 때마다 지시를 반복할 필요가 없어요.

Memory 개선 사항(v0.101.0–v0.107.0)

• 비밀 정보 정리: Memory를 디스크에 기록하기 전에 비밀 정보가 있는지 자동으로 검사해요
• CWD 인식: 이제 Memory 파일에 작업 디렉터리 맥락이 포함되어 프로젝트별 내용을 떠올릴 수 있어요
• 개발자 메시지 제외: 개발자 및 시스템 메시지를 1단계 Memory 입력에서 제외해 사용자 상호 작용에 집중하고 Memory 품질을 높여요
• diff 기반 망각(v0.106.0): 이제 Memory는 diff 기반 망각을 사용해 오래된 사실을 제거하며, 시간이 지나도 Memory 저장소를 간결하고 관련성 높은 상태로 유지해요⁶⁰
• 사용량 기반 선택(v0.106.0): 이제 Memory 검색은 사용량을 반영해 자주 접근했거나 최근에 관련성이 높았던 Memory를 우선해요⁶⁰
• 설정 가능한 Memory(v0.107.0): 이제 Memory를 완전히 설정할 수 있어요. 저장된 모든 Memory를 초기화하려면 codex debug clear-memories를 사용하세요. 서로 관련 없는 프로젝트 사이에서 맥락을 전환하거나 Memory 상태가 실제 상황과 달라졌을 때 유용해요⁶²
• 2단계 모델 업그레이드(v0.121.0): 이제 2단계 Memory 통합 모델은 이전 기본 모델에서 업그레이드된 gpt-5.4예요. 2단계 파이프라인은 세션 사이에 실행되며 1단계 기록에서 오래 유지할 사실을 추려 내요. 모델 변경으로 같은 토큰 비용에서 더 정확하게 내용을 떠올릴 수 있어요.⁸²
• TUI Memory 메뉴(v0.121.0): 새로운 세션 내 UI에서 Memory 모드, 개별 Memory 삭제, 초기화 버튼을 사용할 수 있어요. 이제 Memory를 초기화해도 과거 rollout은 유지되므로, 세션 재생을 중단하지 않고 이후에 떠올릴 내용만 지울 수 있어요.⁸²

Memory와 AGENTS.md 비교

팁: 계속 유지해야 하는 사실은 /m_update로 저장하세요. 현재 세션에만 필요한 맥락은 대화에서 Codex에게 직접 알려 주면 돼요. 팀과 공유할 맥락은 AGENTS.md를 사용하세요.

세션 관리

Codex는 세션을 ~/.codex/sessions/ 아래에 저장하므로 CLI와 데스크톱 환경 전반에서 재개, 포크, 멀티스레드 워크플로를 사용할 수 있습니다.

v0.146.0에서는 스레드를 주소 지정할 수 있습니다. 이제 /new와 /clear에 세션 이름을 지정할 수 있고, 중요한 스레드는 고정할 수 있으며, 한 대화에 접근하기 위해 다른 대화를 닫을 필요 없이 보조 대화를 열어 둘 수 있습니다.¹¹⁴ 실질적으로는 장기 프로젝트가 날짜로 구분해 알아봐야 하는 타임스탬프 목록이 아니게 됩니다. v0.147.0에서는 대화 섹션이 추가됩니다. 대화는 수동으로 정렬할 수 있는 영구 섹션으로 구성되며, 긴 트랜스크립트는 전체를 한 번에 불러오는 대신 점진적으로 탐색합니다.¹¹⁶

재개

중단한 지점부터 계속하세요.

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

TUI 내의 /resume 슬래시 명령은 검색 기능이 있는 동일한 대화형 선택기를 엽니다.

페이지 단위 스레드 기록(v0.145.0) [EXPERIMENTAL]: 실험적인 페이지 단위 스레드 기록은 효율적인 재개, 기록 전체 검색, 유지되는 스레드 이름, 서브 에이전트 지원, 메모리 기능을 세션 관리에 제공합니다. 기록을 한 번에 모두 불러오는 대신 페이지별로 불러오므로, 수백 개의 세션이 있는 장기 작업 디렉터리에서 특히 중요합니다. 실험적 기능이므로 릴리스마다 인터페이스가 바뀔 수 있습니다.¹¹²

포크

현재 진행 상황을 잃지 않고 대안을 살펴보도록 대화를 분기하세요.

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

포크는 포크 지점까지의 동일한 기록을 공유하는 독립 스레드를 만듭니다. v0.146.0부터 포크 기록은 페이지 단위로 제공되며, 포크를 임시로 만들 수도 있습니다. 임시 포크는 스레드 목록에 표시되지 않으므로, 실제로 탐색하는 스레드 목록에서 일회성 실험을 제외할 수 있습니다.¹¹⁴ 한 포크의 변경 사항은 다른 포크에 영향을 주지 않습니다. 접근 방식을 비교하거나(예: “포크해서 Memcached 대신 Redis 시도”) 위험한 변경을 안전하게 살펴볼 때 유용합니다.

서브 에이전트로 스레드 포킹(v0.107.0): 이제 스레드를 독립적인 서브 에이전트로 포크할 수 있으므로, 하나의 대화에서 자율적으로 실행되는 병렬 작업 흐름을 만들 수 있습니다. 이는 기존 포크 모델을 확장한 기능입니다. 대화를 단순히 분기하는 대신 포크된 스레드가 자체 실행 컨텍스트를 가진 서브 에이전트가 됩니다.⁶² v0.117.0부터 서브 에이전트는 구조화된 에이전트 간 메시징과 함께 경로 기반 주소(예: /root/agent_a)를 사용하므로 멀티 에이전트 조정이 더 명시적이고 디버그하기 쉬워집니다.⁷⁵

암호화된 에이전트 간 메시지(v0.138.0+): 이제 멀티 에이전트 v2는 상위 에이전트가 서브 에이전트를 생성하거나 메시지를 보낼 때 전송하는 작업 텍스트를 암호화합니다. spawn_agent, send_message, followup_task의 메시지 매개변수는 암호화된 것으로 표시됩니다. Responses API는 상위 모델이 도구 호출을 생성할 때 페이로드를 암호화하고, 로컬에서 실행되는 Codex는 암호문만(InterAgentCommunication.encrypted_content, 평문 내용은 비어 있음) 전달하며, API는 수신 모델에 전달할 때 서버 측에서 이를 복호화합니다.¹⁰⁸ 실질적인 결과는 3가지입니다.

• 로컬 세션 로그에는 더 이상 위임 평문이 포함되지 않습니다. 상위 에이전트가 서브 에이전트를 생성했다는 사실과 반환된 내용은 볼 수 있지만, 전송한 정확한 지침은 볼 수 없습니다. 세션 기록으로 멀티 에이전트 실행을 감사하거나 디버그하는 경우 해당 기록은 사라집니다. 이를 추적하는 공개 회귀 이슈에는 2026년 7월 중순 기준 연결된 수정 사항이 없습니다.¹⁰⁹ 확장 수명 주기 이벤트(서브 에이전트 시작/중지, 도구 실행, 턴 메타데이터 — v0.133.0+)와 앱 서버 관찰 가능성은 발생한 일을 재구성할 수 있는 남은 연결 지점입니다.⁹⁸
• 커스텀 제공자 모델이 작동하지 않을 수 있습니다. 암호화된 도구 사용으로 구성되지 않은 모델 엔드포인트는 암호화된 spawn_agent 스키마를 400 오류("declares encrypted parameters but is not configured for encrypted tool use")와 함께 거부합니다. 커스텀 제공자에서 해당 오류로 멀티 에이전트 위임이 실패한다면, 설정 문제가 아니라 암호화 변경 때문입니다.¹⁰⁹
• Codex가 생성한 알림은 계속 읽을 수 있습니다. 하위 작업 완료 알림은 Codex 자체에서 생성하므로 평문으로 유지되며, 이제 직렬화된 JSON 봉투 대신 형식화된 agent_message 항목으로 렌더링됩니다.¹⁰⁸

OpenAI는 이 변경의 위협 모델을 공개하지 않았습니다. PR은 암호문 흐름을 설명하지만, 어떤 위협으로부터 보호하는지는 밝히지 않습니다.

멀티 에이전트 v2 안정화(v0.145.0, 옵트인): v0.137.0에서 처음 도입되고 v0.138.0에서 암호화된 위임이 추가된 멀티 에이전트 v2 경험은 이제 옵트인 기능으로 안정화되었습니다. v0.145.0에서는 구성 가능한 서브 에이전트 모델, 서브 에이전트별 추론 수준, 구성 가능한 동시성, 복원된 멀티 에이전트 역할, 향상된 에이전트 탐색 기능을 추가합니다. v0.137/v0.138의 초기 안정화 기간 동안 v2 사용을 미뤘다면, 이번 릴리스에서 구성 인터페이스가 안정화됩니다. 이제 서브 에이전트 모델과 추론 선택은 런타임에 고정되지 않고 설정에서 지정합니다.¹¹²

스레드 목록

활성 세션을 확인하고 관리하세요.

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

데스크톱 앱에서는 전체 기록과 diff 미리보기를 포함한 스레드를 사이드바에서 볼 수 있습니다.

세션 수명 주기

세션은 CLI와 데스크톱 앱 간에 동기화됩니다. 한쪽에서 시작한 뒤 다른 쪽에서 계속할 수 있습니다.

비대화형 모드 (codex exec)

codex exec는 스크립팅, CI/CD, 자동화를 위해 Codex를 비대화형으로 실행해요.¹⁵

기본 사용법

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

기본적으로 codex exec는 진행 상황과 이벤트를 stderr에, 에이전트의 최종 메시지를 stdout에 출력해요. 따라서 표준 Unix 파이프라인과 조합해서 사용할 수 있어요.

세션 보관 (v0.136.0)

기록을 삭제하지 않으면서 재개 및 포크 목록을 깔끔하게 유지하도록 세션을 보관할 수 있어요. TUI에서는 /archive를 사용하고, 셸에서는 다음 명령을 사용하세요.¹²⁵

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

보관된 세션은 보관을 해제하기 전까지 재개하거나 포크할 수 없어요. 종료하려던 세션을 실수로 계속 진행하지 않도록 막아 주는 안전장치예요. 같은 릴리스에서 codex app-server --stdio를 사용하면 편집기 및 호스트 통합을 위해 app-server를 stdio 모드로 실행할 수 있고, 이제 /diff에서는 저장소가 제공하는 Git 도우미를 실행하지 못해요. 이는 명령 안전성을 위한 수정이에요. Windows에서는 알파 단계의 프로비저닝 경로에 관리자를 위한 codex sandbox setup --elevated가 추가됐어요.¹²⁵

JSON Lines 출력

--json을 사용하면 stdout이 JSONL 이벤트 스트림으로 바뀌어요.

codex exec --json "fix the tests" | jq

이벤트 유형: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

구조화된 출력

JSON Schema를 사용해 응답 형식을 강제할 수 있어요.

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message는 최종 메시지를 파일에 써요.

세션 재개 및 검토

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

주요 플래그

CI 인증

codex exec는 자동화 환경의 비대화형 인증을 위해 CODEX_API_KEY를 지원해요.

codex exec 시작 배너 (v0.130.0). codex exec 시작 배너에는 더 이상 기존 “research preview” 문구가 표시되지 않아요. CI에서 시작 출력을 수집한다면 이제 배너 문구가 더 간결해졌다는 점에 유의하세요. 구조화된 --json 이벤트는 변경되지 않았어요.⁹¹

codex remote-control (v0.130.0+)

codex remote-control은 IDE 확장 프로그램, 사용자 지정 오케스트레이터, 원격 제어 영역처럼 다른 프로세스가 제어하도록 설계된 헤드리스 app-server를 시작하는 최상위 명령이에요. 여러 통합 개발자가 수동으로 조합해 사용하던 다중 플래그 codex app-server 호출을 대체하며, 타사 도구에서 데스크톱 및 IDE 환경에 포함된 것과 동일한 app-server 런타임으로 접근할 수 있는 안정적인 단일 진입점을 제공해요.⁹¹ v0.133.0에서는 명령의 런타임 동작이 개선됐어요. 포그라운드 명령처럼 실행하고 준비될 때까지 기다린 후 시스템 상태를 보고할 수 있으며, 장기간 실행되는 컨트롤러 구성에 필요한 명시적인 데몬 방식의 start / stop 명령도 계속 사용할 수 있어요.⁹⁸ v0.143.0에는 codex remote-control pair가 추가됐어요. 이 명령은 실행 중인 데몬에서 수동 페어링 코드를 생성해 컨트롤러가 자동 검색 핸드셰이크 없이 연결할 수 있게 해요. 제어 프로세스와 데몬이 서로 다른 호스트나 네트워크 구간에 있을 때 유용해요.¹⁰⁶

# Start a headless, remotely controllable app-server
codex remote-control

# Generate a manual pairing code for an out-of-band controller (v0.143.0+)
codex remote-control pair

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

모든 턴을 한꺼번에 메모리에 불러오지 않고 긴 스레드 기록을 나열해야 하는 UI를 구축한다면 codex remote-control을 아래의 app-server 페이지 매김 APIs와 함께 사용하세요.

App-Server 스레드 페이지 매김 (v0.130.0+)

이제 app-server 클라이언트는 서로 다른 3가지 턴 항목 보기를 통해 긴 스레드를 페이지 단위로 탐색할 수 있어요.⁹¹

특히 오케스트레이터와 롤아웃 파일이 서로 다른 시스템에 있을 수 있는 원격 제어 배포에서는 v0.121.0에 도입된 ThreadStore 인터페이스와 페이지 매김을 함께 사용해 장기간 실행되는 스레드를 효율적으로 탐색하세요.⁸² v0.143.0에서는 컨트롤러가 검사할 수 있는 범위가 넓어졌어요. 이제 app-server 클라이언트는 사용 가능한 환경을 나열하고, 스레드의 하위 스레드 목록을 확인하며, 특정 턴을 기준으로 기록을 포크할 수 있어요. 이를 통해 UI는 실행 내용을 다시 재생하지 않고 이전 지점에서 실행을 분기할 수 있어요.¹⁰⁶

실시간 App-Server 설정 새로 고침 (v0.130.0+)

이제 실행 중인 app-server 스레드는 다시 시작하지 않아도 config.toml 변경 사항을 반영해요. 설정을 편집하고 저장하면 실행 중인 스레드의 다음 턴부터 새 값이 적용돼요. 이는 codex remote-control에 대응하는 버그 수정으로, 장기간 실행되는 헤드리스 서버를 종료하지 않고 그 자리에서 다시 설정할 수 있게 해요.⁹¹

암호화된 원격 실행기 (v0.141.0)

v0.141.0 안정 버전부터, 2026년 6월 18일 기준으로 원격 실행기는 인증된 종단 간 암호화 Noise 릴레이 채널을 통해 연결돼요. 이제 제어 영역과 실행기는 둘 사이에 있는 릴레이를 신뢰하지 않아도 돼요. 오케스트레이터가 네트워크 경계를 넘어 app-server를 제어할 때 특히 중요해요. 같은 릴리스에서는 플랫폼 간 원격 실행 시 실행기의 기본 작업 디렉터리와 셸이 그대로 유지되도록 변경됐어요. 따라서 한 운영체제의 컨트롤러가 다른 운영체제의 실행기를 제어해도 경로나 셸 동작 방식이 임의로 바뀌지 않아요. 이제 TLS는 기업 프록시와의 호환성을 위해 P-521 인증서 서명도 허용해요.¹⁰³

Codex Cloud 및 백그라운드 작업 [EXPERIMENTAL]

상태: Codex Cloud는 실험적 기능이에요. 인터페이스, 가격, 제공 여부는 변경될 수 있어요. 클라우드 환경은 OpenAI에서 관리하므로 사용자가 인프라를 제어할 수 없어요.

Codex Cloud는 OpenAI에서 관리하는 환경에서 작업을 비동기식으로 실행해요.⁴ Codex를 CI 파이프라인과 통합하는 방법은 GitHub Action 및 CI/CD도 참고하세요.

작동 방식

1. 작업을 제출해요. chatgpt.com/codex, Slack 통합 또는 CLI를 사용할 수 있어요.
2. Codex가 저장소를 격리된 클라우드 sandbox에 복제해요.
3. 에이전트가 독립적으로 코드를 읽고, 테스트를 실행하고, 변경 사항을 만들어요.
4. 작업이 끝나면 Codex가 PR을 생성하거나 검토할 diff를 제공해요.
5. codex apply <TASK_ID>로 결과를 로컬에 적용해요.

Cloud의 인터넷 접근

에이전트의 인터넷 접근은 기본적으로 꺼져 있으며 환경별로 설정해요.

• 꺼짐: 에이전트가 인터넷에 접근할 수 없음, 기본값
• 켜짐: 선택적인 도메인 허용 목록과 HTTP 메서드 제한

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

에이전트의 인터넷 접근이 꺼져 있어도 설정 스크립트는 인터넷을 사용해 종속성을 설치할 수 있어요.

Slack 통합

Slack 채널이나 스레드에서 @Codex를 멘션해 클라우드 작업을 시작하세요.

사전 요구 사항: 1. 지원되는 ChatGPT 요금제, Plus, Pro, Business, Enterprise 또는 Edu 2. 연결된 GitHub 계정 3. 설정된 클라우드 환경 1개 이상 4. 작업 공간에 설치된 Slack 앱

Codex는 작업 링크로 답변하고 완료되면 결과를 게시해요.

Cloud CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

Codex Desktop App

Codex Desktop App(macOS 및 Windows)은 여러 프로젝트를 관리하는 데 최적화된 그래픽 인터페이스를 제공해요.¹⁶ Windows 버전은 기본 PowerShell 지원과 Windows 전용 샌드박스를 갖추고 2026년 3월 4일에 출시되었어요.⁶⁶

설치

codex app                      # Auto-downloads and installs on first run

또는 직접 다운로드하세요: Codex.dmg (macOS) | Microsoft Store에서 이용 가능(Windows)

주요 기능

Appshots, 브라우저 댓글 및 Computer Use

5월 21일 앱 업데이트를 통해 Desktop App은 단순한 스레드 관리자를 넘어 더 강력한 컨텍스트 제공 수단이 되었어요. Codex가 작업하기 전에 다른 Mac 앱의 상태를 파악해야 할 때는 Appshots를 사용하세요. Codex는 맨 앞에 있는 창, 앱에서 제공하는 화면 안팎의 텍스트를 캡처하고 첨부 파일을 세션 기록에 로컬로 저장해요.⁹⁹

웹 및 프런트엔드 작업에서는 페이지에 인증이 필요하지 않다면 앱 내 브라우저를 먼저 사용하세요. Codex와 사용자가 렌더링된 미리 보기를 함께 확인할 수 있고, 클릭, 스크린샷, 에셋 다운로드, 읽기 전용 검사 JavaScript 같은 브라우저 조작을 지원해요. 또한 페이지 영역에 댓글을 표시하면 Codex가 다음 턴에서 이를 처리할 수 있어요.⁹⁹ 로그인이 필요한 사이트에서는 계속 Chrome 확장 프로그램을 사용하세요.

구조화된 통합이나 브라우저 미리 보기로 작업을 검증할 수 없을 때만 Computer Use를 사용하세요. Computer Use는 허용된 Mac 앱을 검사하고 조작할 수 있지만, 파일 수정과 셸 명령어에는 Codex의 승인 및 샌드박스 규칙이 그대로 적용돼요. 잠금 상태 사용의 범위도 제한적이에요. Mac이 잠긴 후 Codex는 신뢰할 수 있는 활성 Computer Use 턴에서만 허용된 앱에 일시적으로 접근할 수 있으며, 다시 잠그는 보호 장치와 로컬 입력 감지 기능이 적용돼요.⁹⁹

스레드 모드

각 스레드는 생성할 때 선택한 3가지 모드 중 하나로 실행돼요.

Worktree 격리 방식:

Worktree 스레드를 시작하면 Desktop App은 다음 작업을 수행해요. 1. 임시 디렉터리에 새로운 git worktree(git worktree add)를 생성해요 2. 현재 HEAD에서 새 브랜치를 체크아웃해요 3. worktree 안에서 에이전트를 실행해 모든 파일 변경 사항을 격리해요 4. 작업이 끝나면 diff 검토 화면을 표시하고, 사용자가 병합할 변경 사항을 선택해요

따라서 같은 저장소에서 여러 Worktree 스레드를 충돌 없이 동시에 실행할 수 있어요. 각 스레드에는 고유한 브랜치와 작업 디렉터리가 할당돼요.

자동화

자동화는 앱에서 로컬로 실행되므로 앱이 실행 중이고 프로젝트가 디스크에 있어야 해요.

• Git 저장소에서는 자동화가 전용 백그라운드 worktree를 사용해요. 이 worktree는 사용자의 작업 디렉터리와 격리돼요
• Git이 아닌 프로젝트에서는 프로젝트 디렉터리에서 직접 실행돼요
• 자동화에는 기본 샌드박스 설정이 적용돼요

자동화 설정 방법: 1. Desktop App에서 프로젝트를 여세요 2. 사이드바에서 자동화 탭을 클릭하세요 3. 트리거를 정의하세요(일정, 웹훅 또는 수동) 4. 프롬프트를 작성하고 실행 모드(local 또는 worktree)를 선택하세요 5. 자동화 실행에 사용할 추론 수준을 설정하세요(App v26.312)⁷² 6. 자동화는 일정에 따라 실행되고 결과를 검토 대기열에 추가해요

사용 사례: - 이슈 분류: 새로운 이슈를 자동으로 분류하고 우선순위를 지정해요 - CI 모니터링: 빌드 실패를 감시하고 수정 방법을 제안해요 - 알림 대응: 모니터링 알림에 진단 분석으로 대응해요 - 종속 항목 업데이트: 보안 패치를 확인하고 적용해요

결과는 사용자가 승인할 수 있도록 검토 대기열에 표시돼요.

Windows 지원

Codex Desktop App은 기본 PowerShell 지원, Windows 전용 샌드박스, skills, 자동화, worktrees를 비롯한 모든 기능을 갖추고 2026년 3월 4일에 Windows용으로 출시되었어요(App v26.304). WSL은 필요하지 않아요.⁶⁶

GitHub Action 및 CI/CD

공식 GitHub Action을 사용하면 Codex를 CI/CD 파이프라인에 통합할 수 있어요.¹⁸

기본 사용법

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

설정 옵션

출력: final-message, 이후 단계나 작업에서 사용할 최종 Codex 응답 텍스트예요.

안전 전략

접근 제어

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

기본값: 쓰기 권한이 있는 공동 작업자만 Codex 워크플로를 트리거할 수 있어요.

Codex SDK

TypeScript SDK는 Codex의 에이전트 기능을 맞춤형 애플리케이션에 내장합니다.¹⁹

설치

npm install @openai/codex-sdk

기본 사용법

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

고급 SDK 기능

• runStreamed(...): 중간 업데이트를 위한 Async 이벤트 스트림
• Python SDK 인증 (v0.132.0+): API 키 로그인, ChatGPT 브라우저/디바이스 코드 흐름, 계정 확인, 로그아웃은 모두 기본 SDK 경로입니다.⁹⁷
• 텍스트 전용 turn 편의 기능 (v0.132.0+): Python turn API는 일반 문자열을 받고 수집된 항목, 시간, 사용량이 포함된 더 풍부한 TurnResult 메타데이터를 반환합니다.⁹⁷
• outputSchema: JSON 형태의 최종 출력을 강제합니다
• 멀티모달 입력: 텍스트 + 로컬 이미지({ type: "local_image", path: "..." })를 전달합니다
• 이미지 워크플로 (v0.117.0): view_image는 URL을 반환하고, 생성된 이미지는 다시 열 수 있으며, 세션을 재개해도 이미지 기록이 유지됩니다⁷⁵
• 다중 환경 view_image (v0.130.0): 여러 환경에 걸친 세션(v0.124.0에서 turn별 환경 + 작업 디렉터리 선택 기능으로 도입되고, v0.125.0에서 고정 환경으로 개선됨)의 경우, 이제 view_image는 오케스트레이터의 로컬 파일 시스템이 아니라 선택한 환경을 통해 파일 경로를 확인합니다. 원격 환경에서 첨부한 이미지는 SDK를 실행하는 호스트가 아니라 해당 환경의 작업 디렉터리를 기준으로 가져옵니다.⁹¹

Thread 및 Client 구성

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

세션은 ~/.codex/sessions 아래에 유지됩니다.

런타임: Node.js 18+.

성능 최적화

컨텍스트 관리

컨텍스트 창 크기는 모델마다 다릅니다. 현재 GPT-5.6 계열(Sol, Terra, Luna)은 272K 창을 사용합니다. 이전 세대의 플래그십인 GPT-5.5는 Codex에서 400K(API에서는 1M)를 제공하며, GPT-5.4 / GPT-5.4-mini(Codex에서 2026년 8월 31일 종료 예정)는 1M / 400K를 제공합니다. 레거시 GPT-5.3-Codex 계열은 272K 입력 + 128K 출력(총 400K 예산)을 제공했습니다. 모든 모델은 예상보다 빠르게 채워지므로 적극적으로 관리하세요.

1. /compact를 정기적으로 사용하세요: 토큰을 확보할 수 있도록 대화 기록을 요약합니다
2. 로컬 문서를 제공하세요: 고품질 AGENTS.md와 로컬 문서는 탐색 오버헤드(컨텍스트 소비)를 줄입니다
3. @를 사용해 특정 파일을 첨부하세요: Codex에게 파일을 찾도록 요청하는 대신 파일을 직접 참조하세요
4. 프롬프트를 집중해서 작성하세요: 정확한 파일을 지정한 범위가 명확한 프롬프트는 제한 없는 탐색보다 컨텍스트를 덜 소비합니다

토큰 효율성

속도 최적화

1. gpt-5.3-codex-spark: 대화형 페어링을 위한 저지연 변형
2. --profile fast: 낮은 추론 수준의 gpt-5.6-luna가 사전 구성되어 있습니다
3. 병렬 도구 실행: Codex는 독립적인 읽기/검사를 동시에 실행하므로, 이를 활용할 수 있게 프롬프트를 구성하세요
4. 결과 중심 루프: 단계별 지시 대신 “구현하고, 테스트하고, 수정한 뒤, 통과하면 멈추세요”라고 요청하세요

문제를 어떻게 디버그하나요?

일반적인 문제와 해결 방법

오류 메시지 참고

codex doctor는 무엇을 하나요?

codex doctor는 버그를 신고하거나 손상된 설치를 디버그하기 전에 실행할 단일 명령입니다. 로컬 런타임, 구성, 인증, 터미널, 네트워크, 상태를 하나의 보고서에 수집하며, 프로젝트의 자체 issue template에서도 출력을 붙여 넣도록 요청합니다.¹²⁰

codex doctor                           # Full human-readable report (the default)
codex doctor --summary                 # Compact view
codex doctor --json                    # Redacted structured JSON, for bug reports
codex doctor --all                     # Expand truncated lists
codex doctor --no-color                # Strip ANSI color

보고서는 안정적인 섹션으로 구성되어 있어 필요한 항목을 빠르게 확인할 수 있습니다.¹²⁰

각 검사는 상태 표시자 – ✓ 정상, ✗ 실패, ⚠ 경고, ○ 유휴 – 및 요약 줄을 포함합니다. --json은 모든 검사를 안정적인 식별자로 키 지정하므로, 눈으로 확인하는 용도뿐 아니라 CI나 지원 스크립트에서도 사용할 수 있습니다.¹²⁰

이 명령은 릴리스마다 기능이 확장되었습니다. v0.131.0에 도입되었고, v0.135.0에는 환경, Git, 터미널, app-server, thread inventory 보고가 추가되었으며, v0.139.0에는 editor와 pager 세부 정보가 추가되었습니다(JSON에서는 민감한 값이 가려짐).^96126122

먼저 사용하세요, 나중에 사용하지 마세요. 대부분의 “Codex가 고장 났습니다” 보고서는 doctor가 이미 알려 주는 원인으로 귀결됩니다. 예를 들어 오래된 인증 모드, 파싱에 실패한 config.toml, 또는 PATH에서 다른 설치본을 가리는 두 번째 설치 등이 있습니다.

진단 도구

codex doctor                           # Full local diagnostic (start here)
codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

세션 내 TUI 진단:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

참고: codex --verbose는 유효한 최상위 flag가 아닙니다. 위의 debug subcommand와 TUI 진단을 사용하세요.

클린 재설치

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

~/.codex/(인증, 구성, 세션)은 유지됩니다. 정확한 버전으로 고정하거나, 문제가 있는 릴리스 이후 다운그레이드하거나, 전체 상태를 삭제하려면 Codex CLI 업데이트, 다운그레이드 또는 제거를 참고하세요.

Debug Mode

codex debug app-server send-message-v2  # Test app-server client

문제 신고

/feedback                              # Send logs to Codex maintainers (in TUI)

또는 github.com/openai/codex/issues에서 issue를 등록하세요.¹

Codex Security [PREVIEW]

Codex Security는 2026년 3월 6일 research preview로 공개되어, 컨텍스트 인식 애플리케이션 보안 검토를 Codex stack에 도입했습니다.⁷⁷ Codex web을 통해 ChatGPT Pro, Enterprise, Business, Edu 고객이 사용할 수 있습니다.

작동 방식: Codex Security는 repository를 분석해 프로젝트별 threat model을 만들고, 실제 영향도를 기준으로 분류된 vulnerability를 식별하며, 이를 검증하기 위해 sandboxed 환경에서 발견 사항을 pressure-test합니다. 이 agent는 수정 방법이 포함된 신뢰도 높은 발견 사항을 표시하여 중요하지 않은 bug로 인한 노이즈를 줄입니다.

성능: research preview 기간에 Codex Security는 120만 개의 commit을 스캔하고 심각도가 높은 vulnerability 10,561개를 식별했습니다. 시간이 지나면서 정밀도가 향상되어 노이즈를 84% 줄이고, 과도하게 보고된 심각도를 90% 이상 낮추며, false positive 비율을 절반으로 줄였습니다. 이 시스템은 OpenSSH, GnuTLS, Chromium에서 실제 vulnerability를 발견했으며, CVE 14개가 할당되었습니다.⁷⁷

참고: Codex Security는 CLI의 내장 sandbox 보안 모델과 별개입니다. sandbox는 Codex로부터 사용자의 컴퓨터를 보호하고, Codex Security는 vulnerability로부터 코드베이스를 보호합니다.

엔터프라이즈 배포

관리자 제어 (requirements.toml)

관리자는 사용자가 재정의할 수 없는 보안 민감 설정을 제한하는 관리자 강제 구성 파일인 requirements.toml을 통해 엔터프라이즈 정책을 적용합니다:²¹

v0.146.0에서는 엔터프라이즈 요금제 인식과 앱 내 업데이트에 대한 관리자 제어가 추가되었습니다.¹¹⁴ 관리형 환경에서는 개발자가 새 릴리스를 발견할 때마다 CLI을 직접 업데이트하는 것과 관리자가 버전 배포 시점을 결정하는 것의 차이를 만듭니다. 릴리스 노트에서는 이 제어 기능을 알리지만 requirements.toml 키는 공개하지 않았습니다. OpenAI가 문서화하기 전까지 정확한 설정 이름은 검증되지 않은 것으로 취급하세요.

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

사용자 수준의 config.toml이 기본 설정을 지정하는 것과 달리, requirements.toml은 사용자가 선택할 수 있는 값을 제한하며 재정의할 수 없는 강제 제약 계층입니다. 관리자 요구 사항 규칙은 프롬프트하거나 금지만 할 수 있으며, 자동으로 허용할 수는 없습니다.

macOS MDM 구성

com.openai.codex 환경 설정 도메인을 사용해 MDM으로 배포하세요.²¹ Codex는 표준 macOS MDM 페이로드(Jamf Pro, Fleet, Kandji 등)를 지원합니다. 줄 바꿈 없이 TOML을 base64로 인코딩하세요.

우선순위(높은 순서부터):

1. macOS 관리형 환경 설정(MDM)
2. 클라우드에서 가져온 요구 사항(ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml(로컬 파일 시스템)

클라우드 요구 사항은 설정되지 않은 요구 사항 필드만 채우므로, 우선순위가 더 높은 관리 계층이 항상 적용됩니다. 클라우드 요구 사항은 최선 노력 방식입니다. 가져오기에 실패하거나 시간이 초과되면 Codex는 클라우드 계층 없이 계속 실행됩니다.

OpenTelemetry 통합

Codex는 표준 OTel 환경 변수의 OpenTelemetry trace-context 전파를 OpenAI API 호출까지 지원합니다. Codex를 실행하기 전에 표준 환경 변수를 설정하세요.

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• 표준 OTEL_* 환경 변수(endpoint, 서비스 이름, 리소스 속성)를 지원합니다.
• trace context가 Codex를 거쳐 API 호출까지 전파되어 엔드 투 엔드 관측성을 제공합니다.
• 리소스 속성을 사용해 팀, 환경 또는 프로젝트별로 trace에 태그를 지정하세요.
• 프롬프트/도구 로깅을 활성화할 때는 개인정보 보호 요구 사항을 고려하세요. trace에 코드 조각이 포함될 수 있습니다.
• 구성 가능한 OpenTelemetry trace 메타데이터(v0.130.0+). 표준 OTEL_RESOURCE_ATTRIBUTES 범위를 넘어, codex-otel crate는 이제 구성 가능한 trace 메타데이터를 제공하므로 관리자는 호출할 때마다 OTEL_RESOURCE_ATTRIBUTES를 처음부터 다시 만들지 않고도 비용 센터, 프로젝트 ID, 티켓 참조 같은 조직별 차원으로 trace에 태그를 지정할 수 있습니다. 이를 동일한 릴리스에 포함된 더욱 풍부한 리뷰/피드백 분석 기능과 함께 사용하면 CLI, app-server 및 remote-control 세션 전반에서 통합된 디버깅과 분류를 수행할 수 있습니다.⁹¹

엔터프라이즈 액세스

• ChatGPT Business / Enterprise / Edu: 조직 관리자가 제어하는 액세스이며, 클라우드에서 가져온 요구 사항이 자동으로 적용됩니다. ID 공급자(Okta, Entra ID 등)를 통해 SAML/OIDC SSO를 지원합니다.
• API: 표준 API 인증, 청구 및 조직/프로젝트 제어를 제공합니다. OpenAI는 SOC 2 Type II 및 SOC 3 보고서를 제공하며, Enterprise 티어에서는 HIPAA BAA를 사용할 수 있습니다.
• Codex SDK: 내부 도구와 워크플로에 임베드하세요.
• 대규모 정책 적용: MDM으로 배포한 requirements_toml_base64 또는 파일 시스템 수준의 /etc/codex/requirements.toml을 사용하세요.

데이터 처리 및 규정 준수: - OpenAI의 Business/Enterprise/API 약관에 따라 API 입력/출력은 학습에 사용되지 않습니다. - 데이터 레지던시의 경우 OpenAI API 트래픽은 기본적으로 미국 기반 인프라를 통해 라우팅됩니다. EU 데이터 레지던시 요구 사항은 OpenAI Enterprise 영업팀에 문의하세요. - 세션 transcript는 로컬에 저장되며, API 호출만 머신 외부로 전송됩니다. - ChatGPT Enterprise는 SOC 2, GDPR, CCPA를 포함한 규정 준수 프레임워크를 지원합니다.

배포 전략

조직에 권장하는 단계적 배포 방식입니다.

1. 파일럿(1-2주차): untrusted sandbox mode와 cached 웹 검색을 적용하는 requirements.toml을 사용해 시니어 엔지니어 3-5명에게 배포하세요. AGENTS.md 패턴과 MCP 서버 요구 사항에 관한 피드백을 수집하세요.
2. 팀 확장(3-4주차): 전체 팀으로 배포를 확대하세요. MDM 또는 리포지토리를 통해 팀 표준 config.toml을 배포하세요. 신뢰할 수 있는 리포지토리에는 workspace-write sandbox를 활성화하세요.
3. CI 통합(5-6주차): 자동화된 PR 리뷰와 테스트 생성을 위해 CI/CD 파이프라인에 codex-action을 추가하세요. 비용을 예측 가능하게 유지하려면 --ephemeral을 사용하세요.
4. 조직 전체(2개월차 이상): 승인된 MCP 서버, sandbox 정책 및 모델 allowlist를 적용하는 requirements.toml과 함께 MDM으로 배포하세요.

감사 패턴

Codex 사용량을 추적하고 규정 준수를 적용하세요.

• OpenTelemetry trace: 팀별 API 호출량, 토큰 사용량 및 지연 시간을 모니터링하세요.
• 세션 유지: 규정 준수 검토를 위해 ~/.codex/sessions/를 감사하세요. 민감한 상황에서는 --ephemeral로 비활성화하세요.
• MCP ID 적용: requirements.toml은 차단된 서버 시도를 기록합니다. 승인되지 않은 도구 사용 여부를 검토하세요.
• Git 감사 추적: 모든 Codex 파일 변경은 표준 git을 거칩니다. 브랜치 기록과 PR diff로 검토하세요.

모범 사례 및 안티패턴

프롬프트 패턴

1. 제약 조건 중심 프롬프트: 경계를 먼저 제시하세요. “API 계약은 변경하지 마세요. 내부 구현만 리팩터링하세요.”
2. 구조화된 재현 단계: 모호한 설명보다 번호가 매겨진 단계가 더 나은 버그 수정을 이끌어냅니다
3. 검증 요청: “lint와 가장 작은 관련 테스트 모음을 실행하세요. 명령과 결과를 보고하세요.”로 마무리하세요.
4. 파일 참조: @filename을 사용해 특정 파일을 컨텍스트에 첨부하세요
5. 결과 중심 루프: “구현하고, 테스트를 실행하고, 실패를 수정하세요. 모든 테스트가 통과할 때만 멈추세요.” Codex는 완료될 때까지 반복합니다

테스트 철학

커뮤니티는 테스트 중심 AI 협업 방식에 의견을 모으고 있습니다.²²

• 완료 신호로 사용할 테스트를 미리 정의하세요
• 테스트가 통과할 때까지 Codex가 반복하도록 하세요 (red → green → refactor)
• Tiger Style 프로그래밍 패턴을 अपन하세요
• 패치를 요청할 때는 정확한 파일 텍스트를 제공하세요. Codex는 퍼지 AST 기반 패치가 아니라 엄격한 매칭을 사용합니다

컨텍스트 관리 모범 사례

• 웹 검색에 의존하기보다 품질 높은 로컬 문서를 제공하세요
• 목차와 진행 파일이 포함된 구조화된 markdown을 유지하세요 (“점진적 공개”)
• 패치 실패를 방지하려면 추적되는 파일 전체에서 줄바꿈 형식(LF vs CRLF)을 통일하세요
• 긴 지침은 컨텍스트 밖으로 밀려날 수 있으므로 AGENTS.md를 간결하게 유지하세요

Git 워크플로

• 익숙하지 않은 저장소에서 Codex를 실행하기 전에 항상 새 브랜치를 만드세요
• 직접 편집보다 패치 기반 워크플로(git diff / git apply)를 사용하세요
• Codex의 제안은 코드 리뷰 PR처럼 검토하세요
• 커밋하기 전에 /diff로 변경 사항을 확인하세요

커뮤니티 skills 및 프롬프트

feiskyer/codex-settings 저장소는 커뮤니티에서 관리하는 구성을 제공합니다.²³

재사용 가능한 프롬프트 (~/.codex/prompts/): - deep-reflector: 개발 세션에서 얻은 학습 내용을 추출합니다 - github-issue-fixer [issue-number]: 체계적인 버그 분석 및 PR 생성 - github-pr-reviewer [pr-number]: 코드 리뷰 워크플로 - ui-engineer [requirements]: 프로덕션 수준의 프런트엔드 개발

커뮤니티 skills: - claude-skill: 권한 모드로 Claude Code에 작업을 넘깁니다 - autonomous-skill: 진행 상황 추적을 포함한 멀티 세션 작업 자동화 - deep-research: 병렬 하위 작업 오케스트레이션 - kiro-skill: 요구사항 → 설계 → 작업 → 실행 파이프라인

안티패턴

토큰을 낭비하거나, 낮은 품질의 결과를 만들거나, 답답한 워크플로를 초래하는 흔한 실수입니다.

비용 안티패턴

컨텍스트 안티패턴

워크플로 안티패턴

프롬프트 안티패턴

워크플로 레시피

일반적인 개발 시나리오를 위한 엔드투엔드 패턴입니다.

레시피 1: 새 프로젝트 설정

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

생성된 AGENTS.md를 검토하고 규칙에 맞게 편집한 다음:

> Run the health endpoint test and confirm it passes

레시피 2: 일일 개발 흐름

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

/diff로 검토한 다음 커밋하세요.

레시피 3: Plan Mode를 사용한 복잡한 리팩터링

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

계획을 검토하세요. 승인하거나 방향을 조정하세요:

[Tab] Also add a migration script using Alembic

Codex가 실행한 후 다음을 확인하세요:

> Run the full test suite and report results
> /diff

레시피 4: codex exec를 사용한 PR 리뷰

codex exec --model gpt-5.6-luna \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

레시피 5: Cloud Tasks를 사용한 디버깅 [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

나중에 진행 상황을 확인하세요:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

완료되면 로컬에서 수정을 적용하세요:

codex apply <TASK_ID>

마이그레이션 가이드

Claude Code에서 전환

알아두어야 할 주요 차이점:

• Sandbox는 OS 수준에서 작동합니다: Codex는 컨테이너가 아니라 Seatbelt/Landlock을 사용합니다. 제한은 애플리케이션 계층 아래인 커널 수준에서 적용됩니다.
• Hooks는 확장 중입니다: Codex는 이제 5개의 hook 이벤트를 지원합니다. SessionStart, Stop, UserPromptSubmit(v0.114.0–v0.116.0, 실험적), AfterAgent(v0.99.0), AfterToolUse(v0.100.0)입니다. 이 시스템은 세션 수명 주기, 프롬프트 가로채기, 도구 수준 자동화를 다루지만, Claude Code의 12개 이상 수명 주기 이벤트가 여전히 더 폭넓게 지원됩니다. 아직 지원되지 않는 자동화 패턴에는 AGENTS.md 지침이나 skills를 사용하세요.
• Sub-agents v2 (v0.117.0): Sub-agents는 이제 구조화된 에이전트 간 메시징과 에이전트 목록 조회를 지원하는 경로 기반 주소(예: /root/agent_a)를 사용합니다.⁷⁵ 이는 기존 기능을 확장한 것입니다(최대 동시 실행 6개, v0.91.0에서 12개에서 감소). 멀티 에이전트 역할은 config를 통해 계속 맞춤 설정할 수 있습니다(v0.104.0+).⁴⁷ v0.105.0에서는 진행 상황 추적 및 ETA와 함께 행별 fanout을 수행하는 spawn_agents_on_csv가 추가되었습니다.⁶¹ Codex에는 사용자 주도 위임을 위한 Claude Code의 명시적인 Task 도구 UX가 아직 없습니다. 위임 패턴에는 cloud tasks 또는 SDK orchestration을 사용하세요.
• AGENTS.md는 여러 도구에서 사용할 수 있습니다: AGENTS.md는 Cursor, Copilot, Amp, Jules, Gemini CLI, 그리고 60,000개 이상의 오픈 소스 프로젝트에서 작동합니다. CLAUDE.md는 Claude 전용입니다.
• 프로필이 수동 전환을 대체합니다: 실행할 때마다 플래그를 바꾸는 대신 config.toml에 프로필을 정의하세요.

GitHub Copilot에서 전환

얻을 수 있는 점: - OS 수준 Sandbox (Seatbelt/Landlock — 컨테이너 기반 방식과 달리 커널에서 적용) - codex apply를 통한 cloud task 위임 - 워크플로 전환을 위한 config 프로필 - worktree 격리를 지원하는 데스크톱 앱

Cursor에서 전환

빠른 참조 카드

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                 ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers               ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Aug 2026)                                            ║
║  gpt-5.6-sol           Recommended default ("Power", 272K)    ║
║  gpt-5.6-terra         Everyday model (272K)                  ║
║  gpt-5.6-luna          Fast + affordable (272K)               ║
║  gpt-5.5               Previous-gen flagship (400K in Codex)  ║
║  gpt-5.4 / -mini       Retire from Codex Aug 31, 2026         ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

변경 로그