OpenAI Codex CLI 설정 가이드

업데이트: 2026-06-06

Codex CLI는 OpenAI의 터미널 코딩 에이전트 도구로, 로컬 저장소에서 코드 수정, 리뷰, 일괄 리팩터링, 명령 협업 작업에 적합합니다. Crazyrouter와 연동할 때는 이전 방식이 아니라 현재 공식으로 지원되는 config.toml 사용자 지정 provider 방식을 사용하는 것을 권장합니다.

개요

~/.codex/config.toml에 사용자 지정 provider를 설정하면 Codex CLI가 요청을 Crazyrouter로 보낼 수 있습니다.

권장 프로토콜: OpenAI-compatible API
사용하는 인터페이스 유형: Responses API
Base URL: https://api.crazyrouter.com/v1
인증 변수: OPENAI_API_KEY
권장 기본 모델: gpt-5.5

이전에 ChatGPT 로그인 방식만 사용했다면, Crazyrouter와 연동할 때는 API Key + 사용자 지정 provider 설정 방식으로 전환하세요. 이렇게 하면 모델, 로그, 할당량, 과금을 더 세밀하게 제어할 수 있습니다.

Codex 원클릭 설정 저장소 보기

스크립트로 환경 변수와 Codex 설정을 바로 작성하고 싶다면 crazyrouter-codex-cli 저장소를 확인하세요.

이런 분들께 적합합니다

Crazyrouter를 터미널 에이전트형 코딩 워크플로에 연동하고 싶은 분
로컬 저장소에서 일괄 수정, 코드 리뷰, 자동 실행을 하고 싶은 분
Codex, Cursor, Claude Code의 트래픽을 분리하여 과금하고 싶은 분
현재 검증된 최신 OpenAI 모델을 터미널 에이전트 코딩에 우선적으로 사용하고 싶은 분

사용 프로토콜

권장 프로토콜: OpenAI-compatible API Codex CLI는 현재 사용자 지정 model_provider를 통해 OpenAI 호환 provider를 사용하는 것을 권장하며, 다음을 지정해야 합니다.

base_url = "https://api.crazyrouter.com/v1"
wire_api = "responses"

Crazyrouter는 /v1/responses를 지원하므로 Codex CLI의 이 연동 방식은 Responses API를 바로 사용할 수 있습니다. 다만 현재 이 경로는 GPT 모델 기준으로 이해하시면 되며, Claude는 POST /v1/responses를 지원하지 않습니다.

시스템 요구 사항 및 사전 준비

항목	설명
Crazyrouter 계정	먼저 crazyrouter.com에서 가입
Crazyrouter token	Codex 전용 `sk-...` token을 별도로 생성하는 것을 권장
Git	`git 2.23+` 권장
Node.js	`Node.js 20+` 권장
Codex CLI	현재 안정 버전 권장
사용 가능한 모델	코딩에 적합한 모델을 최소 1개 이상 허용, 예: `gpt-5.5`

권장 초기 화이트리스트:

gpt-5.5

운영체제별 전체 설치 경로

Windows 권장 경로

Windows에서 Codex의 가장 간단한 경로는 Git + Node.js + npm 전역 설치 Codex + PowerShell 환경 변수 설정입니다. 권장 순서:

Git 설치
Node.js LTS 설치
npm으로 Codex CLI 설치
PowerShell로 OPENAI_API_KEY 작성
PowerShell로 $HOME/.codex/config.toml 작성

권장 검증 명령:

git --version
node -v
npm -v
codex --version
where.exe git
where.exe node
where.exe codex

codex --version 명령을 찾을 수 없다면 PowerShell을 닫았다가 다시 열고 재시도하세요.

macOS 권장 경로

macOS에서 가장 편리한 경로는 보통 Homebrew + Git + Node.js + brew 또는 npm으로 Codex CLI 설치 + ~/.zshrc에 환경 변수 영구 저장입니다. 권장 순서:

Xcode Command Line Tools 설치
Homebrew 설치(아직 없다면)
Git, Node.js 설치
Codex CLI 설치
~/.zshrc에 작성
~/.codex/config.toml에 작성

