Codex를 "대화형 도우미"로만 쓰면, 매번 터미널 앞에 앉아 질문하고 답을 받는 데서 끝나기 쉽습니다. 반대로 CLI의 기본기를 익히면 Codex는 반복 업무를 대신 돌려주는 자동화 엔진이 됩니다. 이 장의 목표는 세 가지를 한 흐름으로 연결하는 것입니다.

하나는 codex로 여는 인터랙티브 TUI이고, 둘째는 codex exec로 돌리는 헤드리스(비대화형) 실행이며, 셋째는 중간에 끊긴 일을 이어가는 resume입니다.¹²

1) 작업 단위부터 정리하기: 대화, 세션, 태스크, 턴

Codex CLI를 제대로 쓰려면 "무엇이 저장되고, 무엇이 다시 이어지며, 무엇이 한 번 실행되고 끝나는지"를 먼저 구분해야 합니다.

대화(conversation)는 우리가 주고받는 메시지의 연속입니다. 하지만 Codex 입장에서는 대화가 항상 하나로 이어지지 않습니다. 어느 순간엔 새로 시작하기도 하고, 예전 대화의 특정 시점으로 되돌아가 갈라지기도 합니다.

세션(session)은 대화를 담는 "그릇"입니다. TUI로 시작한 작업은 한 세션으로 기록되고, 세션은 로컬에 저장되어 나중에 codex resume로 이어갈 수 있습니다.³

태스크(task)는 "이번 실행에서 끝내려는 일의 단위"에 가깝습니다. codex exec는 기본적으로 한 태스크를 실행하고 종료합니다. CI나 스크립트에서는 이 태스크 단위가 가장 다루기 쉽습니다.²

턴(turn)은 "내 입력 1번 → Codex의 실행(파일 읽기/수정/명령 실행 포함) → 응답 1번"의 묶음입니다. 특히 codex exec --json을 쓰면 turn.started, turn.completed 같은 이벤트로 턴 경계를 명확히 관찰할 수 있어 자동화에 유리합니다.⁴

이제부터는 이렇게 이해하면 편합니다.

• codex(TUI)는 긴 세션을 전제로 한 협업 모드입니다.¹

• codex exec는 태스크 1개를 끝까지 밀고 나가는 자동 실행 모드입니다.²

• resume은 그 세션/태스크의 문맥을 이어붙이는 접착제입니다.³⁴

2) codex: 인터랙티브 TUI를 "작업대"로 쓰는 법

codex를 실행하면 전체 화면에 가까운 TUI가 열리고, Codex가 레포를 읽고 변경을 제안하거나 직접 수정하며, 필요하면 명령을 실행하는 흐름을 실시간으로 보여줍니다.¹⁵

TUI 모드는 단순 채팅이 아니라 "작업대"에 가깝습니다. 메시지를 주고받는 동안에도 다음이 계속 누적됩니다.

• 어떤 파일을 읽었는지

• 어떤 변경을 만들었는지

• 어떤 명령을 실행했고 결과가 어땠는지

이 누적이 곧 세션의 가치입니다. 그래서 TUI는 "오늘 한 번 질문하고 끝"이 아니라, 하나의 작업을 안정적으로 완주하는 장기 세션에 어울립니다.

2.1 모델/추론 강도를 작업 중에 바꾸기

TUI에서는 슬래시 커맨드로 모델을 바꾸거나 추론 관련 설정을 조정할 수 있습니다. 대표적으로 /model이 그 역할을 합니다.¹⁶

이 기능이 중요한 이유는 간단합니다. 같은 레포에서도 상황이 바뀝니다.

예를 들어 초반에는 빠르게 구조를 파악해야 하니 속도가 중요하고, 막판에는 회귀 테스트를 통과시키는 정확도가 중요합니다. TUI는 이런 "작업의 국면"에 맞춰 대화 도중에 엔진을 바꾸는 경험을 제공합니다.⁶

2.2 파일을 "정확히 집어서" 이야기하기: @ 파일 검색

TUI에서 @를 입력하면 워크스페이스 파일을 퍼지 검색해서 프롬프트에 경로를 끼워 넣을 수 있습니다.³

실전에서는 "어딘가의 설정 파일"처럼 모호하게 말하는 것보다, @package.json, @pyproject.toml처럼 근거 파일을 정확히 지정하는 편이 훨씬 빠릅니다. 이 습관만으로도 Codex가 불필요한 탐색을 하는 시간을 크게 줄일 수 있습니다.

2.3 화면이 불편하면: alternate screen과 --no-alt-screen

TUI는 터미널의 alternate screen(전체화면 버퍼)을 사용해 깔끔한 UI를 만듭니다. 다만 tmux/zellij 같은 멀티플렉서 환경에서는 스크롤백이나 화면 동작이 기대와 다를 수 있습니다. Codex는 이를 위해 alternate screen 동작을 설정으로 제어하고, 실행 시점에는 --no-alt-screen으로 끌 수도 있습니다.⁷

