코덱스(Codex) CLI 설치 방법과 사용법: 윈도우 한 줄 설치

코덱스 CLI(Codex CLI)는 터미널에서 한국어로 요청하면 파일을 읽고 고치거나 명령을 실행하는 OpenAI의 도구입니다.

이 글은 윈도우에서 Codex CLI를 설치하고, 작업 폴더에서 로그인한 뒤 첫 파일 작업을 맡기고 결과 파일을 여는 데까지 다룹니다. 맥을 쓴다면 맥 설치 안내를 봅니다. 기능과 요금 설명은 2026년 10월 4일 공식 안내 기준입니다.

터미널에서 AI 도구를 쓰면 달라지는 세 가지

터미널은 글자로 명령을 입력해 컴퓨터를 조작하는 프로그램이고, 윈도우에서는 PowerShell이 이 일을 합니다. 윈도우 11의 터미널 앱을 열면 그 안에서 PowerShell이 실행되기도 합니다. CLI(Command Line Interface)는 이렇게 터미널에서 실행하는 프로그램을 말하고, Codex도 CLI 프로그램입니다.

AI가 글을 읽고 분석하고 쓰는 능력은 웹 채팅과 같습니다. 달라지는 것은 자료가 들어가는 길, 결과가 남는 곳, AI가 실행할 수 있는 일입니다.

웹 채팅과 터미널의 Codex

구분	웹 채팅	터미널의 Codex
자료가 들어가는 길	사람이 첨부하거나 붙여 넣음	작업 폴더의 파일을 직접 읽음
결과가 남는 곳	대화창, 사람이 복사해 저장	작업 폴더에 파일로 저장
실행할 수 있는 일	서비스가 제공하는 기능 안에서	허용한 범위의 파일 수정, 명령 실행

웹 채팅도 드라이브 같은 서비스를 연결하면 파일을 다룹니다. 터미널 도구의 가장 큰 차이는 내 컴퓨터의 폴더 하나를 작업 공간으로 정하고 그 안에서 일한다는 점입니다.

요청 한 번이 진행되는 순서

요청 하나는 다섯 단계로 끝납니다. 마지막 단계가 빠지면 AI가 다른 폴더에 저장했거나 요청과 다르게 쓴 경우를 놓칩니다.

Codex에 요청 하나를 맡길 때

1. 11. 요청할 일을 평소 말로
   명령어는 외우지 않아도 됨
2. 22. 읽기작업 폴더에서
   필요한 파일을 엶
3. 33. 작업과 저장권한 설정에 따라
   승인을 묻거나 바로 저장
4. 44. 완료 보고읽은 파일과
   만든 파일을 알려 줌
5. 55. 사람의 확인실제 파일을 열어
   요청과 대조

입력하는 곳이 두 군데입니다

같은 창 안에 입력하는 곳이 두 군데라서, AI에게 할 요청을 PowerShell 명령 입력줄에 넣거나 터미널 명령을 Codex 입력칸에 넣으면 의도와 다르게 동작합니다. 아래 단계마다 어디에 입력하는지 함께 적었습니다.

PowerShell 입력줄과 Codex 입력칸

구분	PowerShell 명령 입력줄	Codex 입력칸
화면에서 찾는 법	PS C:\Users\사용자이름> 같은 줄	codex 실행 뒤 나오는 입력칸
입력하는 것	터미널 명령	AI에게 하는 요청, /로 시작하는 명령
예	codex --version, 폴더 이동	파일 정리 요청, /exit

한눈에 보는 순서

ChatGPT 계정으로 CLI를 쓰려면 공식 요금 안내에서 CLI가 포함된 Plus 이상의 지원 플랜이 필요합니다. Free와 Go에 있는 데스크톱 앱 제공 범위에는 CLI가 들어 있지 않습니다. API 키로도 쓸 수 있지만 API 비용은 구독과 따로 청구되고, 회사 계정은 관리자 설정도 맞아야 합니다. 자세한 조건은 공식 요금 안내에 있습니다.

설치부터 첫 작업까지

1. 1준비. 계정Plus 이상 플랜
   또는 API 키
2. 21. 설치PowerShell에
   설치 명령 한 줄
3. 32. 폴더와 로그인새 작업 폴더에서
   codex 실행
4. 43. 첫 작업Codex 입력칸에
   파일 작업 요청
5. 54. 결과 확인파일 탐색기나
   PowerShell로 열기

1. PowerShell을 열고 설치합니다

