2026년 macOS OpenClaw 게이트웨이에서 프리미엄 모델 하나만 쓰다가 Anthropic HTTP 429, OpenAI 503, 지역 장애로 유일한 API 키가 막히면 프로덕션이 멈춥니다. 모델 페일오버와 명시적 프로바이더 라우팅은 그런 하드 스톱을 경계 있는 저하로 바꿉니다—문서화된 부 모델 체인, 호환 도구 스키마, Retry-After를 존중하는 재시도 예산. 이 튜토리얼은 ~/.openclaw/openclaw.json에 체인을 표현하고, 시크릿을 git 밖에 두며, LaunchAgent 프로덕션 plist를 건드리기 전 openclaw doctor로 검증하는 방법을 다룹니다. 429 재시도 규율, JSON·환경 프로파일, 업스트림 서킷 브레이커, doctor 진단과 함께 라우팅·스로틀·관측을 맞추세요.
페일오버 의사결정 매트릭스, 복사 가능한 설정 골격, 수치 가드레일(핫 패스 최대 3 프로바이더, 시도당 30초, 턴 전체 120초), MacHTML 공개 요금으로 하루 약 $16.9인 Apple Silicon Mac mini에서 돌릴 스테이징 체크리스트를 얻습니다.
페일오버가 필요한 증상
채널은 “생각 중…”인데 로그는 프로바이더 오류 반복. 게이트웨이가 단일 벤더에 재시도를 소진해 턴 중간에 도구 호출이 멈춥니다. 검증된 부 경로 대신 새벽 2시에 API 키를 수동 교체해 재무가 깜짝 청구를 봅니다—병목은 모델 품질이 아니라 라우팅 신호입니다.
페일오버는 “항상 최저가 모델”이 아닙니다. 고객 대면은 프리미엄, 내부 HTML/CSS 감사는 미드, 클라우드 API 전멸 시 비파괴 Ollama 요약만—층마다 문서화·프로브합니다.
페일오버 체인 설계 원칙
핫 패스는 짧게, 최대 3 프로바이더. HTML/CSS 에이전트와 동일 도구 스키마로 주간 프로브. 프로덕션에서 파일 편집이 필수면 write 불가 모델로 폴오픈하지 말고 읽기 전용 요약으로 저하. 턴마다 correlation id·프로바이더 라벨을 로그해 비용 스파이크를 추적합니다.
같은 하드웨어라도 staging·production 체인은 분리. 스테이징 JSON 오타가 프로덕션을 실험 로컬 모델로 떨어뜨리지 않게 합니다.
openclaw.json 라우팅 골격
라우팅은 git 추적 HTML 밖에 둡니다. 프로바이더명은 openclaw.json, API 키는 ~/.openclaw/.env(chmod 600). 프라이머리 모델 ID, 순서 폴백, 프로바이더별 타임아웃, 선택적 비용 상한을 문서화하세요.
{
"agents": {
"default": {
"model": {
"primary": "anthropic/claude-sonnet-4-20250514",
"fallbacks": [
"openai/gpt-4.1",
"google/gemini-2.5-pro"
]
},
"providers": {
"anthropic": { "timeoutMs": 30000 },
"openai": { "timeoutMs": 30000 },
"google": { "timeoutMs": 45000 }
}
}
}
}스니펫은 구조 참고용—OpenClaw 버전마다 필드명이 바뀌므로 배포 전 릴리스 노트와 diff하세요. 편집 후 openclaw doctor와 프로바이더별 한 줄 합성 채팅을 실행합니다.
프로바이더 선정 매트릭스
| 계층 | 용도 | 리스크 |
|---|---|---|
| 프라이머리(프리미엄) | 고객 대면 Slack/Telegram 턴 | 출시 시 쿼터 고갈 |
| 세컨더리(미드) | 내부 감사·비긴급 수정 | 프라이머리 대비 도구 스키마 드리프트 |
| 로컬(Ollama) | 클라우드 API 중단 시 읽기 전용 요약 | 클라우드 추론 깊이 미달 |
| 비활성 | 장애 시 파괴적 도구 금지 | “일단 켜자” 운영 압력 |
429·503과 Retry-After 조율
페일오버는 속도 제한 준수의 대체가 아닙니다. 프라이머리가 429면 문서화 상한(채팅에서 흔히 30초)까지 Retry-After를 지킨 뒤 부 프로바이더로 넘깁니다. 503 폭풍에는 게이트웨이 서킷 브레이커와 짝을 맞추세요. macOS 타이머에 맞는 백오프 표는 429 전문을 참고하세요.
턴 전체는 120초 근처로 상한을 두고, 다섯 프로바이더 루프 대신 사람이 읽을 수 있는 저하 메시지를 반환합니다.
모델 간 도구 스키마 호환
체인의 모든 모델은 게이트웨이가 게시하는 동일 JSON 도구 정의를 받아야 합니다. browser를 거부하는 부 모델은 HTML/CSS 파이프라인을 중간에 깹니다. 프로덕션 폴백에 넣기 전 스테이징에서 읽기·패치 쓰기·디렉터리 목록 세 가지 고정 도구 호출을 각 프로바이더에 실행하세요.
부가 비전 미지원이고 프라이머리가 이미지를 쓰면, 페일오버 전 이미지 파트를 제거하거나 비전 가능 부로만 라우팅합니다.
doctor 프로브·합성 채팅
라우팅 편집 후 openclaw doctor --json을 변경 티켓에 첨부합니다. 각 폴백을 강제하는 합성 메시지를 보내세요: 스테이징에서 프라이머리 키를 일시 폐기하고 부가 10초 내 응답하는지 확인, 키 복구 후 재시작 없이 프라이머리 복귀를 검증. 턴마다 프로바이더 라벨을 게이트웨이 로그에서 확인합니다.
프로브는 staging/프로덕션 프로파일과 맞추고, 개발 노트북에서 프로덕션 시크릿으로 폴백을 시험하지 마세요.
스테이징 롤아웃 체크리스트
- 현재
openclaw.json·.env지문(비밀값 제외)을 git 무시 저장소로보냅니다. - 부 프로바이더 키를 별도 청구 알림과 함께 추가합니다.
- 스테이징 게이트웨이 포트에서 프로바이더별 도구 호출 스모크를 실행합니다.
- 프라이머리 키 무효화로 장애를 시뮬레이션하고 SLA 내 폴백을 확인합니다.
- 스테이징 지표가 24시간 깨끗하면 LaunchAgent plist를 승격합니다.
- 롤백 문서화: JSON 단일 복원 +
launchctl kickstart.
FAQ
페일오버 모델도 같은 도구 정의?
예—체인에 넣기 전 모든 프로바이더에서 도구 호출을 테스트합니다.
페일오버가 429를 자동 해결?
부에 독립 쿼터가 있을 때만. 그 외에는 백오프가 여전히 필요합니다.
doctor는 얼마나 자주?
라우팅·시크릿 변경마다, 프로덕션은 주간 cron도 권장합니다.
MacHTML Apple Silicon Mac mini 대여는 경영진과 동일 WebKit/Node 빌드에서 라우팅을 검증합니다—Linux 컨테이너로 macOS를 흉내 내지 않습니다. SSH 합성 채팅, Keychain 프롬프트 시 VNC. 유휴 전력은 대략 6–12W, 일주일 페일오버 리허설은 전 채널이 “provider error”인 하룻밤 장애보다 저렴한 경우가 많습니다.
공개 요금은 하루 약 $16.9. 리허설 후 인스턴스만 중지하면 되고, 라우팅 표는 git에 남으며 36개월 CapEx는 쌓이지 않습니다.
실제 macOS에서 OpenClaw 모델 페일오버 리허설
프로덕션 LaunchAgent 승격 전 클라우드 Mac mini에서 프로바이더 체인·429 폴백·doctor 프로브를 검증하세요.