가이드 · AI 코딩
Codex CLI 설치 방법: macOS·Windows·Linux, npm·Homebrew와 로그인 오류 해결
macOS·Linux는 터미널에서 curl -fsSL https://chatgpt.com/codex/install.sh | sh 를, Windows는 PowerShell에서 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" 를 실행합니다. Node.js가 있으면 npm install -g @openai/codex 로도 설치합니다. 새 터미널 창에서 codex 를 실행하고 Sign in with ChatGPT를 고르면 ChatGPT 요금제로 씁니다.
심규섭 · 수정 · 2026.11.18 확인 (Codex CLI 0.169.1(macOS, npm 설치)) · 에이전트용 Markdown
목차
이 문서는 터미널을 처음 여는 사람을 기준으로 썼습니다. 설치 명령, 로그인, 설치 확인, 자주 나는 오류 순서로 정리했습니다. 명령어는 2026-11-18에 Codex 공식 문서, 공식 설치 스크립트와 대조했습니다. 같은 날 macOS에서 npm으로 0.169.1을 설치해 출력을 확인했습니다.
Codex CLI 설치 방법
Codex CLI는 OpenAI의 코딩 에이전트를 터미널에서 쓰는 프로그램입니다. CLI는 마우스 대신 글자로 명령을 입력하는 방식입니다. 운영체제에 맞는 명령 하나만 실행합니다.
macOS, Linux (터미널)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npm (Node.js가 이미 있을 때)
npm install -g @openai/codex
Homebrew (macOS)
brew install --cask codex
설치가 끝나면 새 터미널 창을 엽니다. 그 창에서 codex --version을 실행합니다. codex-cli 0.169.1처럼 버전 번호가 나오면 설치된 것입니다. 그다음 작업할 폴더에서 codex를 실행하고 로그인합니다.
| 방법 | 먼저 필요한 것 | 설치 위치 | 업데이트 |
|---|---|---|---|
| 설치 스크립트 (macOS·Linux) | 없음 | ~/.local/bin/codex |
같은 명령 다시 실행 또는 codex update |
| 설치 스크립트 (Windows) | 없음 | %LOCALAPPDATA%\Programs\OpenAI\Codex\bin |
같은 명령 다시 실행 또는 codex update |
| npm | Node.js | npm 전역 폴더 | codex update |
| Homebrew | Homebrew (macOS) | Homebrew 폴더 | codex update |
처음이면 설치 스크립트를 씁니다. Node.js나 Homebrew가 필요 없습니다. 스크립트는 내려받은 파일의 SHA-256 값을 확인한 뒤 설치합니다.
설치 전에 확인할 것
| 항목 | 요구사항 |
|---|---|
| macOS | 12 이상 |
| Linux | Ubuntu 20.04 이상, Debian 10 이상 |
| Windows | Windows 11 권장. Windows 10은 1809 이상에서 동작하지만 Windows 11보다 불안정합니다 |
| 메모리 | RAM 4GB 이상, 8GB 권장 |
| Git | 선택. 2.23 이상이면 PR 관련 기능을 씁니다 |
- 계정: ChatGPT Plus, Pro, Business, Edu, Enterprise 요금제로 씁니다. OpenAI API 키로도 쓸 수 있습니다. API 키를 쓰면 요금제 사용량이 아니라 API 요금이 나갑니다.
- 관리자 권한: 필요 없습니다. macOS·Linux에서 명령 앞에
sudo를 붙이지 않습니다. 설치 스크립트는 내 홈 폴더 안에 설치합니다. - Windows의 winget: 공식 문서는 winget(Windows 패키지 관리자)이 있는 환경을 가정합니다. 없으면 Windows를 업데이트합니다.
macOS·Linux에서 설치
- 터미널을 엽니다. macOS는
Cmd + Space를 누르고터미널을 입력한 뒤 Enter를 누릅니다. - 아래 명령을 붙여넣고 Enter를 누릅니다.
- 설치가 끝나면 터미널 창을 닫고 새 창을 엽니다.
- 새 창에서
codex --version을 실행합니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh
설치 스크립트는 codex를 ~/.local/bin에 넣습니다. 그 폴더가 PATH에 없으면 셸 설정 파일에 PATH 한 줄을 추가합니다. macOS의 zsh는 ~/.zprofile, macOS의 bash는 ~/.bash_profile, Linux의 zsh는 ~/.zshrc, Linux의 bash는 ~/.bashrc입니다. PATH는 터미널이 명령어 프로그램을 찾는 폴더 목록입니다.
설치가 끝나면 스크립트가 지금 창에서 바로 실행하는 명령을 보여 줍니다.
==> Current terminal: export PATH="$HOME/.local/bin:$PATH" && codex
==> Future terminals: open a new terminal and run: codex
새 창을 열면 PATH가 적용되므로 codex만 입력하면 됩니다.
Windows에서 설치
Windows는 PowerShell에서 설치합니다. 관리자 권한으로 열 필요는 없습니다.
- 키보드의 Windows 키를 누르고
powershell을 입력합니다. - “Windows PowerShell”을 클릭합니다.
- 아래 명령을 복사해 붙여넣고 Enter를 누릅니다. 마우스 오른쪽 버튼을 한 번 클릭하면 붙여넣어집니다.
Codex CLI ... installed successfully.가 나오면 PowerShell 창을 닫고 새로 엽니다.- 새 창에서
codex --version을 실행합니다.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
irm은 설치 스크립트를 내려받고, iex는 그 스크립트를 실행합니다. -ExecutionPolicy ByPass는 이 한 번의 실행에만 스크립트 실행 제한을 풉니다. 컴퓨터 설정은 바뀌지 않습니다.
설치 스크립트는 codex.exe를 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin에 넣고, 이 폴더를 사용자 PATH에 추가합니다. 이미 열려 있던 PowerShell 창은 바뀐 PATH를 모릅니다. 그래서 새 창이 필요합니다.
npm으로 설치: npm install -g @openai/codex
Node.js를 이미 쓰고 있으면 npm으로 설치해도 됩니다.
npm install -g @openai/codex
2026-11-18에 macOS에서 실행한 결과입니다.
added 2 packages in 5s
$ codex --version
codex-cli 0.169.1
EACCES 권한 오류가 나도 sudo npm install로 다시 실행하지 않습니다. npm 전역 폴더가 시스템 폴더라는 뜻입니다. 이때는 위의 설치 스크립트를 씁니다. 설치 스크립트는 npm이 필요 없고 홈 폴더 안에 설치합니다.
처음 실행하고 로그인하기
- 작업할 폴더로 이동합니다. 예:
cd ~/projects/my-app codex를 실행합니다.- 로그인 방법에서 Sign in with ChatGPT를 고릅니다.
- 브라우저가 열리면 ChatGPT 계정으로 로그인합니다.
- 터미널로 돌아오면 Codex 입력창이 보입니다.
이 프로젝트를 설명해 줘처럼 첫 요청을 입력합니다.
로그인만 따로 할 때는 codex login을 씁니다. 지금 어떤 방법으로 로그인했는지는 codex login status로 봅니다. 로그인하지 않았으면 Not logged in이 나옵니다. 로그아웃은 codex logout입니다.
API 키로 로그인할 때
printenv OPENAI_API_KEY | codex login --with-api-key
API 키를 명령어에 직접 쓰지 않고 환경 변수에서 읽어 넘깁니다. 터미널 기록에 키가 남지 않습니다.
자주 나는 설치 오류
command not found: codex / codex 용어가 인식되지 않을 때
터미널이 codex 파일을 찾지 못한다는 뜻입니다. 대부분 설치 직후 같은 창에서 실행해서 생깁니다.
- 터미널 창을 닫고 새 창을 엽니다.
- 그래도 안 되면 설치 위치가 PATH에 있는지 봅니다.
# macOS·Linux
echo $PATH | tr ':' '\n' | grep .local/bin
# Windows PowerShell
$env:Path -split ';' | Select-String 'OpenAI\\Codex'
아무것도 나오지 않으면 설치 스크립트를 한 번 더 실행합니다. 스크립트가 PATH를 다시 추가합니다.
로그인 브라우저가 열리지 않거나, 로그인 후 터미널이 멈출 때
Codex는 로그인 결과를 내 컴퓨터의 localhost:1455로 받습니다. 원격 서버, SSH 접속, 회사 방화벽에서는 이 연결이 막힙니다. 이때는 기기 코드 로그인을 씁니다.
codex login --device-auth
터미널에 나온 주소를 아무 기기의 브라우저에서 열고, 로그인한 뒤 일회용 코드를 입력합니다. 먼저 ChatGPT 보안 설정에서 기기 코드 로그인을 켜야 합니다. 회사 워크스페이스는 관리자가 켭니다. 이 기능은 2026-11-18 기준 베타입니다.
회사망에서 인증서 오류가 날 때
회사 프록시가 자체 인증서를 쓰면 로그인과 요청이 실패합니다. 회사 루트 인증서 파일 경로를 지정하고 다시 로그인합니다.
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
원인을 모를 때: codex doctor
codex doctor
codex doctor는 설치, 설정, 로그인, 네트워크 상태를 한 번에 점검합니다. 결과에서 ⚠ 표시가 붙은 줄을 봅니다. 예를 들어 websocket 경고는 프록시·VPN·방화벽이 연결을 막고 있다는 뜻입니다. 답을 찾지 못하면 이 출력을 Codex나 Claude에게 그대로 붙여넣고 물어봅니다.
업데이트와 설치가 두 개일 때
codex update
codex update는 Codex를 최신 버전으로 올립니다. 설치 스크립트로 설치했다면 같은 설치 명령을 다시 실행해도 됩니다.
설치 방법을 바꾸면 codex가 두 개 생길 수 있습니다. 2026-11-18에 제 맥에서 codex doctor를 실행하니 PATH에 codex가 두 개 잡혀 있었습니다. 하나는 0.166.0, 다른 하나는 Homebrew Node.js에 npm으로 깔린 0.154.0이었습니다. 터미널은 PATH에서 먼저 찾은 쪽을 실행합니다. 그래서 업데이트한 버전과 실행되는 버전이 다를 수 있습니다.
which -a codex # macOS·Linux: 설치된 codex 전부 보기
where.exe codex # Windows
두 줄 이상 나오면 쓰지 않는 쪽을 지웁니다. npm으로 설치한 것은 npm uninstall -g @openai/codex, Homebrew는 brew uninstall --cask codex로 지웁니다. 설치 스크립트는 npm이나 Homebrew로 설치한 Codex를 찾으면 지울지 먼저 묻습니다.
설치한 다음에 볼 것
- 프로젝트 폴더에서
/init을 입력하면 Codex가 작업 규칙 파일AGENTS.md를 만듭니다. /permissions로 Codex가 묻지 않고 할 수 있는 일(파일 수정, 명령 실행)의 범위를 정합니다./model로 모델과 추론 강도를 바꿉니다.- Claude Code도 같이 쓰려면 Claude Code CLI 설치 방법을 봅니다. Claude 사용 한도에 걸렸을 때 Codex로 이어서 일하는 방법은 클로드 코드 사용량 한도 글에 있습니다.
이 문서의 용어
- Codex
OpenAI의 코딩 에이전트로, 터미널·IDE·클라우드에서 코드를 읽고 고치고 명령을 실행한다.
- Command-line interface
마우스 클릭 대신 텍스트 명령어를 한 줄씩 입력해 소프트웨어를 조작하는 방식.
- Git
파일의 변경 이력을 스냅샷으로 기록하고, 이전 상태로 되돌리거나 여러 사람의 작업을 합치게 해 주는 버전 관리 시스템.
- Claude Code
Anthropic이 만든 에이전트 코딩 도구로, 코드를 읽고 파일을 고치고 명령을 직접 실행한다.
함께 읽기
뉴스레터 구독
AI·그로스·CRM 실전 사례를 메일로 보내드립니다. 과장된 트렌드보다 바로 실행할 수 있는 방법을 다룹니다.