Codex CLI 기능

Codex는 채팅 이상의 워크플로를 지원합니다. 이 가이드를 사용하여 각 기능이 무엇을 열어주고 언제 사용해야 하는지 알아보세요.

대화형 모드 실행

Codex는 전체 화면 터미널 UI로 실행되며 저장소를 읽고 수정하며 명령을 실행하면서 함께 작업합니다. Codex의 동작을 실시간으로 검토할 수 있는 대화식 워크플로가 필요할 때마다 사용하세요.

codex

명령줄에서 초기 프롬프트를 지정할 수도 있습니다.

codex "이 코드베이스를 설명해 줘"

세션이 열리면 다음을 할 수 있습니다:

프롬프트, 코드 조각 또는 스크린샷(이미지 입력 참고)를 작곡기에 직접 보냅니다.
변경을 하기 전에 Codex가 계획을 설명하는 모습을 보고 해당 단계들을 승인하거나 거부합니다.
Up/Down으로 작곡기에서 초안 기록을 탐색하면 이전 초안 텍스트와 이미지 자리 표시자를 복원합니다.
완료되면 Ctrl+C를 누르거나 /exit을 사용하여 대화형 세션을 종료합니다.

대화 이어가기

Codex는 대화를 로컬에 저장하므로 문맥을 반복할 필요 없이 이전에 멈췄던 지점에서 다시 시작할 수 있습니다. 동일한 저장소 상태와 지침으로 이전 스레드를 다시 열고 싶을 때 resume 하위 명령을 사용하세요.

codex resume은 최근 대화형 세션 목록을 표시합니다. 실행을 강조 표시하면 요약을 볼 수 있고 Enter로 다시 엽니다.
codex resume --all은 현재 작업 디렉터리 외부의 세션도 보여주므로 모든 로컬 실행을 다시 열 수 있습니다.
codex resume --last는 선택기를 건너뛰고 현재 작업 디렉터리에서 가장 최근 세션으로 바로 이동합니다(--all을 추가하면 작업 디렉터리 필터를 무시합니다).
codex resume <SESSION_ID>는 특정 실행을 지정합니다. ID는 선택기, /status, 또는 ~/.codex/sessions/ 아래 파일에서 복사할 수 있습니다.

비대화형 자동화 실행도 다시 시작할 수 있습니다:

codex exec resume --last "발견한 경쟁 조건을 수정해줘"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "계획을 구현해줘"

각 재개된 실행은 원래 기록, 계획 히스토리 및 승인 정보를 유지하므로 이전 문맥을 사용하면서 새로운 지침을 제공할 수 있습니다. 환경을 조정하려면 --cd로 작업 디렉터리를 덮어쓰거나 --add-dir로 추가 루트를 지정하세요.

모델과 추론

Codex에서 대부분의 코딩 작업은 gpt-5.3-codex 모델이 기본입니다. Codex 앱, CLI, IDE 확장 및 Codex Cloud의 ChatGPT 인증 세션에서 사용 가능합니다. 더 빠른 작업을 원한다면 ChatGPT Pro 가입자는 연구 미리보기로 GPT-5.3-Codex-Spark 모델에 접근할 수 있습니다.

세션 중간에 /model 명령으로 변경하거나 CLI 실행 시 지정하세요.

codex --model gpt-5.3-codex

Codex에서 사용 가능한 모델에 대해 자세히 알아보기.

기능 플래그

Codex에는 소수의 기능 플래그가 포함되어 있습니다. features 하위 명령으로 사용 가능한 항목을 확인하고 설정에 변경 사항을 영구적으로 저장하세요.

codex features list
codex features enable unified_exec
codex features disable shell_snapshot

codex features enable <feature>와 codex features disable <feature>는 ~/.codex/config.toml에 기록합니다. --profile을 사용하여 Codex를 시작하면 변경 사항이 루트 구성 대신 해당 프로파일에 저장됩니다.

멀티 에이전트(실험적)

Codex 멀티 에이전트 워크플로로 더 큰 작업을 병렬 처리할 수 있습니다. 설정, 역할 구성(config.toml의 [agents]), 예시는 멀티 에이전트을 확인하세요.

이미지 입력

스크린샷이나 디자인 명세를 첨부하여 Codex가 프롬프트와 함께 이미지 세부사항을 읽을 수 있게 합니다. 대화형 작곡기에 이미지를 붙여넣거나 명령줄에서 파일을 지정할 수 있습니다.

codex -i screenshot.png "이 오류를 설명해줘"

codex --image img1.png,img2.jpg "이 도면들을 요약해줘"

Codex는 PNG, JPEG 등 일반 형식을 지원합니다. 두 개 이상의 이미지에는 쉼표로 구분된 파일 이름을 사용하고 텍스트 지침과 함께 문맥을 제공합니다.

