2026년 OpenClaw 다모델 라우팅·강등 체인: 채널/작업 분기, 429 vs 타임아웃 fail-over, ZoneMac 원격 물리 Mac 게이트웨이 재현(openclaw.json + FAQ)

2. 왜 아픈가

1. “모두 한 모델” 뒤에 숨은 한도. 비싼 모델을 채널 전체에 공유하면 피크 시간 429가 곧 전면 장애가 됩니다. 대화형과 배치, 내부와 외부 트래픽은 서로 다른 프로필과 동시성 예산을 써야 합니다.
2. 429와 타임아웃을 한데 섞은 숨은 비용. 429는 Retry-After와 할당량 존중이 필요하고, 읽기 타임아웃·TLS 실패는 강등 홉이나 더 긴 스트림 유휴 한도에 맞습니다. “세 번 재시도” 하나로 묶으면 대기열만 느려지고 원인은 가려집니다.
3. 설정의 안정성·감사 가능성. 원격 물리 Mac에서 검토 없이 openclaw.json을 고치면 기본 프로필이 깨지거나 강등 순서가 비용 모델과 어긋날 수 있습니다. 프로필 이름을 붙이고 1·2차 순서를 문서화하며 런북에 담당을 적으세요. 라우팅 리로드·포트 충돌(예: 18789)은 다중 채널 게이트웨이 런북에 증상·해결을 함께 적어 두면 재현에 유리합니다.

3. 의사결정 표: 축 × 전략

배포 전에 이 표에 합의하세요. 왼쪽은 자주 하는 지름길, 오른쪽은 무난한 기준선입니다.

4. 재현 가능한 openclaw.json 조각

아래는 구조 예시입니다. 키 이름은 사용 중인 OpenClaw 버전 문서와 맞추고, 프로덕션 전용 경로(채널, 자격 증명 참조)를 덮어쓰지 말며 항상 백업을 둡니다.

4.1 라우터 프로필·채널·작업 태그

{
  "gateway": {
    "router": {
      "defaultProfile": "balanced",
      "profiles": {
        "fast": {
          "primaryModel": "gpt-4o-mini",
          "fallbackChain": ["claude-3-5-haiku", "local-qwen-14b"]
        },
        "balanced": {
          "primaryModel": "gpt-4.1",
          "fallbackChain": ["gpt-4o", "gpt-4o-mini"]
        },
        "quality": {
          "primaryModel": "gpt-4.1",
          "fallbackChain": ["claude-3-5-sonnet", "gpt-4o"]
        }
      },
      "routeByChannel": {
        "telegram": { "profile": "fast" },
        "slack_public": { "profile": "balanced" },
        "api_internal": { "profile": "quality" }
      },
      "routeByTaskTag": {
        "ci": { "profile": "fast" },
        "support": { "profile": "quality" },
        "ops_summary": { "profile": "balanced" }
      }
    }
  }
}

4.2 상류 재시도, 429, 타임아웃

{
  "gateway": {
    "upstream": {
      "http": {
        "maxRetries": 4,
        "retryOnStatus": [408, 409, 425, 429, 500, 502, 503, 504],
        "respectRetryAfter": true,
        "backoff": { "baseMs": 400, "maxMs": 8000, "jitter": 0.2 }
      },
      "circuitBreaker": {
        "errorRateThreshold": 0.35,
        "minSampleSize": 40,
        "openDurationMs": 60000
      },
      "timeouts": {
        "connectMs": 8000,
        "requestMs": 180000,
        "streamIdleMs": 240000
      },
      "failover": {
        "onTimeout": "nextInFallbackChain",
        "on429": "retryWithBackoffThenFallback",
        "maxFallbackHops": 3
      }
    }
  }
}

streamIdleMs는 스트리밍에서 토큰 사이 긴 공백을 허용합니다. on429와 onTimeout을 블록으로 나누면 로그·대시보드에서 SLO를 분리해 강등 깊이와 429 비율을 각각 알림 걸기 좋습니다.

5. 7단계 런북(원격 물리 Mac)

1. 트래픽 축 동결. 제품·운영과 채널 ID와 작업 태그 열거형을 맞추고, 이름 없는 기본값을 없애 balanced로 조용히 빠지지 않게 합니다.
2. JSON 백업. cp openclaw.json openclaw.json.bak.$(date +%Y%m%d%H%M) 후 티켓에 diff를 붙입니다.
3. 라우터 블록 병합. profiles와 fallbackChain을 먼저 넣고, 이어 routeByChannel / routeByTaskTag를 넣습니다.
4. 로컬 골든 요청. 프로필마다 고정 curl(또는 작은 SDK 스크립트)로 127.0.0.1에 호출해 모델 ID와 지연을 기록합니다.
5. 두 클래스 결함 주입. 목·스로틀로 429와 첫 바이트 지연을 각각 재현합니다. 429는 세 번 안에 체인을 태우지 않도록 백오프하고, 타임아웃은 체인을 따라가야 합니다.
6. 관측 연결. 프로필당 요청 수, 429 비율, 강등 깊이 분포, 읽기 타임아웃 비율을 최소한 내보내고 Prometheus·Grafana 런북 임계값과 맞춥니다.
7. 아카이브·리뷰. JSON 조각, 골든 명령, 롤백(bak 복원 + 리로드)을 내부 문서 옆에 커밋합니다.

6. 429 vs 타임아웃 트리아지

7. 인용 가능한 수치(런북용)

• 백오프 시작: 429 1차로 baseMs: 400, maxMs: 8000을 기준으로 상용 QPS 상한과 조정합니다.
• 스트림 유휴: streamIdleMs: 240000(4분)은 긴 답에 적합하고, 짧게 잡으면 대화형에 유리합니다.
• 강등 상한: maxFallbackHops: 3으로 지연 폭증을 막고, 그 이후에는 명시 오류와 온콜로 넘깁니다.

8. FAQ

9. 요약과 노드 선택

다모델 라우팅은 비용·지연·가용성을 감사 가능한 계약으로 옮깁니다. 채널과 작업이 프로필을 고르고, 429와 타임아웃은 서로 다른 fail-over 의미를 갖으며, 순서형 체인은 상류가 흔들릴 때의 마지막 보루입니다.

게이트웨이를 ZoneMac 원격 물리 Mac에 두면 그 경로가 장기간·저지터 Unix 호스트에 고정됩니다. 네이티브 터미널·SSH, launchd 감독, macOS 툴체인과의 정합이 환경 드리프트를 줄여 “원인 불명” 타임아웃을 덜 만듭니다. Apple Silicon 통합 메모리는 박스 안 로컬 백업 소형 모델을 현실적으로 만듭니다. Mac mini M4는 유휴 약 4W·저소음·안정적인 macOS로 7×24 게이트웨이 발판에 잘 맞고, Gatekeeper·SIP로 노출된 서비스 면을 다루기도 수월합니다.

이 라우팅 스택을 예측 가능한 하드웨어에 얹고 운영 부담을 줄이려면 Mac mini M4가 가격 대비 강한 출발점입니다—ZoneMac으로 원격 물리 Mac을 받아 다모델 트래픽을 재현 가능한 게이트웨이 설정 위에 올려 보세요. 지금이 교체·확장을 검토하기 좋은 시점입니다. 홈에서 Mac mini 옵션을 확인할 수 있습니다.