시작하기

설치

npm install -g @openai/codex

인증

export OPENAI_API_KEY="sk-..."

셸 프로파일 또는 .env 파일에 설정

첫 실행

codex "explain this project"
codex "add input validation to app.py"

명령어

대화형 (기본값)

codex                       # start interactive session
codex "fix the login bug"   # with initial prompt

codex exec

codex exec "write unit tests for utils.py"
codex exec "refactor db.py to use async"

비대화형 — 작업이 완료될 때까지 실행

codex review

codex review                # review staged changes
codex review --diff HEAD~3  # review last 3 commits

모드

승인 모드

suggest	제안된 변경사항 표시, 모든 파일 편집과 명령 실행 시 승인 필요
auto-edit	파일 편집 자동 적용, 셸 명령 실행 시 승인 필요
full-auto	승인 없이 편집 및 명령 실행

모드 설정

codex --approval-mode suggest "add tests"
codex --approval-mode auto-edit "refactor"
codex --approval-mode full-auto "fix lint"

설정

설정 파일

# ~/.codex/config.yaml
model: o4-mini
approval_mode: suggest
providers:
  - name: openai
    api_key_env: OPENAI_API_KEY

프로젝트별 재정의: 프로젝트 루트의 .codex/config.yaml

프로젝트 지침

# AGENTS.md (in project root)
- Run tests with: uv run pytest
- Use ruff for linting
- Never modify migration files

유용한 설정 옵션

model	사용할 모델 (예: `o4-mini`, `o3`)
approval_mode	기본 승인 모드
providers	API 제공자 설정 (키, 베이스 URL)
history	대화 히스토리 저장: `true` / `false`

샌드박싱

동작 방식

Codex는 의도치 않은 부작용을 방지하기 위해 샌드박스 환경에서 명령을 실행합니다. 네트워크 접근은 기본적으로 비활성화됩니다. 파일 쓰기는 프로젝트 디렉토리로 제한됩니다.

샌드박스 옵션

macOS	Apple Seatbelt (기본값, 내장)
Linux	Docker 기반 샌드박스
--full-auto	샌드박스 활성화 필요
--dangerously-auto-approve	샌드박스 건너뜀 (비권장)

팁

효과적인 프롬프트

Be specific	"fetch_data()에 재시도 로직 추가" > "코드 개선"
Reference files	"src/auth.py의 버그 수정"으로 범위 좁히기
State constraints	"공개 API를 변경하지 마세요"로 제약 설정
Iterate	같은 세션에서 후속 질문으로 개선

워크플로우 패턴

# Explore → plan → execute
codex "explain the auth module"
codex "plan how to add OAuth support"
codex --approval-mode auto-edit "add OAuth"

# Review before commit
git add -A
codex review

일반 플래그

--model, -m	이 세션의 모델 재정의
--approval-mode	승인 모드 설정
--quiet, -q	최소 출력
--no-project-doc	AGENTS.md 무시

OPENAI CODEX CLI 빠른 참조