Model failover

OpenClaw xử lý lỗi qua hai giai đoạn:

  1. Xoay vòng auth profile trong cùng một provider.
  2. Fallback sang model khác theo danh sách agents.defaults.model.fallbacks.

Tài liệu này giải thích các quy tắc runtime và dữ liệu đằng sau chúng.

Lưu trữ auth (keys + OAuth)

OpenClaw dùng auth profiles cho cả API key và OAuth token.

  • Secrets được lưu trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (cũ: ~/.openclaw/agent/auth-profiles.json).
  • Config auth.profiles / auth.order chỉ chứa metadata + routing (không có secrets).
  • File OAuth cũ (chỉ import): ~/.openclaw/credentials/oauth.json (được import vào auth-profiles.json lần đầu sử dụng).

Chi tiết thêm: /concepts/oauth

Các loại credential:

  • type: "api_key" → { provider, key }
  • type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl cho một số provider)

Profile ID

OAuth login tạo các profile riêng biệt để nhiều tài khoản có thể cùng tồn tại.

  • Mặc định: provider:default khi không có email.
  • OAuth có email: provider:<email> (ví dụ google-antigravity:[email protected]).

Các profile được lưu trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json dưới mục profiles.

Thứ tự xoay vòng

Khi một provider có nhiều profile, OpenClaw chọn thứ tự như sau:

  1. Config tường minh: auth.order[provider] (nếu có).
  2. Configured profiles: auth.profiles lọc theo provider.
  3. Stored profiles: các entry trong auth-profiles.json của provider đó.

Nếu không có thứ tự tường minh, OpenClaw dùng round-robin:

  • Khóa chính: loại profile (OAuth trước API key).
  • Khóa phụ: usageStats.lastUsed (cũ nhất trước, trong cùng loại).
  • Profile cooldown/disabled được đẩy xuống cuối, sắp xếp theo thời gian hết hạn sớm nhất.

Session stickiness (thân thiện với cache)

OpenClaw ghim auth profile đã chọn cho mỗi session để giữ cache của provider ấm. Nó không xoay vòng ở mỗi request. Profile đã ghim được dùng lại cho đến khi:

  • session được reset (/new / /reset)
  • một compaction hoàn thành (compaction count tăng)
  • profile đang trong cooldown/disabled

Chọn thủ công qua /model …@<profileId> sẽ đặt user override cho session đó và không tự động xoay vòng cho đến khi session mới bắt đầu.

Auto-pinned profile (được chọn bởi session router) được coi là preference: chúng được thử trước, nhưng OpenClaw có thể xoay sang profile khác khi gặp rate limit/timeout. User-pinned profile sẽ khóa vào profile đó; nếu nó fail và có cấu hình model fallback, OpenClaw sẽ chuyển sang model tiếp theo thay vì đổi profile.

Tại sao OAuth có thể “trông như bị mất”

Nếu các bạn có cả OAuth profile và API key profile cho cùng một provider, round-robin có thể chuyển đổi giữa chúng qua các message trừ khi được ghim. Để bắt buộc dùng một profile duy nhất:

  • Ghim bằng auth.order[provider] = ["provider:profileId"], hoặc
  • Dùng override theo session qua /model … với profile override (khi UI/chat surface hỗ trợ).

Cooldown

Khi một profile fail do lỗi auth/rate-limit (hoặc timeout trông giống rate limiting), OpenClaw đánh dấu nó vào cooldown và chuyển sang profile tiếp theo. Lỗi format/invalid-request (ví dụ Cloud Code Assist tool call ID validation failure) cũng được coi là đáng failover và dùng cùng cooldown.

Cooldown dùng exponential backoff:

  • 1 phút
  • 5 phút
  • 25 phút
  • 1 giờ (tối đa)

Trạng thái được lưu trong auth-profiles.json dưới usageStats:

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

Billing disable

Lỗi billing/credit (ví dụ “insufficient credits” / “credit balance too low”) được coi là đáng failover, nhưng chúng thường không tạm thời. Thay vì cooldown ngắn, OpenClaw đánh dấu profile là disabled (với backoff dài hơn) và xoay sang profile/provider tiếp theo.

Trạng thái được lưu trong auth-profiles.json:

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

Mặc định:

  • Billing backoff bắt đầu ở 5 giờ, nhân đôi mỗi lần billing fail, và tối đa 24 giờ.
  • Bộ đếm backoff reset nếu profile không fail trong 24 giờ (có thể cấu hình).

Model fallback

Nếu tất cả profile của một provider đều fail, OpenClaw chuyển sang model tiếp theo trong agents.defaults.model.fallbacks. Điều này áp dụng cho auth failure, rate limit, và timeout đã cạn kiệt profile rotation (các lỗi khác không kích hoạt fallback).

Khi một run bắt đầu với model override (hook hoặc CLI), fallback vẫn kết thúc ở agents.defaults.model.primary sau khi thử các fallback đã cấu hình.

Config liên quan

Xem Gateway configuration cho:

  • auth.profiles / auth.order
  • auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
  • auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
  • agents.defaults.model.primary / agents.defaults.model.fallbacks
  • agents.defaults.imageModel routing

Xem Models để hiểu tổng quan về model selection và fallback.