코덱스 CLI 사용법: 설치, 로그인, 승인·샌드박스 설정 순서

코덱스 CLI(Codex CLI)는 터미널에서 OpenAI의 코딩 에이전트에게 작업을 시키는 도구로, 설치 명령 한 줄을 실행하고 ChatGPT 계정으로 로그인하면 시작한다(2026년 10월 20일 기준). 처음에는 작업 폴더 안에서만 자동으로 수정·실행하는 Auto로 시작하고, 버전 관리를 쓰지 않는 폴더는 읽기만 하는 Read-only로 시작한다.

코덱스 CLI 처음 켜기 전에 정할 것

설치를 마치고 터미널에 처음 코덱스를 띄우면 "내 파일을 어디까지 건드려도 되나요?"라는 질문이 가장 먼저 걸린다. 새로 온 인테리어 기사에게 집 열쇠를 줄 때를 떠올리면 쉽다. 거실 공사만 맡기면 거실 문만 열어 주고, 안방이나 금고까지는 따로 허락을 받게 한다. 코덱스도 같은 방식이라 작업 폴더 안은 알아서 고치게 두고 폴더 밖이나 인터넷 접속처럼 선을 넘는 일은 물어보게 설정한다. 다만 열쇠를 아예 맡기는 설정(yolo)도 있으니, 무엇을 골랐는지 모르는 채 시작하지 않는다.

OpenAI 문서에 따르면 코덱스 CLI는 프로젝트 폴더에서 codex를 실행하고 하고 싶은 작업을 적으면, 실행하는 명령과 바뀐 내용(diff)을 터미널에서 실시간으로 보여 주는 방식이다. 클라우드에서 돌리는 작업과 달리 내 컴퓨터의 파일을 직접 다루므로 권한 설정이 더 중요하다. 클라우드 작업이 궁금하면 코덱스 클라우드 작업 시작 방법과 요금제 조건을 먼저 본다.

코덱스 CLI 설치와 로그인

macOS와 리눅스는 터미널에서 아래 한 줄을 실행한다. OpenAI 문서는 업데이트도 같은 명령을 쓴다고 안내한다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

설치가 끝나면 코드를 다룰 프로젝트 폴더로 이동해 codex를 실행한다. 처음 실행하면 "Sign in with ChatGPT"를 포함한 로그인 방법이 나오고, 챗GPT 계정으로 로그인하면 그 요금제에 들어 있는 Codex 사용량을 쓴다. 문서의 명령어 참조를 보면 codex login은 기본으로 브라우저 로그인을 열고, 브라우저를 띄우기 어려운 서버에서는 --device-auth(기기 코드 방식), API 키로 쓰려면 --with-api-key를 붙인다.

성공했는지는 두 곳에서 본다. 터미널에서 codex login status를 실행해 로그인된 상태면 종료 코드 0이 돌아오고, 대화창 안에서 /status를 입력하면 현재 세션 설정과 남은 한도가 나온다. 설치 명령이 끝난 것과 로그인이 된 것은 다르므로, 첫 작업을 시키기 전에 이 확인을 한 번 한다.

Windows는 macOS·리눅스용 한 줄 명령을 그대로 쓰지 않는다. 공식 설치 페이지의 Windows 탭 안내를 따르고, 실행 환경은 아래 윈도우 절에서 고른다.

코덱스 CLI 기본 사용법과 슬래시 명령

대화형 사용은 codex를 실행해 작업을 설명하는 것이 전부이고, 실행 중인 작업은 중간에 방향을 바꿀 수 있다. 같은 문서가 소개하는 첫 번째 작업은 프로젝트에서 /init을 입력해 Codex가 읽을 지침 파일 AGENTS.md를 만드는 것이다. 여기에 빌드 명령과 지켜야 할 규칙을 적어 두면 매번 같은 설명을 반복하지 않는다.

입력	하는 일
codex	현재 폴더에서 대화형 화면을 연다
codex exec	사람 개입 없이 끝나는 비대화형 실행. 반복 작업이나 CI에 쓴다
codex resume	이전 대화를 이어 간다(현재 저장소의 최근 대화를 다시 연다). --last는 이 폴더의 가장 최근 세션
/init	AGENTS.md 지침 파일 생성
/status	현재 세션 설정과 남은 한도 표시
/permissions	허락 없이 할 수 있는 범위 선택과 현재 샌드박스 확인
/model	모델과 추론 강도 선택
/review	바뀐 내용을 검토해 문제 찾기

