Chuyển đổi dự phòng mô hình

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

1. Luân phiên hồ sơ xác thực trong nhà cung cấp hiện tại.
2. Dự phòng mô hình sang mô hình tiếp theo trong agents.defaults.model.fallbacks.

Tài liệu này giải thích các quy tắc thời gian chạy và dữ liệu hỗ trợ chúng.

# Luồng thời gian chạy

Với một lượt chạy văn bản thông thường, OpenClaw đánh giá các ứng viên theo thứ tự này:

Điều này cố ý hẹp hơn so với "lưu và khôi phục toàn bộ phiên". Trình chạy trả lời chỉ lưu các trường lựa chọn mô hình mà nó sở hữu cho dự phòng:

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

Điều đó ngăn một lần thử lại dự phòng thất bại ghi đè các thay đổi phiên không liên quan mới hơn, chẳng hạn như thay đổi /model thủ công hoặc cập nhật luân phiên phiên xảy ra trong khi lần thử đang chạy.

# Chính sách nguồn lựa chọn

OpenClaw tách nhà cung cấp/mô hình đã chọn khỏi lý do nó được chọn. Nguồn đó kiểm soát việc chuỗi dự phòng có được phép dùng hay không:

• Mặc định đã cấu hình: agents.defaults.model.primary dùng agents.defaults.model.fallbacks.
• Mô hình chính của tác nhân: agents.list[].model nghiêm ngặt trừ khi đối tượng mô hình của tác nhân đó bao gồm fallbacks riêng. Dùng fallbacks: [] để làm rõ hành vi nghiêm ngặt, hoặc cung cấp danh sách không rỗng để bật dự phòng mô hình cho tác nhân đó.
• Ghi đè dự phòng tự động: một dự phòng thời gian chạy ghi providerOverride, modelOverride, và modelOverrideSource: "auto" trước khi thử lại. Ghi đè tự động đó có thể tiếp tục đi theo chuỗi dự phòng đã cấu hình và được xóa bởi /new, /reset, và sessions.reset.
• Ghi đè phiên của người dùng: /model, bộ chọn mô hình, session_status(model=...), và sessions.patch ghi modelOverrideSource: "user". Đó là lựa chọn phiên chính xác. Nếu nhà cung cấp/mô hình đã chọn thất bại trước khi tạo câu trả lời, OpenClaw báo lỗi thay vì trả lời từ một dự phòng đã cấu hình không liên quan.
• Ghi đè phiên cũ: các mục phiên cũ hơn có thể có modelOverride mà không có modelOverrideSource. OpenClaw xem chúng là ghi đè của người dùng để một lựa chọn cũ rõ ràng không bị âm thầm chuyển thành hành vi dự phòng.
• Mô hình trong tải trọng Cron: payload.model / --model của một tác vụ cron là mô hình chính của tác vụ, không phải ghi đè phiên của người dùng. Nó dùng các dự phòng đã cấu hình trừ khi tác vụ cung cấp payload.fallbacks; payload.fallbacks: [] làm cho lượt chạy cron nghiêm ngặt.

# Lưu trữ xác thực (khóa + OAuth)

OpenClaw dùng hồ sơ xác thực cho cả khóa API và token OAuth.

• Bí mật nằm trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (cũ: ~/.openclaw/agent/auth-profiles.json).
• Trạng thái định tuyến xác thực thời gian chạy nằm trong ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Cấu hình auth.profiles / auth.order chỉ là siêu dữ liệu + định tuyến (không có bí mật).
• Tệp OAuth cũ chỉ để nhập: ~/.openclaw/credentials/oauth.json (được nhập vào auth-profiles.json trong lần dùng đầu tiên).

Chi tiết hơn: OAuth

Loại thông tin xác thực:

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

# ID hồ sơ

Đăng nhập OAuth tạo các hồ sơ 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]).

Hồ sơ nằm trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json dưới profiles.

# Thứ tự luân phiên

Khi một nhà cung cấp có nhiều hồ sơ, OpenClaw chọn thứ tự như sau:

Nếu không có thứ tự rõ ràng được cấu hình, OpenClaw dùng thứ tự vòng tròn:

• Khóa chính: loại hồ sơ (OAuth trước khóa API).
• Khóa phụ: usageStats.lastUsed (cũ nhất trước, trong từng loại).
• Hồ sơ đang tạm ngưng/bị vô hiệu hóa được chuyển xuống cuối, sắp xếp theo thời điểm hết hạn sớm nhất.

# Tính bám dính của phiên (thân thiện với bộ đệm)

OpenClaw ghim hồ sơ xác thực đã chọn theo từng phiên để giữ ấm bộ đệm của nhà cung cấp. Nó không luân phiên trên mọi yêu cầu. Hồ sơ đã ghim được dùng lại cho đến khi:

