OpenAI Codex CLI 설치 방법 (Windows, macOS, Linux)

- 명령어와 문서 경로는 작성 시점(2026년 8월)의 공식 문서와 대조해 확인했어요. Codex의 문서 도메인은 이미 한 번 옮겨졌으니(developers.openai.com → learn.chatgpt.com), 이 페이지가 오래됐다면 실행하기 전에 최신 공식 문서를 확인하세요.

Codex CLI를 설치하기 전에

OpenAI Codex를 설치하기 전에 다음을 준비해 두세요.

• Codex를 지원하는 ChatGPT 요금제. 작성 시점의 요금 페이지 기준으로 CLI 접근은 Plus 이상(Plus, Pro, Business, Enterprise)이거나 API 키를 통한 종량제가 가장 확실해요. Free/Go에는 포함되지 않을 수 있으니, 추측하지 말고 설치 전에 Codex 요금을 확인하세요.
• OS: Windows, macOS, Linux 중 하나예요. Codex CLI는 세 가지 모두에서 네이티브로 실행되고, Windows에서도 WSL2가 필요 없으며, Apple Silicon과 Intel용 빌드를 따로 고민할 필요도 없어요(설치 프로그램이 알맞은 바이너리를 골라줘요).
• chatgpt.com에 대한 정상적인 연결. 설치 프로그램을 받고 로그인하는 데 필요해요. 나머지 인터넷은 멀쩡히 되더라도, 회사의 캡티브 프록시나 통제가 심한 네트워크에서는 다운로드가 막힐 수 있어요.
• Node.js는 npm 설치 방식을 고를 때만 필요해요. 다른 두 방법(설치 스크립트, Homebrew)은 Node를 전혀 건드리지 않아요.

이 네 가지만 갖추면 실제 설치는 명령어 하나와 짧은 다운로드 대기뿐이에요. 보통 더 오래 걸리는 부분은 로그인에 쓸 올바른 ChatGPT 계정을 고르는 일인데, 특히 개인 계정과 회사에서 발급한 계정(Business/워크스페이스)을 둘 다 가지고 있다면 그래요. 이 둘은 서로 다른 CLI 권한을 가질 수 있으니, 로그인 화면이 낯설거나 CLI가 예상과 다른 요금제를 표시한다면, 뭔가 고장 났다고 단정하기 전에 실제로 어떤 계정으로 인증됐는지 확인하세요.

macOS와 Linux에 Codex CLI 설치하기

가장 빠른 방법은 공식 설치 스크립트로, 터미널에서 바로 실행해요. 네이티브 바이너리를 내려받을 뿐 다른 런타임은 필요 없어요.

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

