Codex CLI: 실전 입문

앞서 Claude Code를 소개했습니다. 이번 장에서는 또 하나의 강력한 터미널 AI 코딩 도구인 Codex CLI를 다룹니다.

참고: Codex에는 데스크톱 앱 버전(그래픽 인터페이스)도 있으며, 이는 이후 장에서 다룹니다. 이 장에서는 터미널 기반 Codex CLI에 초점을 맞춥니다.

터미널 기반 Codex CLI는 Claude Code와 마찬가지로 터미널에서 실행되는 AI 코딩 어시스턴트입니다. 이전 장에서 Claude Code를 이미 배웠다면, 작동 방식이 거의 동일하므로 Codex CLI를 매우 쉽게 익힐 수 있습니다.

Codex CLI란?

한 줄 소개

Codex CLI = OpenAI의 터미널 AI 코딩 어시스턴트

Claude Code와 유사하게, 터미널에서 실행되는 AI 도구입니다. 자연어로 원하는 작업을 지시하면 다음과 같은 일을 할 수 있습니다:

• 새 프로젝트 생성
• 코드 작성
• 코드 수정
• 버그 수정
• 명령어 실행
• 웹 검색을 통한 최신 정보 획득

Codex CLI와 Claude Code의 차이점

핵심 차이점: 서로 다른 기반 모델. Claude Code는 Claude 모델을, Codex CLI는 프로그래밍에 최적화된 OpenAI의 GPT-5-Codex 모델을 사용합니다. 두 도구 모두 장단점이 있으므로, 두 가지를 모두 설치하고 작업에 따라 선택하는 것을 권장합니다.

Codex CLI 설치 방법

사전 요구 사항

1. Node.js: Claude Code와 마찬가지로 Node.js 환경이 필요합니다.

   • 이미 설치되어 있다면(이전에 Claude Code를 설치하면서) 다시 설치할 필요가 없습니다.
   • 설치되어 있지 않다면 https://nodejs.org 에서 LTS 버전을 다운로드하세요.

2. 네트워크: OpenAI 서비스에 접근할 수 있어야 합니다(프록시가 필요할 수 있음).

설치 단계

터미널을 열고 다음을 실행하세요:

npm install -g @openai/codex

완료될 때까지 기다립니다.

설치 확인:

codex --version

버전 번호(예: codex-cli 0.98.0)가 표시되면 설치가 성공한 것입니다.

Mac 사용자는 Homebrew로도 설치할 수 있습니다:

brew install codex

사용 방법 (여러 가지)

Claude Code와 마찬가지로 Codex CLI는 AI 기능에 접근하는 여러 방법을 지원합니다.

방법 1: ChatGPT 멤버십 구매 (가장 간단)

Codex CLI는 ChatGPT 유료 요금제에 포함되어 있습니다.

지원되는 멤버십 유형:

설정:

1. ChatGPT 멤버십을 구매한 후 터미널을 엽니다.
2. codex를 실행하여 시작합니다.
3. 프롬프트에 따라 ChatGPT 계정에 로그인합니다(브라우저가 열려 인증을 진행합니다).
4. 로그인하면 사용할 수 있습니다.

수동으로 로그인할 수도 있습니다:

codex login

방법 2: OpenAI API 키 사용

OpenAI API 키가 있다면 직접 사용할 수 있습니다:

1. 환경 변수 설정:

export OPENAI_API_KEY="your API Key"

2. 그런 다음 codex를 실행합니다.

방법 3: 타사 API 사용 (국내 모델 연동)

이것이 많은 국내 사용자들이 가장 관심을 가지는 부분입니다!

Claude Code와 마찬가지로 Codex CLI도 타사 API와 연동할 수 있습니다. 예를 들어 DeepSeek, Volcengine 등 국내 모델을 사용할 수 있습니다.

설정은 ~/.codex/config.toml 파일을 수정하여 수행합니다(자세한 내용은 다음 섹션에서 설명).

국내 모델 연동: config.toml 수정

config.toml 위치

설정 파일 경로: ~/.codex/config.toml

• Mac/Linux: /Users/사용자이름/.codex/config.toml
• Windows (WSL): ~/.codex/config.toml

