Codex CLI: 완전한 기술 참조 가이드

요약: Codex는 코드베이스를 읽고, OS 수준 sandbox에서 명령을 실행하고, 파일을 패치하고, 작업을 cloud에 위임하는 다중 표면 코딩 에이전트입니다. 5가지 핵심 시스템(config.toml, sandbox/approval 모델, AGENTS.md, MCP, skills)을 익히면 Codex는 생산성을 크게 높여 주는 도구가 됩니다. context 전환에는 profiles를, context 예산 관리에는 /compact를, 지속되는 작업 목표에는 /goal을, Codex, Cursor, Amp 등 여러 도구에서 작동하는 프로젝트 지침에는 AGENTS.md를 사용하세요. GPT-5.5(2026년 4월 23일 출시)는 Codex의 권장 기본값입니다. Codex에서는 400K context window(API에서는 1M), MTok당 $5/$30, Terminal-Bench 2.0 SOTA 82.7%를 제공합니다.⁸³ CLI v0.140.0(stable, 2026년 6월 15일)부터는 /usage가 일별/주별/누적 계정 token 활동을 표시하고, session을 codex delete / /delete로 영구 삭제할 수 있으며(확인 보호 장치 포함), /import가 Claude Code의 설정, 프로젝트 config, 최근 chats를 선택적으로 마이그레이션하고, @를 입력하면 기본적으로 파일, plugins, skills를 위한 통합 mentions 메뉴가 열리며, managed Amazon Bedrock API-key 인증이 CLI 및 MCP OAuth credentials의 암호화된 로컬 저장소와 함께 제공됩니다. 실험적 /realtime 음성 controls는 TUI에서 제거되었습니다.¹⁰² CLI v0.139.0(stable, 2026년 6월 9일)부터는 code mode가 독립형 web search를 직접 호출할 수 있고(중첩된 JavaScript tool calls에서도 가능) plaintext 결과를 받을 수 있으며, tool/connector input schemas가 더 나은 large-schema 및 MCP 호환성을 위해 oneOf/allOf 구조를 보존하고, codex doctor가 editor 및 pager 환경 세부 정보를 추가하며(JSON의 민감한 값은 마스킹), plugin marketplace가 더 빠른 cached-catalog listing과 함께 codex plugin marketplace list --json에서 sources를 노출합니다.¹⁰³ v0.138.0(6월 8일)은 /app을 추가해 macOS와 Windows에서 CLI session을 desktop app으로 넘길 수 있게 했고, local image paths를 model에 노출했으며, reasoning-effort 선택을 더 유연하게 만들고, plugin automation에 구조화된 JSON output을 제공했습니다.¹⁰⁴ v0.137.0(6월 4일)은 multi-agent v2(thread별 runtime 유지, 더 깔끔한 follow-up 및 metadata defaults, hide_spawn_agent_metadata 기본값 true), F13-F24 TUI keybindings, turn별 catalog resolution을 갖춘 v1 skills extension을 출시했습니다.¹⁰⁵ CLI v0.135.0(2026년 5월 28일)부터 codex doctor는 더 풍부한 environment, Git, terminal, app-server, thread inventory를 보고하고, /status는 TUI가 remote를 통해 연결된 경우 remote connection 세부 정보와 server version을 표시합니다. vim mode는 text-object editing, 개선된 word/line-end 동작, 설정 가능한 interrupt-turn을 얻었고, /permissions는 이제 named permission profiles를 이해하고 custom profile을 표시합니다. 패키징된 Codex builds는 지원되는 macOS에서 bundled patched zsh helper를 찾아 사용하며, Python SDK는 thread 및 turn APIs를 위한 친숙한 Sandbox presets를 노출합니다.¹⁰⁷ v0.134.0(2026년 5월 26일)은 대소문자를 구분하지 않는 content matches와 result previews를 갖춘 local conversation history 검색을 도입했고, CLI, TUI permissions, sandbox flows 전반에서 --profile을 기본 profile selector로 만들었으며(legacy profile configs는 migration guidance와 함께 거부됨), per-server environment targeting 및 streamable HTTP servers용 OAuth options로 MCP setup을 개선했습니다. 또한 local $ref/$defs 보존과 oversized schemas 압축으로 connector tool schemas의 신뢰성을 높였고, read-only MCP tools가 readOnlyHint를 알릴 때 동시에 실행되도록 했으며, extension tools를 위한 conversation history를 포함해 더 풍부한 extension 및 hook context를 추가했습니다.¹⁰¹ v0.133.0(2026년 5월 21일)은 goals를 기본으로 활성화하고 전용 storage와 progress tracking을 추가했습니다. codex remote-control에는 foreground readiness/status와 daemon-style start/stop이 추가되었고, permission profiles는 list APIs, inheritance, managed requirements.toml, runtime refresh, 더 강력한 Windows sandbox 통합을 얻었습니다. plugin discovery는 installed versions, marketplace roots, remote collections를 표시하고, extensions는 subagent start/stop, tool execution, turn metadata, async approval/turn processing을 관찰할 수 있습니다. 5월 21일 Codex app 업데이트는 frontmost Mac windows용 Appshots, app/IDE/CLI 전반의 Goal mode GA, in-app browser annotation 개선, 자격을 갖춘 Mac 사용자를 위한 opt-in locked Computer Use를 추가했습니다.⁹⁹¹⁰⁰ v0.132.0(2026년 5월 20일)은 Python SDK first-class auth, 더 단순한 text-only turn APIs, 더 풍부한 TurnResult, codex exec resume --output-schema, 더 빠른 TUI startup, auth-backed remote executor registration, app-server turns의 image-fidelity preservation을 추가했습니다. legacy --full-auto보다 명시적인 sandbox/approval flags 또는 permission profiles를 계속 우선하세요. js_repl은 계속 제거된 상태입니다.^{86878991969798}

Codex는 코드를 작성해 주는 chatbot이 아니라 다중 표면 코딩 에이전트로 작동합니다. CLI는 코드베이스를 읽고, sandbox에서 명령을 실행하고, 파일을 패치하고, MCP를 통해 외부 서비스에 연결하며, 오래 걸리는 작업을 cloud에 위임합니다. 로컬에서 실행되지만 전역적으로 사고합니다. 동일한 지능이 작업 방식에 따라 5가지 서로 다른 표면을 구동하며, 브라우저를 장악하지 않고 브라우저 안에서 Codex를 실행하는 새로운 Chrome extension도 포함됩니다.⁹⁰

Codex를 가볍게 쓰는 것과 효과적으로 쓰는 것의 차이는 5가지 핵심 시스템을 이해했는지에 달려 있습니다. 이것들을 익히면 Codex는 생산성을 크게 높여 주는 도구가 됩니다.

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

저는 몇 달 동안 production codebases, CI/CD pipelines, team workflows 전반에서 Codex를 Claude Code와 함께 사용했습니다. 이 가이드는 제가 시작할 때 있었으면 했던 완전한 reference로 그 경험을 압축한 것입니다. 모든 기능에는 실제 syntax, 실제 configuration examples, 숙련된 사용자도 자주 걸려 넘어지는 edge cases가 포함되어 있습니다.

안정성 참고: [EXPERIMENTAL] 또는 under development로 표시된 기능은 release 사이에 변경될 수 있습니다. v0.133.0(2026년 5월 21일) 기준으로 goals는 기본 활성화되어 있고, permission profiles는 first-class managed surface이며, plugin discovery는 더 쉽게 점검할 수 있고, remote-control은 foreground 또는 daemonized app-server command로 더 쉽게 실행할 수 있습니다. Codex Cloud와 code mode는 여전히 experimental 또는 under development 상태입니다. core CLI, sandboxing, AGENTS.md, config.toml, Skills, hooks, multi-agent tools, plugins, Browser, Computer Use, Appshots는 platform과 plan에 따라 stable 또는 문서화된 user-facing surfaces입니다. v0.132.0은 Python SDK auth와 structured resume automation을 보강했고, v0.131.0은 codex doctor, 통합 @ mention search, marketplace CLI commands, version-aware plugin sharing, runtime enable/disable이 가능한 daemon-managed remote-control, registry-backed environments, 추가 Windows sandbox hardening을 추가했습니다.⁹⁶⁹⁷⁹⁸ Legacy --full-auto는 계속 deprecated 상태이고 js_repl은 계속 제거된 상태입니다.⁸⁶⁸⁷