권장 검증 명령:

git --version
node -v
npm -v
codex --version
which git
which node
which codex

Codex CLI 설치 대안 경로

패키지 매니저 외에도 Codex 공식 저장소는 GitHub Releases 바이너리 패키지를 제공합니다. 대부분의 사용자에게는 여전히 다음을 우선 권장합니다.

Windows: npm install -g @openai/codex
macOS: brew install --cask codex 또는 npm install -g @openai/codex

스크립트로 Crazyrouter 관련 설정을 자동으로 작성하고 싶다면 crazyrouter-codex-cli를 확인하세요. 이 저장소는 Windows, macOS, Linux용 원클릭 설정 스크립트를 제공합니다. 이 문서에서는 각 설정 항목을 직접 검토할 수 있도록 전체 수동 설정 절차도 계속 유지합니다.

처음부터 완전 설치

1단계: Git 설치

아직 Git이 없다면 먼저 Git을 설치하고 전역 사용자 정보 설정을 완료하세요.

Windows PowerShell
macOS
Ubuntu / Debian

winget install --id Git.Git -e --source winget
git --version

xcode-select --install
git --version

또는:

brew install git
git --version

sudo apt update
sudo apt install -y git
git --version

이어서 다음도 실행하는 것을 권장합니다.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

2단계: Node.js 20+ 설치

Codex CLI는 Node.js 도구입니다. 먼저 Node와 npm이 준비되었는지 확인하세요.

Windows PowerShell
macOS
Ubuntu / Debian

winget install OpenJS.NodeJS.LTS
node -v
npm -v

brew install node
node -v
npm -v

sudo apt update
sudo apt install -y nodejs npm
node -v
npm -v

사용 중인 배포판의 기본 설치 버전이 너무 오래되었다면 더 높은 버전으로 업그레이드한 후 계속 진행하세요.

3단계: Codex CLI 설치

Windows PowerShell
macOS

npm으로 전역 설치하는 것을 권장합니다.

npm install -g @openai/codex
codex --version
where.exe codex

Homebrew를 우선 사용하는 것을 권장합니다.

brew install --cask codex
codex --version
which codex

npm이 더 익숙하다면 다음도 가능합니다.

npm install -g @openai/codex
codex --version
which codex

4단계: Crazyrouter에서 Codex 전용 token 생성

Crazyrouter 백엔드에서 codex라는 이름의 token을 새로 생성하세요. 처음에는 다음만 허용하는 것을 권장합니다.

gpt-5.5

이렇게 하면 처음 문제를 해결하기가 더 쉽고 비용 관리도 더 용이합니다.

5단계: 먼저 임시 환경 변수 설정

Codex는 provider 설정을 통해 OPENAI_API_KEY를 읽습니다. 먼저 현재 터미널에서 설정하세요.

Linux / macOS
Windows PowerShell

export OPENAI_API_KEY=sk-xxx
echo $OPENAI_API_KEY

$env:OPENAI_API_KEY = "sk-xxx"
echo $env:OPENAI_API_KEY

6단계: API Key를 영구 환경 변수로 작성

평소에는 shell 설정 파일이나 시스템 사용자 환경 변수에 작성하는 것을 권장합니다.

Linux Bash
macOS / Zsh
Windows PowerShell

echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.bashrc
source ~/.bashrc

echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx", "User")
$env:OPENAI_API_KEY = "sk-xxx"

7단계: Codex 설정 파일 ~/.codex/config.toml 작성

Codex CLI는 시작할 때 ~/.codex/config.toml을 읽습니다.

macOS
Windows PowerShell

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.crazyrouter]
model = "gpt-5.5"
model_provider = "crazyrouter"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
EOF

New-Item -ItemType Directory -Force "$HOME/.codex" | Out-Null
@'
model = "gpt-5.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.crazyrouter]
model = "gpt-5.5"
model_provider = "crazyrouter"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
'@ | Set-Content -Path "$HOME/.codex/config.toml"

설정 후에는 다음으로 확인할 수 있습니다.

macOS
Windows PowerShell

cat ~/.codex/config.toml

