Codex CLI 설치 방법: macOS·Windows·Linux OpenAI 코딩 에이전트 시작하기

요약

Codex CLI는 OpenAI의 코딩 에이전트를 터미널에서 실행하는 도구입니다. 예전에는 npm install -g @openai/codex만 설명해도 충분했지만, 지금은 공식 설치 스크립트, Homebrew cask, npm, GitHub Release 바이너리까지 선택지가 늘었습니다. 이 글에서는 2026년 6월 기준 Codex CLI 설치 방법과 로그인 방식, 그리고 실제로 자주 막히는 설치/인증/터미널 문제를 함께 정리합니다.

배경

Codex CLI를 설치하려고 검색하면 아직도 오래된 글이 많이 나옵니다. 특히 Node.js 22 이상 필요, codex --login 실행, brew install codex처럼 지금 기준으로는 정확하지 않거나 환경에 따라 다르게 동작할 수 있는 내용이 섞여 있습니다.

현재 공식 README 기준으로 Codex CLI는 macOS, Linux, Windows에서 설치할 수 있고, 설치 방식도 여러 가지입니다. 가장 단순한 방법은 공식 설치 스크립트를 쓰는 것이고, npm을 이미 쓰는 개발자라면 @openai/codex 패키지로 설치해도 됩니다.

중요한 점은 설치 명령보다 어떤 인증 방식으로 쓸지, 내 터미널에서 codex 명령이 실제로 잡히는지, 회사/학교/프록시 환경에서 네트워크가 막히지 않는지입니다. 실제로 막히는 부분은 대부분 여기서 나옵니다.

설치 전 확인할 것

먼저 현재 환경을 확인합니다.

node -v
npm -v
which node
which npm
uname -m

npm으로 설치할 경우 npm 패키지의 engines 기준은 현재 node >=16입니다. 다만 실제 사용에서는 최신 LTS 계열 Node.js를 쓰는 편이 안전합니다. 이미 nvm, fnm, volta 같은 Node 버전 관리자를 쓴다면 전역 npm 설치 위치가 어디인지도 같이 봐야 합니다.

npm config get prefix
which codex

Windows에서는 PowerShell 또는 Windows Terminal을 기준으로 설치하고, 개발 작업은 WSL2에서 할지 Windows 네이티브에서 할지도 미리 정하는 것이 좋습니다. 둘은 PATH와 인증 파일 위치가 달라질 수 있습니다.

Codex CLI 설치 방법

방법 1. 공식 설치 스크립트로 설치

macOS 또는 Linux에서는 공식 README가 아래 명령을 안내합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell에서는 다음 명령을 사용합니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

처음 설치하는 사용자라면 이 방식이 가장 간단합니다. 단, 회사 보안 정책상 원격 스크립트 실행이 제한된 환경에서는 스크립트 내용을 먼저 확인하거나 npm/Homebrew/GitHub Release 방식이 더 적절할 수 있습니다.

방법 2. npm으로 설치

Node.js와 npm을 이미 사용하고 있다면 npm 전역 설치도 가능합니다.

npm install -g @openai/codex

설치 후 확인합니다.

codex --version
which codex

2026년 6월 16일 확인 기준 npm의 @openai/codex 최신 버전은 0.140.0입니다. npm 전역 설치는 간단하지만, nvm을 쓰는 환경에서는 Node 버전을 바꾸면 전역 패키지가 다른 위치에 설치될 수 있습니다. 이 경우 which codex 결과가 예상과 다르면 PATH를 먼저 확인해야 합니다.

방법 3. Homebrew로 설치

macOS에서는 Homebrew cask 방식도 제공합니다.

brew install --cask codex

기존 글에서 자주 보이는 brew install codex와 다를 수 있으니 주의합니다. 공식 README는 --cask 설치를 안내하고 있습니다.

방법 4. GitHub Release 바이너리로 설치

패키지 매니저를 쓰기 어렵다면 GitHub Release에서 플랫폼에 맞는 바이너리를 받을 수 있습니다.

Apple Silicon Mac: codex-aarch64-apple-darwin.tar.gz
Intel Mac: codex-x86_64-apple-darwin.tar.gz
Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

압축을 푼 뒤 실행 파일 이름을 codex로 바꾸고 PATH에 잡히는 위치로 옮기면 됩니다.

chmod +x codex
sudo mv codex /usr/local/bin/codex
codex --version

로그인과 인증 방식

Codex CLI를 처음 실행하면 보통 로그인 흐름이 시작됩니다.

codex

공식 README 기준으로는 ChatGPT 계정으로 로그인하는 방식을 권장합니다. Plus, Pro, Business, Edu, Enterprise 플랜에서 Codex 사용 권한이 연결될 수 있기 때문입니다.

API Key로도 사용할 수 있지만, 이 경우는 별도 설정이 필요합니다. 단순히 예전 글처럼 OPENAI_API_KEY만 export하면 모든 인증 문제가 끝난다고 보면 안 됩니다. 조직 정책, 계정 권한, 모델 접근 권한, Codex 설정 방식에 따라 달라질 수 있습니다.