curl을 곧바로 sh로 파이프하는 걸 꺼림칙해하는 사람도 있는데, 그 본능은 대체로 합리적이에요. 그 순간 URL이 돌려주는 내용을 그대로 신뢰하는 셈이니까요. 읽지 않은 스크립트를 무작정 실행하기 싫다면, 먼저 내려받아서(curl -fsSL https://chatgpt.com/codex/install.sh -o install.sh) 내용을 읽은 뒤 sh install.sh를 실행하세요. 잘 알려진 벤더의 공식 도메인에서 한 번만 설치하는 경우라면 대부분의 개발자는 이 위험을 감수해요. 통제가 심하거나 공용으로 쓰는 컴퓨터라면, 내려받아서 읽는 단계에 1분 더 들일 가치가 있어요.

패키지 매니저로 관리하고 싶다면 두 가지 대안이 있어요.

brew install --cask codex

npm install -g @openai/codex

가장 흔한 함정: npm 패키지 이름은 그냥 codex가 아니라 @openai/codex예요. npm install -g codex를 실행하면 엉뚱한 패키지가 설치되거나 404가 나요. 제가 읽은 영어 가이드 중 두 곳이 바로 이 실수를 짚고 있어요. npm 방식으로 간다면 최신 Node.js LTS 릴리스를 쓰세요. 제가 대조한 이차 자료들은 최소 버전에 대해 의견이 갈리니, npm이 버전 오류를 낸다면 먼저 Node를 최신 LTS로 업데이트하거나, 위의 설치 스크립트나 Homebrew로 이 문제 자체를 피하세요. 다시 확인하고 싶다면 GitHub의 공식 README를 참고하세요.

어떤 걸 골라야 할까요? 한 번만 설치하고 수동 업데이트에 신경 쓰지 않는다면 설치 스크립트가 가장 빨라요. 이미 다른 모든 CLI를 Homebrew로 관리하고 있다면 그 습관을 이어가세요(나중에 brew upgrade하면 Codex도 함께 업데이트돼요). npm 방식은 이미 다른 용도로 Node.js를 설치해 둔 경우에만 의미가 있어요. 이 방식만을 위해 Node를 설치하진 마세요.

Windows에 Codex CLI 설치하기

Windows에서는 PowerShell을 열고 다음 명령어를 그대로 실행하세요. 저는 이 글을 쓰면서 제 Windows 컴퓨터에서 직접 실행했어요.

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

1. PowerShell을 엽니다(대부분의 컴퓨터에서 관리자 권한은 필요 없어요).
2. 위 명령어 전체를 붙여 넣고 Enter를 누르세요.
3. -ExecutionPolicy ByPass 플래그는 이 한 번의 실행에만 적용되며 컴퓨터의 정책을 바꾸지 않아요. 서명되지 않은 이 설치 스크립트를 이번 한 번만 실행할 수 있게 해줄 뿐이에요.
4. 기존 터미널을 닫고 새 터미널을 열어 업데이트된 PATH가 적용되게 하세요.
5. codex --version을 실행해 확인하세요.

Windows Terminal이 설치돼 있다면 예전 cmd.exe 창보다 Windows Terminal을 권해요. 필수는 아니지만 PowerShell 프롬프트와 Codex가 출력하는 색상이 더 안정적으로 표시되고, 위의 실제 실행에서도 제가 이걸 썼어요.

Codex CLI는 Windows에서 네이티브로 실행되고 WSL2는 필요 없어요. 팀이 이미 WSL2를 표준으로 삼았다면(예: Linux CI 파이프라인과 스크립트를 공유하려고), 위 macOS/Linux 섹션과 같은 curl 명령어로 WSL2 안에 Codex를 설치할 수도 있어요. Windows 전용 WSL2 명령어가 따로 있는 건 아니에요.

Windows 컴퓨터가 회사 관리 대상(그룹 정책 적용 기기)이라면, -ExecutionPolicy ByPass는 사용자 계층뿐 아니라 조직 정책 계층에서도 막힐 수 있어요. 그런 경우엔 IT 부서가 정책을 완화해 줘야 하고 사용자 쪽 우회 방법은 없어요. 또 갓 내려받은 설치 프로그램을 처음 실행할 때 Windows Defender SmartScreen이 확인을 요청할 수 있어요. 이건 새 파일에 대한 일반적인 경고일 뿐, 뭔가 고장 났다는 신호가 아니에요.

설치 확인하기

codex --version을 실행하세요. 버전 번호가 표시되면 끝난 거예요. 터미널이 codex를 인식하지 못한다고 하면 거의 항상 PATH가 오래됐기 때문이에요. 다른 걸 의심하기 전에 먼저 터미널(IDE 내장 터미널 포함)을 완전히 닫고 새 창을 여세요. 설치 방법을 두 가지 이상 시도했고(예: npm 다음에 설치 스크립트) codex --version이 예상과 다른 버전을 표시한다면, PATH에 사본이 두 개 있을 가능성이 높아요. where codex(Windows) 또는 which codex(macOS/Linux)로 실제로 어느 것이 실행되는지 확인한 뒤 여분을 제거하세요.

Codex에 로그인하기

터미널에서 codex를 실행해 CLI를 띄운 다음, 안내가 나오면 ChatGPT 로그인 옵션을 고르세요(화면의 정확한 문구는 릴리스마다 달라질 수 있으니 그때 CLI가 보여주는 대로 따르세요). 보통은 브라우저 탭이 열려 로그인을 확인한 뒤 세션이 자동으로 터미널로 돌아와요. 토큰을 수동으로 붙여 넣을 필요는 없어요. 사용할 수 있는 모델과 사용 한도는 ChatGPT 요금제가 결정해요. 여기서 숫자를 추측하지 말고 요금제별 Codex 요금에서 구체적인 내용을 확인하세요. 로그인이 조용히 실패한다면(브라우저 탭은 닫히는데 터미널이 확인을 못 받는 경우), 가장 흔한 원인은 회사 SSO나 프록시 계층이 리디렉션을 가로채는 거예요. CLI 자체가 고장 났다고 단정하기 전에 제한 없는 네트워크에서 다시 시도하세요.

첫 Codex 명령 실행하기

실제 프로젝트 폴더로 cd 한 다음(빈 폴더 말고요—Codex에는 읽고 다룰 실제 코드가 필요해요) 다음을 실행하세요.

codex

구체적인 걸 시켜 보세요. 예를 들면 "README를 읽고 이 저장소에서 테스트를 실행하는 방법 3가지를 알려줘." 아니면 몸풀기로 더 작은 것도 좋아요. "이 저장소에서 줄 수 기준으로 가장 큰 파일 5개를 알려줘." Codex가 명령을 실행하거나 파일을 편집해야 하면, 먼저 멈춰서 승인을 요청하고(approval_policy 설정에 따라) 실행하려는 정확한 명령이나 diff를 보여줘서 승인하거나 거부할 수 있게 해요. 이건 오류가 아니라 정상적인 승인 흐름이에요. 왜 멈추는지, 그리고 이를 느슨하게 하거나 엄격하게 하는 방법은 아래 설정 섹션에서 설명해요. 첫 실행이 잘 되면 보통 Codex는 읽거나 변경한 내용의 짧은 요약과 다음 단계 제안을 출력하며 끝나요. 반대로 아무것도 하기 전에 곧바로 오류가 난다면, 거의 항상 이 단계가 아니라 위의 로그인 단계에 원인이 있어요.

~/.codex/config.toml 기본

사용자 설정은 ~/.codex/config.toml에 있고, 프로젝트는 저장소 루트의 .codex/config.toml로 이를 덮어쓸 수 있어요. 우선순위(높은 것부터 낮은 것까지, 공식 설정 문서 기준)는 다음과 같아요. CLI 플래그 > 프로젝트 .codex/config.toml > 프로파일(--profile) > 사용자 ~/.codex/config.toml. 실제로는 이런 뜻이에요. 개인 ~/.codex/config.toml이 합리적인 전역 기본값으로 approval_policy = "on-request"를 설정해 두더라도, 특정 저장소의 .codex/config.toml이 더 엄격한 워크플로를 위해 approval_policy = "untrusted"를 설정하면, 그 저장소 안에서 작업하는 동안에는 프로젝트 파일이 이겨요. 그리고 일회성 --approval-policy CLI 플래그는 한 번의 실행에 한해 둘 다를 이겨요.

이 세 가지가 가장 먼저 조정해 볼 만해요. model은 품질·속도·비용을 저울질하고, sandbox_mode는 Codex가 실제로 무엇을 건드릴 수 있는지 정하며(더 안전한 read-only 옵션과, 기본값으로 실행하면 안 되는 danger-full-access 옵션도 있어요), approval_policy는 수동 승인을 얼마나 자주 해야 하는지 정해요. 세 가지를 모두 하나의 ~/.codex/config.toml에 넣으면 이렇게 돼요.

model = "gpt-5.6"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

이건 기본 계층일 뿐이에요. 다음 계층—Codex에 프로젝트만의 관례(테스트/빌드 명령, 절대 깨지면 안 되는 규칙)를 가르치는 것—은 Codex용 AGENTS.md에 있어요.

흔한 설치 오류와 해결법

대부분의 설치 문제는 네 가지 중 하나로 귀결돼요. 패키지 이름 오타, 오래된 PATH, Windows의 기본 스크립트 정책, 그리고 Codex가 권한을 깔끔하게 해결하지 못하는 폴더예요. 아래에 "재설치하고 기도하기" 식의 일반론이 아니라 각각의 실제 해결법을 정리했어요.

참고: 비슷하지만 다른 두 가지 「curl ... | sh」 설치 명령

나중에 curl -fsSL https://agentkit.best/install.sh | sh 같은 안내를 만나더라도, 그건 완전히 다른 도구예요—AgentKit(ak CLI)으로, Codex나 Claude Code 위에 설치하는 유료 키트이며 Codex 자체의 일부가 아니에요. 두 명령은 거의 똑같아 보이니까(같은 curl -fsSL <domain>/install.sh | sh 형태), 둘 중 하나를 메모나 셸 히스토리에 저장해 나중에 쓸 거라면 도메인으로 라벨을 달아 두세요. 한 스크립트를 다른 것으로 착각해 복사·붙여넣기 하지 마세요.

일찍 들여 둘 만한 습관이 하나 더 있어요. Codex CLI는 빠르게 배포되고, 설치 도메인도 일부 CLI 플래그도 출시 이후 이미 한 번씩 바뀌었어요. 이따금 설치 명령(또는 사용한 방법의 업데이트 경로)을 다시 실행해 두는 건, 자기도 모르게 오래된 빌드를 계속 쓰지 않기 위한 값싼 보험이에요.

자주 묻는 질문

Codex CLI는 무료로 설치할 수 있나요?

CLI 자체는 오픈 소스이고 무료로 설치할 수 있으며, 바이너리가 만료되거나 성가시게 재촉하지도 않아요. 로그인해서 실제로 쓰려면 Codex를 지원하는 ChatGPT 요금제(작성 시점 요금 페이지 기준 Plus 이상이 가장 확실해요)나 사용량 기반으로 청구되는 API 키가 필요해요.

API 키가 필요한가요?

Codex를 지원하는 ChatGPT 요금제로 로그인한다면 필요 없어요—대부분의 개인 개발자에게는 그게 기본 경로예요. API 키는 ChatGPT 요금제 대신 토큰 단위로 결제하고 싶을 때만 필요해요(대화형 로그인이 현실적이지 않은 자동화/CI에 유용해요).

Node.js 없이 설치할 수 있나요?

네. 공식 설치 스크립트(macOS/Linux에서는 curl ... | sh, Windows에서는 PowerShell)와 Homebrew는 Node.js가 전혀 필요 없어요. Node가 필요한 건 npm install -g @openai/codex 방식뿐인데, npm 자체가 Node.js와 함께 제공되기 때문이에요.

Windows에서 WSL이 필요한가요?

아니요. Codex CLI는 자체 설치 프로그램과 자체 바이너리로 Windows에서 네이티브로 실행돼요. WSL2는 기존 Linux 파이프라인이나 셸 스크립트를 팀과 공유하고 싶을 때만 쓸모가 있어요.

어떻게 업데이트하나요?

처음에 쓴 것과 같은 설치 방법(설치 스크립트, brew upgrade, 또는 npm install -g @openai/codex)을 다시 실행하면 기존 버전을 최신 버전으로 덮어써요—먼저 따로 제거하는 단계는 필요 없어요.

Codex를 설치한 뒤 AgentKit을 추가할까요?

Codex CLI 자체는 무료예요(이미 가진 ChatGPT 요금제에 얹혀 가요). AgentKit은 직접 조립하는 대신 미리 만들어진 skill/subagent/워크플로를 얻기 위해 Codex 위에 설치하는 별도의 유료 계층이에요. ak kit init engineer --target codex --global을 실행하고, 미리보기 화면을 확인한 뒤, 새 Codex 세션을 열고 $ak:cook ...을 실행해 시작하세요. 이렇게 해도 방금 설치한 기본 codex 명령 자체는 아무것도 바뀌지 않아요—그 명령에 대해 실행할, 더 구조화된 것들을 줄 뿐이에요. 이건 일회성 홍보가 아니라, 제가 Claude Code와 Codex 양쪽에서 실제로 돌리는 것과 같은 게이트 설정이에요—그 원리는 AgentKit in Codex에서 다뤄요. 오늘은 그저 Codex를 살짝 맛보는 정도라면 이 단계는 통째로 건너뛰고, 매 세션 자신의 워크플로를 다시 설명하는 번거로움을 실제로 느끼게 되면 그때 돌아오세요. 바로 그 지점이 미리 만들어진 키트가 값을 하기 시작하는 순간이에요.