OpenAI Codex CLI: 완벽 설치 가이드 (2026)

OpenAI Codex CLI: 2026년도 전체 설정 가이드

OpenAI의 Codex CLI는 코드베이스를 읽고, 파일을 작성 및 수정하며, 쉘 명령어를 실행하고, 프로그래밍 작업을 반복적으로 해결할 수 있는 명령줄 기반 AI 코딩 에이전트입니다. 터미널에서 상주하는 AI 페어 프로그래머라고 생각하면 됩니다. IDE 기반 도구와 달리 Codex CLI는 텍스트 인터페이스를 통해 작동하므로 속도가 빠르고 스크립트화가 가능하며 SSH를 통해서도 작동합니다.

이 가이드는 설치부터 고급 사용 패턴까지 모든 내용을 다룹니다.

Codex CLI란 무엇인가요?

Codex CLI는 OpenAI가 오픈 소스로 제공하는 터미널 기반 코딩 에이전트입니다. OpenAI의 모델(주로 o4-mini 및 GPT-4o)을 사용하여 코드베이스를 이해하고 다단계 작업을 실행합니다. 주요 기능은 다음과 같습니다:

파일 읽기 및 쓰기 -- 프로젝트를 탐색하고 파일을 수정할 수 있습니다.
쉘 명령어 실행 -- 테스트 실행, 패키지 설치, 빌드 명령어 실행이 가능합니다.
다단계 추론 -- 여러 파일에 걸친 복잡한 작업을 계획하고 실행합니다.
샌드박스 실행 -- 보안을 위해 명령어는 샌드박스 환경에서 실행됩니다.
대화 컨텍스트 -- 세션 전체에서 문맥을 유지합니다.

사전 요구 사항

Codex CLI를 설치하기 전에 다음 사항을 확인하세요:

요구 사항	최소 버전	확인 명령어
Node.js	22+	`node --version`
npm	9+	`npm --version`
Git	2.0+	`git --version`
OpenAI API key	--	platform.openai.com/api-keys

설치 방법

npm을 통한 설치

npm install -g @openai/codex

설치 확인

codex --version

API 키 설정

Codex CLI는 OpenAI API key가 필요합니다. 환경 변수로 설정하세요:

# 쉘 프로필(~/.bashrc, ~/.zshrc 등)에 추가
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

쉘을 다시 로드합니다:

source ~/.zshrc  # 또는 ~/.bashrc

키가 설정되었는지 확인합니다:

echo $OPENAI_API_KEY

기본 사용법

대화형 모드 (Interactive Mode)

프로젝트 디렉토리에서 대화형 모드로 Codex CLI를 시작합니다:

cd /path/to/your/project
codex

자연어 지침을 입력할 수 있는 프롬프트가 나타납니다:

> Fix the failing tests in the auth module

Codex는 테스트 실패를 분석하고, 관련 파일을 읽고, 수정 사항을 제안합니다.

단발성 모드 (One-Shot Mode)

대화형 모드로 들어가지 않고 단일 지침을 실행합니다:

codex "add input validation to the signup endpoint"

입력 파이핑 (Piping Input)

분석을 위해 콘텐츠를 Codex로 전달합니다:

cat error.log | codex "explain these errors and suggest fixes"
git diff HEAD~3 | codex "write a changelog entry for these changes"

구성 (Configuration)

설정 파일

~/.codex/config.json 경로에 설정 파일을 생성합니다:

{
  "model": "o4-mini",
  "approval_mode": "suggest",
  "sandbox": "docker"
}

프로젝트 수준 구성

프로젝트 루트에 codex.md 파일을 생성하여 Codex에 프로젝트에 대한 컨텍스트를 제공합니다:

# 프로젝트: MyApp

## 기술 스택
- TypeScript, React, Next.js
- PostgreSQL with Prisma ORM
- Tailwind CSS

## 컨벤션
- Hook을 사용하는 함수형 컴포넌트 사용
- 패키지 매니저로 `pnpm` 사용
- 테스트는 소스 파일 옆의 `__tests__/` 디렉토리에 위치
- 파일 이름에 kebab-case 사용

## 중요 사항
- `migrations/` 디렉토리의 파일을 직접 수정하지 말 것
- 변경 후에는 항상 `pnpm test`를 실행할 것
- 환경 변수는 `.env.local`에 있음 (커밋 금지)

Codex는 이 파일을 자동으로 읽어 모든 상호작용의 컨텍스트로 사용합니다.

승인 모드 (Approval Modes)

Codex CLI에는 에이전트의 자율성을 제어하는 세 가지 승인 모드가 있습니다:

모드	파일 수정	쉘 명령어	권장 용도
`suggest`	승인 필요	승인 필요	학습, 검토
`auto-edit`	자동	승인 필요	신뢰할 수 있는 파일 변경
`full-auto`	자동	자동	스크립팅, CI 파이프라인

시작 시 모드를 설정할 수 있습니다:

# 제안 모드 (가장 안전, 기본값)
codex --approval-mode suggest "refactor the auth module"

# 자동 수정 모드 (파일 변경은 승인, 명령어는 확인)
codex --approval-mode auto-edit "add unit tests for the User model"

# 전체 자동 모드 (모든 항목 승인)
codex --approval-mode full-auto "fix all ESLint errors"

실용적인 예시

예시 1: 실패하는 테스트 수정

codex "run the tests, identify failures, and fix them"

Codex는 다음 작업을 수행합니다:

테스트 슈트를 실행하여 실패 확인
실패한 테스트 파일과 소스 파일 읽기
근본 원인 분석
타겟 수정 사항 적용
수정을 확인하기 위해 테스트 재실행

예시 2: 새로운 기능 추가

codex "add a rate limiting middleware to the Express API using express-rate-limit. \
Limit to 100 requests per 15 minutes per IP. Add tests."

예시 3: 코드 리팩토링

codex "refactor the database queries in src/services/ to use the repository pattern. \
Keep the existing tests passing."

예시 4: 코드 리뷰

git diff main | codex "review this diff for bugs, security issues, and style problems"

예시 5: 문서화

codex "generate JSDoc comments for all exported functions in src/utils/"

예시 6: 디버깅

codex "the /api/users endpoint returns 500 when the email contains a plus sign. \
Find and fix the bug."

고급 사용법

CI/CD와 함께 사용하기

Codex CLI는 CI/CD 파이프라인을 위해 비대화형 모드로 실행될 수 있습니다:

# .github/workflows/codex-fix.yml
name: Auto-fix lint errors
on:
  push:
    branches: [main]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: codex --approval-mode full-auto "fix all ESLint errors and format with Prettier"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: git diff
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "fix: auto-fix lint errors via Codex CLI"

커스텀 시스템 프롬프트

특수 작업을 위해 기본 시스템 프롬프트를 오버라이드합니다:

codex --system-prompt "You are a security auditor. Review code for vulnerabilities only." \
  "audit the authentication flow"

모델 선택

작업의 복잡도에 따라 모델을 선택합니다:

# 빠르고 저렴한 작업
codex --model o4-mini "fix the typo in the README"

# 복잡한 추론 작업
codex --model o3 "redesign the caching layer to handle cache stampedes"

샌드박싱 옵션

Codex는 다양한 샌드박싱 전략을 지원합니다:

# Docker 샌드박스 (full-auto 모드에 권장)
codex --sandbox docker "install dependencies and run the test suite"

# 네트워크 비활성화 샌드박스
codex --sandbox network-disabled "refactor the parser module"

# 샌드박스 없음 (주의해서 사용)
codex --sandbox none "run the deployment script"

Codex CLI vs 다른 CLI 도구

기능	Codex CLI	Claude Code	Aider
제공자	OpenAI	Anthropic	멀티 제공자
기본 모델	o4-mini	Claude Sonnet	설정 가능
파일 수정	지원	지원	지원
쉘 명령어	지원 (샌드박스)	지원	제한적
승인 모드	3가지 모드	도구당 설정	자동/수동
오픈 소스	예	아니요	예
MCP 지원	아니요	예	아니요
Git 연동	기본	고급	고급
가격	API 사용량 기준	API 사용량 기준	무료 (개인 키 필요)

비용 관리

Codex CLI 비용은 OpenAI API 토큰 사용량을 기준으로 청구됩니다. 대략적인 비용 가이드는 다음과 같습니다:

작업 유형	예상 비용	모델
단순 수정 (파일 1-2개)	$0.01-0.05	o4-mini
기능 추가 (파일 3-5개)	$0.05-0.20	o4-mini
복잡한 리팩토링 (파일 10개 이상)	$0.20-1.00	o4-mini
아키텍처 재설계	$1.00-5.00	o3

비용 절감 팁

프롬프트를 구체적으로 작성하세요. 모호한 지침은 더 많은 대화 횟수를 유발합니다.
대부분의 작업에 o4-mini를 사용하세요. 코딩 작업의 90%를 훌륭하게 처리합니다.
큰 작업은 작은 작업으로 나누세요. 각 작업은 신선한 컨텍스트로 시작됩니다.
codex.md 파일을 활용하세요. 좋은 프로젝트 컨텍스트는 탐색적 읽기 횟수를 줄여줍니다.

