logo

Codex CLI 기능

Codex는 채팅을 넘어 다양한 워크플로를 지원합니다. 이 가이드는 각 기능이 무엇을 가능하게 하는지, 언제 사용하면 좋은지 설명합니다.

대화형 모드 실행

Codex는 저장소를 읽고, 편집하고, 명령을 실행할 수 있는 전체 화면 터미널 UI로 시작됩니다. Codex의 동작을 실시간으로 검토하며 대화형으로 반복하고 싶을 때 사용합니다.

codex

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

codex "Explain this codebase to me"

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

  • composer에 프롬프트, 코드 조각, screenshot을 직접 보냅니다.
  • Codex가 변경 전에 계획을 설명하는 것을 보고, 단계별로 승인하거나 거부합니다.
  • TUI에서 syntax highlight된 Markdown 코드 블록과 diff를 읽고, /theme으로 원하는 theme을 preview하고 저장합니다.
  • /clear로 터미널을 지우고 새 chat을 시작하거나, Ctrl+L로 새 대화를 시작하지 않고 화면만 지웁니다.
  • /copy 또는 Ctrl+O로 최신 완료된 Codex 출력을 복사합니다. 턴이 아직 실행 중이면 진행 중 텍스트 대신 가장 최근에 끝난 출력을 복사합니다.
  • Codex가 실행 중일 때 Tab을 눌러 다음 턴에 보낼 follow-up 텍스트, slash command, ! shell 명령을 queue에 넣습니다.
  • composer에서 Up/Down으로 draft history를 탐색합니다. Codex는 이전 draft 텍스트와 이미지 placeholder를 복원합니다.
  • composer에서 Ctrl+R을 눌러 prompt history를 검색한 뒤, Enter로 match를 적용하거나 Esc로 취소합니다.
  • 작업이 끝나면 Ctrl+C 또는 /exit로 대화형 세션을 닫습니다.

대화 재개

Codex는 transcript를 로컬에 저장하므로 context를 반복 설명하지 않고 이어서 작업할 수 있습니다. 이전 스레드를 같은 저장소 상태와 지침으로 다시 열려면 resume 하위 명령을 사용합니다.

  • codex resume: 최근 대화형 세션 picker를 엽니다. 실행 항목을 highlight하면 summary를 볼 수 있고 Enter로 다시 엽니다.
  • codex resume --all: 현재 작업 디렉터리를 넘어선 세션도 보여 주므로 모든 로컬 실행을 다시 열 수 있습니다.
  • codex resume --last: picker를 건너뛰고 현재 작업 디렉터리의 가장 최근 세션으로 바로 이동합니다. --all을 추가하면 현재 작업 디렉터리 필터를 무시합니다.
  • codex resume {SESSION_ID}: 특정 실행을 대상으로 합니다. ID는 picker, /status, ~/.codex/sessions/ 아래 파일에서 복사할 수 있습니다.

비대화형 automation 실행도 재개할 수 있습니다.

codex exec resume --last "Fix the race conditions you found"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"

재개된 각 실행은 원래 transcript, plan history, approval을 유지하므로 Codex는 이전 context를 활용하고 사용자는 새 지침만 제공할 수 있습니다. 재개 전에 환경을 조정해야 한다면 --cd로 작업 디렉터리를 바꾸거나 --add-dir로 추가 root를 더합니다.

TUI를 원격 app server에 연결하기

Remote TUI 모드는 한 머신에서 Codex app server를 실행하고 다른 머신에서 Codex 터미널 UI를 사용할 수 있게 합니다. 코드, 자격 증명, 실행 환경은 원격 host에 두고 로컬 대화형 TUI 경험을 유지하고 싶을 때 유용합니다.

workspace를 소유하고 명령을 실행할 머신에서 app server를 시작합니다.

codex app-server --listen ws://127.0.0.1:4500

그런 다음 TUI를 실행할 머신에서 연결합니다.

codex --remote ws://127.0.0.1:4500

다른 머신에서 접근하려면 app server를 접근 가능한 interface에 bind합니다.

codex app-server --listen ws://0.0.0.0:4500

--remote는 명시적인 ws://host:port 및 wss://host:port 주소만 받습니다. 일반 WebSocket 연결에는 localhost 주소나 SSH port forwarding을 권장합니다. listener를 localhost 밖에 노출한다면 실제 원격 사용 전에 인증을 구성하고, 인증된 non-local 연결은 TLS 뒤에 두십시오.

