OpenAI Codex CLI 명령어 및 설정 치트시트

OpenAI Codex CLI는 커맨드 라인에서 직접 코드베이스를 분석하고 파일을 편집하며 테스트를 실행하고, Codex Cloud 원격 작업 연동 및 MCP를 통한 외부 도구 연결까지 수행하는 OpenAI의 터미널 네이티브 코딩 에이전트입니다.

이 치트시트는 Codex CLI 하위 명령어와 플래그, 샌드박스 및 승인 정책, 대화형 TUI 슬래시 명령어, 키보드 단축키, 그리고 config.toml / AGENTS.md 설정을 다룹니다.

🔗 관련 치트시트: 터미널 AI 코딩 CLI 비교 치트시트 · Claude Code CLI 치트시트 · Antigravity CLI (agy) 치트시트 · AI 에이전트 하네스 엔지니어링 치트시트

1. 설치, 인증 및 핵심 CLI 명령어

1.1 설치 및 인증

작업	명령어	비고
npm 전역 설치	`npm install -g @openai/codex`	표준 크로스 플랫폼 설치 방식
공식 설치 스크립트	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	macOS / Linux용 한 줄 설치 스크립트
브라우저 로그인	`codex login`	ChatGPT Plus / Pro / Team 계정으로 인증
API 키 인증	`export OPENAI_API_KEY="sk-..."`	헤드리스 CI 또는 컨테이너 환경에 적합

1.2 CLI 하위 명령어 및 전역 플래그

명령어 / 플래그	설명	사용 예시
`codex`	현재 디렉터리에서 대화형 TUI 실행	`codex`
`codex "prompt"`	초기 프롬프트를 지정해 대화형 세션 시작	`codex "Debug 500 timeout errors on login"`
`codex exec` / `codex e`	스크립트 및 CI용 비대화형(헤드리스) 실행	`codex exec "Run all unit tests and fix failures"`
`codex exec --json`	추론 과정과 파일 편집 내역의 구조화된 JSON 로그 스트리밍	`codex exec --json "Refactor utils" > run.jsonl`
`codex review`	현재 Git diff에 대한 비대화형 코드 리뷰 수행	`codex review`
`codex resume`	세션 선택기 열기 (`~/.codex/sessions/`에 저장됨)	`codex resume` / `codex resume --last` / `codex resume <id>`
`codex apply` / `codex a`	Codex Cloud 작업에서 생성된 diff를 로컬 작업 공간에 적용	`codex apply <task_id>`
`codex cloud`	원격 Codex Cloud 작업 조회 및 관리	`codex cloud`
`codex mcp`	Model Context Protocol (MCP) 서버 연동 관리	`codex mcp list` / `codex mcp add <name> ...`
`-m, --model <name>`	세션 또는 실행에 사용할 기반 모델 지정	`codex -m gpt-6.1-sol`
`--strict-config`	`config.toml` 구문 및 키를 엄격하게 검증	`codex --strict-config`

2. 샌드박스 및 승인 정책 매트릭스

Codex CLI는 권한을 두 개의 직교 계층으로 분리합니다: **환경이 접근할 수 있는 범위(--sandbox)**와 **사용자에게 확인을 요청하는 시점(--ask-for-approval)**입니다.

플래그	유효한 값	동작 및 권장 용도
`--sandbox <mode>` (별칭 `-s`)	`read-only`	읽기 전용: 파일을 수정하지 않고 코드 조회 및 검색만 허용
	`workspace-write`	작업 공간 쓰기(권장 기본값): 작업 트리 내부에서만 파일 수정 허용
	`danger-full-access`	제한 없는 접근: 전체 파일 시스템 및 시스템 접근 허용(격리된 컨테이너 전용)
`--ask-for-approval <policy>`	`on-request`	권장 기본값: 위험한 작업이 필요할 때 모델이 확인 프롬프트를 표시
	`on-failure`	실패 시에만 승인 요청으로 에스컬레이션 (샌드박스 권한 상승 프롬프트가 중요하면 `on-request` 사용)
	`never`	완전 무인 모드: 대화형 확인을 전혀 묻지 않음 (CI / 자동화 파이프라인용)

⚠️ 지원 중단 및 폐기된 플래그 안내:

**--full-auto**는 v0.128.0부터 **지원 중단(deprecated)**되었습니다. 샌드박스와 승인 정책을 명시적으로 지정하세요: codex --sandbox workspace-write --ask-for-approval on-request "Fix failing tests"

untrusted 승인 정책은 v0.149.0에서 **폐기(retired)**되었습니다. 설정을 on-request로 마이그레이션하세요.

3. 대화형 TUI 슬래시 명령어

대화형 codex TUI 프롬프트에서 /를 입력하면 컨텍스트, 권한 및 워크플로를 제어할 수 있습니다.

