코덱스 모든 오픈소스 모델 활용법 (OSS 모드)

Codex는 기본적으로 OpenAI 모델과 함께 제공되지만, OpenAI 모델에만 얽매이지 않습니다. CLI에는 Ollama 및 LM Studio와 같은 로컬 런타임을 위한 내장 OSS 모드가 있으며, TOML 파일에 정의한 호환 가능한 모든 엔드포인트에 에이전트를 연결하는 사용자 지정 공급자 시스템도 있습니다. 이는 노트북에서 gpt-oss를 실행하고, 호스팅된 DeepSeek 또는 Qwen API로 Codex를 구동하거나, 프로젝트별로 공급자를 전환할 수 있음을 의미합니다.

이 가이드는 전체 설정 과정을 안내합니다: OSS 모드가 무엇을 하는지, 정확한 구성 키, 모델별 레시피, 그리고 OpenAI 모델을 교체할 때 감수해야 하는 절충점들. 여기 있는 모든 내용은 공식 Codex 고급 구성 문서에서 가져왔습니다. 문서가 모호한 부분은 추측하지 않고 그대로 언급합니다.

시작하기 전에 한 가지 유의할 점이 있습니다. 모델이 Codex 내에서 실행되면, 모델은 워크플로우의 절반에 불과합니다. 나머지 절반은 에이전트가 구축하고 호출하는 API를 검증하는 것입니다. 바로 여기에 Apidog가 적합하며, 이 둘의 연동은 마지막 부분에서 다룰 것입니다.

요약 (TL;DR)

Codex OSS 모드는 CLI 기능입니다. codex --oss를 실행하면 Codex가 OpenAI 대신 로컬 Ollama 또는 LM Studio 서버와 통신합니다. ~/.codex/config.toml에 oss_provider = "ollama"를 설정하여 기본값으로 만들고, -m <model>을 전달하여 실행할 로컬 모델을 선택합니다. 호스팅된 오픈 소스 모델(DeepSeek, Qwen, GLM의 API를 통해)의 경우, base_url 및 env_key를 포함하는 [model_providers.<id>] 블록을 정의한 다음, model_provider로 선택합니다. 주의할 점: 현재 구성 참조에는 responses가 지원되는 유일한 wire_api 값으로 나열되어 있으므로, 엔드포인트는 Responses API 프로토콜을 사용해야 합니다.

OSS 모드란

OSS 모드는 Codex가 로컬 오픈 소스 모델 서버에 대해 실행하기 위한 단축키입니다. 문서에는 두 가지 지원되는 로컬 공급자가 설명되어 있습니다:

Ollama, 인기 있는 로컬 모델 런타임
LM Studio, 내장 로컬 서버가 있는 데스크톱 앱

--oss 플래그로 활성화합니다. Codex 개발자 명령 참조에서:

--oss: 로컬 오픈 소스 모델 공급자를 사용합니다. Codex는 --local-provider, 구성된 oss_provider를 사용하거나, LM Studio와 Ollama 중 하나를 선택하라는 메시지를 표시합니다.

--local-provider라는 동반 플래그가 있으며, lmstudio 또는 ollama를 취하고 단일 실행에 대한 기본값을 재정의합니다. 플래그도 구성 기본값도 설정하지 않으면, 대화형 CLI가 선택을 요청합니다. 비대화형 codex exec는 메시지를 표시하지 않고 오류와 함께 종료됩니다. 따라서 스크립트 및 CI의 경우 항상 공급자를 명시적으로 설정하십시오.

솔직히 말하면: 문서는 CLI의 config.toml 시스템 아래에 OSS 모드와 사용자 지정 공급자를 다룹니다. IDE 확장 및 Codex 클라우드는 구성 문서 어디에서도 로컬 공급자를 지원한다고 언급되지 않습니다. [확인: Codex IDE 확장이 CLI와 동일한 방식으로 config.toml에서 model_providers를 읽는지 여부; 문서는 어느 쪽도 명시하지 않습니다.] OpenAI가 다르게 문서화할 때까지 이를 CLI 워크플로우로 취급하십시오.