문제 해결 (Troubleshooting)

"Command not found: codex"

# 설치 여부 확인
npm list -g @openai/codex

# 재설치
npm install -g @openai/codex

# PATH 확인
echo $PATH

"Invalid API key"

# 키 유효성 확인
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -c 200

Codex가 잘못된 변경을 수행할 때

적용하기 전에 검토할 수 있도록 suggest 모드를 사용하세요.
codex.md 프로젝트 파일에 더 많은 컨텍스트를 추가하세요.
지침을 더 구체적으로 작성하세요.
복잡한 작업을 작고 집중된 단계로 나누세요.

Docker 샌드박스 문제

# Docker가 실행 중인지 확인
docker ps

# Codex 샌드박스 이미지 풀(Pull)
docker pull openai/codex-sandbox:latest

AI 기반 애플리케이션 구축하기

Codex CLI는 코드 작성에 매우 탁월하지만, 애플리케이션에서 이미지, 비디오, 오디오 또는 아바타를 생성해야 하는 경우 코드와 함께 미디어 생성 API가 필요합니다. Hypereal AI는 Codex CLI로 구축된 프로젝트에 통합할 수 있는 통합 AI 미디어 생성 API를 제공하여 지능형 코드 생성과 AI 기반 미디어 생성을 하나의 워크플로우에서 가능하게 합니다.

요약

OpenAI Codex CLI는 강력한 터미널 기반 코딩 에이전트입니다. npm install -g @openai/codex로 설치하고, OPENAI_API_KEY를 설정한 후, 프로젝트에 컨텍스트를 위한 codex.md 파일을 생성하세요. 학습 시에는 suggest 모드를, 신뢰할 수 있는 변경에는 auto-edit 모드를, 스크립팅 및 CI 파이프라인에는 full-auto 모드를 사용하세요. 대부분의 작업에서 o4-mini 모델이 속도, 품질, 비용의 최적의 균형을 제공합니다.

OpenAI Codex CLI: 2026년도 전체 설정 가이드

이 가이드는 설치부터 고급 사용 패턴까지 모든 내용을 다룹니다.

Codex CLI란 무엇인가요?

파일 읽기 및 쓰기 -- 프로젝트를 탐색하고 파일을 수정할 수 있습니다.
쉘 명령어 실행 -- 테스트 실행, 패키지 설치, 빌드 명령어 실행이 가능합니다.
다단계 추론 -- 여러 파일에 걸친 복잡한 작업을 계획하고 실행합니다.
샌드박스 실행 -- 보안을 위해 명령어는 샌드박스 환경에서 실행됩니다.
대화 컨텍스트 -- 세션 전체에서 문맥을 유지합니다.

사전 요구 사항

Codex CLI를 설치하기 전에 다음 사항을 확인하세요:

요구 사항	최소 버전	확인 명령어
Node.js	22+	`node --version`
npm	9+	`npm --version`
Git	2.0+	`git --version`
OpenAI API key	--	platform.openai.com/api-keys

설치 방법

npm을 통한 설치

npm install -g @openai/codex

설치 확인

codex --version

API 키 설정

Codex CLI는 OpenAI API key가 필요합니다. 환경 변수로 설정하세요:

# 쉘 프로필(~/.bashrc, ~/.zshrc 등)에 추가
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

쉘을 다시 로드합니다:

source ~/.zshrc  # 또는 ~/.bashrc

키가 설정되었는지 확인합니다:

echo $OPENAI_API_KEY

기본 사용법

대화형 모드 (Interactive Mode)

프로젝트 디렉토리에서 대화형 모드로 Codex CLI를 시작합니다:

cd /path/to/your/project
codex

자연어 지침을 입력할 수 있는 프롬프트가 나타납니다:

> Fix the failing tests in the auth module

Codex는 테스트 실패를 분석하고, 관련 파일을 읽고, 수정 사항을 제안합니다.

단발성 모드 (One-Shot Mode)

대화형 모드로 들어가지 않고 단일 지침을 실행합니다:

codex "add input validation to the signup endpoint"

입력 파이핑 (Piping Input)

분석을 위해 콘텐츠를 Codex로 전달합니다:

cat error.log | codex "explain these errors and suggest fixes"
git diff HEAD~3 | codex "write a changelog entry for these changes"

구성 (Configuration)

설정 파일

~/.codex/config.json 경로에 설정 파일을 생성합니다:

{
  "model": "o4-mini",
  "approval_mode": "suggest",
  "sandbox": "docker"
}