Windows 키를 누르고 PowerShell을 검색해 일반 실행으로 엽니다. PS C:\Users\사용자이름> 같은 줄이 보이면 명령을 입력할 수 있습니다. 설치 프로그램은 사용자 폴더에 설치하므로 관리자 창으로 열지 않아도 됩니다.

아래는 OpenAI 공식 저장소가 안내하는 설치 명령입니다. PowerShell에 한 줄로 붙여 넣고 Enter를 누릅니다.

irm은 스크립트를 내려받고 iex는 그 내용을 실행합니다. -ExecutionPolicy ByPass는 이때 새로 시작하는 PowerShell 프로세스에만 실행 정책을 지정합니다. 시스템 전체 정책을 영구히 바꾸거나 회사의 관리 정책을 해제하는 명령이 아닙니다. Node.js는 따로 설치하지 않아도 됩니다.

기본 실행 파일 위치는 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin입니다. %LOCALAPPDATA%는 사용자별 앱 데이터 폴더를 뜻합니다. 설치가 끝나면 시작 메뉴에서 PowerShell을 새로 열고 버전을 확인합니다.

Windows PowerShell

> codex --version

codex-cli 0.156.1

버전 번호가 나오면 설치가 끝난 것입니다

명령을 찾지 못한다는 오류가 나오면 글 끝의 오류 해결에서 파일 경로부터 확인합니다.

이미 npm으로 Codex를 관리하고 있다면 그 방식을 그대로 써도 되고, 두 설치 방법을 겹쳐 실행하지 않습니다. 공식 설치 명령은 업데이트에도 쓸 수 있고, 자체 갱신을 지원하는 설치본에서는 codex update로도 업데이트합니다.

2. 작업 폴더를 만든 뒤 로그인합니다

Codex는 실행한 폴더 안에서 일하므로, 처음에는 원본 자료가 없는 새 폴더를 만듭니다. 아래 명령을 PowerShell에서 한 줄씩 실행합니다. 첫 줄은 폴더를 만들고, 둘째 줄은 그 위치로 이동하며, 셋째 줄은 현재 위치를 보여 줍니다.

$HOME은 사용자 홈 폴더입니다. 셋째 줄의 결과가 아래처럼 Projects\codex-practice로 끝나야 다음 단계로 넘어갑니다.

Windows PowerShell

> Get-Location

Path
----
C:\Users\사용자이름\Projects\codex-practice

경로 끝이 Projects\codex-practice인지 봅니다

같은 PowerShell에서 explorer .를 입력하면 이 폴더가 파일 탐색기로 열립니다. 맡길 업무 파일이 있다면 원본이 아니라 복사본을 이 폴더에 넣습니다. 요청이 잘못돼도 원본은 그대로 남습니다. 회사 자료라면 외부 AI 서비스에 넣어도 되는지 조직의 기준을 먼저 봅니다. 준비가 끝나면 codex를 입력합니다.

처음 실행하면 Sign in with ChatGPT를 고르고 브라우저에서 로그인합니다. 브라우저가 열리지 않으면 화면에 나온 주소를 직접 엽니다. 로그인 코드와 인증 주소는 다른 사람에게 보내지 않습니다. 터미널로 돌아오면 화면에 표시된 작업 폴더가 codex-practice인지 봅니다.

설치와 샌드박스 설정은 다른 단계입니다

샌드박스는 AI가 실행하는 명령의 파일 접근과 네트워크 사용 범위를 제한하는 기능입니다. CLI 설치는 일반 사용자 권한으로 끝나지만, 권장 Windows 샌드박스의 초기 설정에는 관리자 승인이 필요할 수 있습니다. 승인 창이 뜨면 내가 시작한 Codex 설정 과정에서 나온 창인지 보고 진행합니다.

Windows에서 고를 수 있는 실행 방식

항목	권장 샌드박스	unelevated	Full Access
파일과 명령 제한	제공	보호 방식이 다름	크게 풀림
쓰는 경우	기본	기본 설정을 쓸 수 없는 환경	오류 해결용으로 쓰지 않음
조직 정책	–	금지될 수 있음	–

회사 PC에서 승인이 막히면 담당자에게 오류 문구와 설정 요구를 보여 주고 허용된 방식을 묻습니다. 설정 오류를 풀려고 곧바로 Full Access로 바꾸지 않습니다.

3. 첫 작업을 맡기고 결과 파일을 엽니다

이제부터는 PowerShell 명령 대신 Codex 입력칸에 한국어 요청을 넣습니다. 첫 작업으로는 결과가 맞는지 바로 대조할 수 있는 일이 좋습니다. 예를 들어 회의록 텍스트 파일의 복사본을 meeting.txt라는 이름으로 작업 폴더에 넣었다면 이렇게 요청합니다.