핵심 요약

• 다섯 가지 표면, 하나의 두뇌: CLI, desktop app, IDE extension, cloud tasks, 새 Chrome extension은 모두 같은 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개 이상의 오픈 소스 프로젝트에서 작동합니다. 한 번 작성하고 어디서나 사용하세요.
• Profiles는 컨텍스트 전환 비용을 줄여줍니다: 이름이 있는 설정 프리셋(fast, careful, auto)을 정의하고 --profile로 전환하세요.
• 컨텍스트 관리가 중요합니다: GPT-5.5는 Codex에서 400K 컨텍스트 창을, API에서는 1M 컨텍스트 창을 제공합니다. GPT-5.4 mini도 더 낮은 지연 시간의 subagent 작업을 위해 400K를 제공하며, GPT-5.3-Codex는 272K 입력을 제공합니다. 토큰 예산을 선제적으로 관리하려면 /compact, 집중된 프롬프트, @file 참조를 사용하세요.⁸³

이 가이드 사용 방법

이 문서는 2,500줄이 넘는 레퍼런스입니다. 본인의 경험 수준에 맞는 지점에서 시작하세요.

끝부분의 빠른 참조 카드에서는 모든 주요 명령을 훑어보기 쉬운 요약으로 제공합니다.

Codex 작동 방식: Mental Model

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

┌─────────────────────────────────────────────────────────┐
│                    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          │
└─────────────────────────────────────────────────────────┘

Core Layer: GPT-5.x 모델 제품군이 모든 것을 구동합니다. 2026년 4월 23일 기준으로, 사용 가능할 때는 gpt-5.5가 권장 모델입니다. Codex에서 400K 컨텍스트(API에서는 1M), Terminal-Bench 2.0 SOTA 82.7%를 제공합니다. gpt-5.4는 롤아웃 기간 동안 fallback 기본값으로 유지됩니다(1M 컨텍스트, 네이티브 computer use).⁸³⁶⁴ 이 계층은 파일을 읽고, 패치를 작성하고, 셸 명령을 실행하며, 코드베이스를 추론합니다. 컨텍스트가 가득 차면 Codex는 대화를 압축해 공간을 확보합니다. 이 계층은 토큰 비용이 발생합니다.

Security Layer: Codex가 실행하는 모든 명령은 OS 수준 sandbox를 통과합니다. macOS에서는 Apple의 Seatbelt 프레임워크가 커널 수준 제한을 적용합니다. Linux에서는 Landlock + seccomp가 파일 시스템과 syscall 접근을 필터링합니다. sandbox는 컨테이너 내부가 아니라 커널 수준에서 작동합니다. 그런 다음 approval policy가 언제 사람의 확인을 요청할지 결정합니다.

Extension Layer: MCP는 외부 서비스(GitHub, Figma, Sentry)를 연결합니다. Skills는 Codex가 필요할 때 로드하는 재사용 가능한 워크플로를 패키징합니다. Apps는 ChatGPT connectors에 연결됩니다. Web search는 인터넷에서 실시간 컨텍스트를 추가합니다.

Surface Layer: CLI는 터미널 파워 유저와 자동화를 위한 표면입니다. Desktop app은 여러 스레드의 프로젝트 관리를 위한 표면입니다. IDE extension은 edit-compile-test 루프를 위한 표면입니다. Cloud는 독립적으로 실행되는 비동기 작업을 위한 표면입니다.

핵심 통찰: 대부분의 사용자는 하나의 표면만 사용합니다. 파워 유저는 5가지를 모두 사용합니다. 오래 실행되는 작업에는 Cloud, 결정적인 repo 작업에는 CLI, 촘촘한 코딩 루프에는 IDE extension, 계획과 조율에는 desktop app, 로그인된 브라우저 워크플로에는 Chrome을 사용합니다.

목차

1. Codex는 어떻게 설치하나요?
2. 빠른 시작: 첫 세션
3. 핵심 상호작용 표면
4. 설정 시스템 심층 분석
5. 어떤 모델을 선택해야 하나요?
6. Codex 비용은 얼마인가요?
7. Decision Frameworks
8. Sandbox 및 Approval System은 어떻게 작동하나요?
9. AGENTS.md는 어떻게 작동하나요?
10. Hooks
11. MCP (Model Context Protocol)이란 무엇인가요?
12. Code Mode
13. JavaScript REPL Runtime
14. Skills란 무엇인가요?
15. Plugins
16. Plan Mode 및 협업
17. Memory System
18. Session Management
19. 비대화형 모드(codex exec)
20. Codex Cloud 및 백그라운드 작업
21. Codex Desktop App
22. GitHub Action 및 CI/CD
23. Codex SDK
24. 성능 최적화
25. 문제는 어떻게 디버그하나요?
26. Enterprise Deployment
27. Best Practices 및 Anti-Patterns
28. Workflow Recipes
29. Migration Guide
30. 빠른 참조 카드
31. Changelog
32. References

Codex는 어떻게 설치하나요?

Package Managers

# 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 Releases에서 플랫폼별 바이너리를 다운로드하세요¹:

시스템 요구 사항

• 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 Completions

# 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.133.0

Quick Start: 첫 세션 시작하기

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를 사용해 보세요 (비대화형 모드 참조)

핵심 상호작용 화면

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

Terminal UI는 다음으로 구성된 전체 화면 애플리케이션입니다.

• Composer: 프롬프트를 입력하고, @로 파일을 첨부하며, ! 접두사로 shell command를 실행합니다
• Output pane: 스트리밍 model 응답, tool call, command output을 표시합니다
• Status bar: model, token usage, git branch, sandbox mode를 표시합니다

주요 TUI 단축키:

Status line 변경(v0.121.0): status line의 기존 context-window meter는 context window가 얼마나 찼는지 보여주는 context-percent indicator로 대체되었습니다. status line을 파싱하는 scripts나 hooks가 있다면 이 형식 변경을 확인하세요.⁸² 새 버전이 있으면 Codex가 CLI 업데이트 알림도 표시합니다.

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

Workflow picker redesign(v0.129.0): redesign된 picker에서 resume과 fork에 더 쉽게 접근할 수 있으며, 새로운 raw scrollback mode를 사용하면 commands나 model output을 그대로 복사해야 할 때 렌더링되지 않은 transcript를 스크롤할 수 있습니다. 긴 debugging session을 triage하거나 output을 다른 tool로 pipe할 때 유용합니다.⁸⁹

통합 @ mentions menu(v0.140.0): 이제 composer에 @를 입력하면 기본적으로 files, plugins, skills를 아우르는 단일 mentions menu가 열립니다. 파일만 첨부하던 flow를 대체하며, 한 번의 keystroke로 모든 project resource를 참조할 수 있습니다.¹⁰²

2. Codex Desktop App (macOS + Windows)

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

Desktop app은 CLI에는 없는 기능을 추가합니다.

