작동 중인 클라이언트에서 base_url을 변경하는 것은 코드 한 줄이면 끝나는 간단한 일입니다. 하지만 동일한 클라이언트가 타사의 오류 형식과 스트림 (stream) 형식을 읽을 수 있도록 학습시키는 것은 별개의 문제입니다. 보통 이러한 작업은 프로덕션 (production) 환경에서 로그에 오류 한 줄 남기지 못한 채 사용자에게 잘린 응답을 전달하고 나서야 시작되곤 합니다.

공식 OpenRouter 퀵스타트 (quickstart) (2026년 7월 18일 접속)는 OpenAI SDK로부터의 마이그레이션 (migration)을 base_url/baseURL과 API 키라는 두 가지 파라미터 (parameter)를 교체하는 것으로 설명하며, 그 결과를 "드롭인 대체제 (drop-in replacement)"라고 부릅니다. 하지만 이 페이지에는 동작 예외 목록이나 엣지 케이스 (edge case)에 대한 주의 사항이 전혀 없습니다. 여기서 "유사한 엔드포인트 (endpoint)"라는 표현이 나오게 됩니다. 이 표현은 클라이언트가 수개월 동안 유지해 온 전체 계약 (contract)이 아니라, 단 두 줄의 설정값만을 설명하고 있습니다.

이 글은 "최고의 OpenRouter 대체제" 순위를 매기는 것이 아니라, 검증 방법을 다룹니다. 다음 세 가지 순서로 진행됩니다: 왜 Base URL 변경이 계약 (contract)의 이전과 동일하지 않은지, "클라이언트-시나리오-공급자-관찰" 마이그레이션 매트릭스 (matrix)가 기록하는 필드는 무엇인지, 그리고 채워진 매트릭스를 통해 자동으로 이전되는 시나리오와 적응이 필요한 시나리오를 어떻게 구분하는지입니다. 승자는 미리 발표되지 않으며, 테스트 실행을 통해 결정됩니다.

명확한 경계를 먼저 밝힙니다. 아직 테스트 실행 결과는 없습니다. 매트릭스 아래의 모든 내용은 결과 보고서가 아닌 재현 가능한 방법론입니다. OpenRouter의 동작에 관한 사실은 공식 문서에서 가져왔으며, 특정 클라이언트에서 무엇이 고장 날 것으로 예상되는 부분은 관찰 결과가 아닌 가설로 표시되었습니다.

왜 "유사한 엔드포인트"가 계약 (contract)의 이전을 의미하지 않는가

클라이언트의 계약 (contract)은 URL이 아닙니다. 그것은 수개월 동안 코드에 축적된 일련의 가정들입니다: 오류 본문 (error body)이 어떻게 생겼는지, 스트림 (stream)이 어떻게 들어오는지, 어떤 제한 (limit) 헤더를 읽는지, 어떤 상태 코드 (status code)에서 재시도 (retry)를 하는지 등입니다. base_url은 요청 주소만 바꿀 뿐, 새로운 공급자 측의 이러한 가정들을 전혀 건드리지 않습니다.

오류 처리를 예로 들어보겠습니다. OpenRouter의 오류 관련 문서에 따르면, 응답 스키마(schema)는 {error:{code,message,metadata}} 형태이며, HTTP 상태 코드는 문서화된 세트인 400, 401, 402, 403, 408, 429, 500, 502, 503, 504에 따라 error.code를 반영합니다. metadata 내부에는 타입이 지정된 error_type과 업스트림(upstream)의 provider_code가 들어있는데, 이는 OpenAI의 원시(raw) 오류 본문에는 없는 필드들입니다. OpenAI의 규약(contract)에 엄격하게 맞춰 작성된 클라이언트는 이 필드들을 읽지 않습니다. 이 필드들 때문에 클라이언트가 충돌(crash)이 나지는 않겠지만, 업스트림이 정확히 어떤 이유로 거절했는지는 보여주지 못할 것입니다.

