Codex CLI 설치와 업데이트: Mac, Linux, Windows

OpenAI Codex CLI 설치는 플랫폼당 명령 하나입니다. macOS와 Linux에서는 curl -fsSL https://chatgpt.com/codex/install.sh | sh, Windows에서는 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"이고, npm과 Homebrew가 지원되는 대안입니다. 업데이트는 codex update이며, 스크립트, npm, Homebrew 설치를 인식해 해당 채널의 업그레이드를 실행합니다.¹⁴¹¹ 대부분의 페이지가 건너뛰는 부분은 첫 명령 이후입니다. 다섯 가지 설치 경로 가운데 무엇을 고를지, 릴리스가 문제를 일으킬 때 버전을 어떻게 고정할지, winget 패키지가 왜 npm보다 마이너 버전 일곱 개 뒤처져 있는지, 제거 후 ~/.codex에 무엇이 남는지입니다. 이 페이지가 그 참고 자료입니다. 작업당 표 하나, v0.153.4(2026년 9월 4일) 기준 최신입니다.⁹

TL;DR

• 독립형 설치 프로그램이 OpenAI가 앞세우는 경로입니다. README와 CLI 문서 모두에서 그렇고, npm과 Homebrew는 대안으로 제시됩니다(CLI 문서에서는 “you can also install”, README에서는 “can also be installed via”). macOS와 Linux에서는 install.sh 스크립트, Windows에서는 install.ps1 스크립트입니다. 컴파일된 바이너리를 내려받으므로 Node가 필요 없습니다.¹¹¹
• npm과 Homebrew는 지원되는 대안입니다. npm install -g @openai/codex는 평범한 패키지 스펙(@<version>)으로 버전을 고정합니다. brew install --cask codex는 이 글을 쓸 때 npm과 같은 0.153.4였습니다.¹²¹⁰
• Codex 자체를 설치할 때는 winget을 피하십시오. OpenAI가 OpenAI.Codex 패키지를 게시하기는 하지만, 0.147.0부터 0.152.0까지의 매니페스트 풀 리퀘스트가 2026년 8월 7일 이후 microsoft/winget-pkgs에서 병합되지 않은 채 쌓여 있어서, 글을 쓰는 날 기준으로 설치 가능한 최신 버전은 npm의 0.153.4에 대해 0.146.1입니다.³¹⁰
• codex update는 스크립트, npm, Homebrew 설치를 다룹니다(v0.128.0 이후). TUI가 이미 갖고 있던 설치 채널 감지를 재사용해 알맞은 업그레이드를 실행합니다. winget 설치는 인식하는 채널이 아니므로, 그것은 winget upgrade OpenAI.Codex로 업데이트하십시오. 나머지의 수동 대응은 설치 프로그램 재실행, npm install -g @openai/codex@latest, brew upgrade --cask codex입니다.⁴¹¹
• 버전 고정은 install.sh에서는 --release <version>, install.ps1 줄 앞에서는 $env:CODEX_RELEASE, npm에서는 @<version>입니다. Homebrew의 cask는 현재 버전 하나만 추적하므로 고정할 수 없습니다.²¹²
• 패키지를 제거해도 상태는 지워지지 않지만, 스크립트 설치에서는 rm -rf ~/.codex가 CLI 자체까지 지웁니다. 설치 프로그램이 릴리스를 ~/.codex/packages/standalone 아래에 보관하기 때문입니다.¹²

Codex CLI는 어떻게 설치합니까?

OpenAI 자체 문서가 제시하는 순서대로 네 가지 경로,¹¹¹ 그리고 OpenAI가 문서화하지 않은 Windows의 winget입니다.³

# Standalone installer, no Node required (macOS, Linux, WSL) -- the route OpenAI lists first
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

# npm (needs Node.js 16+; pins with a plain @version spec)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows; lags npm, see the platform section)
winget install OpenAI.Codex

그런 다음 설치되었는지 확인하고 로그인합니다.

codex --version      # codex-cli 0.153.4
codex login          # ChatGPT account (recommended) or an API key