환경 변수를 사용할 때는 실제 키를 글이나 설정 파일에 직접 남기지 않습니다.

export OPENAI_API_KEY="****"

PowerShell에서는 다음처럼 설정할 수 있습니다.

$env:OPENAI_API_KEY = "****"

기본 사용법

가장 기본은 대화형 실행입니다.

codex

프로젝트 폴더에서 실행하면 Codex가 현재 디렉터리의 파일을 기준으로 작업합니다.

cd my-project
codex

설치와 인증이 끝났다면 먼저 간단한 요청으로 동작을 확인합니다.

이 프로젝트 구조를 요약해줘.

바로 파일을 수정하게 하기보다는 처음에는 읽기 중심 요청으로 시작하는 편이 안전합니다.

실패 사례와 해결

사례 1. `codex: command not found`가 나오는 경우

설치는 끝났는데 터미널에서 이런 메시지가 나올 수 있습니다.

codex: command not found

먼저 실행 파일이 어디에 설치됐는지 확인합니다.

npm config get prefix
which codex

npm 전역 설치를 했는데 which codex가 비어 있다면 npm global bin 경로가 PATH에 없을 가능성이 큽니다.

npm bin -g

사용 중인 셸도 확인합니다.

echo $SHELL

zsh를 쓴다면 ~/.zshrc, bash를 쓴다면 ~/.bashrc 또는 ~/.bash_profile 쪽 PATH 설정을 봅니다. nvm을 쓰는 환경에서는 Node 버전을 바꾼 뒤 전역 패키지가 사라진 것처럼 보일 수 있으므로, 현재 Node 버전에서 다시 설치하는 것도 방법입니다.

npm install -g @openai/codex

사례 2. Homebrew로 설치했는데 명령이 다르게 안내되는 경우

일부 글에서는 아래처럼 안내합니다.

brew install codex

하지만 공식 README 기준 설치 명령은 다음입니다.

brew install --cask codex

Homebrew formula와 cask는 설치 대상과 관리 방식이 다릅니다. 설치가 실패하면 먼저 공식 README의 최신 명령을 확인하고, 이미 잘못 설치한 패키지가 있다면 정리한 뒤 다시 설치합니다.

brew list | grep -i codex
brew uninstall codex
brew install --cask codex

환경에 따라 brew uninstall codex가 해당 항목을 찾지 못할 수 있습니다. 그 경우에는 실제 설치된 항목 이름을 brew list --cask로 확인합니다.

brew list --cask | grep -i codex

사례 3. 로그인은 했는데 권한이나 플랜 문제로 사용할 수 없는 경우

Codex CLI는 단순 설치 도구가 아니라 계정 권한과 연결됩니다. ChatGPT로 로그인했는데도 사용이 안 된다면 먼저 아래를 확인합니다.

ChatGPT 계정이 맞는지
개인 계정과 회사/학교 워크스페이스가 섞이지 않았는지
Codex 사용 권한이 있는 플랜인지
API Key 방식이라면 프로젝트/조직/결제 설정이 맞는지

이 경우 무작정 재설치하기보다 로그아웃/재로그인, 계정 전환, 권한 확인이 먼저입니다. 같은 컴퓨터에서 여러 OpenAI 계정을 쓰는 경우 특히 자주 헷갈립니다.

사례 4. 회사 네트워크에서 WebSocket 재연결 메시지가 반복되는 경우

GitHub 이슈에는 Codex CLI가 WebSocket 연결을 시도하다가 타임아웃 또는 정책 종료 후 HTTPS로 fallback되는 사례가 보고되어 있습니다. 사용자는 Reconnecting..., Request timed out 같은 메시지를 볼 수 있습니다.

먼저 같은 명령을 다른 네트워크에서 실행해 봅니다.

codex

회사 VPN, 프록시, 보안 게이트웨이, SSL inspection이 있는 환경에서는 WebSocket이 막힐 수 있습니다. 공식적으로 모든 환경에서 동일한 해결책이 있는 문제는 아니므로, 이 경우에는 다음 순서로 확인하는 편이 안전합니다.

Codex CLI를 최신 버전으로 업데이트
회사 VPN을 끈 상태 또는 다른 네트워크에서 재현 여부 확인
프록시/방화벽에서 chatgpt.com 및 OpenAI 관련 연결이 차단되는지 확인
문제가 계속되면 GitHub issue에서 같은 버전의 사례 확인

npm 설치라면 업데이트는 다음처럼 합니다.

npm install -g @openai/codex@latest
codex --version

사례 5. Codex 안에서 환경 변수가 안 보이는 경우

Codex가 명령을 실행할 때 사용자의 터미널 환경을 그대로 모두 가져오지 않는다고 느끼는 사례가 있습니다. 예를 들어 터미널에서는 보이는 SENTRY_API_TOKEN, OPENAI_API_KEY 같은 값이 Codex 실행 환경에서는 보이지 않는 식입니다.

먼저 일반 터미널에서 확인합니다.

printenv OPENAI_API_KEY

그다음 Codex 안에서 실행되는 명령이 같은 환경을 보는지 확인합니다. 민감정보는 그대로 출력하지 말고 존재 여부만 확인합니다.