팁: 이 파일이 없다면 먼저 codex를 한 번 실행하면 .codex 폴더가 자동으로 생성됩니다. 그런 다음 config.toml 파일을 수동으로 생성하면 됩니다.

기본 설정 구조

config.toml 설정은 여러 핵심 부분으로 나뉩니다:

# ===== Basic settings =====
model = "gpt-5.3-codex"              # Model to use
model_provider = "openai"             # Model provider (default openai)
approval_policy = "on-failure"        # Approval policy
sandbox_mode = "workspace-write"      # Sandbox mode

# ===== Custom model providers =====
[model_providers.custom_name]
name = "Display name"
base_url = "API URL"
env_key = "API_KEY environment variable name"
wire_api = "responses"

# ===== Profiles =====
[profiles.profile_name]
model_provider = "custom_name"
model = "model name"

중요: wire_api는 반드시 “responses” 사용

이것은 자주 발생하는 함정입니다!

Codex CLI는 두 가지 API 프로토콜을 지원합니다: "chat"(레거시 Chat Completions)과 "responses"(새로운 Responses API)입니다.

2026년 2월부터 OpenAI는 "chat" 프로토콜을 더 이상 사용하지 않고 "responses"로 완전히 전환했습니다. 따라서 타사 모델을 구성할 때 wire_api는 반드시 "responses"로 설정해야 합니다. 타사 API 제공자가 Responses API 형식을 지원하지 않으면 Codex와 직접 연동할 수 없습니다.

다행히도 주요 API 중계 플랫폼(OpenRouter 등)은 이미 Responses API를 지원하고 있습니다.

자세한 논의는 다음을 참조하세요: https://github.com/openai/codex/discussions/7782

실전: DeepSeek 연동

DeepSeek를 예로 들어 설정 방법을 설명합니다:

1단계: config.toml 편집

# Default to DeepSeek
model_provider = "deepseek"
model = "deepseek-chat"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

2단계: 환경 변수 설정

터미널에서 DeepSeek API 키를 설정합니다:

export DEEPSEEK_API_KEY="your DeepSeek API Key"

영구적으로 설정하려면 ~/.zshrc(Mac) 또는 ~/.bashrc(Linux) 파일 끝에 다음 줄을 추가하세요:

echo 'export DEEPSEEK_API_KEY="your DeepSeek API Key"' >> ~/.zshrc
source ~/.zshrc

3단계: Codex 시작

codex

이제 Codex가 DeepSeek 모델을 사용합니다.

참고: DeepSeek 공식 API가 아직 Responses API 형식을 지원하지 않아 연결에 실패하는 경우, Responses API를 지원하는 중계 플랫폼(예: OpenRouter)으로 전환하고 base_url을 해당 중계 플랫폼 주소로 변경하세요.

실전: Volcengine (Doubao) 연동

model_provider = "volcengine"
model = "doubao-pro-32k"