첫 스크립트 설치에서 프로필 블록은 새 셸에서만 효력이 있습니다. 설치한 터미널에서 codex를 찾을 수 없다면, 거기서 export PATH="$HOME/.local/bin:$PATH"를 실행하거나 새 터미널을 여십시오. 설치 프로그램은 끝날 때 같은 두 줄(“Current terminal”과 “Future terminals”)을 출력합니다.¹²

바이너리를 직접 쓰고 싶습니까? 모든 GitHub 릴리스에는 플랫폼별 tarball(codex-aarch64-apple-darwin.tar.gz, codex-x86_64-apple-darwin.tar.gz, codex-x86_64-unknown-linux-musl.tar.gz, codex-aarch64-unknown-linux-musl.tar.gz)이 실려 있고, v0.106.0부터는 같은 install.sh가 각 릴리스에 자산으로 첨부됩니다. 각 아카이브에는 플랫폼 이름이 붙은 항목 하나가 들어 있으므로, 압축을 풀고 codex로 이름을 바꾸십시오.¹⁵

설치 프로그램은 OpenAI가 호스팅하는 릴리스 인프라에서 가져옵니다. chatgpt.com/codex/install.sh는 releases.openai.com으로 리디렉션되며, 이 변경은 v0.146.0에서 도입되었고 GitHub Releases는 폴백 호스트로 유지됩니다.⁶ OpenAI의 아티팩트 호스트를 차단하거나 제한하지만 GitHub는 허용하는 네트워크에서는, 릴리스 자산에서 스크립트를 가져오고 바이너리도 GitHub에서 받도록 지시하십시오.¹¹²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

변수는 파이프의 sh 쪽에 둡니다. VAR=value curl ... | sh 형태는 변수를 curl에만 적용하므로, 스크립트는 그것을 보지 못하고 조용히 기본값을 유지합니다. PowerShell에서는 설치 줄을 실행하기 전에 $env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM = 'false'를 설정하십시오.

어떤 경로를 골라야 합니까?

Codex는 어떤 플랫폼을 지원합니까?

Windows에서 Codex는 Windows 샌드박스와 함께 PowerShell에서 네이티브로 실행되며, 샌드박스 모드는 두 가지입니다. elevated가 선호되는 모드로, 전용 저권한 샌드박스 사용자, 파일 시스템 권한 경계, 방화벽 규칙, 로컬 정책 변경을 사용하며 관리자가 승인하는 설정이 필요합니다. unelevated는 폴백으로, 당신의 사용자에서 파생된 제한된 Windows 토큰과 ACL 기반 파일 시스템 경계로 명령을 실행합니다.⁸ 모드는 config.toml에서 선택합니다.

[windows]
sandbox = "elevated"   # or "unelevated"

OpenAI의 지침은 기본적으로 네이티브 샌드박스를 쓰고, Linux 네이티브 도구가 필요하거나, 워크플로가 이미 WSL2에 있거나, 두 네이티브 Windows 샌드박스 모드 어느 쪽도 맞지 않을 때 WSL을 택하라는 것입니다.⁸ 한 가지 구분해 둘 점: Windows 설정은 자체 설정 단계를 위해 머신에 winget이 있다고 가정하는데, 이것은 winget을 통해 Codex를 설치하는 것과는 별개입니다. OpenAI가 그 패키지를 게시하기는 합니다. 릴리스 워크플로에는 안정 릴리스에 대해 microsoft/winget-pkgs에 매니페스트 풀 리퀘스트를 여는 winget 잡이 있습니다. 그러나 그 제출은 0.146.1 매니페스트가 2026년 8월 7일에 병합된 이후 병합되지 않은 채 쌓여 있습니다. 0.147.0부터 0.152.0까지의 요청은 이 글을 쓸 때 모두 열려 있었고, 0.153.0부터 0.153.4까지는 요청 자체가 없습니다. CLI에는 아무 문제가 없습니다. 패키지 색인이 뒤처져 있을 뿐입니다.³⁸

Node.js는 npm 경로에서만 요구 사항입니다. 설치 스크립트는 컴파일된 바이너리를 내려받고, Homebrew cask는 의존성을 선언하지 않습니다.¹²

Codex CLI는 어떻게 업데이트합니까?

