첫 30분 온보딩: 설치, 로그인, 첫 작업 실행

Codex CLI는 터미널에서 돌아가는 로컬 코딩 에이전트입니다. 선택한 디렉터리 안에서 파일을 읽고, 수정하고, 명령을 실행하며, 세션을 로컬에 저장해 다시 이어갈 수 있습니다.¹² 이 챕터의 목표는 단 하나입니다. 설치와 인증만 끝내고, 오늘 바로 '설명→수정→테스트→diff' 루프를 한 번 완주하는 것입니다.

0) 30분 온보딩 로드맵

처음이라면, 아래 순서대로 진행하는 것이 가장 빠릅니다.

1. (0~10분) Codex CLI 설치 및 버전 확인

2. (10~20분) 로그인(ChatGPT 계정 또는 API 키)

3. (20~30분) 첫 작업 실행: "설명→수정→테스트→diff"

중간에 막히면, 이 챕터 마지막의 "자주 막히는 지점"만 확인해도 대부분 해결됩니다.

1) 설치: npm / Homebrew / 바이너리 중 무엇을 선택할까

Codex CLI는 npm, Homebrew(cask), GitHub 릴리스 바이너리로 설치할 수 있습니다.¹²³⁵ 어떤 방식을 고르든 최종 목표는 단순합니다. codex 실행 파일이 PATH에 잡히고 codex --version이 동작하면 끝입니다.

• 이미 Node.js 기반 도구를 자주 쓰면 npm 전역 설치가 가장 범용적입니다.²

• macOS에서 패키지 관리를 Homebrew로 통일했다면 brew cask가 편합니다.⁵

• 서버/컨테이너처럼 Node.js 설치를 피하고 싶다면 릴리스 바이너리가 깔끔합니다(리눅스는 musl 타깃 바이너리가 제공됩니다).³

2) 설치 방법 1 — npm(권장, 가장 범용)

2.1 Node.js 버전 확인

npm 설치는 Node.js가 필요합니다. Codex CLI는 npm 패키지로 배포되며 다음 명령으로 전역 설치합니다.⁴

node --version
npm --version

2.2 설치

npm install -g @openai/codex

설치 후 버전을 확인합니다.

codex --version

팁: 전역 설치 권한 문제로 막히면, sudo npm install -g로 우회하기보다 nvm 같은 버전 매니저를 쓰는 편이 안전합니다(권한 꼬임을 줄입니다).⁷

3) 설치 방법 2 — Homebrew(cask)

macOS(또는 Homebrew를 쓰는 환경)에서는 다음처럼 설치할 수 있습니다.⁵

brew install --cask codex
codex --version

참고: Homebrew의 의존성 구성은 버전에 따라 달라질 수 있습니다. 설치 후 문제가 있으면 brew info codex로 실제 설치 내용을 확인하는 편이 가장 빠릅니다.

4) 설치 방법 3 — GitHub 릴리스 바이너리(서버/컨테이너에 추천)

최신 릴리스에서 OS/아키텍처에 맞는 압축 파일을 내려받아, 압축을 풀고 실행 파일 이름을 codex로 맞춘 뒤 PATH에 둡니다.³

예: Linux x86_64

curl -fsSL https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz -o codex.tar.gz

tar -xzf codex.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex
rm codex.tar.gz

codex --version

macOS도 같은 방식이며, Apple Silicon은 codex-aarch64-apple-darwin.tar.gz를 선택합니다.³

팁: 릴리스 아카이브에는 플랫폼명이 포함된 단일 실행 파일이 들어 있습니다. 압축 해제 후 codex로 리네임하는 것이 일반적인 사용 흐름입니다.³

5) 로그인(인증): ChatGPT 계정 vs API 키

Codex CLI는 크게 두 가지 인증 방식을 지원합니다.⁴

• ChatGPT 계정 로그인: ChatGPT 플랜(예: Plus/Pro/Team/Edu/Enterprise) 범위에서 Codex를 쓰는 가장 쉬운 시작점입니다.³⁶