로컬 코드 리뷰 실행

CLI에서 /review를 입력하면 Codex의 리뷰 프리셋이 열립니다. CLI는 선택한 diff를 읽고 작업 트리를 건드리지 않으며 우선순위가 정해진 실행 가능한 결과를 보고합니다. 기본적으로 현재 세션 모델을 사용하며, config.toml에서 review_model을 설정하여 덮어쓸 수 있습니다.

기준 브랜치 대비 리뷰는 로컬 브랜치를 선택하게 하며 Codex가 업스트림과의 병합 기반을 찾아 작업을 비교하고 PR 전에 주요 리스크를 강조합니다.
커밋되지 않은 변경사항 리뷰는 스테이징된 항목, 스테이징되지 않은 항목 또는 추적되지 않은 항목을 점검하여 커밋 전에 문제를 해결할 수 있게 합니다.
커밋 리뷰는 최근 커밋을 나열하고 선택한 SHA의 정확한 변경 집합을 읽도록 Codex에 지시합니다.
사용자 지정 리뷰 지침은 “접근성 회귀에 집중”처럼 자신의 문구를 입력하면 동일한 리뷰어를 해당 프롬프트로 실행합니다.

각 실행은 기록 내 별도의 턴으로 나타나므로 코드가 진화함에 따라 리뷰를 다시 실행하고 피드백을 비교할 수 있습니다.

웹 검색

Codex는 자체 웹 검색 도구를 탑재합니다. Codex CLI의 로컬 작업에서는 기본적으로 웹 검색이 활성화되어 있으며 웹 검색 캐시에서 결과를 제공합니다. 캐시는 OpenAI가 유지하는 웹 결과 인덱스이므로 캐시 모드는 실시간 페이지를 가져오지 않고 미리 인덱싱된 결과를 반환합니다. 이는 임의의 실시간 콘텐츠 공격 가능성을 줄여주지만, 웹 결과를 신뢰할 수 없다고 생각하고 다루세요. --yolo 또는 다른 전체 액세스 샌드박스 설정을 사용하는 경우 웹 검색은 실시간 결과로 기본 설정됩니다. 최신 데이터를 가져오려면 단일 실행에 --search를 전달하거나 기본 구성에서 web_search = "live"로 설정하세요. 도구를 끄려면 web_search = "disabled"로 설정하면 됩니다.

Codex가 무엇인가를 검색할 때 기록 또는 codex exec --json 출력에서 web_search 항목이 표시됩니다.

입력 프롬프트로 실행

빠른 답변이 필요한 경우 Codex를 단일 프롬프트로 실행하여 대화형 UI를 건너뛸 수 있습니다.

codex "이 코드베이스를 설명해줘"

Codex는 작업 디렉터리를 읽고 계획을 세우며 종료 전에 터미널에 응답을 스트리밍합니다. --path처럼 특정 디렉터리를 지정하거나 --model로 동작을 미리 조정하는 플래그와 함께 사용하세요.

셸 완성

자주 사용하는 작업을 빠르게 하려면 셸용 자동 완성 스크립트를 설치하세요:

codex completion bash
codex completion zsh
codex completion fish

새 세션용 완성을 설정하려면 셸 구성 파일에서 스크립트를 실행하세요. 예를 들어 zsh를 사용한다면 ~/.zshrc 파일 끝에 다음을 추가할 수 있습니다:

eval "$(codex completion zsh)"

새 세션을 시작하고 codex를 입력한 후 Tab을 눌러 완성을 확인하세요. command not found: compdef 오류가 나타나면 eval "$(codex completion zsh)" 줄 앞에 autoload -Uz compinit && compinit을 추가한 뒤 셸을 다시 시작하세요.

승인 모드

승인 모드는 Codex가 확인 없이 수행할 수 있는 범위를 정의합니다. 대화형 세션에서 /permissions를 사용해 편안한 수준에 따라 모드를 전환하세요.

자동(기본)은 Codex가 작업 디렉터리 내 파일을 읽고 편집하며 명령을 실행하게 합니다. 범위를 벗어나거나 네트워크를 사용할 때만 사전에 확인합니다.
읽기 전용은 상담 모드로 유지합니다. Codex는 파일을 탐색할 수 있지만 계획을 승인할 때까지 수정하지 않거나 명령을 실행하지 않습니다.
전체 액세스는 기계 전체 작업 및 네트워크 액세스를 포함하여 승인 없이 수행할 수 있게 허용합니다. 저장소와 작업을 신뢰할 때만 제한적으로 사용하세요.

Codex는 항상 수행한 작업의 기록을 보여주므로 평소 git 워크플로로 변경을 검토하거나 되돌릴 수 있습니다.

Codex 스크립팅

exec 하위 명령으로 워크플로를 자동화하거나 기존 스크립트에 Codex를 연결하세요. 이 명령은 비대화형으로 실행되며 최종 계획과 결과를 stdout으로 출력합니다.