Codex는 스스로 업데이트하지 않습니다. TUI가 새 릴리스를 알아차리고 당신의 설치 채널에 맞는 명령을 제안합니다. 실행은 당신의 몫이며, 내장 명령은 스크립트, npm, Homebrew 설치를 다룹니다.⁴ 시작 시 확인 자체는 설정 키입니다. config.toml의 check_for_update_on_startup = false이며, 레퍼런스는 이것을 “Check for Codex updates on startup (set to false only when updates are centrally managed)”라고 설명합니다. 업데이트를 중앙에서 관리하는 조직은 requirements.toml에 features.in_app_updates = false를 설정합니다.¹⁶

codex --version                      # what you run now
npm view @openai/codex version       # newest published

codex update                         # built-in, v0.128.0+; detects your install channel

codex update는 2026년 4월 30일 v0.128.0에서 도입되었습니다. 이것을 추가한 풀 리퀘스트는 TUI가 업데이트 안내에 이미 쓰던 설치 채널 감지와 업데이트 실행기를 재사용했습니다. 채널 맵은 npm(그리고 bun, pnpm, Vite+ 변형), Homebrew, Unix와 Windows의 독립형 설치 프로그램을 다룹니다. winget 설치는 거기에 없으므로, winget으로 설치한 Codex는 winget upgrade OpenAI.Codex로만 업데이트됩니다.⁴ 수동 대응은, 그쪽을 선호하거나 머신 이미지를 스크립트로 만들고 있다면 다음과 같습니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # standalone: re-run the installer
npm install -g @openai/codex@latest                    # npm
brew upgrade --cask codex                              # Homebrew
winget upgrade OpenAI.Codex                            # winget (to whatever winget has)

irm https://chatgpt.com/codex/install.ps1 | iex           # standalone on Windows: re-run the installer

릴리스는 빠른 안정 라인으로 나옵니다. 0.150.0부터 0.153.4까지가 2026년 8월 26일과 9월 4일 사이에 나왔으므로, “내가 쓰는 것”과 “최신” 사이의 간격은 분기가 아니라 일주일인 경우가 많습니다.⁹

특정 버전은 어떻게 설치합니까?

npm과 설치 스크립트는 버전으로 고정할 수 있고, Homebrew는 그렇지 않습니다.²¹²

npm install -g @openai/[email protected]                                          # npm: exact version
curl -fsSL https://chatgpt.com/codex/install.sh | sh -s -- --release 0.152.1  # script: --release flag
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_RELEASE=0.152.1 sh    # script: env var, on the sh side
winget install OpenAI.Codex --version 0.146.1                                 # winget: only what it has
codex --version                                                               # verify the rollback took

환경 변수 형태에서는 위치에 유의하십시오. CODEX_RELEASE=0.152.1은 파이프 뒤, sh 앞에 있어야 합니다. curl 앞에 쓰면 변수는 curl에만 적용되고, 스크립트는 당신이 고정했다고 믿는 동안 latest를 설치합니다.¹² Windows에서 PowerShell 스크립트는 유일한 매개변수로 $Release = $env:CODEX_RELEASE를 선언하고 비어 있으면 latest로 돌아가므로, 고정은 같은 세션에서 설정한 그 변수입니다.¹⁷

$env:CODEX_RELEASE = '0.152.1'; irm https://chatgpt.com/codex/install.ps1 | iex

고정은 릴리스가 문제를 일으킬 때 옳은 수입니다. 이슈를 제출하고, 마지막으로 괜찮았던 버전으로 고정하고, 넘어가십시오. 고정할 때마다 codex --version으로 확인하십시오. PATH의 다른 곳에 있는 두 번째 설치가 조용히 자기 바이너리를 계속 제공하기 때문입니다. 설치 스크립트는 정확히 이것을 검사합니다. PATH에 이미 Homebrew, npm, bun이 관리하는 codex가 있으면 “Multiple managed Codex installs can be ambiguous because PATH order decides which one runs”라고 경고하고 알맞은 제거 명령을 대신 실행하겠다고 제안합니다.¹² codex doctor는 사후에 같은 상태를 Environment 아래에 보고합니다.⁷

Codex CLI는 어떻게 제거합니까?

설치한 경로로 제거합니다.

npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

