การสลับไปใช้โมเดลสำรอง

OpenClaw จัดการความล้มเหลวเป็นสองขั้นตอน:

การหมุนเวียนโปรไฟล์การยืนยันตัวตน ภายในผู้ให้บริการปัจจุบัน
การ fallback ของโมเดล ไปยังโมเดลถัดไปใน agents.defaults.model.fallbacks

เอกสารนี้อธิบายกฎขณะรันไทม์และข้อมูลที่รองรับกฎเหล่านั้น

โฟลว์รันไทม์

สำหรับการรันข้อความปกติ OpenClaw จะประเมินตัวเลือกตามลำดับนี้:

Resolve session state

แก้ไขสถานะโมเดลของเซสชันที่ใช้งานอยู่และค่ากำหนดโปรไฟล์การยืนยันตัวตน

Build candidate chain

สร้างลำดับตัวเลือกโมเดลจากการเลือกโมเดลปัจจุบันและนโยบาย fallback สำหรับแหล่งที่มาของการเลือกนั้น ค่าเริ่มต้นที่กำหนดไว้ โมเดลหลักของงาน cron และโมเดล fallback ที่เลือกโดยอัตโนมัติสามารถใช้ fallback ที่กำหนดไว้ได้ ส่วนการเลือกเซสชันโดยผู้ใช้อย่างชัดเจนจะเข้มงวด

Try the current provider

ลองใช้ผู้ให้บริการปัจจุบันพร้อมกฎการหมุนเวียน/คูลดาวน์ของโปรไฟล์การยืนยันตัวตน

Advance on failover-worthy errors

หากผู้ให้บริการนั้นถูกใช้จนหมดด้วยข้อผิดพลาดที่ควร failover ให้ย้ายไปยังตัวเลือกโมเดลถัดไป

Persist fallback override

บันทึก override ของ fallback ที่เลือกไว้ก่อนเริ่ม retry เพื่อให้ตัวอ่านเซสชันอื่นเห็นผู้ให้บริการ/โมเดลเดียวกับที่ runner กำลังจะใช้ override ของโมเดลที่บันทึกไว้จะถูกทำเครื่องหมายเป็น modelOverrideSource: "auto"

Roll back narrowly on failure

หากตัวเลือก fallback ล้มเหลว ให้ย้อนกลับเฉพาะฟิลด์ override ของเซสชันที่เป็นของ fallback เมื่อฟิลด์เหล่านั้นยังคงตรงกับตัวเลือกที่ล้มเหลวนั้น

Throw FallbackSummaryError if exhausted

หากทุกตัวเลือกล้มเหลว ให้ throw FallbackSummaryError พร้อมรายละเอียดรายความพยายามและเวลาหมดอายุคูลดาวน์ที่เร็วที่สุดเมื่อทราบค่า

นี่ตั้งใจให้แคบกว่า “บันทึกและกู้คืนทั้งเซสชัน” reply runner จะบันทึกเฉพาะฟิลด์การเลือกโมเดลที่ตนเองเป็นเจ้าของสำหรับ fallback:

providerOverride
modelOverride
modelOverrideSource
authProfileOverride
authProfileOverrideSource
authProfileOverrideCompactionCount

วิธีนี้ป้องกันไม่ให้การ retry fallback ที่ล้มเหลวเขียนทับการเปลี่ยนแปลงเซสชันอื่นที่ใหม่กว่าและไม่เกี่ยวข้อง เช่น การเปลี่ยน /model ด้วยตนเอง หรือการอัปเดตการหมุนเวียนเซสชันที่เกิดขึ้นระหว่างที่ความพยายามนั้นกำลังรัน

นโยบายแหล่งที่มาของการเลือก

OpenClaw แยกผู้ให้บริการ/โมเดลที่เลือกออกจากเหตุผลที่ถูกเลือก แหล่งที่มานั้นควบคุมว่าอนุญาตให้ใช้ลำดับ fallback หรือไม่:

ค่าเริ่มต้นที่กำหนดไว้: agents.defaults.model.primary ใช้ agents.defaults.model.fallbacks
โมเดลหลักของ agent: agents.list[].model จะเข้มงวด เว้นแต่ว่าอ็อบเจกต์โมเดลของ agent นั้นมี fallbacks ของตัวเอง ใช้ fallbacks: [] เพื่อทำให้พฤติกรรมแบบเข้มงวดชัดเจน หรือระบุรายการที่ไม่ว่างเพื่อให้ agent นั้นเลือกใช้ model fallback
Auto fallback override: fallback ขณะรันไทม์จะเขียน providerOverride, modelOverride, modelOverrideSource: "auto" และโมเดลต้นทางที่เลือกไว้ก่อน retry auto override นั้นสามารถเดินต่อไปตามลำดับ fallback ที่กำหนดไว้ และจะถูกล้างโดย /new, /reset และ sessions.reset การรัน Heartbeat ที่ไม่มี heartbeat.model อย่างชัดเจนจะล้าง direct auto override ด้วยเมื่อ origin ของมันไม่ตรงกับค่าเริ่มต้นที่กำหนดไว้ในปัจจุบันอีกต่อไป
User session override: /model, ตัวเลือกโมเดล, session_status(model=...) และ sessions.patch จะเขียน modelOverrideSource: "user" นี่คือการเลือกเซสชันแบบตรงตัว หากผู้ให้บริการ/โมเดลที่เลือกไว้ล้มเหลวก่อนสร้างคำตอบ OpenClaw จะรายงานความล้มเหลวแทนการตอบจาก fallback ที่กำหนดไว้ซึ่งไม่เกี่ยวข้อง
Legacy session override: รายการเซสชันรุ่นเก่าอาจมี modelOverride โดยไม่มี modelOverrideSource OpenClaw ถือว่ารายการเหล่านั้นเป็น user override เพื่อไม่ให้การเลือกเก่าอย่างชัดเจนถูกแปลงเป็นพฤติกรรม fallback โดยเงียบ
โมเดล payload ของ Cron: payload.model / --model ของงาน cron คือโมเดลหลักของงาน ไม่ใช่ user session override โมเดลนี้ใช้ fallback ที่กำหนดไว้ เว้นแต่งานจะระบุ payload.fallbacks; payload.fallbacks: [] ทำให้การรัน cron เข้มงวด

ที่เก็บการยืนยันตัวตน (คีย์ + OAuth)

OpenClaw ใช้ โปรไฟล์การยืนยันตัวตน สำหรับทั้ง API keys และ OAuth tokens

ความลับอยู่ใน ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (แบบเดิม: ~/.openclaw/agent/auth-profiles.json)
สถานะการกำหนดเส้นทางการยืนยันตัวตนขณะรันไทม์อยู่ใน ~/.openclaw/agents/<agentId>/agent/auth-state.json
Config auth.profiles / auth.order เป็น เมทาดาทา + การกำหนดเส้นทางเท่านั้น (ไม่มีความลับ)
ไฟล์ OAuth แบบเดิมที่ใช้สำหรับนำเข้าเท่านั้น: ~/.openclaw/credentials/oauth.json (นำเข้าไปยัง auth-profiles.json เมื่อใช้งานครั้งแรก)

รายละเอียดเพิ่มเติม: OAuth ประเภทข้อมูลรับรอง:

type: "api_key" → { provider, key }
type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl สำหรับผู้ให้บริการบางราย)

ID โปรไฟล์

การเข้าสู่ระบบ OAuth จะสร้างโปรไฟล์แยกกันเพื่อให้หลายบัญชีอยู่ร่วมกันได้

ค่าเริ่มต้น: provider:default เมื่อไม่มีอีเมล
OAuth พร้อมอีเมล: provider:<email> (เช่น google-antigravity:user@gmail.com)

โปรไฟล์อยู่ใน ~/.openclaw/agents/<agentId>/agent/auth-profiles.json ภายใต้ profiles

ลำดับการหมุนเวียน

เมื่อผู้ให้บริการมีหลายโปรไฟล์ OpenClaw จะเลือกลำดับดังนี้:

Explicit config

auth.order[provider] (หากตั้งค่าไว้)

Configured profiles

auth.profiles ที่กรองตามผู้ให้บริการ

Stored profiles

รายการใน auth-profiles.json สำหรับผู้ให้บริการ

หากไม่ได้กำหนดลำดับไว้อย่างชัดเจน OpenClaw จะใช้ลำดับแบบ round-robin:

คีย์หลัก: ประเภทโปรไฟล์ (OAuth ก่อน API keys)
คีย์รอง: usageStats.lastUsed (เก่าที่สุดก่อน ภายในแต่ละประเภท)
โปรไฟล์ที่อยู่ในคูลดาวน์/ถูกปิดใช้งาน จะถูกย้ายไปท้ายสุด เรียงตามเวลาหมดอายุที่เร็วที่สุด

การยึดติดกับเซสชัน (เป็นมิตรกับแคช)

OpenClaw ปักหมุดโปรไฟล์การยืนยันตัวตนที่เลือกต่อเซสชัน เพื่อให้แคชของผู้ให้บริการยังอุ่นอยู่ OpenClaw ไม่ หมุนเวียนทุกคำขอ โปรไฟล์ที่ปักหมุดจะถูกใช้ซ้ำจนกว่า:

