> ## Documentation Index > Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Codex CLI 설정 가이드 > Codex CLI에서 Crazyrouter를 사용자 지정 provider로 설정하여 OpenAI Responses API에 연결하는 방법과 Git, Node.js, 설치 명령, 설정 파일, 환경 변수 작성까지의 전체 절차 > 업데이트: 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 설정을 바로 작성하고 싶다면 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](https://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 환경 변수 설정`입니다. 권장 순서: 1. Git 설치 2. Node.js LTS 설치 3. npm으로 Codex CLI 설치 4. PowerShell로 `OPENAI_API_KEY` 작성 5. PowerShell로 `$HOME/.codex/config.toml` 작성 권장 검증 명령: ```powershell theme={null} 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`에 환경 변수 영구 저장입니다. 권장 순서: 1. Xcode Command Line Tools 설치 2. Homebrew 설치(아직 없다면) 3. Git, Node.js 설치 4. Codex CLI 설치 5. `~/.zshrc`에 작성 6. `~/.codex/config.toml`에 작성 권장 검증 명령: ```bash theme={null} 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](https://github.com/xujfcn/crazyrouter-codex-cli)를 확인하세요. 이 저장소는 Windows, macOS, Linux용 원클릭 설정 스크립트를 제공합니다. 이 문서에서는 각 설정 항목을 직접 검토할 수 있도록 전체 수동 설정 절차도 계속 유지합니다. ## 처음부터 완전 설치 아직 Git이 없다면 먼저 Git을 설치하고 전역 사용자 정보 설정을 완료하세요. ```powershell theme={null} winget install --id Git.Git -e --source winget git --version ``` ```bash theme={null} xcode-select --install git --version ``` 또는: ```bash theme={null} brew install git git --version ``` ```bash theme={null} sudo apt update sudo apt install -y git git --version ``` 이어서 다음도 실행하는 것을 권장합니다. ```bash theme={null} git config --global user.name "Your Name" git config --global user.email "you@example.com" git config --global init.defaultBranch main ``` Codex CLI는 Node.js 도구입니다. 먼저 Node와 npm이 준비되었는지 확인하세요. ```powershell theme={null} winget install OpenJS.NodeJS.LTS node -v npm -v ``` ```bash theme={null} brew install node node -v npm -v ``` ```bash theme={null} sudo apt update sudo apt install -y nodejs npm node -v npm -v ``` 사용 중인 배포판의 기본 설치 버전이 너무 오래되었다면 더 높은 버전으로 업그레이드한 후 계속 진행하세요. npm으로 전역 설치하는 것을 권장합니다. ```powershell theme={null} npm install -g @openai/codex codex --version where.exe codex ``` Homebrew를 우선 사용하는 것을 권장합니다. ```bash theme={null} brew install --cask codex codex --version which codex ``` npm이 더 익숙하다면 다음도 가능합니다. ```bash theme={null} npm install -g @openai/codex codex --version which codex ``` Crazyrouter 백엔드에서 `codex`라는 이름의 token을 새로 생성하세요. 처음에는 다음만 허용하는 것을 권장합니다. * `gpt-5.5` 이렇게 하면 처음 문제를 해결하기가 더 쉽고 비용 관리도 더 용이합니다. Codex는 provider 설정을 통해 `OPENAI_API_KEY`를 읽습니다. 먼저 현재 터미널에서 설정하세요. ```bash theme={null} export OPENAI_API_KEY=sk-xxx echo $OPENAI_API_KEY ``` ```powershell theme={null} $env:OPENAI_API_KEY = "sk-xxx" echo $env:OPENAI_API_KEY ``` 평소에는 shell 설정 파일이나 시스템 사용자 환경 변수에 작성하는 것을 권장합니다. ```bash theme={null} echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.bashrc source ~/.bashrc ``` ```bash theme={null} echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.zshrc source ~/.zshrc ``` ```powershell theme={null} [System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx", "User") $env:OPENAI_API_KEY = "sk-xxx" ``` Codex CLI는 시작할 때 `~/.codex/config.toml`을 읽습니다. ```bash theme={null} 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 ``` ```powershell theme={null} 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" ``` 설정 후에는 다음으로 확인할 수 있습니다. ```bash theme={null} cat ~/.codex/config.toml ``` ```powershell theme={null} Get-Content $HOME/.codex/config.toml ``` 디렉터리가 아직 Git 저장소가 아니라면: ```bash theme={null} git init git add . git commit -m "chore: initial snapshot before Codex" ``` 이미 기존 저장소라면 최소한 다음을 먼저 확인하세요. ```bash theme={null} git status ``` 저장소 디렉터리로 이동한 후 먼저 최소한의 검증을 해볼 수 있습니다. ```bash theme={null} cd /path/to/your/project codex --profile crazyrouter "Reply only OK" ``` 성공하면 대화형 모드로 들어갈 수 있습니다. ```bash theme={null} codex --profile crazyrouter ``` 첫 검증은 다음 순서로 진행하는 것을 권장합니다. 1. `Reply only OK` 2. `Read the repository structure only. Do not edit files.` 3. `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` 필드만 교체하면 됩니다. 예: ```toml theme={null} 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" ``` 국산 모델로 처음 전환할 때도 다음 순서로 검증하는 것을 권장합니다. 1. `Reply only OK` 2. `Read the repository structure only. Do not edit files.` 3. `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이 노출되면 즉시 교체해야 함 | ## 검증 체크리스트 * [ ] `git --version` 정상 * [ ] `node -v` 정상 * [ ] `codex --version` 정상 * [ ] `OPENAI_API_KEY`가 올바르게 설정됨 * [ ] `~/.codex/config.toml`에 `model_provider = "crazyrouter"`가 작성됨 * [ ] `base_url`이 `https://api.crazyrouter.com/v1`로 설정됨 * [ ] `wire_api`가 `responses`로 설정됨 * [ ] 첫 요청이 성공적으로 반환됨 * [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있음 * [ ] 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 네이티브 인터페이스 문서를 참고하세요. 원클릭 설정 스크립트, README, 최신 사용 안내를 확인하세요.