codex --no-alt-screen

이 옵션은 "한 번만 스크롤백이 필요하다" 같은 상황에서 특히 유용합니다.

2.4 슬래시 커맨드는 '작업 제어판'이다

슬래시 커맨드는 단축키 모음이 아니라, 세션을 운영하는 제어판입니다. 슬래시 팝업을 열어 모델 전환, 권한/승인 관련 설정, 긴 대화 요약 같은 동작을 빠르게 수행할 수 있습니다.⁶

여기서 중요한 포인트는, TUI에서의 제어는 '대화 내용'과 분리된다는 점입니다. 같은 요청을 하더라도, 권한/모드/요약 상태에 따라 결과가 달라지므로 "대화를 잘하는 것"과 "세션을 잘 운영하는 것"을 구분해 익히면 속도가 붙습니다.

3) codex exec: Codex를 자동화 엔진으로 바꾸는 스위치

TUI가 사람과 함께 달리는 모드라면, codex exec는 사람이 옆에 없어도 굴러가는 모드입니다. 문서에서도 codex exec를 스크립트나 CI 같은 파이프라인에서 쓰는 "비대화형 모드"로 설명합니다.²

기본 형태는 단순합니다.

codex exec "이 레포에서 TODO 주석만 모아 요약해줘"

그러나 자동화 관점에서 정말 중요한 차이는 "출력 설계"에 있습니다.

3.1 stdout와 stderr가 분리된다: 파이프라인 친화적인 출력

codex exec는 기본적으로 실행 중 활동 로그는 stderr로 흘리고, 마지막 최종 답변만 stdout로 출력합니다. 그래서 파이프에 연결하기 쉽습니다.⁴

예를 들어 결과만 파일로 저장하고 싶다면, 셸 리다이렉트도 가능하지만 전용 옵션도 있습니다(-o/--output-last-message).⁴

codex exec -o report.txt "보안 취약점 가능성이 있는 지점을 점검하고 보고서를 써줘"

이 패턴을 기억해두면, Codex의 출력을 다른 도구(jq, sed, 린터, PR 템플릿 생성기 등)로 넘기는 자동화가 훨씬 자연스러워집니다.

3.2 기본은 보수적으로: read-only, 그리고 승인 프롬프트 없음

자동화 관점에서 exec 모드를 쓸 때 가장 중요한 건 "실행 중 사람을 깨우지 않기"입니다. 그래서 codex exec는 보통 샌드박스/승인 정책을 플래그나 설정으로 '선언'해두고, 그 정책 범위 안에서 끝까지 달리게 만드는 식으로 사용합니다.²⁴

다만 여기서 한 가지를 조심해야 합니다. 'exec는 항상 승인 프롬프트가 없다' 또는 '항상 read-only로 시작한다'처럼 단정할 수는 없습니다. 기본값은 CLI 버전, config.toml, 프로파일에 따라 달라질 수 있습니다.

실무적으로는 아래 두 가지만 기억하면 충분합니다.

• 자동화를 하려면, 실행 전에 샌드박스 모드와 approval 정책을 명시하라(설정 파일이든 플래그든).⁴

• 파일 수정까지 포함한 "끝까지 자동" 흐름이 필요하면 --full-auto 같은 의도를 드러내는 스위치를 쓰되, 그 의미(어떤 sandbox/approval 조합의 단축인지)는 codex --help와 공식 레퍼런스에서 확인하라.⁴

예:

codex exec --full-auto "테스트가 깨진 부분을 찾아 최소 변경으로 수정하고 테스트를 다시 통과시켜줘"

다음 장(승인·샌드박스)에서 '안전한 자동화의 기본값'을 구체적으로 설계합니다.

3.3 --json: 자동화의 핵심은 "이벤트 스트림"이다

사람이 모니터링할 때는 자연어 로그로 충분합니다. 하지만 자동화는 "어디까지 진행됐는지", "무엇을 바꿨는지", "왜 실패했는지"를 기계가 이해해야 합니다.

codex exec --json은 실행 과정을 JSONL 이벤트로 스트리밍합니다. 스레드 시작/턴 시작/턴 완료 같은 큰 이벤트와, 명령 실행/파일 변경 같은 아이템 이벤트가 구분되어 나옵니다.⁴

이 모드는 다음에 특히 유리합니다.

• CI에서 Codex 실행을 모니터링하고, 실패 이벤트만 잡아 알림을 보내고 싶을 때

• 파일 변경 이벤트만 수집해 변경 요약을 만들고 싶을 때

• 한 태스크를 여러 단계로 쪼개 "진행률"을 기록하고 싶을 때

3.4 --output-schema: 결과를 '보고서'가 아니라 '데이터'로 받기

자동화는 "멋진 문장"보다 "파싱 가능한 결과"가 필요합니다. --output-schema는 JSON Schema를 주고 그 스키마에 맞는 최종 JSON을 출력하도록 요구할 수 있습니다.⁴

