Ubuntu 24.04에서 Codex CLI를 설치하고 사용하는 방법

개요

명령줄 환경에서 AI 기반의 프로그래밍 도구를 활용하면 개발 효율을 크게 향상시킬 수 있습니다. Codex CLI는 OpenAI가 제공하는 명령행 도구로, 자연어 입력을 통해 코드 생성, 리팩토링, 명령 실행, 프로젝트 분석 등을 지원합니다. 아래 가이드에서는 Ubuntu 24.04 시스템에서 nvm을 사용해 Node.js를 설치한 후 npm으로 Codex CLI를 전역 설치하고 검증하는 방법을 안내합니다.

1. 환경 준비: nvm 설치 및 Shell 설정

우선 Node.js 버전 관리자인 nvm(Node Version Manager)을 설치하여 다양한 Node.js 버전을 쉽게 관리할 수 있도록 합니다.

# nvm 설치 스크립트 다운로드 및 실행
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 현재 쉘에서 nvm 즉시 사용 가능하도록 설정
source "$HOME/.nvm/nvm.sh"

참고:

• 위 스크립트는 공식 저장소에서 nvm 설치 스크립트를 가져와 실행합니다.
• 설치 후 ~/.bashrc 또는 ~/.zshrc 파일에 nvm 초기화 코드가 포함되었는지 확인하세요. 일반적으로 자동으로 추가됩니다.
• 새로운 터미널에서 여전히 nvm 명령어가 작동하지 않는다면 source ~/.bashrc 또는 터미널을 재시작하세요.

2. nvm을 사용한 Node.js 설치

다음 단계로 nvm을 사용해 특정 버전의 Node.js를 설치합니다.

# Node.js 버전 25 설치
nvm install 25

# 설치된 Node.js 및 npm 버전 확인
node -v   # 예: v25.1.0
npm -v    # 예: 11.6.2

참고:

• Codex CLI는 Node.js 버전 22 이상을 요구합니다.
• 이미 Node.js를 설치했지만 올바른 버전이 선택되지 않는다면 nvm use 25 및 nvm alias default 25 명령어로 기본 버전을 지정하세요.
• 네트워크 문제가 발생한다면 중국 내부 환경에서는 타오바오나 청화대 등 미러를 사용해 Node.js 또는 npm 패키지를 동기화하세요.

3. Codex CLI 전역 설치

Node.js 환경이 정상적으로 구성되면 이제 Codex CLI를 설치합니다.

# Codex CLI를 npm을 통해 전역 설치
npm install -g @openai/codex

참고:

• 권한 문제(EACCES)가 발생한다면 sudo 대신 npm 전역 디렉터리의 권한을 수정하거나 사용자 디렉터리로 전환하는 것이 좋습니다.
• 중국 내부 네트워크 환경에서는 npm 미러나 프록시를 설정해 패키지 다운로드를 원활하게 진행하세요.

4. 설치 확인

설치 완료 후 다음 명령어를 실행해 설치가 성공했는지 확인합니다.

codex --version  # 예: 0.42.0 출력

참고:

• codex 명령어가 인식되지 않는다면 글로벌 경로가 PATH에 포함되어 있는지 확인하세요.
• 처음 실행 시 인증(예: API Key 설정)이 필요할 수 있습니다.

5. 구성 및 사용: API Key, 모드 설정

5.1 OPENAI_API_KEY 설정

Codex CLI가 OpenAI 모델과 통신하려면 API 키가 필요합니다. 이를 위해 shell 구성 파일에 다음 내용을 추가하세요.

export OPENAI_API_KEY="당신의-API-키"

그런 후 터미널을 다시 로드하거나 source ~/.bashrc (또는 ~/.zshrc)를 실행하세요.

5.2 승인 모드 설명

Codex CLI는 여러 자동화 레벨을 제공하며, 이는 AI가 코드에 대해 수행할 작업 범위를 제어합니다.

사용 예시:

codex "React Hooks 방식으로 Dashboard 컴포넌트 리팩토링"
codex --approval-mode auto-edit "모든 .js 파일을 .tsx로 변환하고 타입 주석 추가"
codex --approval-mode full-auto "완전한 TODO 애플리케이션 생성 및 테스트 실행"

5.3 초기 실행

설치 및 구성이 완료되면 임의의 프로젝트 디렉토리에서 다음 명령어를 실행하세요.

codex

자연어로 요청을 입력하면 도구가 프로젝트를 분석하고 제안 또는 변경 사항을 표시합니다. 예시 요청:

• "프로젝트 내 모든 사용되지 않은 종속성을 분석하여 보고서 생성"
• "src/utils/createUser.ts 파일에 대한 유닛 테스트 작성"

도구는 변경 사항을 표시하며, 이를 검토한 후 적용할 수 있습니다.