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

TL;DR: Codex는 코드베이스를 읽고, OS 수준 sandbox에서 명령을 실행하며, 파일을 패치하고, 작업을 클라우드에 위임하는 멀티 서피스 코딩 에이전트입니다. 다섯 가지 핵심 시스템(config.toml, sandbox/approval 모델, AGENTS.md, MCP, skills)을 마스터하면 Codex는 강력한 생산성 도구가 됩니다. 컨텍스트 전환에는 profile을, 컨텍스트 예산 관리에는 /compact를, 지속적인 작업 목표에는 /goal을, Codex, Cursor, Amp 등에서 작동하는 크로스 툴 프로젝트 지침에는 AGENTS.md를 사용하세요. GPT-5.5(2026년 4월 23일 출시)가 Codex의 권장 기본값입니다 — Codex에서 400K 컨텍스트 윈도우(API에서는 1M), MTok당 $5/$30, Terminal-Bench 2.0 SOTA 82.7%입니다.⁸³ CLI v0.130.0(2026년 5월 8일) 기준으로 Codex는 헤드리스 app-server 제어를 위한 최상위 codex remote-control 명령, 멀티 환경 view_image 해상도, AWS aws login console-login 자격 증명을 통한 Bedrock 인증, app-server 스레드 페이지네이션, 공유 링크 메타데이터 및 발견 가능성 제어를 포함한 번들 hooks의 플러그인 세부 정보 가시성, 실행 중인 스레드의 라이브 config 새로 고침, 구성 가능한 OpenTelemetry 추적 메타데이터, 그리고 Linux 및 Windows에서의 지속적인 sandbox 강화를 제공합니다. v0.129.0(2026년 5월 7일)은 모달 Vim 편집(/vim), 재설계된 워크플로우 선택기, TUI 내 /hooks 브라우저, 테마 인식 상태 표시줄, 마켓플레이스 운영을 갖춘 플러그인 작업 공간 공유, 그리고 /goal 라이프사이클 변경을 추가했습니다. 레거시 --full-auto 대신 명시적인 sandbox/approval 플래그 또는 permission profile을 계속 선호하세요. js_repl은 여전히 제거된 상태입니다.^86878991

Codex는 코드를 작성하는 챗봇이 아니라 멀티 서피스 코딩 에이전트로 작동합니다. CLI는 코드베이스를 읽고, sandbox에서 명령을 실행하며, 파일을 패치하고, MCP를 통해 외부 서비스에 연결하고, 장시간 실행되는 작업을 클라우드에 위임합니다. 로컬에서 실행되지만 글로벌하게 사고합니다. 동일한 인텔리전스가 작업 방식에 따라 다섯 가지 서로 다른 서피스를 구동하며, 여기에는 브라우저를 점유하지 않고도 브라우저 안에서 Codex를 실행하는 새로운 Chrome 확장 프로그램도 포함됩니다.⁹⁰

캐주얼한 Codex 사용과 효과적인 Codex 사용의 차이는 다섯 가지 핵심 시스템으로 귀결됩니다. 이를 마스터하면 Codex는 강력한 생산성 도구가 됩니다.

1. Configuration 시스템: config.toml을 통해 동작을 제어합니다
2. Sandbox & approval 모델: Codex가 수행할 수 있는 작업을 제어합니다
3. AGENTS.md: 프로젝트 수준의 운영 계약을 정의합니다
4. MCP 프로토콜: 외부 서비스로 기능을 확장합니다
5. Skills 시스템: 재사용 가능한 도메인 전문성을 패키징합니다

저는 프로덕션 코드베이스, CI/CD 파이프라인, 팀 워크플로우 전반에 걸쳐 Codex를 Claude Code와 함께 수개월 동안 실행했습니다. 이 가이드는 그 경험을 시작할 때 있었더라면 좋았을 완전한 참고 자료로 정리한 것입니다. 모든 기능에는 실제 구문, 실제 구성 예제, 그리고 숙련된 사용자도 걸려 넘어지는 엣지 케이스가 포함되어 있습니다.

안정성 참고 사항: [EXPERIMENTAL] 또는 under development로 표시된 기능은 릴리스 간에 변경될 수 있습니다. v0.130.0(2026년 5월 8일) 기준으로 Codex Cloud와 code mode는 실험적이거나 개발 중이지만, 핵심 CLI, sandboxing, AGENTS.md, config.toml, Skills, hooks, 멀티 에이전트 도구, 그리고 plugins는 안정적인 서피스입니다. v0.130.0은 codex remote-control 최상위 명령(헤드리스, 원격 제어 가능한 app-server를 위한 더 단순한 진입점), 멀티 환경 view_image 해상도, AWS aws login console-login 자격 증명을 통한 Bedrock 인증, unloaded / summary / full turn 뷰가 있는 app-server 스레드 페이지네이션, 공유 링크 메타데이터 및 발견 가능성 제어를 포함한 번들 hooks의 플러그인 세부 정보 가시성, 라이브 app-server config 새로 고침(실행 중인 스레드가 재시작 없이 config 변경을 반영), codex exec 시작 배너에서 “research preview” 문구 제거, 구성 가능한 OpenTelemetry 추적 메타데이터, Linux sandbox 시작 강화, 그리고 데스크톱 런타임 바이너리 캐시에 대한 Windows sandbox 권한 부여를 추가합니다.⁹¹ v0.129.0(2026년 5월 7일)은 컴포저에서의 모달 Vim 편집(/vim + 구성 가능한 기본 모드), 재설계된 TUI 워크플로우 선택기(더 쉬운 resume/fork, 원시 스크롤백), /hooks 브라우저, 선택적 PR + branch 요약이 있는 테마 인식 상태 표시줄, 플러그인 작업 공간 공유 + 마켓플레이스 운영 + 공유 액세스 제어 + 소스 필터링, /goal 라이프사이클 변경(실험적 goal은 명시적으로 다시 활성화되지 않는 한 resume 시 일시 중지 상태를 유지), Linux sandbox 시작 강화, Windows sandbox 안정성 개선, 그리고 업스트림 보안 패치가 포함된 Bubblewrap 0.11.2 업그레이드를 추가했습니다.⁸⁹ v0.128.0(2026년 4월 30일)은 지속되는 /goal 워크플로우, codex update, 구성 가능한 TUI 키맵, 그리고 확장된 permission profile을 도입했습니다. 레거시 --full-auto는 여전히 사용 중단된 상태이며 js_repl은 제거된 상태입니다.⁸⁶⁸⁷

핵심 요약

• 다섯 가지 표면, 하나의 두뇌: CLI, 데스크톱 앱, IDE 확장, 클라우드 작업, 새로운 Chrome 확장 모두 동일한 GPT-5.x-Codex 지능을 공유하므로 워크플로에 맞는 표면을 선택하세요.⁹⁰
• OS 레벨 샌드박싱: 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.4는 1M 컨텍스트를 제공하고, GPT-5.4 mini는 서브에이전트 작업을 위한 400K를 제공하며, GPT-5.3-Codex는 272K 입력을 제공합니다. /compact, 집중된 프롬프트, @file 참조를 사용하여 토큰 예산을 능동적으로 관리하세요.

이 가이드를 사용하는 방법

이 가이드는 2,500줄 이상의 레퍼런스입니다. 본인의 경험 수준에 맞는 곳에서 시작하세요.

문서 끝의 퀵 레퍼런스 카드는 모든 주요 명령어를 한눈에 볼 수 있는 요약을 제공합니다.

Codex 작동 방식: 멘탈 모델

기능을 살펴보기 전에, Codex의 아키텍처가 사용자의 모든 작업을 어떻게 형성하는지 이해해야 합니다. 이 시스템은 공유 지능 계층을 기반으로 네 가지 표면에서 작동합니다.

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  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년 4월 23일 기준, 사용 가능한 경우 gpt-5.5가 권장 모델입니다. Codex에서 400K 컨텍스트(API에서는 1M), Terminal-Bench 2.0 SOTA 82.7%를 제공합니다. gpt-5.4는 롤아웃 기간 동안 폴백 기본값으로 유지됩니다(1M 컨텍스트, 네이티브 computer use).⁸³⁶⁴ 파일을 읽고, 패치를 작성하며, 셸 명령을 실행하고, 코드베이스에 대해 추론합니다. 컨텍스트가 가득 차면 Codex는 대화를 압축하여 공간을 확보합니다. 이 계층은 토큰을 소비합니다.