왜 Codex 내에서 오픈 소스 모델을 실행해야 하는가

Codex가 OpenAI 자체 에이전트라는 점을 감안하면 합리적인 질문입니다. 몇 가지 실제 이유:

비용 통제. Ollama를 통한 로컬 추론은 토큰당 비용이 전혀 들지 않습니다. 긴 에이전트 세션에서 사용량 제한을 초과하고 있다면, 로컬 모델이 힘든 작업을 처리하는 동안 호스팅된 호출은 어려운 문제에 대비해 아낄 수 있습니다.
프라이버시 및 에어갭(air-gapped) 작업. 일부 코드베이스는 기기를 벗어날 수 없습니다. 로컬 Kimi, GLM 또는 gpt-oss 모델은 모든 토큰을 하드웨어에 보관합니다. 로컬에서 Kimi K3 실행하기 가이드는 실제 필요한 것을 다룹니다.
모델 선호도. 오픈 가중치 모델은 코딩 격차의 대부분을 줄였습니다. DeepSeek 및 Qwen의 호스팅 API는 OpenAI 가격을 밑돌면서 코딩 벤치마크에서 비슷한 점수를 얻었으며, 특정 모델이 코드를 작성하는 방식이 단순히 마음에 들 수도 있습니다.
하나의 에이전트 하네스, 여러 모델. Codex의 터미널 UX, 샌드박싱 및 승인 흐름은 좋습니다. 공급자 구성은 그 하네스를 유지하고 두뇌를 교체할 수 있게 해줍니다.

구성 위치

Codex는 CODEX_HOME 아래에 상태를 저장하며, 기본값은 ~/.codex입니다. 사용자 수준 구성은 ~/.codex/config.toml이며, 리포지토리는 .codex/config.toml에 프로젝트 수준 재정의를 포함할 수 있습니다. 아래의 모든 내용은 이 두 파일 중 하나에 들어갑니다.

빠른 시작: Ollama와 함께 Codex 사용

Codex에서 오픈 소스 모델을 가장 빠르게 사용하는 방법은 Ollama입니다.

ollama.com에서 Ollama를 설치하고 시작합니다. Ollama는 11434 포트에서 OpenAI 호환 API를 제공합니다.
모델을 가져옵니다. OpenAI 자체의 오픈 가중치 릴리스가 자연스러운 첫 번째 선택입니다. gpt-oss 라이브러리 페이지에는 20b 및 120b 변형이 있습니다. Ollama를 사용하여 gpt-oss 실행 방법에서 독립 실행형 설정을 다루었습니다.

ollama pull gpt-oss:20b

OSS 모드에서 Codex를 실행하고 모델 이름을 지정합니다:

codex --oss -m gpt-oss:20b

-m/--model 플래그는 구성된 모델을 재정의하며, --oss와 결합하여 실행할 로컬 모델을 선택합니다. 비대화형 사용의 경우:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

기본값으로 설정하여 플래그를 생략할 수 있습니다. ~/.codex/config.toml에 다음을 추가합니다:

# `--oss`와 함께 사용되는 기본 로컬 공급자
oss_provider = "ollama" # 또는 "lmstudio"

이것이 로컬 모델의 전체 기능입니다. API 키도, 사용자 지정 공급자 블록도 필요 없습니다. LM Studio도 같은 방식으로 작동합니다: 앱에 모델을 로드하고, 로컬 서버를 시작한 다음, codex --oss --local-provider lmstudio를 실행합니다. 서버 설정은 lmstudio.ai를 참조하십시오.

사용자 지정 공급자: Codex를 호환 가능한 모든 엔드포인트에 연결

OSS 모드는 Ollama와 LM Studio를 다룹니다. 그 외 모든 것, 즉 호스팅된 DeepSeek 또는 Qwen API, 프록시, LAN의 vLLM 서버를 위해 Codex는 사용자 지정 모델 공급자를 제공합니다. 문서는 공급자를 "Codex가 모델에 연결하는 방법(기본 URL, 와이어 API, 인증 및 선택적 HTTP 헤더)"으로 정의합니다.