작업 전에 권한을 묻는다면 대상 파일과 실행 내용을 읽고 승인합니다. 권한 설정에 따라 작업 폴더 안의 일부 동작은 묻지 않고 진행하며, 지금 허용된 범위는 Codex 입력칸에서 /permissions로 봅니다. 첫 작업에 권한을 더 넓히지 않습니다.

Codex, codex-practice

> meeting.txt를 읽고 담당자, 할 일, 마감을 표로 정리해서 todo.md에 UTF-8로 저장해줘.

meeting.txt를 읽고 todo.md를 만들었습니다.

이 답만 보고 끝내지 않고 todo.md를 엽니다

완료 답변을 받으면 파일 탐색기에서 todo.md가 생겼는지 봅니다. Codex 화면을 닫지 않고 확인하려면 PowerShell 창을 하나 더 열고 Set-Location "$HOME\Projects\codex-practice"로 같은 폴더에 들어간 뒤 파일을 읽습니다.

표의 줄 수가 회의록의 항목 수와 같은지, 원문에 담당자나 날짜가 없는 항목이 '미정'으로 남았는지 봅니다. 원문에 없는 이름이나 날짜가 채워졌다면 그 항목을 짚어 "이 항목의 담당자와 마감은 원문에 없으니 미정으로 고쳐줘"라고 다시 요청합니다. 위 Get-Content 명령은 파일을 읽기만 하고 고치지 않습니다.

파일이 없다는 오류가 나오면 Get-Location으로 현재 위치를 보고 파일 탐색기에서 실제 이름을 찾습니다. 파일 확장자 표시를 켜면 todo.md.txt처럼 저장된 경우도 보입니다. 한글이 깨진다면 notepad .\todo.md로 메모장에서 열어 저장 인코딩을 봅니다.

일부만 고칠 때도 고칠 곳과 그대로 둘 곳을 함께 적습니다. 예를 들어 todo.md에서 첫 번째 할 일의 마감만 바꿔 줘. 나머지 줄과 다른 파일은 그대로 둬.라고 요청한 뒤, 파일을 다시 열어 나머지 줄이 그대로인지 봅니다. 요청할 때마다 계정의 사용량이 쓰입니다.

작업 폴더에서 맡기기 좋은 일

첫 작업처럼 원문과 결과를 사람이 바로 대조할 수 있는 일이 Codex에 맡기기 좋습니다. 요청은 Codex 입력칸에 넣고, 확인은 PowerShell에서 합니다.

원문과 바로 대조할 수 있는 일

맡길 일	요청할 결과	확인하는 방법
회의록을 할 일 표로	todo.md에 담당자, 할 일, 마감	원문 항목 수와 표의 줄 수
공지나 계약서의 이전 판과 새 판 비교	changes.md에 바뀐 줄만 전후로	내가 아는 변경과 대조
폴더 안 파일 목록	index.md에 이름과 한 줄 설명	Get-ChildItem -Name 결과와 대조

세 가지 모두 원문을 주고, AI가 정리해 파일로 저장하고, 사람이 원문과 대조하는 순서입니다. 이전 판과 새 판을 비교할 때는 두 파일을 같은 폴더에 넣고 "바뀌지 않은 줄은 넣지 마"라고 적으면 결과가 짧아져 대조하기 쉽습니다.

모델과 추론 깊이 고르기

모델은 요청을 처리하는 AI의 종류이고, 추론 깊이는 답을 준비할 때 얼마나 많이 계산할지 정하는 값입니다. 첫 작업은 지금 선택된 설정 그대로 해도 됩니다.

Codex 입력칸에 /model을 입력하면 계정과 환경에서 쓸 수 있는 모델이 나옵니다. 2026년 10월 4일 문서의 주요 예시는 gpt-6.1-sol과 gpt-6-luna이고, 계정에 따라 Astra 같은 다른 선택지도 보입니다. 원하는 모델이 목록에 없어도 설치에는 문제가 없습니다. 고른 뒤에는 /status로 적용된 모델을 봅니다.

Codex, codex-practice

> /model

gpt-6.1-sol
gpt-6-luna

> /status

고른 뒤 /status로 적용된 모델 이름을 봅니다

추론 깊이는 모델이 지원하는 항목 가운데서 고릅니다. 처음에는 기본값으로 쓰고, 어려운 작업에서 결과가 부족할 때 올리면서 시간과 사용량이 얼마나 늘어나는지 봅니다. 모델별 설명은 공식 모델 안내에 있습니다.