Codex는 원격 TUI 연결에 다음 WebSocket 인증 모드를 지원합니다.

  • WebSocket 인증 없음: localhost listener 또는 SSH port forwarding 연결에 적합합니다. Codex는 인증 없이 non-local listener를 시작할 수 있지만 경고를 기록하고 startup banner에서 실제 원격 사용 전 인증 구성을 상기시킵니다.
  • Capability token: app-server host의 파일에 공유 token을 저장하고 --ws-auth capability-token --ws-token-file /abs/path/to/token으로 서버를 시작합니다. TUI host에서는 같은 token을 환경 변수에 넣고 --remote-auth-token-env {ENV_VAR}를 전달합니다.
  • Signed bearer token: app-server host의 파일에 HMAC 공유 비밀을 저장하고 --ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret으로 서버를 시작합니다. TUI는 --remote-auth-token-env {ENV_VAR}를 통해 signed JWT bearer token을 보냅니다. 공유 비밀은 최소 32바이트여야 합니다. Signed token은 HS256을 사용하고 exp를 포함해야 하며, claim 또는 서버 옵션이 있으면 Codex가 nbf, iss, aud도 검증합니다.

App-server host에서 capability token을 만들려면 사용자만 읽을 수 있는 권한의 랜덤 token 파일을 생성합니다.

TOKEN_FILE="$HOME/.codex/codex-app-server-token"
install -d -m 700 "$(dirname "$TOKEN_FILE")"
openssl rand -base64 32 > "$TOKEN_FILE"
chmod 600 "$TOKEN_FILE"

Token 파일은 password처럼 취급하고, 유출되면 재생성하십시오.

TLS proxy 뒤 capability token을 사용하는 예:

# Remote host
TOKEN_FILE="$HOME/.codex/codex-app-server-token"
codex app-server \
  --listen ws://0.0.0.0:4500 \
  --ws-auth capability-token \
  --ws-token-file "$TOKEN_FILE"

# TUI host
export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"
codex --remote wss://codex-devbox.example.com:4500 \
  --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

TUI는 WebSocket handshake 중 원격 auth token을 Authorization: Bearer {token}으로 보냅니다. Codex는 wss:// URL 또는 host가 localhost, 127.0.0.1, ::1인 ws:// URL에서만 이 token을 전송하므로, 네트워크를 통해 client가 인증해야 하는 non-local listener는 TLS 뒤에 두십시오.

모델과 reasoning

대부분의 Codex 작업에서는 사용할 수 있다면 gpt-5.5가 권장 모델입니다. 복잡한 coding, computer use, knowledge work, research workflow를 위한 OpenAI의 최신 frontier 모델이며, 여러 단계 작업에서 planning, tool use, follow-through가 더 강합니다. gpt-5.5를 아직 사용할 수 없다면 gpt-5.4를 계속 사용하십시오. 매우 빠른 작업에는 ChatGPT Pro 구독자가 research preview의 GPT-5.3-Codex-Spark 모델을 사용할 수 있습니다.

세션 중에는 /model 명령으로 모델을 바꾸거나 CLI 시작 시 모델을 지정합니다.

codex --model gpt-5.5

기능 플래그

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를 시작했다면 루트 구성 대신 해당 profile에 변경 사항을 저장합니다.

하위 에이전트

Codex 하위 에이전트 워크플로를 사용해 큰 작업을 병렬화할 수 있습니다. 설정, config.toml의 [agents] role 구성, 예시는 하위 에이전트를 참고하십시오.

Codex는 사용자가 명시적으로 요청할 때만 하위 에이전트를 생성합니다. 각 하위 에이전트가 자체 모델 호출과 도구 작업을 수행하므로, 하위 에이전트 워크플로는 비슷한 단일 에이전트 실행보다 더 많은 토큰을 사용합니다.

이미지 입력

Screenshot이나 design spec을 첨부하면 Codex가 prompt와 함께 이미지 세부 정보를 읽을 수 있습니다. 대화형 composer에 이미지를 붙여 넣거나 명령줄에서 파일을 제공할 수 있습니다.

codex -i screenshot.png "Explain this error"

codex --image img1.png,img2.jpg "Summarize these diagrams"

Codex는 PNG, JPEG 같은 일반 형식을 받습니다. 두 개 이상의 이미지는 comma-separated 파일 이름으로 제공하고, 텍스트 지침과 결합해 context를 추가합니다.

이미지 생성

CLI에서 Codex에게 이미지를 생성하거나 편집하도록 요청할 수 있습니다. icon, banner, illustration, sprite sheet, placeholder art 같은 asset에 적합합니다. 기존 asset을 변환하거나 확장하려면 prompt에 reference image를 첨부하십시오.

자연어로 요청하거나 prompt에 $imagegen을 포함해 image generation skill을 명시적으로 호출할 수 있습니다.

내장 이미지 생성은 gpt-image-2를 사용하고 일반 Codex 사용 한도에 포함됩니다. 품질과 크기에 따라 평균적으로 이미지 생성이 없는 유사 턴보다 포함 한도를 3-5배 빠르게 사용합니다.