모델은 --model(-m)로 한 번만 바꿔 실행할 수 있고, 최신 웹 검색이 필요하면 --search를 붙인다. 이 옵션이 없으면 웹 검색은 미리 저장된 결과(cached)를 쓴다.

코덱스 CLI 승인 모드와 샌드박스, 무엇으로 시작할까

샌드박스는 Codex가 기술적으로 할 수 있는 일(어디에 쓰고 인터넷에 닿는지)이고, 승인 정책은 어떤 때 사람에게 먼저 묻는지다. 에이전트 승인·보안 문서가 나눈 네 가지 사용 방식은 다음과 같다.

이름	설정 값	동작
Auto	플래그 없음 또는 --sandbox workspace-write --ask-for-approval on-request	작업 폴더에서 읽기·수정·명령 실행을 자동으로 하고, 폴더 밖 수정이나 네트워크가 필요한 명령은 승인을 묻는다
Read-only	--sandbox read-only --ask-for-approval on-request	읽기 전용 샌드박스 안에서만 움직이고, 그 밖의 동작은 승인이 필요하다
읽기 전용 비대화형(CI)	--sandbox read-only --ask-for-approval never	읽기 전용으로 돌며 승인을 묻지 않는다
Dangerous full access	--dangerously-bypass-approvals-and-sandbox(--yolo)	샌드박스와 승인이 모두 없다. 문서가 권장하지 않는 모드

고르는 기준은 폴더 성격이다. 문서는 Git 같은 버전 관리를 쓰는 폴더에는 Auto를, 버전 관리를 쓰지 않는 폴더에는 Read-only를 권한다. 차이는 되돌릴 수 있는지다. 버전 관리가 있으면 Codex가 잘못 고친 파일을 이전 상태로 되돌릴 수 있지만, 없으면 그럴 방법이 없다. 아직 신뢰하지 않은 폴더는 온보딩이나 /permissions에서 신뢰를 정하기 전까지 Read-only로 시작할 수 있다.

Auto에서도 명령이 인터넷에 접속하는 것은 기본으로 꺼져 있다. 패키지 설치처럼 접속이 꼭 필요하면 승인·보안 문서대로 설정 파일(config.toml)의 [sandbox_workspace_write] 아래에 network_access = true를 넣어 켠다. --yolo는 격리된 컴퓨터나 가상 환경에서만 쓴다는 것이 문서의 안내이고, 이때는 웹 검색도 실시간(live)이 기본이 된다.

바뀐 설정은 /permissions를 열어 현재 샌드박스와 쓰기 가능한 폴더가 의도한 대로인지 확인한다. 설정 파일에 예전 값 approval_policy = "untrusted"가 남아 있으면 문서상 폐기된 값이라 클라이언트가 시작되지 않을 수 있으니 지운다.

윈도우에서 코덱스 CLI 쓰기: PowerShell과 WSL

윈도우 샌드박스 문서에 따르면 Codex는 WSL이나 가상 머신 없이 PowerShell에서 바로 실행할 수 있다. 리눅스 전용 도구가 필요하거나 작업 환경이 이미 WSL2에 있다면 WSL을 고른다. PowerShell에서는 윈도우 샌드박스, WSL2에서는 리눅스 샌드박스가 적용된다.

윈도우 샌드박스에는 세 가지가 있다. mxc는 호환되는 기기에서 권장하는 방식으로 관리자 승인 설정이 필요 없지만 Windows 11 24H2 또는 25H2의 지정 빌드 이상이어야 한다. mxc를 쓸 수 없으면 관리자 승인 설정이 필요한 elevated를 우선하고, 관리자 설정이 막힌 회사 PC처럼 정책이 허용할 때만 마지막 수단으로 unelevated를 쓴다. unelevated는 네트워크 격리가 약하다. 레거시 방식은 config.toml의 [windows] 아래 sandbox = "elevated"처럼 지정한다.

CLI 0.162.0 이상이면 설정을 바꾸지 않고 mxc가 동작하는지 한 번만 시험할 수 있다. PowerShell에서 문서의 시험 명령(codex -c windows.sandbox=mxc sandbox ... echo MXC_OK)을 실행해 MXC_OK가 출력되고 종료 코드가 0이면 정상이다.

코덱스 CLI 사용량 한도와 요금제

