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

1. Luân phiên hồ sơ xác thực trong provider hiện tại.
2. Chuyển 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: [] để làm rõ hành vi nghiêm ngặt, hoặc cung cấp danh sách không rỗng để bật chuyển dự phòng mô hình cho agent đó.
• Ghi đè dự phòng tự động: một dự phòng runtime ghi providerOverride, modelOverride, modelOverrideSource: "auto" và mô hình gốc đã chọn 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 mà không thăm dò mô hình chính trên mọi tin nhắn, nhưng OpenClaw định kỳ thăm dò lại mô hình gốc đã cấu hình và xóa ghi đè tự động khi mô hình đó phục hồi. /new, /reset và sessions.reset cũng xóa các ghi đè có nguồn tự động. Heartbeat chạy không có heartbeat.model rõ ràng sẽ xóa các ghi đè tự động trực tiếp khi nguồn gốc của chúng không còn khớp với mặc định hiện đã cấu hình.
• 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à một lựa chọn phiên chính xác. Nếu provider/mô hình đã chọn thất bạ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.
• 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 payload Cron: payload.model / --model của cron job là mô hình chính của job, 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 job cung cấp payload.fallbacks; payload.fallbacks: [] làm cho lượt chạy Cron nghiêm ngặt.

​

Bộ nhớ đệm bỏ qua lỗi xác thực

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

Thông báo dự phòng hiển thị với người dùng

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

↪️ Model Fallback cleared: <primary> (was <fallback>)

​

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

• Bí mật và trạng thái định tuyến xác thực runtime nằm trong ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• 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 kho xác thực theo agent trong lần dùng đầu tiên).
• Các tệp auth-profiles.json, auth-state.json cũ và các tệp auth.json theo agent được nhập bởi openclaw doctor --fix.

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

​

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 khóa API).
• Khóa phụ: usageStats.lastUsed (cũ nhất trước, trong từng loại).
• Hồ sơ cooldown/bị tắt đượ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 bộ nhớ đệm)

• 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 trong cooldown/bị tắt

​

Gói đăng ký OpenAI Codex cộng với khóa API dự phòng

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

​

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

​

Tắt do billing

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

• Backoff billing bắt đầu ở 5 giờ, tăng gấp đôi sau 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).
• Các lần thử lại khi quá tải cho phép 1 lần xoay hồ sơ cùng nhà cung cấp trước khi fallback mô hình.
• Các lần thử lại khi quá tải mặc định dùng backoff 0 ms.

​

Fallback mô hình

​

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

​

Lỗi nào chuyển tiếp fallback

​

Hành vi bỏ qua cooldown so với probe

​

Ghi đè phiên và chuyển đổi mô hình trực tiếp

• Chỉ các thay đổi mô hình do người dùng chủ động rõ ràng 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 fallback, ghi đè Heartbeat, hoặc Compaction không tự đánh dấu một chuyển đổi trực tiếp đang chờ.
• Ghi đè 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 nhà cung cấp đã chọn nhưng không truy cập được sẽ hiển thị lỗi thay vì bị che bởi agents.defaults.model.fallbacks.
• Trước khi bắt đầu một lần thử lại fallback, trình chạy phản hồi lưu bền vững các trường ghi đè fallback đã chọn vào mục phiên.
• Ghi đè fallback tự động vẫn được chọn ở các lượt tiếp theo để OpenClaw không probe một primary đã biết là lỗi trên mọi tin nhắn. OpenClaw định kỳ probe lại origin đã cấu hình và xóa ghi đè tự động khi nó phục hồi; /new, /reset, và sessions.reset xóa ngay các ghi đè có nguồn tự động.
• Phản hồi người dùng thông báo chuyển tiếp fallback và khôi phục đã xóa fallback một lần cho mỗi thay đổi trạng thái. Các lượt fallback dính không lặp lại thông báo.
• /status hiển thị mô hình đã chọn và, khi trạng thái fallback khác, mô hình fallback đang hoạt động cùng lý do.
• Đối soát phiên trực tiếp ưu tiên ghi đè phiên đã lưu bền vững hơn các trường mô hình runtime cũ.
• Nếu lỗi chuyển đổi 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 lỗi, trình chạy chỉ rollback các trường ghi đè mà nó đã ghi, và chỉ khi chúng vẫn khớp với ứng viên đã lỗi đó.

​

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

• nhà cung cấp/mô hình đã thử
• lý do (rate_limit, overloaded, billing, auth, model_not_found, và các lý do chuyển đổi dự phòng tương tự)
• trạng thái/mã 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 cho 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 đ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