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

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. 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.

​

Luồng runtime

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

​

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

• Mặc định đã cấu hình: agents.defaults.model.primary dùng agents.defaults.model.fallbacks.
• Mô hình chính của agent: agents.list[].model là nghiêm ngặt trừ khi đối tượng mô hình của agent đó có fallbacks riêng. Dùng fallbacks: [] để biểu thị rõ hành vi nghiêm ngặt, hoặc cung cấp một danh sách không rỗng để bật dự phòng mô hình cho agent đó.
• Override dự phòng tự động: một dự phòng runtime ghi providerOverride, modelOverride, và modelOverrideSource: "auto" trước khi thử lại. Override tự động đó có thể tiếp tục đi qua chuỗi dự phòng đã cấu hình và được xóa bởi /new, /reset, và sessions.reset.
• Override 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à một lựa chọn phiên chính xác. Nếu nhà cung cấp/mô hình đã chọn lỗi trước khi tạo phản hồ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.
• Override 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à override 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 payload Cron: payload.model / --model của một cron job là mô hình chính của job, không phải override phiên của người dùng. Nó dùng các dự phòng đã cấu hình trừ khi job cung cấp payload.fallbacks; payload.fallbacks: [] làm cho lần chạy cron trở nên nghiêm ngặt.

​

Lưu trữ xác thực (khóa + 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 runtime nằm trong ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Cấu hình auth.profiles / auth.order chỉ là metadata + định tuyến (không có bí mật).
• Tệp OAuth cũ chỉ dùng để import: ~/.openclaw/credentials/oauth.json (được import vào auth-profiles.json khi dùng lần đầu).

• 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ơ

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

​

Thứ tự luân phiên

• Khóa chính: loại hồ sơ (OAuth trước API key).
• Khóa phụ: usageStats.lastUsed (cũ nhất trước, trong từng loại).
• Hồ sơ đang cooldown/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.

​

Độ bám phiên (thân thiện với cache)

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

​

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

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

​

Cooldown

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

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

​

Vô hiệu hóa do billing

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

• Backoff billing bắt đầu ở 5 giờ, tăng gấp đôi theo mỗi lỗi billing, và giới hạn ở 24 giờ.
• Bộ đếm backoff đặt lại nếu hồ sơ không lỗi trong 24 giờ (có thể cấu hình).
• Thử lại 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 quá tải mặc định dùng 0 ms backoff.

​

Dự phòng mô hình

​

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

​

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

​

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

​

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

• Chỉ các thay đổi mô hình rõ ràng do người dùng điều khiển mới đánh dấu một chuyển đổi trực tiếp đang chờ. Điều đó 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 bao giờ tự đánh dấu một chuyển đổi 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, nên một provider đã chọn nhưng không truy cập được sẽ hiện ra dưới dạng 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, runner phản hồi 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 ở các lượt sau để OpenClaw không thăm dò primary đã biết là lỗi ở mọi tin nhắn. /new, /reset, và sessions.reset xóa các override có nguồn gốc 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.
• Hòa giải phiên trực tiếp ưu tiên override phiên đã lưu hơn các trường mô hình runtime lỗi thời.
• Nếu lỗi chuyển trực tiếp trỏ tới một ứng viên sau trong chuỗi fallback đang hoạt động, OpenClaw nhảy thẳng tới 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 đó.

​

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

• provider/model đã thử
• lý do (rate_limit, overloaded, billing, auth, model_not_found, và các lý do failover tương tự)
• status/code tùy chọn
• tóm tắt lỗi dễ đọc cho con người

• 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 provider/model đã thử
• nếu phần chặn còn lại là một 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 đang chặn mô hình đó

​

Cấu hình liên quan

• 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