보안 계층: Codex가 실행하는 모든 명령은 OS 레벨 샌드박스를 거칩니다. macOS에서는 Apple의 Seatbelt 프레임워크가 커널 레벨 제한을 적용합니다. Linux에서는 Landlock + seccomp가 파일시스템 및 시스콜 액세스를 필터링합니다. 샌드박스는 컨테이너 내부가 아닌 커널 레벨에서 작동합니다. 그런 다음 승인 정책이 사용자 확인을 요청할 시점을 결정합니다.

확장 계층: MCP는 외부 서비스(GitHub, Figma, Sentry)와 연결됩니다. Skills는 Codex가 필요할 때 로드하는 재사용 가능한 워크플로를 패키징합니다. Apps는 ChatGPT 커넥터에 연결됩니다. 웹 검색은 인터넷에서 실시간 컨텍스트를 추가합니다.

표면 계층: CLI는 터미널 파워 유저와 자동화용입니다. 데스크톱 앱은 멀티 스레드 프로젝트 관리용입니다. IDE 확장은 편집-컴파일-테스트 루프용입니다. 클라우드는 독립적으로 실행되는 비동기 작업용입니다.

핵심 통찰: 대부분의 사용자는 하나의 표면만 사용합니다. 파워 유저는 네 가지 모두를 사용합니다. 장시간 실행 작업에는 클라우드, 결정론적 리포지토리 작업에는 CLI, 긴밀한 코딩 루프에는 IDE 확장, 계획 및 조정에는 데스크톱 앱을 사용합니다.

목차

1. Codex를 어떻게 설치하나요?
2. 빠른 시작: 첫 세션
3. 핵심 상호작용 표면
4. 설정 시스템 심층 분석
5. 어떤 모델을 선택해야 하나요?
6. Codex 비용은 얼마인가요?
7. 의사결정 프레임워크
8. 샌드박스 및 승인 시스템은 어떻게 작동하나요?
9. AGENTS.md는 어떻게 작동하나요?
10. Hooks
11. MCP(Model Context Protocol)란 무엇인가요?
12. Code Mode
13. JavaScript REPL 런타임
14. Skills란 무엇인가요?
15. 플러그인
16. Plan Mode 및 협업
17. 메모리 시스템
18. 세션 관리
19. 비대화형 모드 (codex exec)
20. Codex Cloud 및 백그라운드 작업
21. Codex 데스크톱 앱
22. GitHub Action 및 CI/CD
23. Codex SDK
24. 성능 최적화
25. 문제를 어떻게 디버깅하나요?
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

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

macOS와 Linux에서는 한 줄짜리 설치 스크립트를 GitHub 릴리스 자산으로 제공해요:⁶⁰

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

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

바이너리 다운로드

npm 또는 Homebrew가 없는 환경에서는 GitHub 릴리스에서 플랫폼별 바이너리를 다운로드하세요¹:

시스템 요구 사항

• macOS: Apple Silicon 또는 Intel (Seatbelt를 통한 전체 sandbox 지원)
• Linux: x86_64 또는 arm64 (Landlock + seccomp를 통한 sandbox)
• Windows: 제한된 토큰을 사용하는 네이티브 sandbox (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로 설정하세요. 일부 기능(클라우드 threads)은 사용할 수 없을 수 있어요.

전문가 팁: 자격 증명 저장 방식은 config.toml의 cli_auth_credentials_store로 설정할 수 있어요. 옵션: file(기본값), keyring(OS 키체인), 또는 auto(사용 가능하면 keyring, 아니면 file로 대체).

Shell 자동 완성

# 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.130.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가 주요 파일을 읽고 코드베이스를 설명해요. 기본 suggest 모드에서는 변경 사항이 만들어지지 않아요.

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는 어떻게 작동하나요? 참조) - 워크플로에 맞는 profile 설정하기 (Profiles 참조) - 비대화형 자동화에 codex exec 사용해 보기 (Non-Interactive Mode 참조)

핵심 인터랙션 표면

Codex는 동일한 인텔리전스를 기반으로 4가지 별개의 인터페이스를 제공합니다. 각 표면은 서로 다른 워크플로우 패턴에 최적화되어 있습니다.

