모델 장애 조치

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. 현재 제공자 내에서 인증 프로필 순환.
2. agents.defaults.model.fallbacks의 다음 모델로 모델 폴백.

​

런타임 흐름

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

선택 소스 정책

• 구성된 기본값: agents.defaults.model.primary는 agents.defaults.model.fallbacks를 사용합니다.
• 에이전트 기본 모델: agents.list[].model은 해당 에이전트 모델 객체에 자체 fallbacks가 포함되지 않는 한 엄격합니다. 엄격한 동작을 명시하려면 fallbacks: []를 사용하고, 해당 에이전트에 모델 폴백을 적용하려면 비어 있지 않은 목록을 제공하세요.
• 자동 폴백 재정의: 런타임 폴백은 재시도 전에 providerOverride, modelOverride, modelOverrideSource: "auto", 선택된 원본 모델을 기록합니다. 이 자동 재정의는 구성된 폴백 체인을 계속 따라갈 수 있으며 /new, /reset, sessions.reset으로 지워집니다. 명시적인 heartbeat.model 없이 실행되는 Heartbeat도 원본이 현재 구성된 기본값과 더 이상 일치하지 않으면 직접 자동 재정의를 지웁니다.
• 사용자 세션 재정의: /model, 모델 선택기, session_status(model=...), sessions.patch는 modelOverrideSource: "user"를 기록합니다. 이는 정확한 세션 선택입니다. 선택된 제공자/모델이 응답을 생성하기 전에 실패하면 OpenClaw는 관련 없는 구성된 폴백으로 응답하는 대신 실패를 보고합니다.
• 레거시 세션 재정의: 이전 세션 항목에는 modelOverrideSource 없이 modelOverride가 있을 수 있습니다. OpenClaw는 명시적인 이전 선택이 조용히 폴백 동작으로 변환되지 않도록 이를 사용자 재정의로 취급합니다.
• Cron 페이로드 모델: Cron 작업 payload.model / --model은 작업 기본 모델이며 사용자 세션 재정의가 아닙니다. 작업이 payload.fallbacks를 제공하지 않는 한 구성된 폴백을 사용합니다. payload.fallbacks: []는 Cron 실행을 엄격하게 만듭니다.

​

인증 저장소(키 + OAuth)

• 비밀은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 저장됩니다(레거시: ~/.openclaw/agent/auth-profiles.json).
• 런타임 인증 라우팅 상태는 ~/.openclaw/agents/<agentId>/agent/auth-state.json에 저장됩니다.
• 구성 auth.profiles / auth.order는 메타데이터 + 라우팅 전용입니다(비밀 없음).
• 레거시 가져오기 전용 OAuth 파일: ~/.openclaw/credentials/oauth.json(처음 사용할 때 auth-profiles.json으로 가져옴).

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

​

프로필 ID

• 기본값: 이메일을 사용할 수 없을 때 provider:default.
• 이메일이 있는 OAuth: provider:<email>(예: google-antigravity:user@gmail.com).

​

순환 순서

• 기본 키: 프로필 유형(API 키보다 OAuth 우선).
• 보조 키: usageStats.lastUsed(각 유형 내에서 가장 오래된 것 우선).
• 쿨다운/비활성화된 프로필은 가장 이른 만료 순서로 끝으로 이동됩니다.

​

세션 고정성(캐시 친화적)

• 세션이 재설정될 때(/new / /reset)
• Compaction이 완료될 때(Compaction 횟수 증가)
• 프로필이 쿨다운 상태이거나 비활성화된 경우

​

OpenAI Codex 구독 및 API 키 백업

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

쿨다운

• 1분
• 5분
• 25분
• 1시간(상한)

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

​

결제 비활성화

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

• 결제 백오프는 5시간에서 시작하고, 결제 실패마다 두 배로 증가하며, 24시간에서 상한이 적용됩니다.
• 프로필이 24시간 동안 실패하지 않았다면 백오프 카운터가 재설정됩니다(구성 가능).
• 과부하 재시도는 모델 폴백 전에 동일 공급자 프로필 1회 교체를 허용합니다.
• 과부하 재시도는 기본적으로 0 ms 백오프를 사용합니다.

​

모델 폴백

​

후보 체인 규칙

​

어떤 오류가 폴백을 진행하는가

​

쿨다운 건너뛰기와 프로브 동작

​

세션 재정의 및 라이브 모델 전환

• 명시적인 사용자 주도 모델 변경만 보류 중인 라이브 전환을 표시합니다. 여기에는 /model, session_status(model=...), sessions.patch가 포함됩니다.
• 폴백 교체, Heartbeat 재정의, Compaction 같은 시스템 주도 모델 변경은 자체적으로 보류 중인 라이브 전환을 표시하지 않습니다.
• 사용자 주도 모델 재정의는 폴백 정책에서 정확한 선택으로 처리되므로, 연결할 수 없는 선택된 공급자는 agents.defaults.model.fallbacks로 가려지지 않고 실패로 드러납니다.
• 폴백 재시도가 시작되기 전에 응답 러너는 선택된 폴백 재정의 필드를 세션 항목에 저장합니다.
• OpenClaw가 모든 메시지에서 알려진 불량 주 모델을 프로브하지 않도록, 자동 폴백 재정의는 이후 턴에서도 선택된 상태로 남습니다. /new, /reset, sessions.reset은 자동 소스 재정의를 지우고 세션을 구성된 기본값으로 되돌립니다.
• /status는 선택된 모델을 표시하고, 폴백 상태가 다르면 활성 폴백 모델과 이유도 표시합니다.
• 라이브 세션 조정은 오래된 런타임 모델 필드보다 저장된 세션 재정의를 우선합니다.
• 라이브 전환 오류가 활성 폴백 체인의 더 뒤쪽 후보를 가리키면, OpenClaw는 관련 없는 후보를 먼저 따라가지 않고 해당 선택된 모델로 직접 이동합니다.
• 폴백 시도가 실패하면 러너는 자신이 쓴 재정의 필드만 롤백하며, 해당 필드가 여전히 실패한 후보와 일치할 때만 롤백합니다.

​

관측 가능성 및 실패 요약

• 시도한 공급자/모델
• 이유(rate_limit, overloaded, billing, auth, model_not_found 및 유사한 페일오버 이유)
• 선택적 상태/코드
• 사람이 읽을 수 있는 오류 요약

• 시도된 공급자/모델 체인과 관련 없는 모델 범위 속도 제한은 무시됩니다.
• 남은 차단이 일치하는 모델 범위 속도 제한이면 OpenClaw는 해당 모델을 여전히 차단하는 마지막 일치 만료 시간을 보고합니다.

​

관련 구성

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 라우팅