Get-Content $HOME/.codex/config.toml

8단계: Git 저장소 준비 및 첫 스냅샷 생성

디렉터리가 아직 Git 저장소가 아니라면:

git init
git add .
git commit -m "chore: initial snapshot before Codex"

이미 기존 저장소라면 최소한 다음을 먼저 확인하세요.

git status

9단계: Codex 시작 및 첫 검증 완료

저장소 디렉터리로 이동한 후 먼저 최소한의 검증을 해볼 수 있습니다.

cd /path/to/your/project
codex --profile crazyrouter "Reply only OK"

성공하면 대화형 모드로 들어갈 수 있습니다.

codex --profile crazyrouter

첫 검증은 다음 순서로 진행하는 것을 권장합니다.

Reply only OK
Read the repository structure only. Do not edit files.
Find the highest-risk file in this repo and explain why, but do not change anything.

권장 모델 설정

사용 시나리오	권장 모델	이유
기본 주력 코딩	`gpt-5.5`	2026년 3월 23일 프로덕션 환경에서 실측 성공했으며, Codex / Responses API의 주 기준선으로 적합

Claude가 필요하다면 Claude 네이티브 POST /v1/messages 또는 OpenAI 호환 POST /v1/chat/completions를 사용하세요. Claude를 이 wire_api = "responses" 경로의 Codex에 설정하지 마세요.

국산 모델 네이티브 지원 현황

2026-05-15 프로덕션 재검증을 기준으로, Crazyrouter에서 **네이티브 POST /v1/responses**를 통해 Codex CLI가 정상적으로 소비할 수 있는 국산 모델은 현재 다음 기준으로만 공개하는 것을 권장합니다.

모델	현재 결론	설명
`kimi-k2.5`	권장	`/v1/responses` SSE가 `response.completed`까지 완전히 반환되며, Codex의 간단한 응답과 파일 읽기 모두 통과
`kimi-k2.6`	권장	`kimi-k2.5`와 같은 등급이며, 현재 국산 모델 주력 후보로 사용 가능
`MiniMax-M2.7`	아직 비권장	최소 Responses 프로브에서 `convert_request_failed`가 발생했으며, 파일 읽기 작업도 `response.completed` 이전에 끊김
`deepseek-v4-pro`	아직 비권장	Claude Code에서는 사용 가능하지만, Codex의 이 Responses 경로에서는 여전히 500 / 높은 수요 / 재연결 실패가 발생
`glm-5.1`	아직 비권장	현재 프로덕션 Responses 네이티브 라우팅이 해당 모델을 지원하지 않는 상류로 떨어져, Codex에서 `stream closed before response.completed` 오류 발생

Codex에서 국산 모델을 시험해보고 싶다면 먼저 token 화이트리스트를 다음으로 좁히는 것을 권장합니다.

gpt-5.5
kimi-k2.5
kimi-k2.6

실험적 동작과 스트림 끊김 재시도를 명확히 감수할 수 있는 경우가 아니라면, MiniMax-M2.7, deepseek-v4-pro, glm-5.1을 Codex 기본 화이트리스트에 바로 추가하지 않는 것을 권장합니다.

국산 모델로 전환하는 방법

base_url = "https://api.crazyrouter.com/v1"과 wire_api = "responses"는 그대로 두고 model 필드만 교체하면 됩니다. 예:

model = "kimi-k2.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.crazyrouter]
model = "kimi-k2.5"
model_provider = "crazyrouter"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

국산 모델로 처음 전환할 때도 다음 순서로 검증하는 것을 권장합니다.

Reply only OK
Read the repository structure only. Do not edit files.
Read agent.md and reply with exactly the first Markdown heading text.

Token 설정 모범 사례

설정	권장	설명
전용 token	필수	Codex는 Cursor, Claude Code와 token을 공유하지 않아야 함
모델 화이트리스트	강력 권장	Codex가 실제로 호출할 모델만 허용
IP 제한	고정 출구 환경이라면 활성화 권장	개인 기기가 네트워크를 자주 바꾼다면 신중히 사용
할당량 상한	강력 권장	Codex의 에이전트형 실행은 할당량을 빠르게 소모하기 쉬움
환경 격리	권장	로컬 개발, 원격 서버, CI에서 서로 다른 token 사용
유출 처리	즉시 교체	shell 히스토리, 설정 백업, 화면 공유로 token이 노출되면 즉시 교체해야 함

