코덱스 CLI 설치·사용법 2026 — 윈도우/맥 설치부터 앱·CLI 차이까지

코덱스는 오픈AI의 코딩 에이전트 제품군 이름이고, 그 안에 여러 실행 방식이 들어 있습니다. 한 덩어리로 뭉뚱그리면 설치할 때부터 헷갈리니, 먼저 이름부터 구분하고 넘어가겠습니다. 같은 코덱스라도 어디서 도느냐에 따라 설치·인증·사용 흐름이 전부 다릅니다.

이 글의 주인공은 첫 줄, 코덱스 CLI입니다. 제 입장에서 정리하면 클로드 코드(Claude Code)와 거의 같은 성격의 도구입니다. 터미널에 자연어로 지시하면 프로젝트 폴더의 파일을 읽고, 코드를 수정하고, 테스트 명령을 돌리고, 결과를 확인하는 식으로 한 사이클을 스스로 돕니다. 데스크톱 앱이나 웹 버전은 대화 중심이라 가볍게 쓰기 좋지만, 내 로컬 코드베이스를 통째로 만지는 작업은 CLI 쪽이 훨씬 직접적입니다.

설치가 막히는 사람의 절반은 설치 명령 자체보다 그 앞 단계에서 걸립니다. 본격적으로 깔기 전에 세 가지만 먼저 점검하면 뒤가 훨씬 수월합니다.

1. Node.js 버전 — 코덱스 CLI는 비교적 최신 Node.js를 요구합니다. 보통 LTS 최신(현재 기준 22번대 이상)을 깔아두면 안전합니다. 회사·학교 PC에 오래된 14, 16번대가 남아 있으면 설치는 되더라도 실행 시 알 수 없는 오류가 납니다.
2. 오픈AI 계정 — 코덱스 CLI는 로그인이 필요합니다. 챗지피티 구독 계정으로 로그인하거나, 플랫폼 API 키로 인증하는 두 방법이 있습니다. 어느 쪽으로 갈지 미리 정해두는 게 좋습니다.
3. 운영체제 — 맥(macOS)과 리눅스는 설치가 단순합니다. 윈도우는 그냥 깔아도 동작하지만, 권한·경로 문제로 막히면 WSL(윈도우용 리눅스)에서 돌리는 편이 훨씬 안정적입니다.

제 경우 현재 Node.js 버전을 확인하는 습관부터 들이라고 권합니다. 한 번 깔아두면 잊고 지내다가, 어느 날 버전이 낮은 환경에서 설치하면 원인 모를 에러로 시간을 잡아먹기 때문입니다.

맥과 리눅스는 설치 과정이 단순합니다. Node.js만 제대로 깔려 있으면 npm 전역 설치 한 줄로 끝납니다. 저는 애플 실리콘 맥에서 이 방식으로 설치했고, 막힘 없이 한 번에 끝났습니다.

아래 명령으로 깐 뒤, 설치가 됐는지 버전 확인 명령으로 한 번 더 점검하면 됩니다. 권한 문제로 전역 설치가 거부되면 앞에 무작정 관리자 권한을 붙이기보다, Node.js를 사용자 디렉터리에 깔아둔 환경(예: nvm)에서 다시 시도하는 편이 깔끔합니다.

윈도우는 한 줄 설치가 그대로 통하기도 하지만, 막히면 원인이 제각각이라 시간을 잡아먹습니다. 제가 윈도우 PC에서 직접 깔아보며 겪었거나, 주변에서 같은 데서 멈춘 케이스를 묶어 정리합니다. 핵심은 거의 다 Node.js 환경과 경로·권한 두 갈래에서 납니다.

제가 윈도우에서 가장 자주 본 함정은 두 가지입니다. 하나는 한글 윈도우 계정 이름 때문에 사용자 폴더 경로에 한글이 섞여 일부 도구가 경로를 잘못 읽는 경우, 다른 하나는 OneDrive로 동기화되는 폴더 안에서 프로젝트를 돌릴 때 파일 잠금 충돌이 나는 경우입니다. 둘 다 프로젝트를 영문 이름의 로컬 폴더(예: C 드라이브 바로 아래)로 옮기면 대부분 풀립니다. 그래도 불안정하면 WSL을 까는 게 답입니다.

설치가 끝나면 처음 실행할 때 로그인을 합니다. 여기서 의외로 많이 막히는데, 인증 경로가 두 갈래라 어느 쪽인지 헷갈리는 게 원인입니다. 본인 상황에 맞는 쪽을 먼저 정하면 깔끔합니다.

• 챗지피티 구독 계정으로 로그인 — 챗지피티 플러스(Plus)나 프로(Pro) 같은 구독이 있으면, codex 첫 실행 시 브라우저가 열리며 오픈AI 계정 로그인 화면이 뜹니다. 로그인하면 인증이 끝나고, 구독에 포함된 한도 안에서 별도 추가 결제 없이 코덱스를 씁니다.
• API 키로 인증 — 구독 대신 플랫폼 API 키를 환경변수로 넣어 쓰는 방식입니다. 이쪽은 사용량만큼 토큰 단위로 과금되므로, 많이 돌리면 비용이 따로 쌓입니다.

토큰 단계에서 멈췄다는 분들의 증상은 대개 비슷합니다. 브라우저 로그인 창은 떴는데 터미널로 인증이 안 돌아오거나, 로그인은 됐다는데 다시 실행하면 또 로그인을 요구하는 식입니다. 이때는 아래 순서로 점검하면 거의 풀립니다.