스크립트 설치에는 물어볼 패키지 관리자가 없습니다. 설치 프로그램은 ~/.local/bin에 codex 심볼릭 링크를 두는데(CODEX_INSTALL_DIR로 재정의 가능), 이것은 ~/.codex/packages/standalone/current 안의 바이너리(현재 릴리스에서는 current/bin/codex)를 가리킵니다. current 자체는 내려받은 각 릴리스가 놓이는 ~/.codex/packages/standalone/releases/로 향하는 심볼릭 링크입니다. macOS에서는 설치 프로그램이 첫 링크 옆에 두 번째 심볼릭 링크 codex-code-mode-host를 추가합니다.¹² 전부 제거합니다.

rm -f ~/.local/bin/codex ~/.local/bin/codex-code-mode-host   # the second link exists on macOS installs only
rm -rf ~/.codex/packages/standalone

설치할 때 ~/.local/bin이 PATH에 없었거나, 설치 프로그램이 경쟁하는 Homebrew, npm, bun 설치를 발견하고 항목을 다시 썼다면, 스크립트는 셸 프로필에도 표시된 블록을 덧붙였습니다. ~/.zprofile(macOS zsh), ~/.bash_profile, ~/.zshrc, ~/.bashrc, 또는 ~/.profile의 # >>> Codex installer >>>부터 # <<< Codex installer <<<까지입니다. 그 세 줄을 지우면 끝입니다.¹²

Windows에서 install.ps1은 %USERPROFILE%\.codex\packages\standalone(그 변수를 설정했다면 %CODEX_HOME%\packages\standalone) 아래에 같은 배치를 유지합니다. 내려받은 릴리스는 releases\에, 활성 릴리스를 가리키는 current 정션이 있습니다. codex.exe는 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin(CODEX_INSTALL_DIR로 재정의 가능)을 통해 노출되는데, 이것 자체가 current\bin으로 향하는 정션이며, 프로필 블록 대신 그 bin 경로를 이후 PowerShell 세션을 위해 사용자 PATH에 씁니다. 독립형 디렉터리를 먼저 제거하고, 그다음 이제 대상이 없어진 bin 정션을 제거하고, 그다음 환경 변수의 사용자 Path 변수에서 항목을 빼십시오.¹⁷

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\packages\standalone"   # releases plus the current junction
cmd /c rmdir "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin"                  # the bin junction; rmdir removes the link, not a target

위의 패키지 관리자 제거는 ~/.codex/를 건드리지 않습니다. Homebrew의 --zap도 실제로는 마찬가지입니다. cask의 유일한 zap 절은 rmdir: "~/.codex"이고, Homebrew는 rmdir:를 이미 비어 있는 디렉터리에만 적용합니다.² 그 디렉터리에는 config.toml, 저장된 자격 증명, 모든 세션이 들어 있으며, 그래서 재설치하면 로그인과 기록이 그대로 이어집니다. 정말로 깨끗한 상태를 원할 때만 지우고, 스크립트 설치에서 그것이 무엇을 뜻하는지 알아 두십시오.

rm -rf ~/.codex   # discards config.toml, credentials, all sessions -- AND the CLI itself on a script install

상태를 유지하는 깨끗한 재설치는 npm에서 한 줄입니다. npm uninstall -g @openai/codex && npm install -g @openai/codex@latest. 스크립트 경로에서는 설치 프로그램을 다시 실행하면 ~/.codex/packages/standalone 아래의 릴리스가 교체되고 설정은 그대로 남습니다.¹²

전체 수명 주기를 표 하나로

codex doctor는 무엇을 검사합니까?

codex doctor는 버그를 제출하기 전이나 “어제는 됐던” 설치를 디버깅하기 전에 실행할 명령입니다. 0.153.4에서는 보고서 하나에 일곱 개 섹션을 담습니다. Notes, Environment(런타임과 설치 일관성), Configuration(config.toml 로드 상태, 인증, MCP, 샌드박스 정책), Desktop App(v0.149.0에서 추가), Updates, Connectivity, Background Server입니다. --summary는 간결한 보기, --json은 민감 정보를 가린 기계 판독 형식, --all은 잘린 목록 펼치기, --no-color는 로그용입니다. 0.153.4의 codex doctor --help에는 --ascii도 있습니다.⁷¹³¹⁵ “Codex가 고장 났다”는 보고의 대부분은 첫 화면에 이름이 나오는 무언가로 귀결됩니다. 오래된 인증 모드, 파싱에 실패한 config.toml, 또는 PATH의 것을 가리는 두 번째 설치입니다. 섹션별 전체 설명은 가이드에 있습니다.

