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

핵심 요약: Codex는 여러 환경에서 사용하는 코딩 에이전트입니다. 코드베이스를 읽고, OS 수준의 샌드박스에서 명령을 실행하며, 파일을 수정하고, 클라우드에 작업을 위임합니다. config.toml, 샌드박스/승인 모델, AGENTS.md, MCP, skills라는 다섯 가지 시스템을 익히면 작업 효율을 크게 높일 수 있습니다. 모델 선택: 현재 OpenAI 모델 문서는 복잡한 코딩과 에이전트 작업에 GPT-6.1 Sol(gpt-6.1-sol, v0.159.1부터 CLI에 기본으로 포함된 모델)을, 처음부터 끝까지 수행해야 하는 가장 어려운 작업에 GPT-6-Astra를, 범위가 명확하고 반복적인 작업에 GPT-6 Luna를 권장합니다. 사용 가능한 모델은 요금제, 클라이언트, 워크스페이스 설정에 따라 달라집니다. GPT-6 Sol과 GPT-5.6 모델은 모델 선택 메뉴에 계속 표시되며, ChatGPT로 로그인하는 사용자를 대상으로 한 Codex의 GPT-5.5 지원은 2026년 10월 14일에 종료됩니다.^146171178 처음 사용하십니까? 설치와 빠른 시작으로 바로 이동하세요. 릴리스 소식을 확인하고 계십니까? 최신 안정 버전은 v0.164.0(2026년 10월 23일)입니다. 재사용 가능한 프롬프트를 위한 /presets 슬롯 10개, 인라인 /model 및 /permissions 인수, 전체 화면 대화 기록의 이미지 미리 보기, 기업에서 관리하는 MCP 로그인, 기본으로 활성화된 Bedrock 설정 마법사를 제공합니다. 주요 릴리스 변경 사항은 현재 상태 요약(기본으로 활성화된 기능과 아직 실험 단계인 기능)으로 시작한 뒤 각 버전을 다루며, 변경 이력에는 가이드의 모든 업데이트가 정리되어 있습니다.^116178182183

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

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

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

저는 몇 달 동안 프로덕션 코드베이스, CI/CD 파이프라인, 팀 워크플로에서 Codex를 Claude Code와 함께 사용했습니다. 이 가이드는 그 경험을 바탕으로, 처음 시작할 때 있었으면 했던 종합 참고 자료로 정리한 것입니다. 모든 기능에는 실제 구문, 실제 설정 예제, 숙련된 사용자도 놓치기 쉬운 예외 상황을 함께 담았습니다.

핵심 요점

• 5가지 인터페이스, 하나의 두뇌: CLI, 데스크톱 앱, IDE 확장 프로그램, 클라우드 작업, 브라우저 확장 프로그램(Chrome, Edge, Brave, Opera, Vivaldi)은 모두 동일한 모델 제품군을 공유하므로 워크플로에 맞는 인터페이스를 선택하세요.⁹⁰
• 운영체제 수준의 샌드박싱: Codex는 컨테이너 내부가 아니라 커널 수준에서 파일 시스템과 네트워크 제한을 적용합니다(macOS에서는 Seatbelt, Linux에서는 bubblewrap + seccomp).
• AGENTS.md는 여러 도구에서 호환됩니다: 프로젝트 지침은 Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed와 60,000개 이상의 오픈 소스 프로젝트에서 작동합니다. 한 번 작성해 어디서든 사용하세요.
• 프로필을 사용하면 컨텍스트 전환 부담을 줄일 수 있습니다: 이름이 지정된 설정 프리셋(fast, careful, auto)을 정의하고 --profile로 전환하세요.
• 컨텍스트 관리가 중요합니다: Codex에 포함된 카탈로그에서 GPT-6.1 Sol, GPT-6 Astra, Sol, Luna와 GPT-5.6 제품군의 컨텍스트 창은 272K입니다(API에는 GPT-6.1 Sol, GPT-6 Sol, Luna가 1.05M으로 명시되어 있습니다). GPT-5.5는 2026년 10월 14일 Codex에서 지원이 종료될 때까지 400K를 제공합니다. /compact, 범위를 명확히 한 프롬프트, @file 참조를 사용해 토큰 예산을 미리 관리하세요.^83112178

이 가이드 사용 방법

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

마지막에 있는 빠른 참조 카드에서는 모든 주요 명령을 한눈에 살펴볼 수 있습니다.

릴리스 주요 변경 사항: 최근 달라진 점

Codex 릴리스 흐름을 살펴보는 독자를 위해 버전별 변경 사항을 최신순으로 정리했습니다. 처음 사용한다면 빠른 시작으로 건너뛰세요. 아래 내용을 몰라도 바로 활용할 수 있습니다. 검증 세부 사항(버전 비교, 커밋 목록, 문서 확인)은 각주에 있습니다.

현재 상태

2026년 10월 23일 기준 Codex CLI

• 안정 버전: v0.164.0(10월 23일, npm latest)은 0.164.0-alpha.11에 릴리스 커밋 1개를 더해 출시했으며(alpha.12에는 안정 버전에 없는 커밋 9개가 포함되어 있습니다), v0.163.0 이후 커밋 330개를 포함합니다. 재사용할 프롬프트와 slash commands를 저장하는 번호가 지정된 /presets 슬롯 10개, 인라인 /model [model] --reasoning <level> --speed <tier> 및 /permissions <profile-id>, Kitty 또는 Sixel 터미널의 전체 화면 대화 기록 내 이미지 미리보기, MCP 연결을 위한 기업 관리형 권한 부여, 지원되는 원격 Bash 명령의 자격 증명 마스킹(credential_masking 플래그로 제어), 기본 활성화된 Amazon Bedrock 설정 마법사가 추가되었습니다. 이전 버전인 v0.163.0(10월 15일)에서는 검색 가능한 /config 패널, 리더 키, 기본 활성화된 Daybreak가 추가되었습니다.
• 알파 버전: npm alpha는 0.165.0-alpha.1입니다(10월 23일, 안정 버전 출시 몇 시간 후). 해당 태그에서 reasoning_effort_override는 안정 기능으로 활성화되어 있으며, 새로 추가된 guardianv3, guardian_recorded_items, tui_multi_backend는 비활성화되어 있습니다. 0.164 계열은 alpha.1(10월 16일)부터 alpha.12(10월 22일)까지 이어졌으며, 별도 빌드인 0.163.0-alpha.11.1과 11.2(10월 21~22일), 0.164.0-alpha.11.1(10월 23일)도 함께 출시되었습니다.
• v0.159.1부터 기본 모델: GPT-6.1 Sol이 Amazon Bedrock을 포함해 GPT-6-Astra를 대체했습니다. 다른 모델을 계속 사용하려면 config.toml에서 model을 설정하세요. v0.164.0에 포함된 카탈로그는 v0.162.1 및 v0.163.0의 카탈로그와 바이트 단위로 동일하며, v0.159.1과 같은 모델을 나열합니다.
• v0.164.0부터 기본 활성화: Amazon Bedrock 설정 마법사(bedrock_setup_wizard, 안정 기능. [features] 아래에 bedrock_setup_wizard = false를 설정하면 비활성화됩니다), 증분 도구 업데이트(incremental_tools, 안정 기능), MCP OAuth 갱신 조정(mcp_oauth_refresh_coordination, 안정 기능). 관리형 worktrees와 실시간 대화는 항상 활성화됩니다. 해당 플래그는 제거된 것으로 표시되지만 기능은 활성화된 상태로 유지됩니다.
• v0.163.0부터 기본 활성화: Daybreak(cli_daybreak, 이제 안정 기능. [features] 아래에 cli_daybreak = false를 설정하면 제어 항목이 숨겨집니다)와 코드 모드 중단(code_mode_interrupt, 안정 기능)이 활성화되어 후속 입력도 실행 중인 Code Mode 셀을 중단합니다. API 키를 사용하는 세션에는 Cyber 액세스 프로그램이 기본 제공됩니다(api_key_cyber_access_programs). 제거된 항목: shell_zsh_fork와 unified_exec_zsh_fork는 마이그레이션 안내와 함께 무시됩니다.
• v0.162.0부터 기본 활성화: instant_interrupt가 활성화되어 새 입력이 모델 응답을 중단하고 우선 처리됩니다([features] 아래에 instant_interrupt = false를 설정하면 비활성화됩니다). 이 플래그는 여전히 개발 중으로 표시됩니다.
• v0.161.0부터 기본 활성화: API 키를 통한 모델 검색([features] 아래에 api_key_model_discovery = false를 설정하면 비활성화됩니다).
• v0.158.0부터 기본 활성화: 권한이 상승된 터미널에 입력할 때 승인 요청([features] 아래에 write_stdin_approval = false를 설정하면 비활성화됩니다), 전체 화면 TUI에서 선택 시 복사 및 마우스 오른쪽 버튼 클릭으로 붙여넣기([tui] 아래의 copy_on_select = "never", right_click_paste = "off"). Guardian 스레드 컨텍스트는 항상 활성화되며, thread_context는 무시됩니다.
• v0.157.0부터 기본 활성화: 전체 화면 대화 기록([tui] 아래의 fullscreen_transcript = false)과 백그라운드 서버 자동 시작([features] 아래의 daemon_auto_start = false 또는 --no-daemon).
• v0.156.0부터 기본 활성화: /voice, 관리형 worktrees, Guardian의 상위 스레드 압축 결과 재사용.
• 선택적 활성화 또는 실험 기능: Codex Cloud, 코드 모드와 순위 기반 도구 검색(code_mode_tool_search, v0.162.0), Guardian 기록 조회(guardian_conversation_history_tools, v0.160.0), v0.164.0에서 비활성화된 상태로 제공되는 개발 중 플래그(v0.163.0부터: async_compaction, credential_masking, output_token_replay, retain_client_tool_outputs, subagent_default_context_limits, code_mode_host_grpc, code_mode_tool_description_first, guardian_trust_orchestrator_connectors; v0.164.0에서 추가: app_server_websocket_compression, executor_capability_discovery_v2, mcp_tool_list_changed, multi_env_copy_file, runtime_agent_instances, subagent_thread_environments, wake_on_agent_messages). 실험적 컨텍스트 관리는 현재 사용할 수 없습니다.
• 모델: 복잡한 코딩에는 GPT-6.1 Sol, 가장 어려운 작업에는 GPT-6-Astra, 반복 가능한 작업에는 GPT-6 Luna를 사용합니다. GPT-6 Sol과 Luna는 Fast(크레딧 2.5배)로 시작하지만, GPT-6.1 Sol은 그렇지 않습니다. GPT-5.5는 2026년 10월 14일 Codex에서 제외됩니다.
• 버전 고정: npm install -g @openai/codex@0.164.0을 실행한 다음 codex --version으로 확인하세요.^{176178186187188189192193194195}

v0.164.0(2026년 10월 23일)

0.164 계열은 자체 알파 버전을 기반으로 안정 버전을 출시했습니다. v0.164.0은 0.164.0-alpha.11에 릴리스 커밋 1개를 더해 10월 23일에 게시되었습니다(04:48 UTC, npm latest는 04:52 UTC). alpha.12(10월 22일)는 이 분기 지점보다 커밋 9개가 앞서 있었고, 별도 빌드인 0.164.0-alpha.11.1(10월 23일 01:58 UTC)은 alpha.11을 기반으로 커밋 4개를 추가했습니다. v0.163.0과 비교하면 커밋은 330개입니다. 플래그 3개가 활성화되고 안정 기능으로 표시됩니다. bedrock_setup_wizard(Amazon Bedrock 설정 마법사로, 자격 증명이 감지되면 API 키 입력이 다른 AWS 로그인 방식과 함께 표시됩니다), incremental_tools, mcp_oauth_refresh_coordination입니다. worktrees와 realtime_conversation 플래그는 제거된 것으로 표시되지만 기능은 활성화된 상태로 유지되므로, 관리형 worktrees와 실시간 대화는 더 이상 켜거나 끌 수 없습니다. stable_environment_tools와 transcript_v2도 제거되었습니다. 개발 중 플래그 7개가 새로 추가되었으며 모두 비활성화되어 있습니다. 번들 모델 카탈로그는 v0.162.1에 포함된 것과 동일한 블롭입니다.¹⁹⁴¹⁹⁵

