무료 모델로 Codex CLI 사용하기
Codex CLI는 OpenAI의 터미널용 오픈 소스 코딩 에이전트입니다. 사용자 지정 모델 제공업체를 쓸 수 있습니다. 이 가이드는 FreeLLMAPI를 통해 Codex CLI를 다른 제공업체의 무료 모델에 연결합니다. Codex는 Responses API를 사용하며, FreeLLMAPI는 이를 /v1/responses에서 제공합니다.
코드, 모델 이름, 실시간 카탈로그 레이블은 영어로 표시합니다.
동작 방식
Codex CLI는 OpenAI Responses 형식으로 요청을 보냅니다. Codex 문서에 따르면 responses가 지원되는 유일한 wire_api 값입니다. 따라서 Codex용 제공업체는 /v1/responses를 제공해야 합니다. FreeLLMAPI가 이 엔드포인트를 제공합니다. 각 요청을 변환하고, 무료 모델(예: Gemini, GPT-OSS, Qwen, GLM)로 보냅니다.
- 얻는 것: 무료 모델에서 동작하는 Codex CLI 에이전트, 도구, 편집 루프.
- 얻지 못하는 것: ChatGPT 요금제를 통한 OpenAI 자체 GPT 모델. 요청은 FreeLLMAPI 풀에 있는 무료 제공업체로 갑니다.
- 한계:
/v1/responses의 이미지 입력은 아직 지원되지 않습니다. 텍스트 프롬프트를 사용하세요.
1단계: FreeLLMAPI와 Codex CLI 설치하기
둘 다 설치
curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @openai/codexhttp://localhost:3001을 여세요. Keys 페이지에서 무료 제공업체 키를 두 개 이상 추가하세요. 같은 페이지에서 통합 키를 복사하세요. macOS에서는 brew install --cask codex로 Codex를 설치할 수도 있습니다.
2단계: Codex CLI 연결하기
설정 명령은 ~/.codex/config.toml에 제공업체를 추가합니다. 먼저 백업을 만들고 새 블록을 병합하므로, 다른 설정은 그대로 남습니다.
명령 한 줄
export FREELLMAPI_API_KEY=<unified-key>
npx freellmapi setup-codex --url http://localhost:3001 --dry-run
npx freellmapi setup-codex --url http://localhost:3001
codex이 명령은 실시간 카탈로그의 값으로 다음 설정을 씁니다. 키는 파일에 들어가지 않습니다. Codex는 FREELLMAPI_API_KEY 환경 변수에서 키를 읽으므로, Codex를 실행하는 각 셸에서 이 변수를 내보내세요.
~/.codex/config.toml
model = "auto"
model_provider = "freellmapi"
model_context_window = 128000
model_auto_compact_token_limit = 115200
tool_output_token_limit = 20000
[model_providers.freellmapi]
name = "FreeLLMAPI"
base_url = "http://localhost:3001/v1"
wire_api = "responses"
env_key = "FREELLMAPI_API_KEY"
requires_openai_auth = false| 키 | 동작 |
|---|---|
model_provider | model_providers에서 제공업체를 선택합니다. 기본값은 openai입니다. |
env_key | 제공업체 API 키를 담은 환경 변수 |
requires_openai_auth | false는 Codex가 OpenAI 로그인을 요구하지 않는다는 뜻입니다 |
model_context_window | 활성 모델의 컨텍스트 토큰. 명령은 실시간 카탈로그의 값을 사용합니다. |
model_auto_compact_token_limit | 자동 기록 압축을 시작하는 토큰 수. 명령은 컨텍스트 윈도우의 90%로 설정합니다. |
tool_output_token_limit | Codex가 기록에 유지하는 각 도구 출력의 토큰 예산 |
키를 파일과 셸 프로필 밖에 두려면 런처를 사용하세요. 런처는 키를 환경 변수에만 넣고 Codex를 시작합니다.
비영속 런처
npx freellmapi launch-codex요청이 게이트웨이로 가는지 확인하려면 npx freellmapi doctor를 실행하세요. 이 명령은 라우팅된 Authorization 헤더, 카탈로그, 실시간 점검을 확인합니다. 그러면 대시보드의 요청 로그에 각 Codex 호출이 표시됩니다. X-Routed-Via 응답 헤더는 응답한 제공업체와 모델의 이름을 보여 줍니다. 요청이 실패 전환되었다면 X-Fallback-Trail이 실패한 각 단계와 이유를 보여 줍니다.
[profiles.NAME] 테이블을 config.toml에서 더 이상 읽지 않습니다. 이제 프로필은 별도 파일입니다. 예: ~/.codex/NAME.config.toml. 최신 Codex 버전에서는 위의 기본 설정을 사용하세요.모델 메타데이터 경고 제거
Codex는 실행할 때마다 "Model metadata for auto not found"를 출력합니다. Codex는 게이트웨이의 모델 ID를 알지 못합니다. 컨텍스트 윈도우와 이미지 지원 같은 실제 메타데이터를 주려면 제공업체에 모델 카탈로그 URL을 추가하세요.
[model_providers.freellmapi]에 추가
model_catalog_url = "http://localhost:3001/v1/codex/models"카탈로그는 Codex의 기본 시스템 프롬프트와 도구 설정을 유지합니다. 바뀌는 것은 경고와 컨텍스트 윈도우뿐입니다.
Codex CLI용 모델 선택하기
Codex는 에이전트입니다. 도구 호출로 셸 명령을 실행하고 파일을 편집합니다. 도구 호출을 지원하고 컨텍스트 윈도우가 큰 모델을 사용하세요. 아래 표는 현재 두 조건을 모두 충족하는 무료 모델을 보여 줍니다.
| 모델 | 무료 제공 | 컨텍스트 | 무료 한도 (가장 좋은 조건) | 도구 | 비전 |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 요청/분 1 req/min per model | 예 | 아니요 |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 요청/분 40 RPM | 예 | 예 |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 예 | 예 |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | 예 | 아니요 |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | 예 | 예 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 요청/분 20 요청/일 250,000 토큰/분 ~3M | 예 | 예 |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | 예 | 예 |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 요청/분 50 요청/일 50 req/day account-wide (1,000 after a $10 purchase) | 예 | 예 |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 요청/분 50 요청/일 Shared rate limit | 예 | 아니요 |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 요청/분 250 요청/일 70,000 토큰/분 ~6M | 예 | 예 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 요청/분 20 요청/일 250,000 토큰/분 ~3M | 예 | 예 |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | 예 | 예 |
일치하는 무료 모델 109개 중 12개를 표시합니다. 모든 모델 보기.
FreeLLMAPI 카탈로그의 실시간 데이터입니다 (버전 2026.11.19, 2026-11-19 확인). 무료 한도는 자주 바뀝니다. 카탈로그는 매일 확인합니다.
model = "auto"를 유지하면 라우터가 요청마다 모델을 고릅니다. 모델 하나를 고정하려면 npx freellmapi setup-codex --url http://localhost:3001 --model <id>를 실행하세요. model = "auto:smart" 또는 model = "auto:fast"를 config.toml에 설정할 수도 있습니다.
무료 요금제에는 분당 한도와 일일 한도가 있습니다. 제공업체가 429 오류를 보내면 FreeLLMAPI는 요청을 체인의 다음 모델로 보냅니다. 긴 Codex 세션에는 제공업체 네 곳 이상의 키를 추가하세요. Codex는 model_auto_compact_token_limit에 도달하면 기록을 압축합니다. 값을 낮추면 요청이 더 작아지며, 분당 토큰 한도가 낮은 무료 요금제에 도움이 됩니다.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| Codex가 ChatGPT로 로그인하라고 요청합니다 | model_provider가 설정되지 않아 Codex가 openai를 사용합니다 | model_provider = "freellmapi"로 설정하세요 |
401 "Invalid API key" | 이 셸에 FREELLMAPI_API_KEY가 설정되지 않았습니다 | 변수를 내보내거나 npx freellmapi launch-codex를 사용하세요 |
"Model metadata for auto not found" | Codex가 게이트웨이의 모델 ID를 알지 못합니다 | model_catalog_url을 추가하세요 |
wire_api = "chat"을 사용할 때 오류 | Codex는 Responses API만 지원합니다 | wire_api = "responses"로 설정하세요 |
| 프로필 설정이 무시됩니다 | Codex 0.134.0 이상은 [profiles.NAME] 테이블을 무시합니다 | 기본 제공업체 설정을 쓰거나 별도의 프로필 파일을 사용하세요 |
| "All models rate-limited after N attempts" (N회 시도 후 모든 모델이 속도 제한에 걸림) | 모든 키가 한도에 도달했습니다 | 더 많은 제공업체의 키를 추가하거나 쿨다운이 끝날 때까지 기다리세요 |
자주 묻는 질문
Codex CLI를 무료로 사용할 수 있나요?
네. Codex CLI는 오픈 소스입니다. config.toml에서 FreeLLMAPI를 사용자 지정 모델 제공업체로 추가하세요. 게이트웨이가 각 요청을 무료 제공업체 요금제로 보내므로 추론 비용은 $0입니다.
Codex CLI가 다른 제공업체의 모델을 쓸 수 있나요?
네. base_url, env_key, wire_api = "responses"를 포함한 [model_providers.
Codex CLI는 Chat Completions API를 지원하나요?
아니요. Codex 설정 참고 문서는 responses가 지원되는 유일한 wire_api 값이라고 밝힙니다. FreeLLMAPI는 /v1/responses를 제공하므로 Codex 제공업체로 동작합니다.
Codex CLI에 가장 좋은 무료 모델은 무엇인가요?
도구 호출을 지원하고 컨텍스트가 최소 128K인 모델을 사용하세요. 이 페이지의 표는 현재 두 조건을 모두 충족하는 가장 강력한 무료 모델을 보여 줍니다.
'Model metadata for auto not found' 오류는 어떻게 고치나요?
~/.codex/config.toml의 제공업체 블록에 model_catalog_url = "http://localhost:3001/v1/codex/models"를 추가하세요. 그러면 Codex가 게이트웨이 모델의 실제 메타데이터를 읽습니다.
관련 가이드
- Claude Code를 무료로 사용하는 방법
- 무료 LLM API로 OpenCode 사용하기
- 무료 LLM API로 Aider 사용하기
- 최고의 무료 코딩 모델 API
- 무료 GPT API가 있나요?
출처
- Codex docs: config reference (20 November 2026 확인)
- Codex docs: advanced config and profiles (20 November 2026 확인)
- Codex CLI repository (20 November 2026 확인)
- FreeLLMAPI docs: coding agents and Codex (20 November 2026 확인)
- FreeLLMAPI CLI generators (20 November 2026 확인)