게이트웨이 호환성 요구 사항
Codex 게이트웨이는 여기에 설명된 Responses API 동작을 유지해야 합니다. 여기에는 엔드포인트, 스트리밍, 대화 이어가기, 도구 호출, 인증, 라우팅, 유용한 오류가 포함됩니다.
요청과 엔드포인트
wire_api = "responses"로 게이트웨이 공급자를 구성하세요. 기본 URL이
https://gateway.example.com/v1와 같은 경우 게이트웨이는
POST /v1/responses를 수락하고 클라이언트가 사용하는 요청 및 응답 필드를 유지해야 합니다.
Chat Completions 또는 Anthropic Messages 엔드포인트가 작동한다고 해서
Responses 호환성이 입증되는 것은 아닙니다.
상태 확인 및 모델 목록 엔드포인트는 선택적인 운영 보조 수단입니다. 이러한 엔드포인트는 Codex 대화를 실행하지 않으며 도구 지원을 입증하지도 않습니다.
스트리밍
전체 답변을 버퍼링하지 말고 서버 전송 이벤트(SSE)를 점진적으로
전달하세요. 성공적인 종료를 나타내는
response.completed 이벤트를 포함해 이벤트 유형과 페이로드를 유지하세요. 클라이언트가
응답 실패와 연결 정지를 구분할 수 있도록 오류 및 실패 이벤트를 전달하세요.
게이트웨이뿐 아니라 로드 밸런서와 리버스 프록시를 통과하는 전체 스트림을 검증하세요. 스트림이 완료되지 않은 텍스트 응답만으로는 충분하지 않습니다.
대화 이어가기
후속 턴에서도 재전송된 대화 입력을 유지하세요. 게이트웨이는 다음 턴에 필요한 이전 메시지, 도구 호출, 도구 결과를 수락해야 합니다.
WebSocket 또는 증분 전송을 활성화한다면
previous_response_id 동작도 검증하세요. 상태를 유지하지 않는 HTTP Responses 경로는
이 대화 이어가기 방식 없이도 재전송된 입력을 사용할 수 있습니다.
도구
함수 호출 항목과 이에 대응하는 function_call_output 항목을
호출과 결과를 연결하는 식별자까지 포함해 유지하세요. 전체 루프가
작동해야 합니다. 즉, Codex가 호출을 수신하고 도구를 실행한 뒤 결과를 제출하고
최종 답변을 받아야 합니다.
텍스트 요청이 성공해도 이 루프가 검증되는 것은 아닙니다. 활성화할 실제 모델과 클라이언트 기능을 테스트하세요. 게이트웨이가 요청 필드를 수락한다고 해서 업스트림 모델이 해당 기능을 구현한다는 증거는 아닙니다.
인증과 헤더
배포에 선택한 클라이언트 인증 방식을 지원하세요.
env_key 또는 명령 기반 bearer 토큰을 사용하거나, 사용자 지정 헤더로 전송하는 자격 증명에는 env_http_headers을 사용합니다.
비밀 헤더 값에는 환경 변수를 사용하고,
구성에 하드코딩하지 마세요. 구성 및 자격 증명 헬퍼 규약은
사용자 지정 공급자 참고 문서를
참조하세요.
개발자는 게이트웨이의 업스트림 공급자 ID와 별도로 인증하세요. 관리자 키와 업스트림 자격 증명은 게이트웨이에 보관하세요. 라우팅과 사용자 식별에 필요한 헤더를 유지하고 자격 증명의 만료, 갱신, 취소를 테스트하세요.
모델 라우팅과 메타데이터
각 Codex용 모델 이름은 의도한 업스트림 모델로 라우팅되어야 합니다. 모델의 자기 설명에 의존하지 말고 게이트웨이 기록에서 경로를 검증하세요.
배포된 Codex 버전에서 인식하는 이름을 사용하거나
사용자 지정 별칭에 맞는 카탈로그를 제공하세요.
모델 가용성과 마이그레이션 메타데이터도 검토하세요. 대체 모델 역시
게이트웨이를 통해 라우팅되어야 합니다. 마이그레이션이 없는 조직 소유 별칭은
카탈로그 항목의 upgrade를 null로 설정하세요. 카탈로그 메타데이터는 클라이언트 동작에 정보를 제공하지만,
모델에 기능을 추가하거나
게이트웨이 경로를 만들지는 않습니다. 실제 업스트림 모델과 공급자를 기준으로
컨텍스트 한도, 추론 옵션, 도구를 검증하세요. 일반 게이트웨이 연결에는
Codex의 기본 제공 공급자 통합에서 수행하는 메타데이터 조정이
자동으로 적용되지 않습니다.
인식되는 모델 이름
배포된 Codex 버전에서 인식하는 정확한 모델 이름을 게이트웨이
별칭과 Codex의 model에 사용하세요. 업스트림 공급자가 해당 모델을 지원하고
조직에서 사용을 승인했는지 확인하세요.
codex --version를 확인하고 Codex 모델 카탈로그에서 일치하는 rust-v<version> 태그를 선택하세요.
사용자 지정 빌드라면 해당 소스 커밋을 사용하고, 데스크톱 배포라면
번들로 제공되는 CLI 버전에 맞추세요. 항목의 slug 값을 확인하여 해당
버전에서 인식하는 이름을 찾으세요. 게이트웨이가 모델의 기능을 변경한다면
이름이 인식되더라도 그 차이를 반영한 카탈로그 메타데이터를 제공하세요.
오류
클라이언트 인증 오류, 알 수 없는 모델 경로,
요청 속도 제한, 업스트림 실패를 유용하게 구분할 수 있도록 유지하세요. 모든 실패를
일반적인 500 응답으로 통합하지 마세요. 토큰, 공급자 자격 증명, 민감한 요청 내용을
노출하지 않으면서 실패한 계층을 진단할 수 있을 만큼 충분한 정보를 반환하세요.
데이터 및 도구 경계
모델 트래픽은 다음 경로를 따릅니다.
Codex client -> LLM gateway -> model provider클라이언트는 개발자 자격 증명으로 게이트웨이에 인증합니다. 게이트웨이는 업스트림 공급자 자격 증명을 사용해 모델에 접근합니다. 모델 요청에 포함된 프롬프트, 소스 발췌문, 도구 인수, 도구 결과는 게이트웨이를 통과할 수 있습니다. 이에 맞게 로깅, 보존, 민감 정보 마스킹, 접근, 내보내기 제어를 설정하세요.
모델 게이트웨이가 Codex의 모든 연결을 라우팅하는 것은 아닙니다. 로컬 명령은 클라이언트 실행 환경에서 실행됩니다. MCP server, 플러그인 서비스, 브라우저 및 앱 상호작용, 그 밖의 활성화된 서비스는 별도의 네트워크 경로와 자격 증명을 사용할 수 있습니다. 모델 공급자 구성은 이러한 권한을 부여하거나 해당 네트워크 제어를 대체하지 않습니다. 이러한 경계에 대해서는 에이전트 승인 및 보안과 MCP를 참조하세요.
적합성 점검 목록
배포된 클라이언트, 게이트웨이, 모델의 각 조합에 대해 다음 증거를 기록하세요.
- Responses 요청 및 응답 필드.
- 점진적 SSE 전달과 성공적인 종료.
- 재전송된 입력을 사용하는 후속 턴.
- 선택한 전송 방식에서 사용하는 경우
previous_response_id. - 함수 호출, 이에 대응하는 결과, 최종 답변.
- 올바른 모델 라우팅과 일치하는 메타데이터.
- 사용자별 요청 식별, 자격 증명 갱신 및 취소.
- 유용한 인증, 라우팅, 요청 속도 제한, 업스트림 오류.
- 민감 정보가 마스킹된 진단 정보와 의도한 로깅 정책.
도입 테스트 절차에 따라 구성을 배포하기 전에 이 증거를 수집하세요.