Codex

Codex (CLI) 연결 (Connect Codex CLI to LiteLLM)

Codex는 모든 구성을 ~/.codex/config.toml에서 읽어요. 거기서 LiteLLM을 커스텀 모델 제공자로 정의하고 같은 파일에 MCP 게이트웨이를 등록해요. 이는 ChatGPT Desktop 안의 Codex 표면이 사용하는 것과 같은 콘피그라서, 한 번 설정하면 둘 다 커버돼요.

출처: 문서

본문

빠른 참조 (Quick reference)

LLM 설정 (LLM setup)

1. Codex 설치

npm i -g @openai/codex

또는 공식 설치 프로그램으로:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

2. LiteLLM을 모델 제공자로 정의하기

Codex는 OpenAI Responses API를 사용하며, LiteLLM은 이를 /v1/responses에서 서빙해요. ~/.codex/config.toml에 provider 블록을 추가하고 기본값으로 선택하세요. env_key는 Codex가 가상 키를 읽는 환경 변수를 명명하므로 파일에 시크릿이 저장되지 않아요:

~/.codex/config.toml

model = "claude-sonnet-5"
model_provider = "litellm"

[model_providers.litellm]
name = "LiteLLM"
base_url = "http://localhost:4000/v1"
env_key = "LITELLM_API_KEY"
wire_api = "responses"

긴 에이전트 턴은 게이트웨이 뒤에서 몇 분 동안 유휴 상태일 수 있으므로, 작업이 짧게 잘리면 스트림 타임아웃과 재시도를 올리세요:

~/.codex/config.toml

[model_providers.litellm]
stream_idle_timeout_ms = 7200000
stream_max_retries = 5
request_max_retries = 4

키를 export한 다음 Codex를 실행하세요:

export LITELLM_API_KEY="sk-1234"
codex

model은 LiteLLM 콘피그의 어떤 model_name이든 될 수 있어요. 실행마다 codex --model gemini-3.1-pro-preview로 재정의하세요. Codex는 OpenAI 자체 모델의 메타데이터만 알므로, 게이트웨이 이름으로는 첫 요청에 Model metadata for ... not found. Defaulting to fallback metadata를 출력해요. 요청은 여전히 진행돼요.

Codex는 시작 헤더에 모델을 표시하고 작업을 게이트웨이로 라우팅해요. 여기서 Codex 0.154가 로컬 게이트웨이를 통해 응답하고 있어요:

3. 검증 (Verify)

Codex에게 작은 변경을 요청한 다음 Admin UI의 Logs 또는 Usage를 확인하세요. 요청이 /v1/responses 아래에, 가상 키와 선택한 모델에 귀속되어 나타나요.

MCP 설정 (MCP setup)

같은 ~/.codex/config.toml에 LiteLLM MCP 게이트웨이를 스트림 가능 HTTP 서버로 등록하세요. Codex는 bearer 토큰을 파일이 아니라 환경 변수에서 읽으므로, 모델 제공자용으로 이미 export한 것을 재사용하세요:

~/.codex/config.toml

[mcp_servers.litellm]
url = "http://localhost:4000/my_mcp_server/mcp"
bearer_token_env_var = "LITELLM_API_KEY"

my_mcp_server는 게이트웨이 콘피그의 mcp_servers: 아래 키와 일치해야 하고, 키에 그 서버 액세스가 필요해요 (overview 참고). Codex는 키를 Authorization: Bearer ***로 보내고 게이트웨이가 이를 받아요. codex를 시작하고 /mcp를 실행하세요. 서버가 연결됨으로 그 도구 수와 함께 표시되고, /mcp verbose는 서버 이름이 접두사로 붙은 도구(my_mcp_server-read_wiki_structure)와 Auth: Bearer token을 나열해요.

서버 블록의 리터럴 bearer_token = "..."는 현재 Codex에서 bearer_token is not supported for streamable_http로 실패해요. bearer_token_env_var를 사용하세요. 서버가 전혀 표시되지 않으면, [features] 아래 experimental_use_rmcp_client = true가 설정되지 않는 한 원격 MCP 서버를 무시하는 오래된 Codex 빌드예요. Codex를 업그레이드하세요.

업스트림 OAuth 제공자를 앞에 두는 LiteLLM 서버의 경우, 정적 토큰을 설정하는 대신 codex mcp login litellm을 실행해 플로우를 완료하세요. MCP OAuth 참고.

문제 해결 (Troubleshooting)

• Connection refused는 설정한 base_url에서 게이트웨이에 도달할 수 없다는 뜻. 호스트, 포트, /v1 접미사를 확인하세요.
• 게이트웨이의 401은 LITELLM_API_KEY가 codex를 실행하는 셸에 export되지 않았거나, 키가 더 이상 유효하지 않다는 뜻.
• Invalid model name passed in은 model이 게이트웨이 콘피그의 model_name과 일치하지 않는다는 뜻. 업스트림 제공자의 이름이 아닌 사용자 이름을 사용하세요.
• 요청이 Admin UI에 절대 나타나지 않으면 여전히 기본 제공자에 있는 것이므로, 파일 최상위에 model_provider = "litellm"이 설정됐는지 확인하세요.

다음 단계 (Next steps)

ChatGPT Desktop의 Codex는 이 같은 콘피그 파일을 사용해요. LiteLLM virtual keys와 MCP gateway reference도 보세요.