터미널을 열기 전에 딱 두 가지만 준비하세요
Codex CLI 설치는 터미널에 명령어 한 줄을 넣으면 시작됩니다. 다만 설치가 끝났는데 `codex`가 안 잡히는 경우가 은근 많아요. 운영체제에 맞는 설치 방법을 고르고, 설치 뒤 새 터미널에서 첫 실행까지 확인해야 제대로 끝난 겁니다.
macOS나 Linux라면 공식 설치 스크립트를 쓸 수 있습니다. Node.js와 npm이 이미 익숙한 사람은 npm 전역 설치를 골라도 됩니다. 두 방법을 한꺼번에 실행할 필요는 없어요.
Windows에서는 환경 차이로 막히는 지점이 다를 수 있습니다. 현재 공식 안내에 표시된 Windows 설치 방법을 먼저 확인하고, 오래된 블로그의 명령을 그대로 섞어 쓰지 않는 편이 안전합니다.
설치 전에 프로젝트 파일을 백업하거나 Git 상태를 확인해두는 습관도 괜찮습니다. 설치 자체가 코드를 바꾸는 건 아니지만, 첫 요청부터 수정 작업을 맡길 생각이라면 되돌아갈 지점을 먼저 만드는 편이 마음이 놓여요.
잠깐 정리하면: 설치 방법 하나를 고른 뒤 `codex` 실행, 로그인, 프로젝트 폴더 확인까지 이어가세요. 명령어가 없다는 오류가 나오면 재설치보다 새 터미널과 PATH부터 보는 게 빠릅니다.
설치 명령은 어디서 갈릴까요
macOS와 Linux에서 독립 설치 스크립트를 쓰려면 터미널에 아래 명령을 입력합니다.
“`bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
“`
npm을 쓰고 있다면 아래 방식도 가능합니다.
“`bash
npm install -g @openai/codex
“`
Codex CLI 설치 방법은 둘 중 하나만 고르면 됩니다. 설치가 끝난 터미널에서 바로 인식되지 않으면 창을 닫고 새 터미널을 연 뒤 `codex`를 실행해보세요.
| 상황 | 먼저 고를 방법 | 확인할 것 |
|---|---|---|
| macOS·Linux, npm이 낯섦 | 공식 설치 스크립트 | 설치 뒤 새 터미널 |
| Node.js를 이미 사용함 | npm 전역 설치 | npm 전역 경로 |
| Windows에서 시작함 | 공식 Windows 안내 | 지원 방식과 셸 |
회사 컴퓨터라면 전역 프로그램 설치가 막혀 있을 수 있습니다. 이때 관리자 권한을 무작정 붙이기보다 사내 정책과 설치 가능한 경로부터 확인하세요.
Codex CLI 설치 기록에는 선택한 방식도 적어두세요. 나중에 업데이트할 때 독립 설치와 npm 명령을 섞지 않아도 됩니다.
여기서 막히면 PATH부터 봅니다
명령을 넣었는데 `command not found`와 비슷한 문구가 뜬다면 프로그램이 없는 경우와 터미널이 위치를 모르는 경우를 나눠야 합니다. Codex CLI 설치를 여러 번 반복해도 PATH가 잡히지 않으면 증상은 그대로예요.
먼저 터미널을 완전히 닫았다가 다시 엽니다. 그래도 같다면 설치 과정 끝부분에 나온 경로 안내를 확인하고, npm을 썼다면 npm 전역 실행 파일 위치가 현재 PATH에 포함됐는지 봅니다.
맥에서 셸 설정을 바꾼 적이 있다면 현재 쓰는 셸과 설정 파일이 맞는지도 확인하세요. 비밀번호나 토큰은 화면 캡처에 남기지 말고, 명령과 오류 문구만 기록해두면 원인을 찾기 편합니다.
이 단계에서 다른 오류까지 함께 보인다면 Codex 오류 해결 글의 로그인·권한·폴더·네트워크 순서로 나눠보세요. 설치 오류와 실행 권한 문제를 섞지 않는 게 중요합니다.
첫 실행, 로그인 화면부터 확인하세요
Codex CLI 설치가 끝났다면 작업할 프로젝트 폴더로 이동한 뒤 아래처럼 실행합니다.
“`bash
codex
“`
첫 실행에서는 제공되는 로그인 방법 가운데 하나를 선택합니다. ChatGPT 계정 로그인을 쓴다면 브라우저 인증을 마친 뒤 터미널로 돌아왔는지 확인하세요. 예전에 API 키를 사용했던 환경은 현재 로그인 상태가 남아 있을 수 있으니 계정이 예상과 다르면 로그아웃 후 다시 시작하는 편이 낫습니다.
로그인이 끝나면 거창한 작업부터 시킬 필요가 없습니다. `이 프로젝트 구조를 설명해줘`처럼 읽기 중심 요청으로 시작하면 현재 폴더를 제대로 보고 있는지 확인하기 좋아요.
요금이나 사용 한도가 헷갈리면 Codex 가격 글에서 ChatGPT 플랜과 별도 API 과금을 먼저 구분해보세요. 로그인 방식이 다르면 비용을 이해하는 기준도 달라집니다.
프로젝트 폴더가 왜 설치만큼 중요할까요
터미널에서 `codex`가 실행된다고 준비가 모두 끝난 건 아닙니다. Codex CLI 설치 뒤에는 실제 코드가 있는 폴더에서 시작해야 필요한 파일과 Git 상태를 제대로 읽을 수 있어요.
처음에는 현재 위치, 파일 목록, `git status`를 사람이 직접 확인해보세요. 빈 폴더나 프로젝트의 한 단계 위에서 실행하면 Codex가 엉뚱한 범위를 보게 됩니다.
권한을 넓게 열기 전에 읽기 중심 요청으로 범위를 확인하는 것도 좋습니다. 현재 세션 정보는 `/status`, 허용 범위는 `/permissions`처럼 화면에 제공되는 명령으로 확인할 수 있습니다. 메뉴는 업데이트될 수 있으니 보이지 않는 항목은 공식 CLI 문서에서 다시 확인하세요.
Codex와 Cursor 비교처럼 편집기 안에서 쓰는 방식과 터미널 방식은 작업 감각이 다릅니다. 파일을 직접 보며 수정하고 싶다면 IDE가 편하고, 명령과 저장소 흐름을 한곳에서 다루려면 CLI가 잘 맞습니다.
업데이트 전, 설치 때 쓴 방법부터 확인하세요
독립 설치 스크립트로 시작했다면 같은 공식 설치 명령을 다시 실행해 업데이트할 수 있습니다. npm으로 Codex CLI 설치를 했다면 npm 전역 설치 명령으로 최신 버전을 받으면 됩니다.
“`bash
npm install -g @openai/codex
“`
업데이트 뒤에는 열려 있던 터미널을 그대로 믿지 말고 새 창에서 실행 상태를 확인하세요. 설정이나 명령 이름은 바뀔 수 있으므로 오래된 화면과 현재 화면이 다르다고 바로 오류로 판단할 필요는 없습니다.
문제가 생겼을 때는 설치 방법, 운영체제, 실행한 셸, 오류 문구를 네 줄로 남겨두세요. 이 기록만 있어도 단순 경로 문제인지 로그인 문제인지 훨씬 빨리 가를 수 있습니다.
자주 막히는 질문만 짧게 풀어봅니다
Codex CLI 설치에 Node.js가 꼭 필요한가요?
macOS와 Linux의 공식 독립 설치 스크립트를 쓰면 npm 방식만 고집할 필요는 없습니다. 이미 Node.js 개발 환경을 쓰는 사람은 npm 전역 설치가 익숙할 수 있어요. 운영체제와 현재 도구에 맞는 방법 하나만 선택하세요.
팀에서 설치 방식을 통일해둔 경우에는 개인 취향보다 팀 기준을 따르는 편이 좋습니다. 문제가 생겼을 때 같은 명령과 경로를 기준으로 확인할 수 있고, 업데이트 방법도 서로 달라지지 않기 때문입니다.
설치 후 codex 명령을 찾지 못하면 다시 설치해야 하나요?
바로 다시 설치하지 마세요. 새 터미널을 열고 PATH와 npm 전역 실행 파일 경로를 먼저 확인합니다. 같은 설치 명령을 여러 번 실행하면 파일은 늘지 않아도 원인 기록이 흐려질 수 있습니다.
Codex CLI 설치 직후라면 터미널 재시작만으로 명령이 잡히는 경우도 있습니다. 그래도 안 되면 설치 로그에 표시된 경로부터 차분히 확인하세요.
오류 문구를 검색할 때는 운영체제와 설치 방식을 함께 적어보세요. macOS의 npm 경로 문제와 Windows의 실행 환경 문제는 해결 순서가 다를 수 있어서, `command not found` 한 줄만으로는 답이 너무 넓어집니다.
첫 요청은 무엇으로 시작하면 편한가요?
Codex CLI 설치 확인용으로는 코드 수정보다 `이 프로젝트 구조를 설명해줘` 같은 읽기 요청이 좋습니다. 폴더를 제대로 열었는지 확인한 뒤 작은 수정과 테스트로 범위를 넓히면 실수를 줄일 수 있어요.
첫 응답에서 프로젝트와 상관없는 설명이 나온다면 요청을 길게 고치기 전에 현재 폴더부터 다시 보세요. 파일 목록과 Git 상태를 확인한 뒤 작은 파일 하나를 설명하게 하면 읽는 범위가 맞는지 금방 알 수 있습니다.
설치가 끝났다면 오늘 확인할 네 칸
설치 명령이 끝났다면 바로 큰 작업을 맡기기보다 새 터미널에서 실행, 로그인 계정, 프로젝트 폴더를 차례로 확인해보세요. Codex CLI 설치는 프로그램을 내려받는 데서 끝나는 일이 아니라 첫 요청이 정확한 저장소를 읽는 순간까지가 한 묶음입니다.
오늘 확인할 것은 간단합니다. 설치 방법 하나, 새 터미널의 `codex` 실행, 로그인 계정, 현재 프로젝트 폴더를 순서대로 보세요. 막힌다면 오류 문구와 실행 위치를 남겨두면 다음 점검이 훨씬 쉬워집니다.
