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