예를 들어 레포 메타데이터를 뽑아 다른 시스템(대시보드/인벤토리)에 적재하려면, 사람 읽기 좋은 설명 대신 스키마 기반 JSON이 훨씬 안정적입니다.

4) resume: 끊긴 문맥을 다시 붙이는 방법(Interactive / Exec)

Codex를 강하게 쓰다 보면 "한 번에 끝내기 어려운 일"이 반드시 생깁니다. 빌드가 오래 걸리거나, 중간에 잠깐 다른 일을 하거나, CI에서 1차 점검만 시키고 사람이 2차 지시를 하기도 합니다.

그럴 때 필요한 게 resume입니다.

4.1 인터랙티브 세션 재개: codex resume

인터랙티브 세션은 codex resume로 다시 열 수 있습니다. 가장 최근 세션은 --last, 특정 세션은 ID로 재개합니다.³

# 세션 선택 UI
codex resume

# 가장 최근 세션
codex resume --last

# 특정 세션 ID
codex resume <SESSION_ID>

여기서 "세션 ID를 어디서 얻나?"가 다음 질문인데, 문서에서는 /status나 로컬 세션 저장소에서 확인할 수 있다고 안내합니다.³

4.2 비대화형 실행의 재개: codex exec resume

자동화 흐름에서도 "이어서 실행"이 가능할 때가 있습니다. 일부 버전/구성에서는 codex exec resume <SESSION_ID> 또는 --last로 직전 실행 문맥을 이어서 후속 지시를 줄 수 있습니다.²⁵

# 직전 exec 실행 문맥에 이어서 추가 지시(지원되는 경우)
codex exec resume --last "방금 변경한 부분에서 회귀 테스트를 추가해줘"

다만 서브커맨드/플래그 형태는 버전별로 달라질 수 있고, '세션 ID를 어디서 확인하는지'나 'exec 실행이 resume 목록에 어떻게 노출되는지'도 변경될 여지가 있습니다.⁴⁵

그래서 이 파트를 팀 표준으로 삼을 때는 다음을 권합니다.

• 우선 codex exec --help로 현재 버전에서 지원되는 문법을 확인한다.

• CI에서 이어달리기가 필요하면, 세션 ID를 로그/아티팩트로 남기는 규칙부터 만든다(후속 작업이 사람에게 넘어올 수 있으므로).

직전 exec 세션에 이어서 추가 지시

codex exec resume --last "방금 변경한 부분에서 회귀 테스트를 추가해줘"

중요한 제약도 함께 기억해야 합니다. 문서에 따르면 보존되는 것은 대화 문맥(컨텍스트)이고, 다음 실행에서의 동작(모델, 출력 형식 등)은 여전히 플래그로 다시 지정할 수 있습니다.4

즉, "문맥은 이어지지만 실행 옵션은 재선언할 수 있다"가 exec resume의 감각입니다.

## 5) 한 번에 체득하는 추천 루틴: TUI에서 다듬고, exec로 굳히고, resume로 이어가기

CLI를 자동화 엔진으로 쓰는 감각은 아래 루틴을 몇 번만 반복하면 잡힙니다.

먼저 TUI에서 작업을 '사람 눈으로' 정리합니다. 레포 구조를 파악하고, 어떤 명령을 돌려야 하는지(테스트, 린트, 포맷) 기준을 세우고, 변경 방향을 합의하는 시간입니다.1

그 다음 같은 일을 `codex exec`로 옮겨 "한 번에 끝까지" 실행해봅니다. 여기서 목표는 대화가 아니라 재현성입니다. 같은 입력이면 비슷한 출력을 얻고, stdout/stderr 분리 덕분에 결과를 파일이나 다른 도구로 넘길 수 있어야 합니다.24

마지막으로, 작업이 길어질수록 resume를 자연스럽게 섞습니다. 로컬에서 하던 일을 다음 날 이어가고, CI에서 돌린 exec 세션을 사람이 후속 지시로 마무리합니다.34

이 루틴이 자리 잡으면, Codex는 "코드 생성기"가 아니라 반복 실행 가능한 자동화 단위가 됩니다.

---

## 참고

[^1]: [Codex CLI (OpenAI Developers)](https://developers.openai.com/codex/cli)

[^2]: [Non-interactive mode (OpenAI Developers)](https://developers.openai.com/codex/noninteractive)

[^3]: [Codex CLI features — sessions & resume (OpenAI Developers)](https://developers.openai.com/codex/cli/features)

[^4]: [Codex CLI reference / command line options (OpenAI Developers)](https://developers.openai.com/codex/cli/reference)

[^5]: [openai/codex (GitHub)](https://github.com/openai/codex)

[^6]: [Slash commands in Codex CLI (OpenAI Developers)](https://developers.openai.com/codex/cli/slash-commands)

[^7]: [CLI options overview (community cheatsheet; verify with `codex --help`)](https://zenn.dev/daishiro/articles/codex-cli-cheatsheet)