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

터미널 기반 AI 코딩 도구가 늘어나는 흐름

2025년부터 2026년 사이, 코딩을 돕는 AI 도구의 중심이 Cursor 같은 IDE 안의 자동완성에서 터미널 안에서 직접 일을 시키는 에이전트 쪽으로 옮겨 가는 모습입니다. 앤트로픽의 클로드 코드(Claude Code)가 이 방식으로 널리 쓰이는 도구라면, OpenAI 쪽에서 같은 방식으로 만든 도구가 코덱스 CLI(Codex CLI)입니다.

맥에서 코덱스 CLI를 처음 깔 때 마주치는 화면은 터미널(Terminal)입니다. 평소 Spotlight와 Finder로만 일을 처리해 오신 분이라면 마우스로 쓰는 앱보다 낯설 수 있지만, 터미널은 클릭 대신 짧은 한 줄로 일을 시킨다는 점만 다릅니다.

설치는 예전보다 더 짧아졌습니다. 전에는 Homebrew와 Node.js를 먼저 깔고 npm으로 본체를 받았는데, 지금은 OpenAI가 맥용 설치 스크립트를 따로 내놓아서 터미널에 한 줄만 붙여 넣으면 됩니다. Apple Silicon(M1 이후)과 Intel 맥 모두 같은 순서로 진행합니다. 설치하다 막혔을 때 뜨는 메시지별 해결법은 글 끝 자주 발생하는 문제에 정리했습니다.

“

코덱스 CLI(Codex CLI)는 OpenAI가 만든 터미널 기반 AI 코딩 도구입니다. 맥에서는 터미널에 curl -fsSL https://chatgpt.com/codex/install.sh | sh 한 줄로 본체를 받고, codex를 실행해 ChatGPT 계정으로 로그인하면 첫 작업 준비가 끝납니다. 모델은 GPT-6 Astra, Sol, Luna 가운데 고르고, 추론 깊이는 low부터 ultra까지 여섯 단계가 있습니다.

아래 설치 명령과 기본값은 2026년 9월 23일, 코덱스 CLI 0.156.1 기준입니다.

한눈에 보는 설치 순서

시작하기 전에 계정을 확인해 주세요. ChatGPT Plus 이상 플랜이 있으면 바로 시작할 수 있습니다. 플랜별 차이는 자주 묻는 질문에 따로 정리했습니다.

맥(macOS)에서 설치하는 방법입니다. 윈도우 PC를 쓰시는 분은 윈도우용 가이드를 참고하세요.

Step 1. 터미널 열기

설치 작업은 모두 터미널(Terminal) 안에서 합니다. 맥에 기본으로 깔려 있는 앱입니다.

1. 키보드의 ⌘ Command + Space를 누르세요. (Spotlight 검색)
2. "터미널" 또는 "Terminal"이라고 입력합니다.
3. 엔터를 눌러 터미널을 실행하세요.

✅ 성공 신호: 검은(또는 흰) 창이 열리고 깜빡이는 커서가 나타납니다. 이후 모든 명령어는 이 창에 입력합니다.

Step 2. 코덱스 CLI 설치

아래 한 줄을 터미널에 복사해서 붙여 넣고 엔터를 누르세요.

설치 스크립트가 최신 버전을 내려받아 사용자 폴더(~/.local/bin)에 깔고, 필요하면 셸 설정 파일에 경로까지 추가합니다. sudo와 맥 비밀번호는 필요 없습니다.

설치가 끝나면 터미널을 완전히 닫았다가 다시 열어 주세요. ⌘ Command + Q로 종료한 뒤 다시 실행하면 됩니다. 새 창을 열어야 codex 명령이 인식됩니다.

확인 명령어:

codex-cli 0.156.1처럼 버전 번호가 나오면 정상입니다. 새 버전이 나오면 숫자는 더 커집니다. 업데이트할 때는 같은 설치 명령을 한 번 더 실행하거나 codex update를 입력하면 됩니다.

위 명령으로 설치했다면 이 표는 건너뛰세요. Homebrew나 npm으로 프로그램을 관리하는 분을 위한 다른 방법입니다.