설치 후 달라지는 것

새 설치가 처음 걸려 넘어지는 것은 바이너리가 아닙니다. v0.149.0부터 CLI는 approval_policy = "untrusted"에서 시작을 거부하므로, 이전 머신에서 복사한 config.toml에는 수정 하나가 필요합니다.¹³ Claude Code에서 넘어오셨습니까? 마이그레이션 글이 두 설정을 나란히 대응시키고, 훅 글은 Codex가 모델 주위에서 무엇을 실행하는지 다룹니다. Codex CLI 가이드가 전체 참고 자료입니다. 샌드박스와 승인 모드, AGENTS.md, MCP, 스킬, 클라우드 작업까지. 두 도구를 모두 쓴다면, Claude Code 설치 페이지가 이 페이지의 쌍둥이입니다.

자주 묻는 질문

Codex CLI를 최신 버전으로 업데이트하려면 어떻게 합니까?

codex update(v0.128.0 이후)를 실행하십시오. 스크립트, npm, Homebrew 가운데 어느 것으로 설치했는지 감지해 해당 채널의 업그레이드를 실행합니다. 수동 대응은 설치 스크립트 재실행, npm install -g @openai/codex@latest, 또는 brew upgrade --cask codex입니다. winget 설치는 codex update가 인식하는 채널이 아니므로, 그것은 winget upgrade OpenAI.Codex를 쓰십시오.

Codex CLI는 자동으로 업데이트됩니까?

아닙니다. TUI가 새 릴리스를 확인하고 설치 채널에 맞는 업데이트 명령을 제안하며, codex update(v0.128.0 이후)가 그것을 실행합니다. 당신이 실행하기 전에는 아무것도 내려받거나 적용되지 않습니다.

Codex CLI는 어떻게 제거합니까?

설치한 경로를 쓰십시오. npm uninstall -g @openai/codex, brew uninstall --cask codex, 또는 winget uninstall OpenAI.Codex입니다. 스크립트 설치라면 ~/.local/bin/codex 심볼릭 링크(macOS에서는 ~/.local/bin/codex-code-mode-host도)와 ~/.codex/packages/standalone 디렉터리를 제거하십시오. Windows에서 스크립트 설치는 %USERPROFILE%\.codex\packages\standalone, %LOCALAPPDATA%\Programs\OpenAI\Codex\bin 정션, 사용자 PATH의 항목이며, 셋 다 제거하십시오. 설정, 자격 증명, 세션은 당신이 그 디렉터리의 나머지를 직접 지우기 전까지 ~/.codex/에 남습니다.

Windows에서는 Codex CLI를 어떻게 설치합니까?

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"를 실행하십시오. CLI는 Windows 샌드박스와 함께 PowerShell에서 네이티브로 실행되며(elevated가 선호, unelevated가 폴백), WSL2는 Linux 도구가 필요하거나 어느 샌드박스 모드도 맞지 않을 때의 선택지이지 요구 사항이 아닙니다. Windows 11이 권장 기준선입니다. winget install OpenAI.Codex도 되지만 안정 라인보다 뒤처집니다.

Codex를 설치하려면 Node.js가 필요합니까?

npm 경로에서만 필요하며, 패키지는 Node 16 이상을 요구합니다. 설치 스크립트, PowerShell 스크립트, Homebrew cask는 모두 컴파일된 codex 바이너리를 제공하므로, Node가 없는 머신에서도 Codex를 실행할 수 있습니다.

내 Codex 버전은 어떻게 확인합니까?

codex --version이 출력합니다(예: codex-cli 0.153.4). npm view @openai/codex version은 게시된 최신 버전을 보여 주고, codex doctor는 설치 경로와 PATH의 다른 복사본이 그것을 가리고 있는지를 보고합니다.