เซสชันถูกรีเซ็ต (/new / /reset)
Compaction เสร็จสมบูรณ์ (ตัวนับ compaction เพิ่มขึ้น)
โปรไฟล์อยู่ในคูลดาวน์/ถูกปิดใช้งาน

การเลือกด้วยตนเองผ่าน /model …@<profileId> จะตั้งค่า user override สำหรับเซสชันนั้น และจะไม่ถูกหมุนเวียนอัตโนมัติจนกว่าจะเริ่มเซสชันใหม่

โปรไฟล์ที่ปักหมุดอัตโนมัติ (เลือกโดย session router) จะถูกถือเป็น ค่ากำหนด: จะถูกลองก่อน แต่ OpenClaw อาจหมุนเวียนไปยังโปรไฟล์อื่นเมื่อมี rate limit/timeout เมื่อโปรไฟล์เดิมกลับมาใช้งานได้อีกครั้ง การรันใหม่สามารถเลือกใช้โปรไฟล์นั้นอีกครั้งได้โดยไม่ต้องเปลี่ยนโมเดลหรือรันไทม์ที่เลือกไว้ โปรไฟล์ที่ผู้ใช้ปักหมุดจะล็อกอยู่กับโปรไฟล์นั้น หากล้มเหลวและมีการกำหนด model fallback ไว้ OpenClaw จะย้ายไปยังโมเดลถัดไปแทนการสลับโปรไฟล์

การสมัครใช้งาน OpenAI Codex พร้อม API-key สำรอง

สำหรับโมเดล agent ของ OpenAI การยืนยันตัวตนและรันไทม์แยกจากกัน openai/gpt-* ยังคงอยู่บน Codex harness ขณะที่การยืนยันตัวตนสามารถหมุนเวียนระหว่างโปรไฟล์การสมัครใช้งาน Codex และ API-key สำรองของ OpenAI ได้ ใช้ auth.order.openai สำหรับลำดับที่ผู้ใช้เห็น:

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

โปรไฟล์การสมัครใช้งาน Codex ที่มีอยู่แล้วอาจยังใช้ ID โปรไฟล์แบบเดิม openai-codex:* API-key สำรองที่จัดลำดับไว้สามารถเป็นโปรไฟล์ API-key openai:* ปกติได้ เมื่อการสมัครใช้งานถึงขีดจำกัดการใช้งาน Codex OpenClaw จะบันทึกเวลา reset ที่แน่นอนเมื่อ Codex ให้มา ลองใช้โปรไฟล์การยืนยันตัวตนถัดไป ตามลำดับ และคงการรันไว้ภายใน Codex harness เมื่อเวลา reset ผ่านไปแล้ว โปรไฟล์การสมัครใช้งานจะมีสิทธิ์ใช้งานอีกครั้ง และการเลือกอัตโนมัติครั้งถัดไป สามารถกลับไปใช้โปรไฟล์นั้นได้ ใช้โปรไฟล์ที่ผู้ใช้ปักหมุดเฉพาะเมื่อคุณต้องการบังคับใช้บัญชี/คีย์หนึ่งสำหรับ เซสชันนั้น โปรไฟล์ที่ผู้ใช้ปักหมุดตั้งใจให้เข้มงวดและจะไม่กระโดด ไปยังโปรไฟล์อื่นโดยเงียบ

คูลดาวน์

เมื่อโปรไฟล์ล้มเหลวเนื่องจากข้อผิดพลาดการยืนยันตัวตน/rate-limit (หรือ timeout ที่ดูเหมือน rate limiting) OpenClaw จะทำเครื่องหมายว่าอยู่ในคูลดาวน์และย้ายไปยังโปรไฟล์ถัดไป

What lands in the rate-limit / timeout bucket

