Codex CLI 설치 사용법: 독립 설치기부터 첫 코드 생성까지 (2026)

작성자:

터미널 검은 창만 봐도 손이 굳는 사람이 많다. 그런데 Codex CLI 설치와 사용법은 막상 해보면 별거 아니다. 창에 명령어 한 줄을 넣고 로그인만 통과하면 그다음부터는 사람한테 부탁하듯 말로 코드를 만들 수 있다. 이 글은 Node 설치부터 로그인, 첫 코드 생성까지 실제로 걸려 넘어지는 지점만 골라 짧게 끝내는 걸 목표로 한다.

Codex CLI는 OpenAI가 내놓은 터미널용 코딩 도우미다. VS Code 같은 무거운 도구를 켜지 않고도 지금 열려 있는 그 터미널 안에서 “이 폴더에 간단한 할 일 목록 앱 만들어줘” 같은 요청을 처리한다. 정작 초보자가 넘어지는 곳은 설치 자체가 아니라 Node 버전이나 인증 단계다. 그 부분을 하나씩 짚어보자.

Codex CLI 설치 전에 준비할 것

본격적인 설치에 들어가기 전에 딱 두 가지만 챙기면 된다. Node.js와 OpenAI 계정이다. Codex CLI는 npm 패키지로 배포되니 npm으로 깔려면 Node.js가 먼저 있어야 한다. 버전이 너무 낮으면 설치는 되는데 막상 실행할 때 알 수 없는 에러가 뜨곤 한다. 이 단계를 대충 넘기면 나중에 원인 찾느라 오히려 시간을 더 쓴다.

터미널을 열고 아래 명령으로 지금 버전을 확인해 보자. macOS는 스포트라이트에서 “터미널”, 윈도우는 시작 메뉴에서 “PowerShell”이나 “명령 프롬프트”를 검색하면 된다.

node -v
npm -v

npm으로 설치할 거라면 Node.js 16 이상이면 된다(가급적 최신 LTS를 권장한다). node -v가 v16보다 낮게 나오거나 “명령을 찾을 수 없습니다”라고 뜨면 Node부터 새로 깔아야 한다. nodejs.org에서 LTS 버전을 받아 설치하면 npm은 자동으로 함께 들어온다. 버전이 애매하면 그냥 가장 최신 LTS를 받는 게 마음 편하다. 참고로 Node를 아예 깔기 싫다면 뒤에서 소개할 다른 설치 경로도 있으니 지금 Node가 없다고 여기서 막힐 필요는 없다.

준비물 확인 명령 없거나 낮을 때
Node.js (npm 설치 시) node -v nodejs.org에서 최신 LTS(16 이상) 설치
npm npm -v Node 설치 시 자동 포함
OpenAI 계정 – chatgpt.com 로그인 또는 API 키 발급

Codex CLI 설치 사용법: 설치 명령 한 줄

OpenAI가 초보자에게 먼저 권하는 방법은 독립 실행 설치기(standalone installer)다. 별도 런타임을 깔 필요 없이 실행 파일 하나만 내려받으면 되는 방식이라 Node가 없어도 바로 시작할 수 있다. OpenAI 공식 안내(developers.openai.com/codex/cli)나 GitHub 릴리스 페이지에서 자기 운영체제에 맞는 파일을 받아 설치하면 된다. 설치가 끝나면 확인 삼아 버전을 찍어본다.

codex --version

이미 Node가 깔려 있다면 npm으로 설치하는 게 더 익숙할 수 있다. 전역 설치 옵션(-g)을 쓰면 어느 폴더에서든 codex를 부를 수 있다. 여기서 초보자가 흔히 저지르는 실수 하나. 패키지 이름을 codex로만 적으면 엉뚱한 게 깔린다. 앞에 @openai/를 꼭 붙이자.

npm install -g @openai/codex

Homebrew를 쓰는 macOS 사용자라면 brew로도 깔 수 있다. 요즘은 formula가 아니라 cask로 배포돼서 --cask를 붙여야 한다.

brew install --cask codex