자주 묻는 질문

어떤 Windows 버전에서 시작하나요?

공식 안내는 Windows 11을 권장합니다. 최신 업데이트가 적용된 Windows 10은 제한적인 최선 노력 지원이고, 1809 이상이 필요합니다. PowerShell에서 winver를 입력하면 Windows 버전 창이 열립니다. 공식 안내가 전제하는 패키지 관리 프로그램은 winget --version으로 확인합니다. 이 명령을 찾지 못하면 Windows 업데이트나 Windows 패키지 관리자 설치 상태를 보고, 회사 PC라면 담당자에게 문의합니다.

WSL도 설치해야 하나요?

이 글의 Windows 기본 설치에는 필요하지 않습니다. WSL은 Windows에서 Linux 환경을 쓰는 기능이며, Linux 도구가 필요한 프로젝트에서 따로 고를 수 있습니다.

유료 ChatGPT 구독이 꼭 필요한가요?

ChatGPT 계정으로 로그인해 쓰려면 Plus 이상의 지원 플랜이 필요하고, API 키 방식은 구독과 별개로 API 요금이 나갑니다. 개인용 Plus는 월 20달러이고 Pro는 월 100, 200, 500달러 선택지가 있습니다. 실제 결제 금액은 지역과 세금에 따라 결제 화면에서 정해지고, 회사 계정은 관리자 설정에 따라 쓸 수 있는 모델이 다릅니다.

Claude Code와 함께 설치해도 되나요?

됩니다. 명령 이름이 claude와 codex로 다르고 설정도 따로 관리합니다. 같은 파일을 두 도구가 동시에 고치지 않게 하고, 한쪽 결과를 다른 쪽에 넘길 때는 결과를 먼저 확인합니다. 두 도구를 순서대로 사용하는 연습에 예시가 있습니다.

설치 중 막히면 이렇게 확인합니다

codex를 명령 이름으로 인식하지 못할 때는 아래 순서로 원인을 좁힙니다.

codex 명령을 못 찾을 때

1. 11. 새 창에서 다시새 PowerShell에서
   codex --version
2. 22. 파일 확인Test-Path로
   codex.exe가 있는지
3. 33. 전체 경로 실행True라면
   전체 경로로 --version
4. 44. PATH 추가전체 경로로 되면
   사용자 Path에 bin 폴더
5. 55. 설치 다시 보기False라면 설치 오류와
   실제 설치 위치

codex가 명령 이름으로 인식되지 않습니다

새 PowerShell 창에서 codex --version을 다시 실행합니다. 그래도 같으면 기본 설치 위치에 파일이 있는지 확인합니다.

True라면 전체 경로로 버전을 확인합니다. 앞의 &는 따옴표 안의 경로를 프로그램으로 실행하라는 뜻입니다.

전체 경로로 실행된다면 PATH, 즉 명령을 찾는 폴더 목록에 설치 폴더가 빠진 경우입니다. 시작 메뉴에서 계정의 환경 변수 편집을 검색해 사용자 변수의 Path에 위 bin 폴더 경로가 있는지 봅니다. 없다면 새 항목에 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin을 추가합니다. 이 창에는 PowerShell의 $env: 표기를 넣지 않고, 기존 항목이나 전체 Path 값은 지우지 않습니다. 저장한 뒤 새 PowerShell에서 다시 확인합니다.

False라면 PATH를 추가하지 말고 설치 마지막 오류와 실제 설치 위치부터 봅니다. 설치할 때 경로를 따로 지정했다면 그 위치를 씁니다.

다른 버전의 Codex가 실행됩니다

경로가 여러 개 나오면 설치 방식이 둘 이상입니다. 삭제 명령부터 실행하지 말고 어느 방식으로 관리할지 정한 뒤 해당 경로의 버전을 봅니다.

명령은 실행되지만 로그인이나 설정 오류가 납니다

Codex를 종료한 일반 PowerShell에서 다음을 실행합니다.

진단 결과에서 실패한 항목과 오류 문구를 봅니다. 샌드박스 오류라면 Windows 버전, 관리자 승인 여부, 회사 정책 가운데 어디서 막혔는지 나눠 봅니다. 회사의 접속 제한은 임의로 우회하지 말고 담당자에게 허용된 방법을 묻습니다. 도움을 요청할 때 로그인 코드나 .sandbox-secrets 폴더 내용은 보내지 않습니다.

참고 자료

• 공식 설치 명령
• Codex CLI 시작
• 설치 경로
• Windows 샌드박스
• 명령과 진단 기능