OpenAI Codex CLI 설치 방법: Mac·Windows 첫 실행과 로그인

Codex CLI는 터미널에서 현재 프로젝트를 읽고 파일 수정과 명령 실행을 돕는 OpenAI 코딩 에이전트다. Mac·Linux는 공식 설치 스크립트, Windows는 PowerShell 설치 스크립트로 바로 설치할 수 있다. npm과 Homebrew도 지원한다. 설치 후 프로젝트 폴더로 이동해 codex를 실행하고, 개인 사용자는 브라우저에서 ChatGPT로 로그인하는 흐름이 가장 짧다. API 키 로그인은 ChatGPT 구독 사용이 아니라 OpenAI Platform의 사용량 기반 과금이라는 점을 구분해야 한다.

Mac과 Linux에 설치하기

OpenAI 공식 저장소의 현재 빠른 설치 명령은 다음과 같다.

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

설치가 끝나면 새 터미널을 열고 확인한다.

codex --version
codex

Homebrew를 이미 쓰고 있다면 cask 설치도 가능하다.

brew install --cask codex

Node.js와 npm 환경을 관리하고 있다면 npm 전역 설치를 선택할 수 있다.

npm install -g @openai/codex

세 방법을 동시에 쓸 필요는 없다. 설치 방식이 여러 개 섞이면 업데이트 후 which codex가 예전 실행 파일을 가리키는 일이 생길 수 있다. 이미 설치했다면 먼저 which codex로 실제 실행 경로를 확인하고 한 가지 방식으로 관리하는 편이 낫다.

Windows PowerShell에 설치하기

Windows 공식 명령은 PowerShell에서 실행한다.

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

명령 프롬프트가 PS C:\...>로 시작하는지 확인하면 PowerShell인지 알 수 있다. 설치 후 창을 닫고 새 PowerShell을 열어 확인한다.

codex --version
codex

npm을 쓰는 Windows 사용자라면 다음 명령도 공식 지원 경로다.

npm install -g @openai/codex

현재 공식 저장소는 Windows용 설치 스크립트를 별도로 제공한다. 예전 글처럼 무조건 WSL부터 설치해야 하는 것은 아니다. 다만 프로젝트가 이미 WSL의 Linux 파일 시스템 안에 있고 빌드 도구도 Linux에 설치되어 있다면, WSL 터미널 안에서 Mac·Linux용 설치 명령을 실행해 그 환경 안에 Codex를 설치하는 편이 자연스럽다. Windows에 설치한 codex와 WSL에 설치한 codex는 같은 실행 파일이 아니다. 프로젝트와 개발 도구가 있는 쪽에 설치해야 경로가 덜 꼬인다.

ChatGPT 로그인과 API 키 로그인의 차이

codex를 처음 실행하면 로그인 방식을 선택할 수 있다. 공식 문서는 두 가지 로컬 로그인 방식을 안내한다.

• ChatGPT로 로그인: 브라우저가 열리고 ChatGPT 계정으로 인증한다. 해당 구독과 워크스페이스 권한을 따른다.
• API 키로 로그인: OpenAI Platform API 키를 사용한다. 사용량은 Platform 계정의 표준 API 요금으로 청구된다.

단순히 개인 컴퓨터에서 대화형으로 시작한다면 codex login을 실행하고 브라우저 로그인 흐름을 완료하면 된다. 현재 상태는 다음 명령으로 확인할 수 있다.

codex login status

공용 PC나 계정을 바꿔야 할 때는 저장된 인증을 제거한다.

codex logout

API 키는 코드 저장소나 셸 기록에 직접 붙여 넣고 커밋하면 안 된다. Codex의 인증 정보는 기본적으로 ~/.codex 아래 파일 또는 운영체제 자격 증명 저장소에 캐시될 수 있다. 공식 문서는 파일 기반 ~/.codex/auth.json을 비밀번호처럼 취급하고 이슈나 채팅에 공유하지 말라고 안내한다.

