Codex CLI가 OSS 모드를 지원하면서 OpenAI 의존도에서 벗어날 길이 열렸습니다. Ollama나 LM Studio를 로컬 장비에 띄우고 API 연동만 설정하면 끝입니다. 사내 전용 모델 게이트웨이나 OpenRouter 같은 외부 서비스도 연동할 수 있습니다.

로컬 프로바이더 정의와 설정

로컬 모델을 연동하려면 ~/.codex/config.toml 파일에 프로바이더 구성을 추가해야 합니다. Codex CLI를 사용할 때는 기본적으로 OpenAI 규격을 따르는 API 엔드포인트가 필요합니다. 예컨대 Ollama를 연동할 때는 responses 프로토콜을 지정하는 편이 안전합니다. 기존 chat 방식은 향후 지원을 중단할 예정입니다.

model = "qwen2.5-coder:32b"
model_provider = "local_ollama"
oss_provider = "ollama"

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

LM Studio 연동도 구조는 비슷합니다. 포트 번호만 1234 로 바꾸면 로컬 장비에서 바로 붙습니다. 외부 게이트웨이를 연동한다면 experimental_bearer_token 필드에 API 키를 넣습니다. 이 설정 파일은 로컬 디렉토리에만 보관하고 소스 저장소 업로드는 피해야 보안 사고를 막습니다.

달라진 프로필 구성 방식

Codex 0.134.0 버전부터는 프로필 설정을 개별 파일로 분리하여 관리해야 작동합니다. 예전 개발 문서에 적힌 [profiles.xxx] 테이블 방식은 더는 인식하지 않습니다. 이제는 ~/.codex/fast-coder.config.toml 처럼 프로필마다 전용 파일을 따로 생성해야 합니다.

model = "qwen2.5-coder:7b"
model_provider = "local_ollama"
model_reasoning_effort = "low"

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

특정 작업을 수행할 때 –profile 옵션을 붙여 명령어를 실행하면 됩니다. 로컬 장비 사양에 맞춰 가벼운 모델과 무거운 모델을 프로필 단위로 쪼개두면 자원 관리가 편합니다. 복잡한 코드 리뷰는 클라우드 대형 모델로 보내고 단순 코딩은 로컬 모델로 처리하는 조합이 유용합니다.

로컬 연동 시 주의할 호환성

로컬 API 엔드포인트가 OpenAI 규격을 완벽하게 모사하지 못하면 동작 오류가 빈번하게 발생합니다. 특히 스트리밍 출력이나 도구 호출 영역에서 호환성 문제가 자주 나타납니다. 대규모 코드 편집 작업을 넘기기 전에 간단한 디버깅으로 호환성을 먼저 검증해야 리소스 낭비를 막습니다.

자체 구축한 vLLM이나 SGLang 환경에서도 프로토콜 호환성은 가장 취약한 고리입니다. 겉보기에는 호환 엔드포인트처럼 보여도 내부 파라미터 파싱 단계에서 뻗는 경우가 흔합니다. 가벼운 더미 파일 편집 테스트를 먼저 돌려보고 실무 프로젝트에 투입하는 방식을 권장합니다.

로컬 장비 성능이 충분하다면 OSS 모드는 비용 부담을 덜어줄 훌륭한 대안입니다. 손에 익은 개발 도구를 입맛대로 튜닝하는 재미도 쏠쏠합니다.

요약

  • Codex CLI 0.134.0 버전부터는 단일 설정 파일 대신 프로필별 독립 구성 파일을 사용해야 오작동을 피합니다.
  • 로컬 LLM 연동 시 호환성 문제를 예방하려면 기존 chat 방식 대신 responses 프로토콜 설정을 우선 적용해야 합니다.
  • 대규모 코드 편집 전에 가벼운 더미 파일 편집으로 로컬 인프라의 API 호환성을 검증하는 과정이 필수적입니다.