• phiên được đặt lại (/new / /reset)
• một lần Compaction hoàn tất (số đếm Compaction tăng)
• hồ sơ đang tạm ngưng/bị vô hiệu hóa

Lựa chọn thủ công qua /model …@<profileId> đặt một ghi đè của người dùng cho phiên đó và không được tự động luân phiên cho đến khi phiên mới bắt đầu.

# Vì sao OAuth có thể "trông như bị mất"

Nếu bạn có cả hồ sơ OAuth và hồ sơ khóa API cho cùng một nhà cung cấp, vòng tròn có thể chuyển đổi giữa chúng qua các tin nhắn trừ khi đã ghim. Để buộc dùng một hồ sơ duy nhất:

• Ghim bằng auth.order[provider] = ["provider:profileId"], hoặc
• Dùng ghi đè theo phiên qua /model … với ghi đè hồ sơ (khi bề mặt UI/chat của bạn hỗ trợ).

# Tạm ngưng

Khi một hồ sơ thất bại do lỗi xác thực/giới hạn tốc độ (hoặc hết thời gian chờ trông giống giới hạn tốc độ), OpenClaw đánh dấu hồ sơ đó là đang tạm ngưng và chuyển sang hồ sơ tiếp theo.

Tạm ngưng dùng lùi theo hàm mũ:

• 1 phút
• 5 phút
• 25 phút
• 1 giờ (giới hạn)

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

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

# Vô hiệu hóa do thanh toán

Lỗi thanh toán/tín dụng (ví dụ "insufficient credits" / "credit balance too low") được xem là đủ điều kiện chuyển dự phòng, nhưng thường không phải tạm thời. Thay vì tạm ngưng ngắn, OpenClaw đánh dấu hồ sơ là bị vô hiệu hóa (với lùi lâu hơn) và luân phiên sang hồ sơ/nhà cung cấp tiếp theo.

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

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

Mặc định:

• Lùi do thanh toán bắt đầu ở 5 giờ, tăng gấp đôi theo mỗi lỗi thanh toán, và giới hạn ở 24 giờ.
• Bộ đếm lùi được đặt lại nếu hồ sơ không thất bại trong 24 giờ (có thể cấu hình).
• Thử lại do quá tải cho phép 1 lần luân phiên hồ sơ cùng nhà cung cấp trước khi dự phòng mô hình.
• Thử lại do quá tải mặc định dùng 0 ms lùi.

# Dự phòng mô hình

Nếu tất cả hồ sơ cho một nhà cung cấp đều thất bại, OpenClaw chuyển sang mô hình tiếp theo trong agents.defaults.model.fallbacks. Điều này áp dụng cho lỗi xác thực, giới hạn tốc độ và hết thời gian chờ đã cạn luân phiên hồ sơ (các lỗi khác không chuyển tiếp dự phòng). Lỗi nhà cung cấp không lộ đủ chi tiết vẫn được gắn nhãn chính xác trong trạng thái dự phòng: empty_response nghĩa là nhà cung cấp không trả về thông điệp hoặc trạng thái dùng được, no_error_details nghĩa là nhà cung cấp trả về rõ ràng Unknown error (no error details in response), và unclassified nghĩa là OpenClaw đã giữ lại bản xem trước thô nhưng chưa có bộ phân loại nào khớp.

Các lỗi quá tải và giới hạn tốc độ được xử lý quyết liệt hơn so với thời gian chờ do thanh toán. Theo mặc định, OpenClaw cho phép thử lại một lần với auth-profile cùng nhà cung cấp, rồi chuyển sang fallback mô hình đã cấu hình tiếp theo mà không chờ. Các tín hiệu nhà cung cấp đang bận như ModelNotReadyException được xếp vào nhóm quá tải đó. Điều chỉnh hành vi này bằng auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs và auth.cooldowns.rateLimitedProfileRotations.

Khi một lượt chạy bắt đầu từ primary mặc định đã cấu hình, primary của cron job, primary của agent có fallback tường minh, hoặc override fallback được tự động chọn, OpenClaw có thể đi theo chuỗi fallback đã cấu hình tương ứng. Primary của agent không có fallback tường minh và các lựa chọn người dùng tường minh (ví dụ /model ollama/qwen3.5:27b, bộ chọn mô hình, sessions.patch, hoặc override nhà cung cấp/mô hình CLI dùng một lần) là nghiêm ngặt: nếu nhà cung cấp/mô hình đó không thể truy cập hoặc lỗi trước khi tạo phản hồi, OpenClaw báo lỗi thay vì trả lời từ một fallback không liên quan.

# Quy tắc chuỗi ứng viên