어느 쪽을 골라도 결과는 같다. Node를 새로 깔기가 부담스러우면 독립 설치기가 가장 간단하고 개발 환경에 Node가 이미 있으면 npm 한 줄이 빠르다. 세 방법 모두 윈도우·맥·리눅스에서 동작하니 손에 맞는 걸 고르면 된다.

Codex CLI 설치, 로그인, 첫 코드 생성 3단계 흐름도
Codex CLI 시작 3단계

코덱스 CLI 윈도우 설치에서 자주 막히는 지점

윈도우 사용자가 유독 잘 걸리는 부분이 있다. 하나는 권한 문제다. npm install -g가 “권한이 거부되었습니다” 비슷한 메시지를 뱉으면 PowerShell을 관리자 권한으로 다시 열고 시도해 보자. 아이콘에서 마우스 오른쪽 버튼을 누른 뒤 “관리자 권한으로 실행”을 고르면 된다.

또 하나는 codex를 쳤는데 “인식할 수 없는 명령”이라고 나오는 경우다. 대개 npm 전역 설치 경로가 PATH에 안 잡혀서 그렇다. 터미널을 완전히 껐다 새로 열면 해결되는 일이 많으니 그것부터 해보고 그래도 안 되면 컴퓨터를 한 번 재부팅해 본다. 오래된 WSL이나 회사 보안 프로그램이 npm 설치를 막기도 하니 사내 노트북이라면 이 점도 염두에 두자.

Codex CLI 로그인: 인증 통과하기

설치가 끝나면 로그인 차례다. 초보자에게 가장 헷갈리는 관문인데, 로그인 방식이 크게 두 갈래라 그렇다. 하나는 ChatGPT 계정으로 로그인하는 방식, 다른 하나는 OpenAI API 키를 직접 넣는 방식이다. 대부분은 앞쪽이 편하다.

  1. 터미널에서 작업할 폴더로 이동한 뒤 codex를 입력해 실행한다.
  2. 로그인 안내가 뜨면 ChatGPT 계정 로그인을 선택한다. 그러면 브라우저가 자동으로 열린다.
  3. 브라우저에서 평소 쓰던 OpenAI(ChatGPT) 계정으로 로그인하고 접근을 승인한다.
  4. 승인이 끝나면 터미널로 돌아온다. 인증 성공 메시지가 뜨면 준비 완료다.

API 키로 인증하고 싶다면 OpenAI 플랫폼에서 키를 발급받아 쓰면 된다. 키를 환경 변수 OPENAI_API_KEY에 넣어 둔 다음 그 값을 codex login --with-api-key로 넘겨 등록하는 방식이다. 다만 API 키 방식은 쓴 만큼 요금이 붙는 구조라 요금 정책은 발급 전에 꼭 확인하자.

# macOS / Linux (zsh, bash)
export OPENAI_API_KEY="sk-여기에-본인-키"
printenv OPENAI_API_KEY | codex login --with-api-key

# 윈도우 PowerShell
$env:OPENAI_API_KEY="sk-여기에-본인-키"
$env:OPENAI_API_KEY | codex login --with-api-key

직접 해보니 초보자가 제일 많이 헤매는 건 “브라우저 로그인 창이 안 뜨는” 상황이었다. 원격 서버에 SSH로 접속한 터미널이거나 브라우저가 자동으로 안 열리는 환경이면 화면에 인증용 URL이 텍스트로 찍힌다. 그 주소를 복사해 내 컴퓨터 브라우저에 붙여 넣고 로그인하면 똑같이 연결된다. 창이 안 뜬다고 설치가 잘못된 게 아니니 당황하지 말자.

코덱스 CLI 첫 코드 생성해 보기

로그인까지 통과했으면 이제 진짜 재미있는 대목이다. 빈 폴더를 하나 만들고 거기서 codex를 실행한 다음 사람한테 말하듯 요청을 적으면 된다. 처음부터 거창한 걸 시키지 말고 결과를 눈으로 바로 확인할 수 있는 작은 작업부터 주는 게 좋다.

mkdir codex-test
cd codex-test
codex

