Codex CLI 초기 세팅 가이드

OpenAI에서 제공하는 Codex CLI를 설치하고 초기 세팅을 하는 방법을 정리해보려고 한다. Codex CLI는 터미널에서 자연어로 AI에게 요청을 보내고, 코드 수정이나 실행까지 바로 연결할 수 있도록 도와주는 도구다. GitHub Copilot처럼 에디터 안에서만 쓰는 게 아니라, CLI 환경에서 프로젝트 단위로 활용할 수 있다는 점이 특징이다.

 

1. 설치

먼저 NPM을 통해 패키지를 설치한다. 전역 설치를 권장한다.

npm install -g @openai/codex

설치 후 버전을 확인한다.

codex --version

정상적으로 설치됐다면 버전 정보가 출력된다.

 

2. 인증 (Authentication)

Codex CLI를 처음 실행하면 인증이 필요하다. 두 가지 방식이 있다.

1. ChatGPT 계정 로그인
   • 터미널에서 codex 명령을 실행하면 브라우저가 열리면서 로그인 화면이 나온다.
   • Plus나 Pro 계정이 있다면 해당 권한으로 Codex를 사용할 수 있다.
2. API Key 환경 변수 설정
   • OpenAI API 키를 발급받아 환경 변수로 등록한다.

   export OPENAI_API_KEY="sk-발급받은-키"
   

   • .bashrc 또는 .zshrc에 추가해두면 매번 입력할 필요가 없다.

 

3. 실행 모드

Codex CLI는 기본적으로 인터랙티브 모드로 동작한다.
터미널에서 아래와 같이 실행한다.

codex

또는 한 줄짜리 프롬프트를 곧바로 입력할 수도 있다.

codex "이 함수에서 NullPointerException이 나는 원인을 찾아줘"

 

4. 승인 모드 (Approval Mode)

Codex는 프로젝트의 파일을 읽거나 수정하거나 명령을 실행할 수 있다. 이때 어느 정도 권한을 줄 것인지 선택해야 한다.

• auto (기본값)
  현재 디렉토리 내 파일 읽기, 수정, 명령 실행은 자동으로 수행된다.
• read-only
  코드베이스를 읽을 수만 있고, 수정이나 실행은 승인해야 한다.
• full-access
  디렉토리 안팎의 파일 읽기, 수정, 실행까지 전부 자동으로 허용한다. (주의 필요)

예시:

codex --approval-mode read-only "이 코드 리팩토링 해줘"

 

 

5. 옵션 활용

• 특정 모델 지정
• codex --model o4-mini "이 코드를 Java로 변환해줘"
• 이미지 프롬프트 입력
• codex --image error.png "이 에러 메시지를 설명해줘"
• 비대화형 실행
• codex exec "lint 에러 수정해줘"

 

여기까지 Codex CLI를 설치하고 초기 세팅을 마치는 방법을 살펴봤다.

정리하면 다음 순서다.

1. npm install -g @openai/codex 설치
2. 로그인 또는 API 키 설정
3. codex 실행 후 프롬프트 입력
4. 필요에 따라 승인 모드와 옵션 지정

이제 프로젝트 폴더에서 바로 AI에게 “이 버그 고쳐줘”라고 요청할 수 있다. 단순히 코드 작성 보조를 넘어서, 실제 작업 맥락 속에서 AI를 불러와 활용할 수 있다는 점이 Codex CLI의 매력이라고 할 수 있다.