프로젝트 수준 구성

프로젝트 루트에 codex.md 파일을 생성하여 Codex에 프로젝트에 대한 컨텍스트를 제공합니다:

# 프로젝트: MyApp

## 기술 스택
- TypeScript, React, Next.js
- PostgreSQL with Prisma ORM
- Tailwind CSS

## 컨벤션
- Hook을 사용하는 함수형 컴포넌트 사용
- 패키지 매니저로 `pnpm` 사용
- 테스트는 소스 파일 옆의 `__tests__/` 디렉토리에 위치
- 파일 이름에 kebab-case 사용

## 중요 사항
- `migrations/` 디렉토리의 파일을 직접 수정하지 말 것
- 변경 후에는 항상 `pnpm test`를 실행할 것
- 환경 변수는 `.env.local`에 있음 (커밋 금지)

Codex는 이 파일을 자동으로 읽어 모든 상호작용의 컨텍스트로 사용합니다.

승인 모드 (Approval Modes)

Codex CLI에는 에이전트의 자율성을 제어하는 세 가지 승인 모드가 있습니다:

모드	파일 수정	쉘 명령어	권장 용도
`suggest`	승인 필요	승인 필요	학습, 검토
`auto-edit`	자동	승인 필요	신뢰할 수 있는 파일 변경
`full-auto`	자동	자동	스크립팅, CI 파이프라인

시작 시 모드를 설정할 수 있습니다:

# 제안 모드 (가장 안전, 기본값)
codex --approval-mode suggest "refactor the auth module"

# 자동 수정 모드 (파일 변경은 승인, 명령어는 확인)
codex --approval-mode auto-edit "add unit tests for the User model"

# 전체 자동 모드 (모든 항목 승인)
codex --approval-mode full-auto "fix all ESLint errors"

실용적인 예시

예시 1: 실패하는 테스트 수정

codex "run the tests, identify failures, and fix them"

Codex는 다음 작업을 수행합니다:

테스트 슈트를 실행하여 실패 확인
실패한 테스트 파일과 소스 파일 읽기
근본 원인 분석
타겟 수정 사항 적용
수정을 확인하기 위해 테스트 재실행

예시 2: 새로운 기능 추가

codex "add a rate limiting middleware to the Express API using express-rate-limit. \
Limit to 100 requests per 15 minutes per IP. Add tests."

예시 3: 코드 리팩토링

codex "refactor the database queries in src/services/ to use the repository pattern. \
Keep the existing tests passing."

예시 4: 코드 리뷰

git diff main | codex "review this diff for bugs, security issues, and style problems"

예시 5: 문서화

codex "generate JSDoc comments for all exported functions in src/utils/"

예시 6: 디버깅

codex "the /api/users endpoint returns 500 when the email contains a plus sign. \
Find and fix the bug."

고급 사용법

CI/CD와 함께 사용하기

Codex CLI는 CI/CD 파이프라인을 위해 비대화형 모드로 실행될 수 있습니다:

# .github/workflows/codex-fix.yml
name: Auto-fix lint errors
on:
  push:
    branches: [main]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: codex --approval-mode full-auto "fix all ESLint errors and format with Prettier"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: git diff
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "fix: auto-fix lint errors via Codex CLI"

커스텀 시스템 프롬프트

특수 작업을 위해 기본 시스템 프롬프트를 오버라이드합니다:

codex --system-prompt "You are a security auditor. Review code for vulnerabilities only." \
  "audit the authentication flow"

모델 선택

작업의 복잡도에 따라 모델을 선택합니다:

# 빠르고 저렴한 작업
codex --model o4-mini "fix the typo in the README"

# 복잡한 추론 작업
codex --model o3 "redesign the caching layer to handle cache stampedes"

샌드박싱 옵션

Codex는 다양한 샌드박싱 전략을 지원합니다:

# Docker 샌드박스 (full-auto 모드에 권장)
codex --sandbox docker "install dependencies and run the test suite"

# 네트워크 비활성화 샌드박스
codex --sandbox network-disabled "refactor the parser module"

# 샌드박스 없음 (주의해서 사용)
codex --sandbox none "run the deployment script"

Codex CLI vs 다른 CLI 도구

기능	Codex CLI	Claude Code	Aider
제공자	OpenAI	Anthropic	멀티 제공자
기본 모델	o4-mini	Claude Sonnet	설정 가능
파일 수정	지원	지원	지원
쉘 명령어	지원 (샌드박스)	지원	제한적
승인 모드	3가지 모드	도구당 설정	자동/수동
오픈 소스	예	아니요	예
MCP 지원	아니요	예	아니요
Git 연동	기본	고급	고급
가격	API 사용량 기준	API 사용량 기준	무료 (개인 키 필요)