1. 인터랙티브 CLI (Terminal 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는 다음과 같은 요소를 갖춘 풀스크린 애플리케이션입니다:

• Composer: 프롬프트를 입력하고, @로 파일을 첨부하며, ! 접두사로 셸 명령을 실행합니다
• Output pane: 모델 응답, 도구 호출, 명령 출력을 스트리밍합니다
• Status bar: 모델, 토큰 사용량, git 브랜치, 샌드박스 모드를 표시합니다

주요 TUI 단축키:

상태 표시줄 변경 (v0.121.0): 상태 표시줄의 기존 컨텍스트 윈도우 미터가 컨텍스트 윈도우가 얼마나 채워졌는지 보여주는 컨텍스트 백분율 인디케이터로 대체되었습니다. 상태 표시줄을 파싱하는 스크립트나 hooks가 있다면 이 형식 변경을 확인하세요.⁸² 또한 새 버전이 출시되면 Codex는 CLI 업데이트 알림을 표시합니다.

TUI에서 사용 가능한 슬래시 명령:

워크플로우 피커 재설계 (v0.129.0): 재설계된 피커에서 resume과 fork에 더 쉽게 접근할 수 있게 되었으며, 새로운 raw 스크롤백 모드를 통해 명령이나 모델 출력을 그대로 복사해야 할 때 렌더링되지 않은 트랜스크립트를 스크롤할 수 있습니다. 긴 디버깅 세션을 분류하거나 출력을 다른 도구로 파이핑할 때 유용합니다.⁸⁹

2. Codex Desktop App (macOS + Windows)

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

데스크톱 앱은 CLI에 없는 기능을 추가합니다:

• 멀티태스킹: 서로 다른 프로젝트에서 여러 병렬 에이전트를 동시에 실행
• Git worktree 격리: 각 스레드가 리포지토리의 격리된 사본에서 작업
• 인라인 diff 리뷰: 앱을 떠나지 않고 변경 사항을 스테이징, 되돌리기, 커밋
• 통합 터미널: 명령 실행을 위한 스레드별 터미널
• 대화 포킹: 대안을 탐색하기 위해 대화를 분기
• 플로팅 팝아웃 윈도우: 대화를 휴대 가능한 윈도우로 분리
• 자동화: 반복 작업 예약 (이슈 분류, CI 모니터링, 알림 응답)

앱과 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가 관리하는 환경에서 비동기적으로 실행됩니다:

• Fire and forget: 로컬 머신과 독립적으로 실행되는 작업을 큐에 추가
• 병렬 실행: 여러 클라우드 작업을 동시에 실행
• PR 생성: Codex가 완료된 작업으로부터 풀 리퀘스트를 생성
• 로컬 적용: 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. Codex for Chrome [NEW]

Codex는 Chrome용 브라우저 확장으로 출시되어 CLI, 데스크톱 앱, IDE 확장, 클라우드와 함께 다섯 번째 표면을 추가합니다. 이 확장은 일반적인 브라우징을 대체하기보다는 함께 동작하도록 설계되었습니다: Codex는 백그라운드에서 탭 전반에 걸쳐 병렬로 작동하며, 어떤 사이트에 접근할지에 대한 통제권은 사용자에게 있습니다.⁹⁰

• 병렬 탭 실행: Codex는 포그라운드 탭을 잠그지 않고 여러 탭에서 동시에 작동합니다.
• 사이트별 제어: Codex가 상호작용할 수 있는 웹사이트를 허용 목록으로 지정합니다; 기본값은 접근 차단입니다.
• 워크벤치로서의 브라우저: 이 확장은 페이지가 진실의 원천인 앱 및 웹사이트 작업—관리 콘솔, 내부 대시보드, 콘텐츠 관리 UI, 티켓 시스템—에 가장 적합하며, 로컬 리포지토리에서의 CLI를 대체하지 않습니다.
• 동일한 두뇌: Codex for Chrome은 다른 표면들이 사용하는 것과 동일한 GPT-5.x-Codex 인텔리전스를 실행하므로, CLI에서 작동하는 AGENTS.md 또는 skills 구성이 브라우저 기반 작업에 동일한 컨벤션으로 적용됩니다.

Codex Chrome extension docs에서 설치하세요.⁹⁰

설정 시스템 심층 분석

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은 일반적인 설정 병합 후에 사용자가 선택할 수 있는 값을 제한하는 정책 제약 계층으로 작동합니다. Enterprise Deployment를 참조하세요.

설정 파일 위치

전문가 팁: CODEX_HOME 환경 변수는 기본 ~/.codex 디렉터리를 오버라이드합니다. CI/CD 또는 다중 계정 설정에 유용합니다.

전체 설정 레퍼런스

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.5"                      # Recommended model when available
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
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

# ─── 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)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── 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.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

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

[profiles.auto]
model = "gpt-5.4"
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.
[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 wire API (wire_api = "chat")는 OpenAI 호스팅 모델에서 사용 중단(deprecated)되었으며, 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"

어떤 모델을 선택해야 하나요?

사용 가능한 모델 (2026년 4월)

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

GPT-5.4는 모든 Codex 표면(CLI, 앱, IDE 확장, 클라우드)에서 계속 사용할 수 있습니다.⁶⁴ 정확한 모델 목록은 계정 및 배포에 따라 다릅니다. 로컬 캐시를 확인하세요: ~/.codex/models_cache.json.

사용 중단 안내 (2026년 3월 11일): GPT-5.1 모델은 더 이상 ChatGPT에서 사용할 수 없습니다. 기존 대화는 GPT-5.3 Instant, GPT-5.4 Thinking 또는 GPT-5.4 Pro에서 자동으로 계속됩니다. GPT-5.1-Codex-Mini는 비용 민감 워크로드를 위해 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일): MTok당 $0.75/$4.50 가격에 400K 컨텍스트를 제공하는 더 작고 빠른 GPT-5.4 변형 — GPT-5.4 할당량의 30%만 사용합니다. Subagent 위임에 이상적입니다. GPT-5.4가 계획 및 조정을 처리하는 동안 GPT-5.4 mini subagent가 더 좁은 하위 작업(코드베이스 검색, 파일 검토, 문서 처리)을 병렬로 처리하도록 합니다.⁷⁶

모델 선택 플로우차트

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ 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.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

추론 노력

응답하기 전에 모델이 얼마나 “생각”할지 제어합니다:

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

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 / -m을 통해 실행별로 설정합니다:

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

Codex 비용은 얼마인가요?

기능별 정보는 모델 선택을, 작업별 모델 선정 방법은 의사결정 프레임워크를 참조하세요.

ChatGPT 플랜별 액세스

Codex 사용 가능 여부는 ChatGPT 플랜과 조직 설정에 따라 달라집니다:⁵¹

2026년 4월 가격 업데이트: Business 연간 가격이 시트당 월 $25에서 $20로 인하되었습니다. 사용량 기반 가격의 Codex 전용 시트가 이제 Business 및 Enterprise 워크스페이스에서 제공되며, 고정 시트 비용 없이 토큰 소비량에 따라 청구됩니다.⁷⁹ 유료 플랜 대상 프로모션 사용 한도 2배 혜택(2026년 2월 Desktop App 출시 당시 도입)은 계속 유지됩니다.¹⁶

2026년 5월 사용 한도 상향 (2026년 5월 31일까지): Plus 플랜의 Codex는 25배 5시간 한도로 실행되며(표준 20배 상향 대비), $100/월 등급은 같은 기간 동안 두 배로 늘어납니다. 이 기간을 활용하면 평소의 5시간 한도에 부딪히지 않고 더 긴 클라우드 작업 배치나 더 높은 처리량의 에이전트 실행을 진행할 수 있습니다.⁸⁹

크레딧 비용

Codex 작업은 플랜 할당량에서 크레딧을 소비합니다:

Enterprise 및 Edu 플랜은 계약 할당에 따라 크레딧이 확장됩니다. TUI에서 /status를 확인하여 현재 사용량을 점검하세요.

API 청구

API를 통해 Codex를 사용하는 경우, OpenAI는 선택한 모델에 대한 표준 OpenAI API 가격(적용 가능한 prompt-caching 할인 포함)에 따라 토큰당 사용량을 청구합니다. 현재 요율은 공식 API 가격 페이지에서 확인하세요.²⁰

비용 최적화 전략

1. 프로필 활용: 일상적인 작업에는 gpt-5.1-codex-mini와 model_reasoning_effort = "low"를 사용하는 fast 프로필을 만드세요
2. 고수준 추론은 아껴 쓰기: 토큰을 3-5배 더 소비하므로 xhigh는 정말 어려운 문제에만 사용하세요
3. --ephemeral 사용: CI/CD에서 세션 영속성을 건너뛰어 오버헤드를 줄이세요
4. 추론 요약 최소화: 설명이 필요 없을 때는 model_reasoning_summary = "none"으로 설정하세요
5. exec 모드로 일괄 처리: codex exec는 자동화 워크플로의 TUI 오버헤드를 회피합니다
6. 사용량 모니터링: TUI의 /status와 조직 청구 대시보드를 확인하세요

실제 비용 예시

일반적인 작업에 대한 대표적인 API 비용 (gpt-5.3-codex 표준 가격, medium 추론 기준):

비용은 추론 강도, 캐싱, 대화 길이에 따라 달라집니다. 일상적인 작업에는 gpt-5.1-codex-mini를 사용하면 비용을 약 40-60% 절감할 수 있습니다. 캐시된 입력 토큰은 할인된 가격으로 청구됩니다.

숨겨진 토큰 오버헤드

모든 도구 호출은 보이는 프롬프트 외에 추가 토큰을 소비합니다:

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

팀 비용 관리

팀 비용 통제 전략: - requirements.toml 설정으로 조직 전반에 모델 및 추론 강도 한도를 적용하세요 - CI/CD에는 gpt-5.1-codex-mini 사용 — 자동화된 파이프라인은 최대 추론 수준이 거의 필요하지 않습니다 - 프로필 기반 예산 책정 — 적절한 비용 상한을 가진 ci, review, dev 프로필을 정의하세요 - OpenTelemetry로 모니터링 — 엔터프라이즈 배포는 사용량 텔레메트리를 기존 관측성 스택으로 내보낼 수 있습니다

의사 결정 프레임워크

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

각 sandbox 모드를 사용해야 할 때

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

Plan 모드 vs 직접 실행

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 vs Tab

경험 법칙: Enter = “지금 멈추고 이걸 들으세요.” Tab = “끝나면 이것도 해주세요.”

Desktop App vs 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.1-codex-mini"
model_reasoning_effort = "low"

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

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

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

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

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

Codex는 기술적으로 가능한 것과 Codex가 사람의 승인을 요청하는 시점을 분리하는 2계층 보안 모델을 사용합니다. 이 접근 방식은 Claude Code의 권한 시스템과 근본적으로 다릅니다 — Codex는 OS 커널 수준에서 제한을 적용합니다.⁵ 관리자가 조직 전체에 적용하는 requirements.toml 제약 조건에 대해서는 Enterprise Deployment도 참고하세요.

계층 1: 샌드박스 (무엇이 가능한가)

샌드박스는 OS 네이티브 메커니즘을 사용해 파일시스템 및 네트워크 접근을 제어합니다:

플랫폼별 적용 방식:

• macOS: Apple의 Seatbelt 프레임워크를 sandbox-exec를 통해 사용하며, 모드별 프로파일이 런타임에 컴파일되어 커널에 의해 적용됩니다⁶. v0.121.0부터 macOS 샌드박스 프로파일은 특정 Unix 소켓(예: docker.sock, 에디터 IPC 소켓)을 허용 목록에 추가할 수 있으며 프라이빗 DNS 해석은 더 이상 기본적으로 차단되지 않습니다.⁸²
• Linux: 파일시스템 제한을 위한 Landlock + 시스템콜 필터링을 위한 seccomp. 독립 헬퍼 프로세스(codex-linux-sandbox)가 심층 방어 격리를 제공합니다.⁵ Bubblewrap(bwrap)은 벤더링되어 Linux 빌드의 일부로 컴파일됩니다(v0.100.0에서 선택 사항에서 승격됨)⁷. v0.117.0은 레거시 커널 구성을 가진 구형 배포판에서 샌드박스 안정성을 개선했습니다.⁷⁵ v0.129.0은 Linux에서 샌드박스 시작을 강화하고 벤더링된 Bubblewrap을 업스트림 보안 패치가 포함된 0.11.2로 업그레이드했으며, v0.130.0은 추가 시작 강화를 추가했습니다.⁸⁹⁹¹
• Windows: 제한된 토큰을 사용하는 네이티브 샌드박스(v0.100.0에서 실험적 단계에서 승격됨). WSL도 지원됩니다(Linux Landlock + seccomp 상속). v0.117.0에는 더 나은 프로세스 격리를 위한 제한 토큰 샌드박스 개선이 포함됩니다.⁷⁵ v0.130.0은 샌드박스 사용자에게 데스크톱 런타임 바이너리 캐시 접근을 부여하여 Windows 샌드박스가 workspace-sandbox 사용자에 대해 런타임 바이너리를 안정적으로 해석할 수 있도록 합니다.⁹¹

이것이 중요한 이유: 컨테이너 기반 샌드박싱(Docker)과 달리, OS 수준 샌드박싱은 더 빠르고, 더 가볍고, 탈출하기 더 어렵습니다. 커널은 Codex가 시스템 호출을 보기도 전에 제한을 적용합니다.

보안 수정 사항: - zsh-fork 샌드박스 우회 (v0.106.0): zsh 포킹을 통한 셸 실행이 샌드박스 제한을 우회할 수 있는 취약점을 수정했습니다.⁶⁰ 이전 버전을 사용 중이라면 즉시 업그레이드하세요. - 입력 크기 상한 (v0.106.0): Codex는 이제 과도하게 큰 페이로드로 인한 정지를 방지하기 위해 약 100만 자의 입력 상한을 적용합니다.⁶⁰ - 보안 devcontainer 프로파일 (v0.121.0): Docker devcontainer를 위한 새로운 강화된 고객 프로파일은 컨테이너 내부 샌드박싱에 Bubblewrap을 사용합니다. WSL2는 지원되며; WSL1은 명시적으로 거부됩니다(Bubblewrap은 WSL1의 커널 shim과 호환되지 않음).⁸² - Guardian 검토 + hooks (v0.121.0): Guardian 검토 세션 중에는 hooks가 비활성화되어 pre/post-tool hooks가 Guardian 서브에이전트의 결정에 간섭할 수 없습니다.⁸² 로깅이나 검증을 위해 hooks에 의존하고 있다면, Guardian 검토는 이를 건너뛴다는 점을 인지하세요 — 전체 감사 추적이 필요한 경우 app-server observability에 의존하세요. - Linux /dev 파일시스템 (v0.105.0): Linux의 샌드박스 명령은 이제 최소한의 /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+)

