본문 바로가기

AI Insights & Innovations

최신 인공지능 기술과 트렌드를 탐색하는 전문 블로그

AI/OPENAI

OpenAI Codex CLI 최신 버전 메뉴얼: 설치, 명령어, 기능 및 사용법

by dma-ai 2025. 9. 24.
728x90

OpenAI Codex CLI 최신 버전 메뉴얼: 설치, 명령어, 기능 및 사용법

OpenAI Codex CLI는 터미널에서 작동하는 강력한 오픈소스 코딩 에이전트로, 자연어 명령을 통해 코드 작성, 실행, 파일 관리, Git 워크플로 자동화 등을 수행할 수 있습니다. 2025년 9월 기준 최신 버전(v0.4.0)을 기반으로, 이 메뉴얼은 Codex CLI의 설치 방법, 주요 명령어, 기능, 그리고 실용적인 사용법을 자세히 안내합니다. 터미널에서 AI 기반 코딩을 시작하고 싶은 개발자라면 이 가이드를 참고해 생산성을 높여보세요!

1. Codex CLI란?

Codex CLI는 OpenAI가 제공하는 경량 AI 코딩 도구로, ChatGPT 수준의 추론 능력과 로컬 파일 및 셸 명령 실행 기능을 결합해 개발 워크플로를 혁신합니다. 주요 특징은 다음과 같습니다:

  • 터미널 네이티브: 별도의 UI 없이 기존 터미널 환경에서 동작
  • 추론 + 실행: 코드 생성뿐 아니라 파일 수정, 명령 실행, Git 연동 가능
  • 레포 인식: 프로젝트 맥락을 이해하고 Git 저장소와 통합
  • 보안 중심: 네트워크 차단 및 디렉토리 샌드박싱으로 안전한 실행 환경 제공
  • 멀티모달 입력: 텍스트뿐 아니라 스크린샷, 다이어그램 입력 지원
  • 오픈소스: Apache 2.0 라이선스로 커뮤니티 기여 가능

이 도구는 macOS, Linux, Windows(WSL2)를 지원하며, Rust로 재작성된 최신 버전은 성능과 보안이 크게 향상되었습니다.

2. 설치 방법

Codex CLI를 설치하려면 Node.js(v14 이상)와 npm이 필요하며, OpenAI API 키 또는 ChatGPT 유료 플랜(Plus, Pro, Team 등)이 있어야 합니다. 아래는 단계별 설치 가이드입니다.

사전 요구 사항

  • Node.js: v14 이상 설치 및 PATH에 추가
  • npm: Node.js에 포함
  • Git: Git 저장소 연동을 위해 권장
  • OpenAI API 키: OpenAI 대시보드에서 발급
  • 운영체제: macOS 12+, Linux(Ubuntu 20.04+), Windows 11(WSL2)

설치 단계

  1. Node.js 확인Node.js가 설치되어 있지 않다면, 공식 웹사이트에서 최신 버전을 설치하세요.
  2. node --version npm --version
  3. Codex CLI 설치설치 후, 다음 명령어로 설치 확인:
  4. codex --version
  5. npm install -g @openai/codex
  6. OpenAI API 키 설정
    API 키를 환경 변수로 설정합니다:영구 적용을 위해 셸 프로필 파일(~/.zshrc 또는 ~/.bashrc)에 추가:Windows(WSL2)에서는:
  7. setx OPENAI_API_KEY "your-api-key-here"
  8. echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc source ~/.zshrc
  9. export OPENAI_API_KEY="your-api-key-here"
  10. 첫 실행첫 실행 시, ChatGPT 계정 로그인 또는 API 키 입력을 요청하는 프롬프트가 표시됩니다.
  11. codex

참고: Windows는 네이티브 지원이 없으므로 WSL2(Ubuntu)에서 설치하세요. 설치 중 오류 발생 시 npm install --legacy-peer-deps를 시도하세요.

3. 주요 명령어

Codex CLI는 대화형 모드와 비대화형 모드를 지원하며, 다양한 플래그와 명령어를 통해 유연한 작업이 가능합니다. 아래는 자주 사용되는 명령어입니다.

기본 명령어

  • 도움말 확인사용 가능한 명령어와 옵션을 표시합니다.
  • codex --help
  • Codex 실행대화형 터미널 UI를 시작합니다.
  • codex
  • 비대화형 실행예: codex exec "퀵 정렬 알고리즘을 파이썬으로 작성해줘"
  • codex exec "작업 요청"
  • 이미지 입력스크린샷이나 다이어그램을 입력으로 사용합니다.
  • codex --image screenshot.png "이 에러를 분석해줘"

대화형 모드 명령어