codex exec "CI 실패를 수정해줘"

shell 스크립팅과 exec를 결합하여 자동으로 변경 로그를 갱신하거나 이슈를 정리하고 PR 제출 전에 편집 검사를 강제하는 등의 맞춤형 워크플로를 구성할 수 있습니다.

Codex 클라우드와 작업

codex cloud 명령으로 터미널을 벗어나지 않고도 Codex cloud 작업을 분류하고 실행할 수 있습니다. 인수 없이 실행하면 대화형 선택기가 열리고 활성 또는 완료된 작업을 탐색하며 변경 내용을 로컬 프로젝트에 적용합니다.

터미널에서 직접 작업을 시작할 수도 있습니다:

codex cloud exec --env ENV_ID "열린 버그를 요약해줘"

--attempts(1–4)를 추가하여 Codex cloud가 여러 솔루션을 만들어야 할 때 best-of-N 실행을 요청하세요. 예를 들어 codex cloud exec --env ENV_ID --attempts 3 "열린 버그를 요약해줘"처럼 사용할 수 있습니다.

환경 ID는 Codex cloud 구성에서 가져옵니다—codex cloud를 실행하고 Ctrl+O를 눌러 환경을 선택하거나 웹 대시보드에서 정확한 값을 확인하세요. 인증은 기존 CLI 로그인 흐름을 따르며 제출이 실패하면 명령이 0이 아닌 상태로 종료되므로 스크립트나 CI와 연결할 수 있습니다.

슬래시 명령

슬래시 명령은 /review, /fork 또는 팀-특정 작업이나 개인 단축키를 위한 자체 재사용 가능한 프롬프트처럼 특화된 워크플로에 빠르게 접근할 수 있게 합니다. Codex는 엄선된 기본 제공 명령을 제공하며 사용자 정의 명령도 만들 수 있습니다.

슬래시 명령 가이드를 참조하여 기본 제공 명령 목록을 보고 사용자 정의 명령을 작성하는 방법과 해당 위치를 이해하세요.

프롬프트 편집기

긴 프롬프트를 작성할 때 전체 편집기로 전환한 다음 결과를 작곡기로 다시 보내는 것이 편할 수 있습니다.

프롬프트 입력에서 Ctrl+G를 눌러 VISUAL 환경 변수(또는 VISUAL이 설정되지 않은 경우 EDITOR)가 정의한 편집기를 엽니다.

모델 컨텍스트 프로토콜(MCP)

Model Context Protocol 서버를 구성하여 Codex를 더 많은 도구에 연결하세요. ~/.codex/config.toml에 STDIO 또는 스트리밍 HTTP 서버를 추가하거나 codex mcp CLI 명령으로 관리하세요—세션 시작 시 Codex가 자동으로 실행하고 내장 도구 옆에 해당 도구를 노출합니다. 다른 에이전트 안에서 Codex 자체를 MCP 서버로 실행할 수도 있습니다.

Model Context Protocol에서 예시 구성, 지원 인증 흐름 및 더 자세한 가이드를 확인하세요.

팁과 바로 가기

작곡기에서 @를 입력하면 작업 공간 루트에 대한 퍼지 파일 검색이 열립니다; Tab이나 Enter를 눌러 강조된 경로를 메시지에 삽입하세요.
Codex 실행 중 Enter를 눌러 현재 턴에 새 지침을 주입하거나 Tab을 눌러 다음 턴용 후속 프롬프트를 예약하세요.
줄을 !로 시작하면 로컬 셸 명령(예: !ls)이 실행됩니다. Codex는 결과를 사용자 제공 명령 결과처럼 처리하며 승인 및 샌드박스 설정을 적용합니다.
작곡기가 비어 있는 상태에서 Esc를 두 번 눌러 이전 사용자 메시지를 편집하세요. 계속 Esc를 누르면 기록을 더 거슬러 올라가고 Enter를 눌러 그 지점에서 다시 포크할 수 있습니다.
codex --cd <path>로 어떤 디렉터리에서든 Codex를 실행하여 cd를 먼저 실행할 필요 없이 작업 루트를 설정하세요. 활성 경로가 TUI 헤더에 표시됩니다.
여러 프로젝트에서 변경을 조율해야 할 때 --add-dir로 더 많은 쓰기 가능한 루트를 노출하세요(예: codex --cd apps/frontend --add-dir ../backend --add-dir ../shared).
Codex를 실행하기 전에 환경이 이미 준비되어 있어야 토큰을 환경 활성화 탐색에 낭비하지 않습니다. 예를 들어 Python 가상 환경(또는 다른 언어 환경)을 소스하고, 필요한 데몬을 시작하며, 사용할 것으로 예상되는 환경 변수를 미리 export하세요.