게이트웨이 배포

게이트웨이 관리자는 모델 라우팅을 설정하고 시범 배포에 참여할 사용자 한 명에게 접근 권한을 부여하세요. 개발자에게 설정을 배포하기 전에 지원하는 각 클라이언트에서 연결을 테스트하세요. 게이트웨이 인증에는 게이트웨이 자체 OAuth, API 키 또는 자격 증명 헬퍼를 사용하세요. 게이트웨이 인증과 ChatGPT 워크스페이스 로그인을 함께 사용하려면 게이트웨이를 통해 ChatGPT로 로그인하기를 참고하세요.

사전 준비 사항

개발자에게 Codex를 배포하기 전에 다음 사항을 확인하세요.

• 게이트웨이가 배포할 기본 URL과 정확히 같은 주소에서 HTTPS 요청을 처리합니다.
• 게이트웨이가 업스트림 공급자의 자격 증명을 보관합니다.
• Codex에서 사용할 승인된 모델 별칭이 각각 의도한 업스트림 모델에 매핑되어 있습니다.
• 게이트웨이 자체 OAuth, 권한 범위가 제한된 게이트웨이 API 키, 자격 증명 헬퍼 중 사용할 인증 방식을 테스트했습니다.
• OAuth를 사용한다면 공개 클라이언트가 등록되어 있고 테스트 사용자가 승인되어 있으며, 게이트웨이에서 OAuth 액세스 토큰을 검증할 수 있습니다.
• API 키나 헬퍼를 사용한다면 비밀 정보를 전달할 수단이나 테스트를 마친 헬퍼가 있습니다.
• 설정, 필요한 헬퍼, 카탈로그 파일을 배포할 수 있습니다.

게이트웨이 요구 사항

Codex를 연결하기 전에 게이트웨이가 다음 요구 사항을 충족하는지 확인하세요.

• POST /v1/responses에서 Codex의 Responses API 요청을 받습니다.
• SSE 이벤트를 버퍼링 없이 스트리밍하고 response.completed로 스트림을 종료합니다.
• 이전 입력을 다시 전송하면 후속 요청에서 대화를 이어갈 수 있습니다.
• previous_response_id는 WebSocket 또는 증분 전송을 활성화한 경우에만 보존합니다.
• 함수 호출과 그에 대응하는 function_call_output 항목을 보존합니다.
• Codex에서 사용하는 각 모델 별칭의 요청을 의도한 업스트림 모델로 라우팅합니다.
• 사용자별로 인증하고, 오류가 발생하면 원인을 파악할 수 있는 오류 메시지를 반환합니다.

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

게이트웨이 배포 절차

배포한 게이트웨이를 개발자가 실제로 사용할 수 있는지 검증하려면 다음 다섯 단계를 순서대로 진행하세요.

1. 모델 이름을 선택하고 라우팅을 검증하세요.
2. 인증 방식을 선택하세요.
3. 게이트웨이를 통해 Codex를 테스트하세요.
4. 설정을 배포하세요.
5. 개발자 컴퓨터에서 검증하세요.

모델 이름 선택 및 라우팅 설정

Codex의 model 값을 게이트웨이의 모델 이름으로 설정하세요. 이 이름으로 들어오는 요청을 승인된 업스트림 모델로 라우팅하도록 게이트웨이를 설정하세요.

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

로컬 카탈로그를 사용하려면 models.json 예시부터 살펴보세요.

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

모델 메타데이터를 중앙에서 업데이트하려면 원격 카탈로그를 호스팅하고 model_providers.<id>.model_catalog_url로 URL을 지정하세요. 로컬 파일을 배포하려면 model_catalog_json으로 경로를 지정하세요. 게이트웨이 자체 OAuth가 유일한 인증 수단이라면 로컬 카탈로그를 사용하세요. OAuth만으로는 원격 카탈로그 자동 조회가 활성화되지 않습니다. 두 설정에 대한 자세한 내용은 설정 레퍼런스를 참고하세요.

클라우드 또는 게이트웨이 공급자로부터 사용 중인 Codex 버전과 호환되는 카탈로그 엔드포인트나 파일을 받으세요. 승인된 각 별칭과 해당 모델의 메타데이터가 포함되어 있는지 확인하세요. 카탈로그 구현 방법은 게이트웨이 및 클라우드용 모델 카탈로그 구현을 참고하세요.

원격 카탈로그 제공

