증상: OpenRouter 통합 API가 타임아웃하거나 429가 섞여 올 때
브라우저에서 OpenRouter 대시보드와 문서는 열리는데, 애플리케이션이나 터미널에서 https://openrouter.ai/api/v1/chat/completions 같은 엔드포인트만 긴 connection timeout·읽기 타임아웃을 기록하거나 HTTP 429 Too Many Requests를 반환하는 경우가 있습니다. 사용자는 한 업체의 단일 제품이라고 가정하지만, 실제로는 키 발급 UI가 붙는 웹 세션·정적 자산, 문서 CDN, 그리고 추론 요청이 오가는 API 경로가 다른 TCP 연결 세트를 형성합니다. 공식 가이드가 안내하는 기본 URL 역시 openrouter.ai 호스트에 모이기 때문에, 얼핏 보면 「모든 것이 같은 도메인」처럼 보이지만 브라우저 탭마다 붙는 추가 Host, npm install @openrouter/sdk 때의 registry.npmjs.org와 tarball, 필요 시 github.com·objects.githubusercontent.com 같은 주변 툴체인이 한 번에 실패하면 원인 진단이 급격히 어려워집니다.
Clash 계열 클라이언트는 위에서 아래로 규칙을 매칭합니다. 웹만 보이는 광범위 DIRECT나 지역 rule-set이 먼저 맞으면, API만 프록시를 타야 하는 회사 정책과 어긋나거나 반대로 API만 의도치 않게 직결되어 지터가 커질 수 있습니다. 이 글은 규제 우회를 조장하지 않으며, 이용 약관·API 키 보관·회사 보안 정책을 먼저 확인해야 합니다. 아래 호스트 목록은 문서화된 공개 엔드포인트와 흔한 툴체인을 출발점으로 삼되, 반드시 실패한 요청의 실제 SNI를 개발자 도구와 코어 로그로 다시 확인해야 합니다.
API·CDN·레지스트리를 나누면 달라지는 점
OpenRouter는 클라이언트가 보는 관문이 하나지만, 네트워크 관점에서는 긴 스트리밍 응답·높은 동시 연결을 요구하는 API 트래픽과 짧은 버스트가 많은 패키지 다운로드·GitHub 요청이 섞입니다. 두 종류를 한 PROXY 그룹에만 몰아넣으면 무관한 대역폭 경쟁으로 API 지연이 튀고, 반대로 모든 해외 트래픽을 아무거나 하나의 노드에 고정하면 레지스트리 타임아웃이 API까지 의심하게 만듭니다.
그래서 AI-OPENROUTER·NPM-MAIN·GITHUB-CDN처럼 역할별 select 또는 url-test 그룹을 두고, 각 그룹에는 핸드셰이크 실패율이 낮은 노드만 넣는 방식이 유지 보수에 유리합니다. 장기적으로는 Rule Providers·rule-set으로 목록을 옮기고, 로컬 YAML에는 충돌이 적은 최소 행만 남기세요. JavaScript 패키지 레지스트리 분리 패턴은 npm·pnpm 분리 글과 직접 맞닿아 있습니다.
대표 호스트 묶음: openrouter.ai와 주변 SNI
공식 문서 기준으로 클라이언트가 직접 치는 기본 축은 아래와 같습니다. 서비스가 바뀌면 인증·과금·상태 페이지용 서브도메인이 늘 수 있으니 분기마다 네트워크 탭으로 갱신하십시오.
- OPENROUTER-API-WEB:
openrouter.ai및 공식이 안내하는 동일 접미사의 문서·웹 UI. Chat Completions 등 OpenAI 호환 REST가 같은 호스트 아래/api/v1경로에 붙습니다. - OPENROUTER-STATIC(관측 기반): 브라우저가 추가로 불러오는 자바스크립트 번들·이미지·서드파티 분석 호스트가 있다면 네트워크 탭에서 Host를 적어 별도 그룹이나 OPENROUTER 블록에 합류시킵니다. 실제 운영 환경이 바뀌면 CDN 접두사가 달라질 수 있습니다.
- NPM-REGISTRY:
registry.npmjs.org와 팀이 쓰는 미러. - GITHUB-RELATED:
github.com,codeload.github.com,objects.githubusercontent.com등 tarball·릴리스 자산이 붙는 호스트.
같은 최상위 도메인이라도 서브도메인이 갈라지면 Clash에서는 다른 규칙 대상이 됩니다. DOMAIN-KEYWORD는 오탐 범위가 넓어 운용 프로필에서는 가급적 피하고, 검증된 DOMAIN-SUFFIX만 쌓는 편이 안전합니다.
# Example — verify live hostnames in your browser or core log
proxy-groups:
- name: AI-OPENROUTER
type: select
proxies:
- 🇯🇵 Low-latency
- ♻️ Auto
- DIRECT
rules:
- DOMAIN-SUFFIX,openrouter.ai,AI-OPENROUTER
# Add verified asset/CDN suffixes from DevTools if they differ:
# - DOMAIN-SUFFIX,cdn.example.com,AI-OPENROUTER
프로필 전반에서 이 블록보다 위에 있는 DIRECT·GEOIP 행이 먼저 매칭되면 OpenRouter 전용 줄은 실행되지 않습니다. ChatGPT·Anthropic·국내 직결 세트를 함께 쓰는 경우 상대 순서를 한 번에 검토하세요.
HTTP 429와 「느린 노드」 가설 구분하기
429는 통상 요청 빈도·할당량·WAF 정책과 연관됩니다. 진짜로 키 한도를 넘겼다면 노드를 바꿔도 응답이 좋아지지 않습니다. 다만 다음과 같은 경우에는 규칙 정렬이 체감에 영향을 줍니다. 첫째, 자동 url-test 그룹이 짧은 주기로 노드를 바꿔 출구 IP가 요청마다 달라지는 것이 업스트림에서 이상 징후로 잡히는 경우. 둘째, 타임아웃 때문에 클라이언트가 재시도를 폭발적으로 늘려 사실상 DoS에 가까운 패턴을 만드는 경우. 셋째, 브라우저 세션은 정상인데 API만 다른 그룹으로 나가며 레이트 리밋 카운터가 꼬이는 경우입니다.
따라서 429 로그를 보면 즉시 프록시를 의심하기보다 응답 본문·헤더의 메시지와 OpenRouter 측 대시보드 지표를 함께 보고, rule hit 한 줄로 실제 출구와 규칙 이름을 먼저 고정하는 것이 순서입니다.
DNS와 fake-ip가 경로를 흔드는 경우
fake-ip 모드에서 브라우저·OS resolver와 코어 내부 resolver가 서로 다른 A/AAAA를 들고 있으면, 한 앱은 프록시를 타고 다른 앱은 직결처럼 보이는 이중 경로가 생깁니다. redir-host로 바꿔 재현되는지 확인하고, DoH 업스트림이 지역별로 다른 답을 주는지도 봅니다. fake-ip-filter에 플랫폼 호스트를 넣어야 하는지, nameserver가 과도하게 fallback으로 떨어지는지 점검하세요. TUN과 병행한다면 TUN 모드 가이드의 DNS 설명을 함께 읽으면 이해가 빠릅니다.
직결(DIRECT) 오매칭과 규칙 우선순위
오래된 국내 직결이나 키워드 rule-set이 광범위하게 먼저 맞으면, OpenRouter 호스트가 의도와 다른 출구로 나갑니다. 반대로 지나치게 넓은 FINAL,DIRECT만으로는 보안 정책상 API만 특정 국가 노드를 타야 하는 요구와 충돌할 수도 있습니다. 문제 세션에서 어떤 줄에 매칭됐는지 로그를 남기고, AI-OPENROUTER 규칙을 충돌 블록보다 위로 올리되 DOMAIN 범위를 필요 이상으로 키우지 마세요. rule-provider 여러 개를 붙이면 병합 뒤 실제 순서가 기대와 다를 수 있으니 클라이언트가 보여 주는 최종 목록으로 검증합니다.
OpenAI SDK·터미널·스트리밍에서의 경로
공식 문서는 OpenAI 호환 클라이언트에 baseURL: https://openrouter.ai/api/v1 형태를 안내합니다. Python·Node 런타임은 환경 변수 HTTPS_PROXY를 무시하는 조합이 있으니, 브라우저는 정상인데 CLI만 실패하면 프록시 미적용부터 의심합니다. curl -v로 동일 URL을 재현하고, Clash 로그에서 mixed 포트와 TUN 인터페이스 중 어디를 탔는지 확인하세요.
Chromium 계열이 HTTP/3(QUIC)를 선호할 때 UDP 경로가 막히면 TCP 폴백 전까지 화면이 비는 것처럼 느껴질 수 있습니다. 실험적으로 QUIC을 껐을 때 증상이 사라지는지 비교해 보고, 세부는 QUIC·HTTP/3 가이드를 참고합니다. 스트리밍 토큰 전달이 중간에 끊기면 SSE/WebSocket의 유휴 타임아웃·DNS를 함께 봅니다. 연결은 되는데 데이터가 안 오는 공통 절차는 로그·DNS·규칙 가이드와 연결됩니다.
재현 가능한 자가 점검 체크리스트
아래 순서는 메모하기 쉽게 짧게 유지했습니다. 단계마다 로그 한 줄만 남겨도 동료에게 넘기기 좋습니다.
- 브라우저·CLI에서 실패한 요청의 Host·상태 코드·본문 일부를 기록한다.
- Clash에서 동일 시각 연결이 어느 정책·rule 이름에 매칭됐는지 확인한다.
- 같은 노드로 다른 HTTPS 사이트를 열어 회선 자체 이슈를 가른다.
- npm·GitHub가 같이 실패하면 레지스트리 전용 규칙을 앞당겨 본다.
- DNS 모드·nameserver·fake-ip-filter를 바꿔 재현 여부를 본다.
- AI-OPENROUTER 그룹에서 노드를 수동 전환해 지연·실패율 차이를 비교한다.
- TUN·시스템 프록시·브라우저 확장이 동시에 개입하지 않는지 확인한다.
이 과정을 거치면 「OpenRouter가 불안정하다」는 보고를 특정 Host의 DIRECT 오매칭, DNS 이중 해석, SDK만 프록시 미적용, 진짜 429 할당량 같은 가설로 나눌 수 있습니다.
자주 묻는 질문
Q. Clash만으로 OpenRouter 429를 없앨 수 있나요?
A. 계정·엔드포인트 한도를 넘긴 진짜 429는 라우팅으로 사라지지 않습니다. 다만 출구가 들쭉날쭉하거나 재시도 폭주가 나면 비슷한 증상이 보일 수 있어 규칙 정리는 여전히 필요합니다.
Q. API와 웹이 모두 openrouter.ai인데 어떻게 나누나요?
A. 기본 DOMAIN 규칙은 호스트 단위라 한 덩어리로 묶는 것이 일반적입니다. 대신 npm·GitHub·관측된 별도 자산 호스트를 분리하면 체감이 크게 좋아지는 경우가 많습니다.
Q. 터미널만 실패하고 브라우저는 정상인가요?
A. 프록시 환경 변수, PAC, mixed-port, DNS를 의심하고 터미널과 GUI의 경로를 나란히 로그로 비교하세요.
정리
비교적 단순해 보이는 통합 LLM API도 실제로는 동일 브랜드 이름 뒤에 API 스트림·웹 자산·패키지 레지스트리가 한꺼번에 섞입니다. 일부 범용 VPN이나 버튼 하나로 전체 트래픽만 바꾸는 도구는 호스트 단위 정책이나 rule hit 진단에 한계가 있어, 개발자가 원하는 「이 요청만 안정 출구」를 세밀하게 맞추기 어렵습니다. 설정 파일을 까 보지 않으면 왜 API만 끊기는지 추적도 힘듭니다.
반면 Clash·Mihomo 계열은 DOMAIN 기반 규칙과 정책 그룹으로 역할별 출구를 나누고, DNS 모드와 로그를 같은 화면에서 확인할 수 있어 OpenRouter 같은 집계형 게이트웨이와 잘 맞습니다. ChatGPT·Kimi·Claude Code 분리 글에서 다룬 뼈대를 그대로 이식하면, 한 번 템플릿만 정리해 두고도 이후 모델 교체가 잦은 환경에서 비용을 줄일 수 있습니다.
클라이언트 빌드 출처를 먼저 통일한 뒤 이 글의 규칙을 얹고 싶다면, 본 사이트 클라이언트 다운로드 페이지에서 현재 플랫폼 패키지를 확인해 주세요. 더 넓은 설정 개념은 문서 허브의 고급 설정 파트와 이어 읽으면 흐름이 연결됩니다.