멀티 모델 전략

OpenClaw의 멀티 모델 운영은 "작업별 임의 라우팅 코드"가 아니라 공식 모델 ref, allowlist, fallback, auth profile 상태를 관리하는 일입니다.

기준일: 2026-07-13 공식 기준: Models CLI concepts, Model failover, Models CLI reference, CLI reference

핵심 개념

개념	공식 키/명령	운영 의미
Primary model	agents.defaults.model.primary	새 session 또는 unpinned session의 시작 모델
Fallback models	agents.defaults.model.fallbacks	configured default/job primary 실패 시 순서대로 시도
Model allowlist	agents.defaults.models	/model, picker, session override의 허용 모델 목록
Provider wildcard	"provider/*": {}	해당 provider에서 발견되는 모델을 allowlist에 포함
Utility model	agents.defaults.utilityModel	짧은 내부 작업용 별도 모델. 비워 두면 primary/provider 정책을 따른다
Auth profiles	openclaw models auth ...	provider 안에서 profile rotation과 cooldown을 적용

Provider-qualified model

모델은 가능한 한 provider/model 형태로 씁니다.

{
  agents: {
    defaults: {
      model: {
        primary: "<provider/model>",
        fallbacks: ["<fallback-provider/model>"],
      },
      models: {
        "<provider/model>": { alias: "primary" },
        "<fallback-provider/*>": {},
      },
    },
  },
}

이 예시는 schema 모양을 보여주는 운영 예시입니다. 실제 사용 가능 여부는 계정, provider auth, 설치된 plugin, openclaw models list 결과에 따라 달라집니다.

선택 기준

OpenClaw의 모델 선택은 출처에 따라 엄격도가 다릅니다.

선택 출처	fallback 동작
Configured default	agents.defaults.model.fallbacks 사용
Auto fallback 상태	원 primary를 주기적으로 재확인하고 회복 시 복귀
User session selection	strict. 선택 모델이 실패하면 fallback하지 않고 실패를 표시
Cron --model 또는 payload model	job primary로 처리하며 configured fallback을 사용할 수 있음

운영 중 "왜 fallback되지 않았는가"를 볼 때는 먼저 해당 모델이 user session selection인지 configured default인지 확인해야 합니다.

openclaw models status
openclaw models list
openclaw models fallbacks list

실습

agents.defaults.models가 있으면 /model과 picker는 그 목록 안에서만 선택합니다. 모델이 막히면 exact provider/model ref를 추가하거나 provider wildcard를 사용합니다.

openclaw config set agents.defaults.models '{"<provider/model>":{}}' --strict-json --merge
openclaw models aliases list
openclaw models aliases add primary <provider/model>

주의할 점입니다.

• allowlist에 추가할 때 plain object overwrite를 피하려면 --merge를 사용합니다.
• --replace는 대상 목록 전체를 교체해야 할 때만 사용합니다.
• local/GGUF 모델도 bare filename이 아니라 provider-prefixed ref가 필요합니다.
• provider ID는 plugin이 광고하는 ID를 사용합니다.

Failover와 cooldown

Model failover는 단순한 "저렴한 모델로 자동 전환"이 아닙니다.

• Rate limit, timeout, transient server error는 cooldown/failover 후보가 될 수 있습니다.
• Billing/credit 실패는 더 긴 disable/backoff로 처리될 수 있습니다.
• Format/invalid-request 오류는 같은 payload 재시도도 실패할 가능성이 높아 보통 terminal error로 드러납니다.
• 일부 provider SDK의 긴 retry-after 대기는 OpenClaw failover가 작동할 수 있도록 cap이 적용됩니다.
• Rate-limit cooldown은 provider profile 전체가 아니라 model-scoped cooldown으로 기록될 수 있습니다.

Model scan

openclaw models scan은 OpenRouter 공개 :free 카탈로그를 읽고 fallback 후보를 탐색합니다.

openclaw models scan --no-probe --json
openclaw models scan --provider openrouter --max-candidates 10

라이브 probe, --set-default, --set-image는 실제 provider key와 호출 가능성이 필요합니다. 문서 작성에서는 scan 결과를 고정 추천 모델처럼 적지 말고, "현재 환경에서 확인한 후보"로만 다룹니다.

도구에 입력할 프롬프트

현재 OpenClaw의 model inventory, auth profile, primary, fallback, allowlist를 조사해줘.
모델 ID는 models list에서 확인한 provider/model만 사용하고,
가격과 기본 모델은 고정하지 말고 현재 환경의 확인 결과로 표시해줘.

체크리스트

• 문서와 설정에는 provider/model 형식만 기록한다.
• 가격표, 고정 기본 모델, 오래된 모델 날짜 suffix를 문서 근거 없이 쓰지 않는다.
• /model로 고른 session pin과 configured default/fallback을 구분한다.
• allowlist 변경은 --merge와 openclaw config validate로 검증한다.
• provider auth 문제는 openclaw models auth list와 openclaw models status --json으로 분리한다.

다음 단계

• openclaw models status --json으로 현재 auth와 fallback 상태를 확인합니다.
• openclaw models list --all 또는 provider별 list로 exact ref를 확인합니다.
• model failover가 필요한 운영 환경에서는 fallback 순서와 user session pin 정책을 문서화합니다.