• OpenAI API 키: CI/CD나 헤드리스 환경처럼 "계정 로그인"이 번거로운 자동화에 유리합니다(사용량 기반 과금).⁴

또 한 가지 실무 포인트가 있습니다. 한 번 로그인한 뒤에는 같은 머신에서 인증 정보가 재사용되는 경우가 많습니다. 다만 정확한 저장 위치/공유 범위는 OS와 버전에 따라 바뀔 수 있으니, 팀에 배포할 때는 항상 최신 문서를 기준으로 확인하세요.⁴

5.1 ChatGPT 계정 로그인(가장 쉬운 시작)

프로젝트 디렉터리로 이동해 codex를 실행합니다.

cd /path/to/your-repo
codex

처음 실행 시 인증 방법을 고르게 되는데, "Sign in with ChatGPT"를 선택하면 브라우저에서 로그인/권한 부여를 진행한 뒤 터미널로 돌아오며 인증이 완료됩니다.³⁴

인증을 다시 하거나 계정을 바꾸고 싶다면 다음을 사용합니다.

codex login
codex logout

5.2 API 키 로그인(자동화·서버에 적합)

API 키는 가능한 한 셸 히스토리나 프로세스 목록에 노출되지 않게 다루는 것이 좋습니다. 문서에서는 표준입력으로 넘기는 패턴을 안내합니다.⁴

printenv OPENAI_API_KEY | codex login --with-api-key

또는 파일에서 읽을 수도 있습니다.⁴

codex login --with-api-key < my_key.txt

5.3 원격/헤드리스(SSH, 서버, 컨테이너)에서 ChatGPT 로그인하기

원격 환경에서는 브라우저 기반 로그인 흐름이 막히는 경우가 흔합니다. 이때는 보통 아래 중 하나로 해결합니다.

• 로컬에서 먼저 로그인한 뒤 인증 파일을 복사해 원격에 배치

• SSH 포트 포워딩으로 루프백 콜백을 터널링

다만 세부 동작(예: 어떤 포트/경로를 쓰는지, 파일이 '호스트에 종속되는지')은 CLI 버전과 실행 환경에 따라 달라질 수 있습니다. 팀 표준을 만들기 전에는 최신 공식 문서를 기준으로 확인해 주세요.⁴

6) 첫 실행: '설명→수정→테스트→diff' 루프 완주하기

설치와 인증이 끝났다면, 이제 "오늘 당장 도움이 되는" 기본 루프를 한 번만 돌려보면 됩니다. Codex CLI의 핵심은 결과 코드 한 덩어리를 받아 붙여 넣는 것이 아니라, 레포 안에서 계획하고 변경하고 검증하고, diff로 확인하는 흐름을 터미널에서 끝내는 데 있습니다.¹²

6.1 준비: 안전한 작업 공간 만들기

처음에는 실수해도 되돌리기 쉬운 형태로 시작하는 게 좋습니다.

cd /path/to/your-repo

git checkout -b codex-onboarding

6.2 1단계 — "설명(Explain)" 시키기

Codex를 띄우고, 가장 먼저 레포를 설명하게 합니다.

codex "이 프로젝트 구조를 설명하고, 테스트 실행 방법과 엔트리 포인트를 찾아줘"

설명이 만족스럽지 않으면, "어떤 파일을 근거로 말하는지"를 더 요구하세요. 예를 들어 "package.json 스크립트와 README 기준으로" 같은 조건을 붙이면 좋습니다.

6.3 2단계 — "수정(Fix/Change)" 시키기

다음은 아주 작은 작업을 시킵니다. 예컨대 린트/타입 오류 하나를 고치거나, 로그 메시지를 정리하거나, 함수명을 통일하는 정도가 좋습니다.

codex "테스트 실행이 실패하면, 실패 원인을 찾아 최소 변경으로 고치고 관련 테스트도 업데이트해줘"

Codex는 로컬 파일을 읽고 수정할 수 있으며, 터미널 명령 실행도 워크플로에 포함시킬 수 있습니다.¹

