Codex 통합

Codex 통합 (Codex)

OpenAI Codex는 CLI 기반 코딩 에이전트예요. vLLM은 OpenAI-Responses API를 구현하고 있어서, Codex를 vLLM 서버로 연결하면 OpenAI API 대신 여러분의 모델을 백엔드로 쓸 수 있어요. 완전히 로컬/프라이빗한 코딩 어시스턴트를 만들 수 있다는 뜻이죠. 이 페이지에서 설정 방법을 알아볼게요.

출처: vLLM 공식 문서 — serving/integrations/codex

Codex를 vLLM 서버로 연결하면 OpenAI API 대신 여러분의 모델을 백엔드로 쓸 수 있어요. 이는 다음에 유용해요.

• 완전히 로컬/프라이빗한 코딩 어시스턴트 실행
• 도구 호출 능력이 있는 오픈 가중치 모델 사용
• 커스텀 모델로 테스트·개발

동작 원리 (How It Works)

vLLM은 Codex가 OpenAI 서버와 통신하는 데 쓰는 것과 동일한 OpenAI-Responses API를 구현해요. Codex를 vLLM 서버로 연결하도록 설정하면, Codex가 OpenAI 대신 vLLM으로 요청을 보내요. vLLM은 이 요청을 로컬 모델에 맞게 번역하고, Codex가 기대하는 형식으로 응답을 돌려줘요.

즉, vLLM이 서빙하는 적절한 도구 호출 지원이 있는 어떤 모델이든 Codex에서 OpenAI 모델의 대체품으로 쓸 수 있어요.

요구사항 (Requirements)

Codex는 강력한 도구 호출 능력이 있는 모델을 요구해요. 모델이 OpenAI-Responses 도구 호출 API를 지원해야 해요. 모델의 도구 호출 활성화 방법은 Tool Calling 문서를 참고하세요.

vLLM 서버 시작 (Starting the vLLM Server)

도구 호출이 가능한 모델로 vLLM을 시작해요. Qwen/Qwen3-27B를 쓰는 예시예요.

vllm serve Qwen/Qwen3.6-27B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --enable-auto-tool-choice --tool-call-parser qwen3_coder

다른 모델은 --enable-auto-tool-choice와 올바른 --tool-call-parser로 도구 호출을 명시적으로 활성화해야 해요. 모델에 맞는 플래그는 Tool Calling 문서를 참고하세요.

Codex 설정 (Configuring Codex)

Codex는 ~/.codex/config.toml에 있는 TOML 파일로 설정돼요. 이 파일을 생성하거나 편집해 Codex를 vLLM 서버로 연결하세요.

model = "my-model"
model_provider = "vllm"

[model_providers.vllm]
name = "vLLM"
env_key = "VLLM_API_KEY"
base_url = "http://localhost:8000/v1"
wire_api = "responses"

팁: vLLM은 기본적으로 인증을 요구하지 않으므로 env_key를 아무 더미 환경 변수로 설정할 수 있어요.

export VLLM_API_KEY=dummy

경고: responses API를 쓸 때는 여러분의 vLLM 버전이 OpenAI Responses API를 지원하는지 확인하세요.

문제 해결 (Troubleshooting)

Connection refused: vLLM이 실행 중이고 지정한 URL에서 접근 가능한지 확인하세요. 포트가 일치하는지, base_url에 /v1 경로 접미사가 포함됐는지 확인하세요.

Model not found: ~/.codex/config.toml의 model 필드가 vLLM에 넘긴 --served-model-name과 일치하는지 확인하세요.

더 알아보기 (Learn more)

• Claude Code 통합 (Claude Code)
• OpenAI 호환 서버 (OpenAI-Compatible Server)
• 도구 호출 (Tool Calling)