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

요약: Codex는 여러 환경에서 작동하는 코딩 에이전트입니다. 코드베이스를 읽고, 운영체제 수준의 샌드박스에서 명령을 실행하고, 파일을 수정하며, 작업을 클라우드에 위임합니다. config.toml, 샌드박스/승인 모델, AGENTS.md, MCP, skills라는 5가지 시스템을 익히면 Codex를 강력한 생산성 도구로 활용할 수 있습니다. 모델 선택: 이제 OpenAI의 모델 문서는 일상적인 코딩과 복잡한 코딩에는 GPT-6 Sol(gpt-6-sol, v0.156.1부터 CLI 선택기에 포함), 가장 어려운 전체 과정 작업에는 GPT-6-Astra(모델을 설정하지 않았을 때 여전히 CLI에 포함된 기본값), 범위가 명확한 대량 작업에는 GPT-6 Luna를 안내합니다. 사용 가능 여부는 요금제, 워크스페이스 설정, 배포 상황에 따라 달라지며, 그동안 GPT-5.6 모델도 계속 사용할 수 있습니다. GPT-5.5는 ChatGPT 로그인 방식의 Codex에서 2026년 10월 14일에 지원이 종료됩니다.¹⁴⁶¹⁷¹ 처음 사용합니까? 설치와 빠른 시작으로 바로 이동하세요. 릴리스를 추적하고 있습니까? 최신 안정 버전은 v0.157.1(2026년 9월 26일)입니다. 릴리스 주요 내용에서는 현재 상태 요약(기본으로 활성화된 기능과 아직 실험 단계인 기능)을 먼저 제시한 뒤 각 버전을 설명하며, 변경 기록에는 가이드의 모든 업데이트가 정리되어 있습니다.¹¹⁶¹⁷⁴

Codex는 단순히 코드를 작성하는 챗봇이 아니라 여러 환경에서 작동하는 코딩 에이전트입니다. CLI는 코드베이스를 읽고, 샌드박스에서 명령을 실행하고, 파일을 수정하고, MCP를 통해 외부 서비스에 연결하며, 오래 걸리는 작업을 클라우드에 위임합니다. Codex는 로컬에서 실행되지만 전체 환경을 아우르며 작동합니다. 작업 방식에 따라 동일한 지능을 5가지 환경에서 활용할 수 있으며, 여기에는 브라우저를 장악하지 않고도 Codex를 브라우저에서 실행하는 브라우저 확장 프로그램(Chrome, Edge, Brave, Opera, Vivaldi)도 포함됩니다.⁹⁰¹²⁷

Codex를 가볍게 사용하는 것과 효과적으로 활용하는 것의 차이는 5가지 핵심 시스템에 달려 있습니다. 이를 익히면 Codex를 강력한 생산성 도구로 활용할 수 있습니다.

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

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

핵심 요점

• 5가지 환경, 하나의 두뇌: CLI, 데스크톱 앱, IDE 확장 프로그램, cloud tasks, 브라우저 확장 프로그램(Chrome, Edge, Brave, Opera, Vivaldi)은 모두 동일한 모델 제품군을 공유하므로, 워크플로에 맞는 환경을 선택하세요.⁹⁰
• 운영체제 수준의 샌드박싱: 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로 전환할 수 있습니다.
• 컨텍스트 관리의 중요성: 기본 제공되는 Codex 카탈로그에서는 GPT-6 Astra, Sol, Luna와 GPT-5.6 제품군에 272K 컨텍스트 창을 제공합니다(API에는 GPT-6 Sol과 Luna가 1.05M으로 명시되어 있습니다). GPT-5.5는 2026년 10월 14일 Codex에서 지원이 종료될 때까지 400K를 제공합니다. /compact, 범위를 명확히 한 프롬프트, @file 참조를 사용하여 토큰 예산을 선제적으로 관리하세요.⁸³¹¹²

이 가이드의 활용 방법

이 문서는 3,300줄이 넘는 레퍼런스입니다. 자신의 경험 수준에 맞는 부분부터 시작하세요.

문서 끝의 빠른 참조 카드에서는 모든 주요 명령을 한눈에 살펴볼 수 있도록 요약해서 제공합니다.

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

Codex의 릴리스 흐름을 추적하는 독자를 위해 최신 버전부터 정리한 버전별 기록입니다. 처음 접하십니까? 빠른 시작으로 건너뛰어도 됩니다. 아래 내용은 Codex를 생산적으로 사용하는 데 필요하지 않습니다. 검증 세부 정보(비교, 커밋 목록, 문서 확인)는 각주에서 확인할 수 있습니다.

현재 상태

2026년 9월 26일 기준 Codex CLI

• 안정 버전: v0.157.1, 9월 26일 게시(npm latest). v0.157.0(9월 25일)에 Windows 패치를 적용한 버전입니다.
• 알파 버전: npm alpha는 0.159.0-alpha.4입니다. 0.158 계열은 안정 버전으로 출시되지 않았습니다.
• v0.157.0부터 기본 활성화: 전체 화면 대화 기록, 백그라운드 서버 자동 시작, Guardian 스레드 컨텍스트입니다. 기능을 끄려면 [tui] 아래에서 fullscreen_transcript = false, [features] 아래에서 daemon_auto_start = false를 설정하거나 --no-daemon으로 실행하고, [features.guardianv2] 아래에서 thread_context = false를 설정하세요.
• v0.156.0부터 기본 활성화: /voice, 관리형 worktrees, Guardian 상위 압축 재사용([features] 키 realtime_conversation, worktrees, guardian_reuse_parent_compaction)입니다.
• 여전히 별도 활성화가 필요하거나 실험적인 기능: 실험적 컨텍스트 관리, Codex Cloud, 코드 모드입니다.
• 모델: 일상적이고 복잡한 코딩에는 GPT-6 Sol(gpt-6-sol), 가장 어려운 전체 과정 작업에는 GPT-6-Astra(모델을 설정하지 않았을 때 여전히 CLI에 포함된 기본 모델), 대량 작업에는 GPT-6 Luna를 사용합니다. GPT-5.5는 2026년 10월 14일에 ChatGPT 로그인 방식의 Codex에서 제외됩니다.
• 버전 고정: npm install -g @openai/codex@0.157.1을 실행한 다음 codex --version으로 확인하세요.¹⁷⁴¹⁷⁵

v0.157.1 (2026년 9월 26일)

main에서 역이식한 4가지 수정 사항으로 구성된 Windows 패치입니다. 이제 Codex가 코드 모드 호스트나 로컬 stdio MCP 서버를 시작할 때 콘솔 창을 열지 않습니다. Windows가 프로세스를 외부 작업 객체 안에 둔 경우에도 백그라운드 서버를 실행할 수 있으며, 분리된 백그라운드 서버가 더 이상 실행 프로그램의 출력 파이프를 열린 상태로 유지하지 않습니다. 이 문제로 실행 프로그램이 종료된 뒤에도 호출 명령이 계속 대기할 수 있었습니다. GitHub 릴리스 노트와 변경 기록 항목에는 주요 내용을 “확인할 수 없다”고만 나옵니다. 위 목록은 해당 릴리스의 커밋을 바탕으로 작성했습니다.

해야 할 일: Windows에서 Codex를 실행한다면 업그레이드하세요. 4가지 수정 사항은 모두 Windows에만 적용됩니다.¹⁷⁴

v0.157.0 (2026년 9월 25일)

3가지 기능을 추가로 기본 활성화한 릴리스입니다.

• 전체 화면 대화 기록이 기본으로 활성화됩니다. 이제 설정에 [tui] 섹션이 없어도 세션을 열면 v0.156.0에서 /tui를 통해 제공하던 전체 화면 UI가 표시됩니다. 터미널 스크롤 기록을 유지하려면 /tui에서 Scrollback을 선택하거나 [tui] 아래에서 fullscreen_transcript = false를 설정하세요. --no-alt-screen과 tui.alternate_screen = "never"가 여전히 우선 적용됩니다. 이제 Shift를 누른 채 클릭하면 대화 기록 선택 범위가 확장됩니다.
• 조건을 충족하는 대화형 실행에서는 백그라운드 서버가 자동으로 시작되며 이 옵션은 /experimental에서 제외됩니다. --no-daemon, --oss, --profile 또는 대부분의 -c 재정의를 사용한 실행에서는 이 기능을 사용하지 않습니다. 실행 중인 서버의 설정이 세션과 일치하지 않으면 Codex는 해당 서버를 사용하지 않고 실행하거나, 필요한 설정으로 서버를 다시 시작하거나, 취소하는 옵션을 제시하며 기본값은 취소입니다. 자동 시작을 끄려면 [features] 아래에서 daemon_auto_start = false를 설정하세요.
• 동기 및 비동기 검토에서 Guardian 스레드 컨텍스트가 기본으로 활성화되며 Guardian v2의 enabled 설정과는 별개로 작동합니다. 끄려면 [features.guardianv2] 아래에서 thread_context = false를 설정하세요.

모델: v0.156.1에서 처음 제공된 GPT-6 Sol과 Luna가 이 릴리스에도 포함됩니다. 이제 Amazon Bedrock 카탈로그에서도 두 모델을 제공하며, Bedrock의 기본 모델은 GPT-5.6 Sol에서 GPT-6 Sol로 변경됩니다. GPT-5.6 Sol에서는 ultrafast 서비스 티어가 제거되고 Fast만 남습니다. 포함된 카탈로그에서는 GPT-6-Astra가 더 이상 실험적 컨텍스트 관리를 지원하는 것으로 표시되지 않습니다(컨텍스트 관리 참조).

그 밖의 새로운 기능으로, 다른 앱에서 열린 대화를 초안과 대기 중인 프롬프트까지 유지한 채 분기하는 f 단축키가 추가되었습니다. /import는 원격 및 백그라운드 서버 세션에서 작동하며, 터미널은 유니코드 글머리 기호, 체크박스, 정렬된 수식을 렌더링합니다. 수정 사항을 통해 스레드를 전환해도 음성 대화가 계속되고, 턴이 끝날 때 전송하지 않은 답변을 복구하며, tmux 마우스 설정을 준수합니다. 또한 실시간 연결과 독립 실행형 웹 검색을 설정된 프록시를 통해 라우팅하고, 일시적으로 실패한 파일 업로드를 5분 제한 시간으로 재시도하며, 리디렉션과 개방형 HTTP 및 WebSocket 연결 전체에 네트워크 제한을 적용합니다. Windows에서는 sandbox 객체 접근이 실행 프로그램의 로그온 세션으로 제한됩니다.¹⁷⁴

v0.156.1 (2026년 9월 23일)

GPT-6 Sol과 GPT-6 Luna를 안정 버전 CLI에 추가한 단일 변경 패치입니다. 이제 두 모델이 /model 선택기에서 GPT-6-Astra 아래에 표시됩니다. GPT-6-Astra는 계속 첫 번째로 표시되며, config.toml에 모델이 설정되지 않았을 때 포함된 기본 모델로 유지됩니다. 선택기에서는 GPT-5.6 계열을 이전 모델로 다시 표시하며, GPT-5.6 Sol의 설명은 “복잡한 작업을 위한 이전 코딩 모델”로 나옵니다. GPT-5.5는 “레거시 코딩 모델”로 표시됩니다. 사용량 제한에 가까워지면 모델 전환 안내에서 이제 gpt-5.6-luna 대신 gpt-6-luna를 제안합니다.

설정에서 이전 모델을 지정했다면 일회성 마이그레이션 안내가 표시됩니다. 저장된 gpt-5.6-sol, gpt-5.6-terra, gpt-5.5, gpt-5.4 선택은 GPT-6 Sol을 가리키며, gpt-5.6-luna와 gpt-5.4-mini는 GPT-6 Luna를 가리킵니다. 이 릴리스에서는 Amazon Bedrock 카탈로그가 변경되지 않습니다. GPT-6 Sol이나 Luna가 없으며, GPT-5.6 Sol이 계속 Bedrock의 기본 모델입니다.

문서에서 언급하지 않은 비용 관련 세부 사항이 하나 있습니다. 포함된 카탈로그는 GPT-6 Sol과 Luna의 기본 서비스 티어를 Fast(priority)로 설정하므로, service_tier를 설정하지 않은 TUI 세션은 Fast 모드로 시작할 수 있습니다. ChatGPT 로그인에서는 이 모드에 Standard 크레딧의 2.5배가 청구됩니다. /fast status로 확인할 수 있으며 /fast off를 실행하면 Standard로 전환됩니다.

해야 할 일: 업그레이드한 다음 익숙한 작업에서 codex -m gpt-6-sol을 사용해 보세요. 사용 가능 여부는 요금제, 작업 공간 설정, 배포 상태에 따라 다릅니다. Enterprise 관리자는 먼저 새 모델을 활성화해야 합니다.¹⁷¹

v0.156.0 (2026년 9월 22일)

3가지 기능을 동시에 기본 활성화한 릴리스이며, 문서 변경 기록에서도 같은 날 그중 처음 2가지를 발표했습니다.

• 음성이 기본으로 활성화됩니다. 지원되는 빌드에서는 /experimental을 거치지 않고 /voice로 실시간 대화를 시작할 수 있습니다. 새로 추가된 기능으로는 설정 가능한 F8 전환 키, 이후 대화에서 사용할 음성을 고르는 /voice settings 선택기, Linux 및 Windows용 내장 음성 런타임, 동작 줄이기 지원이 있습니다.
• 관리형 worktrees가 기본으로 활성화됩니다. --worktree와 /worktree에 더 이상 기능 플래그가 필요하지 않습니다. worktree 세션은 기존 로컬 daemon에 연결할 수 있으며 에이전트 개요에서 생성할 수도 있습니다.
• Guardian 상위 압축 재사용이 기본으로 활성화됩니다. Guardian이 검토 세션을 다시 시작할 때 상위 스레드의 암호화된 압축을 재사용할 수 있습니다.

각 기능을 끄는 방법은 슬래시 명령 표의 /voice 및 /worktree 행과 Guardian 섹션에 나와 있습니다.

그 밖의 새로운 기능으로, /tui에서 선택할 수 있으며 대화 기록 검색, 마우스를 이용한 선택 및 복사, 오른쪽 클릭 복사, 클릭 가능한 링크, 경고 뷰어를 제공하는 선택적 전체 화면 TUI가 추가되었습니다. /theme 선택기에는 내장 테마 6개가 추가되었고, /usage 분석 대시보드, 터미널에서 렌더링되는 Mermaid 다이어그램과 TeX 수식 및 각각의 전환 설정, /daemon 메뉴와 --no-daemon 플래그도 추가되었습니다. 새 TUI 스레드에서는 추론 요약이 기본으로 비활성화됩니다. 보안 수정으로 Windows의 인바운드 트래픽, 권한 소켓, 읽기 전용 파일 핸들과 관련된 sandbox 허점을 막았으며, 이제 codex doctor가 오류에 설정값을 그대로 표시하지 않습니다. 버그 수정으로 실패하거나 중단된 턴 이후에도 스트리밍된 답변을 유지하고, tmux와 SSH에서 클립보드 전달을 복구하며, 재개 시 Plan 모드를 복원하고, 시스템 프록시를 통한 로그인 복구를 지원합니다.¹⁶⁹

v0.155.1 (2026년 9월 18일)

하나의 문제를 수정한 긴급 패치입니다. 0.155.0에서는 설정에 model_reasoning_summary가 없는 새 로컬 TUI 스레드가 detailed 요약을 요청했으며, 추론 요약을 지원하지 않는 제공자는 해당 요청을 바로 거부했습니다. 0.155.1에서는 대체값을 none으로 되돌렸으므로 키를 설정하지 않으면 요약을 요청하지 않습니다. 명시적인 auto, concise, detailed 설정은 이전부터 항상 적용되었으며 지금도 마찬가지입니다. 동일한 한 줄 변경 사항이 main에도 반영되어 0.156.0에 포함되었습니다.

해야 할 일: 0.155.0의 새 TUI 세션이 OpenAI 이외의 제공자나 자체 호스팅 제공자에서 실패했다면 업그레이드하세요. 요약을 사용하려면 해당 키를 명시적으로 설정하세요(설정 참고 자료 참조).¹⁵⁸

v0.155.0 (2026년 9월 17일)

음성 기능이 별도 활성화가 필요한 실험적 기능으로 안정 버전 TUI에 도입되었습니다. 지원되는 빌드에서 /experimental을 통해 활성화하면 /voice로 스트리밍 대화 기록과 마이크 제어 기능이 있는 실시간 대화를 열 수 있었습니다. 음소거 단축키를 설정할 수 있었으며 macOS 패키지에는 서명된 음성 리소스가 포함되었습니다. 5일 뒤 v0.156.0에서 기본으로 활성화되었습니다. 이 릴리스에서는 관리형 worktrees가 계속 기본으로 비활성화되었습니다.

0.155.0에는 다음 기능도 포함됩니다.

• MCP 사용자 확인: 지원되는 Mac의 로컬 TUI 세션에서 Secure Enclave가 서명한 Touch ID 확인을 MCP 요청에 사용합니다. 작업 공간 범위로 신원을 제한하며 MCP 도구 연속 실행에서도 네이티브 확인을 지원합니다.
• Windows의 /sandbox-add-read-dir 슬래시 명령이 제거되었습니다.
• Worktree 관리: 에이전트 개요에서 worktree 세션을 숨기거나 보관 또는 삭제하고, 소유권 세부 정보를 확인하며, 변경 사항이 없는 관리형 worktree를 삭제하기 전에 확인합니다.
• 실시간 추론 요약이 TUI 상태 행에 스트리밍되며 완료된 작업에는 완료 시간이 표시됩니다.
• Daemon: 설정 가능한 업데이트 일정, codex app-server daemon update 명령, daemon 재시작 이후의 스레드 복구가 추가되었습니다.
• Amazon Bedrock AWS 자격 증명 명령과 안정 버전 CLI 릴리스에 맞춘 Python SDK 게시 기능이 추가되었습니다.

