30초 요약: 대부분 파일 선택 문제입니다
1. 애플 실리콘 맥은 aarch64-apple-darwin, 인텔 맥은 x86_64-apple-darwin입니다. 이름이 비슷해 반대로 받으면 실행되지 않습니다.
2. 최신 릴리스에 자산이 160개나 됩니다. codex-app-server-, codex-package-, codex-symbols-처럼 접두어가 다른 것들이 섞여 있어 CLI 본체가 아닌 파일을 받기 쉽습니다.
3. 로그인 정보 저장 위치는 cli_auth_credentials_store로 정합니다. file·keyring·auto·ephemeral 네 값이 있고, keyring은 OS 자격증명 저장소를 쓸 수 없으면 실패합니다.
가장 빠른 해법부터 말하면, 직접 내려받는 대신 npm으로 설치하는 쪽이 아키텍처 선택을 자동으로 처리해 줍니다. 그래도 파일을 직접 받아야 하는 상황이라면 아래를 보세요.
1. 아키텍처: aarch64인가 x86_64인가
내 맥이 어느 쪽인지부터 확인해야 합니다. 터미널에서 한 줄이면 됩니다.
uname -m
· arm64가 나오면 애플 실리콘(M 시리즈) → aarch64 파일
· x86_64가 나오면 인텔 맥 → x86_64 파일
헷갈리는 이유가 있습니다. 애플 실리콘 맥에서도 로제타를 거치면 uname -m이 x86_64로 보일 수 있습니다. 터미널 앱 정보에서 “Rosetta를 사용하여 열기”가 켜져 있는지 확인해 보세요. 켜져 있다면 끄고 다시 확인하는 편이 정확합니다.
| 환경 | 받아야 할 파일 |
|---|---|
| 애플 실리콘 맥 | codex-aarch64-apple-darwin.tar.gz 또는 .dmg |
| 인텔 맥 | codex-x86_64-apple-darwin.tar.gz 또는 .dmg |
| Linux (x86) | codex-x86_64-unknown-linux-musl.tar.gz |
| Linux (ARM) | codex-aarch64-unknown-linux-musl.tar.gz |
| Windows | codex-x86_64-pc-windows-msvc.exe 계열 |
2. 비슷한 파일명이 160개 있습니다
릴리스 페이지를 열면 자산 목록이 아주 깁니다. 2026년 9월 15일 확인 시점의 최신 릴리스(rust-v0.154.0)에 자산이 160개였습니다. 여기서 CLI 본체가 아닌 파일을 받는 일이 잦습니다.
| 파일명 접두어 | 정체 | CLI 설치용? |
|---|---|---|
| codex-<arch>-... | CLI 본체 | 예 |
| codex-app-server-... | IDE 확장 등이 쓰는 앱 서버 | 아니요 |
| codex-package-... | 패키징된 배포본 | 용도에 따라 |
| codex-symbols-... | 디버그 심볼 | 아니요 |
| codex-responses-api-proxy-... | API 프록시 | 아니요 |
| codex-code-mode-host-... | 코드 모드 호스트 | 아니요 |
| codex-npm-*.tgz | npm 배포용 tarball | npm이 알아서 씀 |
확장자도 세 가지가 섞여 있습니다. .tar.gz(범용), .zst(zstd 압축, 별도 도구 필요), .dmg(맥 디스크 이미지). 압축 해제가 안 된다면 .zst를 받았을 가능성이 높습니다.
릴리스에는 codex라는 이름의 DotSlash 파일도 포함됩니다. 공식 문서 설명으로는 “소스 관리에 가벼운 커밋을 만들어 모든 기여자가 플랫폼과 무관하게 같은 버전의 실행 파일을 쓰도록” 해 주는 장치입니다. 팀에서 버전을 고정하고 싶을 때 쓰는 것이지, 개인이 그냥 설치할 때 받는 파일은 아닙니다.
3. 로그인 정보가 어디에 저장되나
cli_auth_credentials_store로 검색해서 들어오는 경우가 여기입니다. 공식 인증 문서가 이 설정을 이렇게 설명합니다.
기본 동작은 이렇습니다. Codex는 로그인 정보를 ~/.codex/auth.json이라는 평문 파일이나 OS 자격증명 저장소에 캐시합니다. ChatGPT 로그인 세션은 만료 전에 토큰을 자동 갱신해서, 보통은 다시 브라우저 로그인을 하지 않아도 이어집니다.
| 값 | 저장 위치 | 주의 |
|---|---|---|
| file | CODEX_HOME(기본 ~/.codex) 아래 auth.json | 평문입니다. 문서가 파일 권한 관리를 당부합니다 |
| keyring | OS 자격증명 저장소 | 사용할 수 없으면 실패합니다. 원격 서버·컨테이너에서 자주 걸립니다 |
| auto | OS 저장소가 있으면 그쪽, 없으면 auth.json | 대부분의 경우 무난한 선택 |
| ephemeral | 현재 프로세스 메모리에만 | CI나 일회성 실행용 |
설정은 config.toml에 한 줄입니다.
# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"
여기서 막히는 전형적인 상황이 두 가지입니다. 하나는 SSH로 접속한 리눅스 서버나 컨테이너에서 keyring을 쓰도록 돼 있는 경우입니다. 데스크톱 세션이 없어 OS 저장소에 접근할 수 없으니 실패합니다. auto나 file로 바꾸면 됩니다.
다른 하나는 조직 정책입니다. 문서가 명시합니다. 관리자는 cli_auth_credentials_store와 chatgpt_base_url을 로컬 인증 요구사항으로 강제할 수 있고, 사용자는 config.toml이나 CLI 옵션으로 덮어쓸 수 없습니다. 회사 계정으로 쓰는데 설정이 안 먹는다면 이 경우일 수 있습니다.
문서가 적어 둔 동작입니다. “CLI와 확장은 같은 캐시된 로그인 정보를 공유한다. 둘 중 하나에서 로그아웃하면 다음에 CLI나 확장을 시작할 때 다시 로그인해야 한다.” 한쪽에서 로그아웃했는데 다른 쪽도 풀리는 이유가 여기 있습니다.
4. 시스템 요구사항을 먼저 봅니다
설치 문서가 요구사항을 표로 정리해 두었습니다. 특히 윈도우 항목이 중요합니다.
| 항목 | 요구사항 |
|---|---|
| 운영체제 | macOS 12 이상, Ubuntu 20.04+/Debian 10 이상, 또는 Windows 11(WSL2 경유) |
| Git (선택·권장) | 2.23 이상. 내장 PR 도우미용 |
| RAM | 최소 4GB, 8GB 권장 |
윈도우가 “via WSL2”로 명시돼 있다는 점을 놓치기 쉽습니다. 릴리스에 codex-x86_64-pc-windows-msvc.exe 같은 윈도우 네이티브 바이너리가 있어서 그냥 받으면 되는 것처럼 보이지만, 문서가 제시하는 요구사항은 WSL2입니다. 네이티브에서 문제가 생긴다면 WSL2로 옮겨 보는 것이 공식 경로에 가깝습니다.
설치 경로를 어떻게 고를까
가장 무난한 방법npm으로 설치하면 아키텍처에 맞는 바이너리를 자동으로 고릅니다. 릴리스에 codex-npm-darwin-arm64, codex-npm-darwin-x64처럼 플랫폼별 패키지가 따로 올라가 있고, 설치 시 맞는 것이 내려옵니다.
직접 받아야 한다면uname -m으로 확인 → codex-<arch>-apple-darwin.tar.gz를 받습니다. 접두어가 codex- 바로 뒤에 아키텍처가 오는 파일이 CLI 본체입니다.
팀에서 버전을 고정하고 싶다면DotSlash 파일을 저장소에 커밋하는 방식이 공식 문서가 제시하는 방법입니다.
소스에서 빌드하려면Rust 툴체인이 필요합니다. 문서의 절차는 저장소를 받아 codex-rs로 이동한 뒤 rustup으로 툴체인을 깔고 cargo build입니다. 일반 사용 목적이라면 권하지 않습니다.
자주 묻는 질문
애플 실리콘인데 x86_64를 받으면 어떻게 되나요?
실행이 안 되거나 로제타 설치를 요구합니다. uname -m으로 확인한 값과 파일명의 아키텍처를 맞추세요.
.zst 파일은 어떻게 여나요?
zstd 압축 형식이라 별도 도구가 필요합니다. 특별한 이유가 없다면 .tar.gz를 받는 편이 간단합니다.
auth.json이 평문이라는데 괜찮나요?
문서도 이 점을 전제로 파일 권한 관리를 당부합니다. 걱정된다면 cli_auth_credentials_store를 keyring이나 auto로 바꾸세요. 다만 keyring은 OS 저장소를 못 쓰는 환경에서 실패합니다.
설정을 바꿨는데 적용이 안 됩니다.
조직 관리자가 로컬 인증 요구사항으로 강제한 경우 사용자가 덮어쓸 수 없습니다. 문서에 명시된 동작이므로 관리자에게 확인해야 합니다.
이 글은 오류를 직접 재현한 건가요?
아닙니다. 공식 릴리스 자산 목록(160개, rust-v0.154.0)과 인증·설치 문서를 직접 확인해 원인을 정리한 글입니다. 각 오류 메시지를 실제로 발생시켜 본 기록은 아니므로, 환경에 따라 다른 원인일 수 있습니다.
2026년 9월 15일 openai/codex GitHub 저장소의 최신 릴리스(rust-v0.154.0) 자산 목록을 API로 직접 조회해 파일명 체계와 개수(160개)를 확인했고, docs/install.md의 시스템 요구사항과 DotSlash·소스 빌드 안내, developers.openai.com의 Codex 인증 문서에서 cli_auth_credentials_store의 네 가지 값과 관리자 강제 규정, 로그인 캐시 위치를 확인했습니다. 개별 오류 메시지를 직접 재현하지는 않았습니다.