승인 흐름은 이제 추가 샌드박스 권한과 세분화된 거부를 지원합니다:⁶¹

• 추가 샌드박스 권한: 명령이 현재 샌드박스 모드를 넘어선 접근을 필요로 할 때, Codex는 전체 모드 변경을 요구하는 대신 특정 추가 권한을 요청할 수 있습니다
• 세분화된 거부: 피드백과 함께 개별 도구 호출을 거부하면 Codex가 같은 명령을 단순히 재시도하는 대신 접근 방식을 조정할 수 있습니다

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

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

권한 프로파일 (v0.113.0+, v0.128.0에서 확장됨)

권한 프로파일은 파일시스템과 네트워크 샌드박스 정책을 명명된 재사용 가능한 섹션으로 분리합니다. default_permissions를 :read-only, :workspace, :danger-no-sandbox와 같은 내장 프로파일로 설정하거나, 사용자 지정 [permissions.<name>] 테이블을 가리키도록 설정하세요.⁸⁷

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"

프로젝트 루트가 쓰기 가능하더라도 읽을 수 없어야 하는 민감한 파일과 glob에는 none을 사용하세요. 일회성 명령 예외에는 프로파일을 광범위하게 확장하기보다 규칙을 선호하세요.⁸⁷

레거시 --full-auto 가이던스

오래된 가이드들은 --full-auto를 다음의 편의 별칭으로 설명했습니다:

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

v0.128.0의 릴리스 노트는 --full-auto를 사용 중단으로 표시하며, 현재 CLI 도움말에서는 더 이상 대화형 실행에 이를 나열하지 않습니다. 대신 위의 명시적 플래그나 명명된 권한 프로파일을 사용하세요.⁸⁶

샌드박스 안정성 (v0.129.0): Linux 샌드박스 시작 강화는 느린 파일시스템이나 심볼릭 링크된 체크아웃에서의 경합을 줄이고; Windows 샌드박스 안정성 개선은 장시간 실행 중의 여러 엣지 케이스 충돌을 해결하며; 벤더링된 Bubblewrap은 업스트림 보안 패치가 포함된 0.11.2로 업그레이드됩니다. 구성 변경은 필요하지 않습니다. 이를 적용하려면 codex update를 실행하세요.⁸⁹

권장 구성

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

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

파워 유저 (전체 접근, human-in-the-loop):

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

이 조합은 커뮤니티에서 권장하는 “sweet spot”입니다: 최대 권한이지만 모든 명령에 승인이 필요합니다.⁸

CI/CD 자동화:

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

Guardian 서브에이전트와 함께하는 Smart Approvals (v0.115.0+)

Smart Approvals는 모든 작업에 대해 사람의 승인을 요구하는 대신 검토 요청을 guardian 서브에이전트를 통해 라우팅할 수 있습니다. guardian 세션은 승인 사이에 지속되어 prompt cache를 재사용하고 시작 오버헤드를 피합니다. 각 검토는 깨끗한 기록을 받습니다(이전 결정이 이후 검토로 새지 않음).⁷³

config.toml에서 리뷰어를 구성하세요:

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

이는 일괄적인 approval_policy = "never" 대신 추론을 동반한 자동화된 검토를 원하는 CI/CD 워크플로에 특히 유용합니다.

네트워크 접근 활성화

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+)을 보완하여 모든 전송 계층을 다룹니다.

샌드박스 테스트

샌드박스를 신뢰하기 전에 그 동작을 검증하세요:

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

샌드박스가 올바르게 작동하고 있다면, workspace 범위의 프로파일에서 두 명령 모두 권한 거부 오류로 실패해야 합니다. 둘 중 하나라도 성공한다면, 샌드박스 구성을 조사할 필요가 있습니다.

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

AGENTS.md는 Codex의 프로젝트 지침 시스템입니다. 이제 Linux Foundation의 Agentic AI Foundation이 관리하는 오픈 표준⁹이며, 특정 저장소나 디렉터리 안에서 Codex가 어떻게 동작하는지 정의합니다. Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode, 그리고 60,000개 이상의 오픈 소스 프로젝트가 이를 지원합니다. 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

훌륭한 AGENTS.md의 조건

Codex 자체의 직접적인 안내와 커뮤니티 패턴¹⁰을 바탕으로 정리하면 다음과 같습니다.

권장: - 구체적으로 작성하세요. "search efficiently"보다 "Use rg --files for discovery"가 더 낫습니다. - 완료 기준을 정의하세요. “완료”는 무엇을 의미하나요? (테스트 통과, lint 정리 등) - 명령을 포함하세요. 빌드, 테스트, lint, format 명령을 정확히 적습니다. - 작업별로 구성하세요. 코딩, 리뷰, 릴리스, 사고/디버그 섹션처럼 나눕니다. - 에스컬레이션을 정의하세요. 막히거나 예상치 못한 상태를 만났을 때 무엇을 해야 하는지 적습니다.

비권장: - 실행 규칙 없이 전체 스타일 가이드를 그대로 넣지 마세요. - 모호한 지시를 사용하지 마세요. (“주의하기”, “최적화하기”) - 서로 충돌하는 우선순위를 섞지 마세요. (속도 + 빠짐없는 검증 + 런타임 예산 없음) - 문서용 설명문처럼 쓰지 마세요. 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.

Agent 세션의 비밀 정보 처리