보안 수정으로 WSL 상호 운용 탈출과 셸 스냅샷을 통한 자격 증명 노출을 막았습니다. Memory v2는 저장 및 통합을 위한 기반만 추가되었으며 아직 사용할 수 있는 기능은 아닙니다.¹⁵⁶

v0.154.0 (2026년 9월 9일)

이 릴리스는 대략 0.154.0-alpha.6 시점을 기준으로 분기되었으므로 alpha.7에서 처음 등장한 기능(실시간 TUI 음성, MCP 사용자 확인, Memory v2, daemon 자동 업데이트 설정, 추론 노력 수준 고정)은 모두 0.155까지 기다려야 했습니다.

제거된 기능: codex mcp-server와 독립 실행형 codex-mcp-server 바이너리입니다. 통합 기능은 app-server 프로토콜이나 Claude Code용 Codex 플러그인으로 이전하세요. Codex를 외부 MCP 서버에 연결하는 codex mcp는 영향을 받지 않습니다(MCP 서버로 Codex 실행하기 참조). 레거시 Guardian 승인 검토 경로도 제거되었으며, 새 사용자 지침으로 인해 승인이 무효화되면 이제 해당 승인이 거부됩니다.

새로운 기능:

• 실험적 관리형 worktrees: --worktree 또는 /worktree를 사용하며 codex exec 지원과 TUI worktree 브라우저를 제공합니다.
• 비동기 사용자 메시지: 초안을 잃지 않고 Codex가 계속 작업하는 동안 인라인 질문에 답할 수 있습니다.
• Windows 서비스 지원: sandbox 프로비저닝, Windows의 app-server daemon, 관리형 daemon 업데이트를 지원합니다.
• 원격 권한 프로필: 앱 서버에서 검색하며 TUI에서 이름으로 선택할 수 있습니다.
• Vim R 바꾸기 모드, 실시간 컨텍스트 압축 상태, 세션 시작 시 모델 기능에 따라 제한되는 실험적 컨텍스트 관리가 추가되었습니다.

보안 측면에서는 작업 공간 신뢰가 설정되기 전에 PATH 도우미가 더 이상 실행되지 않으며, macOS sandbox는 터미널 입력 주입 공격에 대응하도록 강화되었습니다. MCP 연결은 OAuth 토큰 갱신을 조정하고, 원격 재개 및 분기에서는 저장된 권한을 유지하며, 다른 앱에서 열린 대화를 재개하면 읽기 전용 대화 기록을 표시합니다. 음성 기능은 런타임 기반만 제공되었으며, 공개 문서 없이 최초의 Daybreak 코드 참조가 추가되었습니다.¹⁵²¹⁵³

v0.153.3 및 v0.153.4 (2026년 9월 4일)

GPT-6-Astra 출시 내용을 CLI에 반영한 같은 날의 패치입니다. v0.153.3은 Astra를 Amazon Bedrock 카탈로그에 추가하고(GPT-5.6 Sol은 Bedrock의 기본 모델로 유지됨) Astra의 비동기 확인 질문 지침을 수정했습니다. v0.153.4는 Astra를 모델 선택기에 추가하고, 모델을 설정하지 않았을 때 포함된 기본 모델로 지정했으며, 비동기 질문 지침이 도구 사용 가능 여부에 따라 적용되도록 했습니다.

해야 할 일: Astra는 v0.153.1부터 -m gpt-6-astra로 사용할 수 있으며 v0.153.4부터 선택기에 표시됩니다. 최소 CLI 버전은 문서에 명시되지 않았으므로 이 버전들을 각각의 하한선으로 간주하세요. 계정에 포함된 기본 모델을 사용할 권한이 없다면 기본값에 의존하지 말고 config.toml에서 model을 명시적으로 설정하세요.^145146147148

v0.153.1 및 v0.153.2 (2026년 9월 3일)

v0.153.1에서는 Guardian의 컴퓨터 사용 점수 산정이 모델 요구 사항을 따릅니다. 활성 모델의 메타데이터에 node_repl_auto_review_required가 설정된 경우에만 컴퓨터 사용 전용 점수 산정과 빠른 승인 결정이 실행됩니다. 점수 산정을 건너뛰는 모델로 전환하면 이전 점수나 산정 중인 점수가 무효화되므로, 다시 전환해도 오래된 승인이 되살아나지 않습니다. 릴리스 본문에는 API을 통해 설정할 수 있는 역이식된 GPT-6-Astra 카탈로그 항목만 기재되어 있습니다. 선택기와 기본값은 v0.153.4까지 변경되지 않았습니다. v0.153.2는 Astra Fast 티어의 설명을 “1.5배”에서 “2배 속도, 사용량 증가”로 수정합니다(표시 문구만 변경됨).¹⁴²¹⁴³

v0.153.0 (2026년 9월 3일)

• Vim 실행 취소 및 다시 실행: u와 Ctrl+R로 붙여 넣은 콘텐츠와 이미지 첨부 파일을 포함한 작성기 초안 전체를 복원할 수 있습니다. vim_normal.redo는 설정 가능한 키맵 동작입니다.
• 원격 플러그인 마켓플레이스: 플러그인 CLI에서 원격 플러그인을 나열, 설치, 제거할 수 있으며, codex plugin list는 출처, 버전, 설치 정책, 인증 정책을 표시합니다.
• tui.auto_recap = false는 자동 요약을 끕니다. 수동 /recap은 계속 작동합니다.
• Plus 및 Team의 사용량 제한 경고가 더 일찍 표시됩니다. 약 5시간의 기간에 할당량이 절반 미만으로 남으면 표시되며, 다른 요금제는 기존의 75/90/95% 기준을 유지합니다.
• Guardian 범위가 승인 모드를 따릅니다. Full Access에서는 확인만 필요한 작업에 대해 Guardian 검토를 건너뛰고, User 승인 모드에서는 백그라운드 점수 산정과 사전 준비를 건너뜁니다.
• features.context_management.experimental_mode는 기본으로 비활성화되며, Codex 백엔드의 대상 Plus, Pro, Pro Lite 세션에서 토큰 예산 기반 컨텍스트, 기록 메모, new_context 도구를 활성화합니다.
• tui.disable_paste_burst가 최상위 키를 대체하며, 기존 키도 대체 설정으로 계속 작동합니다.

수정 사항: 앱 서버 연결이 끊긴 뒤에도 초안을 유지한 채 TUI 세션이 다시 연결되고, Guardian 검토 기록이 압축, 재시작, 분기 후에도 유지되며, 기억된 MCP 승인이 선택한 계정 범위로 제한됩니다.¹⁴⁰

v0.152.0 및 v0.152.1 (2026년 9월 1일)

update_plan이 별도 활성화 방식으로 변경되었습니다. tools.update_plan.enabled의 기본값은 false이며, 비활성화된 동안에는 포함된 update_plan 지침이 모델, 협업 모드, 멀티 에이전트, 압축, 사전 준비, 목표 계속 진행 프롬프트에서 제거됩니다(Plan 모드 및 협업 참조). 그 밖의 새로운 기능으로, / 및 ?와 n/N을 사용하는 Vim 검색이 추가되었으며 연산자와 조합할 수 있고 새 초안은 Insert 모드에서 시작합니다. 조치 가능한 사용량 제한 배너, Amazon Bedrock 재인증을 포함한 자격 증명 갱신 진행 상태, 패키지 형식의 MCP 서버 이름(:, @, /, . 허용), MCP openai/elicitation 양식 요청, 도구별 MCP output_token_limit, 신뢰할 수 있는 출처로 제한되는 클라우드 작업 자격 증명, 설정 가능한 thread/shellCommand 제한 시간, 모델 메타데이터를 통해 기본 활성화되는 토큰 예산 기능이 추가되었습니다. v0.152.1에서는 Guardian 승인 검토가 모델 메타데이터에서 Node REPL 정책을 가져올 수 있습니다.¹³⁸¹³⁹

v0.151.0 (2026년 8월 29일)

• /recap은 요청할 때 대화를 요약하며, Codex는 조건을 충족하는 유휴 상태의 비활성 대화를 자동으로 요약합니다.
• 코드 모드 호스트에서 WebSocket 전송 방식이 제거됩니다(stdio와 gRPC만 지원).
• 저장소가 지원하는 경우 지속형 스레드에서 페이지가 나뉜 기록을 기본으로 사용합니다.
• 시계 도구와 내장된 선제적 작업 지침을 갖춘 persistent 추론 노력 수준이 추가됩니다.
• Guardian v2는 이미지를 포함한 컴퓨터 사용 검토를 기본으로 사용합니다.
• Vim에 f/F/t/T 찾기 및 이동 동작과 gg/G가 추가됩니다.
• 권한이 상승된 터미널에 입력할 때 새로운 승인을 요구하도록 설정할 수 있습니다(write_stdin_approval, 기본값은 비활성화).
• 선택적 MCP 서버의 유예 기간을 설정할 수 있으며(mcp_optional_startup_grace_ms, 기본값 1,000밀리초), 확장 프로그램은 MCP 도구 결과를 검사하거나 바꿀 수 있습니다.

수정 사항을 통해 /cd가 sandbox 제한을 약화하지 못하도록 하고, 권한 변경 후 오래된 Guardian 분류가 작업을 승인하지 못하도록 했습니다. 릴리스 본문에는 마지막 몇 개의 PR만 기재되어 있으며 전체 변경 사항은 비교 내역에서 확인할 수 있습니다.¹³⁴¹³⁵

v0.150.0 및 v0.150.1 (2026년 8월 26~27일)

hooks에 활성화된 최상위 턴이 중단될 때 실행되는 Interrupt 이벤트가 추가되었습니다(기본 제한 시간 1초, 최대 3초, 하위 에이전트에서는 실행되지 않음). /copy는 전체 응답, 개별 코드 블록, 인용문 중에서 선택하는 선택기를 엽니다. @ 멘션으로 작업을 지정할 수 있고, 에이전트는 작업을 읽고 생성하며 메시지를 보낼 수 있습니다. /rename은 편집 가능한 제목을 제안합니다. Markdown 링크는 클릭 가능한 레이블로 렌더링되고, 단축키로 권한 모드를 순환할 수 있으며, Vim에는 . 반복 기능이 추가됩니다. 또한 신뢰할 수 없는 프로젝트에서는 더 이상 프로젝트 수준 AGENTS.md 지침을 제공하지 않습니다. features.network_proxy.credential_broker와 Guardian v2의 review_scope.computer_use_only는 설정할 수 있으며 기본으로 비활성화된 기능으로 추가됩니다. v0.150.1에서는 유지된 이미지가 원격 압축의 토큰 예산에 포함됩니다.¹³²¹³³

v0.149.0 및 v0.149.1 (2026년 8월 20~24일)

untrusted 승인 정책이 폐기되었습니다. 이 정책을 지정하는 설정은 on-request로 이전하세요. 새로운 기능으로는 대화형 codex agents 대시보드, /cd, /pwd, /cwd, 기존 로컬 또는 원격 세션에 메시지를 보내는 codex queue, 더 다양한 Vim 변경 동작, 기능이 확장된 codex doctor(엔드포인트 보호, 네트워크 및 프록시 오류, 데스크톱 앱 상태, 업데이트 연결)가 있습니다. SDK에는 max/ultra 추론 노력 수준이 추가됩니다. 재개하거나 분기한 스레드는 권한 프로필을 복원합니다. v0.149.1에는 codex exec --thread-source <SOURCE>가 추가되었습니다(user, subagent, memory_consolidation 또는 기능 이름. TypeScript SDK에서는 threadSource).

같은 기간의 가격 변경: OpenAI는 8월 21일부터 3개월간(최소 2026년 11월 21일까지) GPT-5.6 Sol 가격을 20% 넘게 인하했으며, Sol의 Codex 크레딧 요율은 입력, 캐시된 입력, 출력 토큰 100만 개당 각각 125/12.5/750에서 100/10/500크레딧으로 낮아졌습니다.^120121126

v0.147.0 및 v0.148.0 (2026년 8월 7~18일)

v0.147.0에서는 codex exec --full-auto가 제거되었습니다(v0.128부터 사용 중단 예정). --sandbox workspace-write와 승인 플래그 또는 프로필을 함께 사용하세요. 또한 --approve-for-me, 카탈로그 전체를 검색할 수 있는 이식 가능한 Agent Plugins, 별도 활성화 방식의 MCP 2026-07-28 프로토콜, 대화 섹션이 추가되었습니다. v0.148.0에는 Markdown으로 내보내는 /export, codex exec fork, /status의 예상 크레딧 또는 비용, 내장 제공자로서의 Amazon Bedrock Runtime, 비동기 및 MCP 호출 hooks, 거부되거나 읽을 수 없는 경로에서 안전을 위해 차단되는 sandbox 제한이 추가되었습니다.¹¹⁶¹¹⁸

이전 릴리스 (2026년 5~7월)

• v0.146.0 및 v0.146.1(7월 29일, 8월 5일): 설정된 프록시가 모든 전송 방식을 처리합니다. Agent Plugins 매니페스트와 Amazon Bedrock 및 Claude Code 마켓플레이스, 스레드 고정 기능이 있는 세션 이름 지정, 실행기에서 제공하는 skills, 사이버 역량을 갖춘 모델을 위한 강화된 자동 검토 기본값이 추가되었습니다.¹¹⁴¹¹⁵
• v0.145.0(7월 21일): Claude Code뿐 아니라 Cursor에서도 /import할 수 있습니다. 음성 기능이 스트리밍 실시간 V3 대화로 돌아왔고, 별도 활성화 방식의 멀티 에이전트 v2 환경이 안정화되었습니다. 페이지가 나뉜 실험적 스레드 기록과 Amazon Bedrock 로그인이 추가되었으며, 포함된 GPT-5.4 선택 항목은 GPT-5.6 Terra와 Luna로 마이그레이션됩니다. v0.144.6에서는 GPT-5.6 컨텍스트 창을 272,000토큰으로 설정했습니다.¹¹¹¹¹²
• v0.140.0(6월 15일): /usage, codex delete와 /delete, Claude Code에서 가져오는 /import, 통합된 @ 멘션 메뉴, Amazon Bedrock API 키 인증, CLI 및 MCP OAuth 자격 증명을 위한 암호화된 로컬 저장소가 추가되었습니다. 기존 /realtime 음성 제어 기능은 제거되었습니다.¹⁰²
• v0.139.0(6월 9일): 코드 모드에서 웹 검색을 직접 호출할 수 있고, 도구 스키마에 oneOf/allOf가 유지되며, codex doctor가 편집기와 페이저 세부 정보를 보고하고, 마켓플레이스 출처가 JSON 출력에 표시됩니다.¹⁶⁵
• v0.138.0(6월 8일): /app은 CLI 세션을 데스크톱 앱으로 넘기며, 멀티 에이전트 v2에서는 상위 에이전트가 하위 에이전트에 보내는 작업 텍스트가 암호화됩니다.¹⁶⁶¹⁰⁸
• v0.137.0(6월 4일): 멀티 에이전트 v2, F13~F24 TUI 키 바인딩, v1 skills 확장이 추가되었습니다.¹⁶⁷
• v0.132.0~v0.135.0(5월 20~28일): 로컬 대화 기록 검색, 기본 프로필 선택기로서의 --profile, 기본 활성화되는 목표, 권한 프로필 상속과 관리형 requirements.toml, codex remote-control 시작 및 중지, 더 다양한 정보를 제공하는 codex doctor와 /status, Vim 텍스트 객체, /permissions의 이름 있는 권한 프로필, Python SDK 인증과 Sandbox 프리셋, codex exec resume --output-schema가 추가되었습니다. 5월 21일 앱 업데이트에는 Appshots, 정식 출시된 Goal 모드, 별도 활성화 방식의 잠긴 Computer Use가 추가되었습니다.^{96979899100101176}

레거시 --full-auto는 v0.147.0부터 제거되었으며 js_repl도 계속 제거된 상태입니다.^86878991116

안정성 참고: 안정적이고 문서화된 기능은 핵심 CLI와 TUI, sandbox 및 승인 정책, config.toml, AGENTS.md, skills, hooks, 플러그인, 멀티 에이전트 도구, 목표, 권한 프로필, /voice와 관리형 worktrees(v0.156.0부터 기본 활성화), 전체 화면 대화 기록과 백그라운드 서버 자동 시작(v0.157.0부터 기본 활성화)입니다. Browser, Computer Use, Appshots는 문서화된 사용자용 기능이며 사용 가능 여부는 플랫폼과 요금제에 따라 달라집니다. 실험적이거나 개발 중인 기능은 Codex Cloud, 코드 모드, 실험적 컨텍스트 관리, Memory v2, 로컬 에이전트 메시지 보드, 이 가이드에서 [EXPERIMENTAL]로 표시되거나 /experimental에 나열된 모든 기능입니다. 이러한 기능은 릴리스 간에 변경될 수 있습니다. 제거된 기능은 --full-auto(v0.147.0), untrusted 승인 정책(v0.149.0), codex mcp-server(v0.154.0), js_repl입니다.

알파 채널: 알파 빌드는 하루에도 여러 번 출시되고, 알파 계열의 릴리스 본문은 임시 문구이며, 이전 기반에서 별도로 분기된 빌드도 정기적으로 등장합니다(가장 최근에는 0.155.0-alpha.16.4, 0.157.0-alpha.11.1, 0.158.0-alpha.15.1, 0.158.0-alpha.2.1). npm alpha 태그가 이러한 빌드 중 하나를 가리킨 적이 최소 2번 있었기 때문에 @alpha를 설치하면 latest보다 오래된 빌드가 설치되었습니다. 0.158 계열은 0.158.0-alpha.2(9월 23일)부터 alpha.15(9월 25일)까지 진행되었지만 안정 버전은 출시되지 않았습니다. 9월 25일에는 alpha 태그가 0.159 계열로 이동했으며 현재 버전은 0.159.0-alpha.4입니다. 알파 버전을 추적한다면 npm view @openai/codex dist-tags를 확인하고 @alpha 대신 정확한 버전을 설치하세요.¹⁷²¹⁷⁵ 최근 알파 계열이 안정 버전으로 이어진 과정의 날짜별 기록은 ¹⁷³에서 확인할 수 있습니다.