더 큰 이미지 생성 batch에는 환경 변수에 OPENAI_API_KEY를 설정하고 Codex에게 API를 통해 이미지를 생성하게 요청하면 API pricing이 적용됩니다.

Syntax highlighting과 theme

TUI는 fenced Markdown 코드 블록과 파일 diff에 syntax highlight를 적용해 review와 debugging 중 코드를 쉽게 훑을 수 있게 합니다.

/theme을 사용해 theme picker를 열고, theme을 live preview하고, 선택 내용을 ~/.codex/config.toml의 tui.theme에 저장합니다. $CODEX_HOME/themes 아래에 사용자 지정 .tmTheme 파일을 추가하고 picker에서 선택할 수도 있습니다.

로컬 코드 리뷰 실행

CLI에서 /review를 입력하면 Codex의 review preset이 열립니다. CLI는 선택한 diff를 읽고, 작업 트리를 건드리지 않은 채 우선순위가 있는 실행 가능한 finding을 보고하는 전용 reviewer를 실행합니다. 기본적으로 현재 세션 모델을 사용하며, config.toml에 review_model을 설정해 오버라이드할 수 있습니다.

  • Base branch 기준 리뷰: 로컬 branch를 선택하면 Codex가 upstream과 merge base를 찾고, 작업 내용을 diff한 뒤 PR을 열기 전 가장 큰 위험을 강조합니다.
  • Uncommitted changes 리뷰: staged, unstaged, untracked 변경을 모두 검사해 commit 전에 문제를 처리할 수 있게 합니다.
  • Commit 리뷰: 최근 commit을 나열하고 선택한 SHA의 정확한 changeset을 읽습니다.
  • 사용자 지정 리뷰 지침: "접근성 회귀에 집중"처럼 직접 문구를 입력하면 같은 reviewer가 해당 prompt로 실행됩니다.

각 실행은 transcript의 별도 턴으로 표시되므로 코드가 바뀔 때 review를 다시 실행하고 feedback을 비교할 수 있습니다.

웹 검색

Codex에는 first-party 웹 검색 도구가 포함됩니다. Codex CLI의 로컬 작업에서 Codex는 기본적으로 웹 검색을 활성화하고 웹 검색 cache에서 결과를 제공합니다. 이 cache는 OpenAI가 유지하는 웹 결과 index이므로 cached mode는 live page를 가져오지 않고 미리 index된 결과를 반환합니다. 임의 live content에서 오는 prompt injection 노출을 줄이지만, 웹 결과는 여전히 신뢰할 수 없는 것으로 취급해야 합니다. --yolo 또는 다른 full access sandbox 설정을 사용하면 웹 검색은 기본적으로 live 결과를 사용합니다. 최신 데이터를 가져오려면 단일 실행에 --search를 전달하거나 설정 기초에서 web_search = "live"를 설정합니다. 도구를 끄려면 web_search = "disabled"를 설정할 수 있습니다.

Codex가 무언가를 검색하면 transcript 또는 codex exec --json 출력에 web_search 항목이 표시됩니다.

입력 prompt로 실행

빠른 답변만 필요하다면 대화형 UI 없이 단일 prompt로 Codex를 실행합니다.

codex "explain this codebase"

Codex는 작업 디렉터리를 읽고, plan을 만들고, 종료 전에 terminal로 응답을 stream합니다. --path 같은 flag로 특정 디렉터리를 대상으로 하거나 --model로 동작을 미리 조정할 수 있습니다.

Shell completion

일상 사용을 빠르게 하려면 shell용 completion script를 설치합니다.

codex completion bash
codex completion zsh
codex completion fish

새 세션에서 completion을 사용하려면 shell 구성 파일에서 completion script를 실행합니다. zsh를 사용한다면 ~/.zshrc 끝에 다음을 추가할 수 있습니다.

# ~/.zshrc
eval "$(codex completion zsh)"

새 세션을 열고 codex를 입력한 뒤 Tab을 눌러 completion을 확인합니다. command not found: compdef 오류가 보이면 eval "$(codex completion zsh)" 줄 앞에 autoload -Uz compinit && compinit를 ~/.zshrc에 추가하고 shell을 다시 시작합니다.

승인 모드

승인 모드는 Codex가 확인을 위해 멈추지 않고 할 수 있는 일의 범위를 정의합니다. 대화형 세션 안에서 /permissions를 사용해 편안한 수준에 맞게 모드를 바꿉니다.

  • Auto 기본값: Codex가 작업 디렉터리 안에서 파일을 읽고, 편집하고, 명령을 실행할 수 있습니다. 해당 범위 밖을 건드리거나 네트워크를 사용할 때는 여전히 묻습니다.
  • Read-only: Codex를 상담 모드로 유지합니다. 파일을 탐색할 수 있지만 plan을 승인하기 전에는 변경하거나 명령을 실행하지 않습니다.
  • Full Access: Codex가 네트워크 접근을 포함해 머신 전반에서 묻지 않고 작업할 수 있게 합니다. 신뢰하는 저장소와 작업에서만 드물게 사용하십시오.