검증 체크리스트

자주 발생하는 오류와 해결

증상	흔한 원인	해결 방법
`codex: command not found`	CLI가 설치되지 않았거나, 전역 npm 디렉터리가 PATH에 없음	Codex를 재설치하고 npm 전역 bin이 PATH에 포함되었는지 확인
401 unauthorized	`OPENAI_API_KEY`가 잘못되었거나 만료되었거나, 복사 시 공백이 포함됨	token을 새로 생성하고 환경 변수를 다시 설정
403 / model not allowed	token이 현재 모델을 허용하지 않음	Crazyrouter token 설정에서 해당 모델을 허용
404	`base_url`이 잘못 작성되었거나 `/v1`이 빠짐	`https://api.crazyrouter.com/v1`로 수정
요청 구조 오류	`wire_api`가 `responses`가 아님	`wire_api = "responses"`로 수정
CLI는 시작되지만 요청이 Crazyrouter로 가지 않음	`model_provider`가 `crazyrouter`로 전환되지 않음	`config.toml`의 provider 설정 확인
Git 변경 내용을 검토하기 어려움	저장소 스냅샷을 먼저 생성하지 않음	초기 스냅샷을 먼저 커밋한 후 Codex가 실제 수정을 하도록 함
비용이 너무 빠르게 증가함	긴 컨텍스트, 다중 라운드 도구 호출, 또는 여러 저장소가 하나의 token을 공유	token을 분리하고, 한도를 설정하고, 모델 화이트리스트를 축소

성능 및 비용 권장 사항

처음 연동 시 작은 저장소로 먼저 검증하고, 바로 대규모 저장소에서 전체 작업을 실행하지 마세요
기본 주력으로는 gpt-5.5를 권장하며, 먼저 GPT / Responses 경로를 검증하세요
Codex와 IDE 도구를 분리하여 계산하면 고비용 발생 지점을 파악하기 쉽습니다
고위험 저장소나 CI 시나리오에는 더 엄격한 token 할당량을 설정하세요
비정상적으로 높은 비용이 발생할 때마다, 먼저 Crazyrouter 로그를 확인하여 다중 라운드 에이전트 동작으로 인한 것인지 확인하세요

FAQ

Codex CLI에는 어떤 Base URL을 작성해야 하나요?

https://api.crazyrouter.com/v1로 작성하세요.

Windows에서는 PowerShell과 Git Bash 중 어느 쪽을 권장하나요?

처음 설정할 때는 문서의 PowerShell 경로를 우선 따르는 것이 좋습니다. 사용자 수준 환경 변수와 $HOME/.codex/config.toml을 가장 일치시키기 쉽습니다.

여기서 왜 `wire_api = "responses"`로 설정해야 하나요?

현재 Codex CLI의 사용자 지정 provider는 Responses API를 통해 작동하는 것을 권장하며, Crazyrouter가 /v1/responses를 지원하기 때문입니다.

여기서 왜 더 이상 Claude를 권장하지 않나요?

Claude는 현재 POST /v1/messages와 POST /v1/chat/completions만 지원하며, POST /v1/responses는 지원하지 않기 때문입니다. Codex의 이 연동 방식은 wire_api = "responses"로 고정되어 있으므로, Claude를 이 경로의 권장 모델로 삼지 않아야 합니다.

처음에 왜 Git 스냅샷을 먼저 만드는 것을 권장하나요?

Codex는 파일을 수정하고 명령을 실행하는 에이전트이기 때문입니다. 먼저 스냅샷을 만들어 두면 리뷰와 롤백이 훨씬 수월해집니다.

이미 `codex login`을 했다면 API Key를 설정할 필요가 있나요?

필요합니다. Crazyrouter와 연동할 때는 여전히 OPENAI_API_KEY와 사용자 지정 provider 설정을 사용해야 합니다.

