Codex CLI 설치 방법

AI 코딩 도구를 떠올리면 보통 VS Code 같은 에디터 확장부터 생각하는 경우가 많습니다.
그런데 실제로 개발을 하다 보면, 에디터보다 터미널에서 바로 작업하는 흐름이 더 편한 순간이 꽤 많습니다.

예를 들어 이런 경우입니다.

• 원격 서버에 SSH로 접속해서 작업할 때
• 빠르게 프로젝트 구조를 훑고 싶을 때
• 테스트, 빌드, 실행 명령과 함께 AI 코딩 에이전트를 쓰고 싶을 때
• GUI보다 터미널 중심 개발 습관이 익숙할 때

이럴 때 잘 맞는 도구가 바로 Codex CLI입니다.
OpenAI 공식 문서에 따르면 Codex CLI는 터미널에서 로컬로 실행되는 코딩 에이전트이며, 현재 디렉터리의 코드를 읽고, 수정하고, 명령을 실행할 수 있습니다. 또한 오픈소스로 공개되어 있고 Rust 기반으로 만들어졌습니다.

이번 글에서는 다음 내용을 차근차근 설명하겠습니다.

• Codex CLI가 무엇인지
• 설치 전에 무엇을 준비해야 하는지
• npm과 Homebrew로 설치하는 방법
• Windows 사용자가 주의할 점
• 설치 후 첫 실행과 로그인 방법
• 처음 실행한 뒤 바로 해보면 좋은 예시

Reference: https://developers.openai.com/codex/cli

CLI – Codex | OpenAI Developers

 

---

1. Codex CLI란 무엇인가

Codex CLI는 터미널에서 직접 사용하는 OpenAI의 코딩 에이전트입니다.
공식 문서 기준으로 Codex CLI는 현재 작업 중인 디렉터리를 기준으로 프로젝트를 살펴보고, 파일을 수정하고, 명령을 실행할 수 있습니다. 쉽게 말해, 단순한 챗봇이 아니라 실제 개발 작업을 도와주는 터미널용 에이전트라고 보면 됩니다.

즉, 이런 식의 요청이 가능합니다.

• “이 프로젝트 구조를 설명해줘”
• “현재 디렉터리에서 버그를 찾아줘”
• “이 저장소에서 테스트 실패 원인을 분석해줘”
• “최소 수정으로 문제를 고쳐줘”

에디터 안에서 쓰는 IDE 확장과 비교하면, Codex CLI는 터미널과 셸 명령 중심의 작업 흐름에 더 잘 맞습니다. 그래서 연구용 서버, 리눅스 환경, 원격 개발, 반복 작업 자동화 쪽에서 특히 강점을 가집니다. 이 점은 Codex가 CLI, IDE, 앱 등 여러 인터페이스에서 공통으로 동작하되, CLI에서는 터미널 환경에 맞춰 활용하도록 설계된 공식 문서 구조에서도 확인할 수 있습니다.

2. 설치 전에 알아둘 것

• 어떤 운영체제에서 사용할 수 있나
  • 공식 문서상 Quickstart에는 Codex CLI가 macOS, Windows, Linux에서 지원된다고 안내되어 있습니다.
  • 다만 CLI 전용 페이지에서는 macOS와 Linux에서 사용 가능하고, Windows 지원은 실험적이라고 설명합니다.
  • 그래서 실제로는 Windows에서도 사용할 수 있지만, 안정성과 작업 경험을 고려하면 macOS 또는 Linux, 혹은 Windows + WSL 조합이 더 권장된다고 이해하는 것이 좋습니다.
• 로그인은 어떻게 하나
  • Codex CLI를 처음 실행하면 로그인 과정이 나오는데, ChatGPT 계정 또는 OpenAI API 키로 인증할 수 있습니다. 공식 Quickstart와 CLI 문서 모두 이 두 방식을 안내하고 있습니다.
  • 또한 Quickstart에는 모든 ChatGPT 플랜에 Codex가 포함된다고 나와 있고, API 키로도 사용할 수 있다고 설명합니다. 다만 API 키 로그인 시 일부 기능은 제한될 수 있다고 Codex 관련 문서에서 안내하고 있습니다.
• Node.js가 필요한가
  • npm으로 설치할 경우, 당연히 npm을 사용할 수 있는 환경이 먼저 필요합니다. 즉, Node.js가 설치되어 있어야 합니다. 설치 명령 자체가 npm 기반으로 제공되기 때문입니다.
  • 공식 CLI 문서는 npm 설치 명령을 제공하고, Quickstart는 npm 또는 Homebrew 설치 방식을 안내합니다.

3. Codex CLI 설치 방법

• Codex CLI는 공식 문서 기준으로 크게 두 가지 방식으로 설치할 수 있습니다.
  • npm 설치
  • Homebrew 설치
• Quickstart는 두 방식을 모두 공식적으로 안내합니다.

4. npm으로 설치하기

• 가장 보편적인 설치 방법은 npm을 사용하는 방식입니다.
• 터미널에서 아래 명령을 실행합니다.

npm install -g @openai/codex