공급자가 제공하는 HTTPS 카탈로그 엔드포인트를 사용하세요. 선택한 공급자의 config.toml 테이블에 엔드포인트의 전체 URL을 넣어 배포하세요.

model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"

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

Codex 프로세스가 CODEX_GATEWAY_API_KEY 환경 변수를 읽을 수 있도록 설정하세요. 추론 요청을 게이트웨이로 라우팅하려면 base_url을 별도로 설정하세요. 생략하면 Codex는 현재 인증 방식에 해당하는 기본 OpenAI 엔드포인트를 사용합니다.

원격 카탈로그를 자동으로 조회하려면 API 키 인증, 명령어 기반 인증 또는 Codex 백엔드 인증이 필요합니다. 게이트웨이 자체 OAuth나 사용자 지정 헤더만으로는 자동 조회가 실행되지 않습니다.

승인된 모델이 변경되면 공급자와 협의해 카탈로그를 업데이트하세요. 클라이언트 설정을 변경한 뒤에는 클라이언트를 다시 시작하세요.

현재 적용 중인 model_catalog_json 설정은 requirements.toml에서 강제한 설정까지 모두 제거하세요. 이 설정이 원격 URL보다 우선하므로 설정이 남아 있으면 원격 카탈로그를 가져올 수 없습니다.

로컬 카탈로그 배포

model_catalog_json을 사용해 시작 시 공급자가 제공한 파일을 불러오세요. 사용자 지정 로컬 카탈로그는 기본 제공 카탈로그를 대체합니다.

게이트웨이 별칭, 카탈로그의 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 연결, 플러그인 배포 및 관련 정책은 따로 설정하세요.

인증 방식 선택

게이트웨이 자체 OAuth

1. PKCE를 사용하는 인가 코드 플로우를 지원하는 공개 OAuth 클라이언트를 등록하고, 로그인을 허용할 사용자나 그룹을 승인하세요.
2. 발급된 액세스 토큰을 선택한 쿠키 또는 사용자 지정 헤더에서 읽어 검증하도록 게이트웨이를 설정하세요. 인증된 사용자별로 승인된 모델, 요청 한도, 예산을 적용하세요.
3. 게이트웨이 자체 OAuth에 따라 인가 URL과 토큰 URL, 공개 클라이언트 ID, 권한 범위, 선택 사항인 리소스, 토큰 전달 설정, 고정 리디렉션 포트가 있다면 해당 포트까지 확인하세요. 이에 맞는 루프백 리디렉션 URI를 ID 공급자에 등록하세요.
4. 배포할 CLI 또는 데스크톱 앱에서 테스트 사용자로 브라우저 로그인, 토큰 갱신, 액세스 권한 취소를 테스트하세요. 원격 CLI 사용자의 환경에서도 브라우저가 콜백 주소에 접근할 수 있는지 확인하세요.

사용자는 각자 로그인합니다. 배포 대상은 OAuth 설정이며, 클라이언트 시크릿, 게이트웨이 API 키, 헬퍼 실행 파일은 배포하지 않습니다. 업스트림 공급자의 자격 증명은 게이트웨이에 보관하세요.

API 키 또는 자격 증명 헬퍼

1. 개발자별로 권한 범위가 제한된 게이트웨이 자격 증명을 하나씩 발급하세요. 그래야 각 개발자의 사용량을 파악하고 액세스 권한을 개별적으로 취소할 수 있습니다.
2. 각 자격 증명에 승인된 모델, 요청 한도, 예산, 만료 시점, 갱신 주기를 설정하세요.
3. 비밀 관리 도구나 설치된 자격 증명 헬퍼를 통해 자격 증명을 전달하세요. 업스트림 공급자 및 게이트웨이 관리자의 자격 증명은 개발자 컴퓨터에 저장하지 마세요.
4. 헬퍼를 사용한다면 명령어 기반 인증 사양을 따르고 배포 전에 토큰 조회와 갱신을 테스트하세요.
5. 개발자에게 자격 증명 갱신 방법과 도움이 필요할 때 문의할 곳을 안내하세요.

게이트웨이를 통한 Codex 테스트

배포를 시작하기 전에 공급자 설정에 따라 별도의 테스트 사용자 한 명에게 배포 예정인 공급자 설정 블록과 인증 방식을 적용하세요.

게이트웨이가 모델 카탈로그를 제공한다면 Codex와 호환되는 models 배열을 반환하는지 확인하세요. 사용자 자격 증명으로 OpenAI에 추론을 요청한다면 게이트웨이가 필수 ChatGPT 헤더를 Codex 백엔드로 전달하는지 확인하세요.

