Codex CLI는 OpenAI가 만든 터미널 AI 코딩 에이전트입니다. ChatGPT를 브라우저에서 쓰는 것처럼, Codex CLI는 터미널에서 GPT-5.5 등 OpenAI 모델을 바로 불러서 코드 작성, 파일 수정, 명령어 실행까지 시킬 수 있어요. ChatGPT Codex라고도 불리는데, ChatGPT 플랜 또는 OpenAI API 키로 사용할 수 있는 터미널 코딩 도구입니다.
Codex CLI 사용법이 궁금한 분들을 위해, 설치부터 실전 활용까지 한 번에 정리했습니다.
Codex CLI가 뭔가요?
Codex CLI는 터미널(명령 프롬프트)에서 동작하는 AI 코딩 에이전트입니다. 비슷한 도구로는 Anthropic의 Claude Code, 구글의 Gemini CLI가 있어요.
핵심 특징을 정리하면 이렇습니다.
- GPT-5.5 기본 탑재 — 기본 모델은 GPT-5.5이며, 설정에 따라 GPT-5.4 등 다른 모델로 전환할 수도 있습니다
- 오픈소스 — Apache 2.0 라이선스로 GitHub에 공개돼 있어요. 누구나 코드를 볼 수 있습니다
- 샌드박스 격리 — AI가 파일을 수정하거나 명령어를 실행할 때, 안전한 격리 환경에서 먼저 돌려봅니다
- ChatGPT 플랜으로 사용 — Free/Go 플랜도 제한적으로 사용할 수 있고, Plus($20/월) 이상이면 본격적으로 쓸 수 있어요
Codex CLI vs Claude Code vs Gemini CLI 비교
터미널 AI 코딩 도구가 세 개나 되니 헷갈릴 수 있어요. 핵심만 비교하면 이렇습니다.
| Codex CLI | Claude Code | Gemini CLI | |
|---|---|---|---|
| 개발사 | OpenAI | Anthropic | |
| 기본 모델 | GPT-5.5 | Sonnet / Opus | Gemini 2.5 Pro |
| 가격 | Free(제한적)~Plus $20/월~ | Pro $20/월~Max $100~200/월 | 무료 (Antigravity CLI로 전환) |
| 오픈소스 | O (Apache 2.0) | X (독점) | O (Apache 2.0) |
| 샌드박스 | 기본 내장 (3단계 옵션) | 있음 (/sandbox · OS 레벨) | 있음 (Docker · Seatbelt) |
| 코딩 강점 | 속도, 토큰 효율 | 복잡한 코드, 정확도 | 검색 연동 |
| 웹 검색 | 제한적 | 가능 | 구글 검색 내장 |
| 멀티 에이전트 | 병렬 실행 지원 | 서브에이전트 | 제한적 |
간단히 정리하면, Codex CLI는 빠른 속도와 안전한 샌드박스가 강점이고, Claude Code는 복잡한 코드 작업의 정확도가 강점입니다. 참고로 Gemini CLI는 2026년 6월 18일부로 종료되었고, 후속 도구인 Antigravity CLI(agy)로 전환되었습니다.
Codex CLI 설치 방법
Codex 설치는 간단합니다. Windows, Mac, Linux 모두 지원해요.
사전 준비
- Node.js 22 이상 (npm 설치 시에만) — npm으로 설치할 때만 필요합니다. nodejs.org에서 LTS 버전을 설치하세요. 아래 Homebrew·사전 빌드 바이너리 방식은 Node.js 없이도 설치됩니다
- ChatGPT 플랜 — Free/Go 플랜도 제한적으로 사용할 수 있지만, 본격적으로 쓰려면 Plus($20/월) 이상을 권장합니다
Windows에서 Codex 설치
PowerShell을 열고 아래 명령어를 실행하면 됩니다.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"또는 npm으로 설치할 수도 있어요.
npm install -g @openai/codex주의: npm i -g codex라고 치면 안 됩니다. 이건 2012년에 만들어진 전혀 다른 패키지예요. 반드시 @openai/codex로 설치하세요.
Mac / Linux에서 Codex 설치
curl -fsSL https://chatgpt.com/codex/install.sh | shMac은 Homebrew로도 가능합니다.
brew install --cask codex설치 확인
codex --version버전 번호가 표시되면 Codex 설치가 완료된 겁니다.
Codex CLI 첫 실행 — 인증하기
설치 후 처음 codex를 실행하면 인증 화면이 나옵니다.
codex“Sign in with ChatGPT”를 선택하세요. 브라우저가 열리고, ChatGPT 계정으로 로그인하면 자동으로 인증이 완료됩니다. API 키를 따로 발급받을 필요가 없어요.
인증이 끝나면 바로 Codex CLI를 사용할 수 있습니다.
Codex CLI 사용법 — 승인 정책과 샌드박스
Codex CLI 사용법에서 가장 중요한 건 AI에게 얼마나 자유를 줄지 정하는 부분입니다. 여기엔 서로 독립된 두 개의 축이 있어요.
- 승인 정책 (
--ask-for-approval) — AI가 명령을 실행하기 전에 얼마나 자주 물어볼지 - 샌드박스 (
--sandbox) — AI가 파일·네트워크에 어디까지 접근할 수 있는지 (아래 샌드박스 항목 참고)
이 둘은 별개입니다. “승인 없이 실행할지”와 “파일 접근 범위”를 따로 정할 수 있어요. 예전 버전의 --approval-mode 방식은 현재 이렇게 두 축으로 나뉘었습니다.
승인 정책 (–ask-for-approval)
- untrusted — 안전한 읽기 작업만 자동으로 하고, 변경이 생기는 명령은 매번 승인받습니다 (가장 안전)
- on-request — 작업 디렉토리 안에서는 읽기·수정·명령 실행을 자동으로 진행합니다
- never (
-a never) — 승인 프롬프트를 끕니다. 어떤 샌드박스와도 함께 쓸 수 있어요
한 번에 자동으로 — –full-auto
codex --full-auto--full-auto는 “승인은 필요할 때만(on-request) + 샌드박스는 워크스페이스 쓰기(workspace-write)”를 한 번에 켜주는 단축 옵션입니다. 빠르게 작업할 때 편리하지만, 작업 디렉토리는 자유롭게 수정되니 중요한 폴더에서는 주의하세요.
처음 써본다면 옵션 없이 codex로 시작하면 안전한 기본값으로 동작합니다. 현재 설치한 버전에서 쓸 수 있는 정확한 옵션·명령은 codex --help나 실행 중 /help로 확인하는 게 가장 확실해요.
Codex CLI 실전 활용법 5가지
Codex CLI를 실제로 어떻게 쓰는지 사용법을 정리했습니다.
1. 코드 작성
codex "Python으로 CSV 파일을 읽어서 날짜별로 정렬하는 스크립트 만들어줘"작업 디렉토리에서 바로 실행하면, 파일을 만들고 코드를 작성해줍니다.
2. 버그 수정
codex "이 프로젝트에서 TypeError가 나는 원인을 찾아서 고쳐줘"프로젝트 폴더 전체를 읽고, 에러 원인을 찾아서 수정 사항을 제안합니다.
3. 코드 설명
codex "이 폴더에 있는 코드가 뭘 하는 건지 설명해줘"낯선 코드베이스를 파악할 때 유용합니다.
4. 테스트 작성
codex "src/utils.py에 대한 유닛 테스트를 작성해줘"기존 코드를 분석해서 테스트 코드를 자동으로 만들어줍니다.
5. 리팩토링
codex "이 함수를 더 읽기 쉽게 리팩토링해줘"코드 구조 개선도 가능합니다. 단, 중요한 코드라면 Suggest 모드에서 변경 사항을 꼭 확인하세요.
Codex CLI 샌드박스 — 안전장치
Codex CLI는 샌드박스를 기본으로 내장하고 있습니다. Claude Code(/sandbox)나 Gemini CLI(Docker·Seatbelt)도 샌드박스를 제공하지만, Codex는 설치 직후부터 샌드박스가 기본 적용된다는 점이 특징이에요.
샌드박스가 하는 일은 간단합니다. AI가 실행하는 명령어와 파일 수정을 제한된 권한 범위 안에서만 동작하도록 가둡니다. 실수로 중요한 파일을 삭제하거나 위험한 명령어를 실행하는 걸 막아주는 거예요.
Codex CLI의 샌드박스 옵션은 --sandbox 뒤에 아래 3가지 중 하나를 붙여서 지정합니다.
- read-only — 파일 읽기만 가능. 가장 안전합니다
- workspace-write — 작업 디렉토리(워크스페이스) 안에서만 파일 수정·명령 실행 허용
- danger-full-access — 샌드박스 제한 해제(파일·네트워크 전체 접근). 꼭 필요할 때만
codex --sandbox read-only "이 프로젝트 구조를 분석해줘"처음 써보시는 분이라면 read-only로 시작하는 게 좋습니다.
Codex CLI 가격 — ChatGPT 구독에 포함
Codex CLI는 별도 결제가 아니라 ChatGPT 구독에 포함돼 있습니다.
| 플랜 | 가격 | Codex 사용량 |
|---|---|---|
| ChatGPT Free | 무료 | 체험용(매우 제한적) |
| ChatGPT Go | $8/월 | 입문용(제한적) |
| ChatGPT Plus | $20/월 | 기본 사용량 |
| ChatGPT Pro (5x) | $100/월 | Plus 대비 약 5배 |
| ChatGPT Pro (20x) | $200/월 | Plus 대비 약 20배 |
이미 ChatGPT Plus를 구독하고 있다면 추가 비용 없이 Codex CLI를 바로 쓸 수 있습니다. Free/Go 플랜으로도 제한적으로 사용할 수 있지만, 실용적으로 쓰려면 Plus 이상을 권장합니다. 플랜별 Codex 사용량 한도는 프로모션·시점에 따라 달라지니 공식 가격 페이지에서 확인하세요.
참고: ChatGPT 구독 외에 OpenAI API 키로도 Codex CLI를 쓸 수 있습니다(사용량 기반 과금). 팀·조직이라면 Business·Enterprise 플랜에서도 사용할 수 있어요.
Codex CLI 주의할 점
- 설치 방식에 따라 Node.js가 필요합니다 — npm으로 설치하면 Node.js 22 이상이 필요하지만, Homebrew나 사전 빌드 바이너리로 설치하면 Node.js 없이도 동작합니다
- Windows도 지원합니다 — npm(Node.js 22+) 또는 사전 빌드 바이너리로 설치할 수 있어요. 일부 기능은 WSL2 환경에서 더 안정적이니, 문제가 생기면 WSL2를 함께 써보세요
- 패키지 이름을 정확히 입력하세요 —
@openai/codex가 맞습니다.codex만 치면 전혀 다른 패키지가 설치돼요 - ChatGPT 플랜 또는 API 키가 필요합니다 — Free 플랜으로도 제한적 사용은 가능하지만, 본격적으로 활용하려면 Plus 이상을 권장합니다
- 민감한 파일에 주의하세요 — 프로젝트 폴더에
.env, API 키, 비밀번호 등이 있으면 AI가 읽을 수 있습니다. 중요한 파일은.codexignore에 추가하거나, 승인 정책을 보수적으로 설정하세요
정리하면
Codex CLI는 OpenAI의 터미널 AI 코딩 에이전트이고, 샌드박스를 통한 안전한 실행이 가장 큰 특징입니다.
- 이미 Claude Code를 쓰고 계시다면 → Codex CLI를 보조 도구로 같이 써보세요. 빠른 작업이나 교차 검증에 유용합니다
- ChatGPT Plus를 구독 중이라면 → 추가 비용 없이 바로 쓸 수 있으니 설치해보시는 걸 추천합니다
- 터미널 AI가 처음이라면 → ChatGPT Free 플랜으로 Codex CLI를 체험해보고, 마음에 들면 Plus로 업그레이드하는 방법도 있어요
Codex CLI 설치에 5분이면 충분합니다. ChatGPT 구독이 있으시다면 한번 써보세요.
※ Codex CLI 사용법은 2026년 6월 기준입니다. 공식 문서는 OpenAI Codex CLI 공식 문서에서 확인하실 수 있어요.