กลุ่ม rate-limit นั้นกว้างกว่า 429 ธรรมดา: ยังรวมข้อความจากผู้ให้บริการ เช่น Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, throttled, resource exhausted และขีดจำกัด usage-window เป็นรอบ เช่น weekly/monthly limit reachedข้อผิดพลาด format/invalid-request มักเป็นแบบสิ้นสุด เพราะการ retry payload เดิมจะล้มเหลวแบบเดิม ดังนั้น OpenClaw จะแสดงข้อผิดพลาดเหล่านั้นแทนการหมุนเวียนโปรไฟล์การยืนยันตัวตน เส้นทาง retry-repair ที่ทราบสามารถเลือกใช้ได้อย่างชัดเจน: เช่น ความล้มเหลวของการตรวจสอบ ID การเรียก tool ของ Cloud Code Assist จะถูก sanitize และ retry หนึ่งครั้งผ่านนโยบาย allowFormatRetry ข้อผิดพลาด stop-reason ที่เข้ากันได้กับ OpenAI เช่น Unhandled stop reason: error, stop reason: error และ reason: error จะถูกจัดประเภทเป็นสัญญาณ timeout/failoverข้อความเซิร์ฟเวอร์ทั่วไปอาจถูกจัดอยู่ในกลุ่ม timeout นั้นด้วยเมื่อแหล่งที่มาตรงกับรูปแบบชั่วคราวที่ทราบ เช่น ข้อความ stream-wrapper แบบเปล่าของ pi-ai An unknown error occurred จะถูกถือว่าควร failover สำหรับผู้ให้บริการทุกเจ้า เพราะ pi-ai ส่งข้อความนี้เมื่อสตรีมของผู้ให้บริการจบด้วย stopReason: "aborted" หรือ stopReason: "error" โดยไม่มีรายละเอียดเฉพาะ payload JSON api_error ที่มีข้อความเซิร์ฟเวอร์ชั่วคราว เช่น internal server error, unknown error, 520, upstream error หรือ backend error ก็ถือเป็น timeout ที่ควร failover เช่นกันข้อความ upstream ทั่วไปเฉพาะ OpenRouter เช่น Provider returned error แบบเปล่าจะถือเป็น timeout เฉพาะเมื่อบริบทของผู้ให้บริการเป็น OpenRouter จริงๆ ข้อความ fallback ภายในทั่วไป เช่น LLM request failed with an unknown error. ยังคงใช้แนวทางอนุรักษ์นิยมและไม่ trigger failover ด้วยตัวเอง

SDK retry-after caps

SDK ของผู้ให้บริการบางตัวอาจ sleep เป็นเวลา Retry-After ที่ยาวนานก่อนคืนการควบคุมให้ OpenClaw สำหรับ SDK ที่อิง Stainless เช่น Anthropic และ OpenAI OpenClaw จะจำกัดการรอ retry-after-ms / retry-after ภายใน SDK ไว้ที่ 60 วินาทีโดยค่าเริ่มต้น และแสดงผล response ที่ retry ได้ซึ่งยาวกว่านั้นทันที เพื่อให้เส้นทาง failover นี้รันได้ ปรับแต่งหรือปิด cap ด้วย OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS; ดู พฤติกรรมการ retry

Model-scoped cooldowns

คูลดาวน์ rate-limit สามารถจำกัดขอบเขตตามโมเดลได้เช่นกัน:

OpenClaw บันทึก cooldownModel สำหรับความล้มเหลว rate-limit เมื่อทราบ ID โมเดลที่ล้มเหลว
โมเดลพี่น้องบนผู้ให้บริการเดียวกันยังสามารถลองได้เมื่อคูลดาวน์ถูกจำกัดขอบเขตไว้กับโมเดลอื่น
หน้าต่าง billing/disabled ยังคงบล็อกทั้งโปรไฟล์ข้ามโมเดล

คูลดาวน์ใช้ exponential backoff:

1 นาที
5 นาที
25 นาที
1 ชั่วโมง (cap)

สถานะถูกเก็บใน auth-state.json ภายใต้ usageStats:

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

การปิดใช้งานจาก billing

ความล้มเหลวด้าน billing/credit (เช่น “insufficient credits” / “credit balance too low”) จะถูกถือว่าควร failover แต่โดยปกติไม่ใช่เรื่องชั่วคราว แทนที่จะใช้คูลดาวน์สั้นๆ OpenClaw จะทำเครื่องหมายโปรไฟล์เป็น disabled (พร้อม backoff ที่ยาวกว่า) และหมุนเวียนไปยังโปรไฟล์/ผู้ให้บริการถัดไป

ไม่ใช่ทุก response ที่มีลักษณะ billing จะเป็น 402 และไม่ใช่ทุก HTTP 402 จะเข้ามาในส่วนนี้ OpenClaw คงข้อความ billing ที่ชัดเจนไว้ในเลน billing แม้ผู้ให้บริการจะคืน 401 หรือ 403 แทน แต่ matcher เฉพาะผู้ให้บริการจะยังจำกัดขอบเขตอยู่กับผู้ให้บริการที่เป็นเจ้าของ matcher นั้น (เช่น OpenRouter 403 Key limit exceeded)ระหว่างนี้ ข้อผิดพลาดชั่วคราว 402 สำหรับหน้าต่างการใช้งานและขีดจำกัดค่าใช้จ่ายขององค์กร/เวิร์กสเปซจะถูกจัดประเภทเป็น rate_limit เมื่อข้อความดูเหมือนลองใหม่ได้ (เช่น weekly usage limit exhausted, daily limit reached, resets tomorrow หรือ organization spending limit exceeded) รายการเหล่านี้จะอยู่บนเส้นทางคูลดาวน์/เฟลโอเวอร์สั้น แทนที่จะเป็นเส้นทางปิดใช้งานการเรียกเก็บเงินแบบยาว

