OpenAI Codex는 자연어로 코드를 생성하는 AI 모델이에요. 최근에는 Codex CLI라는 터미널 기반 AI 코딩 도구도 출시되었어요. AI 코딩 도구를 내 개발 환경에 설치해서 바로 활용하고 싶은 분들을 위해 설치 방법을 상세하게 안내해 드릴게요.
이번 글에서는 Codex CLI 설치, OpenAI API 키 설정, 개발 환경 구성까지 처음 설치하는 분들도 쉽게 따라할 수 있도록 단계별로 설명할게요. 맥OS, 윈도우, 리눅스 환경 모두 커버해요.
Codex CLI란?
Codex CLI 소개
Codex CLI는 OpenAI가 개발한 터미널 기반 AI 코딩 에이전트예요. 터미널에서 자연어로 명령을 내리면 코드 생성, 파일 편집, 명령어 실행 등을 자동으로 수행해요. 웹 브라우저 없이 개발 환경에서 직접 AI 코딩 도움을 받을 수 있는 강력한 도구예요. GitHub에서 오픈소스로 공개되어 있어서 무료로 사용할 수 있어요 (OpenAI API 키와 API 비용은 별도).
Codex CLI의 주요 기능
Codex CLI가 할 수 있는 것들을 정리했어요.
- 코드 생성: 자연어 설명으로 파일 및 코드 자동 생성
- 코드 편집: 기존 파일을 분석하고 수정 제안 실행
- 명령어 실행: 터미널 명령어를 AI가 직접 실행
- 버그 수정: 에러 메시지를 분석해서 자동 수정
- 테스트 작성: 코드에 맞는 테스트 파일 자동 생성
- 문서화: 코드에 대한 주석과 README 자동 생성
설치 전 준비사항
시스템 요구 사항
Codex CLI를 설치하기 전에 시스템 환경을 확인해야 해요.
- Node.js: 버전 18 이상 필요해요. node -v 명령어로 현재 버전 확인 가능
- npm 또는 yarn: Node.js와 함께 설치돼요
- Git: 소스 코드 관리에 필요해요
- 운영체제: macOS, Linux, Windows(WSL 권장)에서 사용 가능
OpenAI API 키 발급
Codex CLI를 사용하려면 OpenAI API 키가 필요해요. API 키 발급 방법을 설명할게요.
- 1단계: platform.openai.com에 접속해서 계정 생성 또는 로그인
- 2단계: 우측 상단 계정 메뉴에서 ‘API keys’ 클릭
- 3단계: ‘Create new secret key’ 버튼 클릭
- 4단계: 키 이름 입력 후 생성, 발급된 키를 안전하게 저장 (한 번만 표시됨)
- 5단계: 결제 수단 등록 (API 사용 요금 결제에 필요)
API 키는 절대로 공개된 곳에 올리면 안 돼요. GitHub에 올리거나 코드에 하드코딩하지 않도록 주의해요.
Codex CLI 설치 방법
macOS 설치 방법
macOS 터미널에서 다음 단계를 따라 설치해요.
- 1단계: Terminal 앱 열기
- 2단계: Node.js 설치 확인: node -v (버전 18 이상이어야 해요)
- 3단계: Codex CLI 설치: npm install -g @openai/codex
- 4단계: API 키 환경 변수 설정: export OPENAI_API_KEY=”your-api-key”
- 5단계: 설치 확인: codex –version
환경 변수를 영구적으로 적용하려면 ~/.zshrc 또는 ~/.bash_profile 파일에 export 명령어를 추가하면 돼요.
Windows 설치 방법 (WSL 권장)
Windows에서는 WSL(Windows Subsystem for Linux)을 사용하는 것을 권장해요.
- 1단계: Windows 스토어에서 Ubuntu 설치 또는 PowerShell에서 wsl –install 실행
- 2단계: WSL 터미널 열기
- 3단계: Node.js 설치: sudo apt update && sudo apt install nodejs npm
- 4단계: Codex CLI 설치: npm install -g @openai/codex
- 5단계: API 키 환경 변수 설정: export OPENAI_API_KEY=”your-api-key”
WSL 없이 순수 Windows PowerShell에서도 설치할 수 있지만, 일부 기능이 제한될 수 있어요.
Linux 설치 방법
Linux(Ubuntu/Debian 계열)에서의 설치 방법이에요.
- 1단계: sudo apt update && sudo apt upgrade
- 2단계: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash – 로 Node.js 18 설치
- 3단계: sudo apt install nodejs
- 4단계: npm install -g @openai/codex
- 5단계: ~/.bashrc 또는 ~/.zshrc에 API 키 환경 변수 추가
Codex CLI 기본 사용법
첫 번째 명령 실행하기
설치가 완료되면 터미널에서 바로 사용할 수 있어요. 사용할 프로젝트 폴더로 이동한 뒤 codex 명령을 입력해요.
- 대화형 모드 실행: codex
- 단일 명령 실행: codex “파이썬으로 피보나치 수열 함수를 만들어 줘”
- 파일 수정 요청: codex “app.py 파일의 login 함수에 입력값 유효성 검사를 추가해 줘”
명령을 입력하면 AI가 제안을 보여주고, 수락 여부를 물어봐요. 적용할 내용을 확인하고 동의하면 파일이 자동으로 수정돼요.
안전 모드와 자동 승인 모드
Codex CLI는 실행 전에 모든 변경사항을 보여주는 안전 모드가 기본이에요. 빠른 작업이 필요할 때는 자동 승인 모드를 사용할 수 있어요.
- 안전 모드(기본): 모든 변경사항을 확인하고 수동으로 승인
- 자동 승인 모드: codex –auto-approve “요청 내용” 으로 자동 승인
자동 승인 모드는 실수로 원치 않는 변경이 일어날 수 있으니, 신뢰할 수 있는 작업에만 사용하세요.
GitHub Copilot 설치 방법
VS Code에 Copilot 설치하기
Codex 기술을 기반으로 하는 GitHub Copilot은 VS Code에서 가장 쉽게 사용할 수 있어요.
- 1단계: VS Code 실행 후 확장 프로그램(Extensions) 패널 열기 (Ctrl+Shift+X)
- 2단계: ‘GitHub Copilot’ 검색 후 설치 버튼 클릭
- 3단계: 설치 완료 후 GitHub 계정으로 로그인
- 4단계: GitHub Copilot 구독 플랜 선택 (개인, 팀, 기업)
- 5단계: 설치 완료 – 코드 작성 시 자동으로 제안이 나타나요
Copilot 기본 단축키
VS Code에서 GitHub Copilot을 사용할 때 알면 좋은 단축키예요.
- Tab: 코드 제안 수락
- Esc: 코드 제안 거절
- Alt+]: 다음 제안 보기
- Alt+[: 이전 제안 보기
- Ctrl+Enter: 여러 제안 패널 열기
설치 후 문제 해결
자주 발생하는 오류와 해결법
Codex CLI 설치 및 실행 중 자주 발생하는 문제들과 해결 방법이에요.
- ‘codex’ 명령어를 찾을 수 없음: npm 글로벌 경로가 PATH에 등록되어 있지 않아요. npm root -g 명령으로 경로 확인 후 PATH에 추가해요
- API 키 오류: 환경 변수 OPENAI_API_KEY가 올바르게 설정되어 있는지 echo $OPENAI_API_KEY 명령으로 확인해요
- 권한 오류: sudo npm install -g 대신 nvm을 활용한 Node.js 설치를 권장해요
- Node.js 버전 오류: nvm use 18 명령으로 Node.js 버전을 18로 전환해요
마무리
OpenAI Codex CLI 설치는 몇 가지 단계만 따라하면 어렵지 않아요. Node.js 준비, OpenAI API 키 발급, npm 설치, 이 세 가지만 순서대로 진행하면 터미널에서 AI 코딩 어시스턴트를 사용할 수 있어요. GitHub Copilot은 VS Code 사용자에게 더욱 쉽고 자연스러운 AI 코딩 경험을 제공해요.
AI 코딩 도구를 처음 사용한다면 GitHub Copilot으로 시작하는 것이 가장 쉬워요. 더 심화된 AI 코딩 자동화를 원한다면 Codex CLI를 설치해서 터미널 기반의 강력한 AI 코딩 에이전트를 경험해 보세요.