Codex는 항상 action transcript를 표시하므로 일반적인 git workflow로 변경 사항을 review하거나 되돌릴 수 있습니다.

Codex 스크립팅

Workflow를 자동화하거나 기존 script에 Codex를 연결하려면 exec 하위 명령을 사용합니다. 이 명령은 Codex를 비대화형으로 실행하고 최종 plan과 결과를 stdout으로 내보냅니다.

codex exec "fix the CI failure"

exec를 shell script와 결합해 changelog 자동 갱신, issue 정렬, PR 전 editorial check 강제 같은 사용자 지정 workflow를 만들 수 있습니다.

Codex cloud 작업

codex cloud 명령을 사용하면 terminal을 떠나지 않고 Codex cloud task를 triage하고 시작할 수 있습니다. 인자 없이 실행하면 대화형 picker가 열리고 active 또는 finished task를 탐색하며 변경 사항을 로컬 프로젝트에 적용할 수 있습니다.

Terminal에서 task를 직접 시작할 수도 있습니다.

codex cloud exec --env ENV_ID "Summarize open bugs"

Codex cloud가 둘 이상의 solution을 생성하길 원하면 --attempts(1-4)를 추가해 best-of-N 실행을 요청합니다. 예: codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs".

Environment ID는 Codex cloud 구성에서 가져옵니다. codex cloud를 실행하고 Ctrl+O로 environment를 선택하거나 web dashboard에서 정확한 값을 확인하십시오. 인증은 기존 CLI login을 따르며, 제출 실패 시 명령이 non-zero로 종료되므로 script나 CI에 연결할 수 있습니다.

Slash command

Slash command는 /review, /fork, /side, 사용자 지정 reusable prompt 같은 특화 workflow에 빠르게 접근하게 합니다. Codex에는 curated built-in command가 포함되며, 팀별 작업 또는 개인 shortcut용 사용자 지정 command를 만들 수 있습니다.

Built-in catalog를 탐색하고 사용자 지정 command 작성 방법과 디스크 위치를 알아보려면 slash commands guide를 참고하십시오.

Prompt editor

긴 prompt를 작성할 때는 전체 editor로 전환한 뒤 결과를 composer로 되돌려 보내는 것이 편할 수 있습니다.

Prompt input에서 Ctrl+G를 누르면 VISUAL 환경 변수로 정의된 editor가 열립니다. VISUAL이 없으면 EDITOR가 사용됩니다.

Model Context Protocol(MCP)

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

예시 구성, 지원 auth flow, 더 자세한 가이드는 Model Context Protocol을 참고하십시오.

팁과 shortcut

  • Composer에서 @를 입력하면 workspace root의 fuzzy file search가 열립니다. Tab 또는 Enter를 눌러 highlight된 path를 메시지에 넣습니다.
  • Codex가 실행 중일 때 Enter를 누르면 현재 턴에 새 지침을 주입하고, Tab을 누르면 다음 턴의 follow-up 입력을 queue에 넣습니다. Queue에 넣을 입력은 일반 prompt, /review 같은 slash command, ! shell command일 수 있습니다. Codex는 queue된 slash command를 실행 시점에 parse합니다.
  • 줄 앞에 !를 붙여 로컬 shell 명령을 실행합니다. 예: !ls. Codex는 출력을 사용자가 제공한 명령 결과처럼 취급하면서 승인과 샌드박스 설정을 계속 적용합니다.
  • Composer가 비어 있을 때 Esc를 두 번 누르면 이전 사용자 메시지를 편집합니다. 계속 Esc를 누르면 transcript에서 더 뒤로 이동하고, Enter를 눌러 그 지점에서 fork합니다.
  • 아무 디렉터리에서나 codex --cd {path}를 사용해 먼저 cd하지 않고 작업 root를 설정합니다. 활성 path는 TUI header에 표시됩니다.
  • 둘 이상의 프로젝트에 걸쳐 변경을 조율해야 한다면 --add-dir로 더 많은 writable root를 노출합니다. 예: codex --cd apps/frontend --add-dir ../backend --add-dir ../shared.
  • Codex가 무엇을 활성화해야 하는지 조사하는 데 토큰을 쓰지 않도록 Codex 실행 전에 환경을 미리 준비하십시오. 예를 들어 Python virtual environment 또는 다른 language environment를 source하고, 필요한 daemon을 시작하고, 사용할 환경 변수를 미리 export합니다.
Previous
개요
Next
옵션