สถานะถูกจัดเก็บใน auth-state.json:

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

ค่าเริ่มต้น:

แบ็กออฟของการเรียกเก็บเงินเริ่มที่ 5 ชั่วโมง เพิ่มเป็นสองเท่าต่อความล้มเหลวของการเรียกเก็บเงินแต่ละครั้ง และจำกัดสูงสุดที่ 24 ชั่วโมง
ตัวนับแบ็กออฟจะรีเซ็ตหากโปรไฟล์ไม่ล้มเหลวเป็นเวลา 24 ชั่วโมง (กำหนดค่าได้)
การลองใหม่เมื่อโอเวอร์โหลดอนุญาตให้ หมุนเวียนโปรไฟล์ภายในผู้ให้บริการเดียวกัน 1 ครั้ง ก่อน fallback โมเดล
การลองใหม่เมื่อโอเวอร์โหลดใช้แบ็กออฟ 0 ms ตามค่าเริ่มต้น

fallback โมเดล

หากโปรไฟล์ทั้งหมดของผู้ให้บริการล้มเหลว OpenClaw จะย้ายไปยังโมเดลถัดไปใน agents.defaults.model.fallbacks สิ่งนี้ใช้กับความล้มเหลวของการยืนยันตัวตน ขีดจำกัดอัตรา และการหมดเวลาที่ใช้การหมุนเวียนโปรไฟล์จนหมดแล้ว (ข้อผิดพลาดอื่นจะไม่เลื่อน fallback) ข้อผิดพลาดของผู้ให้บริการที่ไม่เปิดเผยรายละเอียดเพียงพอยังคงถูกติดป้ายอย่างแม่นยำในสถานะ fallback: empty_response หมายความว่าผู้ให้บริการไม่ได้ส่งข้อความหรือสถานะที่ใช้งานได้กลับมา, no_error_details หมายความว่าผู้ให้บริการส่งกลับมาอย่างชัดเจนว่า Unknown error (no error details in response), และ unclassified หมายความว่า OpenClaw เก็บพรีวิวดิบไว้ แต่ยังไม่มีตัวจัดประเภทใดตรงกับมัน ข้อผิดพลาดโอเวอร์โหลดและขีดจำกัดอัตราจะถูกจัดการเชิงรุกกว่าคูลดาวน์การเรียกเก็บเงิน ตามค่าเริ่มต้น OpenClaw อนุญาตให้ลองใหม่ด้วยโปรไฟล์ยืนยันตัวตนของผู้ให้บริการเดียวกันหนึ่งครั้ง จากนั้นสลับไปยัง fallback โมเดลถัดไปที่กำหนดค่าไว้โดยไม่รอ สัญญาณผู้ให้บริการไม่ว่าง เช่น ModelNotReadyException จะอยู่ในกลุ่มโอเวอร์โหลดนั้น ปรับค่านี้ได้ด้วย auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs และ auth.cooldowns.rateLimitedProfileRotations เมื่อการรันเริ่มจากค่าเริ่มต้นหลักที่กำหนดค่าไว้, ค่าหลักของงาน cron, ค่าหลักของ agent ที่มี fallback ชัดเจน, หรือการ override fallback ที่เลือกอัตโนมัติ OpenClaw สามารถเดินตามสาย fallback ที่กำหนดค่าไว้ซึ่งตรงกันได้ ค่าหลักของ agent ที่ไม่มี fallback ชัดเจนและการเลือกของผู้ใช้โดยตรง (เช่น /model ollama/qwen3.5:27b, ตัวเลือกโมเดล, sessions.patch หรือการ override ผู้ให้บริการ/โมเดลแบบครั้งเดียวผ่าน CLI) เป็นแบบเคร่งครัด: หากผู้ให้บริการ/โมเดลนั้นเข้าถึงไม่ได้หรือล้มเหลวก่อนสร้างคำตอบ OpenClaw จะรายงานความล้มเหลวแทนที่จะตอบจาก fallback ที่ไม่เกี่ยวข้อง

กฎของสาย candidate

OpenClaw สร้างรายการ candidate จาก provider/model ที่ถูกร้องขอในปัจจุบัน พร้อม fallback ที่กำหนดค่าไว้

Rules