Codex가 볼 수 있는 기록은 단순한 소스 코드가 아니라 보안 표면으로 다루세요. Codex 릴리스 노트에는 shell 스냅샷과 환경 변수 수정 작업이 기록되어 있고, 메모리 시스템은 메모리 쓰기에서 비밀 정보를 스캔합니다. 하지만 이런 보호 장치가 명령 출력, 세션 기록, shell 스냅샷, 로컬 로그, 헬퍼 스크립트를 자격 증명을 출력해도 되는 안전한 장소로 바꿔 주지는 않습니다.³⁷⁵⁵⁹⁵

운영 규칙은 단순합니다. 모델이 검사하도록 비밀 정보를 출력하지 마세요. 헬퍼 자격 증명은 환경이 요구하는 설정에 보관하세요. 감사할 때는 실행 가능한 소스, 문서, 생성된 캐시, 세션 기록, shell 스냅샷, 로그, 의도적인 비밀 정보 저장소를 분리하세요. 신뢰도 높은 비밀 정보 형태가 나타나면 로컬 기록을 수정하세요. 수동 위생 루프가 입증된 뒤에만 예방 hooks를 도입하세요. 공개적으로 공유할 교훈은 표면 지도와 수락 기준이지, 비공개 토큰 값이나 정확한 경로, 탐지기 내부 구조가 아닙니다.⁹⁵

Override 메커니즘

어느 디렉터리 수준이든 AGENTS.override.md는 해당 범위의 일반 AGENTS.md를 대체합니다. 다음 용도로 사용하세요.

• 릴리스 동결: “새 기능 금지, 수정만 허용”
• 사고 대응 모드: “모든 변경은 on-call의 검토를 받아야 함”
• 임시 강화: “이번 sprint에는 dependency 업데이트 금지”

설정

# 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는 안정화되었습니다.⁸⁵ 이제 hooks는 config.toml과 requirements.toml 안에서 인라인으로 설정할 수 있습니다. 더 이상 별도의 hook 스크립트 파일이 필요하지 않습니다. 또한 apply_patch 및 장시간 실행되는 Bash 세션과 함께 MCP tools도 관찰합니다. 이 시스템은 이제 세션 생명 주기와 tool 수준 자동화를 모두 다루며, 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의 stdout은 모델 컨텍스트로 들어가므로, 세션 시작 시 동적 정보(날짜, branch 이름, 환경 변수)를 주입하기에 적합합니다.

Claude Code Hook 패턴 복제하기

Claude Code에서 이전하는 경우, 비슷한 자동화를 구현하는 방법은 다음과 같습니다.

전문가 팁: v0.124.0(2026년 4월 23일)부터 hooks 엔진은 안정화되었습니다. 새로운 hook 이벤트는 여전히 릴리스에 포함됩니다. Codex changelog를 확인하세요.

TUI 내부 hook 브라우저(v0.129.0): TUI에서 /hooks를 실행하면 사용 가능한 hooks를 찾고, 현재 활성화된 항목을 확인하며, config.toml을 편집하지 않고 개별 hooks를 전환할 수 있습니다. 문제가 있는 plugin-bundled hook을 조사하거나 집중 편집 세션을 위해 AfterToolUse linter를 임시로 비활성화할 때 유용합니다.⁸⁹

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

MCP는 외부 도구와 서비스에 연결해 Codex의 기능을 확장해요. codex mcp 명령 그룹은 현재 experimental로 표시되어 있으며, 명령과 설정 형식은 릴리스 사이에 바뀔 수 있어요. Codex는 STDIO(로컬 프로세스)와 Streamable HTTP(원격 서버)라는 2가지 전송 방식을 지원해요.¹¹

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

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는 빠른 응답을 유지해요.

Plugin MCP 로딩(v0.123.0+)은 .mcp.json에서 표준 mcpServers 스키마와 최상위 서버 맵을 모두 허용하므로, 어느 규칙으로 작성된 plugins라도 깔끔하게 로드돼요.⁸⁴

Codex를 MCP 서버로 실행하기

Codex는 멀티 에이전트 오케스트레이션을 위해 자기 자신을 MCP 서버로 노출할 수 있어요.¹²

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

서버는 2가지 도구를 노출해요: 1. codex(): 프롬프트, sandbox, 모델, 승인 매개변수로 새 세션을 시작해요 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: 컨텍스트 인식 개발 — Context7을 프레임워크 문서와 함께 사용하면 Codex가 항상 최신 API 참조를 갖게 돼요:

[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 거버넌스 — requirements.toml을 통해 개발자가 사용할 수 있는 MCP 서버를 제한하세요:

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

requirements.toml의 ID와 일치하지 않는 모든 서버는 시작 시 차단돼요. 전체 정책 설정은 Enterprise Deployment를 참고하세요.

Code Mode [EXPERIMENTAL]

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

이 기능은 experimental이에요. 업데이트는 릴리스 노트를 확인하세요.

JavaScript REPL 런타임 [REMOVED]

Codex v0.100.0은 experimental JavaScript REPL 런타임(js_repl)을 추가했고, v0.106.0에서는 이를 /experimental 표면으로 승격했어요.⁶⁰ 이제 그 안내는 과거 기록이에요. v0.128.0 릴리스 changelog에는 “Remove js_repl feature”가 포함되어 있으며, 현재 기능 목록에서는 js_repl과 js_repl_tools_only가 모두 제거된 것으로 표시돼요.⁸⁶

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

Skills란 무엇인가요?

Skills는 Codex가 필요할 때 불러오는 재사용 가능한 작업별 기능 패키지예요. 공개 agent 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/ 아래에는 기본 제공 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)

Metadata (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인 경우)
• Creator: $skill-creator를 사용해 새 skill을 대화형으로 만들어요
• Installer: $skill-installer install <name>을 사용해 커뮤니티 skills를 설치해요

활성화/비활성화

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

Skills와 Slash Commands 비교

Skills 디버깅

skill이 활성화되지 않는 경우:

1. 검색 확인: /skills가 TUI에 해당 skill을 표시해야 해요
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 용어를 포함하세요

프로덕션 예시: Deploy Skill

참조와 scripts가 함께 작동하는 완전한 다중 파일 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, app connectors를 하나의 설치 가능한 패키지로 통합해요(v0.110.0+).⁶⁵ v0.117.0부터 plugins는 1급 구성 요소가 되었어요. product-scoped plugins는 시작 시 자동으로 동기화되고, /plugins는 검색과 관리를 위한 TUI 내 브라우저를 제공해요.⁷⁵ v0.128.0에서는 marketplace 설치, 원격 bundle caching, 원격 제거 APIs, plugin-bundled hooks, hook 활성화 상태, external-agent config 가져오기로 plugin 워크플로가 확장됐어요.⁸⁶ v0.129.0(2026년 5월 7일)에는 plugin workspace sharing(다시 게시하지 않고 plugin 세트를 팀원에게 푸시), share access controls(수신자별 활성화/비활성화, 취소), source filtering(workspace가 가져올 marketplaces 제한), 그리고 CLI 대신 /plugins 브라우저에서 직접 호출할 수 있는 marketplace operations가 추가됐어요.⁸⁹ v0.130.0(2026년 5월 8일)은 plugin packaging을 더 투명하게 만들고 share workflow를 더 세밀하게 제어할 수 있게 해요.⁹¹

• Bundled hooks가 plugin details에 표시돼요. 이제 /plugins 상세 보기에는 plugin이 번들로 포함하는 모든 lifecycle hook(SessionStart, UserPromptSubmit, Stop 등)이 표시돼요. plugin을 설치하기 전에 해당 plugin이 세션에 정확히 어떤 hooks를 등록할지 확인할 수 있어요. 이제 도구만 믿고 설치한 plugin에서 예상치 못한 hook 부작용이 생기는 일을 줄일 수 있어요.
• Plugin share metadata가 shareContext에 포함돼요. workspace에서 plugin이 공유되면 이제 share-link payload가 링크 metadata(creator, scope, freshness)를 노출해요. 그래서 수신 세션은 출처를 보여주고 수락 여부를 판단할 수 있어요.
• Share settings의 discoverability controls. Share settings는 discoverability 토글을 제공해요. 팀은 plugins를 조직 전체에서 일반적으로 목록화하지 않고도 특정 workspaces나 수신자 목록에 게시할 수 있어요.

Plugin Sources

Plugin Discovery