3.1 컨텍스트, 모델 및 권한

명령어	기능	참고 및 사용법
`/init`	리포지토리에 맞춘 초기 `AGENTS.md` 파일 생성	새 프로젝트에서 가장 먼저 권장되는 단계
`/status`	활성 모델, 권한 및 토큰 사용량 확인	남은 컨텍스트 용량 모니터링
`/model`	모델 및 Reasoning Effort 단계를 대화형으로 전환	재시작 없이 추론 깊이 조절
`/permissions`	세션 도중 샌드박스 모드 및 승인 정책 변경	필요에 따라 권한을 강화하거나 완화
`/mcp`	연결된 MCP 서버 상태 조회 및 관리	외부 도구 및 DB 연결 상태 점검

3.2 엔지니어링 워크플로 및 세션 제어

명령어	기능	참고 및 사용법
`/plan`	파일을 편집하기 전에 구현 계획을 초안 작성 및 검토	대규모 리팩터링 전에 아키텍처 합의
`/review`	커밋되지 않은 변경 사항에 대한 다각적 코드 리뷰 실행	버그, 엣지 케이스, 보안 위험 탐지
`/diff`	아직 커밋되지 않은 현재 파일 수정 내역 확인	수락 전에 줄 단위 diff 검토
`/fork`	대화 스레드를 별도의 체크포인트로 분기	메인 컨텍스트를 오염시키지 않고 대안 탐색
`/compact`	대화 이력을 요약해 컨텍스트 여유 공간 확보	긴 멀티턴 세션에서 컨텍스트 드리프트 방지
`/copy`	가장 최근에 완료된 응답을 클립보드에 복사	패치나 요약을 빠르게 추출
`/title`	현재 대화 스레드 이름 변경	`codex resume`에서 세션을 쉽게 찾을 수 있음
`/statusline` / `/theme`	하단 상태 표시줄 항목 또는 TUI 색상 테마 사용자 지정	터미널 화면 표시 방식 맞춤 설정
`/prompts:<name>`	사용자 지정 Markdown 프롬프트 템플릿 호출	`~/.codex/prompts/<name>.md` 실행

4. 터미널 단축키 및 입력 구문

단축키 / 구문	동작	효과 및 활용 시나리오
`@<path>`	퍼지 파일 참조	파일 내용을 인라인으로 삽입 (예: `@src/auth.ts`)
`!<command>`	인라인 로컬 셸 명령어	활성 샌드박스 규칙 내에서 셸 명령 실행 (예: `!npm test`)
`Tab`	다음 프롬프트 대기열 등록	Codex가 작업하는 동안 후속 프롬프트, 슬래시 명령어 또는 `!` 명령 예약
`Enter`	실행 중 중단 / 방향 조정	에이전트가 응답하는 도중 추가 지침을 즉시 전달
`Ctrl + G`	외부 편집기 열기	`$VISUAL` / `$EDITOR`(Vim, VS Code 등)에서 여러 줄 프롬프트 작성
`Ctrl + R`	프롬프트 이력 검색	이전에 제출한 프롬프트를 역방향 검색
`Ctrl + L`	화면 지우기 및 다시 그리기	대화 상태를 유지하면서 터미널 화면 정리
`Ctrl + O`	최신 출력 복사	`/copy`와 동일
`Ctrl + X`	키보드 메뉴 열기	키보드 프리셋 및 확장 기능 접근
`Ctrl + C`	취소 / 종료	진행 중인 작업 중단 또는 Codex 세션 종료

5. 설정 파일 및 메모리 계층 (`config.toml` & `AGENTS.md`)

프로젝트 수준 설정은 전역 사용자 기본값을 재정의(오버라이드)합니다.

계층	전역 범위 (모든 리포지토리)	프로젝트 범위 (현재 리포지토리)	용도
핵심 설정	`~/.codex/config.toml`	`.codex/config.toml`	기본 모델, 샌드박스, 승인 정책, 네트워크 토글, MCP
에이전트 지침	`~/.codex/AGENTS.md`	`./AGENTS.md` (리포지토리 루트)	빌드/테스트 명령어, 코딩 표준, 아키텍처 규칙
사용자 지정 프롬프트	`~/.codex/prompts/*.md`	—	재사용 가능한 `/prompts:<name>` 슬래시 명령 템플릿
세션 로그	`~/.codex/sessions/`	—	`codex resume`로 복원되는 영구 세션 로그

권장 최소 `~/.codex/config.toml` 구성

# 기본 모델
model = "gpt-6.1-sol"

# 기본 샌드박스 및 승인 정책
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 기본적으로 샌드박스 내부에서 외부 네트워크 접근 제한
network_access = false