Codex CLI 설치와 안전한 첫 실행
Codex CLI 설치, 인증 또는 custom provider 선택, 검증, 안전한 첫 작업을 다루는 최신 가이드입니다.
목차
선택적 provider automation에는 현재 scripts https://www.bettertoken.ai/install-codex-provider.sh 및 https://www.bettertoken.ai/install-codex-provider.ps1를 사용하세요. 현재 instructions에서 요구할 때만 임시 values를 TEMP에 보관합니다.
계속하려면 본인의 BetterToken 계정과 API Key를 사용하세요. BetterToken 계정 만들기
Codex CLI는 터미널에서 사용하는 OpenAI의 코딩 에이전트입니다. 공식 codex 클라이언트 하나를 설치한 다음 ChatGPT 로그인, OpenAI API Key 또는 지원되는 custom provider 중 한 가지 접근 경로를 선택합니다. provider마다 별도 Codex 앱을 설치할 필요가 없습니다.
안전한 첫 실행은 설치, codex --version 확인, 인증 또는 provider 경로 하나 완료, 테스트 리포지토리에서 읽기 전용 작업 실행의 네 단계로 진행합니다. 이 검증 전에는 프로덕션 코드를 열지 마세요.
이 글은 2026년 8월 21일의 OpenAI Codex 리포지토리와 BetterToken Codex 문서를 기준으로 확인했습니다. 설치 명령과 구성 필드는 바뀔 수 있으므로 실제 설정 시에는 연결된 1차 문서를 따르세요.
종량제 custom provider를 선택한다면 BetterToken Codex 설정 가이드를 열고 자신의 API Key를 만든 뒤, 프로덕션 리포지토리를 열기 전에 첫 요청을 검증하세요. BetterToken은 공식 Codex CLI에 custom provider를 설정하는 방식이며 별도 Codex 클라이언트나 ChatGPT 구독이 아닙니다.
설치 방법 선택
| 방법 | 적합한 경우 | 요구 사항 |
|---|---|---|
| 독립 설치 프로그램 | macOS, Linux, Windows에 직접 설치 | curl 또는 PowerShell, Node.js 불필요 |
| Homebrew cask | Homebrew로 관리하는 macOS | Homebrew |
| npm | Node.js 기반 환경 | 작동하는 Node.js와 npm |
| GitHub Releases 바이너리 | 수동 또는 통제된 설치 | 아카이브와 PATH 관리 |
유지보수되는 Codex CLI는 Rust로 구현됩니다. Node.js는 npm 설치 또는 Node.js를 명시적으로 요구하는 별도 provider 설정 스크립트에만 필요합니다.
사전 조건 확인
OpenAI 설치 문서는 macOS 12 이상, Ubuntu 20.04+/Debian 10+, WSL2를 통한 Windows 11을 지원 기준으로 안내합니다. 리포지토리 작업에는 Git을 권장합니다. 네이티브 Windows 지원과 sandbox 세부 사항은 별도 문서에 있으며 변경될 수 있습니다.
설치 전 확인할 사항입니다.
- OpenAI 공식 인증과 custom provider 중 하나를 결정합니다.
- 대상 터미널이
PATH를 갱신할 수 있는지 확인합니다. - 프로덕션 working tree가 아닌 테스트 리포지토리에서 시작합니다.
- API Key를 명령 인수, 소스 파일, 스크린샷, 셸 기록에 넣지 않습니다.
Codex CLI 설치
macOS 및 Linux: 독립 설치 프로그램
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version설치 프로그램이 PATH를 바꿨다면 새 터미널을 여세요.
macOS: Homebrew
brew install --cask codex
codex --versionnpm: macOS, Linux 또는 Windows
npm install -g @openai/codex
codex --versioncodex를 찾지 못하면 실제 npm 전역 prefix를 확인합니다.
npm config get prefix그 위치를 PATH와 비교하고 일반적인 Node.js 또는 셸 설정을 수정한 뒤 새 터미널을 여세요. 실제 설치 구조를 확인하지 않고 추정한 /bin 경로를 추가하지 마세요.
Windows와 GitHub Releases
공식 PowerShell 설치 프로그램입니다.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --versionWindows에서 Linux 중심으로 개발한다면 WSL2 안에 Linux CLI를 설치하고, 가능하면 프로젝트를 /mnt/ 아래가 아니라 WSL 파일 시스템에 둡니다. Codex Releases에는 OS와 CPU 아키텍처별 아카이브도 있습니다. 맞는 바이너리를 이미 PATH가 관리하는 디렉터리에 풀고 버전을 확인하세요.
접근 경로는 정확히 하나만 선택
문제를 진단할 때 OpenAI 공식 로그인 상태와 custom provider 구성을 섞지 마세요. 먼저 한 경로를 검증합니다.
ChatGPT로 로그인
codex login
codex login status브라우저 흐름을 완료하세요. GUI가 없는 시스템에서는 다른 컴퓨터에서 브라우저 토큰을 복사하지 말고, 현재 OpenAI가 문서화한 device code 또는 API Key 방식을 사용하세요.
OpenAI API Key 사용
키는 secret manager나 환경 변수에 저장하고 눈에 보이는 명령 인수로 전달하지 마세요. 지원되는 로그인 흐름과 credential storage는 OpenAI 인증 가이드를 따릅니다. 저장된 공식 자격 증명은 codex logout으로 제거합니다.
custom provider 구성
custom provider도 같은 공식 CLI를 사용합니다. 구성에서 Base URL, API 프로토콜, 모델, Key를 제공하는 환경 변수를 선택합니다. BetterToken은 OpenAI Responses API를 통한 Codex 경로를 문서화합니다. 현재 Base URL은 https://www.bettertoken.ai/v1이며 Model ID와 Key group은 동적이므로 현재 인터페이스나 문서에서 가져와야 합니다.
테스트 전에 원하는 provider 구성을 덮어쓸 수 있는 오래된 OpenAI 환경 변수를 제거합니다.
unset OPENAI_API_KEY
unset OPENAI_BASE_URL그 다음 현재 BetterToken Codex 가이드를 따르세요. 최신 config.toml 필드, wire_api = "responses", Key 변수, 모델 선택, 시작 명령이 포함되어 있습니다. 구성을 바꾼 뒤에는 Codex를 완전히 재시작합니다.
안전한 첫 실행
중요하지 않은 리포지토리에서 시작합니다.
git clone https://github.com/openai/codex codex-test
cd codex-test
codex --sandbox read-only "Explain the entry point of this project"의도한 접근 경로로 Codex가 시작되고, 관련 파일을 올바르게 식별하며, 파일을 수정하지 않고, 예상하지 못한 쓰기나 실행 권한을 요구하지 않으면 첫 실행이 성공한 것입니다. BetterToken을 사용할 때는 정상적인 모델 응답과 Dashboard의 해당 요청, 모델, 상태, token usage 기록도 API 경로를 확인합니다.
계층별 문제 해결
codex: command not found
새 터미널을 열고 설치가 끝났는지와 실제 설치 위치를 확인합니다. npm은 npm config get prefix를 사용하고, Release 바이너리는 그 디렉터리가 PATH에 있는지 확인합니다.
브라우저가 열리지 않음
브라우저 사용 가능 여부와 callback 차단 여부를 확인합니다. headless 시스템에서는 문서화된 device code 또는 API Key 경로를 사용하세요. 다른 시스템의 인증 파일을 복사하지 마세요.
custom provider가 401, 403, 404 또는 HTML을 반환
Key 변수, 계정, provider, Base URL, 오래된 환경 변수의 덮어쓰기를 확인합니다. Key는 절대 출력하지 마세요. 404나 HTML이면 현재 Codex Docs와 Base URL을 비교하고 Claude Code용 Base URL을 재사용하지 않았는지 점검합니다.
model not found 또는 변경이 적용되지 않음
오래된 글이나 스크린샷이 아니라 provider의 현재 모델 목록에서 Model ID를 복사합니다. Codex 프로세스를 모두 중지하고 새 터미널을 연 뒤 활성 profile 또는 구성 파일을 확인하고 작은 읽기 전용 요청 하나로 다시 테스트합니다. 인증, 모델, Base URL, sandbox를 동시에 바꾸지 마세요.
최종 체크리스트
codex --version이 버전을 반환합니다.- 테스트에서는 인증 또는 provider 경로 하나만 활성화되어 있습니다.
- secret이 소스 코드와 셸 기록 밖에 있습니다.
- Base URL, 프로토콜, 모델, Key 변수가 현재 provider 문서와 일치합니다.
- 테스트 리포지토리에서 읽기 전용 작업이 파일 변경 없이 성공합니다.
- 사용 내역이 예상한 provider Dashboard 또는 계정 기록에 나타납니다.
이 확인 뒤 실제 리포지토리를 필요한 최소 권한으로 열 수 있습니다. 자율성을 높이기 전에 제안된 명령과 diff를 검토하세요.
