게이트웨이를 통해 Codex 배포하기

조직의 LLM 게이트웨이를 통해 Codex를 배포합니다. 모델 경로를 구성하고, 개발자 자격 증명을 발급하고, 검증된 Codex 구성을 배포하세요.

사전 요구 사항

개발자에게 Codex를 배포하기 전에 다음이 준비되어 있는지 확인하세요.

• 배포할 정확한 기본 URL에서 HTTPS를 제공하는 게이트웨이.
• 게이트웨이에서 보관하는 업스트림 공급자 자격 증명.
• 의도한 업스트림 모델에 매핑된, 승인된 Codex용 모델 별칭.
• 권한 범위가 제한된 테스트용 게이트웨이 자격 증명.
• 비밀 정보 전달 수단 또는 테스트를 마친 자격 증명 헬퍼.
• 구성, 헬퍼 실행 파일, 필요한 카탈로그 파일을 배포할 수단.

게이트웨이 요구 사항

Codex를 연결하기 전에 게이트웨이 제품이 다음 필수 동작을 유지하는지 확인하세요.

• POST /v1/responses에서 Codex Responses API 요청을 수락합니다.
• 버퍼링 없이 SSE 이벤트를 스트리밍하고 response.completed로 종료합니다.
• 재전송된 입력을 사용해 후속 대화를 이어갑니다.
• WebSocket 또는 증분 전송이 활성화된 경우에만 previous_response_id를 유지합니다.
• 함수 호출과 이에 대응하는 function_call_output 항목을 유지합니다.
• 각 Codex용 모델 별칭을 의도한 업스트림 모델로 라우팅합니다.
• 사용자를 개별적으로 인증하고 원인을 숨기지 않는 유용한 오류를 반환합니다.

상태 확인 엔드포인트, /v1/models, Chat Completions 응답 또는 일반 텍스트 응답 하나만으로는 게이트웨이의 적합성을 확인할 수 없습니다. 자세한 규약은 게이트웨이 호환성 요구 사항을 참조하세요.

게이트웨이 도입하기

배포된 게이트웨이에서 검증된 개발자 환경으로 나아가려면 다음 다섯 가지 점검 단계를 순서대로 완료하세요.

1. 모델 이름 선택 및 경로 검증.
2. 개발자 자격 증명 발급.
3. 게이트웨이를 통한 Codex 테스트.
4. 구성 배포.
5. 개발자 컴퓨터에서 검증.

모델 이름과 경로 선택하기

Codex의 model를 게이트웨이의 모델 이름으로 설정하세요. 게이트웨이에서 해당 이름을 승인된 업스트림 모델로 라우팅하도록 구성하세요.

사용자 지정 이름에 모델 카탈로그 사용하기

게이트웨이가 Codex에서 인식하지 못하는 모델 이름을 사용한다면 model_catalog_json을 사용하세요. 카탈로그는 Codex가 해당 이름에 사용할 지침, 추론 옵션, 컨텍스트 한도, 도구 기능을 제공합니다. 일치하는 항목이 없으면 요청은 의도한 업스트림 모델에 도달하더라도 Codex는 일반 설정을 사용할 수 있습니다.

예를 들어 company-coding-model를 gpt-6-luna의 별칭으로 사용하려면 다음과 같이 하세요.

1. 게이트웨이에 company-coding-model 별칭을 만들고 승인된 업스트림 gpt-6-luna 모델로 라우팅합니다.
2. 사용 중인 Codex 버전의 Codex 모델 카탈로그를 다운로드하고 사본을 gateway-models.json로 저장합니다. 이 파일을 시작점으로 사용하세요.
3. 사본의 gpt-6-luna 항목을 편집합니다. slug를 company-coding-model로 설정하고 나머지 메타데이터가 업스트림 모델 및 게이트웨이 기능과 일치하는지 확인하세요. 모델 마이그레이션이 없는 별칭이라면 upgrade를 null로 설정하세요.
4. 항목을 최상위 models 배열에 유지하고 파일을 각 클라이언트에 배포합니다. 사용자 지정 카탈로그는 번들로 제공되는 카탈로그를 대체하므로 사용자가 선택해야 하는 모든 모델을 포함하세요.

