Codex CLI 커스텀 모델 프로바이더 설정 방법은 세 단계다. ~/.codex/config.toml에 [model_providers.<id>] 테이블을 정의하고, 프로필에서 그 프로바이더와 모델을 지정한 뒤, codex --profile <이름>으로 실행한다. 이때 커스텀 프로바이더에는 wire_api = "responses"가 반드시 들어가야 한다. Chat Completions 지원은 2026년 2월 제거와 함께 하드 에러로 전환된다고 공지됐다.
프로필 형식도 버전에 따라 다르다. Codex 0.134.0 이상은 ~/.codex/<이름>.config.toml 별도 파일을 쓰고, 0.134.0 이전 버전은 config.toml 안의 [profiles.<name>] 테이블을 쓴다. 아래 절차는 Hugging Face Inference Providers 라우터와 로컬 Ollama 두 사례를 기준으로 한다. 공식 문서 인용은 2026-11 기준이다.
목차
적용 대상과 버전별 차이
이 글이 다루는 범위는 OpenAI Codex CLI가 OpenAI 기본 모델 대신 OpenAI 호환 엔드포인트로 요청을 보내도록 구성하는 경우다. 엔드포인트 예시는 두 가지다.
| 사례 | base_url | 인증 |
|---|---|---|
| Hugging Face Inference Providers 라우터 | https://router.huggingface.co/v1 |
env_key = "HF_TOKEN" |
| 로컬 Ollama | http://localhost:11434/v1/ |
공식 예시에 env_key 없음 |
wire_api = "chat" 제거
OpenAI 메인테이너 etraut-openai는 2025-12-09 Codex의 chat/completions 지원 중단 공지(#7782)에서 Chat Completions API 지원을 2026년 2월 초에 완전히 제거한다고 밝혔다. 지원 중단 기간이 끝나면 경고가 아니라 하드 에러가 된다.
영향을 받는 설정은 두 종류다. 공지 원문은 "If you have configured a custom model provider with wire_api = "chat" or have not specified a wire_api, you will need to update your model provider definition"이다. wire_api = "chat"으로 적어 둔 정의와 wire_api 키를 아예 생략한 정의 모두 wire_api = "responses"로 고쳐야 한다.
로컬 모델 사용자에게는 LM Studio의 responses API를 쓰거나 oss_provider = "lmstudio"로 설정하라는 안내가 함께 실렸다.
#7782 공지에는 chat 지원이 제거되는 정확한 Codex 버전 번호가 적혀 있지 않고 시점(2026년 2월 초)만 나온다. 버전으로 판단하기보다 설정 파일의 `wire_api` 값을 직접 확인하는 쪽이 확실하다.
Hugging Face의 Codex 연동 문서는 프로필을 ~/.codex/huggingface.config.toml 같은 별도 파일로 만들고, 그 파일 최상위에 model_provider와 model을 둔다. 같은 문서의 주의 문장은 "For Codex versions before 0.134.0, you have to define profiles in a [profiles.
정리하면 프로바이더 정의([model_providers.<id>])는 보통 config.toml에 두지만, 뒤에 나올 Ollama 프로필 예시처럼 프로필 파일 안에 함께 정의하는 경우도 있다. 프로필의 위치는 버전에 따라 갈린다.
~/.codex/
├── config.toml ← [model_providers.huggingface] 정의
├── huggingface.config.toml ← 0.134.0 이상: HF 프로필
└── ollama-launch.config.toml ← 0.134.0 이상: Ollama 프로필(프로바이더 정의 포함)
시작 전 준비 사항
Hugging Face 경로의 전제 조건은 공식 문서 기준 두 가지다. Codex CLI가 설치돼 있어야 하고, ‘Make calls to Inference Providers’ 권한을 가진 Hugging Face API 토큰이 필요하다. 토큰은 HF_TOKEN 환경 변수로 넘긴다. 추론 비용을 개인 계정이 아닌 조직에 청구하려면 해당 조직의 Write 권한도 있어야 한다.
Ollama 경로는 설치 명령이 문서에 명시돼 있다. Ollama의 Codex CLI 설정 문서는 npm install -g @openai/codex로 Codex를 설치하라고 안내한다. 전제 조건 원문은 "Use a context window of at least 64k tokens for Codex."로, 컨텍스트 창을 최소 64k 토큰으로 맞춰야 한다.
| 항목 | Hugging Face | Ollama |
|---|---|---|
| Codex CLI 설치 | 필요 | npm install -g @openai/codex |
| 토큰·권한 | ‘Make calls to Inference Providers’ 권한 토큰, HF_TOKEN |
— |
| 조직 청구 | 조직 Write 권한 | — |
| 컨텍스트 창 | — | 최소 64k 토큰 |
Hugging Face 라우터를 커스텀 모델 프로바이더로 등록하기
Hugging Face Inference Providers 라우터는 OpenAI 호환 엔드포인트로 동작한다. 아래 순서는 공식 문서의 Quick Setup을 그대로 따른다.
1단계: 토큰 환경 변수 설정
export HF_TOKEN=hf_...
hf_... 부분에 실제 토큰 값을 넣는다. 프로바이더 정의의 env_key가 이 변수 이름을 가리키므로 두 값의 철자가 같아야 한다.
2단계: config.toml에 model_providers 테이블 추가
~/.codex/config.toml에 다음 블록을 넣는다.
[model_providers.huggingface]
name = "Hugging Face"
base_url = "https://router.huggingface.co/v1"
env_key = "HF_TOKEN"
wire_api = "responses"
각 키의 역할은 이렇다. name은 표시용 이름, base_url은 요청을 보낼 라우터 주소다. 인증 토큰을 읽어 올 환경 변수는 env_key가 지정한다. 마지막 wire_api = "responses"는 요청을 OpenAI 호환 Responses API로 라우팅하는 설정이며, Hugging Face 문서도 "Codex custom providers require wire_api = "responses""라고 팁으로 강조한다.
추론 비용을 Hugging Face 조직에 청구하려면 같은 테이블 끝에 http_headers = { "X-HF-Bill-To" = "your-org-name" } 한 줄을 추가하고 your-org-name을 조직 이름으로 바꾼다.
3단계: 프로필 작성
0.134.0 이상에서는 ~/.codex/huggingface.config.toml 파일을 새로 만든다.
model_provider = "huggingface"
model = "openai/gpt-oss-120b"
model_provider 값은 2단계 테이블 이름의 huggingface 부분과 일치해야 한다. 0.134.0 이전 버전이라면 이 파일을 만들지 않고, 같은 내용을 config.toml 안 [profiles.<name>] 테이블에 정의한다.
모델 이름에는 라우팅 접미사를 붙일 수 있다. openai/gpt-oss-120b:groq처럼 쓰면 특정 프로바이더로 고정되고, :cheapest 또는 :fastest는 우선순위 기준을 지정한다. 어떤 모델을 고르든 Inference Providers에서 chat completion용으로 제공되는 모델인지 먼저 확인해야 한다고 문서는 적고 있다.
4단계: 실행
codex --profile huggingface
codex exec --profile huggingface "Explain what this repository does."
codex exec --profile huggingface -m "zai-org/GLM-5.1" "Return OK."
첫 줄은 대화형 세션을 연다. 두 번째 codex exec는 프롬프트 하나를 비대화형으로 한 번만 처리하므로 스크립트나 자동화 작업에 맞는다. 세 번째처럼 -m을 넘기면 프로필 파일을 고치지 않고 그 실행에서만 모델이 바뀐다.
로컬 Ollama를 Codex CLI 프로바이더로 연결하기
Ollama 문서는 두 가지 진입 방식을 제시한다. 설정 파일 없이 바로 띄우는 방식과, 프로필 파일로 설정을 고정하는 방식이다.
빠른 시작과 수동 연결
npm install -g @openai/codex
ollama launch codex
codex --oss
codex --oss -m gpt-oss:120b
codex --oss -m gpt-oss:120b-cloud
ollama launch codex가 빠른 시작 경로다. 수동으로 연결할 때는 codex --oss를 쓰고, 모델은 -m으로 고른다. 문서가 드는 클라우드 모델 예시는 gpt-oss:120b-cloud다.
프로필 파일로 설정 유지
실행할 때마다 플래그를 붙이지 않으려면 ~/.codex/ollama-launch.config.toml을 만든다. Hugging Face 사례와 달리 이 예시는 프로바이더 정의까지 같은 프로필 파일 안에 둔다.
model = "gpt-oss:120b"
model_provider = "ollama-launch"
model_catalog_json = "/Users/you/.codex/model.json"
[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://localhost:11434/v1/"
wire_api = "responses"
model_catalog_json의 /Users/you/... 경로는 문서 예시 값이므로 자신의 홈 디렉터리 경로에 맞춘다. 공식 예시의 [model_providers.ollama-launch]에는 env_key가 없다. wire_api = "responses"는 여기서도 들어가 있다.
파일을 저장한 뒤에는 셸에서 codex --profile ollama-launch로 실행한다. 이 프로필로 띄우면서 웹 검색을 끄려면 -c 옵션으로 값을 덮어써 codex --profile ollama-launch -c 'web_search="disabled"'처럼 실행한다.
설정 시 주의사항과 제약
Responses API 요건. 커스텀 프로바이더는 wire_api = "responses"를 요구하고, chat/completions 방식은 2026년 2월 제거와 함께 하드 에러로 공지됐다. 연결하려는 엔드포인트가 Chat Completions 형식만 제공한다면 이 설정만으로는 붙일 수 없다. 기존 설정 파일에 wire_api 키가 없는 프로바이더 정의가 남아 있으면 그것도 수정 대상이다.
모델 제공 여부. Hugging Face 라우터에서는 모델 ID가 올바르더라도, 해당 모델이 Inference Providers에서 chat completion용으로 제공되지 않으면 쓸 수 없다고 봐야 한다. 라우팅 접미사(:groq, :cheapest, :fastest)는 제공되는 모델 위에서 경로만 조정한다.
`X-HF-Bill-To` 헤더는 지정한 조직으로 추론 비용을 청구하는 역할이다. 공식 문서는 이 헤더를 쓰려면 해당 조직의 Write 권한이 필요하다고 명시한다. 조직 이름을 잘못 적거나 권한이 없는 조직을 지정하지 않도록, 헤더를 넣기 전에 계정의 조직 권한부터 확인한다.
버전과 프로필 위치. 0.134.0 이전 Codex에서는 <이름>.config.toml 별도 파일 대신 config.toml의 [profiles.<name>] 테이블을 써야 한다. 여러 환경에서 같은 설정을 공유한다면 각 환경의 Codex 버전을 먼저 맞추는 편이 혼선을 줄인다.
OpenAI 측 Codex 설정 레퍼런스 페이지는 조사 과정에서 본문을 확인하지 못했다. 그래서 `model_providers`의 전체 필드 목록, 재시도·타임아웃 기본값 같은 항목은 이 글에서 다루지 않는다. 위 내용은 Hugging Face·Ollama 공식 연동 문서와 #7782 공지에 근거한다.
Codex CLI에서 커스텀 모델 프로바이더를 쓰는 구조는 어느 엔드포인트든 같다. [model_providers.<id>]에 base_url과 wire_api = "responses"를 적고, 인증이 필요하면 env_key로 토큰 변수를 연결한다. 이어서 프로필에서 model_provider와 model을 고른 뒤 codex --profile로 실행한다. 차이는 버전에서 생긴다. 0.134.0 이상은 프로필을 ~/.codex/<이름>.config.toml 파일로 분리하고, 그 이전은 config.toml 안 [profiles.<name>] 테이블을 쓴다. 기존 설정에 wire_api = "chat"이나 wire_api 미지정 정의가 남아 있다면 가장 먼저 고쳐야 할 부분이다.
Hugging Face 경로는 토큰 권한과 모델 제공 여부를, Ollama 경로는 64k 이상의 컨텍스트 창을 먼저 챙기면 된다. 이 설정 위에서 확장할 주제로는 codex exec를 CI 스크립트에 넣어 비대화형 작업을 자동화하는 방법이 있다. LM Studio를 oss_provider = "lmstudio"로 연결하는 로컬 모델 구성도 같은 맥락이다. 여러 codex --profile 설정을 프로젝트별로 나눠 관리하는 방식 역시 같은 흐름에 속한다.
관련 글
- GPT-5 Codex CLI 사용법 7단계 — 설치·인증·API 호출·에이전트 태스크 완전 정복 – OpenAI Codex CLI 설치, 인증, GPT-5-Codex 모델 API 호출, AGENTS.md 에이전트 태스크 설정, config…
- OpenAI Codex 에이전트 루프 구조 완전 정복 — plan-execute-verify 5단계 – Codex CLI의 에이전트 루프는 while 루프 기반으로 Responses API 호출 → 도구 실행 → 결과 반환 사이클을 반복한다….
- OpenAI Codex 보안 취약점 탐지 5단계: SQL 인젝션·XSS 자동 스캔 실전 가이드 – 레거시 PHP·Node.js 코드베이스에 OpenAI Codex를 붙여 SQL 인젝션과 XSS 취약점을 자동으로 찾아낸 경험. 프롬프트 설…