Codex CLI 사용법: 설치부터 첫 코드 생성까지
codex cli 사용법 한 줄 요약
codex cli 사용법의 핵심은 설치 명령 하나보다 승인 범위를 먼저 이해하는 거예요.npm i -g @openai/codex로 설치한 뒤codex를 실행하면 ChatGPT 계정이나 API 키로 로그인해서 바로 시작할 수 있고, Windows는 아직 실험 지원이라 초보자면 WSL 작업공간 쪽이 덜 헷갈립니다. 자동 실행은read-only→workspace-write→--full-auto순서로 올리면 되고,--full-auto도 워크스페이스 밖 수정이나 네트워크 접근에선 멈출 수 있어요. (developers.openai.com)
터미널 열고 npm i -g @openai/codex 쳤는데 바로 끝날 줄 알았죠. 근데 실제로는 Node 버전에서 한 번, 로그인 방식에서 한 번, 승인 모드에서 또 한 번 멈칫하게 돼요. 저도 처음엔 한 세션에 프롬프트를 다 몰아넣었다가 컨텍스트만 불어나서 엉뚱한 파일을 건드리는 일이 자꾸 생기더라고요.
그래서 초보자 기준 codex cli 사용법은 “설치 먼저, 권한 범위 먼저, 자동화는 나중” 순서로 잡는 게 덜 꼬여요. 이미 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드를 따라가봤다면 비슷해 보여도 승인 정책 감각은 꽤 다르게 느껴질 겁니다.
여기서는 딱 세 가지만 챙길게요. 설치가 왜 막히는지, --full-auto를 어디까지 믿어도 되는지, 그리고 실제 프로젝트에서 첫 코드 생성 작업을 어떤 식으로 잘라 맡겨야 덜 헤매는지. 참고로 작업 두 개를 한 디렉토리에 몰아넣는 순간부터 컨텍스트가 급격히 지저분해지거든요. 기능별로 디렉토리나 worktree를 갈라두는 편이 훨씬 낫더라고요.
Codex CLI가 뭔데? 30초 개념 정리
Codex CLI를 처음 보면 그냥 터미널 챗봇 같아요. 근데 실제 포인트는 대화형 codex, 비대화형 codex exec, 그리고 승인 범위를 어디까지 열지 구분하는 데 있어요. (developers.openai.com)
openai codex 터미널 쪽은 로컬에서 저장소를 읽고, 바꾸고, 명령을 돌리는 오픈소스 CLI예요. npm으로 설치하고 Node.js 22 이상에서 돌아갑니다. 첫 실행에서 ChatGPT 계정이나 API 키를 고르는 흐름도 여기서 바로 이어져요. (developers.openai.com)
근데 굳이 터미널에서 해야 할까요? 파일 수정과 명령 실행을 한 흐름에 묶을 수 있어서, IDE 붙이기 애매한 자동화 작업에서 진가가 나와요.
- 먼저 구분할 것
codex는 대화형 세션codex exec는 반복 가능한 자동 실행read-only와workspace-write차이가 사고 범위를 가름함--full-auto는 “다 허용”이 아니라 “기본 승인선이 낮아진 자동 작업”에 가까움
| 항목 | 초보자 기준 해석 | 왜 먼저 알아야 하나 |
|---|---|---|
| 대화형 시작 | codex로 바로 물어보고 수정 확인 |
첫 삽질이 적음 |
| 자동 실행 | codex exec로 한 번에 끝내기 |
스크립트화하기 좋음 |
| 승인 정책 | 멈춰서 물어보는 범위 결정 | 파일 사고 예방 |
| 샌드박스 | 어디까지 쓰고 실행하는지 결정 | 네트워크/외부 경로 통제 |
Codex CLI 설치: npm 한 줄과 Node.js 체크
설치는 길지 않아요. 근데 Node 버전 하나 틀리면 로그인 전부터 바로 막힙니다.
공식 CLI 페이지는 npm i -g @openai/codex 전역 설치와 첫 실행 codex를 안내하고, GitHub README는 brew install --cask codex도 같이 적어둡니다. 저장소 package.json의 엔진 조건은 Node 22 이상이에요. 설치하다 막히면 바로 자주 막히는 에러 4가지와 해결법으로 내려가도 됩니다. (developers.openai.com)
설마 Node 버전 안 보고 바로 설치부터 하는 건 아니죠?
설치 전 체크리스트
node -v가 22 이상인지 보기npm -v가 정상 출력되는지 보기- 예전 API 키 로그인 이력이 있으면 메모해두기
- 작업 디렉토리를 Git 저장소 안에서 열 건지 정하기
# Node 버전 확인
node -v
# npm으로 Codex CLI 설치
npm i -g @openai/codex
# Homebrew를 쓴다면 이 방법도 가능
# brew install --cask codex
# 설치 확인
codex --version
# 첫 실행
codex
처음 codex를 치면 로그인 방식을 고르라고 나와요. ChatGPT 구독 있으면 ChatGPT 계정으로, API 키를 쓰고 싶으면 API 키로 잡으면 됩니다. 예전에 API 키로 썼다가 구독 로그인으로 바꾸려면 codex logout 한 번 치고 다시 시작하면 돼요.
Codex full-auto 모드까지: 승인 방식 한 번에 이해하기
커뮤니티에선 suggest, auto, full-auto처럼 뭉뚱그려 말하곤 해요. 근데 최신 공식 문서는 read-only, workspace-write, danger-full-access, --full-auto 조합으로 설명하니, 초보자는 “어디까지 자동이고 어디서 멈추는지”만 잡으면 됩니다. (developers.openai.com)
근데 이걸 왜 이렇게 쪼개놨을까요? 샌드박스(파일 범위)와 승인 정책(멈추는 타이밍)이 서로 다른 축이라 따로 두는 편이 실무에서 덜 꼬이거든요.
처음엔 아래 실전 워크플로우: codex cli 사용법으로 첫 코드 만들기 예제를 보고 다시 올라와도 괜찮아요. 실제로 한 번 돌려보면 표가 훨씬 빨리 읽힙니다.
| 초보자식 구분(공식 명칭 아님) | 실제 옵션 | 자동으로 되는 일 | 여기서 멈춤 |
|---|---|---|---|
| 확인형 | --sandbox read-only --ask-for-approval on-request |
파일 읽기, 답변 | 수정, 명령 실행, 네트워크 |
| 작업형 | --sandbox workspace-write --ask-for-approval untrusted |
파일 읽기/수정 | 신뢰 못 하는 명령, 외부 실행 경로 |
| 맡김형 | --full-auto |
워크스페이스 안 읽기/쓰기/명령 | 워크스페이스 밖 수정, 네트워크 |
| 완전 개방형 | --dangerously-bypass-approvals-and-sandbox |
거의 전부 | 사실상 멈춤 없음, 초보자 비추천 |
Git 저장소 안에서 시작하면 공식 문서는 Auto 쪽을 기본 추천하고, Git 없는 폴더는 read-only 쪽으로 시작하라고 안내해요. workspace-write는 기본적으로 네트워크가 꺼져 있고, 예전 글에서 자주 보이는 on-failure는 deprecated라서 지금은 on-request나 never 기준으로 다시 읽는 게 맞습니다. (developers.openai.com)
# 같은 작업으로 모드 차이 보기
codex "README.md를 한국어로 번역해줘"
read-only에선 수정 전 멈춰요.workspace-write에선 워크스페이스 안 수정이 훨씬 매끈합니다.--full-auto는 반복 작업에 편한데, 바깥 경로나 네트워크가 걸리면 또 멈춰요. 바로 이 경계에서 가장 자주 막힙니다.
실전 워크플로우: codex cli 사용법으로 첫 코드 만들기
codex cli 사용법은 프롬프트를 길게 꾸미는 것보다 작업 단위를 잘 자르는 게 먼저예요. 처음엔 저장소 전체를 맡기지 말고, 파일 하나와 결과 하나가 분명한 예제로 시작하세요.
첫 작업부터 full-auto? 직접 해봤는데, 이러면 어디서 꼬인 건지 추적이 안 돼요.
모드가 헷갈리면 위 Codex full-auto 모드까지: 승인 방식 한 번에 이해하기 표만 다시 보고 오면 됩니다. 공식 문서는 codex를 대화형 시작점으로, codex exec를 안정판 비대화형 실행으로 안내하고 있어요. 프롬프트 문자열도 바로 넘길 수 있습니다. (developers.openai.com)
1단계: 실습 디렉토리 만들기
# 실습용 디렉토리 만들기
mkdir codex-csv-demo
cd codex-csv-demo
# 샘플 CSV 준비
printf "name,age\nmin,29\nseo,31\n" > sample.csv
Git 저장소 안이면 Codex가 자동으로 Auto 모드를 추천하고, Git 없는 폴더면 read-only로 시작해요.
2단계: 대화형으로 한 번 맡기기
# 대화형 세션과 함께 프롬프트 전달
codex "sample.csv를 읽어서 output.json으로 저장하는 Python 스크립트 csv_to_json.py를 만들어줘. 실행 방법도 README.md에 적어줘."
작업 두 개 이상이면 한 폴더에 다 우겨넣지 마세요. 직접 해보면 프롬프트는 멀쩡한데 다른 파일까지 건드리는 순간이 오거든요. 기능별 디렉토리나 worktree를 따로 파두는 편이 훨씬 덜 꼬입니다.
3단계: 반복 작업이면 codex exec로 고정하기
# 비대화형 자동 실행 — 프롬프트가 길어도 따옴표 안에서 한 줄로 입력
codex exec "현재 디렉토리에서 sample.csv를 읽어 output.json을 만드는 csv_to_json.py와 README.md를 만들어줘. 마지막에 생성 파일 목록과 실행 명령을 요약해줘."
4단계: 생성물 직접 돌려보기
# 생성된 스크립트 실행 예시
python3 csv_to_json.py sample.csv output.json
# 결과 확인
cat output.json
| 생성물 | 기대 상태 | 사람이 꼭 볼 것 |
|---|---|---|
csv_to_json.py |
CSV를 JSON으로 바꾸는 스크립트 | 예외 처리, 인코딩 |
output.json |
실제 JSON 파일 생성 | 필드명, 값 타입 |
README.md |
실행 순서 정리 | 복붙 가능한지 |
| 테스트 로그 | 있으면 더 좋음 | 실패 케이스 빠짐 없는지 |
codex exec로 돌리면 비대화형이라 스크립트 안에 넣기 좋아요. CI에서 반복 작업을 걸 때 이쪽이 훨씬 깔끔합니다. 대화형 codex는 탐색용, codex exec는 고정 작업용으로 나눠 쓰면 컨텍스트가 안 꼬여요.
자주 막히는 에러 4가지와 해결법
초보자가 오래 막히는 지점은 설치 실패보다 애매한 상태예요. 명령은 맞는데 버전, 로그인 이력, 승인 정책이 서로 엇갈리면 이상하게 시간을 많이 먹죠.
이상하게 로그인만 실패하고 설치는 멀쩡한 적, 있었죠? 대부분 예전 API 키 로그인 상태가 셸에 남아서 새 세션을 덮어버려서 그래요. codex logout 한 번 치고 다시 들어가면 풀리는 경우가 많아요.
버전 체크부터 다시 할 거면 Codex CLI 설치: npm 한 줄과 Node.js 체크로 올라가세요. 거기서부터 다시 잡는 게 제일 빠릅니다.
| 증상 | 먼저 볼 것 | 바로 할 일 |
|---|---|---|
| 설치는 됐는데 실행이 이상함 | node -v |
Node 22 이상으로 맞추기 |
| 예전 API 키로 쓰다 플랜 로그인으로 바꾸려 함 | 로그인 이력 | codex logout 후 codex 재실행 |
--full-auto인데 중간에 멈춤 |
워크스페이스 밖 경로, 네트워크 접근 | sandbox/approval 범위 다시 보기 |
| 예전 블로그 플래그가 안 먹음 | on-failure 같은 구식 옵션 |
on-request, never, --sandbox 조합 기준으로 다시 쓰기 |
대부분 아래 두 줄이면 바로 풀려요.
# Node 버전 올리기 (nvm 기준)
nvm install 22 && nvm use 22
# 로그인 꼬였을 때
codex logout && codex
workspace-write는 네트워크가 기본 꺼짐이라는 거, 표 보면 알 것 같은데 실제론 의외로 자주 잊습니다. on-failure는 deprecated라서 on-request나 never로 바꿔 읽으세요. Windows면 WSL 작업공간에서 다시 시작하는 편이 훨씬 낫더라고요. (github.com)
자주 묻는 질문
Q1. Codex CLI는 무료인가요?
A: 2026년 4월 11일 기준 OpenAI 도움말은 Codex를 ChatGPT Plus, Pro, Business, Enterprise/Edu에 포함한다고 적고 있고, 한시적으로 Free와 Go에도 포함된다고 안내해요. API 키로 별도 호출하면 codex-mini-latest 기준 입력 $1.50, 캐시 입력 $0.375, 출력 $6.00 / 1M tokens라서 구독 로그인과 API 사용은 계산법이 다릅니다. (help.openai.com)
Q2. ChatGPT Plus만 있으면 Codex CLI 로그인 되나요?
A: 첫 실행 codex에서 ChatGPT 계정이나 API 키로 인증할 수 있어요. 예전에 API 키로만 쓰던 환경이면 패키지 업데이트 뒤 codex logout을 한 번 치고 다시 codex를 실행해야 구독 기반 접근으로 바뀝니다. (developers.openai.com)
Q3. full-auto 모드면 내 파일이 다 바뀌나요?
A: 그렇게 보면 안 돼요. --full-auto는 --sandbox workspace-write --ask-for-approval on-request처럼 동작하고, 기본 workspace-write는 네트워크가 꺼져 있어서 워크스페이스 밖 수정이나 네트워크 접근에선 여전히 승인 요청이 뜰 수 있어요. (developers.openai.com)
Q4. 업데이트 후 예전 플래그가 왜 안 먹어요?
A: 최신 문서는 on-failure를 deprecated로 적고 on-request나 never를 권장해요. 그래서 예전 블로그 글이나 스크립트를 그대로 복붙하면 이상하게 안 맞는 경우가 생깁니다. (developers.openai.com)
Q5. 여러 프로젝트를 동시에 돌려도 되나요?
A: 됩니다. 다만 디렉토리 하나에 전부 몰아넣지 말고 feature 단위로 worktree나 별도 폴더를 나누세요. 직접 해보면 컨텍스트가 섞이는 문제가 확 줄어요.
다음 단계
지금은 위 실전 예제 프롬프트부터 한 번 돌려보세요. mkdir codex-csv-demo 치고 CSV 하나 만들어서 codex에 맡겨보는 게 가장 빠릅니다. 설치 감이 잡히면 Claude Code 설치 가이드로 넘어가서 두 CLI의 손맛 차이까지 붙이면 돼요. 둘 다 터미널 에이전트인데 승인 정책 감각이 꽤 달라서, 직접 비교해보면 어떤 작업에 뭘 쓸지 감이 빨리 옵니다.
