Codex CLI를 설치하려면 먼저 운영체제와 평소 사용하는 패키지 관리 방식에 맞는 공식 채널을 고르세요. 현재 OpenAI는 macOS/Linux용 독립 실행형(standalone) 설치 스크립트, Windows용 PowerShell 설치 스크립트, npm 패키지, Homebrew cask를 안내합니다. npm은 선택지 중 하나일 뿐, 모든 설치의 공통 전제가 아닙니다.
완료 기준은 세 단계입니다. ① 적합한 채널의 명령을 실행하고, ② 작업할 폴더에서 codex가 실제로 시작되며, ③ ChatGPT 또는 API 키로 로그인한 뒤 codex login status에서 활성 인증 방식을 확인해야 합니다. 명령을 한 번 실행했다는 사실만으로는 사용 준비가 끝나지 않습니다.
“이 문서는 2026년 8월 16일에 확인한 OpenAI Codex CLI 공식 문서와 OpenAI 인증 문서를 기준으로 합니다. 설치 명령과 인증 정책은 바뀔 수 있으므로 실제 실행 전 공식 문서도 함께 확인하세요.
먼저 설치 채널을 고르세요
가장 좋은 설치 방법은 하나로 고정되지 않습니다. 새로 Node.js를 설치할지부터 고민하기보다, 지금 사용하는 환경에 맞는 공식 채널을 선택하는 편이 빠릅니다.
| 현재 환경 | 선택할 수 있는 공식 채널 | 판단 기준 |
|---|---|---|
| macOS 또는 Linux | 독립 실행형 설치 스크립트 | 별도 패키지 관리자 선택 없이 공식 설치 경로를 쓰고 싶을 때 |
| Windows PowerShell | 독립 실행형 설치 스크립트 | Windows용 공식 PowerShell 경로를 쓰고 싶을 때 |
| npm을 이미 사용하는 환경 | npm 패키지 | 기존 npm 기반 전역 도구 관리 흐름에 Codex CLI를 포함하고 싶을 때 |
| Homebrew를 이미 사용하는 환경 | Homebrew cask | 기존 brew 업데이트 흐름으로 관리하고 싶을 때 |
이 표는 ‘어느 채널이 무조건 더 좋다’는 순위가 아닙니다. 예를 들어 npm 경로에는 npm을 실행할 수 있는 환경이 필요하지만, 검토한 공식 자료에서는 npm 경로의 최소 또는 권장 Node.js 버전을 확인할 수 없었습니다. 서드파티 글의 버전 번호를 공통 요구사항처럼 적용하지 마세요. 독립 실행형이나 Homebrew 경로에 Node.js가 반드시 필요하다고 볼 근거도 없습니다.
macOS와 Linux: 독립 실행형 설치
OpenAI가 현재 안내하는 macOS/Linux standalone 명령은 다음과 같습니다.
bashcurl -fsSL https://chatgpt.com/codex/install.sh | sh
업데이트할 때도 공식 빠른 시작 문서는 같은 명령을 다시 실행하도록 안내합니다.
이 명령이 공식 문서에 실려 있다는 사실과 모든 배포판·네트워크에서 성공한다는 보장은 서로 다릅니다. 회사 네트워크, 관리형 장치, 셸 정책 때문에 실패한다면 임의의 우회 명령을 추가하기 전에 설치 출력과 최신 공식 문서를 확인하세요.
Windows: PowerShell 독립 실행형 설치
Windows용 현재 공식 명령은 다음과 같습니다.
powershellpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
공식 빠른 시작 문서는 업데이트에도 같은 명령을 다시 사용합니다. 다만 이 명령이 모든 회사 관리 장치의 실행 정책, 모든 아키텍처 또는 모든 네트워크 조건에서 성공한다는 뜻은 아닙니다. PowerShell 정책이나 보안 도구가 실행을 막는 환경이라면 정책을 임의로 완화하기보다 조직의 관리자와 확인해야 합니다.
Windows에서 Codex CLI를 설치하기 위해 WSL이나 npm을 반드시 먼저 준비해야 한다고 단정할 필요도 없습니다. 현재 공식 문서에는 Windows용 standalone 경로가 별도로 있습니다. WSL은 자신의 개발 환경이 이미 WSL 중심일 때 검토할 수 있는 별도 선택이지, 여기서 입증된 공통 필수 단계는 아닙니다.
npm으로 설치
npm을 이미 사용하며 전역 CLI 도구를 npm으로 관리한다면 다음 공식 패키지를 설치할 수 있습니다. 업데이트할 때도 같은 명령을 다시 사용합니다.
bashnpm install -g @openai/codex
패키지 이름은 @openai/codex입니다. 비슷한 이름의 비공식 패키지를 추측해서 설치하지 마세요. 또한 현재 확인한 공식 Codex CLI 빠른 시작과 인증 문서만으로는 npm 경로의 최소 Node.js 버전을 확정할 수 없습니다. 설치 전 자신의 npm 환경과 최신 공식 안내를 확인하되, 확인되지 않은 버전 번호를 모든 독자에게 적용하지 않는 것이 안전합니다.
Homebrew로 설치
Homebrew를 이미 사용한다면 현재 공식 cask 명령은 다음과 같습니다.
bashbrew install --cask codex
설치 후 Homebrew 채널로 업데이트할 때는 다음 명령을 사용합니다.
bashbrew upgrade --cask codex
여기서 중요한 부분은 --cask입니다. 과거 글이나 서드파티 예시에 나온 다른 문법보다 현재 OpenAI 공식 문서의 명령을 우선하세요. Homebrew가 없는 독자가 이 경로를 사용하기 위해 반드시 새로 Homebrew부터 설치해야 하는 것은 아닙니다. standalone을 포함한 다른 공식 채널과 비교해 자신의 관리 방식에 맞는 쪽을 선택하면 됩니다.
첫 실행으로 설치 상태를 확인하세요
선택한 채널의 설치가 끝났다면 실제 작업을 시작하기 전에 테스트할 폴더를 정하세요. OpenAI의 빠른 시작은 프로젝트 디렉터리를 연 뒤 다음 명령으로 Codex CLI를 실행하도록 안내합니다.
bashcodex
정상적으로 첫 실행 화면이 열리면 로그인 방법을 선택할 수 있습니다. 이 단계는 단순히 설치 파일을 내려받았다는 것보다 강한 확인 신호입니다. 반대로 셸이 codex 명령을 찾지 못한다면 아직 ‘설치 완료’라고 판단하지 마세요.
command not found가 나타났을 때 모든 환경에 통하는 PATH 수정 명령을 무작정 붙여 넣는 것은 좋지 않습니다. 사용한 채널부터 다시 확인하세요.
- 공식 문서에 나온 채널과 명령을 그대로 사용했는지 확인합니다.
- npm 경로라면 설치한 패키지가 정확히
@openai/codex인지 확인합니다. - Homebrew 경로라면 현재 공식 문법에
--cask가 포함되는지 확인합니다. - 설치 출력에 실패가 있었는지 확인하고, 운영체제·셸·관리 정책에 맞는 공식 문서 범위를 벗어나 임의의 PATH 변경을 적용하지 않습니다.
검토한 근거만으로는 모든 운영체제의 PATH 복구 절차를 하나의 정답으로 제시할 수 없습니다. 특히 관리형 장치에서는 시스템 설정을 바꾸기 전에 관리자 확인이 필요할 수 있습니다.
ChatGPT 로그인과 API 키 로그인은 같은 선택이 아닙니다
Codex CLI는 로컬 작업에서 ChatGPT 로그인과 API 키 로그인을 지원합니다. 두 방식은 단순히 로그인 화면만 다른 것이 아니라 적용되는 접근 권한, 과금 방식, 워크스페이스 통제 및 데이터 처리 정책의 경계가 다릅니다.
ChatGPT로 로그인
브라우저 기반 ChatGPT 로그인 흐름을 시작하려면 다음 명령을 사용할 수 있습니다.
bashcodex login
또는 codex를 처음 실행한 화면에서 Sign in with ChatGPT를 선택할 수 있습니다. 다만 로그인 선택지가 보인다고 해서 특정 구독 플랜, 조직 워크스페이스 또는 지역에서의 사용 자격이 자동으로 보장되는 것은 아닙니다. 실제 접근 가능 여부는 자신의 계정과 워크스페이스 정책에서 확인하세요.
API 키로 로그인
OpenAI 인증 문서는 환경 변수에 저장한 API 키를 표준 입력으로 전달하는 다음 흐름을 안내합니다.
bashprintenv OPENAI_API_KEY | codex login --with-api-key
이 예시는 printenv를 사용할 수 있는 셸을 전제로 합니다. 모든 Windows 셸에서 그대로 동작한다고 확대 해석하지 마세요. API 키 방식은 API 사용량 기반 접근과 연결되며, ChatGPT 구독 로그인과 동일한 과금 경계로 간주하면 안 됩니다.
API 키를 명령 인자, 공개 프롬프트, 스크린샷, 셸 기록 또는 신뢰할 수 없는 환경에 그대로 노출하지 마세요. 이 문서의 예시에도 실제 키 값을 직접 붙여 넣지 않습니다.
활성 인증 방식을 확인하세요
로그인 흐름을 마친 뒤에는 추측하지 말고 상태 명령으로 현재 방식을 확인하세요.
bashcodex login status
여기서 활성 인증 방식을 확인했다면 다음 세 단계를 구분할 수 있습니다.
- 설치 명령 실행: 설치 프로그램이나 패키지 관리 명령을 실행한 상태
- CLI 실행 확인: 작업 폴더에서
codex명령이 실제로 시작되는 상태 - 인증 상태 확인:
codex login status로 현재 로그인 방식을 확인한 상태
계정을 바꾸거나 로컬 자격 증명을 지우려면 공식 문서에 나온 로그아웃 명령을 사용합니다.
bashcodex logout
자격 증명 캐시의 내부 파일을 직접 열거나 내용을 복사해 확인할 필요는 없습니다. 상태 확인에는 공식 CLI 명령을 사용하고, 비밀 정보는 출력·공유하지 않는 것이 원칙입니다.
실제 저장소에서 실행하기 전 중지선
설치와 로그인 확인이 끝났더라도 곧바로 중요한 업무 저장소에서 넓은 권한으로 실행할 필요는 없습니다. 먼저 영향이 없는 테스트 폴더에서 다음 상태를 확인하세요.
- 선택한 설치 채널과 실행한 명령을 알고 있다.
codex가 실제로 시작된다.codex login status로 활성 인증 방식을 확인했다.- ChatGPT 접근과 API 사용량 기반 접근 중 무엇을 쓰는지 알고 있다.
- 현재 계정·워크스페이스의 권한과 조직 정책을 확인했다.
이 조건 중 하나라도 불명확하다면 실제 저장소 권한을 넓히기 전에 멈추는 편이 낫습니다. 특히 플랜 포함 범위, 가격, 할당량, 모델 제공 여부, 지역별 접근성은 변동 가능한 정보입니다. 이 문서는 그런 조건을 보장하지 않으므로 로그인한 계정의 현재 안내와 공식 문서를 다시 확인해야 합니다.
설치 완료 체크리스트
마지막으로 아래 항목을 순서대로 확인하면 ‘명령을 실행했다’와 ‘사용 준비가 됐다’를 혼동하지 않을 수 있습니다.
- macOS/Linux standalone, Windows standalone, npm, Homebrew 중 내 환경에 맞는 공식 채널을 골랐다.
- 최신 OpenAI 공식 문서의 명령을 사용했다.
- 작업할 폴더에서
codex를 실행했다. - ChatGPT 또는 API 키 중 적용되는 인증 방식을 선택했다.
-
codex login status로 활성 인증 방식을 확인했다. - 실제 저장소에서 실행하기 전에 계정·워크스페이스 권한과 과금 경계를 확인했다.
핵심은 설치 명령 하나를 외우는 것이 아닙니다. 자신에게 맞는 공식 채널을 선택하고, CLI가 실제로 시작되며, 어떤 인증 방식이 활성화됐는지 확인하는 것이 Codex CLI 설치의 완료 기준입니다. 세 단계가 끝났을 때에만 영향이 없는 테스트 폴더에서 다음 작업을 시작하세요.
