쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(윈도우)

터미널 기반 AI 코딩 도구가 표준이 되는 시기

2025년부터 2026년 사이, 코딩을 거드는 AI 도구의 무게중심이 빠르게 바뀌었습니다. Cursor 같은 IDE 안의 자동완성에서 출발해, 이제는 터미널 안에서 직접 일을 시키는 에이전트 형태가 표준에 가까워졌습니다. 앤트로픽의 클로드 코드(Claude Code)가 그 흐름의 한 축이었다면, OpenAI 진영에서 그에 대응해 정리한 도구가 코덱스 CLI(Codex CLI) 입니다.

다행히도 윈도우 PC에서 코덱스 CLI를 처음 깔 때 마주치는 화면은 PowerShell로 클로드 코드와 동일합니다. 평소 작업 표시줄과 파일 탐색기로 컴퓨터를 쓰던 분이라면 처음에는 낯설게 느껴지지만, 클릭과 드래그 대신 짧은 문장으로 컴퓨터에 일을 시키는 방식이라는 점만 다를 뿐입니다. 그리고 클로드 코드를 이미 설치한 적이 있다면 사전 준비(PowerShell 관리자 모드, Node.js)는 그대로 재사용할 수 있어 훨씬 간단합니다.

윈도우에서 코덱스 CLI는 설치 자체가 매우 짧습니다. 사실상 한 줄짜리 npm 명령이 본체 설치의 전부이고, 그다음은 ChatGPT 계정 로그인뿐입니다. 아래 순서대로 따라가 주세요. 윈도우 10·11 어느 쪽이든 동일하게 진행됩니다. 설치 도중에 막히는 메시지가 뜬다면 글 끝의 자주 발생하는 문제 섹션을 확인해 보세요.

“

코덱스 CLI(Codex CLI)는 OpenAI가 만든 터미널 기반 AI 코딩 도구입니다. 윈도우에서는 PowerShell 관리자 모드를 열어 Node.js를 먼저 깐 뒤(이미 있다면 건너뛰어도 됩니다), npm i -g @openai/codex 한 줄로 본체를 받고, codex 명령으로 실행해 ChatGPT 계정으로 로그인하면 첫 실행 준비가 끝납니다. 모델은 기본으로 GPT-5.5가 선택되며, 추론 깊이는 medium·high·xhigh 중에서 고를 수 있습니다.

이 글은 윈도우 PC를 기준으로 합니다. 맥(Mac)을 쓰시는 분은 맥용 가이드 (맥에서 설치하는 방법 바로가기)를 참고하세요.

Step 1. PowerShell을 관리자 모드로 실행

설치 작업은 모두 PowerShell이라는 윈도우 기본 도구 안에서 합니다. 일반 모드가 아닌 관리자 모드여야 Node.js 같은 사전 도구를 시스템에 설치할 수 있습니다. 본체 설치(npm i -g)는 일반 모드로도 가능하지만, 처음부터 관리자 모드로 시작하면 단계 도중에 막히는 일이 줄어듭니다.

1. 키보드의 Windows 키를 누르세요.
2. "PowerShell"이라고 입력하세요.
3. 검색 결과에서 "관리자 권한으로 실행"을 클릭하세요.

✅ 성공 신호: 창 제목 줄에 "관리자: Windows PowerShell"이라고 표시됩니다. 이후 모든 명령어는 이 창에 입력합니다.

Step 2. Node.js가 깔려 있는지 확인하고, 없으면 설치

코덱스 CLI는 npm 글로벌 패키지로 배포됩니다. 즉 Node.js가 깔려 있으면 본체 설치는 한 줄로 끝납니다. 클로드 코드를 이미 설치하신 분이라면 보통은 이 단계가 그대로 통과됩니다.

먼저 확인부터 합니다.

두 명령어 모두 버전 번호가 나오면 Step 3으로 바로 넘어가세요. 만약 "node를 찾을 수 없습니다" 같은 메시지가 뜨면 아래 명령어로 Node.js LTS 버전을 설치합니다.

설치가 끝나면 PowerShell을 닫았다가 다시 관리자 모드로 열어 주세요. 새로 설치한 도구는 새 창에서만 인식됩니다.

✅ 성공 신호: node -v, npm -v 모두 버전 번호가 출력되면 사전 준비 완료입니다.

Step 3. 코덱스 CLI 본체 설치

이제 본체를 설치합니다. PowerShell 한 줄이면 끝납니다.

-g는 글로벌 설치를 뜻하며, 어느 폴더에서든 codex 명령을 부를 수 있게 됩니다. 설치가 끝나면 확인합니다.

