바로가기: 배경 · 매트릭스 · 절차 · /v1/models · 트러블슈팅 · FAQ
라우터 표는 LiteLLM 게이트 글, 비용 관점은 다중 모델 비용 매트릭스, OpenAI 호환 엔드포인트는 vLLM 스타일 라우팅, 관측 스키마는 OTel GenAI·Langfuse 대비 OTel과 맞추면 됩니다.
배경과 리스크
실리콘 맥은 여러 모델을 동시에 두드리기 좋습니다. Helicone은 SDK 없이 관측을 붙이지만 베이스 URL·헤더·model 문자열이 게이트 종단과 어긋나면 예산과 로그가 갈라집니다. 게이트는 planner-pro인데 업스트림만 다른 이름을 보면 재현이 깨집니다. 전용 원격 노드에 고정하면 열과 소켓이 안정돼 카운터 기준이 흔들리지 않습니다.
라우팅 정렬 매트릭스
| 층 | 소유 | 일치 대상 |
|---|---|---|
| 게이트 | 스킬 별칭 | 최종 model |
| Helicone | 세션·프로젝트 키 | 공급자 키·허용 목록 |
| 퓨즈 | RPM·TPM·연속 오류 | 짧은 JSON 스로틀 |
재현 절차 (공식 2026.5.x)
1. Getting Started에 따라 CLI를 설치하고 런북에는 2026.5.x 라인을 명시합니다. Node 22 LTS를 맞춘 뒤 openclaw doctor로 경고를 없애고 launchd에 루프백 게이트를 등록합니다.
2. OpenAI 호환 베이스는 Helicone 포워더로 두고 예시처럼 https://oai.hconeai.com/v1를 씁니다. Authorization에는 공급자 키, Helicone-Auth에는 프로젝트 키를 넣습니다.
3. 스킬 HTTP 클라이언트는 공인이 아니라 로컬 게이트 베이스만 바라보게 하고 관측 헤더는 게이트 업스트림에서만 추가합니다.
4. OpenClaw 세션·Helicone 프로젝트·공급자 시크릿을 각각 다른 chmod 0400 파일에 두고 관리자 스코프를 런타임에 섞지 않습니다.
5. 게이트 훅이나 스킬 프롤로그에서 분당 요청·분당 토큰·연속 오류를 롤링으로 세다 임계를 넘기면 circuit·retry_after_ms·route가 든 짧은 JSON을 돌려 에이전트가 분기합니다. 프롬프트와 원문 바디는 실패 봉투에서 제거합니다.
6. LangGraph+OpenClaw 패턴으로 두 모델을 병렬 스모크하고 Helicone 대시보드와 로컬 카운터를 비교해 우회 호출이 없는지 확인합니다. 라우트 변경 시 openclaw doctor 출력과 트레이스 한 건을 아카이브합니다.
/v1/models 호환 검사
SDK는 종종 목록을 먼저 봅니다. 운영과 같은 게이트→Helicone→공급자로 GET /v1/models를 보내 매니페스트 id와 맞추세요. 공급자로 직행하는 지름 프로브는 금지입니다.
curl -sS "https://oai.hconeai.com/v1/models" \
-H "Authorization: Bearer ${PROVIDER_API_KEY}" \
-H "Helicone-Auth: Bearer ${HELICONE_API_KEY}" | jq '.data[].id'로컬 게이트가 있으면 127.0.0.1와 에이전트가 쓰는 게이트 베어러로도 같은 조회를 해 목록을 diff 하세요. SDK가 베이스에 /v1을 덧붙이므로 이중 접두가 없는지 확인합니다.
트러블슈팅
- 401:
Helicone-Auth누락·회전 불일치, 게이트가 커스텀 헤더를 전달하는지 확인. - 모델 없음: 목록 diff 후 LiteLLM 글 별칭 확인.
- 퓨즈 즉시 개방: 서킷 열림 상태에서 재시도 폭주를 막지 않으면 Helicone에도 증폭 기록이 쌓입니다.
FAQ
Helicone이 서킷을 대체하나요? 아니요. 대시보드는 신호일 뿐이고 Mac 측 롤링 카운터가 소켓과 CPU를 보호합니다.
/v1/models를 꼭 보나요? 네. 호환 클라이언트는 목록에 없는 id를 거부합니다. 라우터가 항목을 숨기면 여기서 먼저 드러납니다.
개발에서 Helicone 생략? 별도 루프백 포트 프로필을 두되 모델 문자열은 운영과 동일하게 유지하세요.
노드 선택은? 절전·VPN 변동이 적은 맥 미니 M4 임대가 다중 모델 팬아웃과 퓨즈 튜닝에 유리합니다.