Codex는 세션 시작 시 어떤 plugins가 활성화되어 있는지 model에 알려줘요(v0.111.0). 이로 인해 설치된 MCPs, apps, skills의 검색성이 향상돼요.⁶⁵ model은 작업 context를 기반으로 세션 중 관련 plugins를 제안할 수 있어요. v0.117.0에서는 product-scoped plugins가 시작 시 동기화되어, 수동 개입 없이 최신 plugin catalog를 사용할 수 있어요.⁷⁵

@plugin Mentions (v0.112.0+)

채팅에서 설치된 plugin을 @plugin-name으로 직접 참조할 수 있어요.⁶⁸ plugin을 언급하면 해당 context(기능, 도구, 설정)가 model의 context window에 자동으로 포함돼요. plugin이 무엇을 하는지 따로 설명할 필요가 없어요.

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

이는 custom skills, MCP 서버, app connectors를 포함해 설치된 모든 plugin에서 작동해요.

Plugin Marketplace (v0.113.0+)

이제 plugin marketplace에는 metadata, categories, ratings를 포함한 더 풍부한 검색 기능이 들어 있어요.⁶⁹ 설치 시 auth checks는 API keys 또는 OAuth가 필요한 plugins에 유효한 credentials가 있는지 설치 전에 확인해요. 제거 endpoint는 plugins와 관련 설정을 깔끔하게 제거해요.

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

현재 OpenAI Codex 문서는 marketplace source 관리를 codex plugin marketplace 아래에 두고 있어요. 이는 OpenAI의 first-party marketplace를 넘어 third-party plugin 배포를 공식화하며, GitHub repo shorthand, HTTP(S) Git URLs, SSH URLs, 로컬 marketplace root directories를 지원해요. 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 [email protected]: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와 함께 /plugins 브라우저에 표시돼요. App-server callers(IDE/desktop integrations)는 marketplaces를 프로그래밍 방식으로 등록할 수 있는 병렬 endpoint를 가지고 있어요.⁸²

보안 고려 사항: Third-party marketplaces는 Codex 권한으로 임의의 plugin code를 실행해요. 추가하기 전에 sources를 검토하고, 첫 실행 중에는 sandboxed execution을 선호하세요.

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 config, skill 설치, app connector 설정이 필요했던 작업을 통합해요. 하나의 plugin이 이 세 가지를 모두 번들로 포함할 수 있어 팀 onboarding이 빨라지고 설정 이식성이 높아져요.

플랜 모드 및 협업

플랜 모드를 사용하면 Codex가 변경 사항을 실행하기 전에 접근 방식을 설계할 수 있습니다. v0.94.0부터 기본적으로 활성화되어 있습니다.¹⁴ “Plan Mode vs Direct Execution” 의사 결정 트리는 Decision Frameworks를 참조하세요.

플랜 모드 진입

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

플랜 모드에서 Codex는 다음을 수행합니다: - 파일을 읽고 코드베이스를 분석합니다 - 구현 계획을 제안합니다 - 사용자가 승인하기 전까지는 변경을 수행하지 않습니다 - 전용 TUI 뷰에 계획을 스트리밍합니다

스티어 모드 (Steer Mode)

스티어 모드(v0.98.0부터 기본 활성화)를 사용하면 Codex가 현재 작업을 중단하지 않고도 적극적으로 작업하는 동안 새로운 지침을 주입할 수 있습니다.¹⁴

주입 방법은 두 가지입니다:

실용적인 예시:

# 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

스티어 모드는 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부터 실시간 음성 세션은 마이크와 스피커 디바이스 선택을 지원하므로, 특정 오디오 입력/출력 하드웨어를 선택할 수 있습니다.⁶²

기타 개선 사항: - 긴 링크가 TUI 라인을 가로질러 줄바꿈되어도 클릭 가능 상태를 유지합니다 (v0.105.0)⁶¹ - 로컬 파일 링크가 개선된 형식으로 렌더링됩니다 (v0.106.0)⁶⁰ - 서브 에이전트에 대한 Ctrl+C 처리가 자식 프로세스를 올바르게 종료하도록 수정되었습니다 (v0.106.0)⁶⁰

메모리 시스템

Codex에는 세션 전반에 걸쳐 사실, 기본 설정, 프로젝트 컨텍스트를 저장하는 영구 메모리 시스템(v0.100.0+)이 있습니다.²⁴

메모리 명령어

메모리는 ~/.codex/memory/ 아래의 마크다운 파일에 저장됩니다. Codex는 세션 시작 시 이를 로드하여 향후 모든 세션에서 동작에 반영합니다.

무엇을 저장해야 하는가

메모리는 영구적인 기본 설정과 프로젝트 사실을 저장하는 데 가장 적합합니다:

• 프로젝트 컨벤션: “이 프로젝트는 스페이스가 아닌 탭을 사용합니다” 또는 “API 응답에는 항상 meta 필드가 포함됩니다”
• 도구 기본 설정: “npm 대신 pnpm을 사용하세요” 또는 “pytest -x --tb=short로 테스트를 실행하세요”
• 아키텍처 결정: “auth 모듈은 src/middleware/가 아니라 src/core/auth/에 있습니다”
• 워크플로우 기본 설정: “diff를 보여주기 전에 항상 linter를 실행하세요”

파이프라인에서의 메모리

codex exec를 실행할 때 메모리는 자동으로 로드됩니다. 즉, CI/CD 파이프라인과 스크립트도 대화형 세션과 동일한 컨텍스트의 이점을 누릴 수 있으며, 매번 호출할 때마다 지침을 반복할 필요가 없습니다.

메모리 개선 사항 (v0.101.0–v0.107.0)

• 시크릿 새니타이즈: 메모리는 디스크에 기록되기 전에 자동으로 시크릿 검사를 거칩니다
• CWD 인식: 메모리 파일에 이제 프로젝트별 회수를 위한 작업 디렉터리 컨텍스트가 포함됩니다
• 개발자 메시지 제외: 개발자/시스템 메시지는 phase-1 메모리 입력에서 제외되어 사용자 상호작용에 집중함으로써 메모리 품질이 향상됩니다
• Diff 기반 잊기 (v0.106.0): 이제 메모리는 diff 기반 잊기를 사용하여 오래된 사실을 제거하므로, 시간이 지나도 메모리 저장소가 간결하고 관련성 있게 유지됩니다⁶⁰
• 사용량 인식 선택 (v0.106.0): 메모리 회수가 이제 사용량을 인식하여, 자주 액세스되고 최근에 관련성이 있는 메모리를 우선시합니다⁶⁰
• 구성 가능한 메모리 (v0.107.0): 이제 메모리는 완전히 구성 가능합니다. codex debug clear-memories를 사용하여 저장된 모든 메모리를 깨끗한 상태로 초기화할 수 있으며 — 관련 없는 프로젝트 간에 컨텍스트를 전환하거나 메모리 상태가 표류했을 때 유용합니다⁶²
• Phase-2 모델 업그레이드 (v0.121.0): phase-2 메모리 통합 모델이 이제 gpt-5.4입니다(이전 기본값에서 업그레이드). phase-2 파이프라인은 세션 사이에 실행되어 phase-1 트랜스크립트를 영구적인 사실로 증류하며, 모델 변경으로 동일한 토큰 비용에서 회수 품질이 향상됩니다.⁸²
• TUI 메모리 메뉴 (v0.121.0): 새로운 세션 내 UI는 메모리 모드, 개별 메모리 삭제, 리셋 버튼을 노출합니다. 이제 메모리 리셋은 과거 롤아웃을 무효화하지 않고 보존하므로, 리셋 시 세션 재생을 깨뜨리지 않으면서 미래 회수 영역만 지웁니다.⁸²

메모리 vs AGENTS.md

팁: 무기한으로 지속되어야 할 사실에는 /m_update를 사용하세요. 세션별 컨텍스트는 대화에서 Codex에게 직접 알려주면 됩니다. 팀 공유 컨텍스트에는 AGENTS.md를 사용하세요.

세션 관리

Codex는 세션을 ~/.codex/sessions/ 아래에 영속화하여 CLI와 데스크톱 표면 전반에서 재개, 포크, 다중 스레드 워크플로우를 가능하게 합니다.

재개

중단했던 곳에서 이어서 작업하세요:

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 슬래시 명령어는 검색 기능이 있는 동일한 대화형 픽커를 엽니다.