printenv OPENAI_API_KEY >/dev/null && echo "set" || echo "missing"

해결은 환경마다 다릅니다. 가장 안전한 방향은 프로젝트에 필요한 환경 변수를 명시적으로 설정하고, 비밀값은 .env를 Git에 올리지 않는 것입니다. Codex 설정 파일이나 프로젝트 문서에 실제 키를 적는 것은 피해야 합니다.

사례 6. macOS에서 보안 정책 때문에 보조 도구가 막히는 경우

GitHub issue에는 macOS에서 rg 같은 보조 실행 파일이 보안 정책에 의해 차단되는 사례도 보고되어 있습니다. 이런 경우 Codex 자체 설치 문제처럼 보이지만 실제로는 macOS Gatekeeper, quarantine 속성, 보안 설정이 원인일 수 있습니다.

먼저 Codex 버전과 진단 정보를 확인합니다.

codex --version
codex doctor

codex doctor가 제공되는 버전이라면 진단 결과를 보고 어떤 실행 파일이 막혔는지 확인합니다. 무작정 권한을 넓히기보다, 최신 버전 업데이트 후에도 같은 문제가 재현되는지 먼저 확인하는 편이 좋습니다.

npm install -g @openai/codex@latest

모범 사례

Codex CLI를 처음 쓸 때는 자동 수정부터 맡기기보다 읽기와 설명 중심으로 시작하는 것이 좋습니다.

이 저장소의 구조를 설명해줘.
테스트 실행 방법을 찾아줘.
이 에러 로그의 원인을 후보별로 정리해줘.

파일 수정을 요청할 때는 Git 상태를 먼저 깨끗하게 만들어 둡니다.

git status

수정 후에는 Codex의 설명만 믿지 말고 직접 테스트합니다.

npm test
npm run build

회사 코드나 민감한 프로젝트에서 사용할 때는 보안 정책도 확인해야 합니다. API Key, 고객 데이터, 운영 비밀번호, 사내 토큰을 Codex 프롬프트나 설정 파일에 직접 붙여 넣는 방식은 피하는 것이 좋습니다.

흔한 실수

Node 버전만 보고 설치 문제를 판단하는 것

현재 npm 패키지 기준은 node >=16입니다. 문제는 Node 버전보다 npm 전역 설치 경로, PATH, nvm 전환으로 인한 전역 패키지 위치 차이에서 더 자주 발생합니다.

오래된 설치 명령을 그대로 따라 하는 것

Codex CLI는 변화가 빠른 도구입니다. 블로그 글에 있는 설치 명령보다 공식 README와 GitHub Release의 최신 정보를 먼저 봐야 합니다.

API Key 방식과 ChatGPT 로그인 방식을 섞어서 이해하는 것

공식 README는 ChatGPT 계정 로그인을 권장합니다. API Key 방식도 가능하지만, 별도 설정과 권한 확인이 필요할 수 있습니다. 인증 문제를 설치 문제로 착각하면 시간을 많이 씁니다.

Codex가 수정한 결과를 검증하지 않는 것

Codex는 코드를 수정할 수 있지만, 수정 결과가 항상 프로젝트 의도와 맞는 것은 아닙니다. 테스트, 빌드, diff 확인은 사용자가 반드시 해야 합니다.

결론

Codex CLI 설치 자체는 어렵지 않습니다. macOS와 Linux는 공식 설치 스크립트나 npm, Homebrew cask를 사용할 수 있고, Windows는 PowerShell 설치 스크립트를 사용할 수 있습니다.

하지만 실제로 시간을 잡아먹는 부분은 설치 명령이 아니라 PATH, 인증, 계정 권한, 네트워크, 터미널 환경 차이입니다. 그래서 Codex CLI 글은 단순 설치 순서보다 command not found, 로그인 권한 문제, WebSocket/프록시 문제, 환경 변수 문제 같은 실패 사례를 함께 보는 편이 훨씬 실용적입니다.

처음 설치한다면 아래 순서로 진행하면 됩니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex

npm 환경이 이미 정리되어 있다면 다음 방식도 충분합니다.

npm install -g @openai/codex@latest
codex --version
codex

참고 자료

OpenAI Codex GitHub README: https://github.com/openai/codex
Codex CLI npm 패키지: https://www.npmjs.com/package/@openai/codex
Codex 최신 GitHub Release: https://github.com/openai/codex/releases/latest
OpenAI Codex 인증 문서: https://developers.openai.com/codex/auth
OpenAI Codex CLI 기능 문서: https://developers.openai.com/codex/cli/features
OpenAI Codex 설정 문서: https://developers.openai.com/codex/config-basic
GitHub issue: WebSocket timeout/fallback 사례: https://github.com/openai/codex/issues/28503
GitHub issue: macOS에서 rg 차단 사례: https://github.com/openai/codex/issues/28190
GitHub issue: 환경 변수 상속 관련 사례: https://github.com/openai/codex/issues/3064

Codex CLI 설치 방법: macOS·Windows·Linux에서 OpenAI 코딩 에이전트 시작하기

요약

목차

배경