launchd 상시 구동을 전제로 클라이언트는 단일 HTTPS와 안정 별칭만 알면 됩니다. 토큰 범위는 LangGraph·OpenClaw 게이트웨이, 백오프·차단은 JSON Schema·재시도, 에이전트 운영은 checkpoint·쿼터 글과 맞춥니다.
문제 정의
첫째 서비스마다 SDK를 들면 키 순환·감사 비용이 폭증합니다. 둘째 코드명 변경 시 별칭이 없으면 CI와 앱이 동시에 깨집니다. 셋째 차단 버킷을 공유하면 한 테넌트 스파이크가 전 풀을 덮습니다.
게이트웨이와 LiteLLM 역할 표
| 층 | 담당 | 장애 시 먼저 볼 것 |
|---|---|---|
| OpenClaw 게이트웨이 | 토큰 범위, 테넌트 식별, 대외 오류 요약 형태 | 리버스 프록시가 Authorization 헤더를 제거했는지 |
| LiteLLM Proxy | model_list, 별칭, 폴백, 업스트림 타임아웃 | 503 비율, 읽기 타임아웃, 공급자 쿼터 |
| 원격 Mac 노드 | 디스크 로그, 시각 동기화, 포트 고정 | 절전, 디스크 여유, 동일 호스트 포트 충돌 |
관리 API와 메트릭은 같은 호스트의 루프백에만 두고 운영자는 SSH 터널로 붙습니다. 대외 TLS·레이트 리밋·WAF 규칙은 게이트웨이 한 줄에 모으면 인증서 면적과 변경 창이 줄어듭니다.
배포·설정·검수 절차
1) ~/llm-edge 루트와 파일 권한 0600, 공급자 키는 LiteLLM만 읽고 Git 비저장.
2) LiteLLM을 127.0.0.1에 바인딩, model_list·fallbacks·대외 model_alias만 공개.
3) 게이트웨이 대외·내부는 LiteLLM 루프백, Dashboard 토큰은 허용 별칭만으로 최소 권한.
4) 테넌트별 동시성·RPM 예산과 슬라이딩 윈도 오류율 차단, 임계는 스테이징 p95 기준.
5) 실패 응답은 유형·재시도 가능·해시·권장 대기초만, 프롬프트 원문 제외.
6) 토큰 폐기·라우트 단일 차단·503 주입으로 폴백과 X-Request-ID 로그 정합 검수.
- launchd 표준출력·에러 경로와 로그 로테이션으로 디스크 고갈 방지.
- LiteLLM plist를 먼저 기동한 뒤 게이트웨이 기동, 관리 키는 클라이언트 토큰과 분리.
# 게이트웨이 경유 별칭 스모크(예시)
curl -sS "https://<게이트웨이>/v1/chat/completions" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"prod-chat","messages":[{"role":"user","content":"ping"}]}'인용: 대외는 게이트웨이만, 매핑 단일 소스, 구 별칭은 한 릴리스 병행, 라우트별 마지막 공급자 요청 ID 보존.
배포 후 자주 묻는 질문
401·로그 공백: 경로 접두·프록시의 Authorization 전달, 로컬 curl 재현.
차단 오탐: 집계 키를 테넌트·모델로 분리.
구 라우팅: LiteLLM 리로드 후 캐시 TTL·CDN 확인.
요약: 게이트웨이는 신원·범위·오류 형태, LiteLLM은 다중 모델 라우팅·회복력.