OpenResponses Gateway 통합 계획

배경

OpenClaw Gateway는 현재 /v1/chat/completions에 최소한의 OpenAI 호환 Chat Completions 엔드포인트를 노출합니다 (OpenAI Chat Completions 참조).

Open Responses는 OpenAI Responses API를 기반으로 한 개방형 추론 표준입니다. 에이전트 워크플로를 위해 설계되었으며 항목 기반 입력과 시맨틱 스트리밍 이벤트를 사용합니다. OpenResponses 명세는 /v1/chat/completions가 아닌 /v1/responses를 정의합니다.

목표

• OpenResponses 시맨틱을 따르는 /v1/responses 엔드포인트 추가.
• Chat Completions를 비활성화하기 쉽고 최종적으로 제거할 수 있는 호환성 레이어로 유지.
• 격리된 재사용 가능한 스키마로 유효성 검증 및 파싱 표준화.

비목표

• 첫 패스에서 완전한 OpenResponses 기능 동등성 (이미지, 파일, 호스팅 도구).
• 내부 에이전트 실행 로직이나 도구 오케스트레이션 교체.
• 첫 단계에서 기존 /v1/chat/completions 동작 변경.

제안 아키텍처

• /v1/responses를 위한 src/gateway/openresponses-http.ts (또는 open-responses-http.ts) 추가.
• Zod 스키마만 포함하는 src/gateway/open-responses.schema.ts 추가 (게이트웨이 임포트 없음).
• src/gateway/openai-http.ts는 레거시 호환성 어댑터로 유지.
• 설정 gateway.http.endpoints.responses.enabled 추가 (기본 false).
• gateway.http.endpoints.chatCompletions.enabled는 독립적으로 유지; 두 엔드포인트를 개별 토글 가능.
• Chat Completions가 활성화되면 시작 시 레거시 상태를 알리는 경고 발생.

1단계 지원 범위

• input을 문자열 또는 메시지 역할과 function_call_output가 있는 ItemParam[]로 수용.
• 시스템 및 개발자 메시지를 extraSystemPrompt로 추출.
• 가장 최근 user 또는 function_call_output을 에이전트 실행을 위한 현재 메시지로 사용.
• 지원되지 않는 콘텐츠 파트(이미지/파일)는 invalid_request_error로 거부.
• output_text 콘텐츠가 있는 단일 어시스턴트 메시지 반환.
• 토큰 계정이 연결될 때까지 0값으로 usage 반환.

스트리밍 구현 (1단계)

• event:와 data: 모두 포함하는 SSE 라인.
• 필수 시퀀스 (최소 실행 가능):
  • response.created
  • response.output_item.added
  • response.content_part.added
  • response.output_text.delta (필요에 따라 반복)
  • response.output_text.done
  • response.content_part.done
  • response.completed
  • [DONE]

테스트 및 검증 계획

• /v1/responses에 대한 e2e 커버리지 추가:
  • 인증 필요
  • 비스트림 응답 형태
  • 스트림 이벤트 순서 및 [DONE]
  • 헤더와 user를 통한 세션 라우팅
• src/gateway/openai-http.test.ts는 변경 없이 유지.

Chat Completions 폐지 경로

• 엄격한 모듈 경계 유지: responses와 chat completions 간 공유 스키마 타입 없음.
• Chat Completions를 설정으로 옵트인하여 코드 변경 없이 비활성화 가능.
• /v1/responses가 안정화되면 Chat Completions를 레거시로 표시하도록 문서 업데이트.
• 선택적 향후 단계: 더 단순한 제거 경로를 위해 Chat Completions 요청을 Responses 핸들러로 매핑.