게이트웨이 배포하기
조직에 Codex 게이트웨이 연결을 배포하고 확인하세요
게이트웨이 관리자는 모델 경로를 설정하고 시범 사용자에게 권한을 부여하세요. 개발자에게 설정을 배포하기 전에 지원하는 각 클라이언트에서 연결을 테스트하세요. 게이트웨이 인증에는 네이티브 게이트웨이 OAuth, API key 또는 자격 증명 도우미를 사용하세요. 게이트웨이 인증과 ChatGPT 워크스페이스 로그인을 함께 사용하려면 게이트웨이를 통해 ChatGPT로 로그인을 참고하세요.
사전 요구 사항
개발자에게 Codex를 배포하기 전에 다음이 준비되어 있는지 확인하세요.
- 배포할 정확한 기본 URL에서 HTTPS를 제공하는 게이트웨이.
- 게이트웨이에 보관된 업스트림 공급자 자격 증명.
- 의도한 업스트림 모델에 매핑된, 승인된 Codex용 모델 별칭.
- 테스트를 마친 인증 방식: 네이티브 게이트웨이 OAuth, 범위가 지정된 게이트웨이 API key 또는 자격 증명 도우미.
- OAuth의 경우 등록된 공개 클라이언트, 승인된 테스트 사용자, OAuth 액세스 토큰 검증을 지원하는 게이트웨이.
- API key 또는 도우미의 경우 비밀 정보 전달 수단 또는 테스트를 마친 도우미.
- 구성, 필요한 도우미, 카탈로그 파일을 배포할 수단.
게이트웨이 요구 사항
Codex를 연결하기 전에 게이트웨이 제품이 다음 필수 동작을 유지하는지 확인하세요.
POST /v1/responses에서 Codex Responses API 요청을 수락합니다.- 버퍼링 없이 SSE 이벤트를 스트리밍하고
response.completed로 종료합니다. - 재전송된 입력을 사용해 후속 대화를 이어갑니다.
- WebSocket 또는 증분 전송이 활성화된 경우에만
previous_response_id를 유지합니다. - 함수 호출과 이에 대응하는
function_call_output항목을 유지합니다. - 각 Codex용 모델 별칭을 의도한 업스트림 모델로 라우팅합니다.
- 사용자를 개별적으로 인증하고 원인을 숨기지 않는 유용한 오류를 반환합니다.
상태 확인 엔드포인트, /v1/models, Chat Completions 응답 또는 일반 텍스트 응답 하나만으로는 게이트웨이의 적합성을 확인할 수 없습니다. 자세한 규약은 게이트웨이 호환성 요구 사항을 참조하세요.
게이트웨이 도입하기
배포된 게이트웨이에서 검증된 개발자 환경으로 나아가려면 다음 다섯 가지 점검 단계를 순서대로 완료하세요.
모델 이름과 경로 선택하기
Codex의 model을 게이트웨이의 모델 이름으로 설정하세요. 게이트웨이에서 해당 이름을 승인된 업스트림 모델로 라우팅하도록 구성하세요.
| 게이트웨이 모델 이름 | Codex 구성 |
|---|---|
| 사용 중인 Codex 버전에 포함된 기본 제공 모델 이름 | config.toml에서 model을 이 정확한 이름으로 설정합니다. |
company-coding-model 같은 사용자 지정 별칭 |
별칭과 해당 모델의 메타데이터가 포함된 원격 또는 로컬 카탈로그를 제공합니다. |
사용자 지정 이름에 모델 카탈로그 사용하기
로컬 카탈로그를 사용하려면 models.json 예제로 시작하세요.
게이트웨이가 Codex에서 인식하지 못하는 모델 이름을 사용하는 경우 모델 카탈로그를 제공하세요. 카탈로그는 Codex가 해당 이름에 사용하는 지침, 추론 옵션, 컨텍스트 한도 및 도구 기능을 제공합니다. 일치하는 항목이 없으면 요청이 의도한 업스트림 모델에 도달하더라도 Codex는 일반 설정을 사용할 수 있습니다.
model_providers.<id>.model_catalog_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 key 기반, 명령 기반 또는 Codex 백엔드 인증이 필요합니다. 네이티브 게이트웨이 OAuth나 사용자 지정 헤더만으로는 검색이 실행되지 않습니다.
승인된 모델이 변경되면 공급자와 협의하여 카탈로그를 업데이트하세요. 클라이언트의 구성을 변경한 후에는 클라이언트를 다시 시작하세요.
requirements.toml을 통해 적용된 설정을 포함하여 실제로 적용되는 model_catalog_json 설정을 모두
제거하세요. 이 설정은 원격 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
- PKCE를 사용하는 인증 코드 방식을 지원하는 공개 OAuth 클라이언트를 등록하고, 로그인할 수 있는 사용자 또는 그룹을 승인하세요.
- 선택한 쿠키 또는 사용자 지정 헤더에서 발급된 액세스 토큰을 검증하도록 게이트웨이를 구성하세요. 승인된 모델, 요청 한도, 예산을 각 사용자 ID에 적용하세요.
- 네이티브 게이트웨이 OAuth에 따라 인증 및 토큰 URL, 공개 클라이언트 ID, 범위, 선택적 리소스, 토큰 전달 설정, 고정 리디렉션 포트가 있다면 해당 포트를 수집하세요. 이에 맞는 루프백 리디렉션 URI를 ID 공급자에 등록하세요.
- 배포할 CLI 또는 데스크톱 앱에서 테스트 사용자로 브라우저 로그인, 토큰 갱신, 액세스 취소를 테스트하세요. 원격 CLI 사용자를 포함해 브라우저가 콜백에 접근할 수 있는지 확인하세요.
사용자는 각자 로그인합니다. 배포하는 것은 OAuth 구성이며, 클라이언트 비밀 정보, 게이트웨이 API key 또는 도우미 실행 파일이 아닙니다. 업스트림 공급자 자격 증명은 게이트웨이에 보관하세요.
API key 또는 자격 증명 도우미
- 사용량을 개발자별로 식별하고 접근 권한을 개별적으로 취소할 수 있도록 개발자마다 권한 범위가 제한된 게이트웨이 자격 증명을 하나씩 발급합니다.
- 각 자격 증명의 승인된 모델, 요청 속도 제한, 예산, 만료 시점, 갱신 주기를 설정합니다.
- 비밀 정보 관리자 또는 설치된 자격 증명 헬퍼를 통해 자격 증명을 전달합니다. 업스트림 공급자 및 게이트웨이 관리자 자격 증명은 개발자 컴퓨터에 두지 마세요.
- 헬퍼를 사용한다면 명령 기반 인증 규약을 따르고 배포 전에 토큰 조회 및 갱신을 테스트합니다.
- 개발자에게 자격 증명 갱신 방법과 도움을 요청할 담당자를 안내합니다.
게이트웨이를 통해 Codex 테스트하기
배포하기 전에 공급자 구성에 따라 배포할 공급자 블록과 인증 방식으로 격리된 테스트 사용자 한 명의 환경을 구성하세요.
게이트웨이가 모델 카탈로그를 제공한다면, Codex와 호환되는 models 배열을 반환하는지 확인하세요. 사용자 자격 증명으로 OpenAI 추론을 수행하는 경우, 게이트웨이가 필수 ChatGPT 헤더를 Codex 백엔드로 전달하는지 확인하세요.
파일럿에 사용할 클라이언트 버전, 운영 체제, 공급자 ID, 모델 별칭, 인증 방식을 기록하세요. 지원할 각 CLI 또는 데스크톱 환경에서 아래 항목을 확인하세요. 게이트웨이 단독 인증과 ChatGPT 로그인에 게이트웨이 인증을 병행하는 방식을 모두 제공한다면 각 조합을 별도로 테스트하세요.
| 확인 항목 | 작업 | 통과 근거 |
|---|---|---|
| 실제 적용된 구성 | 구성 계층을 살펴보고 의도한 공급자, 모델, 요구 사항이 적용되었는지 확인하세요. | 파일럿에 배포된 설정이 사용됩니다. 사용자 또는 프로필 기본값으로 인해 다른 경로가 선택되지 않습니다. |
| 연결 | 연결 확인을 따르세요. | 예상한 공급자와 별칭이 활성화되어 있고, 테스트 프롬프트가 성공하며, 게이트웨이 로그에서 테스트 사용자를 식별할 수 있습니다. |
| 스트리밍 | 여러 개의 짧은 문단으로 답변하도록 요청하세요. | 텍스트가 점진적으로 도착하고 활성 전송 방식에서 response.completed 이벤트가 발생합니다. HTTP를 별도로 테스트하여 게이트웨이가 버퍼링 없이 SSE 이벤트를 전달하는지 확인하세요. |
| 로컬 도구 루프 | 읽기 전용 권한이 있는 임시 폴더에서 Codex에 최상위 파일 목록을 나열하고 요약하도록 요청하세요. | Codex가 로컬 도구를 호출하고 결과를 반환한 뒤, 파일을 수정하지 않고 최종 답변을 생성합니다. |
| 후속 질문 | 같은 스레드에서 후속 질문을 하세요. | 답변에 이전 턴이 활용되고, 게이트웨이가 재전송된 입력을 수락합니다. WebSocket 또는 증분 전송이 활성화되어 있으면 previous_response_id도 유지됩니다. |
| 오류 및 사용자 귀속 | 의도적으로 잘못된 테스트 별칭이나 만료된 테스트 자격 증명을 사용하여 반복하세요. | 클라이언트가 유용한 라우팅 또는 인증 오류를 수신하고, 유효한 요청은 계속 테스트 사용자에게 귀속됩니다. |
자동 승인이 활성화되어 있다면 임시 테스트 폴더에서 적용하려는 정책에 따라 검토가 필요한 도구 작업을 실행하세요. 게이트웨이가 검토 요청을 처리하고 클라이언트가 승인 결정을 적용하는지 확인하세요. 승인이 필요 없는 읽기 전용 도구 호출로는 이 경로를 테스트할 수 없습니다. 파일럿을 확대하기 전에 지원되지 않는 워크플로를 기록하세요.
이번 도입으로 기존 사용자의 공급자가 변경된다면 지원하는 각 클라이언트에서 새 대화와 변경 전에 생성된 대화를 테스트하세요. 사용자가 기존 대화를 조회하거나 이어 가거나 분기할 수 있는지 기록하고, 진행할 수 없는 워크플로가 있으면 복구 절차를 제공하세요. 기본 공급자를 변경하면 대화 기록도 마이그레이션된다고 가정하지 마세요.
이러한 확인을 모두 통과하면 개발자 인계를 준비하세요.
구성 배포하기
모든 컴퓨터가 동일한 연결 경로를 사용하도록 게이트웨이 기본 URL, 공급자 ID, 승인된 모델 별칭, 인증 설정을 배포하세요.
배포할 항목
네이티브 게이트웨이 OAuth의 경우 공급자 테이블과
[model_providers.<id>.gateway_oauth] 테이블을 연결
가이드에서 가져와
앞서 수집한 등록 값을 넣어 배포하세요. requires_openai_auth = false는 유지하고
env_key, experimental_bearer_token, 명령 기반 auth 테이블은
OAuth가 유일한 게이트웨이 자격 증명인 경우 생략하세요.
자격 증명 도우미의 경우 선택한 구성 계층을 통해 다음 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를 사용하세요. 테스트 요청을 보내고 게이트웨이 로그에서 선택된 경로를 확인하세요. 헤더 옵션은 사용자 지정 모델 공급자를 참고하세요.
개발자에게 구성 값 전달하기
테스트한 파일럿에 맞는 하나의 설정 절차를 개발자에게 제공하세요. 구성을 중앙에서 배포하더라도 다음 정보를 포함하세요.
| 인계 항목 | 제공할 내용 |
|---|---|
| 승인된 클라이언트 | 파일럿에 사용한 클라이언트, 버전, 운영 체제, 설치 또는 업데이트 지침. |
| 구성 전달 방식 | 설정이 이미 관리되고 있는지, 로컬 설정이 필요한지 여부와 별도로 설치되는 도우미 또는 카탈로그 파일. |
| 예상 연결 정보 | API 경로를 포함한 게이트웨이 URL, 공급자 ID, 모델 별칭. 사용자가 변경할 수 있는 값을 설명하세요. |
| 로그인 단계 | 사용자가 ChatGPT 워크스페이스에 로그인해야 하는지, 게이트웨이에서 인증해야 하는지, 둘 다 필요한지 여부. 필수 워크스페이스와 게이트웨이 인증 방식을 명시하세요. |
| 자격 증명 및 카탈로그 | OAuth 등록 값, 자격 증명 환경 변수 또는 설치된 도우미 구성과 카탈로그 URL 또는 확인된 로컬 경로. 비밀 정보는 승인된 비밀 정보 배포 수단을 통해 전달하세요. |
| 검증 및 지원 | 연결 테스트, 예상 결과, 게이트웨이 담당자, 실패 보고 시 포함할 정보. |
관리형 컴퓨터를 사용하는 개발자에게는 기존 구성 확인을 안내하세요. 수동으로 설정하는 개발자에게는 공급자 구성을 안내하세요.
이번 도입으로 공급자가 변경된다면 기존 대화에 대해 테스트한 지침을 포함하세요. 파일럿에서 문제가 발견될 경우에 대비해 도입 담당자가 이전에 정상 작동하던 구성을 사용할 수 있도록 보관하세요.
수동 설정은 설정을 강제 적용하는 수단이 아닙니다. 프로젝트 로컬 .codex/config.toml은 민감한 공급자 또는 인증 라우팅 키를 재정의할 수 없습니다.
개발자 컴퓨터에서 검증하기
배포한 설정이 개발자 컴퓨터에 반영되었는지 확인하려면 다음과 같이 하세요.
- 승인된 클라이언트와 필요한 도우미 또는 카탈로그 파일이 설치되어 있는지 확인하세요. Codex를 다시 시작하고 인계 지침에 따라 로그인을 완료하세요.
- 예상한 공급자와 모델이 적용되어 있는지 확인하세요. CLI에서는
/status를 사용하세요. 실제 적용된 설정이 인계 내용과 다르면/debug-config를 사용하여 구성 계층을 살펴보세요. - 게이트웨이에 연결의 간단한 테스트를 실행하세요.
- 후속 질문을 한 번 하여 대화가 이어지는지 확인한 다음, 게이트웨이 로그에서 해당 개발자의 요청을 확인하세요.
지원하는 클라이언트와 인증 조합에서 파일럿을 통과한 후 액세스 대상을 확대하세요. 클라이언트, 게이트웨이 또는 정책 업데이트 후에도 확인 절차를 반복할 수 있도록 테스트한 구성과 결과를 도입 지침과 함께 보관하세요.
도입 중 발생하는 문제 해결하기
문제를 바탕으로 점검이 필요한 구성, 자격 증명 또는 게이트웨이 계층을 찾으세요.
| 문제 | 해결 방법 |
|---|---|
| 다시 시작한 후 예상한 공급자가 표시되지 않습니다. | 우선 적용되는 구성 계층을 확인하세요. 사용자 또는 프로필 구성이 시스템 기본값을 재정의할 수 있습니다. |
| 모든 사용자의 인증이 실패합니다. | 게이트웨이 인증과 업스트림 공급자 자격 증명을 확인하고, 어떤 서비스가 요청을 거부했는지 파악하세요. |
| 한 사용자의 인증이 실패합니다. | 해당 사용자의 ID 공급자 액세스, 게이트웨이 자격 증명 또는 토큰 리졸버를 확인하세요. |
| 스트리밍이 멈춥니다. | 게이트웨이 버퍼링과 종료 response.completed 전달을 확인하세요. |
| 모델이 없거나 일반적인 기능을 사용합니다. | 사용자 지정 별칭의 경우 게이트웨이 별칭, Codex model, 카탈로그 slug가 일치하는지 확인하세요. 카탈로그 경로와 설치된 Codex 버전과의 호환성을 확인한 후 Codex를 다시 시작하세요. |
| Windows 경로에 문제가 있습니다. | 완전히 해석된 절대 경로를 사용하세요. TOML에서 단일 백슬래시가 포함된 Windows 경로에는 작은따옴표로 묶은 문자열을 사용하세요. |
기존 게이트웨이 배포 재사용하기
조직에서 이미 게이트웨이를 통해 Claude Code를 사용한다면
게이트웨이 제품, 네트워크 경로, 로깅, Bedrock 접근을 재사용할 수 있습니다.
기존의 정상 작동하는 설정을 유지하면서 Codex용 Responses 경로, 자격 증명, 모델 별칭, config.toml을
추가하세요. Claude 클라이언트 설정과
/v1/messages 규약으로는 Codex를 구성할 수 없습니다.
| 기존 Claude 배포 | Codex 마이그레이션 |
|---|---|
| 게이트웨이 제품, DNS, TLS, 프라이빗 네트워킹, 로깅, 민감 정보 가림 처리, 모니터링 | 이러한 서비스는 유지하세요. 게이트웨이 호환성 요구 사항을 충족하는 Codex용 경로를 추가하세요. |
| Bedrock 계정, 공급자 자격 증명, IAM 경계, 추론 프로필, 자격 증명 교체 | 새 Codex 별칭이 가리키는 업스트림 모델에 권한을 부여하는 경우에만 유지하세요. 공급자 자격 증명은 게이트웨이에 계속 보관합니다. |
Claude /v1/messages 경로, Bedrock InvokeModel 형식, Anthropic 헤더, Claude 전용 재시도 또는 오류 |
이를 호환성의 근거로 재사용하지 마세요. Codex에는 POST /v1/responses, Responses 스트리밍, 대화 이어가기, 도구 호출, 유용한 오류 정보가 필요합니다. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY 또는 apiKeyHelper |
Codex는 apiKeyHelper을 지원하지 않습니다. 네이티브 게이트웨이 OAuth, env_key을 사용하는 범위가 지정된 키 또는 Codex 명령 기반 토큰 리졸버를 구성하세요. |
Claude 모델 이름, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides, Bedrock 프로필 매핑 |
게이트웨이 팀에 모델 이름을 선택하고 필요한 사용자 지정 별칭을 구성하도록 요청하세요. 팀에서 제공하는 모델 이름과 모델 카탈로그 JSON을 사용하세요. |
Claude settings.json, managed-settings.json, JSON env 블록, plist 또는 레지스트리 페이로드 |
동일한 MDM 또는 구성 관리 채널을 유지하되, Codex config.toml 및 지원되는 requirements.toml 값을 대신 배포하세요. |
안전하게 마이그레이션하려면 다음 단계를 순서대로 완료하세요.
- 현재 Claude 경로의 구성 요소를 파악하세요. 게이트웨이 URL, 자격 증명 소스, 필수 헤더, 모델 별칭, Bedrock 프로필 매핑, 관리형 배포 채널을 확인하세요.
- 기존 경로와 병행할 Codex용 Responses 경로와 Codex 모델 별칭을 추가하세요.
- 게이트웨이 자체 OAuth, API key 또는 자격 증명 도우미를 선택하고 테스트 사용자 한 명에게 권한을 부여하세요. 정적 자격 증명은
env_key를 통해 제공하세요. 도우미를 사용한다면 Codex의 명령 기반 리졸버 규약을 구현하고 테스트하세요. - 3단계에서 선택한 인증 방식을 사용하여 해당 개발자의 공급자를 구성하세요. 관리형 도입의 경우 게이트웨이 도입에 설명된 Codex 경로와 우선순위에 맞게 페이로드를 변환하세요.
- 개발자가 실제로 사용하는 CLI 또는 데스크톱 환경에서 간단한 연결 확인을 실행한 다음, 게이트웨이를 통한 Codex 테스트의 스트리밍, 대화 이어 가기, 도구 호출, 오류, 로깅, 별칭 라우팅 확인을 모두 실행하세요.
- 파일럿을 통과한 후 나머지 개발자에게 구성을 배포하세요.
모델 카탈로그 참조
로컬 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 버전에 맞는 업스트림 제공자의 현재 기본값을 가져온 다음, 재정의할 설정을 적용하고 최종 카탈로그를 반환하세요.
client_version 카탈로그 엔드포인트 구현
기본 카탈로그 엔드포인트는 제공자의 base_url 아래에 있는 /models입니다.
예를 들어 base_url = "https://gateway.example.com/v1"인 경우 Codex는 다음과 같이 요청합니다:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>기본 검색은 명령 기반 인증과 ChatGPT 같은 Codex 백엔드
인증을 지원합니다. 명령 기반 인증 없이 API key 인증을 사용하는 사용자 지정 제공자의 경우
model_providers.<id>.model_catalog_url을
명시적으로 설정하여 원격 검색을 활성화하세요. API key만으로는 기본 경로에서
검색이 실행되지 않습니다.
model_catalog_url을 사용하여 다음과 같은 전체 카탈로그 URL을 지정하세요:
https://gateway.example.com/codex/models. 기본
/v1/models 엔드포인트를 지정할 수도 있습니다. Codex는 /models를 덧붙이지 않고 이 URL을 그대로 사용합니다.
API key를 통한 검색을 사용하려면 features.api_key_model_discovery를 활성화된 상태로 유지하세요. 이 설정은
기본적으로 켜져 있습니다. 사용자 지정 헤더만으로는 검색이 활성화되지 않습니다.
Codex는 선택한 제공자의 인증 정보와 구성된 헤더를 전송하고,
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 key를 사용하는 경우:
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 key로는 OpenAI에 인증할 수 없습니다.
최상위 models 배열을 포함한 전체 응답을 파싱하세요. 이 엔드포인트는
지침, 추론 기본값, 도구 설정,
컨텍스트 한도, 서비스 등급 등의 Codex 메타데이터를 반환합니다. 공개 /v1/models 엔드포인트는
이 카탈로그를 제공하지 않습니다.
Codex 버전이 바뀌지 않았더라도 이 기본값을 새로 가져오세요. 요청 범위를 의도한 업스트림 ID로 한정하고 응답의 캐시 제어를 준수하세요: 카탈로그는 호출자의 접근 권한에 따라 달라질 수 있습니다. 재정의할 설정을 별도로 관리하여 새로 가져온 기본값에 다시 적용할 수 있도록 하세요.
제공자 재정의 설정 적용
해당 버전의 응답 구조를 유지하면서 필드 값을 변경하세요:
- 호출자가 사용할 수 있는 모델만 포함하도록 필터링하세요. 각
slug를 지원되는 추론 경로에 매핑하고display_name,description또는priority를 조정하세요. 모델 마이그레이션이 없는 별칭의 경우upgrade를null로 설정하세요. - 추론 옵션, 컨텍스트 한도, 입력 모달리티, 서비스 등급을
모델과 경로가 지원하는 값으로 설정하세요. 기본값은 지원되는
선택지 내에서 지정하세요. 서비스 등급이 없는 경로의 경우
service_tiers와additional_speed_tiers를 비우고default_service_tier를null로 설정하세요. - 대체할 지침과 도구 설정을 테스트하지 않았다면 업스트림의 지침과 도구 설정을 유지하세요. 메타데이터는 모델 기능을 추가하거나 추론 접근 권한을 부여하지 않습니다.
게이트웨이 모델 별칭을 사용하는 경우 모델 메타데이터 제공 방법을 참조하세요. 지원되는 각 Codex 버전에서 최종 카탈로그를 테스트하세요.
공개 Rust 타입 사용
클라이언트 스키마와 동일한 공개 Git 태그 또는 커밋의 크레이트를 사용하세요:
codex_protocol::openai_models::{ModelsResponse, ModelInfo}에는codex-protocol을 사용하세요.serde_json::from_slice::<ModelsResponse>()로 파싱하고catalog.models를 수정한 다음,serde_json::to_vec()로 전체 래퍼를 직렬화하세요. 래퍼는 모델 지침의 호환성 필드를 처리합니다.codex-models-manager::bundled_models_response()을 사용하여 해당 리비전의 정적 번들 카탈로그를ModelsResponse로 로드하세요. 이 함수는 현재 업스트림 기본값을 가져오지 않습니다.