โมเดลที่ถูกร้องขอจะอยู่ลำดับแรกเสมอ
fallback ที่กำหนดค่าไว้อย่างชัดเจนจะถูกตัดรายการซ้ำออก แต่ไม่ถูกกรองด้วย allowlist ของโมเดล รายการเหล่านี้ถือเป็นเจตนาของผู้ปฏิบัติงานอย่างชัดเจน
หากการรันปัจจุบันอยู่บน fallback ที่กำหนดค่าไว้แล้วในตระกูลผู้ให้บริการเดียวกัน OpenClaw จะยังใช้สายที่กำหนดค่าไว้ทั้งหมดต่อไป
เมื่อไม่ได้ส่ง fallback override ชัดเจนมา fallback ที่กำหนดค่าไว้จะถูกลองก่อนค่าหลักที่กำหนดค่าไว้ แม้ว่าโมเดลที่ถูกร้องขอจะใช้ผู้ให้บริการคนละราย
เมื่อไม่ได้ส่ง fallback override ชัดเจนให้ตัวรัน fallback ค่าหลักที่กำหนดค่าไว้จะถูกต่อท้าย เพื่อให้สายสามารถกลับไปอยู่ที่ค่าเริ่มต้นปกติได้เมื่อ candidate ก่อนหน้าถูกใช้จนหมด
เมื่อผู้เรียกส่ง fallbacksOverride ตัวรันจะใช้เฉพาะโมเดลที่ถูกร้องขอพร้อมรายการ override นั้น รายการว่างจะปิดใช้งาน fallback โมเดล และป้องกันไม่ให้ค่าหลักที่กำหนดค่าไว้ถูกต่อท้ายเป็นเป้าหมายลองใหม่แบบซ่อน

ข้อผิดพลาดใดที่เลื่อน fallback

Continues on
Does not continue on

ความล้มเหลวของการยืนยันตัวตน
ขีดจำกัดอัตราและการใช้คูลดาวน์จนหมด
ข้อผิดพลาดโอเวอร์โหลด/ผู้ให้บริการไม่ว่าง
ข้อผิดพลาดเฟลโอเวอร์ที่มีลักษณะเหมือนการหมดเวลา
การปิดใช้งานการเรียกเก็บเงิน
LiveSessionModelSwitchError ซึ่งถูกปรับให้อยู่ในเส้นทางเฟลโอเวอร์ เพื่อไม่ให้โมเดลที่คงอยู่เก่าแล้วสร้างลูปลองใหม่ชั้นนอก
ข้อผิดพลาดอื่นที่ไม่รู้จักเมื่อยังมี candidate เหลืออยู่

การยกเลิกอย่างชัดเจนที่ไม่ได้มีลักษณะเหมือนการหมดเวลา/เฟลโอเวอร์
ข้อผิดพลาด context overflow ที่ควรอยู่ภายในตรรกะ compaction/ลองใหม่ (เช่น request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model หรือ ollama error: context length exceeded)
ข้อผิดพลาดไม่รู้จักขั้นสุดท้ายเมื่อไม่มี candidate เหลืออยู่

พฤติกรรมการข้ามคูลดาวน์เทียบกับการ probe

เมื่อโปรไฟล์ยืนยันตัวตนทุกโปรไฟล์สำหรับผู้ให้บริการอยู่ในคูลดาวน์แล้ว OpenClaw จะไม่ข้ามผู้ให้บริการนั้นตลอดไปโดยอัตโนมัติ แต่จะตัดสินใจแยกตาม candidate:

Per-candidate decisions

ความล้มเหลวของการยืนยันตัวตนแบบคงอยู่จะข้ามผู้ให้บริการทั้งหมดทันที
การปิดใช้งานการเรียกเก็บเงินมักถูกข้าม แต่ candidate หลักยังสามารถถูก probe ตามการ throttle เพื่อให้กู้คืนได้โดยไม่ต้องรีสตาร์ต
candidate หลักอาจถูก probe ใกล้เวลาหมดอายุคูลดาวน์ โดยมีการ throttle แยกตามผู้ให้บริการ
fallback sibling ภายในผู้ให้บริการเดียวกันสามารถถูกลองได้แม้อยู่ในคูลดาวน์ เมื่อความล้มเหลวดูเป็นแบบชั่วคราว (rate_limit, overloaded หรือไม่รู้จัก) สิ่งนี้สำคัญเป็นพิเศษเมื่อขีดจำกัดอัตราผูกกับขอบเขตโมเดล และโมเดล sibling อาจยังฟื้นตัวได้ทันที
probe คูลดาวน์แบบชั่วคราวถูกจำกัดไว้ที่หนึ่งครั้งต่อผู้ให้บริการต่อการรัน fallback เพื่อไม่ให้ผู้ให้บริการรายเดียวทำให้ fallback ข้ามผู้ให้บริการหยุดชะงัก