대화형 모드에서 사용 가능한 특수 명령어:

  • /model: 모델 변경 (예: gpt-5-codex, o4-mini)
  • /approvals: 승인 모드 설정 (read-only, auto-edit, full-auto)
  • /review: 현재 변경사항 검토 및 이슈 탐지
  • /diff: Git diff 표시 (추적되지 않은 파일 포함)
  • /new: 새 채팅 세션 시작
  • /compact: 대화 요약으로 컨텍스트 최적화
  • /mention: 특정 파일 참조 (예: /mention main.py)

옵션 플래그

  • -m, --model <model>: 사용할 모델 지정 (예: gpt-5-codex)
  • -a, --approval-mode <mode>: 자동화 수준 설정 (suggest, auto-edit, full-auto)
  • -i, --image <file>: 이미지 파일 입력
  • --quiet: 비대화형 CI 환경에서 실행
  • --no-project-doc: 프로젝트 문서(Markdown) 무시

4. 주요 기능 및 사용법

Codex CLI는 단순한 코드 생성을 넘어 다양한 개발 작업을 자동화합니다. 아래는 주요 기능과 실제 사용 예시입니다.

1) 코드 생성 및 실행

자연어로 코드를 요청하면 생성 후 실행까지 처리합니다.

codex exec "1부터 100까지 합을 구하는 파이썬 코드 작성해줘"

결과:

sum = 0
for i in range(1, 101):
    sum += i
print(sum)  # 출력: 5050

Codex는 코드를 생성하고, 요청 시 실행 결과를 터미널에 표시합니다.

2) 파일 및 프로젝트 관리

파일 이동, 수정, 디렉토리 관리 등을 자동화합니다.

codex "모든 .md 파일을 docs 폴더로 이동해줘"

Codex는 git mv를 사용해 파일을 이동하고 경로를 업데이트합니다.

3) 버그 디버깅 및 리팩토링

스택 트레이스를 분석하고 수정 제안을 제공합니다.

codex "이 에러를 고쳐줘" --image error-screenshot.png

Codex는 스크린샷을 분석해 원인을 파악하고 패치를 적용합니다.

4) Git 워크플로 자동화

변경사항 감지, 커밋 메시지 제안, 브랜치 푸시 등을 처리합니다.

codex "최근 변경사항 커밋하고 푸시해줘"

Codex는 변경사항을 커밋하고, 브랜치 전략에 맞춰 푸시합니다.

5) 멀티모달 입력

스크린샷이나 다이어그램을 활용해 작업을 요청할 수 있습니다.

codex --image ui-design.jpg "이 디자인과 유사한 HTML/CSS 코드 작성해줘"

6) 보안 샌드박스

  • 네트워크 차단: 외부 네트워크 접근 기본 차단
  • 디렉토리 제한: 현재 작업 디렉토리 내에서만 동작
  • 승인 모드:
    • suggest: 파일 읽기만 가능, 쓰기/실행은 사용자 승인 필요
    • auto-edit: 파일 읽기/쓰기 가능, 셸 명령은 승인 필요
    • full-auto: 읽기/쓰기 및 셸 명령 실행, 네트워크 차단 유지

5. 문제 해결 및 팁

일반적인 오류 해결

  • 인증 오류 ("401 AK/SK errors").env 파일의 OPENAI_API_KEY를 삭제하거나 갱신하세요.
  • codex --login
  • 모델 호환성 오류 ("404 This model is only supported in v1/responses")
  • codex --model gpt-5-codex
  • 성능 문제 (응답 느림)
    • .gitignore로 불필요한 파일 제외
    • /model 명령으로 빠른 모델 선택 (예: o4-mini)

활용 팁

  • 한국어 프롬프트: 한국어로 자연어 입력 가능 (예: "퀵 정렬 구현해줘")
  • CI/CD 통합: --quiet 옵션으로 GitHub Actions에서 사용 
    jobs:
  ai_lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: codex --mode auto-edit "Optimize bundle size"
  • 커뮤니티 참여: GitHub 저장소(github.com/openai/codex)에서 이슈 제기 및 기능 요청 가능

6. 주의사항

  • 코드 검토 필수: 자동 생성된 코드는 반드시 검토하고 테스트하세요.
  • 비용 관리: 대용량 작업 시 API 토큰 비용이 발생할 수 있습니다. ChatGPT Plus/Pro 구독자는 무료 사용량이 포함됩니다.
  • 실험적 기능: 멀티모달 입력 및 네트워크 예외 리스트는 2025년 2분기 업데이트 예정.

7. 결론

OpenAI Codex CLI는 터미널에서 AI를 활용해 코딩 작업을 자동화하고 생산성을 극대화하는 강력한 도구입니다. 자연어로 코드 작성, 디버깅, Git 관리까지 처리하며, 보안과 오픈소스 특성을 통해 신뢰성을 확보했습니다. 이 메뉴얼을 따라 설치하고 명령어를 활용해 보세요. 터미널 속 AI 코딩 파트너와 함께 개발의 새로운 가능성을 경험할 수 있을 것입니다!

 

728x90
저작자표시 변경금지 (새창열림)

티스토리툴바