# OpenAI Codex CLI 빠른 참조

*CLI 사용법, 모드, 설정, 주요 명령어*

> Source: OpenAI Codex Documentation (github.com/openai/codex) · MIT

## 시작하기

### 설치

```
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
```

## 모드

### 승인 모드

| Command | Description |
|---------|-------------|
| `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
```

### 유용한 설정 옵션

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

## 샌드박싱

### 동작 방식

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

### 샌드박스 옵션

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

## 팁

### 효과적인 프롬프트

| Command | Description |
|---------|-------------|
| `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
```

### 일반 플래그

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