การ override เซสชันและการสลับโมเดลสด

การเปลี่ยนโมเดลของเซสชันเป็นสถานะร่วม ตัวรันที่ใช้งานอยู่, คำสั่ง /model, การอัปเดต compaction/เซสชัน และการปรับสถานะเซสชันสดให้ตรงกัน ล้วนอ่านหรือเขียนบางส่วนของรายการเซสชันเดียวกัน นั่นหมายความว่าการลองใหม่ด้วย fallback ต้องประสานกับการสลับโมเดลสด:

เฉพาะการเปลี่ยนโมเดลที่ผู้ใช้ขับเคลื่อนอย่างชัดเจนเท่านั้นที่จะทำเครื่องหมายการสลับสดที่รอดำเนินการ ซึ่งรวมถึง /model, session_status(model=...) และ sessions.patch
การเปลี่ยนโมเดลที่ระบบขับเคลื่อน เช่น การหมุนเวียน fallback, การ override heartbeat หรือ compaction จะไม่ทำเครื่องหมายการสลับสดที่รอดำเนินการด้วยตัวเอง
การ override โมเดลที่ผู้ใช้ขับเคลื่อนถือเป็นการเลือกที่เจาะจงสำหรับนโยบาย fallback ดังนั้นผู้ให้บริการที่เลือกไว้แต่เข้าถึงไม่ได้จะแสดงเป็นความล้มเหลว แทนที่จะถูกปิดบังด้วย agents.defaults.model.fallbacks
ก่อนที่การลองใหม่ด้วย fallback จะเริ่ม ตัวรันคำตอบจะคงค่าฟิลด์ fallback override ที่เลือกไว้ลงในรายการเซสชัน
การ override fallback อัตโนมัติจะยังถูกเลือกไว้ในเทิร์นถัดไป เพื่อให้ OpenClaw ไม่ probe ค่าหลักที่ทราบว่าเสียในทุกข้อความ /new, /reset และ sessions.reset จะล้าง override ที่มาจากอัตโนมัติและพาเซสชันกลับไปยังค่าเริ่มต้นที่กำหนดค่าไว้
/status แสดงโมเดลที่เลือก และเมื่อสถานะ fallback แตกต่างกัน จะแสดงโมเดล fallback ที่ใช้งานอยู่พร้อมเหตุผล
การปรับสถานะเซสชันสดให้ตรงกันจะให้ความสำคัญกับ override เซสชันที่คงอยู่มากกว่าฟิลด์โมเดลรันไทม์ที่เก่าแล้ว
หากข้อผิดพลาดการสลับสดชี้ไปยัง candidate ถัดไปในสาย fallback ที่ใช้งานอยู่ OpenClaw จะกระโดดไปยังโมเดลที่เลือกนั้นโดยตรง แทนที่จะเดินผ่าน candidate ที่ไม่เกี่ยวข้องก่อน
หากการลอง fallback ล้มเหลว ตัวรันจะย้อนกลับเฉพาะฟิลด์ override ที่ตัวเองเขียน และเฉพาะเมื่อฟิลด์เหล่านั้นยังตรงกับ candidate ที่ล้มเหลวนั้น

สิ่งนี้ป้องกัน race แบบคลาสสิก:

Primary fails

โมเดลหลักที่เลือกไว้ล้มเหลว

Fallback chosen in memory

candidate fallback ถูกเลือกในหน่วยความจำ

Session store still says old primary

ที่เก็บเซสชันยังคงสะท้อนค่าหลักเดิม

Live reconciliation reads stale state

การปรับสถานะเซสชันสดให้ตรงกันอ่านสถานะเซสชันที่เก่าแล้ว

Retry snapped back

การลองใหม่ถูกดึงกลับไปยังโมเดลเดิมก่อนที่การลอง fallback จะเริ่ม

fallback override ที่คงอยู่จะปิดหน้าต่างนั้น และการย้อนกลับแบบแคบจะรักษาการเปลี่ยนเซสชันแบบแมนนวลหรือรันไทม์ที่ใหม่กว่าไว้ครบถ้วน

การสังเกตการณ์และสรุปความล้มเหลว

runWithModelFallback(...) บันทึกรายละเอียดรายความพยายามที่ป้อนเข้าสู่ล็อกและข้อความคูลดาวน์ที่แสดงต่อผู้ใช้:

ผู้ให้บริการ/โมเดลที่ลอง
เหตุผล (rate_limit, overloaded, billing, auth, model_not_found และเหตุผลเฟลโอเวอร์ที่คล้ายกัน)
สถานะ/โค้ดที่เป็นทางเลือก
สรุปข้อผิดพลาดที่มนุษย์อ่านได้

ล็อก model_fallback_decision แบบมีโครงสร้างยังรวมฟิลด์ fallbackStep* แบบแบน เมื่อ candidate ล้มเหลว ถูกข้าม หรือ fallback ถัดไปสำเร็จ ฟิลด์เหล่านี้ทำให้การเปลี่ยนผ่านที่ลองชัดเจน (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) เพื่อให้ตัวส่งออกล็อกและการวินิจฉัยสามารถสร้างความล้มเหลวของค่าหลักขึ้นใหม่ได้ แม้ fallback ปลายทางจะล้มเหลวด้วยก็ตาม เมื่อ candidate ทุกตัวล้มเหลว OpenClaw จะโยน FallbackSummaryError ตัวรันคำตอบชั้นนอกสามารถใช้สิ่งนั้นเพื่อสร้างข้อความที่เฉพาะเจาะจงขึ้น เช่น “โมเดลทั้งหมดถูกจำกัดอัตราชั่วคราว” และรวมเวลาหมดอายุคูลดาวน์ที่เร็วที่สุดเมื่อทราบ สรุปคูลดาวน์นั้นรับรู้ตามโมเดล:

ขีดจำกัดอัตราที่ผูกกับขอบเขตโมเดลซึ่งไม่เกี่ยวข้องจะถูกละเว้นสำหรับสายผู้ให้บริการ/โมเดลที่ลอง
หากบล็อกที่เหลือเป็นขีดจำกัดอัตราที่ผูกกับขอบเขตโมเดลซึ่งตรงกัน OpenClaw จะรายงานเวลาหมดอายุล่าสุดที่ตรงกันและยังคงบล็อกโมเดลนั้น

การกำหนดค่าที่เกี่ยวข้อง

ดู การกำหนดค่า Gateway สำหรับ:

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

ดู โมเดล สำหรับภาพรวมการเลือกโมเดลและ fallback ที่กว้างขึ้น

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

การสลับไปใช้โมเดลสำรอง

โฟลว์รันไทม์

นโยบายแหล่งที่มาของการเลือก

ที่เก็บการยืนยันตัวตน (คีย์ + OAuth)

ID โปรไฟล์

ลำดับการหมุนเวียน

การยึดติดกับเซสชัน (เป็นมิตรกับแคช)

การสมัครใช้งาน OpenAI Codex พร้อม API-key สำรอง

คูลดาวน์

การปิดใช้งานจาก billing

fallback โมเดล

กฎของสาย candidate

ข้อผิดพลาดใดที่เลื่อน fallback

พฤติกรรมการข้ามคูลดาวน์เทียบกับการ probe

การ override เซสชันและการสลับโมเดลสด

การสังเกตการณ์และสรุปความล้มเหลว

การกำหนดค่าที่เกี่ยวข้อง

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​โฟลว์รันไทม์

​นโยบายแหล่งที่มาของการเลือก

​ที่เก็บการยืนยันตัวตน (คีย์ + OAuth)

​ID โปรไฟล์

​ลำดับการหมุนเวียน

​การยึดติดกับเซสชัน (เป็นมิตรกับแคช)

​การสมัครใช้งาน OpenAI Codex พร้อม API-key สำรอง

​คูลดาวน์

​การปิดใช้งานจาก billing

​fallback โมเดล

​กฎของสาย candidate

​ข้อผิดพลาดใดที่เลื่อน fallback

​พฤติกรรมการข้ามคูลดาวน์เทียบกับการ probe

​การ override เซสชันและการสลับโมเดลสด

​การสังเกตการณ์และสรุปความล้มเหลว

​การกำหนดค่าที่เกี่ยวข้อง

โฟลว์รันไทม์

นโยบายแหล่งที่มาของการเลือก

ที่เก็บการยืนยันตัวตน (คีย์ + OAuth)

ID โปรไฟล์

ลำดับการหมุนเวียน

การยึดติดกับเซสชัน (เป็นมิตรกับแคช)

การสมัครใช้งาน OpenAI Codex พร้อม API-key สำรอง

คูลดาวน์

การปิดใช้งานจาก billing

fallback โมเดล

กฎของสาย candidate

ข้อผิดพลาดใดที่เลื่อน fallback

พฤติกรรมการข้ามคูลดาวน์เทียบกับการ probe

การ override เซสชันและการสลับโมเดลสด

การสังเกตการณ์และสรุปความล้มเหลว

การกำหนดค่าที่เกี่ยวข้อง