[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

환경 변수도 설정해야 합니다:

export VOLCENGINE_API_KEY="your Volcengine API Key"

Profiles를 사용한 여러 모델 전환

여러 모델을 구성한 경우 Profiles를 사용하여 빠르게 전환할 수 있습니다:

# Default to OpenAI
model_provider = "openai"
model = "gpt-5.3-codex"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

# Define Volcengine provider
[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

# DeepSeek profile
[profiles.ds]
model_provider = "deepseek"
model = "deepseek-chat"

# Volcengine profile
[profiles.volc]
model_provider = "volcengine"
model = "doubao-pro-32k"

사용 시 전환:

# Use default OpenAI
codex

# Use DeepSeek
codex --profile ds

# Use Volcengine
codex --profile volc

이렇게 하면 서로 다른 모델을 자유롭게 전환할 수 있어 매우 편리합니다!

더 간단한 방법: OPENAI_BASE_URL

config.toml을 수정하지 않고 일시적으로 타사 API를 사용하려면 환경 변수를 직접 설정하면 됩니다:

export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your DeepSeek API Key"
codex

이 방법이 더 간단하지만, 터미널을 닫으면 설정이 사라집니다.

Codex CLI 사용 방법

기본 시작

Claude Code와 동일합니다:

1. 터미널을 엽니다.
2. cd 명령어로 프로젝트 폴더로 이동합니다.
3. codex를 입력하고 Enter를 누릅니다.

cd /path/to/your/project
codex

Codex가 전체 화면 터미널 인터페이스를 시작하며, 여기서 요구 사항을 입력하기 시작할 수 있습니다.

세 가지 작동 모드

Codex CLI에는 “자율성 수준"을 제어하는 세 가지 모드가 있습니다:

초보자는 Suggest 모드(기본값)를 권장합니다. Codex가 각 단계에서 무엇을 하는지 확인할 수 있습니다.

익숙해지면 Full Auto 모드를 사용하세요:

codex --full-auto "Run tests and fix all failing cases"

직접 작업 할당 (비대화형 모드)

명령어 뒤에 작업 설명을 직접 추가할 수도 있습니다:

codex "Create a Snake game for me"

이렇게 하면 Codex가 대화형 인터페이스에 진입하지 않고 바로 작업을 시작합니다.

이전 대화 이어가기

Claude Code의 --resume과 유사하게, Codex도 이전 세션을 이어갈 수 있습니다:

codex resume

이렇게 하면 중단했던 지점부터 계속 작업할 수 있습니다.

실전: Codex로 스네이크 게임 만들기

1단계: 프로젝트 폴더 생성

1. 바탕화면에 codex-demo와 같은 새 폴더를 만듭니다.
2. 터미널에서 이 폴더를 엽니다.

2단계: Codex 시작

codex

3단계: 요구 사항 입력

Codex에서 다음을 입력합니다:

Create a Snake game for me with the following requirements:

1. Features:
   - Classic Snake gameplay
   - Control snake movement with arrow keys
   - Snake grows longer when eating food, score increases
   - Game over when hitting wall or itself
   - Start and restart buttons

2. Interface:
   - Clean and beautiful, pixel style
   - Display current score and high score
   - Support dark theme

3. Technical requirements:
   - Use only HTML, CSS, JavaScript
   - All code in a single HTML file
   - Use Canvas for game rendering

Please create this HTML file directly.

4단계: Codex가 완료될 때까지 기다리기

Codex가 자동으로 HTML 파일을 생성하고 모든 코드를 작성합니다. 선택한 모드에 따라:

• Suggest 모드: 각 단계마다 확인을 요청하며, 확인 후 실행합니다.
• Full Auto 모드: 바로 모든 작업을 완료합니다.

5단계: 게임 실행

생성된 HTML 파일을 더블클릭하여 브라우저에서 실행하세요!

Codex CLI vs Claude Code: 어떻게 선택할까?

두 가지를 모두 설치하는 것을 권장합니다. 각각 장단점이 있습니다:

제 제안:

• 두 가지 모두 설치하고 작업에 따라 가장 적합한 것을 선택하세요.
• 간단한 프로젝트: 둘 다 가능하므로 아무거나 선택하세요.
• 복잡한 프로젝트: 먼저 하나를 시도해보고 결과가 좋지 않으면 다른 것으로 전환하세요.
• 국내 모델 사용자: 둘 다 타사 API 연동을 지원하며 설정 방식이 비슷합니다.

핵심 철학은 여전히: 코딩 방법을 알 필요 없이, 요구 사항을 설명하는 방법만 알면 됩니다.

요약

오늘 배운 내용:

1. Codex CLI란: OpenAI의 터미널 AI 코딩 어시스턴트, Claude Code와 유사
2. 설치 방법: npm install -g @openai/codex, 한 줄 명령어
3. 사용 방법: Claude Code와 동일한 작동 방식, cd로 프로젝트 디렉토리 이동 후 codex 실행
4. 국내 모델 연동: ~/.codex/config.toml 수정, model_providers 구성
5. 세 가지 모드: Suggest(보수적), Auto Edit(중간), Full Auto(완전 자동)
6. Profile 전환: 여러 모델 구성 후 --profile 매개변수로 자유롭게 전환

이제 두 가지 강력한 AI 코딩 도구인 Claude Code와 Codex CLI를 갖추셨습니다!