OpenClaw xây dựng danh sách ứng viên từ provider/model hiện được yêu cầu cộng với các fallback đã cấu hình.

# Những lỗi làm fallback tiến tiếp

# Hành vi bỏ qua cooldown so với thăm dò

Khi mọi auth profile của một nhà cung cấp đều đã trong cooldown, OpenClaw không tự động bỏ qua nhà cung cấp đó mãi mãi. Nó đưa ra quyết định theo từng ứng viên:

# Override phiên và chuyển mô hình trực tiếp

Các thay đổi mô hình phiên là trạng thái dùng chung. Runner đang hoạt động, lệnh /model, các cập nhật compaction/phiên, và đối soát phiên trực tiếp đều đọc hoặc ghi các phần của cùng một mục phiên.

Điều đó có nghĩa là các lần thử lại fallback phải phối hợp với chuyển mô hình trực tiếp:

• Chỉ các thay đổi mô hình do người dùng chủ động tường minh mới đánh dấu một lần chuyển trực tiếp đang chờ. Điều này bao gồm /model, session_status(model=...) và sessions.patch.
• Các thay đổi mô hình do hệ thống điều khiển như xoay vòng fallback, override heartbeat, hoặc compaction không tự đánh dấu một lần chuyển trực tiếp đang chờ.
• Override mô hình do người dùng điều khiển được xem là lựa chọn chính xác cho chính sách fallback, vì vậy một nhà cung cấp đã chọn nhưng không thể truy cập sẽ hiển thị lỗi thay vì bị che bởi agents.defaults.model.fallbacks.
• Trước khi một lần thử lại fallback bắt đầu, reply runner lưu các trường override fallback đã chọn vào mục phiên.
• Override fallback tự động vẫn được chọn trong các lượt tiếp theo để OpenClaw không thăm dò một primary đã biết là lỗi trên mọi tin nhắn. /new, /reset và sessions.reset xóa các override có nguồn tự động và đưa phiên về mặc định đã cấu hình.
• /status hiển thị mô hình đã chọn và, khi trạng thái fallback khác đi, mô hình fallback đang hoạt động cùng lý do.
• Đối soát phiên trực tiếp ưu tiên override phiên đã lưu hơn các trường mô hình runtime cũ.
• Nếu lỗi chuyển trực tiếp trỏ đến một ứng viên sau trong chuỗi fallback đang hoạt động, OpenClaw nhảy thẳng đến mô hình đã chọn đó thay vì đi qua các ứng viên không liên quan trước.
• Nếu lần thử fallback thất bại, runner chỉ khôi phục các trường override mà nó đã ghi, và chỉ khi chúng vẫn khớp với ứng viên thất bại đó.

Điều này ngăn cuộc đua kinh điển:

Override fallback đã lưu sẽ đóng khoảng hở đó, và rollback hẹp giữ nguyên các thay đổi phiên thủ công hoặc runtime mới hơn.

# Khả năng quan sát và tóm tắt lỗi

runWithModelFallback(...) ghi lại chi tiết theo từng lần thử để cung cấp cho nhật ký và thông báo cooldown hướng đến người dùng:

• nhà cung cấp/mô hình đã thử
• lý do (rate_limit, overloaded, billing, auth, model_not_found, và các lý do failover tương tự)
• trạng thái/mã tùy chọn
• tóm tắt lỗi dễ đọc

Nhật ký có cấu trúc model_fallback_decision cũng bao gồm các trường phẳng fallbackStep* khi một ứng viên thất bại, bị bỏ qua, hoặc một fallback sau đó thành công. Các trường này làm rõ lần chuyển tiếp đã thử (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) để bộ xuất nhật ký và chẩn đoán có thể dựng lại lỗi primary ngay cả khi fallback cuối cùng cũng thất bại.

Khi mọi ứng viên đều thất bại, OpenClaw ném FallbackSummaryError. Reply runner bên ngoài có thể dùng lỗi đó để xây dựng thông báo cụ thể hơn, chẳng hạn như "tất cả mô hình tạm thời đang bị giới hạn tốc độ", và bao gồm thời điểm cooldown sớm nhất kết thúc nếu biết được.

Tóm tắt cooldown đó có nhận biết mô hình:

• các giới hạn tốc độ theo phạm vi mô hình không liên quan bị bỏ qua đối với chuỗi nhà cung cấp/mô hình đã thử
• nếu phần chặn còn lại là giới hạn tốc độ theo phạm vi mô hình khớp, OpenClaw báo thời điểm hết hạn khớp cuối cùng vẫn còn chặn mô hình đó

# Cấu hình liên quan

Xem Cấu hình Gateway để biết:

• 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
• định tuyến agents.defaults.imageModel

Xem Mô hình để biết tổng quan rộng hơn về lựa chọn mô hình và fallback.