쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(맥)
맥 터미널에 공식 설치 명령 한 줄로 Codex CLI를 설치하고, 작업 폴더에서 로그인한 뒤 첫 파일 작업을 맡기는 순서를 설명합니다. 입력하는 곳 두 군데, 결과 파일 확인, 명령을 못 찾을 때 확인할 경로도 정리했습니다.
세 줄로 먼저 읽기
- 맥의 공식 설치 스크립트는 Homebrew나 Node.js를 따로 준비하지 않고 Codex CLI를 사용자 홈 폴더의 .local/bin에 설치합니다.
- 새 작업 폴더에서 codex를 실행해 ChatGPT 계정으로 로그인하고, 결과는 Finder나 cat으로 실제 파일을 열어 확인합니다.
- 모델은 /model에서 고르고 /status로 확인하며 codex 명령을 못 찾으면 설치 파일 위치와 PATH부터 점검합니다.
코덱스 CLI(Codex CLI)는 터미널에서 한국어로 요청하면 파일을 읽고 고치거나 명령을 실행하는 OpenAI의 도구입니다.
이 글은 맥에서 Codex CLI를 설치하고, 작업 폴더에서 로그인한 뒤 첫 파일 작업을 맡기고 결과 파일을 여는 데까지 다룹니다. Windows를 쓴다면 윈도우 설치 안내를 봅니다. 기능과 요금 설명은 2026년 10월 4일 공식 안내 기준입니다.
터미널에서 AI 도구를 쓰면 달라지는 세 가지
터미널은 글자로 명령을 입력해 컴퓨터를 조작하는 프로그램이고, 맥에서는 기본 앱인 터미널(Terminal)이 이 일을 합니다. 폴더를 만들거나 파일 내용을 볼 때 마우스로 하던 일을 한 줄 명령으로 처리합니다. CLI(Command Line Interface)는 이렇게 터미널에서 실행하는 프로그램을 말하고, Codex도 CLI 프로그램입니다.
AI가 글을 읽고 분석하고 쓰는 능력은 웹 채팅과 같습니다. 달라지는 것은 자료가 들어가는 길, 결과가 남는 곳, AI가 실행할 수 있는 일입니다.
웹 채팅과 터미널의 Codex
| 구분 |  웹 채팅 |  터미널의 Codex |
|---|---|---|
| 자료가 들어가는 길 | 사람이 첨부하거나 붙여 넣음 | 작업 폴더의 파일을 직접 읽음 |
| 결과가 남는 곳 | 대화창, 사람이 복사해 저장 | 작업 폴더에 파일로 저장 |
| 실행할 수 있는 일 | 서비스가 제공하는 기능 안에서 | 허용한 범위의 파일 수정, 명령 실행 |
웹 채팅도 드라이브 같은 서비스를 연결하면 파일을 다룹니다. 터미널 도구의 가장 큰 차이는 내 컴퓨터의 폴더 하나를 작업 공간으로 정하고 그 안에서 일한다는 점입니다.
요청 한 번이 진행되는 순서
요청 하나는 다섯 단계로 끝납니다. 마지막 단계가 빠지면 AI가 다른 폴더에 저장했거나 요청과 다르게 쓴 경우를 놓칩니다.
Codex에 요청 하나를 맡길 때
- 1. 요청할 일을 평소 말로
명령어는 외우지 않아도 됨 
2. 읽기작업 폴더에서
필요한 파일을 엶
3. 작업과 저장권한 설정에 따라
승인을 묻거나 바로 저장
4. 완료 보고읽은 파일과
만든 파일을 알려 줌
5. 사람의 확인실제 파일을 열어
요청과 대조
입력하는 곳이 두 군데입니다
같은 창 안에 입력하는 곳이 두 군데라서, AI에게 할 요청을 터미널 명령 입력줄에 넣거나 터미널 명령을 Codex 입력칸에 넣으면 의도와 다르게 동작합니다. 아래 단계마다 어디에 입력하는지 함께 적었습니다.
터미널 입력줄과 Codex 입력칸
| 구분 | 터미널 명령 입력줄 | Codex 입력칸 |
|---|---|---|
| 화면에서 찾는 법 | % 뒤의 커서 | codex 실행 뒤 나오는 입력칸 |
| 입력하는 것 | 터미널 명령 | AI에게 하는 요청, /로 시작하는 명령 |
| 예 | codex --version, 폴더 이동 | 파일 정리 요청, /exit |
한눈에 보는 순서
ChatGPT 계정으로 CLI를 쓰려면 공식 요금 안내 기준으로 CLI가 포함된 Plus 이상의 플랜이 필요합니다. Free와 Go 플랜에서 제공하는 데스크톱 앱 범위에는 CLI가 들어 있지 않습니다. API 키로도 쓸 수 있지만 API 비용은 구독과 따로 청구되고, 회사 계정은 관리자 설정도 맞아야 합니다. 자세한 조건은 공식 요금 안내에 있습니다.
설치부터 첫 작업까지
준비. 계정Plus 이상 플랜
또는 API 키
1. 설치터미널에
설치 명령 한 줄
2. 폴더와 로그인새 작업 폴더에서
codex 실행
3. 첫 작업Codex 입력칸에
파일 작업 요청
4. 결과 확인Finder나
터미널로 열기
1. 터미널을 열고 설치합니다
Command + Space를 누르고 터미널 또는 Terminal을 검색해 엽니다. % 뒤에 커서가 깜빡이면 명령을 입력할 수 있습니다. 아래는 OpenAI 공식 저장소가 안내하는 설치 명령입니다. 한 줄로 붙여 넣고 Enter를 누릅니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh이 명령은 공식 설치 스크립트를 내려받아 실행하므로 Homebrew나 Node.js를 따로 설치하지 않아도 됩니다. 기본 실행 파일 위치는 사용자 홈 폴더 아래 ~/.local/bin입니다. 설치 안내에 다른 위치가 나오면 그 경로를 적어 둡니다.
설치가 끝나면 터미널이 선택된 상태에서 Command + N으로 새 창을 열고 버전을 확인합니다. 원래 창은 닫지 않아도 됩니다.
command not found가 나오면 글 끝의 오류 해결에서 파일 경로부터 확인합니다.
이미 Homebrew나 npm으로 Codex를 관리하고 있다면 그 방식을 그대로 쓰고, 다른 설치 방법을 겹쳐 실행하지 않습니다. 여러 방식으로 설치하면 서로 다른 버전이 잡힙니다. 공식 스크립트로 설치했다면 같은 명령으로 업데이트하고, 자체 갱신을 지원하는 설치본에서는 codex update로도 업데이트합니다.
2. 작업 폴더를 만든 뒤 로그인합니다
Codex는 실행한 폴더 안에서 일하므로, 처음에는 원본 자료가 없는 새 폴더를 만듭니다. 아래 명령을 터미널에 한 줄씩 입력합니다. mkdir은 폴더를 만들고, cd는 그 폴더로 이동하며, pwd는 현재 위치를 보여 줍니다.
mkdir -p "$HOME/Projects/codex-practice"
cd "$HOME/Projects/codex-practice"
pwd셋째 줄의 결과가 아래처럼 Projects/codex-practice로 끝나야 다음 단계로 넘어갑니다.
같은 터미널에 open .을 입력하면 이 폴더가 맥의 파일 관리 앱인 Finder로 열립니다. 맡길 업무 파일이 있다면 원본이 아니라 복사본을 이 폴더에 넣습니다. 요청이 잘못돼도 원본은 그대로 남습니다. 회사 자료라면 외부 AI 서비스에 넣어도 되는지 조직의 기준을 먼저 봅니다. 준비가 끝나면 codex를 입력합니다.
처음 실행하면 Sign in with ChatGPT를 고르고 브라우저에서 로그인합니다. 브라우저가 열리지 않으면 터미널에 나온 주소를 직접 엽니다. 로그인 주소와 인증 코드는 다른 사람에게 보내지 않습니다. 터미널로 돌아오면 화면에 표시된 작업 폴더가 codex-practice인지 봅니다.
3. 첫 작업을 맡기고 결과 파일을 엽니다
이제부터는 터미널 명령 대신 Codex 입력칸에 한국어 요청을 넣습니다. 첫 작업으로는 결과가 맞는지 바로 대조할 수 있는 일을 맡깁니다. 예를 들어 회의록 텍스트 파일의 복사본을 meeting.txt라는 이름으로 작업 폴더에 넣었다면 이렇게 요청합니다.
meeting.txt를 읽고 담당자, 할 일, 마감을 표로 정리해서 todo.md에 저장해줘.
원문에 없는 담당자나 날짜는 만들지 말고 '미정'으로 적어줘.
같은 이름의 파일이 있으면 덮어쓰지 말고 알려 주고, 다른 파일은 수정하지 마.Codex가 작업 전에 권한을 물으면 대상 파일과 실행 내용을 읽고 승인합니다. 권한 설정에 따라 작업 폴더 안의 일부 동작은 묻지 않고 진행하며, 지금 허용된 범위는 Codex 입력칸에서 /permissions로 봅니다. 첫 작업에 권한을 더 넓히지 않습니다.
완료 답변을 받으면 Finder에서 todo.md를 선택하고 Space 키를 눌러 미리보기로 봅니다. Codex 화면을 닫지 않고 터미널로 확인하려면 Command + N으로 새 창을 열고 cd "$HOME/Projects/codex-practice"로 같은 폴더에 들어간 뒤 파일을 읽습니다.
cat todo.md표의 줄 수가 회의록의 항목 수와 같은지, 원문에 담당자나 날짜가 없는 항목이 '미정'으로 남았는지 봅니다. 원문에 없는 이름이나 날짜가 채워졌다면 그 항목을 짚어 "이 항목의 담당자와 마감은 원문에 없으니 미정으로 고쳐줘"라고 다시 요청합니다. cat은 파일 내용을 보여 주기만 하고 고치지 않습니다.
파일이 없다는 오류가 나오면 pwd로 현재 위치를 보고 Finder에서 실제 파일 이름을 찾습니다. Codex가 답에서 어디에 저장했다고 했는지도 다시 읽습니다.
일부만 고칠 때도 고칠 곳과 그대로 둘 곳을 함께 적습니다. 예를 들어 todo.md에서 첫 번째 할 일의 마감만 바꿔 줘. 나머지 줄과 다른 파일은 그대로 둬.라고 요청한 뒤, 파일을 다시 열어 나머지 줄이 그대로인지 봅니다. 요청할 때마다 계정 사용량이 줄어듭니다.
작업 폴더에서 맡기기 좋은 일
첫 작업처럼 원문과 결과를 사람이 바로 대조할 수 있는 일이 Codex에 맡기기 좋습니다. 요청은 Codex 입력칸에 넣고, 확인은 터미널에서 합니다.
원문과 바로 대조할 수 있는 일
| 맡길 일 | 요청할 결과 | 확인하는 방법 |
|---|---|---|
| 회의록을 할 일 표로 | todo.md에 담당자, 할 일, 마감 | 원문 항목 수와 표의 줄 수 |
| 공지나 계약서의 이전 판과 새 판 비교 | changes.md에 바뀐 줄만 전후로 | 내가 아는 변경과 대조 |
| 폴더 안 파일 목록 | index.md에 이름과 한 줄 설명 | ls 결과와 대조 |
세 가지 모두 원문을 주고, AI가 정리해 파일로 저장하고, 사람이 원문과 대조하는 순서입니다. 이전 판과 새 판을 비교할 때는 두 파일을 같은 폴더에 넣고 "바뀌지 않은 줄은 넣지 마"라고 적으면 결과가 짧아져 대조하기 쉽습니다. 파일 목록을 맡겼다면 터미널에서 ls와 cat index.md를 차례로 실행해, ls에 나온 파일 이름이 index.md에 모두 있는지 봅니다.
모델과 추론 깊이 고르기
모델은 요청을 처리하는 AI의 종류이고, 추론 깊이는 답을 준비할 때 얼마나 많이 계산할지 정하는 값입니다. 첫 작업은 지금 선택된 설정 그대로 해도 됩니다.
Codex 입력칸에 /model을 입력하면 계정과 환경에서 쓸 수 있는 모델이 나옵니다. 2026년 10월 4일 문서의 주요 예시는 gpt-6.1-sol과 gpt-6-luna이고, 계정에 따라 Astra 같은 다른 선택지도 보입니다. 원하는 모델이 목록에 없어도 설치에는 문제가 없습니다. 고른 뒤에는 /status로 적용된 모델을 봅니다.
gpt-6-luna
추론 깊이는 모델이 지원하는 항목 가운데서 고릅니다. 처음에는 기본값으로 쓰고, 어려운 작업에서 결과가 부족할 때 올리면서 시간과 사용량이 얼마나 늘어나는지 봅니다. 모델별 설명은 공식 모델 안내에 있습니다.
자주 묻는 질문
데스크톱 앱의 설치 조건과 같나요?
CLI와 데스크톱 앱은 다른 프로그램이라 설치 조건도 따로 봅니다. 공식 저장소는 Apple Silicon과 Intel용 CLI 파일을 각각 제공하고, 이 글은 공식 macOS용 CLI 설치 방법을 따릅니다. 설치나 실행이 실패하면 맥의 운영체제 버전과 오류 문구를 공식 설치 안내와 대조합니다.
유료 ChatGPT 구독이 꼭 필요한가요?
ChatGPT 계정으로 로그인해 쓰려면 Plus 이상의 지원 플랜이 필요하고, API 키 방식은 구독과 별개로 API 요금이 나갑니다. 개인용 Plus는 월 20달러이고 Pro는 월 100, 200, 500달러 선택지가 있습니다. 실제 결제 금액은 지역과 세금에 따라 결제 화면에서 정해지고, 회사 계정은 관리자 설정에 따라 쓸 수 있는 모델이 다릅니다.
Claude Code와 함께 설치해도 되나요?
됩니다. 명령 이름이 claude와 codex로 다르고 설정도 따로 관리합니다. 같은 파일을 두 도구가 동시에 고치지 않게 하고, 한쪽 결과를 다른 쪽에 넘길 때는 결과를 먼저 확인합니다. 두 도구를 순서대로 사용하는 연습에 예시가 있습니다.
설치 중 막히면 이렇게 확인합니다
command not found: codex가 나올 때는 아래 순서로 원인을 좁힙니다.
codex 명령을 못 찾을 때
1. 새 창에서 다시새 터미널 창에서
codex --version
2. 파일 확인ls -l로
.local/bin/codex가 있는지- 3. 전체 경로 실행파일이 있으면
전체 경로로 --version 
4. PATH 추가전체 경로로 되면
.zshrc에 경로 한 줄
5. 설치 다시 보기파일이 없으면 설치 오류와
실제 설치 위치
command not found: codex가 나옵니다
새 터미널 창에서 codex --version을 다시 실행합니다. 그래도 같으면 기본 설치 위치에 파일이 있는지 확인합니다.
ls -l "$HOME/.local/bin/codex"파일이 있다면 전체 경로로 버전을 확인합니다.
"$HOME/.local/bin/codex" --version전체 경로로 실행된다면 PATH, 즉 명령을 찾는 폴더 목록에 설치 폴더가 빠진 경우입니다. 먼저 지금 터미널에서만 경로를 더해 확인합니다.
export PATH="$HOME/.local/bin:$PATH"
codex --version여기서 버전이 나오면 새 창에서도 경로가 적용되게 설정 파일에 한 줄을 넣습니다. 맥의 기본 셸인 zsh는 ~/.zshrc를 읽습니다. 아래 명령은 이 파일을 텍스트 편집기(TextEdit)로 엽니다. touch는 파일이 없으면 만들고, 있으면 기존 내용을 그대로 둡니다.
touch "$HOME/.zshrc"
open -a TextEdit "$HOME/.zshrc"기존 내용은 지우지 않고, export PATH="$HOME/.local/bin:$PATH"가 없을 때만 따로 한 줄로 추가해 저장합니다. 새 터미널 창에서 codex --version을 다시 확인합니다. zsh가 아닌 셸을 쓴다면 그 셸의 설정 파일에 넣습니다.
ls -l에서 파일이 없다고 나오면 PATH를 바꿔도 해결되지 않습니다. 설치 마지막 오류와 실제 설치 위치부터 봅니다.
다른 버전의 Codex가 실행됩니다
which -a codex경로가 여러 개 나오면 Codex가 두 가지 이상의 방식으로 설치된 상태입니다. 삭제 명령부터 실행하지 말고 어느 방식으로 관리할지 정한 뒤 해당 경로의 버전을 봅니다. npm으로 설치한 프로그램을 지우는 명령과 스크립트로 설치한 파일을 정리하는 방법은 서로 다릅니다.
명령은 실행되지만 로그인이나 설정 오류가 납니다
Codex를 종료한 일반 터미널에서 다음을 실행합니다.
codex doctor설치, 설정, 인증 상태를 점검하는 진단 보고서가 나옵니다. 실패한 항목과 오류 문구부터 봅니다. 외부에 도움을 요청할 때는 오류 문구와 버전을 보내고, 인증 코드나 개인 경로는 지웁니다. 회사 네트워크가 접속을 막는다면 임의로 우회하지 말고 담당자에게 허용된 연결 방법을 묻습니다.
참고 자료
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
Codex가 파일을 만들었다고 답하면 무엇을 확인하나요?
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.
이 글이 도움이 되었나요?
코딩 에이전트가 무엇이고 도구마다 무엇이 다른지, 비개발자 눈높이로 고르는 기준까지
코스 전체 보기 →