• Multi-tasking: 서로 다른 project에서 여러 parallel agents를 동시에 실행합니다
• Git worktree isolation: 각 thread는 repo의 격리된 copy에서 작업합니다
• Inline diff review: app을 떠나지 않고 changes를 stage, revert, commit합니다
• Integrated terminal: command 실행을 위한 thread별 terminal입니다
• Conversation forking: 대안을 탐색하기 위해 conversation을 branch합니다
• Floating pop-out windows: conversations를 portable windows로 분리합니다
• Automations: 반복 task(issue triage, CI monitoring, alert response)를 예약합니다
• Appshots: 가장 앞에 있는 Mac app window를 screenshot 및 사용 가능한 text와 함께 thread에 첨부합니다
• In-app browser comments: local 또는 public pages를 preview하고, element/area comments를 남기며, Codex가 정확한 visual feedback을 처리하게 합니다
• Computer Use: Codex가 범위가 지정된 GUI 작업을 위해 허용된 Mac apps를 조작하게 합니다. locked use는 적격 remote Mac Computer Use turn에서 opt-in입니다

app과 CLI를 언제 사용할지: 여러 workstream을 조율하거나 visual diff review가 필요할 때는 desktop app을 사용하세요. terminal composability, scripting, CI/CD integration을 원할 때는 CLI를 사용하세요.

3. IDE Extension (VS Code, Cursor, Windsurf)

Codex IDE extension은 editor에 직접 통합됩니다.

• Agent mode by default: 파일을 읽고, edits를 만들며, commands를 실행합니다
• Inline edits: active files 안에서 context-aware suggestions를 제공합니다
• Shared sessions: sessions가 CLI와 IDE extension 사이에서 sync됩니다
• Same authentication: ChatGPT account 또는 API key로 로그인합니다

VS Code Marketplace 또는 Cursor/Windsurf extension stores에서 설치하세요.³

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks는 OpenAI가 관리하는 environments에서 비동기로 실행됩니다.

• Fire and forget: local machine과 독립적으로 실행되는 tasks를 queue에 넣습니다
• Parallel execution: 여러 cloud tasks를 동시에 실행합니다
• PR creation: Codex가 완료된 작업으로 pull requests를 생성합니다
• Local apply: codex apply <TASK_ID>로 cloud results를 local repo에 가져옵니다

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

Cloud tasks는 chatgpt.com/codex에서도 접근할 수 있습니다.⁴

5. Codex for Chrome [NEW]

Codex는 Chrome용 browser extension으로도 제공되어, CLI, desktop app, IDE extension, cloud에 이어 다섯 번째 화면을 추가합니다. 이 extension은 일반 browsing을 대체하는 대신 그 옆에서 함께 작동하도록 설계되었습니다. Codex는 background에서 tabs 전반에 걸쳐 parallel로 작동하고, 사용자는 Codex가 어떤 sites에 접근할지 계속 제어합니다.⁹⁰

• Parallel tab execution: Codex는 foreground tab을 잠그지 않고 여러 tabs에서 동시에 작동합니다.
• Per-site control: 사용자는 Codex가 상호작용할 수 있는 websites를 allow-list로 지정합니다. 기본값은 access 없음입니다.
• Browser as the workbench: 이 extension은 page가 source of truth인 app-and-website 작업에 가장 적합합니다. 예를 들면 admin consoles, internal dashboards, content-management UIs, ticket systems입니다. local repos에서 CLI를 대체하는 용도는 아닙니다.
• Same brain: Codex for Chrome은 다른 화면들이 사용하는 같은 GPT-5.x-Codex 지능으로 실행됩니다. 따라서 CLI에서 작동하는 AGENTS.md 또는 skills configuration의 conventions가 browser-driven work에도 그대로 적용됩니다.

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

Configuration System 심층 분석

Codex는 설정에 TOML을 사용해요. 우선순위 계층을 이해하는 일은 중요해요. 설정이 충돌할 때 어떤 값이 적용되는지를 결정하기 때문이에요.

우선순위(높은 순서에서 낮은 순서)

1. Session overrides(가장 높음): CLI flags(--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) 및 -c key=value overrides
2. Project config(.codex/config.toml, CWD에서 프로젝트 루트까지 위로 올라가며 검색하며 가장 가까운 디렉터리가 우선 적용돼요)
3. User config($CODEX_HOME/config.toml, 기본값은 ~/.codex/config.toml)
4. System config(Unix의 /etc/codex/config.toml)
5. Built-in defaults(가장 낮음)

requirements.toml은 일반 설정 병합 이후 사용자가 선택할 수 있는 값을 제한하는 정책 제약 레이어로 작동해요. Enterprise Deployment를 참고하세요.

Config 파일 위치

전문가 팁: CODEX_HOME 환경 변수는 기본 ~/.codex 디렉터리를 override해요. CI/CD나 여러 계정 설정에 유용해요.

전체 Configuration Reference

# ~/.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 = 400000           # 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

Profiles

여러 작업 모드에 사용할 수 있는 이름 있는 설정 preset이에요.

# 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"

profile 활성화:

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

전문가 팁: config의 최상위 레벨에 profile = "fast"를 설정해 기본 profile을 지정하세요. session별로는 --profile로 override할 수 있어요.

Custom Model Providers

Azure, AWS Bedrock, 로컬 모델 또는 proxy 서비스에 연결해요.