6.4 3단계 — "테스트(Test)" 돌리고 실패를 다시 고치기

테스트 커맨드가 무엇인지 모르겠다면, Codex에게 먼저 찾아오게 하거나, 직접 npm test, pnpm test, pytest처럼 익숙한 후보를 제시해도 됩니다.

중요한 건, 테스트가 실패하면 그 실패 로그를 근거로 "다시 수정"으로 되돌아가 한 번 더 돌리는 것입니다. 이 반복이 곧 Codex의 생산성이 체감되는 지점입니다.

6.5 4단계 — "diff(Diff)"로 바뀐 점을 눈으로 확인하기

Codex가 만든 변경은 마지막에 항상 사람 손으로 확인해야 합니다.

git status

git diff

이 시점에서 다음 중 하나를 선택합니다.

• 변경이 타당하면 커밋

• 일부만 좋다면 수동 수정 후 커밋

• 방향이 틀렸다면 브랜치를 버리고 다시 시작

Codex가 "뭐가 바뀌었는지" 정리해달라고 요청하는 것도 도움이 됩니다.

codex "방금 변경한 diff를 요약하고, 잠재적 리스크가 있는 부분을 체크리스트로 알려줘"

7) 설치/로그인 직후에 알아두면 좋은 사실 3가지

7.1 Codex CLI는 오픈소스이며 로컬에서 동작한다

Codex CLI는 로컬 머신에서 실행되는 코딩 에이전트로, 선택한 디렉터리 안에서 파일을 읽고 수정하고 명령을 실행합니다.¹³ 설치는 npm/brew/바이너리 중 어떤 방식이든 상관없고, 결과적으로 codex가 PATH에 잡히면 됩니다.

7.2 인증은 '같은 머신' 기준으로 재사용되는 경우가 많다

CLI에서 로그인해두면, 같은 머신에서 실행되는 IDE 확장/다른 터미널 세션에서도 인증이 재사용되는 경우가 많습니다.⁴ 다만 저장 위치나 공유 범위는 OS/버전에 따라 달라질 수 있으니, 조직 배포 시에는 최신 문서를 확인하세요.

7.3 원격 머신에서는 '로그인 경로'를 미리 설계하라

원격 개발 서버/컨테이너/WSL에서는 브라우저 기반 로그인 자체가 병목이 되기 쉽습니다. 그래서 실무에서는 보통

• 로컬에서 로그인 후 인증 파일을 복사하거나,

• SSH/IDE의 포트 포워딩 기능을 사용해 로그인 콜백을 연결

중 하나를 팀 규칙으로 정해두는 편이 운영 비용이 적습니다.⁴

8) 자주 막히는 지점(빠른 해결)

8.1 codex: command not found

npm 설치라면 전역 설치 경로가 PATH에 없는 경우가 많습니다. 우선 다음을 확인합니다.

npm bin -g
which codex

brew 설치라면 brew --prefix 아래 경로가 쉘 설정에 포함되어 있는지 확인하세요.

8.2 권한 문제로 npm 전역 설치가 실패한다

sudo로 억지 설치하기보다, nvm 같은 버전 매니저로 Node.js를 설치하거나 npm 전역 디렉터리를 사용자 홈으로 옮기는 것이 일반적으로 안전합니다.⁷

8.3 원격 서버에서 ChatGPT 로그인이 끝나지 않는다

브라우저가 열려도 "연결이 안 됨"이 뜬다면, 원격의 localhost:1455에 로컬 브라우저가 붙지 못하는 상황입니다. 로컬에서 ssh -L 1455:localhost:1455 ...로 포트 포워딩을 켠 뒤 다시 시도하세요.⁸

참고

¹Codex CLI (OpenAI Developers)

²@openai/codex (npm)

³openai/codex (GitHub) — README & Releases

⁴Authentication (OpenAI Developers)

⁵codex — Homebrew Cask

⁶Codex in ChatGPT (OpenAI Help Center)