LLM Wiki

Codex OSS 모드 & 로컬/커스텀 모델 프로바이더 설정

Properties2
descriptioncodex는 --oss 플래그로 로컬 오픈 모델 프로바이더(ollama · lmstudio)를 바로 붙일 수 있고, [modelproviders.] 테이블로 nvidia-nim 같은 OpenAI 호환 엔드포인트를 커스텀 프로바이더로 추가할 수 있다.
tagsai-coding, codex, openai, open-source, cli

6 min read

한줄 요약

codex는 --oss 플래그로 로컬 오픈 모델 프로바이더(ollama · lmstudio)를 바로 붙일 수 있고, [model_providers.*] 테이블로 nvidia-nim 같은 OpenAI 호환 엔드포인트를 커스텀 프로바이더로 추가할 수 있다. 설정은 ~/.codex/config.toml에 TOML로 작성한다. moc-ai-coding local-llm

OSS 모드 (--oss)

로컬 오픈소스 프로바이더로 Codex를 실행하는 진입점이다.

codex --oss
  • --oss에 프로바이더를 명시하지 않으면 oss_provider 설정값을 기본 프로바이더로 사용한다.
  • 빌트인 OSS 프로바이더는 Ollama와 LM Studio 두 가지다.
oss_provider = "ollama"   # 또는 "lmstudio"

커스텀 모델 프로바이더 — [model_providers.NAME]

빌트인(openai · ollama · lmstudio) 외에, OpenAI 호환 엔드포인트를 가진 어떤 서비스든 [model_providers.<id>] 테이블로 선언하고 최상위 model_provider로 선택한다.

model_provider = "proxy"
 
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.NAME] 필드

필드설명
name프로바이더 표시 이름
base_url모델 서비스 API 엔드포인트 URL
env_keyAPI 키가 담긴 환경 변수 이름
wire_api프로토콜 — "responses"(OpenAI Responses API) 또는 "chat"(Chat Completions). 로컬/호환 서버는 보통 "chat"
query_params요청에 붙일 추가 쿼리 파라미터(TOML 테이블)
http_headers모든 요청에 넣을 고정 HTTP 헤더
env_http_headers환경 변수에서 값을 읽어오는 HTTP 헤더
request_max_retries요청 최대 재시도 횟수
stream_max_retries스트리밍 응답 최대 재시도 횟수
stream_idle_timeout_ms스트리밍 유휴 타임아웃(ms)
requires_openai_authOpenAI 방식 인증 필요 여부(boolean)

별도 커스텀 프로바이더 없이 빌트인 OpenAI 엔드포인트만 바꾸려면 openai_base_url을 쓴다(데이터 레지던시·프록시용):

openai_base_url = "https://us.api.openai.com/v1"

로컬/호환 프로바이더 추가 예시

세 프로바이더 모두 OpenAI 호환 Chat Completions API를 노출하므로 wire_api = "chat"로 붙인다. Ollama·LM Studio는 --oss로 바로 쓸 수 있고, NVIDIA NIM은 빌트인이 아니라 커스텀 프로바이더로 추가한다.

Ollama

--oss로 바로 쓰거나(oss_provider = "ollama"), 명시적 커스텀 프로바이더로 선언한다. 기본 엔드포인트는 http://localhost:11434/v1이고 로컬 실행은 API 키가 필요 없다.

model_provider = "local_ollama"
model = "gemma4:latest"      # ollama list 의 모델 태그
 
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

LM Studio

GUI/헤드리스 모두 OpenAI 호환 서버를 켤 수 있고, 기본 포트는 1234다(oss_provider = "lmstudio"도 가능).

model_provider = "lmstudio"
model = "qwen3-coder"        # LM Studio 에 로드한 모델 id
 
[model_providers.lmstudio]
name = "LM Studio"
base_url = "http://localhost:1234/v1"
wire_api = "chat"

NVIDIA NIM

nvidia-nim은 OpenAI 호환 API를 제공한다. NVIDIA 호스팅 엔드포인트(build.nvidia.com 키)와 자가 호스팅(로컬 NIM 컨테이너, 기본 포트 8000) 두 갈래로 붙일 수 있다.

# (1) NVIDIA 호스팅 — build.nvidia.com 의 무료/유료 모델
model_provider = "nvidia"
model = "nvidia/nemotron-..."
 
[model_providers.nvidia]
name = "NVIDIA NIM"
base_url = "https://integrate.api.nvidia.com/v1"
env_key = "NVIDIA_API_KEY"
wire_api = "chat"
# (2) 자가 호스팅 NIM 컨테이너 (로컬)
[model_providers.nim_local]
name = "NVIDIA NIM (self-hosted)"
base_url = "http://localhost:8000/v1"
wire_api = "chat"

엔드포인트·포트(Ollama 11434 / LM Studio 1234 / NIM 8000)와 NIM 커스텀 구성은 각 도구의 표준 OpenAI 호환 설정을 따른 것으로, 공식 Codex 문서가 빌트인으로 다루는 것은 Ollama·LM Studio 두 OSS 프로바이더뿐이다.

메모

  • 로컬 프로바이더는 보통 인증이 없으므로 env_key를 생략하고, 호스팅 API(NIM 등)는 env_key로 키를 주입한다.
  • model(또는 -m)로 해당 프로바이더에 로드된 모델 id를 지정해야 한다 — 프로바이더만 바꾸고 모델명을 안 맞추면 실패한다.
  • Responses API를 지원하지 않는 로컬 서버에는 반드시 wire_api = "chat"을 줘야 한다.

관련 노트

백링크