포크

현재 진행 상황을 잃지 않으면서 대안을 탐색하기 위해 대화를 분기하세요:

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

포크는 포크 지점까지 동일한 히스토리를 공유하는 독립적인 스레드를 생성합니다. 한 포크의 변경 사항은 다른 포크에 영향을 주지 않습니다. 이는 접근 방식을 비교하거나(예: “포크해서 Memcached 대신 Redis를 시도해보세요”) 위험한 변경 사항을 안전하게 탐색하는 데 유용합니다.

스레드를 서브 에이전트로 포크 (v0.107.0): 이제 스레드를 독립적인 서브 에이전트로 포크할 수 있어, 대화가 자율적으로 실행되는 병렬 작업 스트림을 생성할 수 있습니다. 이는 기존 포크 모델을 확장한 것으로 — 단순히 대화를 분기하는 대신, 포크된 스레드가 자체 실행 컨텍스트를 가진 서브 에이전트가 됩니다.⁶² v0.117.0부터 서브 에이전트는 구조화된 에이전트 간 메시징과 함께 경로 기반 주소(예: /root/agent_a)를 사용하여, 다중 에이전트 조율을 더 명시적이고 디버깅하기 쉽게 만듭니다.⁷⁵

스레드 목록

활성 세션을 보고 관리하세요:

/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 파이프라인과 조합하여 사용할 수 있습니다.

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 런타임에 대한 단일하고 안정적인 진입점을 서드파티 도구에 제공합니다.⁹¹

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

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

대용량 스레드 이력을 메모리에 한 번에 모두 하이드레이션하지 않고 열거해야 하는 UI를 구축할 때는 아래 app-server 페이지네이션 APIs와 codex remote-control을 함께 사용하세요.

App-Server 스레드 페이지네이션 (v0.130.0+)

App-server 클라이언트는 이제 세 가지 별도의 턴 아이템 뷰를 통해 대용량 스레드를 페이지 단위로 처리할 수 있습니다.⁹¹

특히 오케스트레이터가 롤아웃 파일과 다른 머신에 있을 수 있는 remote-control 배포에서 장기 실행 스레드를 효율적으로 탐색하려면, v0.121.0에서 도입된 ThreadStore 인터페이스와 페이지네이션을 함께 사용하세요.⁸²

App-Server Config 라이브 새로고침 (v0.130.0+)

라이브 app-server 스레드는 이제 재시작 없이 config.toml 변경 사항을 반영합니다 — 설정을 편집하고 저장하면, 실행 중인 스레드가 다음 턴에 새 값을 반영합니다. 이는 codex remote-control의 버그 수정 짝으로, 장기 실행 헤드리스 서버를 종료하지 않고 그 자리에서 재구성할 수 있게 해줍니다.⁹¹

Codex Cloud 및 Background Tasks [EXPERIMENTAL]

상태: Codex Cloud는 실험적(experimental) 기능입니다. 인터페이스, 가격, 가용성은 변경될 수 있습니다. 클라우드 환경은 OpenAI가 관리하며, 인프라를 사용자가 제어할 수 없습니다.

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

작동 방식

1. 작업 제출 (chatgpt.com/codex, Slack 통합, 또는 CLI를 통해)
2. Codex가 격리된 클라우드 샌드박스로 저장소를 복제합니다
3. 에이전트가 독립적으로 작업합니다: 코드를 읽고, 테스트를 실행하고, 변경을 수행합니다
4. 완료되면 Codex가 PR을 생성하거나 검토용 diff를 제공합니다
5. codex apply <TASK_ID>로 결과를 로컬에 적용합니다

클라우드 인터넷 액세스

에이전트 인터넷은 기본적으로 꺼져 있으며, 환경별로 구성됩니다.

• Off: 에이전트 인터넷 액세스 없음 (기본값)
• On: 선택적 도메인 허용 목록 + 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. 최소 하나 이상의 구성된 클라우드 환경 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 데스크톱 앱(macOS 및 Windows)은 다중 프로젝트 관리에 최적화된 그래픽 인터페이스를 제공합니다.¹⁶ Windows 버전은 2026년 3월 4일에 네이티브 PowerShell 지원과 네이티브 Windows 샌드박스를 갖추고 출시되었습니다.⁶⁶

설치

codex app                      # Auto-downloads and installs on first run

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

주요 기능

스레드 모드

각 스레드는 생성 시 선택한 세 가지 모드 중 하나로 실행됩니다.

Worktree 격리 메커니즘:

Worktree 스레드를 시작하면 데스크톱 앱은 다음을 수행합니다. 1. 임시 디렉터리에 새 git worktree (git worktree add)를 생성 2. 현재 HEAD에서 새 브랜치를 체크아웃 3. worktree 내부에서 에이전트를 실행 — 모든 파일 변경사항은 격리됨 4. 완료 시 diff 검토를 표시 — 병합할 변경사항을 사용자가 선택

이를 통해 동일한 저장소에서 여러 Worktree 스레드가 충돌 없이 동시에 실행될 수 있습니다. 각각 자체 브랜치와 작업 디렉터리를 가집니다.

자동화

자동화는 앱 내에서 로컬로 실행되므로, 앱이 실행 중이고 프로젝트가 디스크에 있어야 합니다.

• Git 저장소에서는 자동화가 전용 백그라운드 worktree를 사용합니다(작업 디렉터리에서 격리됨)
• 비 Git 프로젝트에서는 프로젝트 디렉터리에서 직접 실행됩니다
• 자동화는 기본 샌드박스 설정을 사용합니다

자동화 설정 방법: 1. 데스크톱 앱에서 프로젝트를 엽니다 2. 사이드바의 Automations 탭을 클릭합니다 3. 트리거(스케줄, 웹훅 또는 수동)를 정의합니다 4. 프롬프트를 작성하고 실행 모드(local 또는 worktree)를 선택합니다 5. 자동화 실행에 대한 reasoning 수준을 설정합니다 (App v26.312)⁷² 6. 자동화는 스케줄에 따라 실행되고 결과를 검토 큐에 추가합니다

예시 사용 사례: - 이슈 분류: 새 이슈를 자동으로 분류하고 우선순위 지정 - CI 모니터링: 빌드 실패를 감시하고 수정 제안 - 알림 응답: 모니터링 알림에 진단 분석으로 대응 - 의존성 업데이트: 보안 패치를 확인하고 적용

결과는 사람의 승인을 위해 검토 큐에 표시됩니다.

Windows 지원

Codex Desktop App은 2026년 3월 4일(App v26.304)에 Windows에서 출시되었으며, 네이티브 PowerShell 지원, 네이티브 Windows 샌드박스, 그리고 WSL을 요구하지 않는 skills, automations, worktrees를 포함한 완전한 기능 패리티를 제공합니다.⁶⁶

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

기본값: write 권한이 있는 협업자만 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(...): 중간 업데이트를 위한 비동기 이벤트 스트림
• outputSchema: JSON 형태의 최종 출력 강제
• 멀티모달 입력: 텍스트 + 로컬 이미지 전달 ({ type: "local_image", path: "..." })
• 이미지 워크플로 (v0.117.0): view_image가 URL을 반환하고, 생성된 이미지를 다시 열 수 있으며, 이미지 기록이 세션 재개 시에도 유지됩니다⁷⁵
• 다중 환경 view_image (v0.130.0): 여러 환경에 걸친 세션의 경우(턴별 환경 + 작업 디렉터리 선택과 함께 v0.124.0에서 도입되었으며, sticky 환경과 함께 v0.125.0에서 개선됨), 이제 view_image는 오케스트레이터의 로컬 파일시스템이 아닌 선택된 환경을 통해 파일 경로를 해결합니다. 원격 환경에서 첨부된 이미지는 SDK를 실행하는 호스트가 아니라 해당 환경의 작업 디렉터리를 기준으로 가져옵니다.⁹¹

스레드 및 클라이언트 설정

// 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+.

성능 최적화

컨텍스트 관리

컨텍스트 윈도우는 모델에 따라 다릅니다. 2026년 4월 기준: Codex의 GPT-5.5는 400K (API에서는 1M)를 제공합니다. GPT-5.4 / GPT-5.4-mini는 각각 1M / 400K를 제공합니다 (Codex에서 API와 동일). GPT-5.3-Codex / GPT-5.2-Codex 계열은 272K 입력 + 128K 출력 (총 400K 예산)으로 실행됩니다. 모두 예상보다 빨리 채워지므로 — 사전에 관리하세요.

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

