Codex

Codex

Codex는 OpenAI의 공식 에이전틱 코딩 도구로, 터미널에서 동작합니다. 코드베이스를 이해하고 파일을 편집하며 명령을 실행해 더 효율적으로 코드를 작성하게 해 줍니다. Codex를 vLLM 서버에 연결하면 OpenAI API 대신 자신의 모델을 백엔드로 사용할 수 있습니다.

출처: 문서

본문

Codex는 OpenAI의 공식 에이전틱 코딩 도구로 터미널에서 동작합니다. 코드베이스를 이해하고 파일을 편집·명령을 실행하며 코드를 더 효율적으로 작성하게 도와줍니다.

Codex를 vLLM 서버에 연결하면 OpenAI API 대신 자신의 모델을 백엔드로 쓸 수 있습니다. 이는 다음에 유용합니다:

  • 완전히 로컬/비공개 코딩 지원 실행
  • 툴 호출 능력을 가진 오픈 가중치 모델 사용
  • 커스텀 모델로 테스트·개발

동작 방식 (How It Works)

vLLM은 OpenAI-Responses API를 구현합니다. 이는 Codex가 OpenAI 서버와 통신할 때 사용하는 것과 같은 API입니다. Codex를 vLLM 서버를 가리키도록 구성하면 Codex가 요청을 OpenAI 대신 vLLM으로 보냅니다. vLLM은 이 요청을 로컬 모델에 맞게 변환하고 Codex가 기대하는 형식으로 응답을 반환합니다.

즉, 적절한 툴 호출을 지원하는 vLLM 서빙 모델은 Codex에서 OpenAI 모델의 drop-in 대체품으로 동작할 수 있습니다.

요구사항 (Requirements)

Codex는 강력한 툴 호출 능력을 가진 모델을 요구합니다. 모델은 OpenAI-Responses 툴 호출 API를 지원해야 합니다. 모델에서 툴 호출을 활성화하는 방법은 Tool Calling을 참고하세요.

설치 (Installation)

먼저 공식 설치 가이드를 따라 Codex를 설치하세요.

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"

구성 필드:

필드 설명
model 사용할 모델 이름. vLLM에 전달한 --served-model-name과 일치해야 함
model_provider 로컬 vLLM 서버를 사용하려면 "vllm"으로 설정
[model_providers.vllm] vLLM 프로바이더 구성 섹션
name vLLM 프로바이더의 표시 이름
env_key Codex가 API 키를 읽을 환경 변수 이름. vLLM은 기본적으로 인증을 요구하지 않으므로 아무 값이든 가능
base_url vLLM 서버의 OpenAI 호환 API 엔드포인트 URL (기본 http://localhost:8000/v1)
wire_api 사용할 API 스타일. OpenAI Responses API에는 "responses"로 설정

팁

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

export VLLM_API_KEY=dummy

경고

responses API를 사용할 때 vLLM 버전이 OpenAI Responses API를 지원하는지 확인하세요.

설정 테스트 (Testing the Setup)

Codex를 구성한 뒤 프로젝트 디렉토리에서 실행하세요:

codex

간단한 프롬프트로 연결을 확인해 보세요. 예를 들어 프로젝트의 파일을 설명해 달라고 요청합니다. 모델이 올바르게 응답하면 설정이 작동하는 것입니다. 이제 vLLM 서빙 모델로 Codex를 코딩 작업에 사용할 수 있습니다.

문제 해결 (Troubleshooting)

연결 거부 (Connection refused): vLLM이 지정된 URL에서 실행 중이고 접근 가능한지 확인하세요. 포트가 일치하고 base_url에 /v1 경로 접미사가 포함되어 있는지 확인하세요.

툴 호출이 작동하지 않음: 모델이 툴 호출을 지원하고 올바른 --tool-call-parser 플래그로 활성화했는지 확인하세요. Tool Calling 참고.

모델을 찾을 수 없음: ~/.codex/config.toml의 model 필드가 vLLM에 전달한 --served-model-name과 일치하는지 확인하세요.

더 알아보기 (Learn more)