✅ 성공 신호: 버전 번호가 출력되면 본체 설치 완료입니다. 이후부터는 관리자 모드가 아니어도 됩니다.

Step 4. 최초 실행과 ChatGPT 로그인

PowerShell에 아래 명령어를 입력해 코덱스 CLI를 처음 실행해 보세요.

처음 실행하면 인증 안내가 뜹니다. 기본 옵션은 ChatGPT 계정으로 로그인입니다. 화면의 안내를 따라 엔터를 누르면 웹 브라우저가 열리고, OpenAI 계정에 로그인하면 자동으로 코덱스 CLI 창에 인증 정보가 전달됩니다. ChatGPT Plus·Pro·Business·Enterprise 어느 플랜이든 모두 로그인 가능합니다.

API key를 별도로 발급해 사용하는 방식도 있지만, 처음에는 ChatGPT 계정 로그인 쪽이 훨씬 간단합니다.

✅ 성공 신호: PowerShell 창에 코덱스 CLI 인터페이스가 떠 있고, 메시지를 입력할 수 있는 상태가 됩니다.

Step 5. 한국어로 대화하고, 기본 사용 흐름 익히기

코덱스 CLI는 별도의 언어 설정이 없습니다. 기본 영문 안내가 보이지만, 한국어로 질문을 입력하면 한국어로 답변이 옵니다. 첫 시도로는 다음 정도의 메시지를 던져 보시면 감이 잡힙니다.

또는

종료는 클로드 코드와 같습니다. Ctrl+C를 두 번 누르거나, /exit 명령을 입력하면 됩니다. 다음번에 다시 시작할 때는 PowerShell을 열고 작업 폴더로 이동한 뒤 codex만 입력하면 됩니다.

✅ 성공 신호: 한국어 질문에 한국어 답변이 정상적으로 돌아오면 설치와 첫 실행이 모두 끝난 것입니다.

GPT-5.5와 xhigh 추론 모드, 한눈에 정리

코덱스 CLI를 처음 실행하면 기본 모델은 GPT-5.5입니다. 2026년 4월 23일에 공개된 OpenAI의 최신 주력 모델이며, 코딩·디버깅·문서 작성·웹 리서치 같은 작업 전반에서 이전 세대인 GPT-5.4보다 더 적은 토큰으로 더 좋은 결과를 내도록 튜닝되었습니다.

GPT-5.5 라인업은 다음 세 가지입니다.

여기에 더해 추론 깊이(reasoning effort) 라는 또 하나의 축이 있습니다. 같은 모델이라도 답하기 전에 얼마나 오래 "생각"할지를 정할 수 있습니다.

사용자가 "GPT-5.5 xhigh" 같은 표현을 보았다면, 이것은 모델 자체의 이름이 아니라 GPT-5.5에 xhigh 추론 모드를 적용한 조합입니다. 어려운 버그를 잡거나, 큰 리팩토링을 부탁할 때 한 번씩 꺼내 쓰는 카드라고 이해하시면 됩니다.

코덱스 CLI 안에서 모델과 추론 깊이는 /model 명령으로 바꿀 수 있습니다. 처음에는 기본값(GPT-5.5 · medium) 그대로 써 보시고, 결과가 얕다고 느껴지는 작업에서만 한 단계씩 올려 보시면 됩니다.

“

GPT-5.5는 OpenAI의 2026년 주력 모델이고, xhigh는 추론을 가장 깊게 돌리는 설정입니다. 모델과 추론 깊이는 별도 축이며, 보통은 기본값으로 충분합니다.

클로드 코드와 코덱스 CLI의 차이점

처음 두 도구를 비교하시는 분께 가장 정확한 답은 "사실상 거의 같다"입니다. 둘 다 터미널에서 자연어로 일을 시키고, 파일을 직접 읽고 고치고, 명령을 대신 실행해 주는 에이전트 형태의 AI 코딩 도구입니다. 사용감도 매우 비슷합니다.

차이점을 굳이 짚으면 다음 정도입니다.

즉 두 도구는 같은 카테고리의 비슷한 도구이며, 어느 한쪽만 써야 할 이유는 거의 없습니다. 보통은 둘 다 깔아 두고 작업 성격에 따라 골라 쓰는 쪽이 자연스럽습니다. 같은 문제에 두 모델의 답을 한 번씩 받아 보면, AI 도구 활용 감각 자체가 빠르게 좋아집니다.

“

코덱스 CLI와 클로드 코드는 같은 카테고리의 비슷한 도구입니다. 둘 다 깔아 두고 작업 성격에 따라 골라 쓰는 편이 가장 실용적입니다.