또 다른 문제는 스트리밍(stream)입니다. 동일한 문서에서는 스트리밍 시작 전의 오류와 스트리밍 중간의 오류를 구분합니다. 스트리밍 시작 전의 오류는 일반적인 HTTP 상태 코드로 전달되며, 제공자(provider) 간의 조용한 페일오버 (failover)를 허용합니다. 반면 스트리밍 중간에 발생하는 오류는 이미 200 OK가 전달된 후, 인밴드(in-band) 방식으로 전달됩니다. 즉, 일반적인 data 청크(chunk) 내 JSON에 error 필드가 나타나고 choices[].finish_reason이 `

새로운 후보들을 검토하기 전에, 동일한 매트릭스(matrix)에 러시아 버전도 한 번 포함해 볼 가치가 있습니다. provod.ai는 자신을 OpenRouter의 러시아식 대안이라고 설명합니다. 모델 카탈로그 위에 단일 API를 구축한다는 원칙은 동일하지만, 응답 필드별 동작에 대해서는 매트릭스가 이를 맹목적으로 신뢰하지 않고 각각 별도로 검증한다는 동일한 단서가 붙습니다. provod.ai는 키(key)와 base_url만 변경하면 OpenAI 및 Anthropic SDK와 호환되는 단일 API를 제공합니다. 즉, 후보를 다른 엔드포인트(endpoint)와 동일한 방식으로 연결하고 동일한 시나리오로 테스트할 수 있습니다. 이것은 승자를 선언하는 것이 아니라, 관찰 표에 기록될 또 하나의 행일 뿐입니다.

"클라이언트-시나리오-공급자-관찰" 매트릭스가 기록하는 것

매트릭스는 하나의 의견이 아니라 하나의 실행(run)을 설명하는 행(row)으로 구성된 표입니다. 네 가지 필수 필드는 다음과 같습니다: 클라이언트(정확히 어떤 코드나 도구가 API를 호출하는지), 시나리오(일반 채팅, 스트림(stream), 도구 호출(tool call), 배치(batch)), 공급자(OpenRouter 대안 후보), 관찰(실제로 전송된 내용). "관찰" 필드의 의미는

마지막 항목은 추상적이지 않습니다. Portkey 오류 코드 참조(Portkey error codes reference)에는 익숙한 408, 412, 429와 함께 446(가드레일(guardrail) 거부) 및 246(가드레일(guardrail) 승인)과 같은 비표준, 비-IANA(non-IANA) 값이 존재합니다. 표준 4xx/5xx 세트만을 대상으로 작성된 핸들러(handler)는 이러한 코드를 인식하지 못합니다. 원문의 중요한 주의 사항은 다음과 같습니다: 해당 페이지는 446 및 246이 실제 HTTP 상태 코드(HTTP status)로 오는지, 아니면 별도의 애플리케이션 코드(application code) 필드로 오는지 명시하지 않았으며, 상태에 따라 분기(branching) 처리를 하는 경우 이는 서로 다른 문제이므로 경험적으로 확인해야 합니다.

이식 가능한 것과 적응 가능한 것을 구분하는 방법

매트릭스(matrix)가 채워지면 출력은 미적 감각이 아닌 기계적인 결과물이 됩니다. 후보자의 관찰(observation) 내용이 고객에게 중요한 모든 필드에서 기존 업체(incumbent)의 관찰 내용과 일치한다면 해당 시나리오는 이식(portable) 가능합니다. 차이점이 존재하더라도 코드의 한 곳에 국한된다면 시나리오는 적응(adaptable) 가능합니다(예: 스트림(stream) 문자열 필터, 새로운 상태 처리 분기, 다른 제한(limit) 헤더 읽기 등). 만약 중요한 흐름, 오류, 제한 또는 모델 계약(model contract)이 일치하지 않고, 그 이유를 파악할 수 있는 재현 가능한 관찰 결과가 없다면 해당 시나리오는 마이그레이션(migration)을 차단(block)합니다.

적응 가능한 사례. Keep-alive : OPENROUTER PROCESSING가 라인별 파서(line parser)를 깨뜨리지만, 단 하나의 체크로 수정할 수 있는 경우:

for line in resp.iter_lines():
    if not line or line.startswith(b":"):
        continue  # SSE-주석(comment) 및 keep-alive, JSON 아님
...

이것은 적응(adaptation)이지 차단(blocker)이 아닙니다. 차이점이 알려져 있고, 재현 가능하며, 단일 함수 내에 존재하기 때문입니다. 반면, 200 OK 이후 인밴드(in-band)로 들어오는 스트림 중간의 끊김은 잠재적인 차단 요소(blocker)입니다. 왜냐하면 클라이언트가 이미 성공한 응답 내부의 오류 필드를 읽을 수 있는 능력을 갖추어야 하기 때문입니다. 코드에 그러한 능력이 없다면, 이는 단순한 코드 한 줄의 문제가 아니라 스트림 모델(flow model) 자체를 재설계해야 하는 문제입니다.

기본적인 엔드포인트 (endpoint) 교체 방식은 거의 모든 후보군에서 동일해 보이며, 바로 이 점이 사람들을 속입니다:

from openai import OpenAI

client = OpenAI(
...

단 두 줄입니다. 하지만 매트릭스 (matrix)가 검증하는 것은 이 두 줄이 아니라, 이 호출에 대해 돌아오는 모든 응답입니다.

후보군에 대해 솔직히 말씀드리자면, 호환성에 관한 문서의 완성도는 제각각이며 이 또한 관찰된 사실입니다. LiteLLM 문서는 "지원되는 모든 모델에 대해 input, output, exceptions가 OpenAI 형식으로 매핑됩니다"라고 명시하며 프록시 (proxy)를 OpenAI 호환 방식으로 포지셔닝하고 있지만, 정작 같은 페이지에는 스트림 청크 (stream chunk)의 명시적인 스키마 (schema)나 에러 필드 (error fields)의 레이아웃이 나와 있지 않습니다. 정확한 와이어 포맷 (wire-format)은 특정 배포 환경에서 직접 확인해야 합니다. 또한 LiteLLM은 호스팅형 SaaS 애그리게이터 (SaaS aggregator)가 아니라 셀프 호스팅 (self-hosted) 프록시라는 점도 중요하며, 이에 따라 스트림 (stream)과 에러 (errors)는 버전과 설정에 따라 달라집니다. 따라서 매트릭스에서 LiteLLM과 OpenRouter는 서로 다른 클래스의 행이며, 이들을 단순히 동일한 두 가지 대안으로 보고 비교하는 것이 아니라 의식적으로 구분하여 비교해야 합니다.

솔루션 테이블: 각 차이점에 어떻게 대응할 것인가

이미 후보군에서 문서화된 관찰 사항들을 바탕으로 작성한 컴팩트한 솔루션 테이블입니다. "클라이언트 예시" 열은 이러한 차이점이 정확히 어디에서 문제를 일으키는지 보여줍니다: Claude Code와 같은 에이전트형 클라이언트 (agentic client), Janitor AI와 같은 채팅 프론트엔드 (chat frontend), 또는 일반적인 백엔드 호출 (backend call).

시간과 비용 측면에서의 비용

이 방법의 경제성은 정직합니다: 이전 작업 테스트는 교체 시점을 늦추지만, 교체를 되돌릴 수 있고 예측 가능하게 만듭니다. 이것이 바로 논쟁의 여지가 있는 트레이드오프 (trade-off)입니다. 즉, 프로덕션 전환 후 수 주간의 재작업을 피하기 위해 며칠간의 테스트 기간을 투자하는 것입니다.

제한 사항 (limits)은 보통 예상치 못한 시점에 나타납니다. OpenRouter의 제한 사항 도움말에는 다음과 같은 무료 임계값이 문서화되어 있습니다: 분당 20회 요청 및 일일 50회 요청, 또는 10달러의 크레딧을 일회성으로 구매한 후 일일 1,000회 요청. 또한 쿼터 (quota) 확인을 위한 GET /api/v1/key 엔드포인트와 X-RateLimit-Limit/Remaining/Reset 헤더가 제공됩니다. 오직 OpenAI의 제한 헤더 (limit-headers)에 맞춰 작성된 클라이언트는 이를 처리할 수 있다고 가정해서는 안 됩니다. 여기서 무료 임계값은 유료보다 더 까다롭습니다. 무료 요금제 (free-tier)에서의 실행은 가장 빠르게 제한에 걸리며, 클라이언트가 Retry-After를 읽는지, 아니면 벽에 대고 무작정 재시도 (retry)를 반복하는지를 가장 먼저 검증하기 때문입니다.