첫 실행은 프로젝트 폴더에서 한다

Codex는 현재 작업 디렉터리를 기준으로 프로젝트를 이해한다. 홈 폴더에서 무작정 실행하기보다 작업할 저장소로 이동한 뒤 시작한다.

cd ~/projects/my-app
git status
codex

Windows PowerShell 예시는 다음과 같다.

cd C:\Users\me\projects\my-app
git status
codex

첫 요청은 범위를 작게 잡는 편이 좋다. 예를 들어 ‘프로젝트 전체를 개선해 줘’보다 다음처럼 확인 가능한 작업을 준다.

README와 package.json을 읽고 로컬 실행 명령을 설명해 줘. 아직 파일은 수정하지 마.

그다음 변경 작업을 맡긴다.

src/auth/login.ts의 실패한 테스트 원인을 찾아 최소 변경으로 수정하고 해당 테스트만 실행해 줘.

이렇게 하면 Codex가 어느 파일과 명령을 다루는지 확인하기 쉽다. 처음부터 저장소 밖의 디렉터리나 광범위한 시스템 권한을 열 이유가 없다. 공식 CLI 문서도 로컬 작업에는 workspace-write 샌드박스와 필요할 때 승인받는 조합을 안내한다.

codex --sandbox workspace-write --ask-for-approval on-request

--dangerously-bypass-approvals-and-sandbox는 이름 그대로 승인과 샌드박스를 우회한다. 일반 개발 폴더에서 설치 확인용으로 쓸 옵션이 아니다.

codex: command not found가 나오면

설치 직후 명령을 찾지 못하면 먼저 새 터미널을 연다. 그래도 안 되면 설치 방법에 따라 실행 파일 위치를 확인한다.

Mac·Linux:

command -v codex
which codex
echo $PATH

Windows PowerShell:

Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'

npm으로 설치했다면 Node와 npm 자체가 보이는지도 확인한다.

node --version
npm --version
npm prefix -g

npm install -g는 성공했는데 codex만 없다면 npm 전역 실행 경로가 PATH에 없을 가능성이 있다. 반대로 공식 설치 스크립트와 npm 설치를 둘 다 했다면 오래된 쪽이 먼저 잡힐 수 있다. Mac·Linux에서는 which -a codex, Windows에서는 Get-Command codex -All로 중복 경로를 확인한다.

설치나 인증 상태를 한 번에 진단할 때는 공식 진단 명령을 쓸 수 있다.

codex doctor

공식 명령 참조에 따르면 이 보고서는 설치, 설정, 인증, 런타임, Git, 터미널 상태 등을 확인한다. 오류가 난 화면만 캡처하기보다 codex --version, 실행 경로, codex login status, codex doctor 결과를 함께 보면 원인이 빨리 좁혀진다. 단, 진단 결과를 공개 이슈에 올리기 전에는 사용자 경로와 저장소 이름 같은 정보를 확인해야 한다.

설치가 끝났는지 확인하는 기준

설치 성공은 codex 화면이 한 번 뜨는 것으로 끝나지 않는다. 다음 네 단계가 모두 되어야 첫 사용 준비가 끝난다.

1. codex --version이 버전을 출력한다.
2. codex login status가 인증 상태를 정상으로 표시한다.
3. 실제 프로젝트 폴더에서 codex가 저장소 파일을 읽는다.
4. 읽기 전용 요청을 수행한 뒤, 작은 수정 한 건과 관련 테스트 실행을 승인 흐름 안에서 완료한다.

업데이트는 설치 방식에 맞춰 관리한다. npm으로 설치했다면 npm, Homebrew라면 Homebrew, 공식 설치 스크립트라면 Codex의 업데이트 흐름을 사용한다. 여러 설치 방법을 섞지 않는 것이 command not found와 구버전 실행을 피하는 가장 간단한 방법이다.

출처: OpenAI Codex GitHub README, Codex Authentication, Codex CLI command reference