공식 문서의 패턴:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "LLM 프록시를 사용하는 OpenAI"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

중요한 키:

키	기능
`model_provider`	Codex가 사용하는 공급자 ID (기본값: `openai`)
`model`	해당 공급자에게 전송되는 모델 이름
`name`	공급자의 표시 이름
`base_url`	API 기본 URL
`env_key`	API 키를 저장하는 환경 변수
`wire_api`	공급자가 사용하는 프로토콜
`query_params`	요청에 추가되는 추가 쿼리 매개변수
`http_headers` / `env_http_headers`	정적 헤더, 또는 환경 변수에서 채워지는 헤더

공급자별 네트워크 튜닝도 가능합니다: request_max_retries (기본값 4), stream_max_retries (기본값 5), stream_idle_timeout_ms (기본값 300000). 느린 로컬 하드웨어는 더 긴 유휴 시간 초과의 이점을 얻습니다. 랩톱에서 120b 모델은 토큰 사이에 한동안 조용히 있을 수 있기 때문입니다.

문서에서 직접 언급하는 두 가지 규칙이 있습니다. 첫째, openai, ollama, lmstudio ID는 예약되어 있으며, 내장 공급자를 재정의할 수 없습니다. 내장 OpenAI 공급자의 기본 URL을 변경하려면 [model_providers.openai]를 생성하는 대신 openai_base_url을 설정하십시오. 둘째, 그리고 이것이 모든 것을 형성합니다: 구성 참조는 wire_api에 대해 "responses가 유일하게 지원되는 값이며, 생략 시 기본값"이라고 명시합니다.

이것은 실제 제약입니다. 이전 Codex 버전은 Chat Completions 엔드포인트에 대해 wire_api = "chat"을 허용했으며, 모델 개요 페이지에서는 Codex를 "Chat Completions 또는 Responses API"를 지원하는 공급자에 연결할 수 있다고 여전히 말합니다. 참조와 개요가 일치하지 않습니다. [확인: wire_api = "chat"이 현재 CLI 릴리스에서 여전히 작동하는지 여부; 구성 참조는 responses-only라고 말하지만, 모델 페이지는 chat도 작동한다고 암시합니다. 게시하기 전에 chat-only 엔드포인트에 대해 테스트합니다.] 만약 responses-only가 유지된다면, 공급자는 Responses API 엔드포인트가 필요하며, 대부분의 OpenAI 호환 서버는 이제 이를 노출하지만 일부 호스팅된 API는 여전히 그렇지 않습니다.

모델별 레시피

아래 각 레시피는 구성 블록과 실행 명령으로 구성됩니다. 실행하기 전에 API 키 환경 변수를 설정하십시오.

DeepSeek (호스팅된 API)

DeepSeek은 V4 Flash 베타와 함께 Responses API 지원을 추가했으며, 이는 Codex의 와이어 프로토콜이 원하는 바와 정확히 일치합니다. 우리는 DeepSeek V4 Flash, Responses API, 그리고 Codex에서 해당 출시를 다루었습니다.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

현재 모델 ID는 DeepSeek API 문서를 확인하십시오. [확인: Responses 프로토콜 액세스를 위한 DeepSeek 문서의 정확한 base_url 경로; /v1 chat 경로는 Responses 경로와 다를 수 있습니다.]

Qwen (Model Studio를 통해 호스팅됨)

