Codex CLI 설치하고 첫 작업 실행하는 방법
Windows 11, macOS, Linux에 Codex CLI를 설치하는 네 가지 방법과 설치 확인, 공식 로그인과 custom provider를 안전하게 구분하는 방법을 설명합니다.
목차
Codex CLI는 OpenAI가 Rust로 만든 터미널 기반 코딩 에이전트입니다. 로컬에서 실행되며 저장소의 코드를 다루고 격리된 환경에서 작업을 수행합니다. 설치 방법은 독립 실행형 설치 프로그램, npm, Homebrew cask, GitHub Releases 바이너리의 네 가지입니다.
설치한 뒤에는 서로 독립된 두 연결 경로 중 하나를 선택하세요. ChatGPT 또는 OpenAI API Key를 이용한 OpenAI 공식 로그인과, 본인 API Key를 사용하는 custom provider입니다. 어느 쪽이든 같은 codex 명령을 사용하므로 별도 클라이언트를 설치할 필요는 없습니다.
설치 전에 준비할 사항
공식 설치 가이드의 기본 시스템 요구사항은 다음과 같습니다.
- macOS: 12(Monterey) 이상
- Linux: Ubuntu 20.04 이상 또는 Debian 10 이상
- Windows: WSL2를 사용하는 Windows 11. 네이티브 Windows는 별도 문서를 따릅니다.
Node.js는 npm으로 설치할 때만 필요합니다. 독립 실행형 설치 프로그램, Homebrew cask, GitHub Releases 아카이브는 바로 실행할 수 있는 파일을 설치합니다.
공식 ChatGPT 로그인에는 ChatGPT 계정이 필요하고, 공식 API 액세스에는 platform.openai.com의 키가 필요합니다. Custom provider에는 본인의 BetterToken 계정, API Key, 현재 Model ID가 필요합니다. Node.js는 npm으로 Codex를 설치하거나 provider 자동 설정 스크립트를 사용할 때만 필요합니다.
Codex CLI 설치하기
macOS 및 Linux — 독립 실행형 설치 프로그램
가장 간단한 방법이며 Node.js가 필요하지 않습니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh설치가 끝나면 명령을 확인하세요.
codex --version버전 번호가 표시되면 명령을 사용할 수 있습니다.
Codex 설치를 마쳤나요? 현재 가이드에 따라 본인 API Key를 연결하세요. 먼저 최신 Docs의 설정 필드를 확인하고, 아직 본인 키가 없다면 BetterToken 계정을 만드세요.
macOS — Homebrew cask
brew install --cask codexnpm — macOS, Linux, Windows
정상 작동하는 npm이 포함된 Node.js가 필요합니다. 최소 Node.js 버전은 npmjs.com/@openai/codex에 있는 패키지의 engines 필드에서 확인하세요.
npm install -g @openai/codex설치 후 codex 명령을 찾을 수 없다면 전역 npm 디렉터리가 PATH에 없는 것입니다. 올바른 경로를 확인하세요.
npm config get prefix표시된 디렉터리를 셸의 PATH와 비교한 다음 터미널을 다시 시작하세요. 확인하지 않고 /bin을 덧붙이면 안 됩니다. 전역 실행 파일의 구조는 OS와 Node.js 설치 방식에 따라 달라집니다.
Linux — GitHub Releases 바이너리
github.com/openai/codex/releases에서 바로 사용할 수 있는 Linux 아카이브를 받을 수 있습니다.
codex-x86_64-unknown-linux-musl.tar.gz— x86_64용codex-aarch64-unknown-linux-musl.tar.gz— arm64용
아카이브를 풀고 실행 파일 이름을 codex로 바꾼 다음, 쓰기 권한이 있고 PATH에 포함된 디렉터리에 두세요.
Windows
Codex CLI는 Windows에서 네이티브로 실행하거나 WSL2 안에서 실행할 수 있습니다. 현재 Windows 문서는 네이티브 실행에 Windows 11을 권장하며, 모든 업데이트가 적용된 Windows 10은 best-effort 방식으로 지원합니다.
네이티브 Windows(PowerShell). 공식 설치 프로그램:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"네이티브 실행에서는 Codex가 Windows Sandbox를 통해 작업 실행을 격리합니다. 모드는 ~/.codex/config.toml에서 설정합니다.
[windows]
sandbox = "elevated""elevated": 권장 설정으로, 전용 sandbox 사용자와 방화벽 규칙을 사용합니다."unelevated": 전용 sandbox 없이 현재 사용자에게 ACL 제한을 적용합니다.
WSL2. Linux 지침에 따라 WSL2 안에 Codex CLI Linux 버전을 설치하세요. Linux 도구를 사용할 때 OpenAI는 프로젝트를 /mnt/ 아래가 아니라 WSL 파일 시스템에 보관할 것을 권장합니다.
같은 Codex CLI를 BetterToken API에 연결하기
BetterToken은 Codex CLI를 다른 애플리케이션으로 대체하지 않습니다. OpenAI 공식 codex 실행 파일을 그대로 사용하고 ~/.codex/config.toml에서 custom provider를 선택합니다. Codex 요청은 Base URL `https://www.bettertoken.ai/v1%60%EC%9D%84?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk 통해 OpenAI Responses를 사용합니다.
다음 세 단계로 전환하세요.
- 본인의 BetterToken 계정과 전용 API Key를 만드세요. 공유 키는 사용하지 마세요.
- 현재 BetterToken Codex 가이드를 열고 최신 모델 목록에서 현재 Model ID와 provider 필드를 복사한 다음, 실행 중인 Codex를 완전히 종료하세요. Model ID, 그룹 이름, 인증 필드가 고정되어 있다고 가정하지 마세요.
- 충돌할 수 있는 기존 OpenAI 환경 변수를 제거하고 현재 Docs에 따라 provider 설정을 적용하세요. 새 터미널에서 Codex를 완전히 다시 시작하고 작은 읽기 전용 작업을 실행한 뒤, BetterToken Dashboard에서 요청, 모델, 상태, input/output/cache token 사용량을 확인하세요.
macOS 및 Linux에서는 충돌 변수를 제거합니다.
unset OPENAI_API_KEY
unset OPENAI_BASE_URLWindows PowerShell에서는 현재 세션과 이후 사용자 세션에서 제거합니다.
Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")BetterToken provider 자동 설정
이 스크립트는 BetterToken provider만 설정하며 Codex CLI 자체는 설치하지 않습니다. Node.js가 필요합니다. API Key나 모델을 인수로 넘기지 않으면 대화형 터미널에서 입력을 요청하므로 secret을 명령줄에 넣지 마세요.
macOS 및 Linux:
curl -fsSL https://www.bettertoken.ai/install-codex-provider.sh?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk | bashWindows PowerShell:
iwr https://www.bettertoken.ai/install-codex-provider.ps1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"인증 필드와 credential 저장 방식은 Codex surface와 클라이언트 버전에 따라 달라집니다. 따라서 이 글은 특정 auth boolean을 고정하지 않으며 공식 로그인과 custom provider를 하나의 설정 예시에 섞지 않습니다.
해당 surface를 현재 BetterToken Codex 가이드에서 선택하고 현재 Model ID와 provider 필드를 복사한 뒤, 변경 후 Codex를 완전히 다시 시작하세요. Secret은 글 본문이나 명령줄이 아니라 현재 Docs에서 지정한 방식으로만 전달해야 합니다.
OpenAI 공식 인증
아래 명령은 OpenAI 공식 경로에만 적용됩니다. BetterToken custom provider를 사용하는 경우 codex login status로 BetterToken API를 확인할 수 없습니다. 테스트 작업을 실행하고 Dashboard 기록을 확인하세요.
ChatGPT로 로그인하기
다음 명령을 실행하세요.
codex login브라우저가 열리면 본인의 ChatGPT 계정으로 로그인을 완료합니다. Codex는 세션을 로컬에 저장하므로 다음 실행부터는 일반적으로 다시 로그인할 필요가 없습니다.
인증 전에 인수 없이 codex를 실행해도 인터페이스가 로그인을 안내합니다. 로그인을 시작하는 기본 방법은 codex login입니다.
API Key로 로그인하기
키를 명령 인수로 넘기거나 echo로 출력하지 마세요. 값이 shell history에 남을 수 있습니다.
현재 환경이나 secret manager에서 OPENAI_API_KEY를 설정합니다. 값을 글, 명령 또는 출력에 넣지 마세요. 변수를 설정한 뒤 stdin으로 전달합니다.
printenv OPENAI_API_KEY | codex login --with-api-key키 값은 화면에 표시되지 않고 명령 기록에도 들어가지 않습니다.
인증 상태 확인하기
로그인 후 상태를 확인하세요.
codex login status현재 인증 방식 또는 로그인되지 않았다는 메시지가 표시됩니다.
인증이 없다고 나오면 해당 방식으로 로그인을 다시 진행하세요.
로그아웃하고 저장된 credential을 제거하려면 다음을 실행합니다.
codex logout~/.codex/auth.json에는 access token이 들어 있습니다. 비밀번호처럼 다루고, 직접 삭제하지 마세요. 정리할 때는 항상 codex logout을 사용합니다.
인증 문서: developers.openai.com/codex/auth. Login 하위 명령과 플래그 참고 문서: developers.openai.com/codex/cli/reference.
테스트 저장소에서 첫 작업 실행하기
작업 중인 코드에 영향을 주지 않도록 테스트 저장소에서 시작하세요. 공개 저장소를 하나 clone합니다. 여기서는 Codex 자체를 예로 듭니다.
git clone https://github.com/openai/codex codex-test
cd codex-test읽기 전용 작업을 실행합니다.
codex --sandbox read-only "Explain the entry point of this project"--sandbox read-only 플래그는 모델이 생성한 명령을 읽기로 제한합니다. Codex가 파일을 변경하지 않고 구조를 의미 있게 설명하면 첫 실행이 완료된 것입니다.
같은 제한으로 TUI를 계속하려면 다음을 실행하세요.
codex --sandbox read-only인터페이스에 What files are in this project and what does each do?를 입력합니다.
OpenAI 공식 경로를 사용하는 경우 인증이 여전히 활성 상태인지 확인하세요.
codex login statusBetterToken provider를 사용하는 경우 정상 응답이 연결의 첫 확인입니다. BetterToken Dashboard도 열어 요청, 모델, 상태, input/output/cache token 사용량이 기록에 표시되는지 확인하세요.
문제 해결
npm 설치 후 codex: command not found가 표시됨
npm config get prefix를 실행하고 결과를 PATH와 비교한 뒤 터미널을 다시 시작하세요. 정확한 실행 파일 경로는 OS와 Node.js 설치 방식에 따라 달라지므로 확인하지 않고 /bin을 추가하지 마세요.
ChatGPT 로그인 시 브라우저가 열리지 않음
GUI가 없는 원격 서버에서는 먼저 OpenAI 공식 device-code flow(beta)를 시도하세요.
codex login --device-auth먼저 ChatGPT security settings 또는 workspace permissions에서 활성화해야 합니다. 사용할 수 없다면 API Key 로그인을 이용하세요.
printenv OPENAI_API_KEY | codex login --with-api-keyCallback, device code, 대체 방법은 공식 인증 가이드를 참고하세요.
BetterToken 연결 후 Codex가 응답하지 않음
다섯 항목을 확인하세요. base_url이 정확히 https://www.bettertoken.ai/v1%60%EC%9D%B8%EC%A7%80,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk wire_api가 responses인지, Model ID와 provider 필드를 현재 BetterToken Docs에서 가져왔는지, model_provider가 선택한 [model_providers.*]테이블과 일치하는지, 기존OPENAI_API_KEY또는OPENAI_BASE_URL이 설정을 덮어쓰지 않는지 확인합니다. config.toml`을 수정한 뒤 새 터미널에서 Codex를 완전히 다시 시작하세요.
codex login status에 Not logged in이 표시됨
- ChatGPT 로그인:
codex login을 다시 실행하고 브라우저에서 로그인을 완료하세요. - API Key 로그인: 작업 환경에
OPENAI_API_KEY가 설정되어 있는지 확인한 뒤printenv OPENAI_API_KEY | codex login --with-api-key를 다시 실행하세요. ~/.codex/auth.json을 직접 삭제하지 말고codex logout을 사용하세요.
Codex CLI 문서: developers.openai.com/codex/cli. 같은 Codex CLI를 BetterToken API에 연결하는 방법: docs.bettertoken.ai/en/ai-tools/codex.