Codex 작동 방식: 멘탈 모델

기능을 자세히 살펴보기 전에 Codex의 아키텍처가 사용 방식 전반에 어떤 영향을 미치는지 이해해야 합니다. 이 시스템은 공통 지능 레이어를 기반으로 5가지 인터페이스에서 작동합니다.

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (on-request → 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 모델 제품군을 기반으로 작동합니다. 2026년 9월 23일 기준 현세대 모델은 GPT-6입니다. 일상적인 작업과 복잡한 코딩에는 gpt-6-sol, 가장 어려운 전체 과정 작업에는 gpt-6-astra를 사용하며, 모델을 설정하지 않은 경우 번들로 제공되는 CLI의 기본 모델도 gpt-6-astra입니다. 집중적인 대규모 작업에는 gpt-6-luna를 사용합니다. 출시 전환 기간에는 GPT-5.6 모델(Sol, Terra, Luna)도 계속 사용할 수 있습니다. Codex에서 컨텍스트가 400K이고 API에서 1M인 gpt-5.5는 ChatGPT 로그인 방식의 Codex에서 2026년 10월 14일에 지원이 종료되며, gpt-5.4는 2026년 8월 31일에 Codex에서 지원이 종료되었습니다.^{83117146148149171} 이 레이어는 파일을 읽고, 패치를 작성하고, 셸 명령을 실행하며, 코드베이스를 추론합니다. 컨텍스트가 가득 차면 Codex는 여유 공간을 확보하기 위해 대화를 압축합니다. 이 레이어에서는 토큰이 소모됩니다.

보안 레이어: Codex가 실행하는 모든 명령은 운영체제 수준의 샌드박스를 통과합니다. macOS에서는 Apple의 Seatbelt 프레임워크가 커널 수준의 제한을 적용합니다. Linux에서는 Landlock + seccomp가 파일 시스템 및 시스템 호출 접근을 필터링합니다. 샌드박스는 컨테이너 내부가 아니라 커널 수준에서 작동합니다. 그런 다음 승인 정책에 따라 사용자에게 확인을 요청할 시점이 결정됩니다.

확장 레이어: MCP는 외부 서비스(GitHub, Figma, Sentry)를 연결합니다. skills에는 Codex가 필요할 때 불러오는 재사용 가능한 워크플로가 담겨 있습니다. Apps는 ChatGPT 커넥터에 연결됩니다. 웹 검색은 인터넷의 실시간 컨텍스트를 추가합니다.

인터페이스 레이어: 터미널 고급 사용자와 자동화를 위한 CLI, 여러 스레드로 프로젝트를 관리하기 위한 Desktop App, 편집-컴파일-테스트 반복 작업을 위한 IDE 확장 프로그램, 독립적으로 실행되는 비동기 작업을 위한 Cloud가 있습니다.

핵심 요점: 대부분의 사용자는 하나의 인터페이스만 사용합니다. 고급 사용자는 5가지를 모두 활용합니다. 장기 실행 작업에는 Cloud, 재현 가능한 저장소 작업에는 CLI, 긴밀한 코딩 반복 작업에는 IDE 확장 프로그램, 계획 및 조율에는 Desktop App, 로그인된 브라우저 워크플로에는 브라우저 확장 프로그램을 사용합니다.

목차

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 Runtime
14. Skills란 무엇입니까?
15. Plugins
16. Plan Mode 및 협업
17. 메모리 시스템
18. 세션 관리
19. 비대화형 모드(codex exec)
20. Codex Cloud 및 백그라운드 작업
21. Codex Desktop App
22. GitHub Action 및 CI/CD
23. Codex SDK
24. 성능 최적화
25. 문제는 어떻게 디버깅합니까? – codex doctor 포함
26. 엔터프라이즈 배포
27. 권장 사항 및 피해야 할 패턴
28. 워크플로 레시피
29. 마이그레이션 가이드
30. 빠른 참조 카드
31. 변경 내역
32. 참고 자료

Codex는 어떻게 설치합니까?

패키지 관리자

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

Codex CLI을 업데이트, 다운그레이드 또는 제거하려면 어떻게 합니까?

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

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

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

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

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

릴리스로 인해 문제가 발생했다면 버전을 고정하는 것이 좋습니다. Codex의 안정 버전은 빠르게 업데이트되므로 정확한 버전을 설치하는 것이 가장 빠른 롤백 방법입니다. 문제를 보고하고 버전을 고정한 뒤 계속 진행하세요. PATH에서 우선순위가 더 높은 다른 설치본이 이전 바이너리를 계속 실행할 수 있으므로 codex --version으로 롤백이 적용되었는지 확인하세요. codex doctor는 Environment에서 바로 이 문제를 표시합니다.

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

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

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

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

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

바이너리 다운로드

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

시스템 요구 사항

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

인증

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

다음 2가지 인증 방식을 사용할 수 있습니다.

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

전문가 팁: config.toml의 cli_auth_credentials_store로 자격 증명 저장 방식을 설정할 수 있습니다. 옵션은 file(기본값), keyring(운영체제 키체인), auto(사용 가능한 경우 키체인을 사용하고 그렇지 않으면 파일로 대체)입니다.

Amazon Bedrock 로그인(v0.145.0, 실험적): Amazon Bedrock을 통해 모델에 접근하는 팀은 기존의 관리형 API 키 인증(v0.140.0 이상) 및 AWS 자격 증명 체인과 함께 사용자 지정 엔드포인트와 인증을 지원하는 실험적 로그인 방식을 사용할 수 있습니다(Custom Model Providers 참조). 기본 Bedrock 모델은 GPT-5.6 Sol입니다.¹¹² v0.150.0에서는 Amazon Bedrock 모델의 대화 압축 및 다중 에이전트 호환성 문제가 수정되었습니다.¹³² v0.151.0에서는 자격이 있는 TUI 로그인 흐름에 기능 플래그로 제어되는 Amazon Bedrock 옵션이 추가되었습니다. 온보딩 과정에서 기존 AWS 프로필과 환경 자격 증명을 검색하고, 프로필, 액세스 키, 환경 변수 및 Bedrock API 키를 직접 설정하는 옵션을 제공하며, AWS 리전을 입력받고, 입력 중 비밀 정보를 가리고, 공급자가 변경되면 내장 서버를 다시 시작합니다.¹³⁵ v0.152.0에서는 자격 증명 갱신 진행 상황을 표시합니다. 모델 공급자가 만료된 자격 증명을 갱신하는 동안 TUI와 codex exec에 진행 상황이 표시되며 Amazon Bedrock 세션 재인증도 포함됩니다. 이를 위해 스레드, 턴, 공급자 및 사용자에게 표시할 메시지를 전달하는 안정적인 modelProvider/authRecoveryStarted 및 modelProvider/authRecoveryCompleted 앱 서버 알림을 사용합니다.¹³⁸

셸 자동 완성

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

빠른 시작: 첫 번째 세션

5분 안에 처음부터 실제 작업까지 시작할 수 있습니다.

1. 설치하고 인증합니다.

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

2. 프로젝트로 이동합니다.

cd ~/my-project                  # Any git repo works

3. Codex를 시작합니다.

codex

대화형 TUI가 표시됩니다. Codex는 프로젝트 구조를 자동으로 읽습니다.

4. 질문합니다.

> What does this project do? Summarize the architecture.

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

5. 변경을 요청합니다.

> Add input validation to the login endpoint

Codex는 편집 내용을 diff로 제안합니다. 검토한 뒤 y로 승인하거나 n으로 거부하세요.

6. slash command를 사용합니다.

> /plan Refactor the database layer to use connection pooling

Codex는 실행하지 않고 계획만 생성합니다. 계획을 검토한 뒤 실행을 시작하도록 승인하세요.

7. 작업 내용을 확인합니다.

> /diff

현재 세션에서 Codex가 적용한 모든 변경 사항을 확인합니다.

다음 단계: - 프로젝트 지침이 포함된 AGENTS.md를 설정합니다(AGENTS.md는 어떻게 작동합니까? 참조). - 작업 흐름에 맞는 프로필을 설정합니다(프로필 참조). - 비대화형 자동화에 codex exec를 사용해 봅니다(비대화형 모드 참조).

핵심 상호 작용 인터페이스

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

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

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

터미널 UI는 다음 기능을 제공하는 전체 화면 애플리케이션입니다.

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

주요 TUI 단축키:

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

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

작업 흐름 선택기 개편(v0.129.0): 새롭게 설계된 선택기에서 재개와 분기 기능에 더 쉽게 접근할 수 있으며, 새로운 원시 스크롤백 모드를 사용하면 명령이나 모델 출력을 그대로 복사해야 할 때 렌더링되지 않은 대화 기록을 스크롤할 수 있습니다. 긴 디버깅 세션을 분류하거나 출력을 다른 도구로 전달할 때 유용합니다.⁸⁹

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

2. Codex Desktop App (macOS + Windows)

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

데스크톱 앱에는 CLI에서 제공하지 않는 다음 기능이 추가됩니다.

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

GPT-Live 기반 ChatGPT 음성 기능(데스크톱 26.715, 2026년 7월 23일): 이제 음성으로 데스크톱 앱을 제어할 수 있습니다. 입력하지 않고 말로 작업을 진행하고 Chat, Work, Codex 전반의 작업을 조율할 수 있습니다. macOS에서 화면 컨텍스트를 켜면 가장 앞에 있는 창의 앱샷이 대화에 공유되므로 보고 있는 내용을 설명하는 대신 바로 질문할 수 있습니다. Plus, Pro, Business, Edu, Enterprise에서 사용할 수 있으며, 데스크톱 앱과 iOS의 Remote를 통해 제공됩니다. 이는 데스크톱 인터페이스의 음성 기능입니다. CLI에는 별도의 자체 음성 기능이 있습니다. TUI의 /voice 실시간 대화 기능은 v0.156.0부터 기본으로 활성화되며, 스페이스바 받아쓰기는 v0.105.0에서 실험적으로 추가되었습니다.¹¹³¹⁶⁹

공유 스레드 스냅샷(2026년 8월 20일): 모든 Codex 요금제에서 macOS 데스크톱 앱을 사용해 로컬 Codex 스레드의 읽기 전용 스냅샷을 공유할 수 있습니다. 원본 스레드가 변경되어도 스냅샷은 업데이트되지 않습니다. 개인 계정 링크는 링크를 보유한 누구나 열 수 있지만, 작업 공간 계정 링크는 해당 작업 공간의 구성원만 열 수 있습니다. Codex는 공유하기 전에 알려진 비밀 정보 패턴을 가리지만 민감한 콘텐츠가 남을 수 있으므로 OpenAI는 공유할 내용을 검토하라고 안내합니다. ChatGPT 데이터 제어의 공유 링크에서 링크를 확인하거나 취소할 수 있습니다.¹²⁸

앱과 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 [실험적]

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

• 요청 후 별도 관리 불필요: 로컬 컴퓨터와 독립적으로 실행되는 작업을 대기열에 추가합니다
• 병렬 실행: 여러 클라우드 작업을 동시에 실행합니다
• PR 생성: Codex가 완료된 작업에서 pull requests를 생성합니다
• 로컬 적용: codex apply <TASK_ID>로 클라우드 결과를 로컬 저장소에 가져옵니다

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

클라우드 작업은 chatgpt.com/codex에서도 이용할 수 있습니다.⁴

5. 브라우저 확장 프로그램 (Chrome, Edge, Brave, Opera, Vivaldi)

Codex는 Google Chrome, Microsoft Edge, Brave, Opera, Vivaldi용 브라우저 확장 프로그램도 제공하며, CLI, 데스크톱 앱, IDE 확장 프로그램, 클라우드와 함께 5번째 인터페이스를 구성합니다. 확장 프로그램은 2026년 5월 Chrome용으로 출시되었고, 2026년 8월 25일 변경 기록에서 나머지 4개 브라우저가 추가되었습니다. ChatGPT 데스크톱 앱의 설정 > 컴퓨터 사용에서 설정할 수 있습니다. 5개 브라우저 모두 탭 멘션과 브라우저 제어를 지원합니다. Opera는 보조 채팅을 지원하지 않으므로 데스크톱 앱에서 작업을 시작하세요. 이 확장 프로그램은 일반적인 브라우징을 장악하지 않고 곁에서 함께 작동하도록 설계되었습니다. Codex는 백그라운드에서 여러 탭을 병렬로 처리하며, 어떤 사이트에 접근할지는 사용자가 제어합니다.⁹⁰¹²⁷

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

브라우저 확장 프로그램 문서에서 설치하세요. 이 페이지의 이전 제목은 Codex for Chrome이었습니다.¹²⁷

설정 시스템 심층 분석

Codex는 설정에 TOML을 사용합니다. 설정이 충돌할 때 어떤 설정이 우선 적용되는지를 결정하므로 우선순위 체계를 이해해야 합니다.

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

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

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

설정 파일 위치

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

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

전체 설정 참고 자료

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6-sol"                    # Docs' example default; unset = bundled default (gpt-6-astra)
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-6-sol"             # 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"          # on-request|never (untrusted retired in v0.149.0)

[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)

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── 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 (global; per-tool MCP overrides in v0.152.0)
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             # Browser-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-command network proxy (experimental); boolean or table, see below
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

features.network_proxy는 boolean | table입니다. 불리언 형식은 프록시를 시작하거나 중지하기만 하며, 테이블 형식에는 정책이 포함됩니다. 프록시는 샌드박스 명령에 권한 프로필의 도메인 규칙을 적용합니다. 프록시가 꺼져 있으면 [permissions.<name>.network] 도메인 규칙이 적용되지 않으며 명령의 네트워크 접근은 직접 이루어집니다. 웹 검색, 앱, MCP 서버 또는 그 밖의 호스팅 도구는 필터링하지 않습니다.¹³⁰

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

관리자가 requirements.toml에서 관리하는 experimental_network 요구 사항은 features.network_proxy 없이도 프록시를 시작할 수 있습니다.¹³⁰

프로필

서로 다른 작업 모드를 위한 이름이 지정된 설정 프리셋입니다. Codex 0.134.0부터 각 프로필은 별도의 파일로 구성됩니다. ~/.codex/<name>.config.toml에는 최상위 키만 저장되며, --profile <name>은 해당 파일을 ~/.codex/config.toml 위에 덮어씁니다. 이전에 config.toml 내부에서 사용하던 [profiles.<name>] 테이블과 최상위 profile = "<name>" 선택자는 더 이상 읽지 않습니다. [profiles.<name>] 테이블이 남아 있으면 해당 키를 프로필 파일로 옮길 때까지 --profile <name> 실행이 거부됩니다.¹²²

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-6-sol"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

프로필 파일은 기본 사용자 설정보다 위에 있고 프로젝트 및 CLI 설정보다 아래에 있는 계층이므로, 기본 설정과 다른 값만 포함하면 됩니다.¹²²

프로필을 활성화합니다.

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

전문가 팁: 설정의 최상위에 profile = "fast"를 지정하여 기본 프로필을 설정하세요. 세션별로 변경하려면 --profile을 사용하세요.

사용자 지정 모델 공급자

Azure, AWS Bedrock, 로컬 모델 또는 프록시 서비스에 연결합니다.

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

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

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

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

경고: OpenAI는 2026년 2월에 OpenAI 호스팅 모델에서 chat/completions 통신 API(wire_api = "chat")을 제거한다고 발표했으며, 이에 따라 이 형식은 더 이상 권장되지 않습니다.³⁴ 로컬 공급자(Ollama, LM Studio)는 이 형식을 계속 지원할 수 있습니다. OpenAI 엔드포인트에는 대신 wire_api = "responses"를 사용하세요.

--oss 플래그로 로컬 모델을 사용합니다.

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

또는 설정 파일에 지정합니다.

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

인라인 설정 재정의

명령줄에서 원하는 설정값을 재정의합니다.

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

어떤 Model을 선택해야 합니까?

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

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

GPT-5.5는 ChatGPT 로그인 방식의 Codex에서 2026년 10월 14일에 지원이 종료됩니다. Model 문서에서는 지원 종료 범위를 모든 요금제의 ChatGPT, ChatGPT Work, Codex로 한정하며(일반 사용자, Business, Enterprise, Edu 포함), OpenAI API에는 적용되지 않는다고 명시합니다.¹⁵⁵ GPT-6 출시와 함께 대체 지침도 변경되었습니다. Plus, Pro, Business, Enterprise, Edu에서는 gpt-6-sol을 선택하고, Free와 Go에서는 데스크톱 앱에서 gpt-6-luna를 선택하세요. 두 Model 모두 “사용 가능한 경우”에 해당합니다. 작업 공간 기본값, 저장된 Model 설정, 관리형 설정, 사용자 지정 에이전트, 예약 작업, 스크립트에서 gpt-5.5를 교체하세요.¹⁷¹

GPT-5.4와 GPT-5.4 mini는 ChatGPT 로그인 방식의 Codex에서 2026년 8월 31일에 지원이 종료되었습니다.¹¹⁷ Model 문서는 이제 대체 Model로 gpt-6-sol과 gpt-6-luna를 안내합니다(Enterprise와 Edu에서는 관리자가 먼저 Luna를 활성화해야 함). API 키 사용에는 영향이 없습니다.⁶⁴¹⁷¹ 정확한 Model 목록은 계정과 출시 단계에 따라 다릅니다. 로컬 캐시를 확인하세요: ~/.codex/models_cache.json.

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

무료 등급 안내(2026년 5월 5일): GPT-5.5 Instant는 2026년 5월 5일에 ChatGPT 무료 등급에 출시되었습니다. 이에 따라 GPT-5.5 계열의 사용 대상이 유료 요금제 외 사용자까지 확대되었지만, Codex CLI를 사용하려면 계속해서 대상 Plus / Pro / Business / Enterprise / Edu / Go 구독 또는 API 키가 필요합니다.⁹²

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

Bedrock GPT-5.6(Sol, Terra, Luna)(v0.143.0, 2026년 7월 8일): Codex는 Amazon Bedrock에서 호스팅되는 3가지 GPT-5.6 Model 변형을 정식으로 지원하기 시작했으며, max Reasoning 노력 단계도 지원합니다. Bedrock 제공자를 통해 Model에 접근하는 팀은 다른 사용자 지정 제공자 Model과 같은 방식으로 이들을 선택할 수 있습니다(Custom Model Providers 참조). max 노력 단계는 가장 어려운 Reasoning과 에이전트형 작업을 대상으로 합니다.¹⁰⁶ v0.144.6(2026년 7월 18일)에서는 Sol, Terra, Luna의 번들 지침을 새로 고치고 Context Window를 272,000토큰으로 수정했습니다.¹¹¹ v0.145.0(2026년 7월 21일)에서는 사용자 지정 엔드포인트와 인증을 지원하는 실험적 Bedrock 로그인을 추가하고, GPT-5.6 Sol을 기본 Bedrock Model로 지정했으며, 번들 GPT-5.4 Model 선택을 각각 대응하는 Terra 및 Luna 변형으로 이전했습니다.¹¹²

GPT-6-Astra(2026년 9월 3일 출시, v0.153.1~v0.153.4를 통해 Codex에 도입): 날짜별 흐름은 다음과 같습니다. v0.153.1은 2026년 9월 3일에 API 전용 카탈로그 항목을 준비했고, OpenAI는 같은 날 GPT-6-Astra를 발표했으며, v0.153.4는 9월 4일에 선택기 항목을 추가하고 번들 CLI 기본값을 전환했습니다. 발표 내용에 따르면 단계적 출시는 제한된 조직부터 시작해(사이버 보안 프로그램 협력사가 우선) “며칠에 걸쳐” ChatGPT Plus, Pro, Business, Enterprise로 확대되며, OpenAI API 및 AWS에도 제공됩니다. 이 출시 관련 내용은 언론 보도(CNBC, Axios, Forbes, Al Jazeera, 9to5Mac)를 근거로 합니다.¹⁴⁵ 9월 4일에 대체된 내용: OpenAI는 X를 통해 GPT-6 Astra를 “이제 ChatGPT Work와 Codex의 모든 Pro, Enterprise, Business Premium 사용자가 사용할 수 있으며”, “API에서도 제공된다”고 발표했습니다. Plus와 Business는 며칠 내 제공될 예정이라고 밝혔고, Codex 책임자인 Tibo Sottiaux는 같은 날 저녁 “이제 Astra가 모든 Plus 및 Business 사용자에게도 출시되었습니다”라고 추가로 알렸습니다. 실제 사용 권한은 여전히 고르지 않습니다. 9월 5일 커뮤니티 보고에서는 Plus 계정의 Codex에 여전히 GPT-5.6 Model만 표시되었으며, 아래에 인용한 Model 문서의 사용 가능 여부 문구도 그대로이므로 이 내용이 계속 유효한 공식 설명입니다.¹⁴⁹ 공식 문서도 공개되었습니다. API Model 페이지는 gpt-6-astra를 “가장 어려운 엔드 투 엔드 작업을 위해 제작된 가장 유능한 Model”인 플래그십으로 설명합니다. 표준 짧은 Context 요금은 입력 MTok당 $10, 출력 MTok당 $50이며, Context Window는 1.05M토큰, 최대 입력은 922,000토큰, 최대 출력은 128K, 지식 기준일은 2026년 4월 30일입니다. 긴 Context 요금 단계도 문서화되어 있습니다. 입력 토큰이 272K를 넘는 프롬프트는 전체 요청에 입력 2배, 출력 1.5배의 요금이 적용되며, 가격 페이지 기준 입력 MTok당 $20, 출력 MTok당 $75입니다. 이는 GPT-5.6 Terra(균형형)와 Luna(저가형)보다 높은 수준입니다. Codex 문서에서는 Astra를 권장 Codex Model로 명시하면서 사용 가능 여부는 “출시 단계, 로그인 방식, 클라이언트에 따라 달라진다”고 설명하고, 대상 계정으로 Pro, Business($100), Enterprise를 안내합니다. Astra의 문서화된 Codex Reasoning 단계는 Low, Medium, High, Extra High, Max, Ultra입니다. Model 문서 페이지는 Medium을 기본값으로 표시하지만, v0.153.4 번들 카탈로그에서는 default_reasoning_level을 low로 설정하므로 실제 기본값은 사용 환경에 따라 다르게 취급하고 세션에서 /status로 확인하세요. 9월 15일에 다시 확인했을 때도 단계 구성은 같았으며, 이제 단계별 선택기 설명이 추가되었습니다(Ultra의 원문: “Maximum reasoning with automatic task delegation”). Max와 Ultra 단계에는 SDK 확인이 따릅니다. Python SDK 0.154.0 릴리스(2026년 9월 10일)는 max 및 ultra Reasoning 노력 값을 추가합니다(#39662).^146148153 CLI에서 Astra는 v0.153.1부터 API를 통해 설정할 수 있고(-m gpt-6-astra), v0.153.3에서 Amazon Bedrock 카탈로그에 추가되었으며(GPT-5.6 Sol은 v0.157.0에서 GPT-6 Sol로 변경되기 전까지 Bedrock 기본값으로 유지됨¹⁷⁴), v0.153.4부터 Model 선택기에 표시되고 Model을 명시적으로 설정하지 않았을 때 번들 기본값으로 사용됩니다. 최소 CLI 버전은 문서화되지 않았으므로 이를 실질적인 최소 버전으로 간주하세요. 이 기본값 전환은 모든 사용 환경이 아닌 번들 CLI 카탈로그에만 해당합니다. 다만 cloud의 격차는 이후 해소되었습니다. 9월 4일과 9월 7일 확인에서는 Astra가 Codex cloud에서 사용할 수 없는 것으로 표시되었고 GPT-5.6 Sol은 사용 가능했지만, 9월 15일 재확인에서는 사용 가능 여부 표에 Astra도 Codex cloud에서 사용할 수 있는 것으로 표시되었습니다. 이 페이지에는 여전히 “현재 Codex cloud 채팅의 기본 Model은 변경할 수 없습니다”라고 안내되어 있습니다. 출시 관련 주의 사항: 사용 권한은 계정마다 다르며, CLI 0.153.4 이상에서는 출시 대상이 아닌 계정에도 아직 제공할 수 없는 Model이 번들 기본값으로 설정될 수 있습니다. 확정적인 선택이 필요하면 config.toml에서 Model을 고정하거나 -m을 전달하세요. v0.156.1부터 문서 자체의 예시는 model = "gpt-6-sol"입니다. Model 페이지에는 Fast 등급이 없지만 Astra Fast 모드 요금은 문서화되어 있습니다. Codex 속도 문서에는 ChatGPT 로그인 사용 시(“사용 가능한 경우”) Standard 크레딧의 2.5배로 안내되어 있으며, API 가격 페이지의 Fast 모드 요금은 해당 Standard 요금의 정확히 2배입니다(짧은 Context에서 MTok당 $20/$100, 긴 Context에서 $40/$150). v0.153.2 카탈로그 문구의 “2x speed” 부분은 여전히 카탈로그 표시 문구일 뿐이며, 속도 페이지에서는 Astra의 속도 배수를 명시하지 않습니다.^145146147148 일부 대체됨, 2026년 9월 23일: Model 문서는 더 이상 Astra를 권장 Codex Model로 설명하지 않습니다. “Recommended models” 섹션은 이제 GPT-6 Sol과 Luna를 먼저 안내하고, Astra는 “가장 어려운 엔드 투 엔드 작업”에 사용하도록 구분하며, Astra를 Codex cloud에서 사용할 수 없다고 표시합니다. 또한 Astra의 시작 노력 단계를 번들 카탈로그와 일치하는 Light(low)로 안내합니다. Model을 설정하지 않으면 Astra가 계속 번들 CLI 기본값으로 사용됩니다.¹⁷¹

Astra의 Power 사전 설정(2026년 9월 6일 또는 그 이전에 문서에 추가됨): Codex Model 문서의 Model 선택기 설명은 이제 선택기의 Power 옵션을 GPT-6-Astra Reasoning 단계에 연결합니다. 이는 Power 사전 설정을 Astra에 연결한 최초의 문서 설명입니다. 이 단락은 ¹⁴⁶의 9월 5일 재확인 당시에는 없었으며, 9월 7일에 공개 상태가 확인되었습니다. 원문: “대상 Pro, Business($100), Enterprise 계정에서는 Astra 출시와 함께 Power 옵션이 Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium, Astra Extra High로 변경됩니다. 옵션은 요금제와 출시 단계에 따라 다를 수 있습니다.” 앞선 문장에서는 선택기 그림에 여전히 GPT-5.6 제어 항목이 표시된다고 설명합니다. 위 Model 표와 함께 해석하면 “Power”는 GPT-5.6 Sol의 Medium Reasoning을 뜻해 왔지만, 사용 권한이 있는 계정에서는 이제 같은 사전 설정 단계가 고정된 Reasoning 단계의 Terra, Sol, Astra에 걸쳐 구성되며, 옵션은 계속 요금제와 출시 단계에 따라 달라집니다. 이 단락은 2026년 9월 15일 재확인 당시에도 원문 그대로 유지되었습니다.¹⁴⁶ 2026년 9월 23일 업데이트: GPT-6 Sol과 Luna 출시 후 문서에서는 6가지 Power 사전 설정을 “Luna High, Sol Light(시작 사전 설정), Sol Medium, Astra Light, Astra Medium, Astra Extra High”로 나열합니다. 일부 유료 요금제에는 Astra Extra High가 없다고 안내하며, Sol은 Medium, Luna는 High, Astra는 Light(low)에서 시작할 것을 제안합니다.¹⁷¹

실험적 교차 Context 메모(Astra, 문서에 게시됨, 선택적 사용): Codex Model 문서 페이지에는 “Experimental context management”라는 섹션이 있으며 원문은 다음과 같습니다. “지원되는 Codex 클라이언트에서 ChatGPT Plus 또는 Pro로 로그인한 사용자는 실험적 Context 관리 기능을 선택적으로 사용할 수 있습니다. Astra는 여러 Context Window에 걸쳐 메모를 유지하고 같은 작업의 이전 메시지와 도구 결과를 검색할 수 있습니다. 이 실험은 기본적으로 꺼져 있으며, 출시 시점에는 Business, Enterprise 또는 API 키 로그인에서 사용할 수 없습니다.” 선택적 사용 방법의 원문은 다음과 같습니다. “사용하려면 config.toml에서 features.context_management.experimental_mode = true로 설정한 다음 새 작업을 시작하세요.” 이는 v0.153.0에서 제공된 features.context_management.experimental_mode 설정과 같습니다(Context Management 참조). v0.153.0 릴리스 안내에서는 대상 Plus, Pro, Pro Lite 세션을 언급했지만, 이제 문서 페이지에서는 이를 Astra라는 이름과 Plus 및 Pro 로그인에 직접 연결합니다. v0.154.0에서는 코드 측 조건이 더 엄격해졌습니다. 이제 세션 시작 시 활성 Model의 기능에 따라 실험 사용 가능 여부가 제한됩니다(#43147). 문서 섹션은 2026년 9월 15일 재확인 당시에도 원문 그대로 유지되었습니다. 이 기능은 실험적이며 기본적으로 꺼져 있습니다. 동작과 사용 가능 조건이 변경될 수 있습니다.^140146152 v0.157.0: 번들 Model 카탈로그는 더 이상 GPT-6-Astra를 비롯한 어떤 번들 Model도 실험적 Context를 지원하는 것으로 표시하지 않으며(#47397), CLI는 해당 기능을 지원한다고 표시된 Model에만 이 실험을 활성화합니다. 따라서 번들 카탈로그에서는 이 선택적 설정이 아무 효과가 없습니다. 로그인한 계정에 제공되는 카탈로그가 다른지는 문서화되지 않았습니다. Model 문서에는 2026년 9월 26일 현재도 이 선택적 사용 방법이 설명되어 있습니다.¹⁷⁴

Model 선택 순서도

Is this a quick fix, extraction, or other well-defined repeatable task?
├─ Yes → gpt-6-luna (most efficient; docs suggest starting at High)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Hardest end-to-end work across many steps and tools?
   │     │  ├─ Yes → gpt-6-astra (strongest; bundled default when no model is set)
   │     │  └─ No → gpt-6-sol (everyday and complex coding; start at Medium)
   └─ GPT-6 not yet available on your account? → gpt-5.6-sol

Reasoning 노력

응답하기 전에 Model이 얼마나 많이 “생각할지” 제어합니다.

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

persistent 세부 정보(v0.151.0): persistent 노력으로 실행되는 작업은 현재 시각 알림과 중단 가능한 clock.sleep 도구를 기본적으로 활성화합니다(features.current_time_reminder 명시 설정과 관리형 요구 사항은 유지됨). 또한 Model 메타데이터가 persistent_instructions를 통해 재정의하거나 비활성화할 수 있는 번들 능동성 및 후속 작업 지침을 제공합니다.¹³⁵

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

전문가 팁: 같은 프롬프트에서도 xhigh Reasoning은 medium보다 3~5배 많은 토큰을 사용할 수 있습니다. 추가 Reasoning이 실질적인 효과를 내는 매우 어려운 문제에만 사용하세요.

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

Model 전환

세션 도중 /model slash command로 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 워크스페이스에서 이용할 수 있습니다. 고정 좌석 요금 없이 토큰 사용량에 따라 청구됩니다.⁷⁹ 가격 페이지에는 이제 2026년 2월 Desktop App 출시 당시의 프로모션용 2x 배수 대신 모델별 구간으로 제한이 공개됩니다(위 표 참고).¹⁶¹⁶²

2026년 5월 사용량 제한 상향(2026년 5월 31일 종료): Plus 플랜의 Codex에는 25× 5시간 제한(기본 20× 상향 대비)이 적용되었으며, 같은 기간에 월 $100 등급의 사용량도 2배로 상향되었습니다.⁸⁹

TUI의 사용량 제한 UX(v0.152.0-v0.153.0): 이제 제한에 도달해도 더 진행할 방법이 없는 상태에 빠지지 않습니다. v0.152.0은 작성 영역 위에 조치 가능한 사용량 제한 배너를 표시합니다. 여기에서 사용량 확인, 크레딧 관리, 제한 초기화, 워크스페이스 소유자 알림, 플랜 관리를 수행할 수 있으며, 인증된 계정과 사용자에 맞는 항목만 표시됩니다. 제한 오류가 발생하면 사용량 정보가 새로 고쳐지고, 배너의 안내에 따라야 하는 경우 Codex는 관련 없는 스레드 설정을 변경하지 않고 사용 가능한 첫 번째 대체 모델로 전환합니다.¹³⁸ v0.153.0에는 Plus 및 Team 플랜을 위한 조기 경고가 추가되었습니다. 약 5시간 단위의 사용량 한도에서 절반 미만이 남으면 경고가 표시되며, 다른 플랜과 시간 단위에는 기존의 75%, 90%, 95% 임계값이 계속 적용됩니다.¹⁴⁰

크레딧 비용

Codex 작업은 플랜에 할당된 크레딧을 소모합니다.

이 요율은 Standard 속도 기준이며, 가격 페이지에 따르면 GPT-6 출시 후에도 GPT-5.6 Sol, Terra, Luna의 요율은 “변경되지 않습니다.” 실제로는 “GPT-5.6 사용 시 메시지당 평균 5-30크레딧”이 소모됩니다(8월 이용 안내 당시에는 5-40으로 표시되었습니다). Fast 모드는 “사용 가능한 경우” GPT-6 Astra, Sol, Luna의 Standard 크레딧 요율보다 2.5배 비쌉니다. 또한 번들 모델 목록에서는 service_tier를 설정하지 않는 한 TUI에서 GPT-6 Sol과 Luna의 기본 등급으로 Fast가 지정되므로, 크레딧이 예상보다 빨리 소진된다면 /fast status를 확인하세요. 이미지 생성은 비슷한 텍스트 전용 요청보다 포함된 한도를 3-5배 빠르게 소모합니다.¹⁶²¹⁷¹

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

API 요금 청구

API를 통해 Codex를 사용할 때 OpenAI는 선택한 모델의 표준 OpenAI API 요금에 따라 토큰별로 사용료를 청구하며, 적용 가능한 프롬프트 캐싱 할인도 반영합니다. 토큰 100만 개당 현재 API 요율은 GPT-6 Sol 입력 $2 / 출력 $10, GPT-6 Luna $0.10 / $0.50, GPT-6 Astra $10 / $50입니다. 세 모델 모두 입력 토큰이 272K를 초과하는 프롬프트는 전체 요청에 대해 입력 요금이 2배, 출력 요금이 1.5배로 적용되며, Fast 모드는 2배의 비용이 듭니다.¹⁴⁶¹⁷¹ ChatGPT 크레딧 배수는 API 키 로그인에 적용되지 않습니다. 현재 요율은 공식 API 가격 페이지에서 확인하세요.²⁰

비용 최적화 전략

1. 프로필을 사용하세요: 일상적인 작업을 위해 gpt-6-luna와 model_reasoning_effort = "low"를 사용하는 fast 프로필을 만드세요
2. 높은 추론 수준은 꼭 필요할 때만 사용하세요: xhigh는 토큰을 3-5배 더 소모하므로 매우 어려운 문제에만 사용하세요
3. --ephemeral을 사용하세요: CI/CD에서는 세션 저장을 생략하여 부가 비용을 줄이세요
4. 추론 요약을 최소화하세요: 설명이 필요하지 않다면 model_reasoning_summary = "none"으로 설정하세요
5. exec 모드로 일괄 처리하세요: codex exec를 사용하면 자동화 워크플로에서 TUI의 부가 비용을 피할 수 있습니다
6. 사용량을 모니터링하세요: TUI의 /status와 조직의 결제 대시보드를 확인하세요. v0.148.0부터 /status, 상태 표시줄, 터미널 제목에는 해당 워크스페이스의 예상 스레드 크레딧 또는 비용이 표시됩니다¹¹⁸

실제 비용 예시

일반적인 작업의 대표적인 API 비용입니다(2026년 중반 gpt-5.3-codex 가격 기준, 중간 추론 수준. 모델이 달라도 상대적인 비용 규모는 비슷합니다).

비용은 추론 수준, 캐싱, 대화 길이에 따라 달라집니다. 일상적인 작업에는 gpt-5.6-luna를 사용하여 비용을 크게 절감하세요. 캐시된 입력 토큰에는 할인된 요금이 적용됩니다.

숨겨진 토큰 부가 비용

도구를 호출할 때마다 화면에 표시되는 프롬프트 외에 추가 토큰이 소모됩니다.

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

팀 비용 관리

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

결정 프레임워크

상황별 인터페이스 선택

상황별 Sandbox 모드 선택

작업별 추론 수준 선택

Plan 모드와 직접 실행 비교

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

Steer 모드: Enter와 Tab

경험칙: Enter = “멈추고 지금 이 내용을 확인하세요.” Tab = “현재 작업이 끝나면 이 작업도 처리하세요.”

Desktop App과 CLI 비교

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

어떤 프로필을 선택해야 합니까?

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

프로필 파일(각 프리셋마다 하나씩 ~/.codex/에 저장되며, 기존의 단일 파일 profile = "default" + [profiles.*] 구성은 0.134.0부터 읽지 않음¹²²):

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

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

Sandbox와 승인 시스템은 어떻게 작동합니까?

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

v0.148.0 보안 강화: 이제 Linux와 Windows 모두에서 sandbox 제한이 차단 우선 방식으로 작동합니다. 거부되었거나 읽을 수 없는 경로는 암묵적으로 허용되지 않고 차단된 것으로 처리됩니다.¹¹⁸

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

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

플랫폼별 적용 방식:

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

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

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

ReadOnlyAccess 정책(v0.100.0 이상): 세부적인 읽기 접근 제어를 위한 설정 가능한 정책 구조입니다. workspace-write 모드에서도 Codex가 읽을 수 있는 디렉터리를 제한하는 데 사용합니다.

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

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

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

on-failure는 일부 이전 예시와 호환 경로에 여전히 나타나지만, 현재 OpenAI 설정 문서에서는 더 이상 사용하지 않는 것으로 표시합니다. 대화형 실행에는 on-request를, 이미 외부 안전 경계가 마련된 비대화형 실행에는 never를 권장합니다.⁸⁷

v0.150.0부터 작성 창에서 권한 모드를 순환하는 키보드 단축키를 지정할 수 있습니다. /keymap에서 설정하세요.¹³²

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

이제 Codex는 여러 단계로 구성된 셸 실행에서 각 명령에 개별 승인 ID를 할당합니다. 따라서 승인을 세밀하게 제어할 수 있습니다. 한 명령을 승인해도 같은 셸 호출에 포함된 후속 명령이 자동으로 승인되지는 않습니다.⁴⁹

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

이제 승인 흐름에서 추가 sandbox 권한과 세부적인 거부를 지원합니다.⁶¹

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

실행 중 권한 요청(v0.113.0 이상)

이제 Codex에는 모델이 실행 중에 추가 권한을 요청할 수 있는 기본 제공 request_permissions 도구가 포함됩니다.⁶⁹ 모델이 더 높은 접근 권한이 필요한 작업을 만나면 조용히 실패하거나 사용자가 다른 플래그로 다시 시작하게 하는 대신, TUI 승인 흐름을 통해 특정 권한(파일 시스템 경로, 네트워크 접근 등)을 정식으로 요청할 수 있습니다.

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

앱과 커넥터에 중간 단계의 승인 수준이 추가되었습니다. writes 앱 승인 모드를 사용하면 앱에서 읽기 전용으로 선언한 작업은 확인 없이 실행하고, 쓰기 작업은 계속 일시 중지하여 승인을 요청합니다.¹⁰⁷ 이전에는 앱 승인이 사실상 전부 허용하거나 전부 차단하는 방식에 가까웠습니다. writes는 대부분의 운영자가 통합 기능에 실제로 원하는 신뢰 구조와 일치합니다. 조회는 자유롭게 허용하고 변경은 먼저 확인합니다.

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

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

권한이 상승된 터미널 입력 승인(v0.151.0)

기본적으로 비활성화된 write_stdin_approval 기능 플래그를 사용하면 권한이 상승된 통합 실행 터미널에 비어 있지 않은 입력을 보내기 전에 새로 승인을 받아야 합니다. 이러한 검토는 hooks, Guardian, 앱 서버, TUI를 통해 writeStdin 승인으로 전달됩니다. 터미널 환경, 실행 디렉터리, 권한 상승 상태는 실행 차례가 바뀌어도 유지되며, 승인 후 바이트를 쓰기 전에 프로세스 식별 정보를 다시 검증합니다. 완전히 서식이 적용된 작업과 승인 사유는 8,000바이트 이내여야 합니다. 이 크기를 초과하거나 잘린 작업은 승인을 요청하거나 터미널에 내용을 전달하기 전에 거부됩니다.¹³⁵

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

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

default_permissions = "project-safe"

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

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

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

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

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

v0.151.0: 복원된 앱 서버 스레드는 권한 프로필을 이전 방식의 실행 차례별 sandbox 재정의로 단순화하지 않고 그대로 유지합니다. 프로필은 실행 차례 라우팅과 호환되는 /cd 디렉터리 변경 후에도 유지됩니다. 복원된 프로필을 이전 sandbox 모드로 안전하게 표현할 수 없는 /cd 요청은 제한을 조용히 약화하지 않고 거부합니다.¹³⁴

이전 --full-auto 사용 지침

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

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

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

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

Sandbox 안정성(v0.129.0): Linux sandbox 시작 과정의 보안 강화로 느린 파일 시스템이나 심볼릭 링크가 있는 체크아웃에서 발생하는 경합이 줄어듭니다. Windows sandbox 안정성 개선으로 장시간 실행 중 발생하는 여러 예외 상황의 충돌을 해결했습니다. 내장 Bubblewrap 버전도 상위 프로젝트의 보안 패치가 포함된 0.11.2로 올라갔습니다. 설정을 변경할 필요는 없습니다. 이러한 개선 사항을 적용하려면 codex update를 실행하세요.⁸⁹

권장 설정

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

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

고급 사용자(전체 접근, 사용자가 검토 과정에 참여):

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

커뮤니티 게시물에서는 이 조합을 “최적의 균형점”으로 추천하지만⁸, 조언을 그대로 따르기 전에 실제 동작을 이해해야 합니다. 명령이 sandbox를 벗어나거나 네트워크에 접근해야 할 때 승인 요청이 발생하지만, danger-full-access는 두 경계를 모두 제거하므로 on-request가 권한 상승을 요청할 상황이 거의 남지 않습니다. 이는 모든 명령을 사용자가 확인하는 최대 권한 설정이 아니라, 확인을 최소화한 최대 권한 설정입니다. 전자를 원한다면 workspace-write를 유지하고 sandbox 경계에서 승인 요청이 발생하도록 하세요.¹²³

CI/CD 자동화:

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

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

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

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

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

일괄적인 approval_policy = "never" 대신 추론을 포함한 자동 검토가 필요한 CI/CD 작업 흐름에서 특히 유용합니다.

Guardian v2 기본값 변경(v0.151.0): 이제 Guardian v2는 이미지를 포함한 컴퓨터 사용 검토를 기본값으로 사용합니다. features.guardianv2.review_scope.computer_use_only의 기본값은 true입니다. 더 넓은 도구 검토 범위를 유지하려면 false로 설정하세요. features.guardianv2.transcript.include_images의 기본값도 true입니다. Guardian 기록에서 이미지를 제외하려면 false로 설정하세요. 두 기능 모두 v0.150.0에서 설정 가능하고 기본적으로 비활성화된 구성 요소로 도입되었으며, v0.151.0부터 기본적으로 활성화되었습니다.¹³⁵

Guardian 범위는 승인 모드를 따릅니다(v0.153.0): 이제 2가지 모드에서는 결과를 바꿀 수 없는 Guardian 작업을 건너뜁니다. Full Access(approvalPolicy: "never"와 제한 없는 권한을 이미 결합한 모드)에서는 확인 전용 Guardian 및 MCP 요청을 동기식 검토, 샘플러 사전 준비 또는 백그라운드 점수 계산 없이 승인합니다. 대기 중이거나 실패했거나 제한된 환경은 Full Access로 취급하지 않으며, 활성 권한 상태를 실행 차례마다 다시 평가하므로 기존 스레드도 안전하게 Full Access로 전환하거나 해제할 수 있습니다. 사용자 승인 모드(approvals_reviewer = "user")에서는 Guardian 사전 준비와 비동기식 점수 계산을 건너뛰고 일반적인 node_repl.js 실행 확인을 자동으로 승인하지만, 민감한 작업 검사와 사용자 입력 요청은 기존 동작을 유지합니다.¹⁴⁰ 이는 Guardian이 실행되는 시점을 줄이는 것이지 사용자 승인 계층을 축소하는 것이 아닙니다. 이 가이드에서 on-request와 함께 사용하는 danger-full-access에 관해 설명한 확인 동작은 별도의 메커니즘인 승인 정책에 해당합니다. 또한 v0.152.1부터 Guardian 승인 검토는 모델 메타데이터(auto_review.node_repl_policy)에서 Node REPL 정책을 가져올 수 있으며, 이 필드가 없으면 내장 정책을 사용합니다.¹³⁹

Guardian 컴퓨터 사용 점수 계산에서 모델 요구 사항 준수(v0.153.1): 이제 컴퓨터 사용 전용 Guardian 점수 계산과 빠른 승인 결정은 활성 모델의 메타데이터에 node_repl_auto_review_required가 설정된 경우에만 실행됩니다. 모델 전환으로 점수 계산을 건너뛰면 이전 점수나 계산 중인 점수가 무효화되므로, 검토 대상 모델로 다시 전환해도 오래된 승인 결정이 되살아나지 않습니다. 이는 v0.153.1 패치의 핵심이지만 릴리스 본문에는 기재되지 않았습니다. #42422(38ba8cdc를 선별 적용한 변경 사항)는 rust-v0.153.0…rust-v0.153.1 비교를 통해서만 확인할 수 있습니다.¹⁴²

Guardian 상위 압축 재사용이 기본적으로 활성화됩니다(v0.156.0): #46522는 guardian_reuse_parent_compaction을 안정화된 기능으로 승격하고 기본적으로 활성화합니다. 이를 통해 Guardian이 검토 세션을 다시 시작할 때 상위 스레드의 암호화된 압축을 재사용할 수 있습니다. PR 테스트에 따르면 상위 기록이 변경되면 캐시된 검토 세션은 여전히 무효화됩니다. 이전 동작으로 되돌리려면: config.toml의 [features] 아래에서 guardian_reuse_parent_compaction = false로 설정하거나 codex features disable guardian_reuse_parent_compaction을 실행하세요.¹⁶⁹¹⁷¹

Guardian 스레드 컨텍스트가 기본적으로 활성화됩니다(v0.157.0): #47275는 guardianv2.thread_context를 안정화된 기능으로 승격하고 동기식 및 비동기식 Guardian 검토에서 활성화하므로, 검토가 스레드 소유 컨텍스트를 사용합니다. 이 설정은 Guardian v2의 enabled 토글과 독립적이며, 명시적 설정과 프로필 재정의는 그대로 유지됩니다. 비활성화하려면: config.toml의 [features.guardianv2] 아래에서 thread_context = false로 설정하세요.¹⁷⁴

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

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

네트워크 접근 활성화

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

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

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

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

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

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

이 변수는 기존 HTTPS_PROXY와 SOCKS5 프록시 지원(v0.93.0 이상)을 보완합니다.

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

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

Sandbox 테스트

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

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

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

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

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

탐색 계층 구조

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

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

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

신뢰하지 않는 프로젝트에서는 프로젝트 AGENTS.md를 건너뜀 (v0.150.0): 위의 순회 과정은 프로젝트를 신뢰한다는 전제에서 작동해요. v0.150.0부터는 “신뢰하지 않는 프로젝트는 더 이상 프로젝트 수준의 AGENTS.md 지침을 제공하지 않으며, 권한이 변경된 뒤에도 관리형 읽기 거부 규칙이 계속 적용됩니다.” 따라서 사용자의 ~/.codex/AGENTS.md 지침은 유지하면서 프로젝트 범위 탐색을 건너뛰므로, 신뢰하기 전에는 신뢰하지 않는 체크아웃이 작업 규칙을 주입할 수 없어요.¹³²

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

이 설정 하나로 Codex의 5가지 핵심 시스템 가운데 3가지가 동시에 결정돼요. 지침, skills, 설정이 모두 기본 폴더를 따라요. 실제로 보조 폴더의 AGENTS.md는 Codex가 열 수 있는 파일일 뿐, 자동으로 불러오는 작업 규칙은 아니에요. 규칙이 담긴 저장소를 두 번째로 연결했다면 기본 폴더로 승격하거나, 기본 폴더의 AGENTS.md에 해당 규칙을 다시 작성하세요. 자동으로 감지되길 기대했던 저장소의 skill 폴더에도 같은 원칙이 적용돼요. CLI의 디렉터리 순회 방식 자체는 바뀌지 않았어요. 이는 데스크톱 앱의 프로젝트 범위 지정 방식이에요.

훌륭한 AGENTS.md의 조건

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

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

피해야 할 사항: - 실행 규칙 없이 전체 스타일 가이드를 그대로 넣지 마세요. - 모호한 지시문을 사용하지 마세요. (“주의하세요”, “최적화하세요”) - 서로 모순되는 우선순위를 섞지 마세요. (속도와 철저한 검증을 모두 요구하면서 실행 시간은 허용하지 않는 경우) - 설명형 문서를 작성하지 마세요. (AGENTS.md는 운영 정책이지 README가 아니에요.)

예시: 프로덕션용 AGENTS.md

# Repository Guidelines

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

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

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

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

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

Codex가 볼 수 있는 기록도 소스 코드와 마찬가지로 보안 대상이라고 생각하세요. Codex 릴리스 노트에는 셸 스냅샷 생성과 환경 변수 가림 처리에 관한 개선 사항이 기록되어 있고, 메모리 시스템은 메모리에 기록되는 내용을 검사해 비밀 정보를 찾아요. 하지만 이러한 보호 기능이 명령어 출력, 세션 기록, 셸 스냅샷, 로컬 로그 또는 보조 스크립트를 자격 증명을 출력해도 안전한 장소로 만들어 주지는 않아요.³⁷⁵⁵⁹⁵

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

덮어쓰기 방식

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

• 출시 동결: “새 기능은 추가하지 않고 수정만 허용”
• 사고 대응 모드: “모든 변경 사항은 당직 담당자의 검토를 받아야 함”
• 일시적 보안 강화: “이번 스프린트에서는 의존성 업데이트 금지”

설정

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

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

스캐폴드 생성

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

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

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

Hooks

Codex는 기존 AfterAgent와 AfterToolUse라는 이름으로 v0.99.0과 v0.100.0에서 hooks를 도입했고, v0.114.0에서는 SessionStart와 Stop을 지원하는 실험적인 hooks 엔진을 추가했으며,⁷⁰ v0.124.0(2026년 4월 23일)에서 hooks를 안정화했어요.⁸⁵ rust-v0.150.0에 포함된 엔진은 12개의 이벤트(codex-rs/hooks/src/lib.rs의 HOOK_EVENT_NAMES)를 등록해요. v0.149.1까지는 11개였고, v0.150.0에서 Interrupt가 12번째로 추가됐어요.¹³² 이제 설정 화면에서는 기존 이름을 찾아볼 수 없어요. AfterToolUse는 소스 트리 어디에도 더 이상 나타나지 않으며, AfterAgent는 기존 notify 브리지의 내부 페이로드 이름으로만 남아 있어요.¹²⁴ Hooks는 에이전트 루프가 진행되는 동안 스크립트나 MCP 도구를 실행해요. 여러 파일에서 일치하는 hooks는 모두 실행되고, 하나의 이벤트와 일치하는 여러 명령 hooks는 동시에 시작돼요. 관리되지 않는 모든 hook은 실행 전에 검토하고 신뢰해야 해요.¹²⁴ v0.148.0에서는 엔진의 기능이 확장되어 hooks가 명령을 비동기식으로 실행하고 MCP 도구를 호출할 수 있어요. 명령 핸들러에 async = true를 설정하면 Codex가 계속 작업하는 동안 해당 명령을 백그라운드에서 실행할 수 있고, mcp_tool 핸들러를 사용하면 에이전트가 이용하는 것과 동일한 MCP 서버에 접근할 수 있어요.¹¹⁸¹²⁴

사용할 수 있는 Hook 이벤트

WebSearch와 같은 호스팅 도구는 hook 경로를 통과하지 않으며 일부 특수 도구 경로는 이 경로를 사용하지 않도록 선택할 수 있어요. OpenAI도 이를 “유용한 가드레일이지만 완전한 시행 경계는 아니다”라고 설명해요.¹²⁴

Hook 설정

Hooks는 이벤트, matcher 그룹, 하나 이상의 핸들러라는 3단계로 구성되며 hooks.json(~/.codex/hooks.json, <repo>/.codex/hooks.json 또는 플러그인의 hooks/hooks.json)이나 config.toml 및 requirements.toml 내부에 있어요. 프로젝트 로컬 hooks는 프로젝트의 .codex/ 계층을 신뢰할 때만 로드돼요.¹²⁴ 인라인 TOML 형식은 다음과 같아요.

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

핸들러 필드는 type(command 또는 mcp_tool, prompt와 agent 핸들러는 파싱되지만 건너뜀), command, 초 단위의 timeout(기본값은 600초, SessionEnd는 1초이며 최대 3초), statusMessage, additionalContextLimit(Codex가 전체 텍스트를 디스크에 저장하고 미리 보기를 보내기 전에 모델에 전달되는 additionalContext의 양), commandWindows(Windows 전용 재정의), async예요. 명령은 세션의 cwd를 작업 디렉터리로 사용하므로 저장소 로컬 hooks는 상대 경로인 .codex/hooks/... 대신 git rev-parse --show-toplevel을 기준으로 경로를 확인해야 해요.¹²⁴

검토 및 신뢰. Codex는 관리되지 않는 각 hook의 현재 해시를 기준으로 신뢰 상태를 기록해요. 새로 추가되거나 변경된 hooks는 검토 대상으로 표시되며 신뢰하기 전까지 건너뛰어요. /hooks를 실행하면 hook 소스를 확인하고, 검토하거나 신뢰하거나 개별 hooks를 비활성화할 수 있어요. 시작할 때 검토가 필요한 hooks가 있으면 Codex는 /hooks를 안내하는 경고를 표시해요. 시스템, MDM, 클라우드 또는 requirements.toml 소스에서 제공하는 관리형 hooks는 정책에 따라 신뢰되며 사용자 hook 브라우저에서 비활성화할 수 없어요. --dangerously-bypass-hook-trust를 사용하면 다른 곳에서 hook 소스를 검증하는 자동화를 위해 저장된 신뢰 상태 없이도 활성화된 hooks를 한 번 실행할 수 있어요.¹²⁴

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

Claude Code Hook 패턴 재현하기

Codex는 구현된 이벤트에 Claude Code과 동일한 이벤트 이름을 사용하므로, 대부분의 hook 설정은 JSON을 hooks.json으로 옮긴 다음 /hooks에서 신뢰하도록 설정하면 이전할 수 있어요.

전문가 팁: 새로운 hook 이벤트는 릴리스에서 계속 추가되고 있어요. v0.150.0에서는 Interrupt 이벤트가 추가됐어요(¹³²). 현재 목록은 codex-rs/hooks/src/lib.rs의 HOOK_EVENT_NAMES와 Codex 변경 로그에서 확인하세요.

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

MCP(Model Context Protocol)란? [EXPERIMENTAL]

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

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

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

v0.147.0 MCP 변경 사항(2026년 8월 7일): Codex는 MCP 2026-07-28 프로토콜 개정판에 대한 옵트인 지원을 추가합니다. 페이지네이션된 탐색(대규모 도구 카탈로그가 지나치게 큰 하나의 목록 대신 페이지 단위로 스트리밍됨), 다중 라운드 요청(서버가 하나의 논리적 요청 안에서 여러 단계의 교환을 유지할 수 있음), 그리고 논블로킹 서버 시작이 포함되며, 캐시된 MCP 도구가 서버 시작 완료 전에 노출되므로 느린 서버가 더 이상 세션 시작을 지연시키지 않습니다. 옵트인 방식이므로 이전 개정판을 사용하는 서버는 변경 없이 그대로 동작합니다.¹¹⁶

v0.151.0 MCP 변경 사항(2026년 8월 29일): 선택적 MCP 서버에 설정 가능한 시작 유예 기간이 추가되었습니다. mcp_optional_startup_grace_ms(기본값 1,000ms)는 도구 카탈로그 수집이 선택적 서버를 얼마나 기다릴지 제어하며, 0으로 설정하면 공유 유예가 비활성화되어 선택적 서버가 각자 설정된 startup_timeout_sec로 되돌아갑니다. 변경된 값은 런타임 중과 MCP 설정 갱신 시에 적용됩니다. 확장 기능은 또한 MCP 도구 결과가 모델에 도달하기 전에 이를 검사하거나 교체할 수 있습니다. ToolLifecycleContributor::on_mcp_tool_result는 MCP 완료가 게시되기 전, 그리고 결과가 모델용으로 준비되기 전에 실행되며, Code Mode를 통한 경우를 포함해 성공 결과와 오류 결과 모두에 적용됩니다.¹³⁴

v0.152.0 MCP 변경 사항(2026년 9월 1일): 세 가지 추가 변경이 있습니다. openai/elicitation 폼 요청이 도입되었습니다. 클라이언트가 객체 값을 갖는 form 기능을 선언하면 Codex가 폼 지원을 알리고, openai/elicitation/create 요청을 처리하며, 해당 메타데이터와 불투명 스키마를 앱 서버를 통해 openaiForm으로 전달합니다(x-openai-* 주석 유지). 기존 openai/form 처리는 독립적으로 유지되며, TUI는 렌더링할 수 없는 폼 요청을 자동으로 거절합니다. 도구별 출력 제한: MCP 서버의 tools 설정 아래 각 항목은 양수 output_token_limit를 받습니다(예: [mcp_servers.context7.tools.search]에 output_token_limit = 2000). 플러그인 정책과 사용자 정책이 겹칠 때는 가장 엄격한 제한이 적용되며, 유효 예산이 대화 기록에 함께 저장되므로 도구 출력, post-tool hook 응답, 재개된 세션이 모두 동일한 제한에서 잘립니다. 이는 전역 tool_output_token_limit와 별개로 추가되는 기능입니다. 패키지 형태의 서버 이름: 이제 MCP 서버 이름에 :, @, /, .를 포함할 수 있으며(따라서 npm:@modelcontextprotocol/server-sequential.thinking도 유효한 이름입니다), mcp add/get/list/remove, 런타임 도구 네임스페이스, OAuth 자격 증명 조회 전반에서 유지되고, 단순하지 않은 이름은 생성된 config.toml 복구 힌트에서 따옴표로 감싸집니다.¹³⁸

MCP 서버 설정

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

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

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

HTTP 서버(원격):

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

CLI 관리

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

세션 내에서: /mcp는 활성 서버와 사용 가능한 도구를 보여 줍니다. /mcp verbose(v0.123.0+)⁸⁴는 전체 서버 진단 정보, 리소스, 리소스 템플릿을 반환합니다. 서버가 로드되지 않거나 도구가 예상한 곳에 나타나지 않을 때 유용합니다. 일반 /mcp는 계속 빠르게 동작합니다. v0.144.0부터 MCP 도구는 실험적 옵트인 없이 대화형으로 인증을 요청할 수 있습니다. 세션 도중 인증이 필요한 서버는 codex mcp login으로 미리 인증할 때까지 실패하는 대신 일반적인 흐름을 통해 프롬프트를 띄웁니다.¹⁰⁷

플러그인 MCP 로딩(v0.123.0+)은 표준 mcpServers 스키마와 .mcp.json의 최상위 서버 맵을 모두 허용하므로, 두 관례 중 어느 쪽으로 작성된 플러그인이든 문제없이 로드됩니다.⁸⁴

MCP 사용자 확인(v0.155.0, 지원되는 Mac): 지원되는 Mac의 로컬 TUI 세션은 Touch ID로 MCP 요청을 확인하고 Secure Enclave가 서명할 수 있습니다(#43624, #43712, #43715). 확인 ID는 등록된 워크스페이스로 제한되며(#43524), 확인 결과는 MCP 도구 연속 호출로도 기본 지원되어 이어집니다(#44346). v2.68 승격 체크리스트에서 처음 관찰되었고, alpha.7 클러스터와 함께 0.154.0에서 빠졌다가 0.155.0에서 출시되었습니다.¹⁵⁶

Codex를 MCP 서버로 실행하기

제거됨(v0.154.0, 2026년 9월 9일). codex mcp-server 명령과 독립 실행형 codex-mcp-server 바이너리는 stable 0.154.0부터 사라졌으며(#42993), 2026년 8월 24일에 시작된 지원 중단 절차가 완료되었습니다. 공식 changelog(2026년 9월 5일): “The codex mcp-server command and standalone codex-mcp-server binary have been removed after their deprecation on August 24, 2026. Update integrations that launch either command before upgrading Codex.” 통합 코드는 VS Code 확장과 데스크톱 앱 뒤에 있는 인터페이스인 app-server 프로토콜(인증, 대화 기록, 승인, 스트리밍되는 에이전트 이벤트)을 대상으로 해야 합니다. 다만 제거 항목 자체가 이 프로토콜을 실험적이며 “isn’t supported for production workloads”라고 명시합니다. 또는 Claude Code에서는 Claude Code용 Codex 플러그인을 사용할 수 있습니다: “Use Codex from Claude Code to review code or delegate tasks.” Codex를 외부 MCP 서버에 연결하는 기능(codex mcp ..., /mcp)은 영향을 받지 않습니다.^125152153

CLI 0.153.4 이하에서는 이 명령이 여전히 존재합니다(2026년 8월 24일부터 지원 중단; v0.149.0부터 stderr에 warning: `codex mcp-server` is deprecated and will be removed in a future release.를 출력한 뒤 어쨌든 시작합니다, PR #39657). 따라서 통합을 즉시 이전할 수 없다면 npm install -g @openai/codex@0.153.4로 고정하는 것이 임시 방편입니다:^12125148152

codex mcp-server                        # REMOVED in 0.154.0; works only on 0.153.x and earlier (deprecated, warns)

0.153.x 이하에서 이 서버는 두 가지 도구를 노출합니다: 1. codex(): 프롬프트, 샌드박스, 모델, 승인 매개변수로 새 세션을 시작합니다 2. codex-reply(): threadId와 프롬프트로 기존 세션을 이어갑니다

Agents SDK(Python)와 함께 사용 – CLI 0.153.4 이하에서만 가능:

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

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "@openai/codex@0.153.4", "mcp-server"]},  # pin: removed in 0.154.0
    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 도구 호출에서도 독립형 웹 검색을 직접 호출할 수 있으며, 결과를 일반 텍스트로 받아요. 따라서 Code mode 흐름은 샌드박스가 적용된 코딩 컨텍스트를 벗어나지 않고도 실시간 정보를 가져올 수 있어요.¹⁶⁵ v0.146.0에서는 독립형 웹 검색이 호환되는 사용자 지정 모델 제공업체까지 확장되어, 이 기능이 더 이상 OpenAI 호스팅 모델로 제한되지 않아요.¹¹⁴

v0.146.0에서는 app-server가 원격 Code Mode 호스트에 연결할 수 있게 되어, Code mode 런타임을 클라이언트와 같은 컴퓨터에서 실행할 필요가 없어졌어요. 처음에는 WebSocket을 통해 연결했어요.¹¹⁴ v0.151.0에서는 WebSocket 전송 방식을 제거했어요(#40692). app server의 --code-mode-host 연결은 http:// 및 https:// gRPC 엔드포인트만 허용하며, 독립형 Code mode 호스트는 stdio 및 gRPC 리스너로 제한돼요. rust-v0.151.0 태그의 리스너 문서에는 “Transport endpoint: stdio, stdio://, or grpc://IP:PORT.”라고 그대로 적혀 있어요. WebSocket은 세션 전송 방식이 아니라 추적을 위해 원시 OTLP 추적 배치를 스트리밍하는 선택적 엔드포인트로만 남아 있어요.¹³⁵

이 기능은 실험 단계예요. 업데이트는 릴리스 노트를 확인하세요.

JavaScript REPL 런타임 [REMOVED]

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

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

Skills란 무엇인가요?

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

Skill 구조

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

검색 위치

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

Skill 만들기

SKILL.md 형식:

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

## Security Audit Procedure

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

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

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

policy:
  allow_implicit_invocation: false    # Require explicit $skill

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

Skills 호출하기

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

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

활성화/비활성화

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

Skills와 Slash Commands 비교

Skills 디버깅하기

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

1. 검색 여부 확인: TUI의 /skills에 해당 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에 있는 용어를 포함하세요

실제 활용 예시: 배포 Skill

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

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

SKILL.md:

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

## Deployment Procedure

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

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

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

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

Plugins

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

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

v0.143.0(2026년 7월 8일)에서는 원격 plugins가 기본으로 활성화됩니다. 이제 별도의 활성화 플래그 없이 원격 plugins를 사용할 수 있으며, /plugins 카탈로그에는 git 및 로컬 소스와 함께 npm marketplace 소스를 포함한 더 풍부한 행이 표시됩니다. 또한 각 항목에 원격 버전과 로컬 설치 버전이 모두 표시되어 버전 차이를 한눈에 확인할 수 있습니다.¹⁰⁶ 공유 plugin 세트를 팀 표준으로 사용하는 경우, 원격 plugins의 기본 활성화를 통해 이전에는 배포를 가로막았던 장치별 활성화 단계를 없앨 수 있습니다.

Plugin 소스

v0.147.0부터 plugin 검색은 단일 쿼리로 로컬, 개인, workspace, 원격 카탈로그를 모두 검색합니다. 즉, 해당 plugin이 들어 있는 카탈로그가 아니라 필요한 기능을 검색하면 됩니다. 이식 가능한 Agent Plugin 패키지와 함께 사용하면 한 환경에서 만든 plugin을 해당 장치나 작성 당시의 workspace에 종속하지 않고 다른 환경에 원활하게 설치할 수 있습니다.¹¹⁶

Plugin 검색

Codex는 세션 시작 시 활성화된 plugins를 모델에 알려 설치된 MCP, apps, skills를 더 쉽게 찾도록 합니다(v0.111.0).⁶⁵ 모델은 작업 맥락에 따라 세션 도중 관련 plugins를 제안할 수 있습니다. v0.117.0에서는 제품 범위 plugins가 시작 시 동기화되므로 수동 작업 없이 최신 plugin 카탈로그를 사용할 수 있습니다.⁷⁵ v0.142.0부터 /plugins 메뉴는 원격 plugins를 OpenAI 엄선, Workspace, 나와 공유됨 섹션으로 구성하며, 조건을 충족하는 대화 차례에서는 관련 plugins를 인라인으로 추천하고 설치할 수 있습니다.¹⁰⁴ v0.151.0부터 plugin/list와 plugin/installed는 요청된 각 cwd의 유효한 plugin 설정을 불러옵니다. 로컬 marketplaces는 요청 순서대로 결합되고, 설치 및 활성화 상태는 저장소 전반에서 병합되며, 잘못된 프로젝트 설정은 유효한 로컬 카탈로그나 전역으로 활성화된 원격 카탈로그를 누락하지 않고 marketplaceLoadErrors를 통해 보고됩니다.¹³⁴

@plugin 멘션(v0.112.0 이상)

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

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

이 기능은 사용자 지정 skills, MCP servers, app connectors를 비롯해 설치된 모든 plugin에서 작동합니다.

Plugin Marketplace(v0.113.0 이상)

이제 plugin marketplace는 메타데이터, 카테고리, 평점을 제공하여 더 풍부한 검색 경험을 지원합니다.⁶⁹ 설치 시 인증 검사를 통해 API 키나 OAuth가 필요한 plugins에 유효한 자격 증명이 있는지 설치 전에 확인합니다. 제거 엔드포인트는 plugins와 관련 설정을 깔끔하게 삭제합니다.

외부 Marketplaces 추가(v0.121.0 이상)

현재 OpenAI Codex 문서에서는 marketplace 소스 관리를 codex plugin marketplace에서 다룹니다. 이를 통해 OpenAI의 자체 marketplace를 넘어 외부 plugin 배포 방식이 정식으로 정의되었으며, GitHub 저장소 축약형, HTTP(S) Git URL, SSH URL, 로컬 marketplace 루트 디렉터리를 지원합니다. Git 참조를 고정하려면 --ref를 사용하고, Git 기반 marketplace 저장소에서만 --sparse PATH를 반복해서 지정하세요.⁹³

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

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

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

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

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

marketplace를 추가하면 해당 marketplace의 plugins가 기본 plugins와 함께 /plugins 브라우저에 표시됩니다. App-server 호출자(IDE 및 데스크톱 통합)는 별도의 엔드포인트를 통해 marketplaces를 프로그래밍 방식으로 등록할 수 있습니다.⁸²

보안 고려 사항: 외부 marketplaces는 사용자의 Codex 권한으로 임의의 plugin 코드를 실행합니다. 추가하기 전에 소스를 검증하고 처음 실행할 때는 샌드박스 환경을 사용하세요.

Agent Plugins: 여러 공급업체가 사용하는 표준(v0.146.0–v0.147.0)

“Agent Plugins”는 단순한 Codex 기능명이 아니라 개방형 공급업체 중립 패키징 표준입니다. Agent Plugins 1.0.0은 2026년 8월 6일에 공개되었으며, 공식 사이트에서는 이를 “AI 에이전트를 확장하는 재사용 가능 구성 요소를 위한 이식 가능한 패키지 형식”이라고 요약합니다.¹⁶¹ plugin은 필수 plugin.json 매니페스트가 있는 디렉터리입니다. 이 매니페스트는 허용되는 최상위 필드가 $schema, name, version, description, author, homepage, repository, license, keywords, extensions의 정확히 10개뿐인 폐쇄형 스키마이며, “클라이언트는 알 수 없는 각 필드를 보고하고 무시해야 합니다.” 또한 각 직계 하위 디렉터리의 SKILL.md가 하나의 skill을 구성하는 선택적 skills/ 폴더, stdio나 Streamable HTTP 또는 기존 HTTP+SSE 서버를 선언하는 선택적 mcp.json, 다른 클라이언트가 “무시해야 하는” 선택적 역도메인 클라이언트 네임스페이스 디렉터리를 포함할 수 있습니다. 이 표준의 규범적 범위는 패키징입니다. 명세는 “AI 에이전트를 확장하는 재사용 가능 구성 요소를 배포 가능한 plugins로 패키징하기 위한 정식 Agent Plugins Specification v1.0.0을 정의”하며, 그 아래의 Agent Skills와 MCP는 각각 자체 명세를 유지합니다.¹⁶¹

핵심은 운영 체계입니다. Vercel이 제안을 시작하고 Amazon, Anysphere(Cursor), GitHub, Microsoft, OpenAI와 함께 1.0 명세를 개발했습니다. 명세 저장소의 관리자 명단에는 Amazon, Cursor, Microsoft, OpenAI, Vercel이 포함되며, Google은 공개 당일 핵심 관리자 그룹에 합류한다고 발표했습니다.¹⁶¹ 공개 시점에 명시된 클라이언트에는 ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, VS Code가 포함됩니다. 눈에 띄게 빠진 곳도 있습니다. 기반이 되는 Agent Skills 형식과 MCP 자체를 만든 Anthropic은 관리자에 포함되지 않습니다. Claude Code은 자체 plugin 형식을 유지하며, Codex는 Claude Code marketplace 소스(v0.146.0)와 /import를 통해 이 차이를 Codex 쪽에서 연결합니다.¹⁶¹

Codex 관점에서 보면 v0.146.0에는 Agent Plugins 매니페스트, workspace plugin 게시, 그리고 2개의 추가 plugin marketplaces인 Amazon Bedrock과 Claude Code¹¹⁴이 도입됩니다. 이어서 v0.147.0에서는 이식 가능한 Agent Plugins 설치와 로컬, 개인, workspace, 원격 카탈로그를 아우르는 검색이 추가되어 전체 흐름이 완성됩니다.¹¹⁶ 팀에는 workspace 게시가 실무적으로 유용합니다. 공개 marketplace를 직접 구축하거나 모든 개발자에게 Git 소스를 수동으로 추가하도록 요청하는 대신 plugins를 자체 workspace에 게시할 수 있습니다.

릴리스 노트는 Codex에서 제공되는 기능을 알리지만 설정 키나 CLI 구문은 공개하지 않습니다. 이 항목은 해당 기능이 도입되었다는 사실과 표준의 명세 내용만 기록하며, Codex에서 기능을 사용하는 방법은 다루지 않습니다. OpenAI 문서에서 다루기 전까지는 매니페스트 작성 워크플로와 모든 codex plugin publish 호출을 검증되지 않은 것으로 간주하세요.

Plugins 관리

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

v0.153.0에서는 plugin CLI의 범위가 marketplace 관리에서 원격 marketplaces를 대상으로 하는 개별 plugin 작업까지 확장됩니다. codex plugin list에는 원격 카탈로그 항목이 포함되며, JSON 출력에 소스, 버전, 설치 정책, 인증 정책이 표시됩니다. 기존 plugin CLI를 통해 원격 plugins를 추가하고 제거할 수도 있습니다. 원격 카탈로그는 범위와 컬렉션별로 캐시됩니다. 최신 캐시 결과를 우선 사용하며, 추가 요청에서 캐시에 없는 plugin을 찾으면 한 번 다시 가져옵니다. 필터링하지 않은 원격 목록 조회가 실패해도 로컬 엄선 카탈로그는 유지되지만, 명시적으로 선택한 원격 marketplaces의 오류는 계속 표시됩니다.¹⁴⁰

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

전문가 팁: Plugins는 이전에 각각 설정해야 했던 MCP config, skill 설치, app connector 설정을 하나로 통합합니다. 단일 plugin에 이 3가지를 모두 포함할 수 있으므로 팀의 초기 설정은 빨라지고 설정의 이식성은 높아집니다.

계획 모드 및 협업

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

계획 모드와 update_plan 도구 비교(v0.152.0): 두 기능은 서로 다르며, 기본적으로 활성화되는 기능은 하나뿐입니다. 계획 모드는 이 절에서 설명하는 협업 모드로, Codex가 실행 전에 계획을 제안합니다. v0.94.0부터 기본적으로 활성화되었으며 변경 사항은 없습니다. update_plan은 모델이 한 턴 안에서 구조화된 계획을 관리하기 위해 호출할 수 있는 계획 도구입니다. v0.152.0에서 선택적으로 활성화하는 방식으로 출시되었습니다. tools.update_plan.enabled의 기본값은 false이며, 이 기능이 비활성화된 동안 Codex는 모델, 협업 모드, 다중 에이전트, 압축, 사전 준비, 목표 지속 프롬프트에 포함된 update_plan 안내도 제거합니다. 계획을 언급하더라도 사용자 지정 기본 지침, 모델 카탈로그 지침, 협업 정책, 사용자 목표 텍스트는 유지됩니다. 활성화하려면 config.toml에서 tools.update_plan.enabled = true를 명시적으로 설정하세요.¹³⁸

계획 모드 시작하기

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

계획 모드에서 Codex는 다음 작업을 수행합니다: - 파일을 읽고 코드베이스를 분석합니다 - 구현 계획을 제안합니다 - 사용자가 승인할 때까지 변경 사항을 적용하지 않습니다 - 전용 TUI 보기에서 계획을 실시간으로 표시합니다

조정 모드

조정 모드(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

조정 모드는 TUI에서 항상 활성화되어 있습니다. Codex가 완료될 때까지 기다렸다가 지침을 전달하려면 턴이 끝난 후 평소처럼 입력하면 됩니다. 별도의 모드는 필요하지 않습니다.

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

구문 강조(v0.105.0): 이제 TUI는 테두리가 있는 코드 블록과 diff의 구문을 인라인으로 강조합니다. /theme으로 색상 테마를 선택하세요.⁶¹

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

음성 받아쓰기(v0.105.0, 실험적 기능): 스페이스바를 눌러 음성 받아쓰기로 프롬프트를 입력하세요. 이 기능은 실험적이며 마이크 권한이 필요할 수 있습니다.⁶¹ v0.107.0부터 실시간 음성 세션에서 마이크와 스피커 장치를 선택할 수 있으므로, 특정 오디오 입력 및 출력 하드웨어를 지정할 수 있습니다.⁶² v0.140.0에서 제거된 후 v0.145.0에서 다시 도입: 실험적인 /realtime 음성 제어 기능과 관련 오디오 종속성이 v0.140.0에서 TUI에서 제거되었습니다. 스페이스바 음성 받아쓰기에는 영향이 없었습니다.¹⁰² v0.145.0에서는 음성이 새로운 형태로 돌아왔습니다. 일반적인 로컬 오디오 형식의 오디오 입력 및 오디오 도구 출력과 스트리밍 실시간 V3 대화를 지원합니다.¹¹² v0.155.0과 v0.156.0: 실시간 음성 대화. v0.155.0(2026년 9월 17일)에서는 실험적인 선택적 기능으로 /voice가 추가되었습니다. 지원되는 빌드에서 /experimental을 통해 활성화하는 스트리밍 자막 및 마이크 제어 기능이 있는 실시간 대화입니다(#43581, #43651, #44331). 음소거 단축키를 설정할 수 있으며(#43690), macOS 패키지에는 서명된 음성 리소스가 포함되었습니다(#43983). v0.156.0(2026년 9월 22일)에서는 이 기능이 안정화되어 기본적으로 활성화되었으며(#44921), 같은 날 문서 변경 기록에 다음과 같이 발표되었습니다. “음성 대화가 기본적으로 활성화되며, F8 전환 키, /voice settings 선택기, Linux 및 Windows용 기본 제공 오디오 런타임을 지원합니다.” 비활성화하려면 config.toml의 [features] 아래에서 realtime_conversation = false를 설정하세요. CLI slash commands 참조에는 여전히 /voice가 나열되어 있지 않으며, 문서의 음성 기능 페이지는 별도의 환경인 데스크톱 앱의 ChatGPT 음성을 다룹니다.¹⁵⁶¹⁶⁹

기타 개선 사항: - 긴 링크가 TUI의 여러 줄에 걸쳐 줄바꿈되어도 클릭할 수 있습니다(v0.105.0)⁶¹ - 로컬 파일 링크가 개선된 형식으로 표시됩니다(v0.106.0)⁶⁰ - TUI 마크다운은 OSC 8 메타데이터를 통해 웹 링크를 클릭 가능한 상태로 유지하며, 공간이 부족한 표는 링크 대상을 잃지 않고 읽기 쉬운 키와 값 형식으로 전환됩니다(v0.136.0)¹⁶⁸ - 지원되는 터미널에서는 마크다운 링크가 클릭 가능한 레이블로 표시되며, 다른 환경에서는 URL이 그대로 표시됩니다(v0.150.0)¹³² - 하위 에이전트에 대한 Ctrl+C 처리가 수정되어 자식 프로세스를 올바르게 종료합니다(v0.106.0)⁶⁰

메모리 시스템

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

메모리 명령어

메모리는 ~/.codex/memory/ 아래의 마크다운 파일에 저장됩니다. Codex는 세션 시작 시 메모리를 불러오고 이후 모든 세션의 동작에 반영합니다.

저장할 내용

메모리는 지속적으로 유지할 선호 사항과 프로젝트 정보를 저장하는 데 가장 적합합니다:

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

파이프라인의 메모리

codex exec를 실행하면 메모리가 자동으로 불러와집니다. 따라서 CI/CD 파이프라인과 스크립트에서도 대화형 세션과 동일한 맥락을 활용할 수 있으며, 호출할 때마다 지침을 반복할 필요가 없습니다.

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

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

메모리와 AGENTS.md 비교

팁: 계속 유지해야 하는 정보에는 /m_update를 사용하세요. 현재 세션에만 필요한 맥락은 대화에서 Codex에 직접 전달하면 됩니다. 팀이 공유할 맥락에는 AGENTS.md를 사용하세요.

세션 관리

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

v0.146.0에서는 스레드를 이름으로 지정할 수 있습니다. 이제 /new와 /clear에 세션 이름을 지정할 수 있고, 중요한 스레드를 고정할 수 있으며, 다른 대화로 이동하기 위해 현재 대화를 닫지 않아도 보조 대화를 계속 열어 둘 수 있습니다.¹¹⁴ 따라서 장기 프로젝트가 날짜를 보고 구분해야 하는 타임스탬프 목록에 머무르지 않습니다. v0.147.0에서는 대화 섹션이 추가되었습니다. 대화를 직접 순서를 지정할 수 있는 영구 섹션으로 정리할 수 있고, 긴 대화 기록은 전체를 한꺼번에 불러오지 않고 점진적으로 탐색할 수 있습니다.¹¹⁶ v0.148.0에서는 /export와 명령줄 포크가 추가되었습니다. /export는 전체 대화를 Markdown으로 내보내고(클립보드 또는 새 파일), codex exec fork는 세션을 비대화형으로 포크하며, 재개 선택 화면에서는 세션을 보관하고 복원할 수 있습니다.¹¹⁸ v0.149.0에서는 codex queue가 추가되었습니다. 명령줄에서 기존 로컬 또는 원격 세션으로 메시지를 보낼 수 있으며, 재개하거나 포크한 스레드가 활성 권한 프로필을 복원하도록 수정되었습니다.¹²⁰ v0.150.0에서는 자동 제목이 추가되었습니다. 이름이 없는 터미널 작업에는 설명형 제목이 자동으로 지정되며, /rename은 대화 내용을 바탕으로 편집 가능한 제목을 제안합니다.¹³² v0.151.0에서는 /recap이 추가되었습니다. 필요할 때 대화의 최근 진행 상황과 다음 단계를 짧게 요약하도록 요청할 수 있습니다. Codex는 조건에 맞는 유휴 상태의 비활성 대화에도 같은 요약을 자동으로 생성하여 대화 기록에 추가하며, 요청 범위는 제한되고 격리됩니다. 재시도는 자동 요청이 실패한 경우에만 수행됩니다.¹³⁵ v0.153.0에서는 자동 실행 여부를 선택할 수 있습니다. tui.auto_recap = false를 설정하면 예약된 자동 요약 확인이 취소되고 대기 중인 자동 결과가 폐기되지만, 수동 /recap은 계속 작동합니다.¹⁴⁰

codex agents(v0.149.0)는 기기에서 활성 상태인 모든 에이전트 세션을 관리하는 대화형 대시보드입니다. 하나의 화면에서 작업을 검색하고, 시작하고, 열고, 이름을 바꾸고, 중지할 수 있으며, 단축키도 설정할 수 있습니다. 세션 내부에서 /agents는 활성 상태인 모든 에이전트 세션 사이를 전환하고, /subagents는 현재 세션의 하위 에이전트 사이를 전환합니다.¹²⁰¹²⁹ v0.150.0에서는 대화에서 작업을 지정할 수 있습니다. @ 멘션으로 다른 Codex 작업을 참조하고, 에이전트에게 터미널에서 작업을 읽거나 생성하거나 메시지를 보내도록 요청할 수 있습니다.¹³²

재개

중단한 지점부터 계속 진행합니다.

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

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

페이지로 나뉜 스레드 기록(v0.145.0, v0.151.0에서 정식 승격): 페이지로 나뉜 스레드 기록은 효율적인 재개, 전체 기록 검색, 저장되는 스레드 이름, 하위 에이전트 지원, 메모리 기능을 세션 관리에 제공합니다. 기록 전체를 한꺼번에 불러오지 않고 페이지 단위로 불러오므로 세션이 수백 개에 이르는 장기 작업 디렉터리에서 특히 유용합니다. v0.145.0에서 실험적 기능으로 도입되었으며, v0.151.0에서는 API가 실험 단계에서 벗어났습니다(thread/turns/list, thread/items/list, thread/revert에 더 이상 실험적 API 기능이 필요하지 않습니다). 또한 저장소가 thread/turns/list와 thread/items/list를 지원하고 thread/start에서 historyMode를 생략한 영구 스레드에 한해서만 페이지 방식이 최종 기본값으로 적용됩니다. 임시 스레드와 해당 API를 지원하지 않는 저장소 기반 스레드에는 여전히 레거시 방식이 기본으로 적용되고, 명시적으로 선택한 설정의 동작도 유지됩니다. 프로토콜 수준의 ThreadHistoryMode 열거형 역시 tag rust-v0.151.0(protocol.rs:755-758)에서 기본값이 Legacy입니다. 즉, 지원되는 영구 스레드의 최종 기본값일 뿐 전체에 일괄 적용되는 변경은 아닙니다.¹¹²¹³⁵

포크

현재 진행 상황을 잃지 않고 다른 방안을 살펴볼 수 있도록 대화를 분기합니다.

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

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

스레드를 하위 에이전트로 포크하기(v0.107.0): 이제 스레드를 독립적인 하위 에이전트로 포크하여, 하나의 대화에서 자율적으로 실행되는 병렬 작업 흐름을 생성할 수 있습니다. 이는 기존 포크 모델을 확장한 기능입니다. 단순히 대화를 분기하는 데 그치지 않고, 포크된 스레드가 자체 실행 컨텍스트를 갖춘 하위 에이전트가 됩니다.⁶² v0.117.0부터 하위 에이전트는 구조화된 에이전트 간 메시징과 함께 경로 기반 주소(예: /root/agent_a)를 사용하므로 다중 에이전트 조정을 더 명확하게 파악하고 디버깅할 수 있습니다.⁷⁵

암호화된 에이전트 간 메시지(v0.138.0 이상): 이제 다중 에이전트 v2는 상위 에이전트가 하위 에이전트를 생성하거나 하위 에이전트에 메시지를 보낼 때 전달하는 작업 텍스트를 암호화합니다. spawn_agent, send_message, followup_task의 메시지 매개변수는 암호화 대상으로 표시됩니다. 상위 모델이 도구 호출을 생성하면 Responses API가 페이로드를 암호화하고, 로컬에서 실행되는 Codex는 암호문만 전달합니다(InterAgentCommunication.encrypted_content, 일반 텍스트 콘텐츠는 비어 있음). 그런 다음 API가 수신 모델에 전달할 때 서버 쪽에서 이를 복호화합니다.¹⁰⁸ 이 변경에는 다음과 같은 3가지 실질적인 영향이 있습니다.

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

OpenAI는 이 변경의 기반이 되는 위협 모델을 공개하지 않았습니다. PR은 암호문 흐름을 설명하지만 무엇을 방어하기 위한 것인지는 밝히지 않습니다.

안정화된 다중 에이전트 v2(v0.145.0, 선택 적용): v0.137.0에서 처음 공개되고 v0.138.0에서 암호화된 위임 기능이 추가된 다중 에이전트 v2 환경이 이제 선택 적용 기능으로 안정화되었습니다. v0.145.0에서는 설정 가능한 하위 에이전트 모델, 하위 에이전트별 추론 수준, 설정 가능한 동시 실행 수, 복원된 다중 에이전트 역할, 개선된 에이전트 탐색 기능이 추가되었습니다. v0.137 및 v0.138의 초기 안정화 기간에 v2 도입을 미뤘다면 설정 체계가 자리 잡은 이번 릴리스부터 도입할 수 있습니다. 이제 하위 에이전트의 모델과 추론 설정은 런타임에 고정되지 않고 설정에서 지정할 수 있습니다.¹¹²

스레드 목록

활성 세션을 확인하고 관리합니다.

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

데스크톱 앱에서는 사이드바에서 전체 기록과 차이 미리 보기와 함께 스레드를 확인할 수 있습니다.

세션 수명 주기

세션은 CLI와 데스크톱 앱 사이에서 동기화되므로 한쪽에서 시작한 작업을 다른 쪽에서 계속할 수 있습니다.

비대화형 모드 (codex exec)

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

기본 사용법

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
codex exec --json "triage open bugs" -o result.txt

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

세션 보관 (v0.136.0)

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

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

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

JSON Lines 출력

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

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

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

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

구조화된 출력

JSON Schema를 사용해 응답 형식을 강제하세요.

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

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

세션 재개 및 검토

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

주요 플래그

CI 인증

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

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

codex remote-control (v0.130.0+)

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

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

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

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

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

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

이제 app-server 클라이언트는 서로 다른 3가지 턴 항목 보기를 통해 대규모 스레드를 페이지 단위로 불러올 수 있어요.⁹¹

v0.121.0에서 도입된 ThreadStore 인터페이스와 페이지 매김을 함께 사용하면 장기 실행 스레드를 효율적으로 탐색할 수 있어요. 특히 오케스트레이터와 롤아웃 파일이 서로 다른 기기에 있을 수 있는 원격 제어 배포 환경에서 유용해요.⁸² v0.143.0에서는 컨트롤러가 살펴볼 수 있는 범위가 넓어졌어요. 이제 app-server 클라이언트는 사용 가능한 환경을 나열하고, 스레드의 하위 스레드 목록을 확인하며, 특정 턴을 기준으로 기록을 포크할 수 있어요. UI에서 실행을 다시 진행하지 않고도 이전 지점부터 분기하는 데 필요한 기본 기능이에요.¹⁰⁶ v0.151.0에서는 페이지가 매겨진 스레드 기록 APIs가 실험 단계에서 벗어났어요. thread/start에서 historyMode를 생략하면 이를 지원하는 저장소를 사용하는 영구 스레드는 기본적으로 페이지가 매겨진 기록을 사용해요. 임시 스레드와 이를 지원하지 않는 저장소는 기존 방식을 유지해요. 페이지가 매겨진 스레드에서는 전체 기록을 한꺼번에 불러오는 방식이 더 이상 권장되지 않아요. (#40676)¹³⁵

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

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

턴 범위 설정 실시간 변경 (v0.151.0): 이제 실행 중인 턴의 설정을 처리 도중에 변경할 수 있어요. 실험적인 app-server 메서드인 turn/settings/update는 이후 턴의 설정을 바꾸지 않으면서 현재 실행 중인 특정 턴의 후속 단계에 사용할 model, effort, summary, serviceTier를 변경해요. 업데이트가 적용되었는지, 거부되었는지, 대상을 찾지 못했는지도 보고해요. 업데이트된 설정 스냅샷을 게시하기 전에 관리형 제약 조건을 다시 검증하고, 턴 시작 시 허용된 승인 및 Guardian 안전 속성을 그대로 유지해요. turn/start는 serviceTierForTurn도 허용하므로 스레드에 저장된 서비스 티어를 건드리지 않고 새 턴 하나의 서비스 티어만 재정의할 수 있어요. "default"는 표준 속도를 뜻하며, 생략하거나 null로 설정하면 스레드의 티어를 상속해요.¹³⁵

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

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

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

GitLab 지원(베타, 2026년 8월 19일): 이제 모든 ChatGPT 요금제에서 Codex 클라우드를 GitLab 프로젝트에 연결할 수 있습니다. 프로젝트를 연결하고, 환경을 만들고, 이슈와 병합 요청에서 작업을 시작하고, 리뷰를 요청할 수 있습니다. Self-Managed GitLab에는 19.0 이상이 필요합니다.¹¹⁹

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

Codex Cloud는 OpenAI가 관리하는 환경에서 작업을 비동기식으로 실행합니다.⁴ CLI v0.150.0부터는 터미널 대화에서도 작업을 다룰 수 있습니다. @ 멘션으로 다른 Codex 작업을 참조하고 에이전트에게 작업을 읽거나 생성하거나 메시지를 보내도록 요청할 수 있습니다.¹³² Codex를 CI 파이프라인에 통합하는 방법은 GitHub Action 및 CI/CD도 참조하세요.

클라우드 작업 자격 증명 보안 강화(v0.152.0): 클라우드 작업 요청에는 저장된 ChatGPT 자격 증명이 포함될 수 있으므로, 이제 인증을 불러오기 전부터 요청 대상이 제한됩니다. CODEX_CLOUD_TASKS_BASE_URL은 443 포트의 신뢰할 수 있는 ChatGPT HTTPS 출처인지 검증되며, 사용자 정보, 쿼리 또는 프래그먼트가 포함된 URL은 거부됩니다. 또한 자격 증명이 리디렉션 대상에 전달되지 않도록 클라우드 작업 백엔드와 환경 검색 클라이언트의 리디렉션이 비활성화되었습니다.¹³⁸

작동 방식

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

클라우드의 인터넷 액세스

에이전트의 인터넷 액세스는 기본적으로 꺼져 있으며 환경별로 설정합니다.

• 꺼짐: 에이전트가 인터넷에 액세스할 수 없습니다(기본값).
• 켜짐: 선택적 도메인 허용 목록과 HTTP 메서드 제한을 적용합니다.

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

에이전트의 인터넷 액세스가 꺼져 있어도 설정 스크립트는 인터넷을 사용하여 종속성을 설치할 수 있습니다.

Slack 통합

Slack 채널이나 스레드에서 @Codex를 멘션하여 클라우드 작업을 시작합니다.

사전 요구 사항: 1. 이용 가능한 ChatGPT 요금제(Plus, Pro, Business, Enterprise 또는 Edu) 2. 연결된 GitHub 계정 3. 설정된 클라우드 환경 1개 이상 4. 워크스페이스에 설치된 Slack 앱

Codex는 작업 링크로 응답하고 완료되면 결과를 게시합니다.

클라우드 CLI

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

Codex Desktop App

Codex Desktop App(macOS 및 Windows)은 여러 프로젝트를 관리하는 데 최적화된 그래픽 인터페이스를 제공합니다.¹⁶ Windows 버전은 기본 PowerShell 지원 및 기본 Windows sandbox와 함께 2026년 3월 4일에 출시되었습니다.⁶⁶

설치

codex app                      # Auto-downloads and installs on first run

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

주요 기능

Appshots, 브라우저 댓글 및 Computer Use

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

웹 및 프런트엔드 작업에서 페이지에 인증이 필요하지 않다면 먼저 앱 내 브라우저를 사용하세요. 사용자와 Codex가 렌더링된 미리 보기를 함께 확인할 수 있으며, 클릭, 스크린샷, 에셋 다운로드, 읽기 전용 검사 JavaScript 등의 브라우저 사용 작업을 지원합니다. 또한 페이지 영역에 댓글을 표시하면 Codex가 다음 턴에서 이를 처리할 수 있습니다.⁹⁹ 로그인이 필요한 사이트에서는 브라우저 확장 프로그램(Chrome, Edge, Brave, Opera 또는 Vivaldi, 단 Opera에는 사이드 채팅이 없음)을 계속 사용하세요. 사이트 도구(WebMCP, 2026년 8월 25일): Desktop App의 내장 브라우저에서 ChatGPT Work와 Codex는 웹사이트가 제공하는 도구를 사용해 페이지를 다룰 수 있습니다. 사이트 도구는 GPT-5.6 Luna 또는 Enterprise나 Edu 워크스페이스에서 사용할 수 없으므로, 최신 Desktop App에서 GPT-5.6 Sol 또는 GPT-5.6 Terra를 사용하세요.¹²⁷

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

스레드 모드

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

Worktree 격리 방식:

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

따라서 충돌 없이 같은 저장소에서 여러 Worktree 스레드를 동시에 실행할 수 있습니다. 각 스레드에는 별도의 브랜치와 작업 디렉터리가 할당됩니다.

Worktree 설정 및 스레드 소유권(v0.151.0): 관리형 worktree 동작은 전용 설정 파서가 기존 [desktop] 설정을 바탕으로 결정합니다. worktree 루트의 기본값은 $CODEX_HOME/worktrees이고, 자동 정리는 기본적으로 활성화되며, 15개의 worktree가 유지됩니다. 설정된 루트, 정리 플래그, 유지 개수는 사용 전에 검증됩니다. 또한 관리형으로 연결된 각 worktree는 Git 메타데이터에 버전이 지정된 codex-thread.json 소유권 레코드를 포함하여 특정 스레드에 바인딩할 수 있습니다. 쓰기는 원자적이고 기존 데이터를 덮어쓰지 않으며, 동일한 바인딩을 반복해도 결과가 달라지지 않고 소유권이 충돌하면 거부됩니다. 소유권 메타데이터를 건드리기 전에 기본, 중첩 및 비관리형 체크아웃도 거부됩니다.¹³⁵

v0.154.0에서 관리형 worktree가 CLI에 도입됨(실험적 기능): 실행 시 --worktree를 사용하거나 TUI에서 /worktree를 실행하면 새 세션 또는 분기된 세션을 위한 격리된 체크아웃이 생성되고, codex exec는 자동화를 위한 관리형 worktree를 지원합니다. 또한 TUI 세션 명령어와 worktree 브라우저를 통해 worktree 세션을 나열하고 탐색하며 재개할 수 있습니다(#42196, #42366, #42652, #43069, #43120, #43286). worktree가 여전히 기본값으로 비활성화된 가운데 v0.155.0에는 관련 관리 기능이 추가됨: 에이전트 개요에서 worktree 세션을 숨기고 보관하고 삭제할 수 있으며, 소유권 세부 정보가 표시되고, 변경 사항이 없는 관리형 worktree를 삭제할 때 확인을 요청합니다(#43942, #44424, #44433). 기본 활성화 변경 사항인 #44870은 9월 11일에 병합되었지만 안정 버전 0.155.0에는 포함되지 않았으며, rust-v0.155.0 태그를 기준으로 선행 커밋 여부를 확인했습니다.¹⁵²¹⁵⁶

v0.156.0에서 관리형 worktree가 기본값으로 전환됨: #44870은 worktrees를 안정 기능으로 승격하고 기본적으로 활성화하며 /experimental에서 제거합니다. 이와 함께 다음 기능도 출시되었습니다. worktree 세션은 자체 데몬을 시작하는 대신 기존 로컬 데몬에 연결할 수 있으며(#46498), 에이전트 개요에서 worktree 세션을 직접 생성할 수 있습니다(#45276). 에이전트 개요에는 상태 필터 탭도 추가되었습니다(#46839). 별도로 요청하지 않는 한 worktree가 비활성화되어 있다고 가정하고 작성한 스크립트나 설정이 있다면, 0.156.0부터 동작이 달라집니다. 비활성화 방법: config.toml의 [features] 아래에 worktrees = false를 설정하세요(실행별 설정: --disable worktrees). 이전 로컬 데몬: “The local Codex service cannot check background terminals”라는 메시지와 함께 worktree 생성 또는 /cd가 차단되면 codex app-server daemon update를 실행하고 Codex를 다시 시작하세요.¹⁶⁹¹⁷¹

자동화

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

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

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

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

결과는 사람의 승인을 받을 수 있도록 검토 대기열에 표시됩니다.

Windows 지원

Codex Desktop App은 기본 PowerShell 지원, 기본 Windows sandbox, skills, 자동화, worktrees를 포함한 모든 기능을 WSL 없이 사용할 수 있도록 지원하며 2026년 3월 4일 Windows용으로 출시되었습니다(App v26.304).⁶⁶

GitHub Action 및 CI/CD

공식 GitHub Action은 Codex를 CI/CD 파이프라인에 통합합니다.¹⁸

기본 사용법

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

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

설정 옵션

출력: final-message는 이후 단계/작업에서 사용할 최종 Codex 응답 텍스트입니다.

안전 전략

접근 제어

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

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

Codex SDK

TypeScript SDK는 Codex의 에이전트 기능을 사용자 지정 애플리케이션에 내장합니다.¹⁹

설치

npm install @openai/codex-sdk

기본 사용법

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

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

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

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

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

고급 SDK 기능

• runStreamed(...): 중간 업데이트를 제공하는 비동기 이벤트 스트림
• Python SDK 인증(v0.132.0+): API 키 로그인, ChatGPT 브라우저/기기 코드 흐름, 계정 조회, 로그아웃을 SDK에서 바로 사용할 수 있습니다.⁹⁷
• 텍스트 전용 턴 편의 기능(v0.132.0+): Python 턴 API는 일반 문자열을 받고, 수집된 항목, 소요 시간, 사용량이 포함된 더 풍부한 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 이상.

성능 최적화

컨텍스트 관리

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

1. /compact를 정기적으로 사용하세요: 대화 기록을 요약해 토큰을 확보합니다
2. 로컬 문서를 제공하세요: 품질이 높은 AGENTS.md와 로컬 문서는 컨텍스트를 소모하는 탐색 작업을 줄입니다
3. @로 특정 파일을 첨부하세요: Codex에 파일을 찾도록 요청하지 말고 직접 참조하세요
4. 프롬프트의 범위를 명확히 하세요: 정확한 파일을 지정한 프롬프트는 개방형 탐색보다 컨텍스트를 적게 소모합니다

실험적 컨텍스트 관리(v0.153.0, 기본적으로 비활성화됨): features.context_management.experimental_mode는 Codex 백엔드를 사용하는 대상 ChatGPT Plus, Pro, Pro Lite 세션에서 토큰 예산 컨텍스트, 기록 메모, new_context 도구로 구성된 통합 컨텍스트 스택을 활성화합니다. API 키 세션, 사용자 지정 공급자, Codex 이외의 엔드포인트, 임시 구조화 스레드는 제외됩니다. 이 플래그는 아직 개발 중임이 명시되어 있으므로 워크플로를 구축할 기능이 아니라 향후 컨텍스트 처리 방향을 미리 살펴보는 기능으로 취급하세요.¹⁴⁰ v0.154.0에는 기능 지원 여부 확인이 추가되었습니다: 세션이 시작될 때 활성 모델의 기능을 기준으로 사용 가능 여부를 결정합니다(#43147). 이는 Codex 모델 문서에서 Plus 및 Pro 로그인용 Astra를 명시한 것과 같은 기능 체계입니다(어떤 모델을 선택해야 합니까? 아래의 교차 컨텍스트 참고 사항 참조).¹⁴⁶¹⁵² v0.157.0 현재 번들 카탈로그에는 이를 지원하는 것으로 표시된 모델이 없으므로(#47397), 해당 카탈로그를 사용하면 이 설정은 아무 효과가 없습니다.¹⁷⁴

토큰 효율성

속도 최적화

1. gpt-5.3-codex-spark: 대화형 페어링을 위한 지연 시간이 짧은 변형 모델입니다
2. --profile fast: 낮은 추론 수준으로 미리 설정된 gpt-5.6-luna 프로필입니다
3. 병렬 도구 실행: Codex는 서로 독립적인 읽기/검사를 동시에 실행하므로 이를 활용할 수 있도록 프롬프트를 구성하세요
4. 결과 중심 반복 작업: 단계별 지침 대신 “구현하고, 테스트하고, 수정한 뒤, 모두 통과하면 중지하세요”라고 요청하세요

문제를 디버깅하려면 어떻게 해야 합니까?

자주 발생하는 문제와 해결 방법

오류 메시지 참고 자료

codex doctor는 어떤 기능을 합니까?

codex doctor는 버그를 신고하거나 손상된 설치를 디버깅하기 전에 실행할 단일 명령입니다. 로컬 런타임, 설정, 인증, 터미널, 네트워크, 상태를 하나의 보고서에 담으며, 프로젝트 자체의 이슈 템플릿에서도 이 출력을 붙여 넣도록 요청합니다.¹⁶³

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

보고서는 일정한 섹션으로 구성되어 필요한 부분을 빠르게 찾아볼 수 있습니다.¹⁶³

각 검사는 상태 표시 기호인 ✓ 정상, ✗ 실패, ⚠ 경고, ○ 대기와 요약 문구를 함께 표시합니다. --json은 모든 검사에 일정한 식별자를 키로 부여하므로 육안으로만 확인하지 않고 CI나 지원 스크립트에서도 활용할 수 있습니다.¹⁶³

이 명령은 릴리스가 거듭되면서 확장되었습니다. v0.131.0에서 처음 도입되었고, v0.135.0에서는 환경, Git, 터미널, 앱 서버, 스레드 목록 보고 기능이 추가되었으며, v0.139.0에서는 편집기와 페이저 세부 정보가 추가되었습니다(JSON에서는 민감한 값을 가립니다).^96176165

마지막이 아니라 가장 먼저 사용하세요. “Codex가 작동하지 않는다”는 신고 대부분은 doctor가 이미 짚어 주는 문제로 귀결됩니다. 오래된 인증 모드, 구문 분석에 실패한 config.toml, 또는 PATH에서 현재 설치를 가리는 또 다른 설치가 대표적인 예입니다.

진단 도구

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

세션 내 TUI 진단:

/status                                # Token/session overview
/debug-config                          # Show config layers and requirement sources
/compact                               # Summarize history to reclaim context

참고: codex --verbose는 유효한 최상위 플래그가 아닙니다. 위의 디버그 하위 명령과 TUI 진단을 사용하세요.

새로 설치

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

~/.codex/의 인증, 설정, 세션은 보존합니다. 정확한 버전으로 고정하거나, 문제가 있는 릴리스 이후 다운그레이드하거나, 모든 상태를 지우는 방법은 업데이트, 다운그레이드 또는 제거를 참고하세요.

디버그 모드

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 [미리 보기]

Codex Security는 2026년 3월 6일에 연구 미리 보기로 공개되었으며, 컨텍스트를 인식하는 애플리케이션 보안 검토 기능을 Codex 제품군에 도입했습니다.⁷⁷ ChatGPT Pro, Enterprise, Business, Edu 고객은 Codex 웹에서 사용할 수 있습니다.

작동 방식: Codex Security는 저장소를 분석하여 프로젝트별 위협 모델을 구축하고, 실제 환경에서 미치는 영향에 따라 분류한 취약점을 식별한 다음, 샌드박스 환경에서 결과를 집중적으로 검증합니다. 에이전트는 신뢰도가 높은 결과와 수정 방법을 제시하여 중요하지 않은 버그로 인한 잡음을 줄입니다.

성능: 연구 미리 보기 기간에 Codex Security는 120만 개의 커밋을 스캔하여 심각도가 높은 취약점 10,561개를 식별했습니다. 시간이 지나면서 정밀도가 개선되어 잡음은 84% 줄었고, 과도하게 보고된 심각도는 90% 이상 감소했으며, 오탐률은 절반으로 낮아졌습니다. 이 시스템은 OpenSSH, GnuTLS, Chromium에서 실제 취약점을 발견했으며, 이 가운데 14건에는 CVE가 부여되었습니다.⁷⁷

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

엔터프라이즈 배포

관리자 제어(requirements.toml)

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

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

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["on-request", "never"]   # `untrusted` retired in v0.149.0

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