OpenClaw Gateway에 OpenResponses 통합하기

에이전트 워크플로우를 개발하다 보면 기존의 단순한 채팅 API만으로는 부족함을 느낄 때가 많아요. 상태 관리나 세밀한 스트리밍 이벤트 처리가 복잡해질수록, 더 구조화된 표준이 간절해지죠. 특히 다양한 도구 호출과 응답을 처리해야 하는 상황에서 API 규격이 파편화되어 있으면 유지보수가 정말 힘들어집니다.

이런 고민을 해결하기 위해 OpenClaw Gateway에 OpenResponses 표준을 도입하기로 했어요. 기존의 OpenAI 호환 방식을 유지하면서도, 에이전트에 최적화된 새로운 방식을 사용하는 방법을 소개해 드릴게요.

필요한 것

OpenClaw Gateway 소스 코드
OpenResponses 사양 (OpenAPI 규격)
Node.js 환경 및 Zod 라이브러리 (스키마 검증용)

빠른 시작

새로운 /v1/responses 엔드포인트를 활성화하고 사용하는 방법은 아주 간단해요. 5분 만에 설정을 마칠 수 있습니다.

1. 엔드포인트 활성화

먼저 설정 파일에서 새로운 엔드포인트를 활성화해야 해요. 기본값은 false이므로 직접 변경해 주세요.

{
  "gateway": {
    "http": {
      "endpoints": {
        "responses": {
          "enabled": true
        },
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

2. 요청 보내기

이제 POST /v1/responses 엔드포인트로 요청을 보낼 수 있습니다. ItemParam 구조를 사용하여 메시지를 구성해 보세요.

curl -X POST http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "OpenResponses-Version: latest" \
  -d '{
    "model": "gpt-4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "text", "text": "안녕, 오늘 날씨 어때?" }]
      }
    ],
    "stream": true
  }'

Implementation Details

이번 통합의 핵심은 안정성과 확장성이에요. 내부적으로 어떻게 구현되었는지 두 가지만 짚어볼게요.

스키마 기반 검증

src/gateway/open-responses.schema.ts 파일에 Zod를 사용해 독립적인 스키마를 구축했어요. 덕분에 외부 SDK 의존성 없이도 CreateResponseBody나 ItemParam 같은 복잡한 유니온 타입을 정확하게 검증할 수 있습니다.

스트리밍 이벤트 순서

OpenResponses는 의미론적(semantic) 이벤트를 사용해요. Phase 1에서는 다음과 같은 순서로 SSE(Server-Sent Events)가 전달됩니다.

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] (최종 종료 신호)

문제 해결

연동 중에 발생할 수 있는 일반적인 상황들과 해결 방법이에요.

이미지나 파일 업로드 실패: 현재 Phase 1 단계에서는 이미지나 파일이 포함된 content parts를 지원하지 않아요. 이런 요청을 보내면 invalid_request_error가 반환되니 텍스트 기반의 input을 사용해 주세요.
레거시 경고 메시지: chatCompletions 엔드포인트가 활성화되어 있으면 스타트업 시점에 경고가 발생할 수 있어요. 이는 해당 API가 향후 제거될 예정임을 알리는 신호이며, 동작에는 문제가 없습니다.
Usage 정보가 0으로 표시됨: 토큰 카운팅 로직이 아직 연결되지 않아 Phase 1에서는 usage 값이 0으로 반환되는 것이 정상입니다.

궁금한 점이 더 있다면 AI Setup Assistant에서 바로 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.