WSL에 OpenAI Codex CLI 설치하기

OpenAI Codex CLI는 터미널에서 동작하는 AI 코딩 도구입니다. 윈도우만 써왔다면 “터미널에 설치”라는 말부터 낯설 수 있는데, WSL(우분투) 리눅스 터미널을 마련해 두면 설치 흐름이 한결 깔끔해집니다.

이 글에서는 WSL 환경을 기준으로, 실제 설치 명령어를 그대로 따라 칠 수 있게 순서대로 정리했습니다. 도구는 자주 갱신되므로, 가장 정확한 기준은 글 아래 출처에 적은 공식 문서임을 먼저 밝혀 둡니다.

Codex CLI가 어떤 도구인가

Codex CLI는 작업하려는 폴더 안에서 명령을 입력해, 대화하듯 코드를 읽고·고치고·실행하는 도구입니다. 그래픽 앱처럼 창을 띄우는 대신 터미널에서 동작하기 때문에, 설치도 일반 프로그램보다는 개발 도구를 설치하는 흐름에 가깝습니다.

같은 계열의 다른 도구를 먼저 설치해 본 적이 있다면 흐름이 거의 비슷합니다. (참고: Claude Code 처음 설치하고 실행해보기)

설치 전에 갖춰야 할 것

• WSL(우분투) 터미널 — 윈도우라면 먼저 WSL로 리눅스 터미널을 마련해 둡니다. 아직 WSL이 없다면 WSL2 설치 글을 먼저 보고 오면 됩니다.
• (npm 설치를 택할 경우) Node.js와 npm — npm으로 설치하려면 Node.js 환경이 먼저 필요합니다. 버전을 깔끔하게 관리하려면 Node.js 버전 매니저로 들이는 편이 이후가 편합니다. 아래의 curl 설치 스크립트를 쓰면 Node 없이도 설치할 수 있으니, Node가 없다면 그쪽을 택해도 됩니다.

WSL 터미널을 열었다면, Node가 이미 있는지 한 번 확인해 봅니다.

node -v
npm -v

버전 숫자가 출력되면 npm 설치 방법을 바로 쓸 수 있고, “command not found”가 나오면 Node가 아직 없는 상태이니 curl 설치 스크립트를 쓰거나 Node부터 설치하면 됩니다.

설치 방법

설치 방법은 두 가지입니다. 둘 중 하나만 따라 하면 됩니다.

방법 A — npm으로 설치 (Node.js가 있을 때)

이미 Node.js·npm을 쓰고 있다면, 패키지 매니저로 한 줄에 설치합니다.

npm install -g @openai/codex

-g는 시스템 어디서나 codex 명령을 쓸 수 있게 전역(global)으로 설치하라는 뜻입니다.

방법 B — 공식 설치 스크립트로 설치 (Node 없이)

Node를 따로 설치하고 싶지 않다면, OpenAI가 제공하는 설치 스크립트를 쓰는 방법이 간단합니다. WSL(리눅스)에서는 다음 명령을 사용합니다.

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

참고로 macOS에서는 brew install --cask codex(Homebrew)도 가능하고, 윈도우 PowerShell에서 바로 설치하는 방법도 따로 있습니다. 이 글은 WSL 기준이므로 위 두 방법을 권장합니다.

설치가 됐는지 확인

설치가 끝났으면 버전을 출력해 정상 설치를 확인합니다.

codex --version

버전 숫자가 나오면 설치가 끝난 것입니다. 만약 “command not found”가 나온다면 터미널을 새로 열거나, 설치 경로(PATH) 설정을 점검해 보세요.

작업 폴더로 이동해서 실행

설치가 끝났다면 아무 곳에서나 실행하지 말고, 작업하려는 프로젝트 폴더 안으로 먼저 이동한 뒤 실행합니다. Codex는 “지금 위치한 폴더”를 작업 대상으로 삼기 때문에, 어디서 실행하느냐가 곧 어떤 파일을 다루게 되느냐로 이어집니다.

cd ~/projects/my-app
codex

codex를 실행하면 터미널 안에서 대화형 화면이 열립니다.

첫 실행 — 로그인(인증)

처음 codex를 실행하면 로그인 절차를 거칩니다. 화면 안내에서 “Sign in with ChatGPT”(ChatGPT 계정으로 로그인) 를 선택하면 브라우저를 통해 계정과 연결됩니다. ChatGPT 계정 대신 API 키로 인증하는 방법도 있는데, 이 경우 키 발급 등 추가 설정이 필요합니다.

한 번 로그인해 두면 이후에는 매번 로그인하지 않아도 되는 경우가 많지만, 구체적인 방식·유효 기간은 환경과 버전에 따라 다를 수 있으니 화면 안내를 그대로 따르는 것이 정확합니다.

초보자가 자주 막히는 부분

• WSL 준비를 건너뜀 — 윈도우에서 리눅스 명령(curl, npm)을 바로 치려다 막히는 경우가 많습니다. 먼저 WSL 터미널을 열고 그 안에서 실행하세요.
• 방법 A·B를 둘 다 실행 — 두 방법은 택일입니다. 하나로 설치한 뒤 codex --version으로 확인하면 됩니다.
• command not found — 설치 직후 명령이 안 잡히면 터미널을 새로 열거나 PATH 설정을 점검합니다.
• 엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더 안에서 실행해야 의도한 파일을 다룹니다.
• 명령을 오래된 글에서 베껴 옴 — 패키지명·옵션은 바뀔 수 있습니다. 항상 공식 문서의 최신 안내를 우선하세요.

출처

이 글의 설치 명령은 아래 공식 자료를 기준으로 작성했습니다. 도구는 자주 갱신되므로, 실제 설치 전에 최신 안내를 한 번 더 확인하시길 권합니다.

• OpenAI Codex CLI 공식 문서 (developers.openai.com)
• openai/codex — GitHub 저장소
• @openai/codex — npm 패키지

정리

WSL에서 Codex를 설치하는 핵심은 리눅스 터미널을 먼저 마련하고, npm이나 공식 설치 스크립트 중 하나로 설치한 뒤, 작업 폴더에서 실행해 로그인하는 흐름입니다. 버전과 환경에 따라 세부는 달라질 수 있으니, 명령은 위 공식 문서를 기준으로 확인하세요. 설치를 마쳤다면, 도구를 더 잘 활용하기 위한 기본기를 함께 점검해 두면 도움이 됩니다.