Codex CLI 기술 레퍼런스
핵심 요약
Codex CLI는 단순히 코드를 생성하는 챗봇이 아니라, 코드베이스를 읽고, 패치를 만들고, 명령을 실행하고, 테스트 결과를 반영하는 개발 에이전트입니다.
개발자가 Codex를 효과적으로 사용하려면 다음 5가지를 먼저 이해해야 합니다.
| 핵 심 시스템 | 목적 | 개발자가 얻는 효과 |
|---|---|---|
config.toml | 모델, 권한, MCP, 프로필 설정 | 세션마다 반복 설정하지 않음 |
| Sandbox / Approval | 파일·네트워크·명령 실행 범위 통제 | 안전한 자동화 가능 |
AGENTS.md | 프로젝트별 작업 규칙 제공 | 팀 표준을 에이전트에 내장 |
| MCP | 외부 도구·문서·API 연결 | GitHub, Figma, Sentry, 사내 API 연동 |
| Skills / Plugins | 반복 워크플로 패키징 | 긴 프롬프트를 재사용 가능한 기능으로 전환 |
실무 사용 루프는 다음과 같습니다.
요구사항 입력
→ 관련 파일 지정
→ 계획 수립
→ 패치 생성
→ 테스트/빌드 실행
→ diff 검토
→ 커밋/PR
Codex를 어떻게 이해해야 하나?
Codex는 하나의 모델이 여러 실행 표면(surface)에서 동작하는 구조로 이해하면 쉽습니다.
| 실행 표면 | 적합한 상황 |
|---|---|
| CLI | 터미널 중심 개발, 빠른 수정, 자동화 스크립트 |
| IDE Extension | VS Code, Cursor 등에서 열린 파일·선택 영역 기반 작업 |
| Desktop App | 여러 작업 스레드, Git worktree, 시각적 diff 리뷰 |
| Codex Cloud / Web | 장시간 작업, 비동기 분석, PR 생성 |
| Browser / App 통합 | 웹 기반 디버깅, 문서·외부 서비스와의 연결 |
개발자는 보통 CLI만으로 시작해도 충분하지만, 팀 단위로 확장하려면 다음 순서로 적용하는 것이 좋습니다.
CLI 사용
→ AGENTS.md 작성
→ config.toml 표준화
→ MCP 연결
→ 반복 업무를 Skill로 분리
→ 공유가 필요하면 Plugin으로 패키징
설치 및 인증
macOS / Linux 설치
curl -fsSL https://chatgpt.com/codex/install.sh | sh
또는 npm으로 설치할 수 있습니다.
npm install -g @openai/codex
macOS에서는 Homebrew도 사용할 수 있습니다.
brew install --cask codex
Windows 설치
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
또는 npm을 사용할 수 있습니다.
npm install -g @openai/codex
Windows에서 샌드박스 안정성과 Linux 개발 환경 호환성이 중요하다면 WSL2 기반 실행을 우선 검토합니다.
로그인
codex
처음 실행하면 ChatGPT 계정 로그인 또는 API 키 인증을 선택할 수 있습니다.
일반적으로는 ChatGPT 계정 로그인을 권장합니다.
codex login
codex login status
codex logout
API 키 기반 사용이 필요한 경우:
export CODEX_API_KEY="sk-..."
codex login --with-api-key
첫 번째 세션
프로젝트 루트에서 실행합니다.
cd ~/projects/my-app
codex
처음에는 코드 변경보다 읽기와 요약 작업으로 시작하는 것이 좋습니다.
이 프로젝트의 구조를 요약해 줘.
주요 진입점, 빌드 명령, 테스트 명령을 찾아서 정리해 줘.
변경하지 말고 분석만 해 줘.
이후 작은 작업을 시킵니다.
src/api/users.ts의 getUser 함수에서 null 반환 가능성을 방어해 줘.
변경 후 관련 테스트만 실행해 줘.
작업이 끝나면 diff를 검토합니다.
/diff
/review
/status
기본 명령과 슬래시 명령
CLI 실행 명령
| 명령 | 용도 |
|---|---|
codex | 대화형 TUI 실행 |
codex "prompt" | 초기 프롬프트와 함께 실행 |
codex exec "prompt" | 비대화형 실행 |
codex app | 데스크톱 앱 실행 또는 handoff |
codex mcp | MCP 서버 관리 |
codex completion <shell> | 셸 자동완성 생성 |
예시:
codex "이 저장소의 테스트 실행 방법을 찾아줘"
codex exec "README의 오타를 수정하고 diff를 요약 해줘"
codex mcp --help
자주 쓰는 슬래시 명령
| 명령 | 용도 |
|---|---|
/status | 현재 모델, 권한, 토큰, AGENTS 로딩 상태 확인 |
/model | 모델 변경 |
/permissions | 승인·샌드박스 모드 변경 |
/plan | 계획 모드 진입 |
/diff | 변경 사항 확인 |
/review | 변경 사항 리뷰 |
/compact | 대화 컨텍스트 압축 |
/init | AGENTS.md 초안 생성 |
/mcp | MCP 서버 상태 확인 |
/skills | 사용 가능한 Skill 확인 |
/plugins | Plugin 탐색·관리 |
설정 시스템: config.toml
Codex 설정은 개인, 프로젝트, 시스템 레벨로 나눌 수 있습니다.