TUI의 새로운 기능. /presets는 키보드 메뉴를 통해 번호가 지정된 슬롯 10개에 재사용할 프롬프트와 slash commands를 저장합니다. 프리셋은 입력창의 텍스트나 현재 모델, 추론 수준, 속도를 바탕으로 만들 수 있으며, 현재 적용 중인 사용자 설정의 tui.presets에 저장됩니다(#54380, #54381). /model [model] --reasoning <level> --speed <tier>는 저장된 기본값을 변경하지 않고 현재 세션에 모델, 추론 수준, 속도를 적용하며, 플래그 값은 공백 또는 =로 구분할 수 있습니다. 모델을 생략하면 현재 모델에 설정이 적용되고, /model만 입력하면 이전처럼 선택 메뉴가 열립니다(#54378). /permissions <profile-id>는 /permissions :read-only처럼 내장 또는 사용자 지정 권한 프로필을 인라인으로 선택하며, :ask-for-approval과 :approve-for-me를 별칭으로 지원합니다(#54383). Kitty 또는 Sixel 그래픽을 지원하는 터미널에서는 전체 화면 대화 기록에 열어 본 이미지와 생성한 이미지가 크기가 제한된 썸네일로 표시됩니다. 원격 작업 공간, 지원되지 않는 터미널, 크기 제한을 초과하는 이미지에는 텍스트 전용 항목이 유지됩니다(#54216).¹⁹⁴

연결과 자격 증명. 직접 설정한 MCP 서버는 키링에 저장된 계정 범위의 기업 권한 부여 정보나 전용 로그인을 통해 인증할 수 있으며, 시크릿이 필요한 OAuth 클라이언트도 지원합니다. 기업 관리형 권한 부여 확장은 2026-07-28 프로토콜을 통해 협상되며, 계정 소유자가 변경되거나 기업 로그인이 기존 권한 부여를 대체하면 해당 권한이 취소됩니다(#55334, #55859, #56001). 자격 증명 마스킹은 사용자 지정 제공업체의 자격 증명을 포함해 지원되는 원격 Bash 명령과 zsh 스냅샷 세션에도 적용됩니다. 명령에는 플레이스홀더가 전달되고, 실행기 로컬 프록시가 일치하는 대상에 실제 자격 증명을 주입합니다. 마스킹을 사용할 수 없는 경우에는 경고를 표시하고 마스킹 없이 실행합니다. 해당 태그에서도 credential_masking 플래그는 비활성화된 상태로 제공됩니다(#54309, #54432, #56049).¹⁹⁴¹⁹⁵

수정 및 정리. 압축에 실패해도 대화 기록에 불완전한 요약이 남지 않으며, 백그라운드 압축 실패 시 패닉 없이 대체 처리로 전환합니다(#53932, #55581). 세션을 재개할 때 압축된 기록을 찾고, 저장된 스레드 설정을 전역 기본값으로 대체하지 않고 복원합니다(#54008, #55923). Windows에서는 HTTPS 및 WebSocket 연결이 로그인한 사용자의 Negotiate 또는 NTLM 자격 증명으로 프록시 인증 요청에 응답합니다(#55994, #56000). 여러 하위 명령 수준에서 지정한 -c 또는 --config는 모든 재정의 값을 유지합니다(#56022). 대기열의 프롬프트는 보류 중인 권한 선택이 완료될 때까지 기다립니다(#55682). 샌드박스는 macOS에서 대소문자가 다른 메타데이터 경로와 실행 파일을 찾는 데 사용되는 교체 가능한 심볼릭 링크를 검사합니다(#54273, #55384). 디스크 사용량도 줄어듭니다. 사용하지 않는 설치본을 정리하고(현재 및 이전에 데몬으로 선택한 설치본은 유지합니다), 방치된 마켓플레이스 체크아웃을 삭제하며, 데몬 로그 크기를 제한합니다(#53827, #55149, #55689, #55690, #55856). 내장 JavaScript 런타임에는 최적화된 Array.sort의 안전성 검사가 추가되었습니다(#54519).¹⁹⁴ 권장 조치: 업그레이드하세요. Bedrock에서 초기 설정을 진행하는 경우를 제외하면 체감할 만한 기본값 변경은 없습니다. Bedrock에서는 이제 마법사가 자동으로 실행됩니다([features] 아래에 bedrock_setup_wizard = false를 설정하면 비활성화됩니다). [features] 아래에 worktrees나 realtime_conversation을 설정했다면, 이제 해당 키는 무시됩니다.¹⁹⁴¹⁹⁵

v0.163.0 (2026년 10월 15일)

0.163 계열의 안정 버전이 별도 릴리스 브랜치에서 출시되었습니다. v0.163.0은 10월 15일에 공개되었습니다(21:30 UTC, npm latest는 21:37 UTC). alpha.10을 기반으로 별도 빌드한 0.163.0-alpha.10.2에 릴리스 커밋 1개를 더한 버전입니다. 정규 개발 흐름의 alpha.11(10월 14일)에는 이 안정 버전에 포함되지 않은 커밋 23개가 있어, 0.158 때와 같은 양상이 반복되었습니다. v0.162.1과 비교하면 커밋은 232개입니다. 기능 플래그 2개가 활성화되며, 둘 다 안정 상태로 표시됩니다. cli_daybreak는 Daybreak 제어 기능, /daybreak 전환, 자격을 갖춘 OpenAI 계정의 Cyber 액세스 프로그램 자동 라우팅을 제공합니다. 서버가 액세스를 제공하면 codex exec에서도 OpenAI API 키로 이를 선택할 수 있습니다. code_mode_interrupt는 턴을 중단할 때 실행 중인 Code Mode 셀과 그 안의 중첩 도구 호출도 함께 중단합니다. 이미 안정 상태였던 api_key_cyber_access_programs도 활성화됩니다. instant_interrupt는 활성화 상태를 유지하며, 여전히 개발 중으로 표시됩니다.¹⁹²¹⁹³

TUI의 새로운 기능입니다. /config는 모양, 알림, 입력, 세션, 텍스트 선택 탭으로 구성된 검색 가능한 환경설정 패널을 엽니다. 지원되는 변경 사항은 즉시 적용되며, 패널에는 재시작이 필요한 항목이 표시됩니다. 변경 사항은 선택한 로컬 설정 파일에 저장됩니다(#52990, #53429). /keymap에서는 리더 키를 설정합니다. tui.keymap.global.leader의 기본값은 ctrl-x이며, leader c 같은 키 바인딩은 이 키를 누른 뒤 이어서 입력합니다. 단축키 안내는 선택하거나 취소할 때까지 표시되며, 음성 음소거 단축키는 Ctrl+X에서 F9로 바뀝니다(#52273). /daemon은 관리형 백그라운드 서버를 재시작할 수 있습니다. 재시작으로 중단될 수 있는 작업을 경고하고, 재시작 후 다시 연결합니다(#53173). Codex는 서로 독립적인 읽기 전용 도구를 병렬로 실행합니다. 여기에는 skills, 메모리, 대화 기록 조회, 플러그인 및 에이전트 목록 조회, 현재 시각, 남은 컨텍스트, get_goal이 포함됩니다(#52245). Codex가 응답하는 동안 후속 메시지를 보내면 즉시 작업 방향에 반영됩니다(#51812, #51835).¹⁹²

수정 사항과 플랫폼 관련 변경입니다. 저장된 스레드를 재개하면 해당 스레드의 권한과 네트워크 승인이 복원되며, 명시적으로 지정한 재정의 설정과 관리 정책이 우선 적용됩니다(#53150, #53419, #53424). 네트워크 프록시는 DNS 조회 전에 권한을 확인하고, 중복된 Host 헤더를 거부하며, 자격 증명 별칭이 검사 hooks를 우회하지 못하도록 합니다(#51650, #52661, #53506). 스레드를 전환한 후 /side를 사용하면 기존 보조 대화로 돌아가며, 대기 중인 프롬프트에 대한 답변은 해당 프롬프트를 보낸 스레드로 전달됩니다(#52184, #53436). Windows에서는 Ctrl+V와 Shift+Insert로 이미지뿐 아니라 텍스트도 붙여넣을 수 있습니다. WSL에서는 반복해서 붙여넣을 때 클립보드 리더를 재사용하며, 복사 시도가 멈춘 채로 남지 않고 시간 초과로 종료됩니다(#53224, #52967, #53453). 자식 프로세스가 출력 파이프를 열어 둔 경우에도 로컬 명령이 신속히 종료되고, 원격 명령은 늦게 도착한 출력을 마지막 폴링에서 받을 수 있도록 보관합니다. 또한 codex exec는 관련 없는 명령을 실행한 뒤 파일 diff를 다시 표시하지 않습니다(#52652, #53331, #53622, #53444).¹⁹²

패치된 zsh가 제거되었습니다. Codex는 표준 셸 실행기를 사용하며, 더 이상 패치된 zsh를 번들로 제공하지 않습니다. codex-execve-wrapper와 shell-escalation 크레이트도 함께 제거되었습니다. shell_zsh_fork와 unified_exec_zsh_fork는 마이그레이션 안내와 함께 무시되며, 관리형 요구 사항에서 이 이름을 계속 사용하면 경고가 표시됩니다(#52160, #52213). 배포 바이너리에서 심볼을 제거해 Linux와 macOS 패키지 크기가 줄었습니다(#52178). Linux 샌드박스 크레이트의 이름과 README는 이제 샌드박스가 기존에 수행하던 역할을 명확히 설명합니다. 파일시스템과 네임스페이스 격리에는 bubblewrap을, 시스템 호출 필터링에는 seccomp를 사용하며, Landlock 구현은 레거시로 유지합니다. 실제 제한 적용 방식은 바뀌지 않았습니다(#52610). 번들로 제공되는 OpenAI Docs 안내에는 GPT-6 제품군으로의 마이그레이션이 포함됩니다(#51768).¹⁹²¹⁹³

권장 조치: 업그레이드하세요. config.toml이나 requirements.toml에 shell_zsh_fork 또는 unified_exec_zsh_fork가 있으면 제거하세요. Daybreak를 수동으로 활성화했다면 해당 플래그는 더 이상 필요하지 않습니다. /voice를 음소거할 때 Ctrl+X를 사용했다면, 이제 F9를 사용하세요.¹⁹²

v0.162.1 (2026년 10월 9일)

v0.162.0에 커밋 3개를 추가해 문제 2개를 수정했습니다. 여러 줄로 된 비동기 질문에서 TUI가 비정상 종료되던 문제를 수정했으며, 줄바꿈과 하이퍼링크의 전체 대상 주소도 보존됩니다. 실행 중인 백그라운드 서버의 기능 설정과 CLI의 기본값이 달라 일부 v0.162.0 사용자에게 발생하던 시작 실패도 해결되었습니다. 호환성 검사는 이제 명령줄에서 명시적으로 지정한 기능 재정의에만 적용됩니다. 기본값, 설정 키, 모델은 변경되지 않습니다.

권장 조치: 업그레이드하세요. 특히 이전 버전의 백그라운드 서버가 실행 중일 때 v0.162.0이 시작되지 않았다면 업그레이드를 권장합니다.¹⁸⁸

v0.162.0 (2026년 10월 8일)

instant_interrupt가 기본적으로 활성화됩니다. v0.159.0에서 선택적으로 활성화할 수 있었던 이 플래그는 새 입력으로 모델 응답을 중단하거나 오래 실행 중인 code-mode 호출이 제어권을 넘기도록 합니다. 이번 릴리스부터 모든 사용자에게 활성화됩니다(PR #51812, 10월 7일 병합). 상태는 여전히 개발 중으로 표시됩니다. 입력한 내용이 응답 종료까지 대기하던 기존 동작으로 되돌리려면 [features] 아래에 instant_interrupt = false를 설정하세요.

TUI의 새로운 기능: worktrees 기능이 활성화되어 있으면 신뢰할 수 있는 로컬 프로젝트에서 관리형 Git worktrees를 생성하고 나열하는 도구를 사용할 수 있어, 모델이 직접 worktree를 열 수 있습니다(#50148). 에이전트 Command Center에서 p로 작업을 고정할 수 있으며, 서버가 지원하는 경우 고정된 작업은 공유 Pinned 그룹에 유지됩니다(#51500). /copy로 대화 기록 블록 사이를 이동하고, Ctrl+Insert로 선택 영역을 복사하며, tui.mouse_scroll_speed(유한한 양수, 기본값 1.0)로 마우스 휠 스크롤 속도를 조정할 수 있습니다(#50434, #50215, #50209). 승인 헤더, 질문, MCP 프롬프트, 경고, 배너의 URL은 줄바꿈된 링크까지 클릭할 수 있습니다. 새 TUI 스레드는 실행 시 명시적으로 지정한 재정의 설정을 유지하면서 서버의 모델 및 추론 요약 기본값을 따릅니다. codex doctor는 설정된 TUI 모드를 보고하며, 계정을 업데이트한 후에도 /status에 계정 이메일이 다시 표시됩니다.

제공업체와 모델: Responses 호환 사용자 지정 제공업체는 [model_providers.<name>.capabilities] 아래에 external_web_access와 remote_compaction을 선언할 수 있습니다(#50459). ultrafast_mode 기능이 활성화된 상태로 출시되므로, Ultra Fast 등급을 명시한 모델 카탈로그(Amazon Bedrock의 Astra 모델, #50472)는 Fast 모드와 독립적으로 해당 등급을 제공할 수 있습니다. 이 태그에 번들로 포함된 카탈로그에는 해당 등급이 없습니다. Code mode에는 Promise 결과를 스트리밍하는 JavaScript 헬퍼와 선택적으로 활성화하는 순위 기반 도구 검색(code_mode_tool_search)이 추가됩니다. apply_patch는 기존 CRLF 줄바꿈을 항상 보존하며, apply_patch_preserve_line_endings 플래그는 제거됩니다. 재시도 가능한 Responses 및 WebSocket 실패는 서버의 Retry-After 지침을 따릅니다.

샌드박스와 플랫폼: 접근이 거부된 파일이 여러 개일 때 Linux 샌드박스가 시작되지 않던 문제를 수정했습니다. 쓰기 가능한 샌드박스 구성용 실행 파일은 거부되며, ripgrep 설정으로 deny-glob 마스크를 약화할 수 없게 되었습니다. Windows 10에서는 일반적인 드라이브 문자 경로를 통한 파일 접근이 복구되었습니다. 샌드박스 임시 디렉터리 권한은 자식 프로세스와 일치하도록 조정되었으며, PowerShell 7 모듈 경로에서도 아카이브 체크섬 검증이 작동합니다. Windows 릴리스에는 서명된 PowerShell 설치 프로그램이 포함됩니다.

권장 조치: 업그레이드하세요. 모델을 중단하지 않고 다음 입력을 미리 작성하던 방식이 필요하다면 instant_interrupt = false를 설정하세요.¹⁸⁷¹⁸⁹

v0.161.0 (2026년 10월 7일)

0.161.0-alpha.13.1에 릴리스 커밋 1개를 더한 버전으로, v0.160.1보다 커밋 155개가 추가되었습니다. 릴리스 노트에는 GPT-6.1 Sol이 새 기본 모델로 기재되어 있지만(#49318, #49339), 이는 v0.159.1에서 이미 배포한 카탈로그 변경 사항입니다. 이 태그에 번들로 포함된 models.json은 v0.160.1의 파일과 바이트 단위로 동일하므로, 0.159.1 이상을 사용하는 사용자에게는 변경 사항이 없습니다.

새로운 기능: /mcp login <name>으로 실행 중인 터미널 세션에서 MCP 서버에 로그인할 수 있습니다(#49290). 음성 장치 선택: /voice 대화에 사용할 마이크, 스피커, 마이크 입력 채널을 선택할 수 있으며, 환경설정은 로컬에 저장됩니다(#49437, #49836). API 키를 통한 모델 검색이 기본적으로 활성화됩니다(api_key_model_discovery, 안정 상태로 승격, #49807). 이 기능을 지원하는 엔드포인트에 OpenAI API 키로 로그인하면 Codex는 번들 목록에만 의존하지 않고 API에서 모델 카탈로그를 갱신합니다. [features] 아래에 api_key_model_discovery = false를 설정하면 비활성화되며, 변경 사항은 새 세션에서 적용됩니다. Amazon Bedrock은 호환 모델에서 multi-agent V2와 Ultra 추론을 지원하며, Bedrock Mantle은 AWS GovCloud 리전을 지원합니다(#49345, #49813). Daybreak(선택적 활성화). 개발 중이며 기본적으로 꺼져 있는 새 cli_daybreak 플래그는 CLI에 Daybreak 제어 기능을 추가합니다. 계정과 모델 카탈로그에서 지원을 명시한 OpenAI 제공자의 ChatGPT 로그인에 대해 /daybreak 전환, 표시기, 자동 Cyber 액세스 프로그램 라우팅을 제공합니다. --enable cli_daybreak를 사용하거나 [features] 아래에 cli_daybreak = true를 설정하면 활성화됩니다. daybreak = true 기본 설정만 저장해서는 아무 효과가 없습니다. 이와 별개로 codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red>(및 TypeScript SDK의 cyberAccessProgram)는 플래그 활성화 여부와 관계없이 한 턴에 사용할 Cyber 액세스 프로그램을 요청하며, 저장된 선택은 변경하지 않습니다(#49856~#49861, #49939, #51207). 번들 카탈로그에는 숨겨진 gpt-daybreak-blue-latest 및 gpt-daybreak-red-latest 항목이 이미 포함되어 있습니다. v0.163.0부터는 기본적으로 활성화되며 안정 기능으로 표시됩니다.¹⁹³

수정 사항: 승인된 파일 시스템 권한 상승은 읽기 거부와 네트워크 제한을 유지하면서 더 넓은 쓰기 권한을 부여할 수 있으며, 백그라운드 작업은 해당 작업이 시작된 턴의 권한을 유지합니다. 명시적으로 지정한 실행 권한은 터미널에 다시 연결한 뒤에도 유지됩니다. 관리자 권한의 Windows 터미널 세션은 내장 서버로 시작할 수 있습니다. 붙여넣기 감지 시간이 만료된 뒤 Enter를 누르면 버퍼에 쌓인 입력이 제출되며, Vim 삽입 모드에서도 동일하게 작동합니다. 스레드를 재개할 때 가장 최근에 확정된 기록이 포함되며, 시작 시 복구 가능한 SQLite 손상을 더 일찍 감지하고 손상된 데이터베이스를 백업으로 보관합니다. Responses 재시도와 WebSocket에서 HTTP로의 대체 연결은 서버의 재시도 지침을 따릅니다. 인증 문서에는 이제 자격 증명이 항상 auth.json에 저장되는 것은 아니며 키링에 저장될 수도 있다고 명시되어 있습니다.

권장 조치: 업그레이드하세요. API 키로 로그인하는 경우를 제외하면 체감할 만한 기본값 변경은 없습니다. 해당 키로 로그인한다면 /model에서 검색된 카탈로그를 확인하세요.¹⁸⁶¹⁸⁹

v0.160.1 (2026년 10월 5일)

Windows의 원격 MCP 서버 관련 수정. macOS 또는 Linux 호스트의 Codex가 원격 Windows 실행기에서 stdio MCP 서버를 실행하고 해당 서버 설정에 원격 환경 변수가 명시되어 있으면, Codex는 이제 SYSTEMROOT, TEMP, TMP도 함께 전달합니다. 따라서 Windows 프로세스는 시작에 필요한 환경을 유지할 수 있습니다. 비밀 정보를 포함하여 요청하지 않은 변수는 계속 제외됩니다. 이번 릴리스는 v0.160.0에 백포트 하나를 적용한 것으로, 기본값, 설정 키, 모델은 변경하지 않습니다.

권장 조치: Unix 호스트에서 Windows 실행기의 원격 stdio MCP 서버를 실행한다면 업그레이드하세요.¹⁸³

v0.160.0 (2026년 10월 1일)

0.160.0-alpha.6.1에 백포트 하나를 더해 만든 0.160 계열의 안정 릴리스입니다. 기본값 변경은 없습니다. 해당 태그의 번들 모델 카탈로그는 v0.159.1 및 v0.159.2와 바이트 단위로 동일하므로, GPT-6.1 Sol이 기본 모델로 유지되며 새 기능 플래그 2개는 꺼진 상태로 제공됩니다. 백포트(#49763)는 v0.159.1 이전에 분기되어 동결된 0.160 후보 버전에 0.159 유지보수 계열의 변경 사항을 반영했습니다. 여기에는 GPT-6.1 Sol 번들 및 Amazon Bedrock 카탈로그와 v0.159.3의 계정 보안 알림이 포함됩니다. 이 백포트가 없었다면 0.160은 GPT-6.1 Sol 없이 출시되었을 것입니다.

선택적으로 활성화할 수 있는 Guardian 추가 기능(둘 다 개발 중이며 기본적으로 꺼져 있음):

• Guardian이 이전 사용자 메시지를 읽을 수 있습니다. [features] 아래에 guardian_conversation_history_tools = true를 설정하세요. Apps가 활성화되어 있으면 검토자는 상위 세션 자체의 Apps 연결을 통해 user_message.search_messages와 user_message.read_messages를 사용할 수 있습니다. 이를 통해 상태 변경을 수반하는 작업을 승인하기 전에 이전 지시, 제한 사항, 철회된 권한을 확인할 수 있습니다. 호출할 때마다 상위 세션의 현재 앱 및 도구 정책을 다시 확인합니다. 응답은 기본적으로 추정 토큰 수 4,000개로 제한되며(auto_review.conversation_history_max_output_tokens), auto_review.experimental_conversation_history_prompt는 내장 검색 지침을 대체합니다.
• 작업 인계를 반영하는 루트 컨텍스트(guardian_root_handoff_context): Guardian이 작업자 에이전트의 동작을 검토할 때, 해당 작업자 또는 그 상위 에이전트에 작업이 인계될 때마다 인계 직전의 루트 메시지 3개와 가장 최근 루트 메시지 3개를 선택합니다. 따라서 최근의 취소 지시도 계속 확인할 수 있습니다.

항상 적용되는 변경 사항: 암호화된 에이전트 메시지가 이제 누락되지 않고 Guardian 기록에 순서대로 표시됩니다.

TUI 변경 사항: 프로젝트 설정도 저장된 신뢰 결정도 없는 폴더에서는 새 세션이 workspace-write 권한과 세분화된 승인 설정으로 시작할 수 있습니다. 단, 로컬 실행 환경, 사용자 설정, 관리 정책이 모두 이를 허용해야 합니다. 재개한 세션은 사용자가 재정의하지 않는 한 저장된 권한을 복원하며, /cd는 “현재 디렉터리 유지” 옵션과 함께 폴더 신뢰 여부를 물을 수 있습니다. 에이전트 명령 센터에는 이전 작업을 한 번에 10개씩 불러오는 “더 보기” 행이 추가됩니다. 로컬 Linux X11 터미널(Wayland, SSH, tmux, WSL, VS Code 제외)에서는 전체 화면 기록에서 선택한 텍스트가 기본 선택 영역에 복사되고, 마우스 가운데 버튼을 클릭하면 입력창에 붙여넣습니다. 전체 화면 상태 줄에는 공간이 충분할 때 Plan mode (shift+tab to cycle)이 표시됩니다. Pro 등급은 이제 /status와 분석에서 “Pro 100”, “Pro 200”, “Pro 500”으로 표시됩니다. 시작 팁은 요금제나 Fast 모드 홍보 대신 사용 중인 플랫폼의 데스크톱 앱을 안내하며, 대기열에 있지만 아직 전송되지 않은 메시지는 재연결 후 중복 없이 전송을 재개합니다.

제공자 및 연결: TUI는 앱 서버의 제공자, 추론 요약, 응답 상세도 설정을 유지하고, 재개 및 분기 기록에 올바른 세션을 표시하며, 서버 연결 시 /status에서 추론 요약 설정을 숨깁니다. 모델 카탈로그(model_catalog_url)를 명시한 제공자는 이제 해당 카탈로그만 사용합니다. 번들 모델은 병합되지 않으며, 메타데이터는 정확한 모델 ID에 맞춰 적용됩니다. 새로고침이 실패하면 캐시된 항목을 재사용하지 않고 삭제하며, 사용 가능한 모델 없이 시작하면 model이 설정되어 있지 않은 한 설정 오류를 보고합니다. 콘텐츠 필터가 응답을 중단하면 재시도 시 모델에 제한 사항을 설명하고, 허용되는 대안을 제시하며, 다른 작업을 계속하도록 지시합니다.

수정 사항: Windows 샌드박스의 PowerShell 대체 실행, 긴 런타임 경로의 ACL 복구, 백그라운드 보조 프로세스에서 콘솔 창이 나타나는 문제를 수정했습니다. 하위 에이전트는 아직 시작 중인 환경을 유지합니다. SQLite는 더 이상 연결 설정 단계에서 멈추지 않으며, 시간 초과 대신 초기화 오류를 보고합니다. 로그 데이터베이스는 백그라운드에서 사용하지 않는 공간을 회수하며, 플러그인 로딩은 파싱된 매니페스트를 캐시하고 HTTP 연결을 재사용합니다. 제공자 문서에는 이제 requires_openai_auth 자격 증명이 cli_auth_credentials_store에서 선택한 백엔드를 사용하며, env_key는 API 키가 저장된 환경 변수의 이름을 지정한다고 명시되어 있습니다.

권장 조치: 업그레이드하세요. 사용자 지정 제공자에 model_catalog_url이 설정되어 있다면, 선택하는 모든 모델이 해당 카탈로그에 포함되어 있는지 확인하세요.¹⁸²

v0.159.3 (2026년 9월 30일)

선택적 계정 보안 알림. OpenAI 제공자에서 ChatGPT로 로그인한 로컬 TUI 세션에는 계정 보안 설정을 마치도록 안내하는 닫을 수 있는 배너가 표시될 수 있습니다. 배너에는 chatgpt.com을 여는 버튼이 있습니다. 표시 대상은 서버가 결정합니다. CLI는 턴을 차단하지 않고 백그라운드에서 알림을 가져오며, 상태를 알 수 없으면 아무것도 표시하지 않습니다. 원격 작업 공간과 FedRAMP 계정은 제외하며, 배너를 닫은 상태는 스레드가 바뀌거나 다시 연결해도 유지됩니다. 사용량 배너가 우선적으로 표시됩니다. 이번 릴리스의 유일한 변경 사항이며, v0.160.0에도 동일한 코드가 포함되어 있습니다.

권장 조치: 없습니다. 알림에 따른 조치는 선택 사항입니다.¹⁸⁴

v0.159.2 (2026년 9월 29일)

Windows에서 콘솔 창이 깜박이는 문제 수정. Windows의 Codex는 이제 백그라운드 프로세스를 시작할 때마다 콘솔 창을 열지 않습니다. 여기에는 셸 도구 명령, hooks, Git 및 npm 호출, 터미널 없이 실행되는 Amazon Bedrock 자격 증명 갱신, doctor 검사, 샌드박스 설정 갱신, 기존 Windows 샌드박스의 명령이 포함됩니다. 터미널이 필요한 명령은 여전히 해당 터미널의 콘솔을 상속합니다. 이번 릴리스는 main의 수정 사항 2개를 하나로 백포트한 것으로, v0.159.1 이후 약 3시간 30분 만에 배포되었습니다. 기본값, 설정 키, 모델은 변경하지 않으며, 새 실행 도우미는 macOS와 Linux에서 이전과 동일하게 작동합니다.

권장 조치: Windows에서 Codex가 작업하는 동안 콘솔 창이 깜박인다면 업그레이드하세요. 특히 백그라운드 서버가 설치되어 있다면 해당됩니다.¹⁸⁰

v0.159.1 (2026년 9월 29일)

GPT-6.1 Sol이 기본 모델이 됩니다. config.toml에 모델이 설정되어 있지 않으면 CLI는 이제 GPT-6-Astra 대신 GPT-6.1 Sol(gpt-6.1-sol)로 시작합니다. 또한 Amazon Bedrock Mantle 및 Runtime 카탈로그에서도 GPT-6.1 Sol이 GPT-6 Sol을 대신해 기본 모델이 됩니다. /model 선택기는 이를 “코딩과 일상 작업을 위한 최신 주력 모델”로 맨 위에 표시하고, 그 뒤로 GPT-6-Astra, GPT-6 Sol(이제 “이전 세대 주력 모델”), GPT-6 Luna, 이전 모델을 나열합니다. 저장된 선택은 마이그레이션되지 않습니다. 설정에 gpt-6-sol 또는 gpt-6-astra가 지정되어 있으면 해당 모델을 유지하며, 이전 GPT-5 모델을 선택한 사용자에게 표시되는 마이그레이션 안내도 여전히 GPT-6 Sol 또는 GPT-6 Luna를 제시합니다. OpenAI는 같은 날 문서에 이 모델을 추가했으며, 현재 복잡한 코딩과 에이전트 워크플로에 권장합니다. “복잡한 작업에서 Astra보다 낮은 비용으로 Astra에 가까운 성능을 제공합니다.” 입력 토큰 100만 개당 50크레딧이 부과되며(캐시된 입력 2.5크레딧, 출력 250크레딧), Plus의 메시지 한도 범위는 15~160개입니다. 카탈로그에는 GPT-6 Sol과 다른 점이 2가지 있습니다. 기본 서비스 티어가 없어 세션이 Fast 대신 Standard 속도로 시작하며, 기본 추론 강도는 medium 대신 low입니다. 출시 시 Plus, Pro, Business, Enterprise, Edu에 순차적으로 제공됩니다. Enterprise와 Edu에서는 관리자가 활성화할 때까지 비활성화 상태로 유지되며, Free와 Go는 출시 대상에 포함되지 않습니다.

권장 조치: 업그레이드한 다음 /status에서 모델을 확인하세요. 계정에 아직 GPT-6.1 Sol이 없다면 config.toml의 model이나 -m으로 사용 가능한 모델을 지정하세요.¹⁷⁸

v0.159.0 (2026년 9월 29일)

v0.158.0 출시 약 27시간 후, 0.159.0-alpha.13을 기반으로 출시되었습니다. 릴리스 노트에 나열된 항목 중 일부는 백포트를 통해 v0.158.0에서 먼저 제공되었습니다. Windows 콘솔 창 및 실행기 수정, Markdown 형식을 유지하는 복사, 환영 화면과 턴 도움말, 로그인 수정이 이에 해당합니다. 릴리스 노트에서 제거되었다고 설명한 tui.prompt_suggestions 설정은 안정 버전에 포함된 적이 없습니다.

이번 릴리스의 새로운 기능:

• instant_interrupt(선택적 활성화, 개발 중): 새 입력이 모델 응답에 끼어들거나 오래 실행 중인 코드 모드 호출이 제어권을 넘기도록 합니다. 사용해 보려면 [features] 아래에 instant_interrupt = true를 설정하세요. v0.162.0부터는 기본적으로 활성화됩니다.
• 경고 뷰어를 닫으면 이미 확인한 경고가 해제됩니다. 나중에 다시 볼 경고는 k를 눌러 유지하세요.
• 계획을 실행할지 결정하는 동안 대화 기록을 스크롤할 수 있습니다.
• Mermaid 렌더링이 더 다양한 순서도 연결선, 레이블, 노드 그룹을 처리합니다.
• 작업을 전환해도 빈 세션의 초안이 유지되며, 첫 번째 턴을 시작하기 전에도 스레드를 보관 처리할 수 있습니다.
• /status는 테두리 없이 표시되며 긴 값은 줄바꿈됩니다.
• App-server 클라이언트는 특정 항목을 기준으로 스레드 기록을 페이지 단위로 조회할 수 있습니다.

샌드박스 변경 사항: 승인된 명령에도 명시적인 파일시스템 접근 거부가 유지되고, 쓰기 가능한 루트 아래의 .aws 디렉터리는 기본적으로 보호됩니다(명시적인 규칙이 있으면 해당 규칙이 우선합니다). 네트워크가 활성화된 macOS 샌드박스에서는 TLS 신뢰 평가가 허용되며, 프록시가 필요한 실행 환경에는 이제 프록시가 제공됩니다. 기본 제공되던 plugin-creator skill은 제거되었습니다.

권장 조치: 샌드박스에서 실행되는 작업이 .aws 아래에 파일을 쓴다면, 명시적인 규칙을 추가하지 않는 한 차단됩니다.¹⁷⁷

v0.158.0 (2026년 9월 28일)

0.158 계열의 안정 릴리스로, 0.158.0-alpha.15.4를 기반으로 합니다. alpha.15에 v0.157.1의 Windows 수정 4개를 포함한 백포트 16개가 추가되었습니다. v0.157.0 이후 커밋 207개가 반영되었습니다.

변경되는 기본 동작:

• 터미널 입력 승인이 활성화됩니다. Codex가 높은 권한으로 실행 중인 명령에 입력을 보낼 때는 먼저 승인을 받아야 합니다. 추가 권한이 부여되었거나, 샌드박스를 우회하거나, 명령 시작 이후 정책이 변경된 경우가 이에 해당합니다. 플러그인이 메트릭에 사용하는 권한처럼 런타임에만 적용되는 권한 부여는 더 이상 검토를 유발하지 않습니다. 이 기능을 끄려면 [features] 아래에 write_stdin_approval = false를 설정하세요.
• 전체 화면 대화 기록에서 선택 시 복사: 마우스로 텍스트를 선택한 뒤 버튼을 놓으면 복사됩니다. 기본값인 auto에서는 자체 복사 단축키를 전달하는 터미널(Ghostty 1.2+, macOS의 Kitty, Windows Terminal, Windows의 VS Code)을 직접 사용할 경우 이 동작을 건너뜁니다. 복사 시 Markdown 형식이 유지됩니다. [tui] 아래에 copy_on_select = "never"(또는 "always")를 설정하세요.
• Windows, WSL, Linux의 전체 화면 TUI에서 마우스 오른쪽 버튼으로 붙여넣기를 지원합니다. [tui] 아래에 right_click_paste = "off"를 설정하거나, macOS에서도 사용하려면 "on"으로 설정하세요.
• Guardian 스레드 컨텍스트가 항상 활성화됩니다. v0.157.0에서 제공한 비활성화 옵션은 제거되었습니다. [features.guardianv2] 아래의 thread_context는 프로필에 설정된 경우를 포함해 무시되며, Codex는 해당 설정을 제거하라는 안내를 표시합니다.

모델 및 요금제: GPT-5.4가 기본 제공 카탈로그와 Bedrock 카탈로그에서 제거되며, 저장된 GPT-5.4 선택 항목에는 계속 GPT-6 Sol로 전환하라는 안내가 표시됩니다. Codex는 Pro Max 요금제를 인식하며 Pro 티어를 “Pro”, “Pro (More)”, “Pro (Max)”로 표시합니다. 추론 강도 단축키로 Max까지 선택할 수 있습니다.

추가된 기능: 사전 등록된 OAuth 클라이언트 시크릿이 필요한 MCP 서버(codex mcp add --oauth-client-secret), exec-server WebSocket 연결용 bearer 토큰, 생성 이미지의 투명 배경, /ps의 여러 줄 명령 미리보기를 지원합니다. 수정 사항에는 Windows 샌드박스 오류(일반적인 Windows 10 경로, 저장된 자격 증명 거부, 대규모 권한 정책), 쓰기 가능한 루트가 중첩된 환경에서의 Linux 샌드박스 시작, 쓰기 가능한 여러 루트에 걸친 Git 메타데이터 보호, 패치 승인 시 macOS 경로 별칭 처리가 포함됩니다. 또한 Guardian은 검토 도중 사용자가 메시지를 보내도 검토를 중단하지 않고 재시도합니다.

권장 조치: 자동화가 높은 권한으로 실행되는 명령에 키 입력을 보낸다면 승인 요청이 표시될 수 있으므로 이에 대비하거나 해당 기능을 끄세요. 설정에서 thread_context도 제거하세요.¹⁷⁶

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가지를 추가로 변경한 릴리스입니다.

• 전체 화면 대화 기록이 기본적으로 활성화됩니다. v0.156.0에서 /tui를 통해 제공하던 전체 화면 UI가 이제 세션의 기본 시작 화면입니다. 설정에 [tui] 섹션이 없어도 적용됩니다. 터미널 스크롤백을 유지하려면 /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 카탈로그에도 두 모델이 추가되며, GPT-6 Sol이 GPT-5.6 Sol을 대신해 Bedrock의 기본 모델이 됩니다. GPT-5.6 Sol에서는 ultrafast 서비스 티어가 제거되어 Fast만 남습니다. 기본 제공 카탈로그는 더 이상 GPT-6-Astra를 실험적 컨텍스트 관리 지원 모델로 표시하지 않습니다(컨텍스트 관리 참조).

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

v0.156.1 (2026년 9월 23일)

안정 버전 CLI에 GPT-6 Sol과 GPT-6 Luna를 추가하는 단일 변경 패치입니다. 이제 두 모델은 /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 로그인으로 사용할 경우 Fast 모드에서는 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 세션을 기존 로컬 데몬에 연결할 수 있으며, 에이전트 개요 화면에서 생성할 수도 있습니다.
• Guardian의 상위 스레드 압축 결과 재사용이 기본으로 활성화됩니다: Guardian이 검토 세션을 다시 시작할 때 상위 스레드의 암호화된 압축 결과를 재사용할 수 있습니다.

각 기능을 끄는 방법은 slash commands 표의 /voice, /worktree 행과 Guardian 섹션에 나와 있습니다.

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

v0.155.1 (2026년 9월 18일)

문제 1건을 수정한 핫픽스입니다. 0.155.0에서는 설정에 model_reasoning_summary가 없는 새 로컬 TUI 스레드가 detailed 요약을 요청했으며, 추론 요약을 지원하지 않는 제공자는 요청 자체를 거부했습니다. 0.155.1은 대체 기본값을 none으로 복원하여 키를 설정하지 않으면 요약을 요청하지 않습니다. 명시적으로 지정한 auto, concise, detailed 설정은 이전에도 적용되었고 지금도 그대로 적용됩니다. 동일한 한 줄 수정이 main에도 반영되어 0.156.0에 포함되었습니다.

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

v0.155.0 (2026년 9월 17일)

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

0.155.0의 추가 변경 사항:

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

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

v0.154.0 (2026년 9월 9일)

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

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

새로운 기능:

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

보안: 워크스페이스 신뢰가 확인되기 전에는 PATH 보조 프로그램이 실행되지 않으며, 터미널 입력 주입을 막도록 macOS 샌드박스가 강화되었습니다. MCP 연결은 OAuth 토큰 갱신을 조율하고, 원격 재개와 분기는 저장된 권한을 유지하며, 다른 앱에서 열려 있는 대화를 재개하면 읽기 전용 대화 기록을 표시합니다. 음성 기능은 런타임 기반만 포함되었으며, 공개 문서 없이 Daybreak를 참조하는 코드가 처음 반영되었습니다.¹⁵²¹⁵³

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

GPT-6-Astra 출시를 CLI에 반영한 같은 날의 패치입니다. v0.153.3은 Amazon Bedrock 카탈로그에 Astra를 추가하고(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가 최상위 키를 대체합니다. 기존 키도 대체 설정으로 계속 사용할 수 있습니다.

수정 사항: app-server 연결이 끊겨도 TUI 세션이 초안을 유지한 채 다시 연결됩니다. Guardian 검토 이력은 압축, 재시작, 분기 후에도 유지되며, 저장된 MCP 승인은 선택한 계정에만 적용됩니다.¹⁴⁰

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

update_plan이 선택적으로 활성화하는 기능으로 바뀌었습니다: tools.update_plan.enabled의 기본값은 false이며, 비활성화된 동안에는 모델, 협업 모드, 멀티 에이전트, 압축, 사전 준비, 목표 지속 프롬프트에서 기본 제공 update_plan 지침이 제외됩니다(계획 모드 및 협업 참조). 이 밖에도 연산자와 조합할 수 있는 Vim의 /, ? 검색 및 n/N 이동, 새 초안 작성 시 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,000ms), 확장 기능은 MCP 도구 결과를 검사하거나 대체할 수 있습니다.

이번 수정으로 /cd가 샌드박스 제한을 약화시키는 문제와 권한 변경 후에도 오래된 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, 비동기 hooks 및 MCP을 호출하는 hooks, 접근이 거부되거나 읽을 수 없는 경로에서 접근을 차단하는 샌드박스 제한이 추가됩니다.¹¹⁶¹¹⁸

이전 릴리스 (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, 목표 모드 정식 출시, 선택적으로 활성화하는 잠금 상태의 Computer Use가 추가되었습니다.^{96979899100101196}

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

안정성 참고: 안정적이며 문서화된 기능은 핵심 CLI 및 TUI, 샌드박싱 및 승인 정책, config.toml, AGENTS.md, skills, hooks, 플러그인, 다중 에이전트 도구, 목표, 권한 프로필, /voice 및 관리형 worktrees(v0.156.0부터 기본 활성화), 전체 화면 대화 기록 및 백그라운드 서버 자동 시작(v0.157.0부터 기본 활성화), 터미널 입력 승인, 선택 시 복사, 마우스 오른쪽 버튼으로 붙여넣기(v0.158.0부터 기본 활성화), 즉시 중단(v0.162.0부터 기본 활성화되었으나 여전히 개발 중으로 표시), Daybreak 및 코드 모드 중단(cli_daybreak, code_mode_interrupt; v0.163.0부터 안정화 및 기본 활성화), Bedrock 설정 마법사, 도구 업데이트의 점진적 전달, MCP OAuth 갱신 조율(v0.164.0부터 안정화 및 기본 활성화)입니다. 관리형 worktrees와 실시간 대화는 v0.164.0부터 상시 활성화됩니다. 해당 플래그는 제거된 것으로 표시되지만 기능은 계속 켜져 있습니다. Browser, Computer Use, Appshots는 문서화된 사용자용 기능이며, 플랫폼과 요금제에 따라 사용 가능 여부가 달라집니다. 실험 단계이거나 개발 중인 기능은 Codex Cloud, 코드 모드 및 코드 모드 도구 검색, Memory v2, 로컬 에이전트 게시판, Guardian 기록 및 인계 컨텍스트 플래그(v0.160.0), 그리고 이 가이드에서 [EXPERIMENTAL]로 표시되거나 /experimental에 나열된 모든 기능입니다. 이러한 기능은 릴리스마다 바뀔 수 있습니다. 설정 레퍼런스에 따르면 실험적 컨텍스트 관리는 “현재 사용할 수 없습니다.” 제거된 항목은 --full-auto(v0.147.0), untrusted 승인 정책(v0.149.0), codex mcp-server(v0.154.0), Guardian thread_context 비활성화 옵션(v0.158.0), shell_zsh_fork 및 unified_exec_zsh_fork 플래그와 패치된 zsh 자체(v0.163.0), js_repl입니다.

알파 채널: 알파 빌드는 하루에도 여러 차례 배포되며, 알파 계열의 릴리스 본문에는 간략한 내용만 담깁니다. 이전 기반 버전에서 별도로 분기한 빌드도 정기적으로 등장합니다. npm alpha 태그가 이러한 빌드 중 하나를 가리킨 사례가 최소 2번 있었으며, 그 결과 @alpha로 설치하면 latest보다 오래된 빌드가 설치되었습니다. 0.158 계열은 0.158.0-alpha.2(9월 23일)에서 alpha.15(9월 25일)까지 이어졌습니다. 안정 버전인 v0.158.0(9월 28일)은 alpha.15에 백포트 16개를 더한 별도 빌드 0.158.0-alpha.15.4를 기반으로 만들어졌으며, 27시간 뒤 v0.159.0이 배포될 때까지 npm latest였습니다. 0.159 계열은 alpha.1(9월 25일)에서 alpha.13(9월 28일)까지 이어졌으며, alpha.13을 기반으로 v0.159.0이 출시되었습니다. 0.160 계열은 0.160.0-alpha.6(9월 29일)까지 진행된 뒤 멈췄습니다. 0.161.0-alpha.1은 alpha.6에서 버전 번호만 바꾼 것입니다. 9월 30일에는 alpha.6에 빠져 있던 v0.159.2의 Windows 콘솔 수정 1개를 추가한 0.160.0-alpha.6.1이 나왔습니다. 같은 날 0.159 계열에서는 패치 버전 v0.159.3이 추가로 출시되었습니다. 이후 0.160 계열에서는 alpha.6.1에 백포트 1개를 더한 안정 버전 v0.160.0(10월 1일)과 v0.160.1(10월 5일)이 출시되었습니다. 0.161 계열에서는 알파 빌드와 별도 백포트 빌드가 나왔고, 최신 버전은 0.161.0-alpha.13.1(10월 6일)이지만 안정 버전은 없었습니다. 더 높은 버전의 안정 릴리스가 아직 나오지 않았으므로 건너뛴 버전으로 보지는 않습니다. 현재 alpha는 0.162.0-alpha.16을 가리킵니다. 알파 버전을 사용한다면 npm view @openai/codex dist-tags를 확인하고 @alpha 대신 정확한 버전을 지정해 설치하세요.^176179181185 최근 알파 계열이 안정 릴리스로 이어진 과정의 날짜별 기록은 ¹⁷³에 있습니다. 0.161 계열은 10월 7일에 0.161.0-alpha.13.1에 릴리스 커밋 1개를 더한 v0.161.0으로 출시되었습니다. 이어 10월 8일에는 0.162.0-alpha.18.1을 기반으로 v0.162.0이 출시되었으며, 0.162.0-alpha.20은 해당 안정 버전의 분기 시점보다 커밋 52개가 앞서 있었습니다. 10월 9일에는 커밋 3개가 추가된 v0.162.1이 나왔습니다. alpha는 10월 10일에 0.163.0-alpha.5였고, 10월 13일에는 alpha.8, alpha.9, alpha.10을 거쳐 10월 14일에는 0.163.0-alpha.11이 되었습니다. 0.163 계열은 10월 15일에 안정 버전으로 이어졌습니다. v0.163.0은 별도 빌드 0.163.0-alpha.10.2에 릴리스 커밋 1개를 더해 만들어졌으며, alpha.11은 해당 분기 시점보다 커밋 23개가 앞서 있었습니다. 0.164 계열은 10월 16일에 alpha.1과 alpha.2로 시작하여 10월 17일에는 0.164.0-alpha.3, 10월 22일에는 alpha.12까지 진행되었습니다. 그와 함께 별도 빌드인 0.163.0-alpha.11.1과 11.2(10월 21~22일), 0.164.0-alpha.11.1(10월 23일)도 나왔습니다. 0.164 계열은 10월 23일에 alpha.11에 릴리스 커밋 1개를 더한 안정 버전 v0.164.0으로 출시되었으며(alpha.12는 해당 분기 시점보다 커밋 9개가 앞서 있었습니다), 같은 날 alpha는 0.165.0-alpha.1로 바뀌었습니다.^{189190191193195}

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 / bubblewrap / 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월 29일 현재 세대는 GPT-6입니다. 복잡한 코딩과 에이전트 작업에는 gpt-6.1-sol을 사용하며, 이 모델은 v0.159.1부터 별도의 모델을 설정하지 않았을 때 번들로 제공되는 CLI의 기본값입니다. 가장 까다로운 엔드 투 엔드 작업에는 gpt-6-astra, 범위가 명확하고 작업량이 많은 경우에는 gpt-6-luna를 사용하며, 이전 세대인 gpt-6-sol도 제공됩니다. 출시 전환 기간에는 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 지원이 종료되었습니다.^{83117146148149171178} 이 레이어는 파일을 읽고, 패치를 작성하고, 셸 명령을 실행하며, 코드베이스를 추론합니다. 컨텍스트가 가득 차면 Codex는 공간을 확보하기 위해 대화를 압축합니다. 이 레이어에서는 토큰을 소비합니다.

보안 레이어: Codex가 실행하는 모든 명령은 운영 체제 수준의 샌드박스를 통과합니다. macOS에서는 Apple의 Seatbelt 프레임워크가 커널 수준의 제한을 적용합니다. Linux에서는 bubblewrap이 파일 시스템과 네임스페이스를 격리하고 seccomp가 시스템 호출을 필터링하며, 이전 Landlock 구현은 레거시 방식으로 유지됩니다. 샌드박스는 컨테이너 내부가 아니라 커널 수준에서 작동합니다. 이후 approval policy가 사용자에게 확인을 요청할 시점을 결정합니다.

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

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

핵심 인사이트: 대부분의 사용자는 한 가지 작업 환경만 사용합니다. 고급 사용자는 5가지를 모두 활용합니다. 장시간 실행되는 작업에는 Cloud, 결정론적인 저장소 작업에는 CLI, 긴밀한 코딩 루프에는 IDE 확장 프로그램, 계획과 조율에는 데스크톱 앱, 로그인된 브라우저 워크플로에는 브라우저 확장 프로그램을 사용합니다.

목차

1. Codex를 어떻게 설치합니까?
2. 빠른 시작: 첫 세션
3. 핵심 상호작용 작업 환경
4. 설정 시스템 심층 분석
5. 어떤 모델을 선택해야 합니까?
6. Codex의 비용은 얼마입니까?
7. 의사 결정 프레임워크
8. 샌드박스와 승인 시스템은 어떻게 작동합니까?
9. AGENTS.md는 어떻게 작동합니까?
10. Hooks
11. MCP(Model Context Protocol)이란 무엇입니까?
12. Code Mode
13. JavaScript REPL 런타임
14. Skills란 무엇입니까?
15. Plugins
16. Plan Mode와 협업
17. 메모리 시스템
18. 세션 관리
19. 비대화형 모드(codex exec)
20. Codex Cloud와 백그라운드 작업
21. Codex 데스크톱 앱
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.164.0
npm view @openai/codex version           # Latest published version

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

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

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

새 릴리스에서 문제가 발생하면 버전을 고정하는 편이 좋습니다. Codex는 안정 버전도 빠르게 출시되므로 특정 버전을 지정해 설치하는 것이 가장 빠른 롤백 방법입니다. 이슈를 등록하고 버전을 고정한 뒤 작업을 계속하세요. 롤백이 적용되었는지는 codex --version으로 확인하세요. PATH에서 다른 설치본이 우선하면 이전 바이너리가 계속 실행되어도 이를 알아채기 어렵습니다. codex doctor는 바로 이 문제를 환경 항목에서 표시합니다.

패키지를 제거해도 사용자 상태는 삭제되지 않습니다. 인증 정보, 설정, 세션 기록은 ~/.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 (bubblewrap + 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(OS 키체인), auto(사용 가능하면 keyring, 그렇지 않으면 파일)입니다.

Amazon Bedrock 로그인 (v0.145.0, 실험적 기능): Amazon Bedrock을 통해 모델에 접근하는 팀은 기존의 관리형 API 키 인증(v0.140.0+) 및 AWS 자격 증명 체인(사용자 지정 모델 제공자 참조) 외에도 사용자 지정 엔드포인트와 인증을 지원하는 실험적 로그인 경로를 사용할 수 있습니다. 기본 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 세션 재인증도 여기에 포함됩니다. 이 기능은 스레드, 턴, 제공자, 사용자에게 표시할 메시지를 담은 안정화된 app-server 알림인 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.164.0

빠른 시작: 첫 세션

5분이면 설치부터 실제 작업까지 시작할 수 있습니다.

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

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

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

cd ~/my-project                  # Any git repo works

3. Codex를 시작하세요:

codex

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

4. 질문하세요:

> What does this project do? Summarize the architecture.

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

5. 변경을 요청하세요:

> Add input validation to the login endpoint

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

6. slash commands를 사용하세요:

> /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 모니터링, 알림 대응)
• Appshots: 맨 앞에 있는 Mac 앱 창의 스크린샷과 추출 가능한 텍스트를 스레드에 첨부합니다
• 앱 내 브라우저 댓글: 로컬 또는 공개 페이지를 미리 보고, 요소나 영역에 댓글을 남겨 Codex가 구체적인 시각적 피드백을 반영하도록 합니다
• Computer Use: Codex가 허용된 Mac 앱을 조작해 지정된 범위의 GUI 작업을 수행하도록 합니다. 지원 대상인 원격 Mac Computer Use 턴에서는 잠금 상태 사용을 선택적으로 활성화할 수 있습니다

GPT-Live 기반 ChatGPT Voice(데스크톱 26.715, 2026년 7월 23일): 이제 음성으로 데스크톱 앱을 조작할 수 있습니다. 타이핑하지 않고 말로 작업 내용을 논의하고 Chat, Work, Codex에 걸쳐 작업을 조율할 수 있습니다. macOS에서 화면 컨텍스트를 켜면 맨 앞에 있는 창의 appshot이 대화에 공유되므로, 보고 있는 내용을 일일이 설명하지 않고 바로 질문할 수 있습니다. 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 [EXPERIMENTAL]

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

• 실행을 맡기고 다른 작업 진행: 로컬 컴퓨터와 독립적으로 실행되는 작업을 대기열에 추가합니다
• 병렬 실행: 여러 클라우드 작업을 동시에 실행합니다
• PR 생성: Codex가 완료한 작업으로 풀 리퀘스트를 생성합니다
• 로컬 적용: codex apply <TASK_ID>로 클라우드 결과를 로컬 저장소에 가져옵니다

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

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

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

Codex는 Google Chrome, Microsoft Edge, Brave, Opera, Vivaldi용 브라우저 확장 프로그램으로도 제공됩니다. CLI, 데스크톱 앱, IDE 확장 프로그램, 클라우드에 이은 5번째 인터페이스입니다. 확장 프로그램은 2026년 5월 Chrome용으로 출시되었으며, 2026년 8월 25일 변경 기록에서 나머지 4개 브라우저에 대한 지원이 추가되었습니다. ChatGPT 데스크톱 앱의 설정 > Computer Use에서 설정할 수 있습니다. 5개 브라우저 모두 탭 멘션과 브라우저 제어를 지원합니다. Opera는 사이드 채팅을 지원하지 않으므로 데스크톱 앱에서 작업을 시작하세요. 확장 프로그램은 평소의 브라우징을 대신하는 것이 아니라 함께 진행하도록 설계되었습니다. Codex는 백그라운드에서 여러 탭을 병렬로 처리하며, 사용자는 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 또는 여러 계정을 사용하는 환경에 유용합니다.

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

전체 설정 레퍼런스

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
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"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

# ─── 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)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (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)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

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

# ─── Guardian Auto-Review (v0.160.0 history keys) ─────
[auto_review]
conversation_history_max_output_tokens = 4000   # Per history-tool response, estimated tokens (default 4,000)
experimental_conversation_history_prompt = ""   # Blank = built-in retrieval instructions

# ─── 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.1-sol"
# GPT-6.1 Sol starts at Standard speed; /fast toggles Fast (2.5x credits)
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"

env_key는 제공자의 API 키를 보관하는 환경 변수의 이름을 지정합니다. 키 자체는 절대 config.toml에 넣지 않습니다. requires_openai_auth = true를 지정한 제공자는 처음 실행할 때 로그인 화면을 표시하며, 자격 증명을 반드시 auth.json에 저장하는 것이 아니라 cli_auth_credentials_store에서 선택한 백엔드(file, keyring 또는 auto)에 저장합니다. v0.160.0부터 model_catalog_url을 설정한 제공자에는 해당 카탈로그의 모델만 제공되며 기본 제공 모델은 병합되지 않습니다. 카탈로그 새로 고침에 실패하면 오래된 캐시 항목을 재사용하지 않고 삭제합니다.¹⁸² v0.162.0부터 사용자 지정 Responses 호환 제공자는 [model_providers.<name>.capabilities] 아래에 지원 기능을 선언할 수도 있습니다. external_web_access = false는 해당 제공자의 호스팅된 웹 검색이 실제 웹에 접근하지 못하게 하며, remote_compaction = "v2"는 해당 제공자가 Responses compaction_trigger 프로토콜을 사용하도록 설정합니다. 이 프로토콜은 그 외에는 OpenAI 및 Azure Responses 제공자에만 적용됩니다("unsupported"를 지정하면 압축이 로컬에서 수행됨).¹⁸⁷

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

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

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

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

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

인라인 설정 재정의

명령줄에서 모든 설정값을 재정의할 수 있습니다.

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

어떤 모델을 선택해야 합니까?

사용 가능한 모델(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일부터 사용할 수 있었습니다. 컨텍스트 창은 Codex에서 400K, API에서 1M입니다. Codex는 구독자 티어 전반의 처리량과 비용 간 균형을 맞추기 위해 컨텍스트 창을 400K로 제한하지만, API에서는 전체 1M을 제공합니다. 가격(API): MTok당 입력 $5 / 출력 $30(GPT-5.4 요율의 2배이며, OpenAI는 토큰 효율 개선 후 실질 인상률이 약 20%라고 설명합니다). 벤치마크: Terminal-Bench 2.0 82.7%(공개 모델 중 당시 최고 수준), 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일 지원이 종료됩니다. 모델 문서에서는 지원 종료 범위를 모든 플랜의 ChatGPT, ChatGPT Work, Codex로 한정하며(소비자, Business, Enterprise, Edu 포함), OpenAI API에는 적용되지 않는다고 설명합니다.¹⁵⁵ GPT-6 출시와 함께 대체 모델 안내도 변경되었습니다. Plus, Pro, Business, Enterprise, Edu에서는 gpt-6-sol을 선택하고, Free와 Go에서는 데스크톱 앱에서 gpt-6-luna를 선택하세요. 두 모델 모두 “사용 가능한 경우”에 해당합니다. 워크스페이스 기본값, 저장된 모델 설정, 관리형 구성, 사용자 지정 에이전트, 예약 작업, 스크립트에서 gpt-5.5를 교체하세요.¹⁷¹

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

지원 중단 참고 사항(2026년 3월 11일): GPT-5.1 모델은 더 이상 ChatGPT에서 사용할 수 없습니다. 기존 대화는 GPT-5.3 Instant, GPT-5.4 Thinking 또는 GPT-5.4 Pro에서 자동으로 계속됩니다. GPT-5.1-Codex-Mini는 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일): 컨텍스트 400K와 MTok당 $0.75/$4.50 요율을 제공하는 더 작고 빠른 GPT-5.4 변형으로, 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 모델 변형을 정식 지원하기 시작했으며, max 추론 수준도 지원합니다. Bedrock 공급자를 통해 모델을 사용하는 팀은 다른 사용자 지정 공급자 모델과 같은 방식으로 선택할 수 있습니다(사용자 지정 모델 공급자 참고). max 수준은 가장 어려운 추론 및 에이전트 작업을 대상으로 합니다.¹⁰⁶ v0.144.6(2026년 7월 18일)에서는 Sol, Terra, Luna의 번들 지침을 갱신하고 컨텍스트 창을 272,000토큰으로 수정했습니다.¹¹¹ v0.145.0(2026년 7월 21일)에서는 사용자 지정 엔드포인트와 인증을 지원하는 실험적 Bedrock 로그인을 추가하고, GPT-5.6 Sol을 Bedrock 기본 모델로 설정하며, 번들 GPT-5.4 모델 선택을 각각 대응하는 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 모델만 표시된다는 사례가 있었으며, 아래에 인용한 모델 문서의 사용 가능 여부 문구도 변경되지 않았으므로 해당 문구가 여전히 유효한 공식 설명입니다.¹⁴⁹ 공식 문서는 공개되어 있습니다. API 모델 페이지에서는 gpt-6-astra를 플래그십으로 소개하며 “가장 어려운 엔드 투 엔드 작업을 위해 구축된 가장 강력한 모델”이라고 설명합니다. 표준 단기 컨텍스트 요율은 MTok당 입력 $10, 출력 $50이며, 컨텍스트 창은 1.05M토큰, 최대 입력은 922,000토큰, 최대 출력은 128K, 지식 기준일은 2026년 4월 30일입니다. 장기 컨텍스트 티어도 문서화되어 있습니다. 입력 토큰이 272K를 넘는 프롬프트에는 전체 요청에 대해 입력 2배, 출력 1.5배의 가격이 적용되며, 가격 페이지 기준 MTok당 입력 $20, 출력 $75입니다. 이는 GPT-5.6 Terra(균형형)와 Luna(저가형)보다 높은 수준입니다. Codex 문서에서는 Astra를 권장 Codex 모델로 소개하면서 사용 가능 여부가 “배포 상황, 로그인 방식, 클라이언트에 따라 달라진다”고 설명하고, 대상 계정으로 Pro, Business($100), Enterprise를 명시합니다. Astra의 문서화된 Codex 추론 단계는 Low, Medium, High, Extra High, Max, Ultra입니다. 문서의 모델 페이지에서는 Medium을 기본값으로 표시하지만, v0.153.4 번들 카탈로그의 default_reasoning_level은 low로 설정되어 있으므로 실제 기본값은 사용하는 환경에 따라 달라진다고 보고 세션에서 /status로 확인하세요. 9월 15일 재확인 시에도 추론 단계는 동일했으며, 단계별 선택기 설명이 추가되었습니다(Ultra의 원문: “자동 작업 위임을 포함한 최대 추론”). Max와 Ultra 단계에는 SDK 확인이 수반됩니다. Python SDK 0.154.0 릴리스(2026년 9월 10일)에서는 max와 ultra 추론 수준 값을 추가했습니다(#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부터 모델 선택기에 표시되고 모델을 명시적으로 설정하지 않았을 때의 번들 기본값으로 사용됩니다. 최소 CLI 버전은 문서화되지 않았으므로 이 버전들을 실질적인 최저 버전으로 간주하세요. 이 기본값 변경은 모든 환경이 아닌 번들 CLI 카탈로그에 관한 사실입니다. 다만 cloud의 격차는 이후 해소되었습니다. 9월 4일과 9월 7일 확인 당시에는 Astra를 Codex cloud에서 사용할 수 없는 것으로 표시했고 GPT-5.6 Sol은 사용할 수 있는 것으로 표시했지만, 9월 15일 재확인에서는 사용 가능 여부 표에 Astra도 Codex cloud에서 사용할 수 있는 것으로 표시되었습니다. 페이지에는 여전히 “현재 Codex cloud 채팅의 기본 모델은 변경할 수 없습니다.”라고 안내되어 있습니다. 배포 시 주의 사항: 이용 권한은 계정마다 다르며, CLI 0.153.4 이상에서는 배포 대상이 아닌 계정에도 아직 사용할 수 없는 모델이 번들 기본값으로 설정됩니다. 일관된 모델 선택이 필요하면 config.toml에서 모델을 고정하거나 -m을 전달하세요. v0.156.1부터 문서 자체의 예시에는 model = "gpt-6-sol"이 사용됩니다. 모델 페이지에 Fast 티어가 표시되지 않더라도 Astra의 Fast 모드 요금은 문서화되어 있습니다. Codex 속도 문서에서는 ChatGPT 로그인 시 Fast 모드가 Standard의 2.5배 크레딧을 사용한다고 설명하며(“사용 가능한 경우”), API 가격 페이지에서는 Fast 모드 요율을 해당 Standard 요율의 정확히 2배로 제시합니다(단기 컨텍스트 MTok당 $20/$100, 장기 컨텍스트 $40/$150). v0.153.2 카탈로그 문구의 “2배 속도” 부분은 카탈로그 표시 문구일 뿐이며, 속도 페이지에는 Astra의 속도 배수가 명시되어 있지 않습니다.^145146147148 2026년 9월 23일 일부 대체됨: 모델 문서에서는 더 이상 Astra를 권장 Codex 모델로 설명하지 않습니다. “권장 모델” 섹션은 이제 GPT-6 Sol과 Luna를 우선 소개하고, Astra는 “가장 어려운 엔드 투 엔드 작업”에 한정하며, Codex cloud에서는 사용할 수 없는 것으로 표시합니다. Astra의 시작 추론 수준은 번들 카탈로그와 일치하는 Light(low)입니다. 모델을 설정하지 않은 경우 Astra는 여전히 번들 CLI 기본값입니다.¹⁷¹ 2026년 9월 29일 대체됨: v0.159.1에서는 GPT-6.1 Sol이 번들 기본값이 되고 Astra는 선택기의 두 번째로 이동했습니다. 모델 문서에서는 이제 복잡한 코딩에 GPT-6.1 Sol을 권장하면서 Astra는 가장 어려운 엔드 투 엔드 작업용으로 유지합니다. 문서의 설정 예시도 이제 gpt-6.1-sol을 사용합니다.¹⁷⁸

Astra의 Power 프리셋(2026년 9월 6일 이전 문서에 추가): Codex 모델 문서의 모델 선택기 설명에서는 이제 선택기의 Power 옵션을 GPT-6-Astra 추론 티어에 대응시킵니다. 이는 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 컨트롤을 보여 준다고 설명합니다. 위 모델 표와 함께 해석하면 “Power”는 GPT-5.6 Sol의 medium 추론을 의미했지만, 이용 권한이 있는 계정에서는 같은 프리셋 단계가 이제 고정된 추론 수준의 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)로 시작할 것을 권장합니다.¹⁷¹

실험적 컨텍스트 간 메모(Astra, 문서에 공개된 선택형 기능): Codex 모델 문서 페이지에는 “실험적 컨텍스트 관리”라는 섹션이 있으며, 원문은 다음과 같습니다. “지원되는 Codex 클라이언트에서 ChatGPT Plus 또는 Pro로 로그인한 사용자는 실험적 컨텍스트 관리를 선택하여 사용할 수 있습니다. Astra는 컨텍스트 창이 바뀌어도 메모를 유지하며 같은 작업의 이전 메시지와 도구 결과를 검색할 수 있습니다. 이 실험은 기본적으로 꺼져 있으며 출시 시 Business, Enterprise 또는 API 키 로그인에서는 사용할 수 없습니다.” 선택 방식의 원문은 다음과 같습니다. “선택하여 사용하려면 config.toml에서 features.context_management.experimental_mode = true를 설정한 다음 새 작업을 시작하세요.” 이는 v0.153.0에서 제공된 동일한 features.context_management.experimental_mode 설정입니다(컨텍스트 관리 참고). v0.153.0 릴리스 노트에서는 대상 세션으로 Plus, Pro, Pro Lite를 명시했지만, 이제 문서 페이지에서는 해당 기능을 Astra 및 Plus와 Pro 로그인에 명시적으로 연결합니다. v0.154.0에서는 코드 측 조건이 강화되어 세션 시작 시 활성 모델의 기능에 따라 실험 사용 자격이 결정됩니다(#43147). 문서 섹션은 2026년 9월 15일 재확인 당시에도 원문 그대로 유지되었습니다. 실험적이며 기본적으로 꺼져 있으므로 동작과 이용 자격이 변경될 수 있습니다.^140146152 v0.157.0: 번들 모델 카탈로그에서는 더 이상 GPT-6-Astra를 비롯한 어떤 번들 모델도 실험적 컨텍스트를 지원하는 것으로 표시하지 않으며(#47397), CLI은 해당 기능을 지원하는 것으로 표시된 모델에서만 실험을 활성화합니다. 따라서 번들 카탈로그에서는 이 설정을 켜도 아무런 효과가 없습니다. 로그인한 계정에 제공되는 카탈로그가 다른지는 문서화되어 있지 않습니다. 2026년 9월 26일에도 모델 문서에서는 이 선택형 기능을 계속 설명했습니다.¹⁷⁴ 2026년 9월 29일: 모델 페이지에서 해당 섹션이 제거되었고, 설정 참조 문서에서는 features.context_management.experimental_mode를 “실험적 컨텍스트 관리 설정입니다. 현재 이 기능을 사용할 수 없습니다.”라고 설명합니다. GPT-6.1 Sol 역시 이를 지원하는 것으로 표시되지 않습니다.¹⁷⁸

모델 선택 흐름도

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; most expensive)
   │     │  └─ No → gpt-6.1-sol (near-Astra at lower cost; default since v0.159.1)
   └─ GPT-6.1 Sol not yet available on your account? → gpt-6-sol, then gpt-5.6-sol

추론 수준

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

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

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

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

전문가 팁: 같은 프롬프트에서도 xhigh 추론은 medium보다 토큰을 3~5배 더 사용할 수 있습니다. 추가 추론이 실제로 도움이 되는 어려운 문제에만 사용하세요.

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

모델 전환

세션 도중 /model slash command로 모델을 전환하거나, --model / -m을 사용해 실행별로 설정합니다.

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

Codex 비용은 얼마입니까?

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

ChatGPT 플랜을 통한 이용

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

2026년 4월 가격 변경: Business 연간 결제 요금이 좌석당 월 $25에서 $20로 인하되었습니다. 이제 Business 및 Enterprise 워크스페이스에서 사용량만큼 결제하는 Codex 전용 좌석을 이용할 수 있습니다. 고정 좌석 요금 없이 토큰 사용량을 기준으로 청구됩니다.⁷⁹ 가격 페이지에는 이제 2026년 2월 Desktop App 출시 당시의 프로모션용 2배 배수 대신 모델별 구간으로 한도가 안내됩니다(위 표 참고).¹⁶¹⁶²

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

TUI의 사용량 한도 환경(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.1 Sol과 GPT-6 Astra, Sol, Luna에 “사용 가능한 경우” Standard 크레딧 요금의 2.5배가 적용됩니다. 또한 번들 카탈로그에서는 service_tier를 설정하지 않으면 TUI의 GPT-6 Sol과 Luna에 Fast가 기본 등급으로 적용되지만, GPT-6.1 Sol에는 적용되지 않습니다. 크레딧이 예상보다 빠르게 소진된다면 /fast status를 확인하세요. 이미지 생성은 비슷한 텍스트 전용 작업보다 포함된 한도를 3~5배 빠르게 소진합니다.^162171178

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

API 청구

API를 통해 Codex를 사용하면 선택한 모델의 표준 OpenAI API 가격에 따라 토큰별 사용료가 청구되며, 해당하는 경우 프롬프트 캐싱 할인도 적용됩니다. 토큰 100만 개당 현재 API 요금은 GPT-6.1 Sol이 입력 $2 / 출력 $10(캐시 입력 $0.10), GPT-6 Sol이 $2 / $10, GPT-6 Luna가 $0.10 / $0.50, GPT-6 Astra가 $10 / $50입니다. 4개 모델 모두 입력 프롬프트가 272K토큰을 넘으면 전체 요청에 입력 요금 2배와 출력 요금 1.5배가 적용되며, Fast 모드는 2배의 요금이 적용됩니다.^146171178 API Key로 로그인할 때는 ChatGPT 크레딧 배수가 적용되지 않습니다. 현재 요금은 공식 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 모드를 사용해야 할 때

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

계획 모드와 직접 실행 비교

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

지시 모드: Enter와 Tab 비교

기본 원칙: Enter = “멈추고 지금 이 내용을 들으세요.” Tab = “현재 작업이 끝나면 이 작업도 하세요.”

데스크톱 앱과 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: 파일 시스템과 네임스페이스 격리에 bubblewrap(bwrap)을 사용하고 syscall 필터링에 seccomp를 사용하며, 독립 실행형 도우미 프로세스(codex-linux-sandbox)를 통해 실행합니다. Landlock 구현은 레거시 방식으로 유지되며, v0.163.0에서는 적용 방식의 변경 없이 crate의 Landlock 명칭이 붙은 명령 유형과 syscall 모듈 이름을 변경했습니다.⁵¹⁹³ Codex는 작업 디렉터리 외부에서 PATH에 처음 발견되는 bwrap을 우선 사용하고, 없으면 번들로 제공되는 codex-resources/bwrap을 사용합니다(v0.100.0부터 번들 제공).⁷ bwrap이 없거나 사용자 네임스페이스를 만들 수 없으면 시작할 때 경고를 표시합니다. v0.117.0에서는 레거시 커널 설정을 사용하는 오래된 배포판의 sandbox 안정성을 개선했습니다.⁷⁵ v0.129.0에서는 Linux의 sandbox 시작 과정을 강화하고, 보안 패치가 적용된 Bubblewrap 0.11.2로 번들 버전을 올렸습니다. v0.130.0에서는 시작 과정의 보안을 추가로 강화했습니다.⁸⁹⁹¹
• Windows: 제한된 토큰을 사용하는 기본 sandbox를 제공합니다(v0.100.0에서 실험 단계에서 정식으로 승격됨). WSL도 지원합니다(Linux의 bubblewrap과 seccomp를 그대로 사용함). v0.117.0에는 프로세스 격리를 개선하는 제한 토큰 sandbox 개선 사항이 포함되어 있습니다.⁷⁵ v0.130.0에서는 sandbox 사용자에게 데스크톱 런타임 바이너리 캐시 접근 권한을 부여하여, Windows sandbox가 workspace 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): 도구 실행 전후의 hooks가 Guardian 하위 에이전트의 판단을 방해하지 않도록 Guardian 검토 세션에서는 hooks가 비활성화됩니다.⁸² 로깅이나 검증에 hooks를 사용한다면 Guardian 검토에서 이를 건너뛴다는 점에 유의하세요. 전체 감사 기록이 필요하면 app-server 관측 기능을 대안으로 사용하세요. - 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, v0.158.0부터 기본 활성화)

write_stdin_approval 기능 플래그는 v0.151.0에 추가되었을 때 기본적으로 꺼져 있었지만 v0.158.0부터 기본적으로 켜지며, 높은 권한으로 실행되는 unified-exec 터미널에 비어 있지 않은 입력을 보내기 전에 새로 승인을 받도록 요구합니다. 이러한 검토는 hooks, Guardian, 앱 서버 및 TUI를 거쳐 writeStdin 승인으로 전달됩니다. 터미널의 환경, 실행 디렉터리 및 권한 상승 상태는 턴 사이에도 유지되며, 바이트를 하나라도 쓰기 전에 승인 후 프로세스 신원을 다시 검증합니다. 형식이 완전히 적용된 작업과 승인 사유는 8,000바이트 이내여야 합니다. 크기 제한을 넘거나 잘린 작업은 승인을 요청하거나 터미널에 전달하기 전에 거부됩니다.¹³⁵ v0.158.0에서는 이 플래그를 켜고(#47799), 플러그인이 측정 지표에 사용하는 권한처럼 런타임에만 부여되는 권한이 검토를 유발하지 않도록 변경했습니다. 반면 추가 에이전트 권한, sandbox 우회 및 실행 이후의 정책 변경은 여전히 검토를 유발합니다(#48073). 끄는 방법: config.toml의 [features] 아래에 write_stdin_approval = false를 설정하세요.¹⁷⁶

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

권한 프로필은 파일 시스템 및 네트워크 sandbox 정책을 이름이 지정된 재사용 가능 섹션으로 분리합니다. default_permissions를 :read-only, :workspace 같은 기본 제공 프로필로 설정하거나 사용자 지정 [permissions.<name>] 테이블을 가리키도록 설정하세요.⁸⁷ v0.133.0에서는 프로필이 관리형 설정 영역으로 승격되었습니다. 목록 API가 사용 가능한 프로필 메타데이터를 노출하고, 프로필끼리 상속할 수 있으며, 관리형 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: 복원된 app-server 스레드는 권한 프로필을 레거시 턴별 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): 이제 결과를 바꿀 수 없는 Guardian 작업은 2가지 모드에서 건너뜁니다. 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 승인 검토는 모델 메타데이터의 Node REPL 정책(auto_review.node_repl_policy)을 사용할 수 있으며, 이 필드가 없으면 번들 정책을 사용합니다.¹³⁹

Guardian 컴퓨터 사용 채점에서 모델 요구 사항 준수(v0.153.1): 이제 컴퓨터 사용 전용 Guardian 채점과 빠른 승인 판단은 활성 모델의 메타데이터에 node_repl_auto_review_required가 설정된 경우에만 실행됩니다. 모델을 전환하여 채점을 건너뛰면 이전 점수나 진행 중인 점수가 무효화되므로, 검토 대상 모델로 다시 전환해도 오래된 승인 판단이 되살아나지 않습니다. 이는 v0.153.1 패치의 핵심 내용이지만 릴리스 본문에는 기재되지 않았습니다. #42422(38ba8cdc의 cherry-pick)는 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 전환과 독립적입니다. v0.157.0에서는 [features.guardianv2] 아래에 thread_context = false를 설정하여 끌 수 있었지만, v0.158.0에서 해당 옵션이 제거되었습니다.¹⁷⁴

Guardian 스레드 컨텍스트 항상 활성화(v0.158.0): #47686과 #47689에서는 Guardian 세션 캡처와 하위 에이전트 기록 포크에 스레드 소유 컨텍스트를 조건 없이 사용하도록 변경했습니다. Codex는 프로필 재정의와 관리형 요구 사항을 포함하여 [features.guardianv2] 아래의 thread_context를 무시하고, config.toml에서 이를 제거하라는 사용 중단 안내를 표시합니다. 이를 대신해 끌 수 있는 설정은 없습니다.¹⁷⁶

Guardian의 이전 사용자 메시지 읽기 지원(v0.160.0, 선택 사항): Guardian이 검토하는 기록에서 이전 지침, 제한 또는 철회된 권한이 누락될 수 있습니다. Apps를 활성화하고 [features] 아래에 guardian_conversation_history_tools = true를 설정하면 검토자에게 user_message.search_messages와 user_message.read_messages라는 2가지 도구가 제공됩니다. 이 도구들은 상위 세션 자체의 Apps 연결과 신원을 통해 제공됩니다. 각 호출은 상위 세션의 현재 앱 및 도구 정책을 다시 확인하며, 비활성화된 도구이거나 승인이 필요한 도구이면 안전 우선으로 실패합니다. [auto_review] 아래의 2가지 키로 동작을 조정할 수 있습니다. conversation_history_max_output_tokens는 각 응답을 제한하고 기본값은 약 4,000토큰으로 추정되며, 더 엄격한 상위 제한이 있으면 계속 적용됩니다. experimental_conversation_history_prompt는 기본 제공 검색 지침을 대체하며, 비워 두면 기본값을 사용합니다. 두 번째 선택 기능 플래그인 guardian_root_handoff_context는 작업자 에이전트의 검토에 제공되는 루트 대화 근거를 각 인계 전후의 메시지와 최신 3개 메시지로 제한합니다. 두 플래그 모두 개발 중이며 기본적으로 꺼져 있고, 아직 설정 참고 문서에도 나오지 않습니다.¹⁸²

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

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가 올바르게 작동한다면 workspace 범위 프로필에서 두 명령 모두 권한 거부 오류와 함께 실패해야 합니다. 둘 중 하나라도 성공하면 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가지를 모두 포함할 수 있으므로 팀의 초기 설정은 빨라지고 설정의 이식성은 높아집니다.

Plan Mode 및 협업

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

Plan mode와 update_plan 도구 비교(v0.152.0): 둘은 서로 다른 기능이며, 이 중 하나만 기본적으로 활성화되어 있습니다. Plan mode는 이 섹션에서 설명하는 협업 모드로, Codex가 실행 전에 계획을 제안하며 v0.94.0부터 기본적으로 활성화된 상태로 유지되고 있습니다. update_plan은 모델이 한 차례의 작업 안에서 구조화된 계획을 관리하기 위해 호출할 수 있는 계획 도구이며, v0.152.0에서 선택적 활성화 방식으로 출시되었습니다. tools.update_plan.enabled의 기본값은 false이며, 비활성화된 동안 Codex는 함께 제공되는 update_plan 지침도 모델, 협업 모드, multi-agent, 압축, 사전 준비 및 목표 지속 프롬프트에서 제거합니다. 계획을 언급하더라도 사용자 지정 기본 지침, 모델 카탈로그 지침, 협업 정책 및 사용자 목표 텍스트는 유지됩니다. config.toml에서 tools.update_plan.enabled = true를 설정하여 명시적으로 활성화하세요.¹³⁸

Plan Mode 진입

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

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

Steer Mode

Steer mode는 v0.98.0부터 기본적으로 활성화되어 있으며, Codex가 현재 작업을 중단하지 않고 수행하는 동안 새 지침을 전달할 수 있게 해 줍니다.¹⁴

지침을 전달하는 방법은 2가지입니다.

실용적인 예시:

# Codex is refactoring the auth module...

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

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

Steer mode는 TUI에서 항상 활성화되어 있습니다. 지침을 전달하기 전에 Codex가 작업을 마칠 때까지 기다리고 싶다면 작업 차례가 끝난 후 평소처럼 입력하면 됩니다. 별도의 모드는 필요하지 않습니다.

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-command 참조에는 여전히 /voice가 나열되어 있지 않으며, 문서의 음성 기능 페이지는 별도의 사용 환경인 데스크톱 앱의 ChatGPT Voice를 다룹니다.¹⁵⁶¹⁶⁹

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

메모리 시스템

Codex에는 세션 간에 정보, 기본 설정 및 프로젝트 맥락을 저장하는 영구 메모리 시스템(v0.100.0 이상)이 있습니다.²⁴

메모리 명령어

메모리는 ~/.codex/memory/ 아래의 markdown 파일에 저장됩니다. 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). v0.155.0에서는 worktree가 여전히 기본값이 아닌 상태로 관련 관리 기능이 추가되었습니다: agents 개요에서 worktree 세션을 숨기거나 보관하거나 삭제할 수 있고, 소유권 세부 정보가 표시되며, 깨끗한 관리형 worktree를 삭제할 때 확인을 요청합니다(#43942, #44424, #44433). 기본 활성화 변경 사항(#44870)은 9월 11일에 병합되었지만 안정 버전 0.155.0에는 포함되지 않았으며, rust-v0.155.0 태그를 기준으로 계보를 확인했습니다.¹⁵²¹⁵⁶

v0.156.0부터 관리형 worktree가 기본값이 됩니다: #44870은 worktrees를 안정 기능으로 승격하고 기본적으로 활성화하며 /experimental에서 제거합니다. 함께 제공되는 기능도 있습니다. worktree 세션은 자체 데몬을 시작하는 대신 기존 로컬 데몬에 연결할 수 있으며(#46498), 상태 필터 탭이 추가된(#46839) agents 개요에서 worktree 세션을 직접 생성할 수도 있습니다(#45276). 요청하지 않으면 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를 다시 시작하세요.¹⁶⁹¹⁷¹

모델용 Worktree 도구(v0.162.0): 기능이 활성화된 신뢰할 수 있는 로컬 프로젝트에서는 모델이 새 도구를 통해 관리형 worktree를 직접 생성하고 나열할 수 있으며(#50148), 새 대화 및 분기 프롬프트에서 worktree 선택지를 설명합니다(#50416).¹⁸⁷

자동화

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

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

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

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

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

Windows 지원

Codex Desktop App은 기본 PowerShell 지원, Windows 네이티브 sandbox, 그리고 WSL 없이도 사용할 수 있는 skills, 자동화, worktree를 비롯한 모든 기능을 갖추고 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");