Chapter 3: Codex 첫걸음 — Claude Code 사용자를 위한 빠른 적응 가이드
3.1 처음 실행하는 사람을 위해
claude 명령에는 익숙하다. 이제 처음으로 codex 명령을 실행하려 한다. 무엇이 같고 무엇이 다른가?
이 챕터는 그 질문에 답한다. 세 가지를 설치하고, 세 가지 멘탈 모델을 전환하고, 가장 자주 쓰는 명령을 대응표로 정리한다.
3.2 설치 — 세 가지
1. Codex CLI 설치
npm install -g @openai/codex
또는 Homebrew를 선호한다면:
brew install openai-codex
CLI 버전 0.125 이상이 필요하다. 확인:
codex --version
버전이 낮으면 npm update -g @openai/codex로 업그레이드한다 [OpenAI, 2026].
2. ~/.codex/config.toml 작성
처음 실행하면 자동으로 기본 파일이 생성되지만, GPT-5.5를 쓰려면 직접 설정해야 한다:
# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model을 설정하지 않으면 기본값 gpt-5.4가 사용된다. model_reasoning_effort는 minimal / low / medium / high / xhigh 중 선택한다 (모델별 가용 옵션 차이 있음). 일상 작업에는 medium, 복잡한 리팩터링에는 high를 권장한다 [OpenAI, 2026].
3. 첫 AGENTS.md 작성
프로젝트 루트에 AGENTS.md를 만든다. 최소한 이 정도면 시작할 수 있다:
# Project Rules
## Stack
- Node.js / TypeScript
- Express.js API
- PostgreSQL
## Code Style
- Use ESLint + Prettier (configs in repo)
- TypeScript strict mode
- Functions < 40 lines
## Testing
- Jest for unit tests
- Run `npm test` before any commit
AGENTS.md의 역할: "이번 대화에서 Claude에게 말하는 것"을 "Codex가 모든 태스크에서 따르는 규칙"으로 바꾸는 것이다 [OpenAI, 2026]. 한번 써두면 매 태스크마다 반복하지 않아도 된다.
3.3 멘탈 모델 전환 — 세 가지
전환 1: "이번 대화" → "규칙 파일"
Claude Code에서: 매 대화 시작에 컨텍스트를 주거나 CLAUDE.md에 전역 설정을 써둔다.
Codex에서: AGENTS.md가 그 역할을 한다. 차이점은 AGENTS.md가 더 구조화되어 있고, 프로젝트 루트뿐 아니라 서브디렉토리에도 둘 수 있으며, Amp·GitHub Copilot·Google Jules 같은 다른 AI 도구도 같은 파일을 읽는다 [Foundation, 2026].
전환 2: "터미널 세션" → "태스크"
Claude Code에서: 터미널을 열고 대화하며 작업한다. 세션이 끝나면 맥락이 사라진다.
Codex에서: 태스크 단위로 작업한다. 각 태스크가 독립 브랜치에서 실행되고 PR로 완료된다. 여러 태스크를 동시에 큐에 넣을 수 있다 [DeployHQ, 2026]:
# 태스크 실행
codex exec "refactor the auth module to use JWT"
# 여러 태스크 동시에
codex exec "add input validation to all API endpoints" &
codex exec "write unit tests for UserService" &
전환 3: "도구별 권한" → "sandbox 레벨"
Claude Code에서: 매 도구 실행 시 허용할지 묻거나, allowedTools로 미리 허용한다.
Codex에서: sandbox_mode로 한 번에 설정한다. workspace-write가 기본 시작점이다 — 현재 작업 디렉토리 내에서만 파일을 쓸 수 있다 [OpenAI, 2026].
3.4 명령어 대응표 — Claude Code → Codex
| 작업 | Claude Code | Codex | 비고 |
|---|---|---|---|
| 시작 | claude |
codex |
— |
| 새 태스크 실행 | 터미널에 프롬프트 입력 | codex exec " (또는 codex e) |
non-interactive 1회 실행. Interactive 모드는 인자 없이 codex |
| 설정 파일 | ~/.claude/CLAUDE.md (global) |
~/.codex/config.toml |
형식 다름 |
| 프로젝트 규칙 | CLAUDE.md (project) |
AGENTS.md (project) |
— |
| 서브에이전트 정의 | .claude/agents/ |
.codex/agents/ |
형식 다름 |
| skills 정의 | .claude/skills/ |
.codex/skills/ |
유사 |
| 모델 선택 | claude --model claude-opus-4-7 |
config.toml: model = "gpt-5.5" |
— |
| effort 설정 | 내장 (adaptive) | config.toml: model_reasoning_model_reasoning_model_reasoning_effort = "xhigh" |
— |
| 코드 리뷰 | /ultrareview |
— (PR로 검토) | Claude Code 전용 |
| 실행 취소 | /undo |
브랜치 버리기 | 방식 다름 |
Claude Code에만 있는 것: /ultrareview, hooks 시스템(Python/bash), Agent Teams의 SendMessage 런타임 협업.
Codex에만 있는 것: branch-per-task 자동화, TOML 기반 에이전트, Linux Foundation AGENTS.md 표준 호환.
3.5 처음 태스크 실행하기
설치가 완료됐으면 바로 실행해보자. Saladi의 "Codex 101" [Saladi, 2026]에서 뽑은 바로 쓸 수 있는 프롬프트:
리팩터링:
codex exec "refactor src/auth.ts — extract token validation into a pure function, add JSDoc"
테스트 추가:
codex exec "write Jest tests for UserService.createUser(), mock the database"
버그 수정:
codex exec "fix the race condition in connection pool — see issue #42"
프롬프트가 구체적일수록 결과가 좋다. "리팩터링해줘"보다 "src/auth.ts의 토큰 검증 로직을 순수 함수로 분리하고 JSDoc을 추가해줘"가 더 좋은 결과를 낸다 [Proser, 2026].
3.6 처음 겪는 차이점과 대처법
"PR이 뭔가요?": Codex의 branch-per-task 방식이 낯설 수 있다. codex exec이 완료되면 새 브랜치에 변경사항이 커밋된다. git checkout 으로 확인하고 git merge 또는 git rebase로 반영한다.
"AGENTS.md를 얼마나 자세히 써야 하나요?": 처음엔 간단하게 시작한다. Stack 정보 + 코드 스타일 기본값 + 테스트 명령어만 있어도 충분하다. 작업하면서 "Codex가 자꾸 틀리는 것"이 생기면 그때 AGENTS.md에 추가한다 [Code, 2026].
"모델이 GPT-5.5가 아닌 것 같아요": ~/.codex/config.toml에 model = "gpt-5.5"가 있는지 확인한다. Pro tier 이상 구독이 필요할 수 있다 [OpenAI, 2026].
5장에서는 AGENTS.md를 실제로 잘 쓰는 법과 서브에이전트 셋업을 다룬다. 지금은 세 가지 설치와 세 가지 멘탈 모델 전환이면 충분하다.
참고문헌
- OpenAI, "Codex CLI changelog," 2026. [OpenAI, 2026]
- OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
- OpenAI, "Codex config basic setup," 2026. [OpenAI, 2026]
- OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
- AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
- DeployHQ, "Codex CLI getting started guide," 2026. [DeployHQ, 2026]
- Saladi, "Codex 101: 33 ready-to-use prompts," 2026. [Saladi, 2026]
- TechBytes, "Claude Code command cheatsheet," 2026. [TechBytes, 2026]
- Augment, "How to write a great AGENTS.md," 2026. [Code, 2026]
- Zack Proser, "Codex daily-use review," 2026. [Proser, 2026]