시범 배포에 사용하는 클라이언트 버전, 운영 체제, 공급자 ID, 모델 별칭, 인증 방식을 기록하세요. 지원할 CLI와 데스크톱 앱 각각에서 다음 항목을 점검하세요. 게이트웨이 인증만 사용하는 방식과 게이트웨이 인증에 ChatGPT 로그인을 함께 사용하는 방식을 모두 제공한다면 두 경우를 별도로 테스트하세요.

자동 승인을 활성화했다면 임시 테스트 폴더에서 배포할 정책에 따라 검토가 필요한 도구 작업을 실행하세요. 게이트웨이가 검토 요청을 처리하고 클라이언트가 승인 결정을 적용하는지 확인하세요. 승인이 필요 없는 읽기 전용 도구 호출로는 이 과정을 테스트할 수 없습니다. 시범 배포를 확대하기 전에 지원되지 않는 워크플로우를 기록하세요.

이번 배포로 기존 사용자의 공급자가 바뀐다면 지원하는 각 클라이언트에서 새 대화와 변경 전에 만든 대화를 모두 테스트하세요. 사용자가 기존 대화를 열어 보거나 이어가거나 브랜치할 수 있는지 각각 기록하고, 진행할 수 없는 워크플로우가 있다면 복구 절차를 안내하세요. 기본 공급자를 바꾸면 대화 기록도 이전된다고 가정하지 마세요.

모든 점검을 통과하면 개발자에게 전달할 설정과 안내를 준비하세요.

설정 배포

모든 컴퓨터가 같은 경로로 연결되도록 게이트웨이 기본 URL, 공급자 ID, 승인된 모델 별칭, 인증 설정을 배포하세요.

배포할 항목

게이트웨이 자체 OAuth를 사용한다면 공급자 테이블과 [model_providers.<id>.gateway_oauth] 테이블을 연결 가이드에 따라 작성하고, 앞에서 확인한 등록 값을 넣어 배포하세요. OAuth가 유일한 게이트웨이 인증 수단이라면 requires_openai_auth = false를 유지하고 env_key, experimental_bearer_token, 명령어 기반 auth 테이블을 생략하세요.

자격 증명 헬퍼를 사용한다면 선택한 설정 계층을 통해 다음 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와 명령어 기반 인증을 함께 사용하지 마세요.

기본값과 요구 사항 배포

사용자가 ChatGPT로 Codex에 로그인하지 않는다면 자체 서버에서 팀 설정을 배포할 수 있습니다. Codex는 모델 요청의 라우팅 방식과 관계없이 이 설정을 가져옵니다.

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

macOS 또는 Linux에서 호스트 전체에 적용할 기본값은 /etc/codex/config.toml에 지정하세요. Windows에서는 config.toml을 %ProgramData%\OpenAI\Codex\에 두세요. 사용자 설정과 프로필 설정은 이러한 기본값을 재정의할 수 있습니다. 지원되는 요구 사항과 해당 파일의 위치는 위 링크에서 확인하세요.

설정에서 참조하는 헬퍼 실행 파일과 로컬 카탈로그 파일은 별도로 배포하세요.

원격 카탈로그 URL을 강제하려면 requirements.toml의 [model_providers.<id>] 아래에 공급자 정의 전체를 넣으세요. 강제 적용되는 공급자 정의는 일반 설정에서 해당 공급자의 테이블을 대체하므로 base_url, 인증 설정, 그 밖의 필수 필드를 모두 포함해야 합니다. 공급자 선택까지 강제해야 한다면 model_provider 요구 사항을 사용하세요.

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 자체 설정을 자동으로 상속하지 않습니다.

라우팅 헤더 배포

게이트웨이가 설정이나 도구에 따라 요청을 라우팅한다면 관리형 requirements.toml의 공급자 설정에 게이트웨이가 요구하는 헤더를 추가하세요. 다음 예시는 라우팅 설정 ID를 전달하고 클라이언트가 Codex임을 나타냅니다.