LiteLLM을 통해 Bedrock을 사용하는 경우 필수 카탈로그 수정 사항을 적용하세요.

게이트웨이 별칭, 카탈로그의 slug, Codex의 model를 company-coding-model로 설정하세요. 파일의 실제 절대 경로를 사용해 배포할 Codex 구성의 첫 번째 TOML 테이블 앞에 다음 설정을 추가하세요.

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

Codex는 시작할 때 카탈로그를 로드하므로 카탈로그를 변경한 후 CLI 또는 데스크톱 앱을 다시 시작하세요.

모델 경로 검증하기

각 모델에 대해 실제 Responses 요청과 게이트웨이 기록으로 경로를 검증하세요. /v1/models 응답은 이름을 찾는 데 도움이 될 수 있지만, 모델이 필요한 요청 및 도구 동작을 지원한다는 증거는 아닙니다.

모델 라우팅과 도구 권한 부여는 도입 과정에서 별도로 다루어야 합니다. MCP 연결, 플러그인 배포, 관련 정책은 따로 구성하세요.

개발자 자격 증명 발급하기

1. 사용량을 개발자별로 식별하고 접근 권한을 개별적으로 취소할 수 있도록 개발자마다 권한 범위가 제한된 게이트웨이 자격 증명을 하나씩 발급합니다.
2. 각 자격 증명의 승인된 모델, 요청 속도 제한, 예산, 만료 시점, 갱신 주기를 설정합니다.
3. 비밀 정보 관리자 또는 설치된 자격 증명 헬퍼를 통해 자격 증명을 전달합니다. 업스트림 공급자 및 게이트웨이 관리자 자격 증명은 개발자 컴퓨터에 두지 마세요.
4. 헬퍼를 사용한다면 명령 기반 인증 규약을 따르고 배포 전에 토큰 조회 및 갱신을 테스트합니다.
5. 개발자에게 자격 증명 갱신 방법과 도움을 요청할 담당자를 안내합니다.

게이트웨이를 통해 Codex 테스트하기

배포하기 전에 게이트웨이에 연결하기에 따라 격리된 테스트 사용자 한 명을 대상으로 배포 예정인 공급자 블록과 자격 증명 방식을 구성하세요.

개발자가 사용할 것과 동일한 CLI 또는 데스크톱 환경에서 아래 항목을 점검하세요.

이 점검을 모두 통과한 후 개발자가 자신의 컴퓨터를 구성하고 검증할 수 있도록 게이트웨이에 연결하기를 안내하세요.

구성 배포하기

모든 컴퓨터가 동일한 연결 경로를 사용하도록 게이트웨이 기본 URL, 공급자 ID, 승인된 모델 별칭, 자격 증명 방식을 배포하세요.

배포할 항목

공급자 기본값을 설정하려면 선택한 구성 계층을 통해 이 config.toml 블록을 배포하세요. 사용 중인 Codex 버전에서 인식하는 모델을 사용하거나 위에서 설명한 일치하는 카탈로그를 제공하세요. 구성된 명령 경로에 토큰 리졸버를 설치하세요.

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

단기 정적 테스트 키를 사용하려면 auth 블록을 제거하고 env_key = "CODEX_GATEWAY_API_KEY"를 [model_providers.enterprise-gateway] 안에 넣은 다음 TOML 외부에서 해당 변수를 설정하세요. env_key를 명령 기반 인증과 함께 사용하지 마세요.

기본값과 필수 설정 배포하기

구성 우선순위를 참고해 기본값을 배포할 위치를 선택하세요. 강제 적용되는 설정과 macOS MDM 페이로드는 관리형 구성을 참조하세요.

macOS 또는 Linux에서 호스트 전체의 기본값을 설정하려면 /etc/codex/config.toml를 사용하세요. Windows에서는 config.toml를 %ProgramData%\OpenAI\Codex\에 배치하세요. 사용자와 프로필은 이러한 기본값을 재정의할 수 있습니다. 링크된 참고 문서에서 지원되는 필수 설정과 해당 파일 위치를 설명합니다.

참조되는 헬퍼 실행 파일과 카탈로그 파일은 별도로 배포하세요.