토큰 효율성

속도 최적화

1. gpt-5.3-codex-spark: 인터랙티브 페어링을 위한 저지연 변형
2. --profile fast: 낮은 reasoning을 가진 사전 구성된 mini 모델
3. 병렬 도구 실행: Codex는 독립적인 읽기/검사를 동시에 실행하므로, 이를 활용할 수 있도록 프롬프트를 구조화하세요
4. 결과 중심 루프: 단계별 지시 대신 “구현, 테스트, 수정, 통과 시 정지”를 요청하세요

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

일반적인 문제 및 해결 방법

오류 메시지 참조

진단 도구

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는 유효한 최상위 플래그가 아닙니다. 위에 나온 debug 하위 명령과 TUI 진단을 사용하세요.

깨끗한 재설치

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

Debug 모드

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

이슈 보고

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

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

Codex Security [PREVIEW]

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

작동 방식: Codex Security는 저장소를 분석하여 프로젝트별 위협 모델을 구축하고, 실제 영향에 따라 분류된 취약점을 식별하며, 샌드박스 환경에서 발견 사항에 대한 압박 테스트를 수행하여 검증합니다. 이 에이전트는 사소한 버그로 인한 잡음을 줄이고, 신뢰도가 높은 발견 사항을 수정안과 함께 제시합니다.

성능: research preview 기간 동안 Codex Security는 120만 개의 커밋을 스캔하여 10,561개의 고심각도 취약점을 식별했습니다. 정밀도는 시간이 지남에 따라 향상되었으며, 잡음은 84% 줄었고, 과도하게 보고된 심각도는 90% 이상 감소했으며, 거짓 양성률은 절반으로 줄었습니다. 이 시스템은 OpenSSH, GnuTLS, Chromium에서 실제 취약점을 발견했으며, 14개의 CVE가 할당되었습니다.⁷⁷

참고: Codex Security는 CLI에 내장된 샌드박스 보안 모델과는 별개입니다. 샌드박스는 Codex로부터 사용자의 머신을 보호하고, Codex Security는 취약점으로부터 사용자의 코드베이스를 보호합니다.

엔터프라이즈 배포

관리자 제어 (requirements.toml)

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

# /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은 사용자가 선택할 수 있는 값을 제한하는 하드 제약 계층이며 사용자가 재정의할 수 없습니다. 관리자 requirements 규칙은 prompt 또는 forbid만 가능하며, 절대 무음으로 허용할 수 없습니다.

macOS MDM 구성

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

우선순위 (높음에서 낮음):

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

클라우드 requirements는 설정되지 않은 requirement 필드만 채우므로, 우선순위가 높은 관리 계층이 항상 우선합니다. 클라우드 requirements는 최선의 노력 기반(best-effort)이며, 가져오기에 실패하거나 시간이 초과되면 Codex는 클라우드 계층 없이 계속 진행합니다.

OpenTelemetry 통합

Codex는 표준 OTel 환경 변수에서 OpenAI API 호출까지 OpenTelemetry trace-context 전파를 지원합니다. 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_* 환경 변수가 적용됩니다 (엔드포인트, 서비스 이름, 리소스 속성)
• Trace context가 Codex를 통해 API 호출까지 전파되어 종단 간 관찰 가능성을 제공합니다
• 리소스 속성을 사용하여 팀, 환경 또는 프로젝트별로 trace에 태그를 지정합니다
• 프롬프트/도구 로깅을 활성화할 때 개인정보 보호 요구사항을 염두에 두세요 — trace에 코드 스니펫이 포함될 수 있습니다
• 구성 가능한 OpenTelemetry trace 메타데이터 (v0.130.0+). 표준 OTEL_RESOURCE_ATTRIBUTES 외에도, codex-otel 크레이트가 이제 구성 가능한 trace 메타데이터를 노출하여 관리자가 호출할 때마다 OTEL_RESOURCE_ATTRIBUTES를 처음부터 다시 구성하지 않고도 조직별 차원(cost-center, 프로젝트 ID, 티켓 참조)으로 trace에 태그를 지정할 수 있습니다. 동일한 릴리스에서 출시된 풍부해진 review/feedback 분석과 함께 사용하여 CLI, app-server, remote-control 세션 전반에 걸친 통합 디버깅 및 트리아지를 수행하세요.⁹¹

엔터프라이즈 접근

• ChatGPT Business / Enterprise / Edu: 조직 관리자가 제어하는 접근 권한과 자동으로 적용되는 클라우드 가져오기 requirements를 제공합니다. 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을 사용하세요

데이터 처리 및 컴플라이언스: - API 입력/출력은 OpenAI의 Business/Enterprise/API 약관에 따라 학습에 사용되지 않습니다 - 데이터 거주지의 경우, OpenAI API 트래픽은 기본적으로 미국 기반 인프라를 통해 라우팅됩니다. EU 데이터 거주지 요구사항이 있는 경우 OpenAI 엔터프라이즈 영업팀에 문의하세요 - 세션 transcript는 로컬에 저장됩니다. API 호출만 머신을 떠납니다 - ChatGPT Enterprise는 SOC 2, GDPR, CCPA를 포함한 컴플라이언스 프레임워크를 지원합니다

롤아웃 전략

조직을 위한 권장 단계별 롤아웃:

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

감사 패턴

Codex 사용량을 추적하고 컴플라이언스를 강제합니다:

• OpenTelemetry trace: 팀별 API 호출량, 토큰 사용량 및 지연 시간을 모니터링합니다
• 세션 영속성: 컴플라이언스 검토를 위해 ~/.codex/sessions/를 감사합니다 (민감한 컨텍스트에서는 --ephemeral로 비활성화)
• MCP identity 강제: 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 기반 패치가 아닌 엄격한 매칭을 사용합니다

컨텍스트 관리 모범 사례

• 웹 검색에 의존하기보다는 고품질 로컬 문서를 제공하세요
• 목차와 진행 파일을 갖춘 구조화된 마크다운을 유지하세요 (“점진적 공개”)
• 패치 실패를 방지하기 위해 추적되는 파일 전반에서 줄 끝(LF 대 CRLF)을 정규화하세요
• 긴 지침은 컨텍스트에서 밀려나므로 AGENTS.md를 간결하게 유지하세요

Git 워크플로

• 익숙하지 않은 저장소에서 Codex를 실행하기 전에 항상 새 브랜치를 만드세요
• 직접 편집보다는 패치 기반 워크플로(git diff / git apply)를 사용하세요
• 코드 리뷰 PR처럼 Codex 제안을 검토하세요
• 커밋하기 전에 /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.1-codex-mini \
  "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를 포함하여 행 단위 팬아웃을 위한 spawn_agents_on_csv를 추가했습니다.⁶¹ Codex는 여전히 사용자 지시 위임을 위한 Claude Code의 명시적 Task tool UX가 부족합니다 — 위임 패턴에는 cloud tasks나 SDK 오케스트레이션을 사용하세요.
• AGENTS.md는 도구 간 호환됨: AGENTS.md는 Cursor, Copilot, Amp, Jules, Gemini CLI 그리고 60,000개 이상의 오픈 소스 프로젝트에서 작동합니다. CLAUDE.md는 Claude 전용입니다.
• 프로필이 수동 전환을 대체: 실행마다 플래그를 변경하는 대신 config.toml에서 프로필을 정의하세요.

GitHub Copilot에서 마이그레이션

얻게 되는 것: - OS 수준 sandboxing (Seatbelt/Landlock — 컨테이너 기반 대비 커널이 강제 적용) - codex apply를 통한 클라우드 작업 위임 - 워크플로 전환을 위한 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 (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

변경 이력

참고 문헌

OpenAI blog URLs 참고: References ¹⁶, ²⁵–³⁰, ³³, ⁶⁴, ⁶⁶, ⁶⁷, ⁷⁶, ⁷⁷는 openai.com/index/ blog posts로 연결되며, Cloudflare bot protection 때문에 자동화된 액세스에는 HTTP 403을 반환합니다. 이 URLs는 일반 web browser로 접속하면 유효합니다.