[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'

클라이언트 환경에서 제공하는 헤더 값에는 env_http_headers를 사용하세요. 테스트 요청을 보내고 게이트웨이 로그에서 선택된 경로를 확인하세요. 헤더 옵션은 사용자 지정 모델 공급자를 참고하세요.

개발자에게 설정값 전달

시범 배포에서 검증한 설정 절차 하나를 개발자에게 안내하세요. 설정을 중앙에서 배포하더라도 다음 정보를 함께 제공하세요.

관리형 컴퓨터를 사용하는 개발자에게는 기존 설정 확인을 안내하세요. 수동 설정이 필요한 개발자에게는 공급자 설정을 안내하세요.

이번 배포로 공급자가 바뀐다면 기존 대화에 대해 테스트한 절차도 안내하세요. 시범 배포 중 문제가 발견될 경우에 대비해 배포 담당자가 이전에 정상 작동하던 설정을 사용할 수 있도록 보관하세요.

수동 설정으로는 설정값을 강제할 수 없습니다. 프로젝트 내 .codex/config.toml에서는 공급자 또는 인증 라우팅과 관련된 민감한 키를 재정의할 수 없습니다.

개발자 컴퓨터에서 검증

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

1. 승인된 클라이언트와 필요한 헬퍼 또는 카탈로그 파일이 설치되어 있는지 확인하세요. Codex를 다시 시작하고 개발자에게 안내한 로그인 절차를 완료하세요.
2. 예상한 공급자와 모델이 선택되었는지 확인하세요. CLI에서는 /status를 사용하세요. 실제 적용된 설정이 안내한 내용과 다르면 /debug-config로 설정 계층을 확인하세요.
3. 게이트웨이에 연결하기에 나온 간단한 테스트를 실행하세요.
4. 후속 질문을 한 번 보내 대화가 이어지는지 확인한 뒤, 게이트웨이 로그에서 해당 개발자의 요청을 확인하세요.

지원하는 클라이언트와 인증 방식의 조합이 모두 시범 배포 검증을 통과하면 접근 권한을 부여할 대상을 확대하세요. 클라이언트, 게이트웨이 또는 정책을 업데이트한 뒤 같은 점검을 반복할 수 있도록 테스트한 설정과 결과를 배포 지침과 함께 보관하세요.

배포 문제 해결

증상에 따라 설정, 자격 증명, 게이트웨이 중 어느 부분을 점검해야 하는지 확인하세요.

기존 게이트웨이 배포 환경 재사용

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

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

1. 현재 Claude 연결에 사용하는 게이트웨이 URL, 자격 증명을 가져오는 위치, 필수 헤더, 모델 별칭, Bedrock 프로필 매핑, 관리형 배포 채널을 파악하세요.
2. 기존 경로와 별도로 Codex용 Responses 경로와 Codex 모델 별칭을 추가하세요.
3. 게이트웨이 자체 OAuth, API 키 또는 자격 증명 헬퍼 중 하나를 선택하고 테스트 사용자 한 명에게 권한을 부여하세요. 고정 자격 증명은 env_key로 Codex에 전달하세요. 헬퍼를 사용한다면 Codex의 명령어 기반 토큰 조회 사양에 맞게 구현하고 테스트하세요.
4. 3단계에서 선택한 인증 방식으로 해당 개발자의 공급자를 설정하세요. 관리형 배포라면 게이트웨이 배포에 설명된 Codex 경로와 설정 우선순위에 맞게 페이로드를 변환하세요.
5. 개발자가 실제로 사용하는 CLI 또는 데스크톱 앱에서 간단한 연결 테스트를 실행하세요. 그런 다음 게이트웨이를 통한 Codex 테스트에 따라 스트리밍, 대화 이어가기, 도구 호출, 오류 처리, 로깅, 별칭 라우팅을 모두 점검하세요.
6. 시범 배포가 검증을 통과하면 나머지 개발자에게 설정을 배포하세요.

모델 카탈로그 레퍼런스

로컬 models.json 파일로 시작하기

먼저 Codex를 실행하는 컴퓨터에서 게이트웨이 공급자를 설정하고 선택하세요.

Codex를 실행하는 컴퓨터에 다음 카탈로그를 models.json으로 저장하세요. gateway-model을 게이트웨이가 허용하는 정확한 모델 ID로 바꾸세요. 표시 이름은 사용자가 모델 선택기에서 보는 이름입니다.

{
  "models": [
    {
      "slug": "gateway-model",
      "display_name": "Gateway model",
      "base_instructions": "Help the user with their coding tasks.",
      "supported_reasoning_levels": [],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "support_verbosity": false,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "experimental_supported_tools": []
    }
  ]
}

더 많은 항목이 포함된 예시는 Codex 모델 카탈로그를 참고하세요.

model_catalog_json 값을 config.toml에서 해당 파일의 절대 경로로 설정하세요. Codex를 다시 시작하고 Gateway model을 선택한 뒤 요청을 보내세요. 게이트웨이가 slug에 지정한 모델 ID를 받았는지 확인하세요.

기본 제공 모델에 별칭을 지정하려면 사용 중인 Codex 버전에서 해당 모델의 카탈로그 항목 전체를 복사한 뒤 slug와 display_name을 변경하세요. 별칭에 마이그레이션 대상이 없다면 upgrade를 null로 설정하세요. 이렇게 하면 모델의 컨텍스트 윈도우, 추론 옵션, 도구 설정이 유지됩니다.

클라이언트에 카탈로그 제공

이 문서는 Codex Models 형식을 구현하는 개발자를 위한 안내입니다. 이 형식은 모델 카탈로그를 정의하며 모델 선택기는 이 카탈로그를 사용합니다. 게이트웨이나 클라우드 서비스 같은 추론 공급자를 개발한다면 이 사양을 따르세요. 그러면 Codex 데스크톱 앱과 CLI가 공급자의 모델을 조회하고 각 모델의 지침과 기능 설정을 사용할 수 있습니다.

기업 관리자가 모델 카탈로그를 직접 관리하려면 model_catalog_url 설정 가이드를 참고하세요.

이 형식을 지원하려면 인증이 필요한 카탈로그 엔드포인트를 구현하세요. 요청을 보낸 Codex 버전에 맞춰 업스트림 공급자의 최신 기본값을 가져오고, 재정의할 값을 적용한 뒤 결과 카탈로그를 반환하세요.

카탈로그 엔드포인트 구현

기본 카탈로그 엔드포인트는 /models이며, 공급자의 base_url 아래에 있습니다. 예를 들어 base_url = "https://gateway.example.com/v1"이면 Codex는 다음 요청을 보냅니다.

GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

기본 경로에서의 자동 조회는 명령어 기반 인증과 ChatGPT 로그인 같은 Codex 백엔드 인증을 지원합니다. 사용자 지정 공급자가 명령어 기반 인증 없이 API 키 인증을 사용한다면 model_providers.<id>.model_catalog_url을 명시적으로 설정해 원격 자동 조회를 활성화하세요. API 키만으로는 기본 경로에서 자동 조회가 실행되지 않습니다.

model_catalog_url에 https://gateway.example.com/codex/models와 같은 전체 카탈로그 URL을 지정하세요. 기본 /v1/models 엔드포인트를 지정해도 됩니다. Codex는 이 URL에 /models를 덧붙이지 않고 그대로 사용합니다. API 키로 자동 조회하려면 기본적으로 켜져 있는 features.api_key_model_discovery를 활성 상태로 유지하세요. 사용자 지정 헤더만으로는 자동 조회가 활성화되지 않습니다.

Codex는 선택한 공급자의 인증 정보와 설정된 헤더를 전송하고, URL에 client_version과 공급자에 설정된 query_params를 추가합니다. 해당 자격 증명을 받을 권한이 있는 서비스에서 카탈로그를 호스팅하세요.

호출자를 인증한 뒤 해당 호출자에 맞는 업스트림 기본값을 가져오고, 재정의할 값을 적용한 다음 전체 ModelsResponse JSON을 그대로 반환하세요. 모든 항목에 비어 있지 않은 고유한 slug 값을 지정하세요. model_catalog_url을 명시한 경우 Codex는 리디렉션과 1 MiB를 초과하는 응답을 거부합니다. 추론 요청을 처리할 때도 계속 모델 접근 권한을 확인하고 적용하세요.

이 엔드포인트를 사용하는 클라이언트에서는 현재 적용 중인 model_catalog_json 설정을 모두 제거하세요. 로컬 파일이 우선하므로 이 설정이 남아 있으면 원격 카탈로그를 가져오지 않습니다.

클라이언트 스키마에 맞추기

카탈로그 요청에서 client_version 쿼리 매개변수를 확인하세요. Codex는 CLI 버전에서 시험판 접미사를 제거하고 major.minor.patch 형식으로 전송합니다. 데스크톱 클라이언트는 앱에 포함된 CLI의 버전을 전송합니다.

공개 Codex 리포지터리에서 해당 버전의 rust-v<version> 태그를 사용하세요. 사용자 지정 빌드라면 빌드에 사용한 정확한 소스 커밋을 사용하세요. 다음 링크는 rust-v0.162.1을 가리키므로 사용 중인 클라이언트에 맞는 리비전을 선택하세요.

• 스키마는 ModelsResponse 및 ModelInfo 응답 타입에서 확인하세요.
• 전체 예시는 기본 제공 models.json을 확인하세요. 이 파일에는 JSON Schema 문서가 아닌 실제 카탈로그 데이터가 들어 있습니다.

기본 제공 파일에는 릴리스 시점의 데이터가 담겨 있습니다. 카탈로그를 생성하기 전에 최신 기본값을 가져오세요.

최신 업스트림 기본값 가져오기

OpenAI 모델을 제공하는 클라우드 공급자는 OpenAI에서 기본값을 가져옵니다. 게이트웨이는 클라우드 또는 업스트림 공급자의 카탈로그를 읽어 배포된 모델의 설정과 계정 및 리전별 사용 가능 여부를 그대로 반영합니다. 각 단계에서 요청을 보낸 Codex의 버전을 전달하고 각 엔드포인트에서 별도로 인증하세요.

OpenAI에서 직접 기본값을 가져오려면 동일한 client_version으로 Codex 모델 엔드포인트를 호출하세요. 다음은 OpenAI API 키를 사용하는 예시입니다.

curl --fail --silent --show-error \
  'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

ChatGPT와 통합할 때는 호출자의 ChatGPT 액세스 토큰을 사용하고, 해당하는 경우 ChatGPT-Account-ID 헤더도 사용하세요. 업스트림 엔드포인트에 접근할 권한이 있는 자격 증명을 사용하세요. 게이트웨이 자체 API 키로는 OpenAI에 인증할 수 없습니다.

최상위 models 배열을 포함해 응답 전체를 파싱하세요. 이 엔드포인트는 지침, 추론 기본값, 도구 설정, 컨텍스트 한도, 서비스 등급 등의 Codex 메타데이터를 반환합니다. 공개 /v1/models 엔드포인트는 이 카탈로그를 제공하지 않습니다.

Codex 버전이 바뀌지 않아도 이 기본값을 갱신하세요. 카탈로그는 호출자의 접근 권한에 따라 달라질 수 있으므로 각 요청은 의도한 업스트림 계정의 권한 범위로 제한하고 응답의 캐시 제어 지시를 따르세요. 재정의할 값은 별도로 관리해 최신 기본값을 가져올 때마다 다시 적용할 수 있도록 하세요.

공급자별 재정의 값 적용

해당 버전의 응답 구조를 유지하면서 필드 값을 변경하세요.

• 호출자가 사용할 수 있는 모델만 남기세요. 각 slug를 지원되는 추론 경로에 매핑하고 display_name, description 또는 priority를 조정하세요. 마이그레이션할 모델이 없는 별칭은 upgrade를 null로 설정하세요.
• 추론 옵션, 컨텍스트 한도, 입력 모달리티, 서비스 등급은 모델과 경로가 모두 지원하는 값으로 설정하세요. 기본값도 지원되는 선택지 중에서 지정하세요. 서비스 등급이 없는 경로에서는 service_tiers와 additional_speed_tiers를 비우고 default_service_tier를 null로 설정하세요.
• 대체할 지침이나 설정을 테스트하지 않았다면 업스트림 지침과 도구 설정을 유지하세요. 메타데이터로 모델에 기능을 추가하거나 추론 요청 권한을 부여할 수는 없습니다.

게이트웨이 모델 별칭을 사용한다면 모델 메타데이터를 제공하는 방법을 참고하세요. 지원하는 각 Codex 버전에서 완성된 카탈로그를 테스트하세요.

공개 Rust 타입 사용

클라이언트 스키마와 동일한 공개 Git 태그 또는 커밋의 크레이트를 사용하세요.

• codex-protocol에서 codex_protocol::openai_models::{ModelsResponse, ModelInfo}를 사용하세요. serde_json::from_slice::<ModelsResponse>()로 응답을 파싱하고 catalog.models를 수정한 뒤 serde_json::to_vec()로 래퍼 전체를 직렬화하세요. 래퍼가 모델 지침의 호환성 필드를 처리합니다.
• codex-models-manager::bundled_models_response()를 사용해 해당 리비전에 기본 제공되는 정적 카탈로그를 ModelsResponse 타입으로 불러오세요. 이 함수는 최신 업스트림 기본값을 가져오지 않습니다.

관련 문서

• 공급자 설정
• MCP
• 플러그인
• 관리형 설정