• 공식 CLI 문서와 Quickstart 모두 이 명령을 설치 방법으로 안내합니다. CLI 전용 페이지에서는 npm i -g @openai/codex 형태로도 제시합니다. 두 명령은 같은 의미입니다.
  • npm install -g: 전역 설치
  • @openai/codex: Codex CLI 패키지
• 즉, 설치가 끝나면 특정 프로젝트 폴더 안이 아니라 시스템 전역에서 codex 명령을 실행할 수 있게 됩니다.
• 설치가 끝난 뒤 아래처럼 바로 실행해볼 수 있습니다.

codex

• 공식 문서에 따르면 이 명령을 실행하면 Codex가 터미널에서 시작되고, 처음 실행 시 로그인 과정을 안내합니다.

5. Homebrew로 설치하기

• macOS 사용자라면 Homebrew로 설치하는 것이 더 익숙할 수 있습니다. Quickstart 문서에는 Homebrew 설치 명령도 함께 제공됩니다.
• 설치 명령은 다음과 같습니다.

brew install codex

• 이 방식은 특히 아래와 같은 사용자에게 잘 맞습니다.
  • 평소 패키지 관리를 Homebrew로 하는 사람
  • macOS 환경에서 CLI 툴을 brew 중심으로 설치하는 사람
  • npm 전역 패키지 관리를 최소화하고 싶은 사람
• 즉, Node.js 생태계에 익숙하면 npm, macOS CLI 툴 관리를 brew로 통일하고 싶으면 Homebrew를 선택하면 됩니다. 공식적으로 둘 다 지원됩니다.

6. 설치 후 첫 실행

• 설치가 끝났다면 이제 아래 명령으로 Codex를 실행합니다.

codex

• 공식 문서에 따르면 Codex CLI는 이 명령으로 interactive terminal UI, 즉 대화형 터미널 세션을 시작합니다. 이후 처음 실행 시 로그인 화면이 뜨고, ChatGPT 계정 또는 API 키로 인증하게 됩니다.
• 인증이 끝나면 현재 디렉터리를 기준으로 Codex에게 작업을 시킬 수 있습니다. Quickstart는 “현재 디렉터리에서 Codex가 작업하도록 요청하라”고 설명하며, 예시로 다음과 같은 첫 메시지를 제시합니다.
  • Tell me about this project
  • Build a classic Snake game in this repo.
  • Find and fix bugs in my codebase with minimal, high-confidence changes.

7. Codex CLI로 할 수 있는 일은 생각보다 많다

• 설치만 해두고 단순 질의응답 도구처럼만 쓰면 Codex의 장점을 절반도 못 쓰는 셈입니다.
• 공식 CLI 문서에는 Codex CLI로 다음과 같은 작업이 가능하다고 나와 있습니다.
  • 대화형 TUI 세션 실행
  • 모델과 추론 수준 제어
  • 이미지 입력 첨부
  • 로컬 코드 리뷰
  • 서브에이전트 활용
  • 웹 검색
  • Codex Cloud 작업 실행
  • 스크립팅 자동화
  • MCP를 통한 추가 도구 연결
  • 승인 모드 선택
• 즉, Codex CLI는 단순히 “터미널용 챗봇”이 아닙니다.
• 조금 익숙해지면 코드 리뷰 도우미, 프로젝트 분석 도구, 반복 작업 자동화 보조, 외부 도구와 연결되는 에이전트처럼 쓸 수 있습니다.

8. 더 잘 쓰고 싶다면 AGENTS.md와 반복 작업 습관을 익히자

• 공식 Best Practices 문서는 Codex를 일회성 질문 도구처럼 쓰기보다, 팀원처럼 설정하고 개선해 가는 방식이 효과적이라고 설명합니다. 또한 큰 저장소에서는 맥락과 구조를 잘 주는 것이 중요하며, 반복되는 워크플로는 Skill로 패키징할 수 있다고 안내합니다.
• 또한 AGENTS.md 문서를 두면 프로젝트 루트부터 현재 작업 디렉터리까지 내려오며 Codex가 그 지침을 참고할 수 있다고 공식 가이드가 설명합니다. 즉, 프로젝트별 규칙, 테스트 방법, 코딩 컨벤션, 주의사항 등을 문서로 남겨두면 Codex가 더 일관되게 동작합니다.
• 이건 설치 직후 꼭 필요한 건 아니지만, 나중에 정말 큰 차이를 만듭니다.

9. 마무리

• Codex CLI 설치 자체는 어렵지 않습니다.
• npm 설치 또는 Homebrew 설치 후, 터미널에서 codex를 실행하고 로그인하면 바로 시작할 수 있습니다. 다만 제대로 활용하려면 단순히 설치에 그치지 말고, 현재 디렉터리 기반으로 프로젝트 설명 요청, Git 체크포인트 습관, WSL 활용, 기본 설정 조정까지 함께 익히는 것이 좋습니다. 공식 문서도 설치 후 바로 현재 디렉터리에서 작업을 시작하고, Git 체크포인트를 남기며, 필요에 따라 설정과 워크플로를 발전시키는 방향을 권장합니다.