OpenAI 가격 페이지에 따르면 Codex는 Free, Go, Plus, Pro, Business 등 챗GPT 요금제에 포함되며 요금제별 사용량이 다르다. Plus 요금제 안내에는 웹, CLI, IDE 확장, iOS에서 Codex를 쓴다고 적혀 있고, Free와 Go는 가벼운 코딩 작업용으로 GPT-6 Luna 모델이 안내된다.

요금제	월 요금	Codex 이용 범위
Free	0달러	간단한 코딩 작업 체험
Go	8달러	가벼운 코딩 작업, GPT-6 Luna
Plus	20달러	웹·CLI·IDE 확장·iOS, GPT-6.1 Sol과 Luna, 크레딧으로 사용량 추가
Pro	100달러부터(100·200·500달러)	5시간 한도 없음. Ultrafast는 500달러에서
Business	사용자당 20달러(연간 결제, 월간 25달러)	2명 이상

Plus와 일반 Business의 5시간당 로컬 메시지 추정치는 GPT-6.1 Sol 15~160개, GPT-6 Astra 5~45개, GPT-6 Luna 350~3,000개다. 고정 한도가 아니라 작업 종류에 따라 달라지고 주간 한도가 함께 적용될 수 있다. 위 표에서 Luna의 추정 메시지 수가 Sol의 열 배 안팎이라, 한도가 빨리 줄면 간단한 작업만 /model로 Luna에 돌려 사용량을 아낄 수 있다. 가격 비교는 챗GPT 요금제 가격·한도 비교에서 이어 볼 수 있다.

가격 페이지에 따르면 챗GPT 로그인으로 쓰는 Codex에서는 GPT-5.5가 2026년 10월 14일에 종료됐다. 이 모델을 계속 쓰던 설정이 있다면 /model에서 다른 모델을 골라야 한다. API 키로 로그인한 세션은 이 종료의 영향을 받지 않는다.

코덱스 CLI 권한 설정 직접 확인해 보기

진짜 프로젝트에 적용하기 전에 빈 임시 폴더로 10분짜리 확인을 해 보면 두 모드의 차이가 눈에 보인다. 먼저 codex --sandbox read-only --ask-for-approval on-request로 열고 "hello.txt 파일을 만들어 줘"라고 시킨다. 문서대로라면 읽기 전용 샌드박스 안에서는 파일을 쓸 수 없어 승인을 묻거나 만들지 못한다고 답해야 한다. 이어서 codex를 옵션 없이 다시 열고 같은 요청을 하면 Auto 모드라 폴더 안에 파일이 바로 생기는지, 폴더 밖 경로를 요청하면 승인을 묻는지 본다. 결과가 문서와 다르면 /permissions에서 현재 샌드박스를 확인한다.

코덱스 CLI 처음 쓸 때 자주 하는 실수

첫째, 버전 관리를 쓰지 않는 폴더에서 Auto로 큰 작업을 시킨다. 잘못 고친 파일을 되돌릴 방법이 없으므로 먼저 git init으로 저장소를 만들고 시작하거나 Read-only로 계획만 받는다. 둘째, 안전장치를 빼려고 --yolo를 습관처럼 붙인다. 승인 요청이 번거롭다면 yolo 대신 필요한 폴더 접근과 네트워크만 설정 파일에서 연다. 셋째, 한도가 갑자기 찼다고 느끼는데 /status를 안 본다. 가격 페이지는 ChatGPT Work와 Codex가 같은 사용량·크레딧·한도를 쓴다고 안내하므로, 남은 양은 대시보드와 /status로 확인한다.

클로드 코드도 함께 쓰는 사람은 클로드 코드·코덱스 계정을 세션마다 나눠 쓰는 방법이 한도 관리에 도움이 된다.

자주 묻는 질문

코덱스 CLI는 API 키 없이 쓸 수 있나요?

쓸 수 있다. 처음 실행할 때 챗GPT 계정으로 로그인하면 요금제에 포함된 사용량으로 동작하고, API 키를 쓰는 방식은 codex login --with-api-key로 따로 고른다.

코덱스 CLI 대화를 닫았다가 이어서 할 수 있나요?

할 수 있다. codex resume을 실행하면 이전 대화를 고르고, --last를 붙이면 현재 폴더의 가장 최근 세션을 바로 연다.

codex exec는 언제 쓰나요?

사람이 화면 앞에 없어도 끝나야 하는 반복 작업이나 CI에서 쓴다. --json으로 진행 이벤트를 받거나 -o로 마지막 응답을 파일에 저장할 수 있다.