Model failover

OpenClaw는 실패를 두 단계로 처리합니다:

  1. 현재 provider 내에서 auth profile 회전.
  2. agents.defaults.model.fallbacks의 다음 model로 model 대체.

이 문서는 런타임 규칙과 이를 뒷받침하는 데이터를 설명합니다.

Auth 저장소 (key + OAuth)

OpenClaw는 API key 및 OAuth token 모두에 대해 auth profile을 사용합니다.

  • 비밀은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 있습니다 (레거시: ~/.openclaw/agent/auth-profiles.json).
  • Config auth.profiles / auth.order는 메타데이터 + 라우팅 전용입니다 (비밀 없음).
  • 레거시 import 전용 OAuth 파일: ~/.openclaw/credentials/oauth.json (첫 사용 시 auth-profiles.json으로 가져옴).

자세한 내용: /concepts/oauth

Credential 유형:

  • type: "api_key" → { provider, key }
  • type: "oauth" → { provider, access, refresh, expires, email? } (+ 일부 provider의 경우 projectId/enterpriseUrl)

Profile ID

OAuth 로그인은 여러 계정이 공존할 수 있도록 고유한 profile을 생성합니다.

  • 기본값: 이메일을 사용할 수 없는 경우 provider:default.
  • OAuth with email: provider:<email> (예: google-antigravity:[email protected]).

Profile은 profiles 아래 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 있습니다.

회전 순서

Provider에 여러 profile이 있는 경우 OpenClaw는 다음과 같은 순서를 선택합니다:

  1. 명시적 config: auth.order[provider] (설정된 경우).
  2. 구성된 profile: provider별로 필터링된 auth.profiles.
  3. 저장된 profile: provider에 대한 auth-profiles.json의 항목.

명시적 순서가 구성되지 않은 경우 OpenClaw는 라운드 로빈 순서를 사용합니다:

  • 기본 key: profile 유형 (OAuth가 API key보다 먼저).
  • 보조 key: usageStats.lastUsed (각 유형 내에서 가장 오래된 것이 먼저).
  • 쿨다운/비활성화된 profile은 끝으로 이동하며 가장 빨리 만료되는 순서로 정렬됩니다.

자세한 내용은 영문 원본을 참조하세요 (Model failover).

← 문서로 돌아가기