[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 wire API(wire_api = "chat")는 OpenAI-hosted 모델에서 deprecated되었고, OpenAI는 2026년 2월 제거를 발표했어요.³⁴ 로컬 provider(Ollama, LM Studio)는 여전히 이 형식을 받을 수 있어요. OpenAI endpoint에는 대신 wire_api = "responses"를 사용하세요.

--oss flag로 로컬 모델을 사용하세요.

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

또는 config에 설정하세요.

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

Inline Config Overrides

command line에서 어떤 config 값이든 override하세요.

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

Sandbox 및 Approval System은 어떻게 작동하나요?

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

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

Sandbox는 OS 기본 메커니즘을 사용해 파일 시스템과 네트워크 접근을 제어합니다.

플랫폼별 적용 방식:

• macOS: sandbox-exec를 통해 Apple의 Seatbelt 프레임워크를 사용하며, 런타임에 컴파일되는 mode별 profile을 커널이 적용합니다⁶. v0.121.0부터 macOS sandbox profile은 특정 Unix sockets(예: docker.sock, editor IPC sockets)를 allowlist에 추가할 수 있고, private DNS resolution은 더 이상 기본적으로 차단되지 않습니다.⁸²
• Linux: 파일 시스템 제한에는 Landlock을, syscall 필터링에는 seccomp를 사용합니다. 독립 helper process(codex-linux-sandbox)가 defense-in-depth 격리를 제공합니다.⁵ Bubblewrap(bwrap)은 Linux 빌드의 일부로 vendored 및 컴파일됩니다(v0.100.0에서 optional에서 승격됨)⁷. v0.117.0은 legacy kernel configuration을 사용하는 오래된 distro에서 sandbox 신뢰성을 개선했습니다.⁷⁵ v0.129.0은 Linux에서 sandbox startup을 강화하고, vendored Bubblewrap을 upstream 보안 패치가 포함된 0.11.2로 올렸습니다. v0.130.0은 추가 startup hardening을 더했습니다.⁸⁹⁹¹
• Windows: restricted token을 사용하는 native sandbox입니다(v0.100.0에서 experimental에서 승격됨). WSL도 지원됩니다(Linux Landlock + seccomp를 상속함). v0.117.0에는 더 나은 process isolation을 위한 restricted-token sandbox 개선이 포함되어 있습니다.⁷⁵ v0.130.0은 sandbox 사용자가 desktop runtime binary cache에 접근할 수 있게 해, Windows sandbox가 workspace-sandbox 사용자에게 runtime binary를 안정적으로 resolve할 수 있도록 했습니다.⁹¹

왜 중요한가요: container 기반 sandboxing(Docker)과 달리 OS 수준 sandboxing은 더 빠르고 가벼우며 벗어나기 어렵습니다. Codex가 system call을 보기 전부터 커널이 제한을 적용합니다.

보안 수정: - zsh-fork sandbox 우회(v0.106.0): zsh forking을 통한 shell execution이 sandbox 제한을 우회할 수 있었던 취약점을 수정했습니다.⁶⁰ 이전 버전을 사용 중이라면 즉시 업그레이드하세요. - 입력 크기 제한(v0.106.0): Codex는 이제 지나치게 큰 payload로 인한 멈춤을 방지하기 위해 약 100만 자의 입력 제한을 적용합니다.⁶⁰ - 보안 devcontainer profile(v0.121.0): Docker devcontainer용으로 새롭게 강화된 customer profile은 container 내부 sandboxing에 Bubblewrap을 사용합니다. WSL2는 지원되지만 WSL1은 명시적으로 거부됩니다(Bubblewrap은 WSL1의 kernel shim과 호환되지 않음).⁸² - Guardian review + hooks(v0.121.0): Guardian review session 중에는 hooks가 비활성화되어 pre/post-tool hooks가 Guardian subagent의 결정에 간섭할 수 없습니다.⁸² logging이나 validation에 hooks를 의존한다면 Guardian review가 이를 건너뛴다는 점을 알아두세요. 전체 audit trail이 필요하다면 app-server observability를 대안으로 사용하세요. - Linux /dev 파일 시스템(v0.105.0): Linux의 sandboxed commands는 이제 최소한의 /dev 파일 시스템을 받아 device node를 기대하는 도구와의 호환성이 향상되었습니다.⁶¹

ReadOnlyAccess policy(v0.100.0+): 세밀한 읽기 접근 제어를 위한 configurable policy shape입니다. workspace-write mode에서도 Codex가 읽을 수 있는 디렉터리를 제한하는 데 사용하세요.

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

2계층: Approval Policy (요청 시점)

Approval policy는 Codex가 사람의 확인을 요청하기 위해 언제 멈출지를 결정합니다.

on-failure는 일부 오래된 예시와 compatibility path에 여전히 나타나지만, 현재 OpenAI configuration docs에서는 deprecated로 표시됩니다. interactive run에는 on-request를, 이미 외부 안전 경계가 있는 non-interactive run에는 never를 사용하는 편이 좋습니다.⁸⁷

별도 Approval ID(v0.104.0+)

Codex는 이제 multi-step shell execution 안의 각 command에 별도의 approval ID를 할당합니다. 즉 approval은 세밀하게 적용됩니다. sequence 안의 command 하나를 승인해도 같은 shell invocation의 이후 command가 자동으로 승인되지는 않습니다.⁴⁹

유연한 Approval Controls(v0.105.0+)

Approval flow는 이제 추가 sandbox permissions와 세밀한 rejection을 지원합니다.⁶¹

• 추가 sandbox permissions: command가 현재 sandbox mode를 넘어서는 접근을 필요로 할 때, Codex는 전체 mode 변경을 요구하는 대신 특정 추가 권한을 요청할 수 있습니다.
• 세밀한 rejection: 개별 tool call을 feedback과 함께 거부할 수 있어, Codex가 같은 command를 단순히 다시 시도하는 대신 접근 방식을 조정할 수 있습니다.

Runtime Permission Requests(v0.113.0+)

Codex에는 이제 model이 runtime에 추가 권한을 요청할 수 있게 하는 내장 request_permissions tool이 포함되어 있습니다.⁶⁹ model이 elevated access가 필요한 task를 만나면, 조용히 실패하거나 사용자가 다른 flag로 다시 시작하도록 요구하는 대신 TUI approval flow를 통해 특정 권한(파일 시스템 경로, 네트워크 접근 등)을 공식적으로 요청할 수 있습니다.

Permission Profiles(v0.113.0+, v0.128.0 및 v0.133.0에서 확장)

Permission profiles는 파일 시스템과 네트워크 sandbox policy를 이름이 있는 재사용 가능한 section으로 나눕니다. default_permissions를 :read-only, :workspace 같은 built-in profile로 설정하거나 custom [permissions.<name>] table을 가리키게 하세요.⁸⁷ v0.133.0은 profile을 managed surface로 승격합니다. list APIs는 사용 가능한 profile metadata를 노출하고, profile은 서로 상속할 수 있으며, managed requirements.toml은 permission requirements를 선언할 수 있고, active profile은 runtime에 refresh되며, Windows sandbox setup은 별도의 ad hoc policy가 아니라 resolved profile을 사용합니다.⁹⁸

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"

project root가 writable이어도 읽을 수 없어야 하는 민감한 파일과 glob에는 none을 사용하세요. 일회성 command 예외에는 profile을 넓게 확장하기보다 rule을 우선적으로 사용하세요.⁸⁷

Legacy --full-auto 안내

오래된 guide에서는 --full-auto를 다음의 convenience alias로 설명했습니다.

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

v0.128.0에서 release notes는 --full-auto를 deprecated로 표시하며, 현재 CLI help에는 interactive run용으로 더 이상 나열되지 않습니다. 대신 위의 명시적 flag나 이름이 지정된 permissions profile을 사용하세요.⁸⁶

Sandbox 신뢰성(v0.129.0): Linux sandbox startup hardening은 느린 파일 시스템이나 symlinked checkout에서 발생하는 race를 줄입니다. Windows sandbox 신뢰성 개선은 long-running run 중 발생하는 여러 edge-case crash를 해결합니다. vendored Bubblewrap은 upstream 보안 패치가 포함된 0.11.2로 올라갔습니다. config 변경은 필요 없습니다. 이를 적용하려면 codex update를 실행하세요.⁸⁹

권장 설정

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

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

Power user(전체 접근, human-in-the-loop):

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

이 조합은 community에서 권장하는 “sweet spot”입니다. 최대 권한을 제공하되 모든 command에 승인이 필요합니다.⁸

CI/CD automation:

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

Guardian Subagent를 통한 Smart Approvals(v0.115.0+)

Smart Approvals는 모든 action에 사람 승인을 요구하는 대신 review request를 guardian subagent로 route할 수 있습니다. guardian session은 prompt cache를 재사용하고 startup overhead를 피하기 위해 approval 간에 유지됩니다. 각 review는 깨끗한 history를 받습니다(이전 decision이 이후 review로 새어 들어가지 않음).⁷³

config.toml에서 reviewer를 설정하세요.

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

이는 포괄적인 approval_policy = "never" 대신 reasoning이 있는 automated review를 원하는 CI/CD workflow에 특히 유용합니다.

Network Access 활성화

Codex는 workspace-write mode에서 기본적으로 network access를 차단합니다. 필요할 때 활성화하세요.

# 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 Proxy Support(v0.104.0+)

WebSocket traffic을 proxy를 통해 route하는 corporate environment를 위해, Codex는 이제 WS_PROXY 및 WSS_PROXY environment variable을 지원합니다.⁴⁹

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

이는 기존 HTTPS_PROXY 및 SOCKS5 proxy support(v0.93.0+)를 보완하며 모든 transport layer를 포괄합니다.

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가 올바르게 작동한다면 workspace-scoped profile 아래에서 두 command 모두 permission denied error로 실패해야 합니다. command 중 하나라도 성공하면 sandbox configuration을 조사해야 합니다.

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 스키마와 최상위 서버 맵을 모두 허용하므로, 어느 관례에 맞춰 작성된 plugin이든 깔끔하게 로드됩니다.⁸⁴

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의 identity와 일치하지 않는 서버는 시작 시 차단됩니다. 전체 정책 설정은 엔터프라이즈 배포를 참고하세요.

Code Mode [EXPERIMENTAL]

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

v0.139.0부터 code mode는 중첩된 JavaScript 도구 호출을 포함해 standalone web search를 직접 호출할 수 있으며, 일반 텍스트 결과를 받습니다. 따라서 code-mode 흐름은 sandboxed 코딩 컨텍스트를 벗어나지 않고도 실시간 정보를 가져올 수 있습니다.¹⁰³

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

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0은 experimental JavaScript REPL runtime(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가 필요할 때 불러오는 재사용 가능한 작업별 기능 패키지입니다. Skills는 공개 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는 symlink된 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 vs 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 용어를 포함하세요

Production 예시: Deploy Skill

references와 scripts가 함께 작동하는 완전한 multi-file 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는 일급 기능이 되었습니다. product-scoped plugins는 시작 시 자동으로 동기화되고, /plugins는 검색과 관리를 위한 TUI 내 브라우저를 제공합니다.⁷⁵ v0.128.0에서는 marketplace 설치, 원격 번들 캐싱, 원격 제거 APIs, plugin에 포함된 hooks, hook 활성화 상태, external-agent 설정 가져오기 등으로 plugin 워크플로가 확장되었습니다.⁸⁶ v0.129.0(2026년 5월 7일)은 plugin workspace 공유(다시 게시하지 않고 plugin 세트를 팀원에게 푸시), 공유 접근 제어(수신자별 활성화/비활성화, 취소), 소스 필터링(workspace가 가져올 marketplace 제한), 그리고 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이 번들로 제공하는 모든 lifecycle hook(SessionStart, UserPromptSubmit, Stop 등)이 나열됩니다. plugin을 설치하기 전에 세션에 어떤 hooks를 등록할지 정확히 확인할 수 있어, 도구만 보고 신뢰한 plugin에서 예상치 못한 hook 부작용이 발생하는 일을 피할 수 있습니다.
• shareContext의 plugin 공유 메타데이터. workspace에서 plugin을 공유하면 이제 공유 링크 payload에 링크 메타데이터(생성자, 범위, 최신성)가 노출되어, 수신 세션이 출처를 보여주고 수락 여부를 결정할 수 있습니다.
• 공유 설정의 검색 가능성 제어. 공유 설정에는 검색 가능성 토글이 있어, 팀이 plugin을 조직 전체에 일반적으로 나열되게 하지 않고도 특정 workspaces 또는 수신자 목록에 게시할 수 있습니다.

Plugin 소스

Plugin 검색

Codex는 세션 시작 시 활성화된 plugins를 모델에 알려 설치된 MCPs, 앱, skills를 더 잘 찾을 수 있게 합니다(v0.111.0).⁶⁵ 모델은 작업 컨텍스트를 바탕으로 세션 중 관련 plugins를 제안할 수 있습니다. v0.117.0에서는 product-scoped plugins가 시작 시 동기화되어, 수동 개입 없이 최신 plugin 카탈로그를 사용할 수 있습니다.⁷⁵

@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/

이는 custom skills, MCP servers, app connectors를 포함해 설치된 모든 plugin에서 작동합니다.

Plugin Marketplace(v0.113.0+)

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

타사 Marketplaces 추가(v0.121.0+)

현재 OpenAI Codex 문서는 marketplace 소스 관리를 codex plugin marketplace 아래에 둡니다. 이는 OpenAI의 first-party marketplace를 넘어선 타사 plugin 배포를 공식화하며, GitHub repo shorthand, 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 [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 호출자(IDE/desktop integrations)는 marketplace를 프로그래밍 방식으로 등록할 수 있는 병렬 endpoint를 갖습니다.⁸²

보안 고려사항: 타사 marketplaces는 사용자의 Codex 권한으로 임의의 plugin 코드를 실행합니다. 추가하기 전에 소스를 검토하고, 첫 실행 중에는 sandboxed 실행을 선호하세요.

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 설치, app connector 설정이 필요했던 것들을 통합합니다. 하나의 plugin이 이 3가지를 모두 번들로 포함할 수 있어, 팀 온보딩이 더 빨라지고 설정을 더 쉽게 이식할 수 있습니다.

Plan Mode와 협업

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

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(v0.98.0부터 기본 활성화)를 사용하면 Codex가 현재 작업을 중단하지 않고 활발히 작업하는 동안 새 지시를 주입할 수 있습니다.¹⁴

주입 방법은 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가 끝날 때까지 기다렸다가 지시하고 싶다면, 턴이 완료된 뒤 평소처럼 입력하면 됩니다. 특별한 mode는 필요 없습니다.

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

Syntax highlighting(v0.105.0): 이제 TUI는 fenced code blocks와 diffs를 inline으로 syntax-highlight합니다. 색상 scheme을 선택하려면 /theme를 사용하세요.⁶¹

새 TUI commands(v0.105.0+):⁶¹

음성 transcription(v0.105.0, experimental): 스페이스바를 눌러 음성 transcription으로 prompts를 받아쓰세요. 이 기능은 experimental이며 microphone 권한이 필요할 수 있습니다.⁶¹ v0.107.0부터 realtime voice sessions는 microphone과 speaker 장치 선택을 지원하므로, 특정 오디오 입력/출력 하드웨어를 선택할 수 있습니다.⁶² v0.140.0에서 제거됨: experimental /realtime 음성 controls와 해당 오디오 dependencies가 TUI에서 제거되었습니다. 스페이스바 음성 transcription은 영향을 받지 않습니다.¹⁰²

기타 개선 사항: - 긴 링크는 TUI 줄을 넘어 줄바꿈되더라도 클릭 가능한 상태로 유지됩니다(v0.105.0)⁶¹ - 로컬 파일 링크는 개선된 formatting으로 렌더링됩니다(v0.106.0)⁶⁰ - TUI markdown은 OSC 8 metadata를 통해 웹 링크를 클릭 가능하게 유지하고, 좁은 tables는 link targets를 잃지 않으면서 읽기 쉬운 key/value records로 fallback합니다(v0.136.0)¹⁰⁶ - sub-agents의 Ctrl+C 처리가 수정되어 child processes를 제대로 종료합니다(v0.106.0)⁶⁰

Memory System

Codex에는 세션 전반에 걸쳐 사실, 선호도, 프로젝트 컨텍스트를 저장하는 영구 Memory System(v0.100.0+)이 있습니다.²⁴

Memory Commands

memory는 ~/.codex/memory/ 아래의 markdown 파일에 저장됩니다. Codex는 세션 시작 시 이를 로드하고, 이후 모든 세션에서 동작을 조정하는 데 사용해요.

저장하면 좋은 내용

memory는 지속적인 선호도와 프로젝트 사실을 저장할 때 가장 잘 작동해요.

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

Pipeline에서의 Memory

codex exec를 실행할 때 memory는 자동으로 로드됩니다. 즉, CI/CD pipeline과 script도 대화형 세션과 같은 컨텍스트의 이점을 얻을 수 있어요. 호출할 때마다 지시사항을 반복할 필요가 없습니다.

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

• Secret 정리: memory는 디스크에 쓰이기 전에 secret이 있는지 자동으로 스캔됩니다
• CWD 인식: 이제 memory 파일에는 프로젝트별 회상을 위해 작업 디렉터리 컨텍스트가 포함됩니다
• Developer message 제외: developer/system message는 phase-1 memory 입력에서 제외되어, 사용자 상호작용에 집중함으로써 memory 품질을 개선합니다
• Diff 기반 망각(v0.106.0): 이제 memory는 diff 기반 망각을 사용해 오래된 사실을 제거하고, 시간이 지나도 memory 저장소를 가볍고 관련성 있게 유지합니다⁶⁰
• 사용량 인식 선택(v0.106.0): 이제 memory 검색은 사용량을 인식해, 자주 접근되었고 최근에 관련성이 높았던 memory를 우선합니다⁶⁰
• 설정 가능한 memory(v0.107.0): 이제 memory는 완전히 설정할 수 있습니다. 깨끗한 상태로 되돌리려면 codex debug clear-memories를 사용해 저장된 모든 memory를 초기화하세요. 서로 관련 없는 프로젝트 간에 컨텍스트를 전환하거나 memory 상태가 흐트러졌을 때 유용합니다⁶²
• Phase-2 model upgrade(v0.121.0): phase-2 memory consolidation model이 이제 gpt-5.4입니다(이전 기본값에서 상향). phase-2 pipeline은 세션 사이에 실행되어 phase-1 transcript를 지속 가능한 사실로 정제합니다. model 변경으로 같은 token 비용에서 회상 품질이 개선됩니다.⁸²
• TUI memories menu(v0.121.0): 새로운 세션 내 UI에서 memory mode, 개별 memory 삭제, reset button을 제공합니다. 이제 memory reset은 과거 rollout을 무효화하지 않고 보존하므로, reset을 해도 session replay를 깨뜨리지 않으면서 이후 회상 표면만 지웁니다.⁸²

Memory vs AGENTS.md

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

Session Management

Codex는 세션을 ~/.codex/sessions/ 아래에 유지해, CLI 및 desktop surface 전반에서 resume, forking, multi-thread workflow를 사용할 수 있게 합니다.

Resume

중단한 지점부터 이어서 작업하세요.

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 slash command는 search가 포함된 동일한 interactive picker를 엽니다.

Fork

현재 진행 상황을 잃지 않고 대안을 탐색하려면 대화를 분기하세요.

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

fork는 fork 지점까지 같은 기록을 공유하는 독립 thread를 만듭니다. 한 fork에서의 변경 사항은 다른 fork에 영향을 주지 않습니다. 이는 접근 방식을 비교하거나(예: “fork하고 Memcached 대신 Redis를 시도해 보기”) 위험한 변경을 안전하게 탐색할 때 유용합니다.

Thread를 sub-agent로 forking(v0.107.0): 이제 thread를 독립적인 sub-agent로 fork할 수 있어, 대화가 자율적으로 실행되는 병렬 작업 흐름을 만들 수 있습니다. 이는 기존 fork model을 확장합니다. 단순히 대화를 분기하는 데 그치지 않고, fork된 thread가 자체 실행 컨텍스트를 가진 sub-agent가 됩니다.⁶² v0.117.0부터 sub-agent는 path 기반 주소(예: /root/agent_a)와 구조화된 agent 간 messaging을 사용하므로, multi-agent coordination이 더 명시적이고 디버그하기 쉬워졌습니다.⁷⁵

Thread Listing

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

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

desktop app에서는 thread가 sidebar에 표시되며 전체 기록과 diff preview를 확인할 수 있습니다.

Session Lifecycle

세션은 CLI와 desktop app 사이에서 동기화됩니다. 한쪽에서 시작하고 다른 쪽에서 계속 이어서 작업할 수 있어요.

비대화형 모드 (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)

세션은 이력을 삭제하지 않고도 resume/fork 목록을 집중된 상태로 유지하도록 보관할 수 있습니다. TUI에서는 /archive로 보관하거나, shell에서는 다음 명령을 사용하세요.¹⁰⁶

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

보관된 세션은 보관을 해제하기 전까지 resume 또는 fork 작업으로부터 보호됩니다. 종료하려던 세션을 실수로 계속 이어가는 일을 막아 주는 안전장치입니다. 같은 릴리스에서 codex app-server --stdio는 editor/host 통합을 위해 app-server를 stdio 모드로 실행하며, /diff는 이제 저장소가 제공하는 Git helper를 실행하지 못하도록 차단됩니다. 이는 명령 안전성 수정입니다. Windows에서는 관리자용 alpha 프로비저닝 경로에 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은 다른 프로세스가 구동하도록 설계된 headless app-server를 시작하는 최상위 명령입니다. IDE 확장, 맞춤 orchestrator, 원격 제어 plane 등에 사용할 수 있습니다. 여러 통합 도구가 직접 이어 붙이던 다중 플래그 codex app-server 호출을 대체하며, 서드파티 tooling에 desktop과 IDE 표면 아래에 함께 제공되는 동일한 app-server 런타임으로 들어가는 단일하고 안정적인 진입점을 제공합니다.⁹¹ v0.133.0은 이 명령의 런타임 형태를 개선했습니다. foreground 명령처럼 실행하고, 준비 상태를 기다리고, machine status를 보고하면서도 오래 실행되는 controller setup을 위해 명시적인 daemon 스타일 start / stop 명령을 계속 제공할 수 있습니다.⁹⁸

# 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.

모든 turn을 한 번에 메모리에 hydrate하지 않고도 큰 thread 이력을 열거해야 하는 UI를 빌드한다면, codex remote-control을 아래의 app-server pagination API와 함께 사용하세요.

App-Server Thread Pagination (v0.130.0+)

App-server client는 이제 3가지 서로 다른 turn item view를 통해 큰 thread를 page 처리할 수 있습니다.⁹¹

특히 orchestrator가 rollout 파일과 다른 machine에 있을 수 있는 remote-control 배포에서 오래 실행되는 thread를 효율적으로 탐색하려면, pagination을 v0.121.0에서 도입된 ThreadStore interface와 함께 사용하세요.⁸²

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

실시간 app-server thread는 이제 재시작 없이 config.toml 변경 사항을 반영합니다. config를 편집하고 저장하면 실행 중인 thread가 다음 turn에서 새 값을 반영합니다. 이는 codex remote-control에 대응하는 bug fix입니다. 오래 실행되는 headless server를 종료하지 않고도 제자리에서 다시 설정할 수 있습니다.⁹¹

Codex Cloud와 Background Tasks [EXPERIMENTAL]

상태: Codex Cloud는 experimental 기능입니다. interface, 가격, 제공 여부는 변경될 수 있습니다. OpenAI가 cloud environment를 관리하며, 사용자는 infrastructure를 제어하지 않습니다.

Codex Cloud는 OpenAI가 관리하는 환경에서 작업을 비동기적으로 실행합니다.⁴ Codex를 CI pipeline에 통합하려면 GitHub Action & CI/CD도 참고하세요.

작동 방식

1. 작업을 제출합니다(chatgpt.com/codex, Slack integration 또는 CLI를 통해).
2. Codex가 repo를 격리된 cloud sandbox로 clone합니다.
3. 에이전트가 독립적으로 작업합니다. 코드를 읽고, test를 실행하고, 변경합니다.
4. 완료되면 Codex가 PR을 만들거나 검토용 diff를 제공합니다.
5. codex apply <TASK_ID>로 결과를 local에 적용합니다.

Cloud의 인터넷 액세스

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

• Off: 에이전트 인터넷 액세스 없음(기본값)
• On: 선택적 domain allowlist + HTTP method 제한

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

에이전트 인터넷이 꺼져 있어도 setup script는 dependency 설치를 위해 인터넷을 계속 사용할 수 있습니다.

Slack Integration

Slack channel 또는 thread에서 @Codex를 mention하면 cloud task가 시작됩니다.

전제 조건: 1. 대상 ChatGPT plan(Plus, Pro, Business, Enterprise 또는 Edu) 2. 연결된 GitHub account 3. 설정된 cloud environment 1개 이상 4. workspace에 설치된 Slack app

Codex는 task link로 답장하고 완료되면 결과를 게시합니다.

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 버전은 2026년 3월 4일에 native PowerShell 지원과 native Windows sandbox를 포함해 출시되었어요.⁶⁶

설치

codex app                      # Auto-downloads and installs on first run

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

주요 기능

Appshots, Browser Comments, Computer Use

5월 21일 app 업데이트로 desktop app은 단순한 thread manager가 아니라 더 강력한 context surface가 되었어요. Codex가 작업하기 전에 다른 Mac app의 상태가 필요할 때는 Appshots를 사용하세요. Codex는 맨 앞 window, app이 노출하는 사용 가능한 visible/off-screen text를 캡처하고, 해당 첨부 파일을 session history에 로컬로 저장해요.⁹⁹

웹과 frontend 작업에서는 페이지에 인증이 필요 없을 때 먼저 in-app browser를 사용하세요. Codex와 사용자가 공유하는 rendered preview를 제공하고, 클릭, screenshot, asset download, read-only inspection JavaScript 같은 browser-use action을 지원하며, Codex가 다음 turn에서 처리할 수 있도록 페이지 영역에 댓글을 표시할 수 있어요.⁹⁹ 로그인된 사이트에서는 계속 Chrome extension을 사용하세요.

Computer Use는 구조화된 integration이나 browser preview로 작업을 검증할 수 없을 때만 사용하세요. 허용된 Mac app을 검사하고 조작할 수 있지만, 파일 편집과 shell command에는 Codex approvals와 sandbox rules가 그대로 적용돼요. locked use의 범위도 좁게 유지됩니다. Mac이 잠긴 뒤 활성화된 신뢰 Computer Use turn 중에는 Codex가 허용된 app에 일시적으로 접근할 수 있으며, relocking safeguards와 local-input detection이 적용돼요.⁹⁹

Thread Modes

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

Worktree 격리 방식:

Worktree thread를 시작하면 desktop app은 다음을 수행해요. 1. 임시 디렉터리에 새 git worktree(git worktree add)를 생성해요 2. 현재 HEAD에서 새 branch를 checkout해요 3. worktree 안에서 agent를 실행해요. 모든 파일 변경은 격리돼요 4. 완료 후 diff review를 보여줘요. 어떤 변경을 다시 merge할지 선택해요

즉, 여러 Worktree thread가 같은 repo에서 충돌 없이 동시에 실행될 수 있어요. 각 thread는 고유한 branch와 working directory를 가져요.

Automations

Automations는 app에서 로컬로 실행되므로 app이 실행 중이어야 하고 프로젝트가 디스크에서 사용 가능해야 해요.

• Git repo에서는 automations가 전용 background worktrees를 사용해요(working directory와 격리됨)
• Git이 아닌 프로젝트에서는 run이 프로젝트 디렉터리에서 직접 실행돼요
• Automations는 기본 sandbox 설정을 사용해요

automation 설정하기: 1. desktop app에서 프로젝트를 여세요 2. sidebar에서 Automations tab을 클릭하세요 3. trigger를 정의하세요(schedule, webhook, manual) 4. prompt를 작성하고 실행 모드(local 또는 worktree)를 선택하세요 5. automation run의 reasoning level을 설정하세요(App v26.312)⁷² 6. Automations가 일정에 따라 실행되고 검토할 결과를 queue에 넣어요

예시 사용 사례: - Issue triage: 새 issue를 자동으로 분류하고 우선순위를 매겨요 - CI monitoring: build failure를 감시하고 수정안을 제안해요 - Alert response: monitoring alert에 diagnostic analysis로 대응해요 - Dependency updates: security patch를 확인하고 적용해요

결과는 사람이 승인할 수 있도록 review queue에 표시돼요.

Windows 지원

Codex Desktop App은 2026년 3월 4일(App v26.304) Windows에 출시되었으며, native PowerShell 지원, native Windows sandbox, 그리고 WSL 없이도 skills, automations, worktrees를 포함한 전체 feature parity를 제공해요.⁶⁶

GitHub Action 및 CI/CD

공식 GitHub Action은 Codex를 CI/CD pipeline에 통합해요.¹⁸

기본 사용법

# .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, downstream steps/jobs에서 사용할 final Codex response text입니다.

Safety Strategies

Access Controls

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

기본값: write access가 있는 collaborators만 Codex workflows를 trigger할 수 있어요.

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(...): 중간 업데이트를 위한 비동기 이벤트 스트림
• Python SDK auth (v0.132.0+): API-key 로그인, ChatGPT 브라우저/device-code 플로, 계정 확인, 로그아웃이 정식 SDK 경로로 제공됩니다.⁹⁷
• 텍스트 전용 턴 편의 기능 (v0.132.0+): Python turn APIs는 일반 문자열을 받을 수 있으며, 수집된 항목, 타이밍, 사용량이 포함된 더 풍부한 TurnResult 메타데이터를 반환합니다.⁹⁷
• outputSchema: JSON 형태의 최종 출력을 강제합니다
• 멀티모달 입력: 텍스트 + 로컬 이미지({ type: "local_image", path: "..." })를 전달합니다
• 이미지 워크플로 (v0.117.0): view_image가 URL을 반환하고, 생성된 이미지를 다시 열 수 있으며, 세션 재개 후에도 이미지 기록이 유지됩니다⁷⁵
• 다중 환경 view_image (v0.130.0): 여러 환경에 걸친 세션(v0.124.0에서 턴별 환경 + 작업 디렉터리 선택으로 도입되고, 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: 낮은 추론 설정의 사전 구성된 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 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에 이슈를 등록하세요.¹

Codex Security [PREVIEW]

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

작동 방식: Codex Security는 저장소를 분석해 프로젝트별 위협 모델을 만들고, 실제 영향 기준으로 분류된 취약점을 식별하며, 샌드박스 환경에서 발견 사항을 압박 테스트해 검증합니다. 이 에이전트는 수정안과 함께 신뢰도가 더 높은 발견 사항을 보여 주어, 중요하지 않은 버그로 인한 잡음을 줄입니다.

성능: research preview 기간 동안 Codex Security는 120만 개의 커밋을 스캔하고 10,561개의 고위험 취약점을 식별했습니다. 정밀도는 시간이 지나며 개선되어 잡음을 84% 줄였고, 과도하게 보고된 심각도는 90% 이상 줄였으며, false positive 비율은 절반으로 낮췄습니다. 이 시스템은 OpenSSH, GnuTLS, Chromium에서 실제 취약점을 발견했고, 14개의 CVE가 배정되었습니다.⁷⁷

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

Enterprise 배포

Admin Controls (requirements.toml)

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

# /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은 사용자가 선택할 수 있는 값을 제한하는 강제 제약 계층이며 사용자는 이를 재정의할 수 없습니다. 관리자 요구사항 규칙은 prompt 또는 forbid만 가능하며, 조용히 허용하는 동작은 없습니다.

macOS MDM 구성

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

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

1. macOS 관리형 preferences (MDM)
2. Cloud에서 가져온 requirements (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (로컬 파일 시스템)

Cloud requirements는 설정되지 않은 requirement 필드만 채우므로, 우선순위가 더 높은 관리 계층이 항상 우선합니다. Cloud requirements는 best-effort 방식입니다. 가져오기에 실패하거나 시간이 초과되면 Codex는 cloud 계층 없이 계속 실행됩니다.

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_* 환경 변수(endpoint, service name, resource attributes)가 적용됩니다
• Trace context가 Codex를 통해 API 호출까지 전파되어 end-to-end 관측성을 제공합니다
• Resource attributes를 사용해 팀, 환경, 프로젝트별로 traces에 태그를 지정하세요
• prompt/tool 로깅을 활성화할 때는 개인정보 보호 요구사항을 염두에 두세요. traces에 코드 조각이 포함될 수 있습니다
• 구성 가능한 OpenTelemetry trace metadata (v0.130.0+). 표준 OTEL_RESOURCE_ATTRIBUTES envelope 외에도, 이제 codex-otel crate는 구성 가능한 trace metadata를 제공하므로 관리자는 호출할 때마다 OTEL_RESOURCE_ATTRIBUTES를 처음부터 다시 만들지 않고도 조직별 차원(cost-center, project ID, ticket reference)으로 traces에 태그를 지정할 수 있습니다. 같은 릴리스에 포함된 더 풍부한 review/feedback analytics와 함께 사용하면 CLI, app-server, remote-control 세션 전반에서 통합 디버깅과 triage를 수행할 수 있습니다.⁹¹

Enterprise 액세스

• ChatGPT Business / Enterprise / Edu: Org-admin이 제어하는 액세스이며, cloud에서 가져온 requirements가 자동으로 적용됩니다. ID 공급자(Okta, Entra ID 등)를 통한 SAML/OIDC 기반 SSO를 지원합니다
• API: 표준 API auth, billing, org/project controls입니다. OpenAI는 SOC 2 Type II 및 SOC 3 보고서를 공개하며, Enterprise tier에서는 HIPAA BAA를 사용할 수 있습니다
• Codex SDK: 내부 도구와 워크플로에 임베드하세요
• 대규모 정책 적용: MDM으로 배포되는 requirements_toml_base64 또는 파일 시스템 수준의 /etc/codex/requirements.toml을 사용하세요

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

Rollout 전략

조직에는 다음과 같은 단계적 rollout을 권장합니다:

1. Pilot (1-2주차): requirements.toml로 untrusted sandbox mode와 cached web search를 강제해 senior engineer 3-5명에게 배포합니다. AGENTS.md 패턴과 MCP 서버 요구사항에 대한 피드백을 수집합니다.
2. 팀 확장 (3-4주차): 전체 팀으로 rollout합니다. 팀 표준 config.toml을 MDM 또는 repo를 통해 배포합니다. 신뢰할 수 있는 repositories에는 workspace-write sandbox를 활성화합니다.
3. CI 통합 (5-6주차): 자동 PR review와 test generation을 위해 CI/CD pipelines에 codex-action을 추가합니다. 비용 예측 가능성을 유지하려면 --ephemeral을 사용합니다.
4. 조직 전체 (2개월차 이후): 승인된 MCP servers, sandbox policies, model allowlists를 강제하는 requirements.toml과 함께 MDM으로 배포합니다.

Audit 패턴

Codex 사용량을 추적하고 컴플라이언스를 적용하세요:

• OpenTelemetry traces: 팀별 API 호출량, token 사용량, latency를 모니터링합니다
• Session persistence: 컴플라이언스 검토를 위해 ~/.codex/sessions/를 audit합니다(민감한 context에서는 --ephemeral로 비활성화)
• MCP identity enforcement: requirements.toml은 차단된 서버 시도를 로깅합니다. 승인되지 않은 도구 사용 여부를 검토하세요
• Git audit trail: 모든 Codex 파일 변경은 표준 git을 거칩니다. branch history와 PR diffs로 검토하세요

모범 사례와 안티 패턴

Prompting 패턴

1. 제약 조건 중심 prompts: 경계부터 제시하세요. “Do NOT change the API contracts. Only refactor internal implementation.”
2. 구조화된 재현 단계: 모호한 설명보다 번호가 매겨진 단계가 더 나은 버그 수정을 이끌어냅니다
3. 검증 요청: 마지막에 “Run lint + the smallest relevant test suite. Report commands and results.”처럼 요청하세요.
4. 파일 참조: @filename을 사용해 특정 파일을 context에 첨부하세요
5. 결과 중심 루프: “Implement, run tests, fix failures, stop only when all tests pass.” Codex는 완료될 때까지 반복합니다

테스트 철학

커뮤니티는 테스트 주도 AI 협업으로 수렴하고 있습니다:²²

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

Context 관리 모범 사례

• web search에 의존하기보다 품질 높은 로컬 문서를 제공하세요
• 목차와 진행 파일이 있는 구조화된 markdown을 유지하세요(“progressive disclosure”)
• 패치 실패를 방지하려면 추적되는 파일 전체에서 줄 끝(LF vs CRLF)을 정규화하세요
• 긴 지침은 context에서 밀려나므로 AGENTS.md를 간결하게 유지하세요

Git Workflow

• 익숙하지 않은 repos에서 Codex를 실행하기 전에 항상 새 branch를 만드세요
• 직접 편집보다 패치 기반 workflow(git diff / git apply)를 사용하세요
• Codex 제안은 code review PR처럼 검토하세요
• commit하기 전에 /diff로 변경 사항을 확인하세요

커뮤니티 Skills와 Prompts

feiskyer/codex-settings repository는 커뮤니티가 관리하는 설정을 제공합니다:²³

재사용 가능한 prompts(~/.codex/prompts/): - deep-reflector: 개발 세션에서 학습 내용을 추출합니다 - github-issue-fixer [issue-number]: 체계적인 버그 분석과 PR 생성을 수행합니다 - github-pr-reviewer [pr-number]: Code review workflow를 수행합니다 - ui-engineer [requirements]: 프로덕션 수준의 frontend 개발을 수행합니다

커뮤니티 skills: - claude-skill: 권한 모드와 함께 작업을 Claude Code에 handoff합니다 - autonomous-skill: 진행 상황 추적이 포함된 다중 세션 작업 자동화 - deep-research: 병렬 하위 작업 오케스트레이션 - kiro-skill: 요구 사항 → 설계 → 작업 → 실행 pipeline

안티 패턴

토큰을 낭비하거나, 낮은 품질의 결과를 만들거나, 답답한 workflow를 만드는 흔한 실수입니다.

비용 안티 패턴

Context 안티 패턴

Workflow 안티 패턴

Prompt 안티 패턴

Workflow 레시피

일반적인 개발 시나리오를 위한 end-to-end 패턴입니다.

레시피 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: 일일 개발 Flow

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로 검토한 다음 commit하세요.

레시피 3: Plan Mode를 사용한 복잡한 Refactor

codex

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

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

[Tab] Also add a migration script using Alembic

Codex가 실행한 후 검증하세요:

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

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

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>

완료되면 fix를 로컬에 적용하세요:

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는 구조화된 agent 간 메시징과 agent 목록 표시와 함께 경로 기반 주소(예: /root/agent_a)를 사용합니다.⁷⁵ 이는 기존 메커니즘(동시 최대 6개, v0.91.0에서 12개에서 축소)을 확장합니다. 다중 agent 역할은 config를 통해 계속 사용자 지정할 수 있습니다(v0.104.0+).⁴⁷ v0.105.0에서는 진행률 추적과 ETA를 포함해 행 단위 fanout을 수행하는 spawn_agents_on_csv가 추가되었습니다.⁶¹ Codex에는 사용자 주도 위임을 위한 Claude Code의 명시적인 Task 도구 UX가 아직 없습니다. 위임 패턴에는 cloud tasks나 SDK 오케스트레이션을 사용하세요.
• AGENTS.md는 도구 간에 사용할 수 있습니다: AGENTS.md는 Cursor, Copilot, Amp, Jules, Gemini CLI, 그리고 60,000개 이상의 open source 프로젝트에서 작동합니다. CLAUDE.md는 Claude 전용입니다.
• Profiles가 수동 전환을 대체합니다: 실행할 때마다 flags를 바꾸는 대신 config.toml에 profiles를 정의하세요.

GitHub Copilot에서 이전하기

얻게 되는 점: - OS 수준 sandboxing (Seatbelt/Landlock — 컨테이너 기반이 아니라 커널에서 강제) - codex apply를 통한 cloud task 위임 - 워크플로 전환을 위한 config profiles - worktree 격리를 제공하는 desktop app

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 블로그 URL 참고: References ¹⁶, ²⁵-³⁰, ³³, ⁶⁴, ⁶⁶, ⁶⁷, ⁷⁶, and ⁷⁷는 openai.com/index/ 블로그 게시물로 연결되며, Cloudflare 봇 보호 때문에 자동화된 접근에는 HTTP 403을 반환합니다. 이 URL들은 일반 웹 브라우저로 접속하면 유효합니다.