Homebrew는 새 버전이 조금 늦게 올라와서 2026년 9월 23일 기준 0.155.0이고, 설치 스크립트와 npm은 0.156.1입니다. 처음이라면 따로 준비할 것이 없는 설치 스크립트 쪽이 간단합니다.

✅ 성공 신호: codex --version에 버전 번호가 출력되면 설치 완료입니다.

Step 3. 처음 실행하고 ChatGPT 로그인

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

처음 실행하면 로그인 방법을 묻습니다. Sign in with ChatGPT를 고르고 엔터를 누르면 웹 브라우저가 열립니다. ChatGPT 계정으로 로그인하고 터미널로 돌아오면 인증 정보가 알아서 넘어와 있습니다.

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

✅ 성공 신호: 터미널 창에 코덱스 CLI 화면이 뜨고, 위쪽 상자에 지금 쓰는 모델 이름이 표시되며, 메시지를 입력할 수 있는 상태가 됩니다. 다음 단계로 넘어가기 위해 /exit를 입력해 종료하세요.

Step 4. 작업 폴더를 만들고 한국어로 첫 작업

코덱스 CLI는 지금 있는 폴더 안에서 일합니다. 연습할 폴더를 먼저 만들고 그 안에서 실행하세요.

첫 줄은 홈 폴더 안에 작업 폴더를 만들고, 둘째 줄은 그 폴더로 이동하고, 셋째 줄은 그 폴더에서 코덱스 CLI를 실행합니다.

코덱스 CLI에는 언어 설정 메뉴가 따로 없습니다. 안내 문구는 영어로 나오지만 한국어로 부탁하면 한국어로 답합니다. 첫 메시지로 이렇게 입력해 보세요.

파일을 만들거나 명령을 실행하기 전에 허락을 묻는 질문이 나오면, 내용을 읽고 화살표 키로 허용하는 항목(보통 Yes로 시작하는 줄)을 골라 엔터를 누릅니다. 어디까지 묻지 않고 진행할지는 /permissions 명령으로 바꿀 수 있습니다.

✅ 성공 신호: 코덱스 CLI가 파일을 만들고 무엇을 했는지 한국어로 알려 주면 설치부터 첫 작업까지 모두 끝난 것입니다.

Step 5. GPT-6 모델과 추론 깊이 고르기

지금 코덱스 CLI에서 고를 수 있는 주력 모델은 GPT-6 계열 세 가지입니다. GPT-6 Sol과 Luna가 나온 과정은 따로 정리해 두었습니다.

기본 모델은 요금제에 따라 다릅니다. 2026년 9월 23일 기준으로 Pro 계정에서 설정 파일 없이 실행할 때의 기본 모델은 gpt-6-astra이고, 공식 문서의 예시 화면에는 gpt-6-sol이 표시됩니다. 지금 쓰는 모델은 실행 화면 위쪽 상자에 나옵니다.

모델과 따로 추론 깊이(reasoning effort)를 고릅니다. 같은 모델이라도 답하기 전에 얼마나 오래 생각할지를 정하는 값이고, 기본값은 medium입니다.

모델과 추론 깊이는 코덱스 CLI 안에서 /model을 입력해 목록에서 고르면 됩니다. 여기서 고른 값은 설정 파일(config.toml)에 저장돼 다음 실행에도 그대로 유지되므로, 설정 파일을 따로 고칠 필요는 없습니다. 한 번만 다른 모델로 실행하고 싶을 때는 codex -m gpt-6-sol처럼 지정합니다.

설정 파일을 직접 열어 고칠 때는 새 줄을 덧붙이지 말고, 파일 맨 위에 이미 있는 model = 줄과 model_reasoning_effort = 줄의 값만 바꿉니다. 같은 줄이 두 번 들어가면 설정 파일을 읽지 못해 오류가 납니다.

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

두 도구는 터미널에서 자연어로 일을 시키고, 파일을 직접 읽고 고치고, 명령을 대신 실행해 주는 같은 종류의 AI 코딩 도구입니다. 사용하는 방식도 거의 같습니다.

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