자주 묻는 질문 (AEO)

“

Q. 코덱스 CLI는 윈도우 어느 버전부터 설치할 수 있나요?

A. winget 명령을 지원하는 Windows 10(1809 빌드 이상)과 Windows 11에서 사전 도구를 깔 수 있습니다. 본체 설치(npm i -g @openai/codex)는 Node.js만 동작하면 어느 윈도우 버전에서도 가능합니다.

“

Q. 코덱스 CLI를 쓰려면 유료 ChatGPT 구독이 꼭 필요한가요?

A. ChatGPT 무료 계정으로도 로그인 자체는 가능하지만, GPT-5.5 같은 최신 모델과 코덱스 기능 전반을 자유롭게 쓰려면 Plus·Pro·Business·Enterprise 중 하나의 유료 플랜이 필요합니다. API key를 직접 발급해 사용량 기반으로 쓰는 방법도 있습니다.

“

Q. 클로드 코드를 이미 쓰고 있는데, 코덱스 CLI를 같이 깔아도 충돌이 없나요?

A. 충돌이 없습니다. 두 도구는 서로 다른 명령(claude와 codex)으로 실행되고, 설정 파일도 별도로 보관됩니다. 동일 폴더에서 한쪽을 종료하고 다른 쪽을 띄워 같은 작업을 시켜 보면 두 도구의 응답 차이를 직접 비교해 볼 수 있습니다.

“

Q. xhigh 추론 모드는 항상 켜 두는 게 좋지 않나요?

A. 일반적인 작업에서는 권장하지 않습니다. xhigh는 답하기 전에 가장 깊게 생각하기 때문에 응답 시간이 눈에 띄게 길어지고, 그만큼 비용이나 사용량 한도도 더 빨리 소진됩니다. 어려운 디버깅이나 큰 리팩토링을 부탁할 때만 한 번씩 꺼내 쓰는 편이 효율적입니다.

자주 발생하는 문제

• "npm을 찾을 수 없습니다": Node.js가 깔려 있지 않거나, 새 PowerShell 창을 안 연 경우입니다. Step 2를 다시 확인하고, 설치 후에는 PowerShell을 닫았다 다시 관리자 모드로 열어 주세요.
• npm i -g에서 권한 오류가 납니다: 관리자 모드가 아닌 일반 PowerShell에서 실행한 경우가 많습니다. 관리자 모드로 PowerShell을 다시 열고 같은 명령어를 입력하세요.
• codex 명령이 인식되지 않습니다: 설치 직후 현재 PowerShell 창에서는 인식되지 않을 수 있습니다. 창을 닫고 다시 연 뒤 codex --version을 시도해 주세요.
• ChatGPT 로그인 창이 열리지 않습니다: 기본 브라우저 설정이 비어 있거나, 회사 PC의 보안 정책이 외부 OAuth 페이지를 차단하는 경우입니다. 개인 네트워크로 옮겨 본 뒤에도 같은 증상이라면 API key 방식으로 인증을 시도해 보세요.
• GPT-5.5 모델이 모델 선택 목록에 보이지 않습니다: 사용 중인 ChatGPT 계정이 GPT-5.5가 아직 롤아웃되지 않은 지역·플랜일 수 있습니다. 일단 기본 모델로 사용하고, 며칠 뒤에 다시 /model을 열어 보세요.

정리

• 사전 준비: PowerShell 관리자 모드에서 Node.js가 깔려 있는지 확인하고, 없으면 winget으로 한 줄 설치합니다.
• 본체 설치: npm i -g @openai/codex 한 줄과 codex 실행, ChatGPT 계정 로그인 한 번으로 끝납니다.
• 첫 사용: 한국어로 바로 질문해도 한국어로 답이 옵니다. GPT-5.5 기본 모델로 시작해, 어려운 작업에서만 xhigh 추론 모드를 한 번씩 꺼내 쓰는 편이 효율적입니다.
• 클로드 코드와는 본질적으로 같은 카테고리의 도구이므로 둘 다 깔아 두고 작업별로 골라 쓰시면 됩니다.

코덱스 CLI는 클로드 코드와 마찬가지로 npm 한 줄이면 본체가 깔리는 가벼운 도구입니다. 윈도우에서는 Node.js 한 번만 정리해 두면 이후 어떤 AI 코딩 CLI가 새로 나와도 같은 방식으로 깔 수 있습니다. 이 가이드 다섯 단계까지 마치고 첫 대화를 한 번 나눠 보신 뒤에, 필요한 확장 설정은 그때그때 골라서 추가하시면 충분합니다.