model_catalog_json는 로컬 JSON 파일을 가리킵니다. requirements.toml를 통해 이를 강제 적용하면 필수 설정은 경로를 고정할 뿐, 파일을 배포하지는 않습니다. Codex가 시작되기 전에 해당 절대 경로에 카탈로그를 배치하세요.

TOML에는 변수 등이 해석된 Windows 절대 경로를 작성하세요. Codex는 %ProgramData%를 model_catalog_json 또는 공급자 인증의 command 값 안에서 확장하지 않습니다. 예를 들어 다음 경로는 배포 과정에서 해당 위치에 파일을 배치한 경우에만 사용하세요.

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

WSL 내의 CLI는 Linux 경로와 Linux의 CODEX_HOME를 읽으며, 네이티브 Windows 구성을 자동으로 상속하지 않습니다.

개발자에게 구성 값 전달하기

관리형 배포를 사용하지 않는다면 각 개발자에게 게이트웨이 URL, 공급자 ID, 모델 별칭, 자격 증명 변수 또는 리졸버, 필요한 카탈로그 경로를 제공하세요. 개발자가 자신의 컴퓨터를 구성하고 검증할 수 있도록 게이트웨이에 연결하기를 안내하세요.

수동 설정은 설정을 강제 적용하는 수단이 아닙니다. 프로젝트 로컬 .codex/config.toml는 민감한 공급자 또는 인증 라우팅 키를 재정의할 수 없습니다.

개발자 컴퓨터에서 검증하기

배포한 설정이 개발자 컴퓨터에 반영되었는지 확인하려면 다음과 같이 하세요.

1. Codex를 다시 시작하고 예상한 공급자와 모델이 설정되어 있는지 확인합니다.
2. 게이트웨이에 연결하기의 짧은 테스트를 실행합니다.
3. 후속 질문을 한 번 하여 대화가 이어지는지 확인한 다음, 게이트웨이 로그에서 해당 개발자의 요청을 확인합니다.

도입 중 발생하는 문제 해결하기

문제를 바탕으로 점검이 필요한 구성, 자격 증명 또는 게이트웨이 계층을 찾으세요.

기존 게이트웨이 배포 재사용하기

조직에서 이미 게이트웨이를 통해 Claude Code를 사용한다면 게이트웨이 제품, 네트워크 경로, 로깅, Bedrock 접근을 재사용할 수 있습니다. 기존의 정상 작동하는 설정을 유지하면서 Codex용 Responses 경로, 자격 증명, 모델 별칭, config.toml를 추가하세요. Claude 클라이언트 설정과 /v1/messages 규약으로는 Codex를 구성할 수 없습니다.

안전하게 마이그레이션하려면 다음 단계를 순서대로 완료하세요.

1. 현재 Claude 경로를 정리합니다. 게이트웨이 URL, 자격 증명 소스, 필수 헤더, 모델 별칭, Bedrock 프로필 매핑, 관리형 전달 채널을 포함하세요.
2. 기존 경로와 병행하는 Codex용 Responses 경로와 Codex 모델 별칭을 추가합니다.
3. 권한 범위가 제한된 Codex 자격 증명을 하나 발급합니다. Codex가 정적 자격 증명을 사용한다면 새 자격 증명을 env_key를 통해 제공하세요. Claude가 자격 증명 헬퍼를 사용한다면 Codex 명령 기반 리졸버 규약을 구현하고 테스트하세요.
4. 해당 개발자에게 공급자 블록을 구성합니다. 관리형 도입이라면 게이트웨이를 통해 Codex 배포하기에서 설명하는 Codex 경로와 우선순위에 맞게 페이로드를 변환하세요.
5. 개발자가 실제로 사용하는 CLI 또는 데스크톱 환경에서 짧은 연결 점검을 실행한 다음, 게이트웨이를 통해 Codex 테스트하기의 스트리밍, 대화 이어가기, 도구 호출, 오류, 로깅, 별칭 라우팅 점검을 모두 실행합니다.
6. 시범 운영을 통과하면 나머지 개발자에게 구성을 배포합니다.

관련 문서

• 게이트웨이에 연결하기
• MCP
• 플러그인
• 관리형 구성