1. 방화벽·VPN을 잠시 끄고 다시 시도합니다. 인증 콜백이 로컬 포트로 돌아오는데, 보안 프로그램이 이를 막는 경우가 있습니다.
2. 브라우저 로그인 후 터미널 창으로 돌아와 인증 완료 메시지를 끝까지 기다립니다. 브라우저만 닫고 터미널을 방치하면 인증이 미완으로 남습니다.
3. 그래도 안 되면 인증 정보를 한 번 비우고 다시 로그인합니다. 코덱스는 보통 사용자 홈의 설정 폴더에 인증 정보를 저장하므로, 그 폴더를 정리하고 재로그인하면 깨끗해집니다.

설치와 로그인을 마쳤으면 이제 진짜 일을 시킬 차례입니다. 사용 흐름은 클로드 코드를 써봤다면 거의 똑같이 느껴집니다. 작업할 프로젝트 폴더로 이동한 뒤 codex 를 실행하고, 하고 싶은 일을 한국어 또는 영어 자연어로 적으면 됩니다.

제가 권하는 첫 사용 순서는 이렇습니다. 처음부터 큰 작업을 통째로 맡기기보다, 작은 것부터 시키며 도구가 내 코드를 어떻게 읽고 고치는지 감을 잡는 게 안전합니다.

1. 프로젝트 폴더로 이동 후 codex 실행. 코덱스가 현재 폴더를 작업 공간으로 인식합니다.
2. 읽기 작업부터 시작 — 처음에는 코드를 고치는 대신 설명을 시켜봅니다. 예: 이 프로젝트 구조를 설명해줘.
3. 작은 수정 요청 — 한 파일의 함수 하나를 고쳐달라는 식으로 범위를 좁혀 시킵니다.
4. 변경 사항 확인 — 코덱스가 제안한 수정을 적용하기 전에 어떤 파일이 어떻게 바뀌는지 보고 승인합니다.
5. 실행·테스트까지 위임 — 익숙해지면 테스트 명령 실행이나 빌드 확인까지 한 번에 맡깁니다.

승인 단계가 핵심입니다. 코덱스 CLI는 파일을 직접 고치고 명령까지 실행할 수 있어서, 무엇을 어디까지 자동으로 허용할지 권한 모드를 정해두는 게 안전합니다. 처음에는 매 변경마다 승인을 받는 모드로 쓰다가, 작업 패턴이 손에 익으면 자동 승인 범위를 넓히는 식으로 조절하면 됩니다.

코덱스를 데스크톱 앱·웹에서도 쓸 수 있으니, 굳이 CLI를 깔 필요가 있느냐는 질문이 자연스럽게 따라옵니다. 둘은 잘하는 영역이 다릅니다. 제가 직접 둘 다 써본 기준으로 정리하면 이렇습니다.

제 결론은 이렇습니다. 코드 한 줄을 물어보거나 개념 설명을 듣는 정도라면 앱·웹이 빠릅니다. 하지만 실제 프로젝트 파일을 통째로 고치고, 테스트를 돌리고, 결과를 보며 다시 수정하는 반복 작업은 CLI가 압도적으로 낫습니다. 저처럼 여러 사이트를 1인으로 굴리면 터미널에서 명령 한 줄로 작업을 던지고 결과만 확인하는 흐름이 훨씬 빠릅니다. 그래서 가벼운 질문은 앱, 본 작업은 CLI로 나눠 쓰는 조합이 가장 현실적이었습니다.

설치까지 마치고 나면 가장 궁금한 게 비용입니다. 핵심은 인증 방식에 따라 추가 비용 유무가 갈린다는 점입니다.

• 챗지피티 구독으로 로그인하는 경우 — 구독료 안에 코덱스 사용 한도가 포함됩니다. 즉 챗지피티 플러스(월 20달러)나 프로(월 200달러)를 이미 내고 있다면, 그 한도 안에서 코덱스 CLI를 쓰는 데 별도 결제가 추가로 발생하지 않습니다. 단, 한도를 다 쓰면 일정 시간 쿨다운이 걸리거나 작업이 제한될 수 있습니다.
• API 키로 인증하는 경우 — 사용한 토큰만큼 과금됩니다. 많이 돌릴수록 비용이 쌓이므로, 사이드 프로젝트로 자주 쓴다면 구독 방식이 예측 가능합니다.

한국 카드 결제 관점에서 덧붙이면, 챗지피티 구독은 미국 달러(USD) 기준으로 청구되고 한국 소비자에게는 부가가치세(VAT) 10%가 별도로 붙습니다. 그래서 플러스 20달러는 부가세 포함 22달러 기준으로, 2026년 6월 환율을 1,350원 안팎으로 가정하면 카드 명세서에는 대략 3만 원 안팎이 찍히는 경우가 많습니다. 환율은 매일 바뀌므로 정확한 금액은 결제 후 카드 명세서에서 확인하시는 게 맞습니다. 코덱스만 따로 결제하는 별도 요금제는 없고, 어디까지나 챗지피티 구독이나 API 사용량에 묶이는 구조라고 이해하시면 됩니다.

참고 자료

• 오픈AI 코덱스 CLI 공식 문서 — 설치·인증·명령 옵션의 1차 출처
• 코덱스 CLI 깃허브 저장소 — 최신 버전·설치 방법·이슈 트래커
• Node.js 공식 다운로드 — 설치 전 LTS 최신 버전 준비