비용 관리

Codex CLI 비용은 OpenAI API 토큰 사용량을 기준으로 청구됩니다. 대략적인 비용 가이드는 다음과 같습니다:

작업 유형	예상 비용	모델
단순 수정 (파일 1-2개)	$0.01-0.05	o4-mini
기능 추가 (파일 3-5개)	$0.05-0.20	o4-mini
복잡한 리팩토링 (파일 10개 이상)	$0.20-1.00	o4-mini
아키텍처 재설계	$1.00-5.00	o3

비용 절감 팁

프롬프트를 구체적으로 작성하세요. 모호한 지침은 더 많은 대화 횟수를 유발합니다.
대부분의 작업에 o4-mini를 사용하세요. 코딩 작업의 90%를 훌륭하게 처리합니다.
큰 작업은 작은 작업으로 나누세요. 각 작업은 신선한 컨텍스트로 시작됩니다.
codex.md 파일을 활용하세요. 좋은 프로젝트 컨텍스트는 탐색적 읽기 횟수를 줄여줍니다.

문제 해결 (Troubleshooting)

"Command not found: codex"

# 설치 여부 확인
npm list -g @openai/codex

# 재설치
npm install -g @openai/codex

# PATH 확인
echo $PATH

"Invalid API key"

# 키 유효성 확인
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -c 200

Codex가 잘못된 변경을 수행할 때

적용하기 전에 검토할 수 있도록 suggest 모드를 사용하세요.
codex.md 프로젝트 파일에 더 많은 컨텍스트를 추가하세요.
지침을 더 구체적으로 작성하세요.
복잡한 작업을 작고 집중된 단계로 나누세요.

Docker 샌드박스 문제

# Docker가 실행 중인지 확인
docker ps

# Codex 샌드박스 이미지 풀(Pull)
docker pull openai/codex-sandbox:latest

Hypereal로 구축 시작하기

OpenAI Codex CLI: 2026년도 전체 설정 가이드

Codex CLI란 무엇인가요?

사전 요구 사항

설치 방법

npm을 통한 설치

설치 확인

API 키 설정

기본 사용법

대화형 모드 (Interactive Mode)

단발성 모드 (One-Shot Mode)

입력 파이핑 (Piping Input)

구성 (Configuration)

설정 파일

프로젝트 수준 구성

승인 모드 (Approval Modes)

실용적인 예시

예시 1: 실패하는 테스트 수정

예시 2: 새로운 기능 추가

예시 3: 코드 리팩토링

예시 4: 코드 리뷰

예시 5: 문서화

예시 6: 디버깅

고급 사용법

CI/CD와 함께 사용하기

커스텀 시스템 프롬프트

모델 선택

샌드박싱 옵션

Codex CLI vs 다른 CLI 도구

비용 관리

비용 절감 팁

문제 해결 (Troubleshooting)

"Command not found: codex"

"Invalid API key"

Codex가 잘못된 변경을 수행할 때

Docker 샌드박스 문제

AI 기반 애플리케이션 구축하기

요약

관련 아티클

MCP Server를 처음부터 구축하는 방법 (2026)

Claude Code 입문 가이드 및 모범 사례 (2026)

Claude Code를 활용해 더 나은 코드를 작성하는 방법 (2026)

지금 바로 개발을 시작하세요

Hypereal로 구축 시작하기

OpenAI Codex CLI: 2026년도 전체 설정 가이드

Codex CLI란 무엇인가요?

사전 요구 사항

설치 방법

npm을 통한 설치

설치 확인

API 키 설정

기본 사용법

대화형 모드 (Interactive Mode)

단발성 모드 (One-Shot Mode)

입력 파이핑 (Piping Input)

구성 (Configuration)

설정 파일

프로젝트 수준 구성

승인 모드 (Approval Modes)

실용적인 예시

예시 1: 실패하는 테스트 수정

예시 2: 새로운 기능 추가

예시 3: 코드 리팩토링

예시 4: 코드 리뷰

예시 5: 문서화

예시 6: 디버깅

고급 사용법

CI/CD와 함께 사용하기

커스텀 시스템 프롬프트

모델 선택

샌드박싱 옵션

Codex CLI vs 다른 CLI 도구

비용 관리

비용 절감 팁

문제 해결 (Troubleshooting)

"Command not found: codex"

"Invalid API key"

Codex가 잘못된 변경을 수행할 때

Docker 샌드박스 문제

AI 기반 애플리케이션 구축하기