어느 한쪽만 써야 할 이유는 거의 없습니다. 둘 다 깔아 두고 작업 성격에 따라 골라 쓰거나, 같은 문제를 두 도구에 한 번씩 맡겨 답을 비교해 보는 방식이 실용적입니다.

자주 묻는 질문

코덱스 CLI는 맥의 어느 버전부터 설치할 수 있나요?

공식 설치 안내는 맥 버전을 따로 적어 두지 않았습니다. 최근 macOS에서 Apple Silicon 맥과 Intel 맥 모두 같은 명령으로 설치할 수 있고, 설치 스크립트가 칩 종류에 맞는 파일을 알아서 받습니다.

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

ChatGPT 계정으로 로그인해 CLI를 쓰려면 Plus 이상 유료 플랜이 필요합니다. 2026년 9월 23일 기준 공식 요금 안내는 이렇게 나뉩니다.

회사 계정이라면 Business와 Enterprise 플랜도 있습니다. 공식 요금 문서 안에서도 Plus의 요금 카드에는 Sol과 Luna만 적혀 있고, 아래 사용량 표에는 Plus의 GPT-6 Astra 한도(5시간에 5~45회)가 함께 나옵니다.

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

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

추론 깊이를 항상 max나 ultra로 두는 게 좋지 않나요?

일반적인 작업에서는 권하지 않습니다. 깊게 생각할수록 답이 늦어지고 남은 사용량도 더 빨리 줄어듭니다. 기본값 medium으로 쓰다가 어려운 디버깅이나 큰 수정을 맡길 때만 올리는 편이 효율적입니다.

코덱스 CLI 설치 중 자주 발생하는 문제

무엇이 잘못됐는지 모르겠다면 진단 명령을 먼저 돌려 보세요. 설치 경로, 설정, 로그인 상태를 점검해 알려 줍니다.

이 명령으로도 원인을 모르겠으면 아래 항목에서 같은 증상을 찾아봅니다.

• "command not found: codex": 설치한 창에서 바로 실행하면 인식되지 않을 수 있습니다. 터미널을 ⌘ Command + Q로 완전히 종료하고 다시 여세요. 그래도 같으면 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc를 입력한 뒤 codex --version을 다시 확인합니다.
• 예전에 npm으로 깐 코덱스가 먼저 실행됩니다: which -a codex로 어떤 경로의 codex가 잡히는지 봅니다. 한 가지 방법만 남기려면 npm uninstall -g @openai/codex로 npm 쪽을 지웁니다.
• ChatGPT 로그인 창이 열리지 않습니다: 기본 브라우저 설정이 비어 있거나 회사 네트워크가 로그인 페이지를 막는 경우입니다. 터미널에 나온 주소를 브라우저에 직접 붙여 넣거나, 개인 네트워크로 옮겨 다시 시도해 보세요.
• 원하는 GPT-6 모델이 /model 목록에 보이지 않습니다: 쓰는 플랜에서 아직 열리지 않은 모델일 가능성이 큽니다. 제공 범위는 플랜과 순차 제공 일정에 따라 다릅니다.

맥에서 코덱스 CLI 설치 정리

• 설치: 터미널에 curl -fsSL https://chatgpt.com/codex/install.sh | sh 한 줄. Homebrew와 Node.js는 필요 없습니다.
• 로그인: codex를 실행해 ChatGPT 계정으로 로그인합니다. CLI는 Plus 이상 플랜에 포함됩니다.
• 첫 사용: 작업 폴더에서 한국어로 바로 부탁하면 됩니다. 모델과 추론 깊이는 /model로 바꿉니다.
• 막혔을 때: codex doctor로 설치와 로그인 상태를 먼저 확인합니다.

같은 작업을 두 도구에 시켜 결과를 비교한 기록은 코덱스 CLI와 클로드 코드 비교에 정리해 두었습니다. 익숙해진 뒤에는 /permissions로 코덱스가 묻지 않고 진행할 범위를 조금씩 늘려 보세요. 처음부터 다 열어 두기보다 한 작업씩 결과를 확인하는 편이 안전합니다.