알리바바의 Model Studio (DashScope)는 Qwen 3.8 계열에 대한 OpenAI 호환 모드를 노출합니다. 호환 모드 엔드포인트는 역사적으로 Chat Completions 형태로 제공되었습니다. [확인: DashScope의 호환 모드가 이제 Responses 프로토콜을 제공하는지 여부; 그렇지 않다면, 이 레시피는 위 wire_api = "chat" 질문에 따라 달라집니다.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Model Studio를 통한 Qwen"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Qwen 3.8 API 가이드는 호스팅 경로에 대한 키, 모델 ID 및 가격을 다룹니다.

Kimi, GLM 및 기타 오픈 가중치 (Ollama를 통해 로컬)

Ollama로 가져올 수 있는 모든 것은 일반 OSS 모드를 통해 작동하며, 공급자 블록이 필요 없습니다:

ollama pull <model>
codex --oss -m <model>

이것은 GLM 및 Qwen 오픈 가중치, 그리고 하드웨어가 견딜 수 있다면 Kimi K3를 포함합니다 (K3 가중치는 MXFP4에서 594GB이므로, 대부분의 사람들은 시도하기 전에 로컬에서 Kimi K3 실행하기를 읽어야 합니다). 중간 크기 머신의 경우 gpt-oss:20b 또는 양자화된 Qwen 코더 빌드가 실용적인 선택입니다.

자체 호스팅 vLLM 또는 LAN 서버

다른 머신에 있는 vLLM 또는 유사한 OpenAI 호환 서버는 OSS 모드가 아닌 사용자 지정 공급자입니다:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "워크스테이션의 vLLM"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

프로필: 작업별로 두뇌 전환

하나의 설정만 선택할 필요는 없습니다. Codex 프로필은 ~/.codex/<profile-name>.config.toml에 있는 별도의 TOML 파일이며, --profile을 전달할 때 기본 구성 위에 계층화됩니다. 로컬 모델 프로필은 다음과 같습니다:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "utils/dates.ts에 단위 테스트 작성"

하드 리팩토링을 위해 기본 구성을 OpenAI 모델로 유지하고, 린트 수정, 테스트 스캐폴딩 및 문서 통과를 위해 --profile oss-local을 실행하십시오. 임시 재정의는 프로필 없이도 작동합니다: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

OpenAI 모델과 비교한 절충점

무엇을 교환하고 있는지 스스로에게 솔직해지세요:

역량. gpt-oss:20b는 gpt-5.6-terra가 아닙니다. 로컬 모델은 긴 다중 파일 편집에서 더 자주 실패하며, 에이전트 루프는 모든 단계가 이전 단계에 기반을 두기 때문에 모델의 약점을 증폭시킵니다.
속도. 호스팅된 API는 빠르게 스트리밍됩니다. 소비자 하드웨어의 큰 로컬 모델은 작업 방식을 바꿀 만큼 충분히 느릴 수 있습니다.
도구 충실도. Codex의 프롬프트 및 도구 호출은 OpenAI 모델에 최적화되어 있습니다. 오픈 소스 모델은 도구 호출을 얼마나 안정적으로 내보내는지 다양하며, responses-only 와이어 프로토콜은 어떤 엔드포인트가 자격을 갖추는지 협소하게 만듭니다.
지원 범위. OSS 모드는 문서화된 CLI 경로이지만, 타사 공급자는 사용자의 책임입니다: 모델 ID, 속도 제한 및 프로토콜 특이 사항은 사용자와 공급업체 간의 문제입니다.

실용적인 분할: 대량의 낮은 위험 작업에는 로컬 또는 저렴한 호스팅 모델, 실패한 실행이 오후를 망칠 수 있는 작업에는 프론티어 모델을 사용하십시오.

에이전트가 사용하는 API 검증

Codex 내에서 어떤 모델이 실행되든, 출력은 일반적으로 API를 호출하거나 정의하는 코드이며, 오픈 소스 모델은 프론티어 모델보다 엔드포인트와 스키마를 더 자주 환각합니다. 이를 프로덕션이 아닌 API 계층에서 잡아내십시오.

Apidog는 워크플로우의 해당 부분을 다룹니다. Apidog MCP 서버를 프로젝트에 연결하면 Codex 에이전트가 필드 이름을 발명하는 대신 코드를 작성하는 동안 실제 API 사양을 읽을 수 있습니다. 그런 다음 Codex 내 Apidog CLI를 사용하여 각 변경 후 터미널에서 에이전트가 테스트 시나리오를 실행하도록 할 수 있습니다: 에이전트는 편집하고, 테스트하며, 사용자는 통과하는 diff를 검토합니다. 더 작은 모델이 코드를 작성할 때 이 루프는 그 어느 때보다 중요합니다. Apidog를 다운로드하여 연결하십시오. CLI 및 MCP 서버는 구성한 모든 모델과 함께 작동합니다.

문제 해결

OSS 모드에서 codex exec가 즉시 오류를 발생시킵니다. 공급자를 설정하지 않았습니다. 비대화형 실행은 프롬프트를 표시하지 않으므로 --local-provider ollama를 전달하거나 구성에서 oss_provider를 설정하십시오.
11434 포트에서 연결 거부. Ollama가 실행 중이 아니거나 다른 주소에 바인딩되어 있습니다. 앱을 시작하거나 ollama serve를 실행하고, curl http://localhost:11434/v1/models로 확인하십시오.
호스팅된 공급자에서 404 또는 프로토콜 오류. base_url 형식이 잘못되었거나 엔드포인트가 Responses 프로토콜을 사용하지 않습니다. 공급업체가 Responses 호환 경로를 문서화하는지 확인하십시오.
인증 실패. env_key는 환경 변수 이름을 지정합니다. Codex는 시작 시 셸 환경에서 키를 읽습니다. 같은 셸에서 내보내고, launchd 또는 CI 셸이 dotfiles를 로드하지 않을 수 있다는 점을 기억하십시오.
느린 로컬 모델에서 스트림이 중간에 중단됩니다. 공급자 블록에서 stream_idle_timeout_ms 및 stream_max_retries를 늘리십시오.
구성 편집이 무시됩니다. 프로젝트 수준의 .codex/config.toml이 사용자 구성을 재정의하는지 확인하고, 프로필이 둘 모두 위에 계층화된다는 점을 기억하십시오.

자주 묻는 질문

Codex OSS 모드가 IDE 확장 또는 Codex 클라우드에서 작동합니까?

문서는 OSS 모드와 사용자 지정 공급자를 CLI의 구성 시스템의 일부로 문서화합니다. 로컬 공급자에 대한 IDE 또는 클라우드 지원은 문서화되어 있지 않으므로, 이를 CLI 기능으로 취급하십시오. [IDE 지원에 의존하기 전에 확인하십시오.]

OSS 모드에서 Codex와 가장 잘 작동하는 모델은 무엇입니까?

하드웨어에서 Ollama 또는 LM Studio가 제공할 수 있는 모든 것입니다. gpt-oss:20b는 마찰이 적은 기본값입니다. 강력한 오픈 가중치 코딩 옵션에는 Qwen 3.8 계열 및 GLM이 포함됩니다. Kimi K3와 같은 거대 모델의 경우, 먼저 로컬 Kimi K3 가이드에서 하드웨어 계산을 확인하십시오.

Codex와 함께 OpenRouter 또는 다른 애그리게이터를 사용할 수 있습니까?

호환 가능한 엔드포인트를 노출하는 모든 애그리게이터는 [model_providers.<id>] 패턴에 맞습니다: base_url 및 env_key를 설정한 다음, model_provider로 선택합니다. 미해결 문제는 프로토콜입니다: 구성 참조에는 responses가 지원되는 유일한 wire_api로 나열되어 있으므로, 애그리게이터가 Responses API를 제공하는지 확인하십시오.

오픈 소스 모델로 Codex를 실행하려면 OpenAI API 키가 필요합니까?

로컬 Ollama 또는 LM Studio 서버를 사용하는 OSS 모드에서는 키가 필요하지 않습니다. 사용자 지정 호스팅 공급자는 env_key를 통해 자체 키를 사용합니다. OpenAI 서비스와 관련된 모든 작업에 대해서는 평소처럼 Codex 자체에 로그인해야 합니다.

작업에 맞는 설정을 실행하십시오. 저렴한 루프에는 로컬 gpt-oss, 낮은 비용으로 호스팅된 속도를 원할 때는 DeepSeek 또는 Qwen, 문제가 어려울 때는 OpenAI의 프론티어 모델을 사용하십시오. Codex의 구성은 이 세 가지를 하나의 플래그로 구분하며, Apidog가 API 측에서 검증을 처리하면 모델은 약속이 아닌 교체 가능한 부품이 됩니다.