첫 번째로 권장하는 모델은 무엇인가요?

먼저 gpt-5.5를 사용하세요.

OpenAI / Responses API 경로에서 가장 편리한 터미널 에이전트 경험을 우선 얻고 싶다면, Codex는 GPT / Responses 경로로 설정해야 합니다. Claude를 우선 사용하고 싶다면 Claude Code 또는 Claude 네이티브 인터페이스 문서를 참고하세요.

crazyrouter-codex-cli 저장소 보기

원클릭 설정 스크립트, README, 최신 사용 안내를 확인하세요.

API 키 & 콘솔 관리

SDK & 코드 예제

서드파티 연동

OpenAI Codex CLI 설정 가이드

개요

Codex 원클릭 설정 저장소 보기

이런 분들께 적합합니다

사용 프로토콜

시스템 요구 사항 및 사전 준비

운영체제별 전체 설치 경로

Windows 권장 경로

macOS 권장 경로

Codex CLI 설치 대안 경로

처음부터 완전 설치

권장 모델 설정

국산 모델 네이티브 지원 현황

국산 모델로 전환하는 방법

Token 설정 모범 사례

검증 체크리스트

자주 발생하는 오류와 해결

성능 및 비용 권장 사항

FAQ

Codex CLI에는 어떤 Base URL을 작성해야 하나요?

Windows에서는 PowerShell과 Git Bash 중 어느 쪽을 권장하나요?

여기서 왜 `wire_api = "responses"`로 설정해야 하나요?

여기서 왜 더 이상 Claude를 권장하지 않나요?

처음에 왜 Git 스냅샷을 먼저 만드는 것을 권장하나요?

이미 `codex login`을 했다면 API Key를 설정할 필요가 있나요?

첫 번째로 권장하는 모델은 무엇인가요?

crazyrouter-codex-cli 저장소 보기

​개요

Codex 원클릭 설정 저장소 보기

​이런 분들께 적합합니다

​사용 프로토콜

​시스템 요구 사항 및 사전 준비

​운영체제별 전체 설치 경로

​Windows 권장 경로

​macOS 권장 경로

​Codex CLI 설치 대안 경로

​처음부터 완전 설치

​권장 모델 설정

​국산 모델 네이티브 지원 현황

​국산 모델로 전환하는 방법

​Token 설정 모범 사례

​검증 체크리스트

​자주 발생하는 오류와 해결

​성능 및 비용 권장 사항

​FAQ

​Codex CLI에는 어떤 Base URL을 작성해야 하나요?

​Windows에서는 PowerShell과 Git Bash 중 어느 쪽을 권장하나요?

​여기서 왜 wire_api = "responses"로 설정해야 하나요?

​여기서 왜 더 이상 Claude를 권장하지 않나요?

​처음에 왜 Git 스냅샷을 먼저 만드는 것을 권장하나요?

​이미 codex login을 했다면 API Key를 설정할 필요가 있나요?

​첫 번째로 권장하는 모델은 무엇인가요?

crazyrouter-codex-cli 저장소 보기

개요

이런 분들께 적합합니다

사용 프로토콜

시스템 요구 사항 및 사전 준비

운영체제별 전체 설치 경로

Windows 권장 경로

macOS 권장 경로

Codex CLI 설치 대안 경로

처음부터 완전 설치

권장 모델 설정

국산 모델 네이티브 지원 현황

국산 모델로 전환하는 방법

Token 설정 모범 사례

검증 체크리스트

자주 발생하는 오류와 해결

성능 및 비용 권장 사항

FAQ

Codex CLI에는 어떤 Base URL을 작성해야 하나요?

Windows에서는 PowerShell과 Git Bash 중 어느 쪽을 권장하나요?

여기서 왜 `wire_api = "responses"`로 설정해야 하나요?

여기서 왜 더 이상 Claude를 권장하지 않나요?

처음에 왜 Git 스냅샷을 먼저 만드는 것을 권장하나요?

이미 `codex login`을 했다면 API Key를 설정할 필요가 있나요?

첫 번째로 권장하는 모델은 무엇인가요?