codex가 켜지면 프롬프트에 이렇게 적어보자.

파이썬으로 "안녕하세요"를 출력하는 hello.py 파일을 만들어줘

그러면 codex가 어떤 파일을 어떻게 만들지 계획을 먼저 보여주고 실제로 파일을 생성하거나 명령을 실행하기 전에 승인을 요청한다. 이 승인 단계가 핵심이다. 파일 쓰기나 명령 실행을 codex가 제멋대로 하지 않고 사용자가 매번 확인하도록 되어 있어서 처음 쓰는 사람도 마음 놓고 시켜볼 수 있다. 만들어진 hello.py를 python hello.py로 직접 돌려 결과가 나오면 첫 코드 생성 성공이다.

승인 없이 알아서 진행하는 자동 모드도 있지만 익숙해지기 전까지는 매번 확인하는 기본 모드를 권한다. 특히 중요한 프로젝트 폴더에서는 자동 모드를 켜지 말자. AI가 파일을 지우거나 덮어쓴 걸 한 박자 늦게 알아채면 되돌리기가 여간 번거로운 게 아니다.

단계 명령/동작 확인 포인트
버전 확인 node -v v16 이상인지
설치 npm install -g @openai/codex 에러 없이 완료
확인 codex --version 버전 번호 출력
로그인 codex 실행 후 계정 로그인 인증 성공 메시지
첫 코드 자연어로 요청 입력 파일 생성·실행 승인

자주 묻는 질문

Codex CLI는 무료인가요?

도구 자체는 오픈소스로 공개돼 있어 설치는 무료다. 다만 실제로 코드를 생성하려면 OpenAI 계정이 있어야 하고, ChatGPT 구독 플랜에 포함되는지 아니면 API 사용량만큼 따로 과금되는지는 로그인 방식에 따라 갈린다. 요금 구조는 시점마다 바뀌니 로그인 전에 OpenAI 공식 안내를 확인하는 걸 권한다.

코덱스 CLI 윈도우 설치도 맥과 똑같나요?

npm으로 설치하는 명령은 윈도우·맥·리눅스가 동일하다. 다만 윈도우는 전역 설치 권한 문제나 PATH 인식 문제가 상대적으로 자주 생긴다. 관리자 권한 PowerShell로 실행하고 명령을 못 찾으면 터미널을 새로 여는 것으로 대부분 풀린다.

Codex CLI 로그인 창이 안 열려요.

원격 서버나 브라우저가 없는 환경에서는 로그인 URL이 화면에 텍스트로 찍힌다. 그 주소를 내 컴퓨터 브라우저에 붙여 넣어 로그인하면 인증이 연결된다. 방화벽이나 회사 보안 정책이 브라우저 실행을 막는 경우도 있으니 사내 장비라면 확인해 보자.

Claude Code와는 뭐가 다른가요?

둘 다 터미널에서 자연어로 코드를 다루는 AI 도구라는 점은 비슷하다. 대신 Codex CLI는 OpenAI 계정 기반이고 Claude Code는 Anthropic 계정 기반이라는 차이가 크다. 명령 방식이나 승인 흐름도 서로 조금씩 달라서 두 도구를 다 써보고 손에 맞는 쪽을 고르는 사람도 많다.

여기까지 따라왔다면 검은 터미널 창이 조금은 덜 무서워졌을 것이다. Codex CLI 설치 사용법의 핵심은 결국 Node 버전 확인, 전역 설치, 계정 로그인, 그리고 작은 요청으로 첫 코드 만들어 보기다. 처음엔 hello.py 같은 사소한 것부터 시작해서, 손에 익으면 실제 프로젝트에 조금씩 붙여 나가면 된다.

공식 참고: OpenAI Codex 로그인·인증 공식 문서

관련 글

같은 결의 터미널 AI 도구가 궁금하다면 Claude Code 입문 가이드를 함께 보면 비교가 쉽다. AI 도구에 프로젝트 규칙을 알려주는 방법이 궁금하다면 CLAUDE.md 작성법 정리도 도움이 된다.

댓글 남기기