การสลับโมเดลเมื่อเกิดข้อผิดพลาด

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

1. การหมุนเวียนโปรไฟล์การตรวจสอบสิทธิ์ ภายในผู้ให้บริการปัจจุบัน
2. การสลับไปใช้โมเดลสำรอง ไปยังโมเดลถัดไปใน agents.defaults.model.fallbacks

ลำดับการทำงานขณะรัน

ขอบเขตนี้จงใจแคบกว่าแนวทาง “บันทึกและคืนค่าทั้งเซสชัน” ตัวรันการตอบกลับจะบันทึกเฉพาะฟิลด์การเลือกโมเดลที่ตนเป็นเจ้าของสำหรับการใช้โมเดลสำรอง ได้แก่ providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount วิธีนี้ป้องกันไม่ให้การลองใช้โมเดลสำรองที่ล้มเหลวเขียนทับการเปลี่ยนแปลงอื่นในเซสชันที่ใหม่กว่าและไม่เกี่ยวข้อง เช่น การเปลี่ยน /model ด้วยตนเองหรือการอัปเดตการหมุนเวียนเซสชันที่เกิดขึ้นระหว่างการลอง

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

แหล่งที่มาของการเลือกเป็นตัวกำหนดว่าอนุญาตให้ใช้ลำดับโมเดลสำรองหรือไม่:

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

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

แคชข้ามความล้มเหลวในการตรวจสอบสิทธิ์

ตามค่าเริ่มต้น การโต้ตอบใหม่แต่ละครั้งจะคงพฤติกรรมการลองใช้โมเดลสำรองเดิมไว้ โดย OpenClaw จะลองตัวเลือกโมเดลสำรองที่กำหนดไว้แต่ละรายการอีกครั้ง รวมถึงตัวเลือกที่ไม่ใช่โมเดลหลักซึ่งเพิ่งล้มเหลวด้วย auth หรือ auth_permanent

เปิดใช้การระงับความล้มเหลวในการตรวจสอบสิทธิ์ซ้ำด้วย:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

ค่านี้เป็น TTL หน่วยมิลลิวินาที ค่า 0 หรือการไม่กำหนดค่าจะปิดใช้แคช ค่าบวกจะถูกจำกัดให้อยู่ระหว่าง 1 วินาทีถึง 10 นาที

การแจ้งเตือนการใช้โมเดลสำรองที่ผู้ใช้มองเห็น

เมื่อเซสชันย้ายไปใช้โมเดลสำรองที่เลือกโดยอัตโนมัติ OpenClaw จะส่งการแจ้งเตือนสถานะในช่องทางการตอบกลับเดียวกัน:

↪️ การสลับไปใช้โมเดลสำรอง: <fallback> (เลือกไว้ <primary>; <reason>)

เมื่อการตรวจสอบในภายหลังสำเร็จและเซสชันกลับไปใช้โมเดลหลักที่เลือกไว้ OpenClaw จะส่ง:

↪️ ยกเลิกการสลับไปใช้โมเดลสำรองแล้ว: <primary> (ก่อนหน้านี้ใช้ <fallback>)

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

ที่เก็บข้อมูลการตรวจสอบสิทธิ์ (คีย์และ OAuth)

OpenClaw ใช้ โปรไฟล์การตรวจสอบสิทธิ์ สำหรับทั้งคีย์ API และโทเค็น OAuth

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

รายละเอียดเพิ่มเติม: OAuth

ประเภทข้อมูลรับรอง:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl สำหรับผู้ให้บริการบางราย)
• type: "token" → โทเค็นแบบ bearer คงที่ซึ่งอาจกำหนดวันหมดอายุได้ OpenClaw จะไม่รีเฟรชโทเค็นนี้ (ใช้สำหรับ aws-sdk และโหมดการตรวจสอบสิทธิ์ผ่านลำดับข้อมูลรับรองอื่น ๆ)

รหัสโปรไฟล์

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

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

โปรไฟล์อยู่ในที่เก็บโปรไฟล์การตรวจสอบสิทธิ์ openclaw-agent.sqlite ของแต่ละเอเจนต์

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

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

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

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

การยึดโปรไฟล์ประจำเซสชัน (เป็นมิตรกับแคช)

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

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

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

การสมัครใช้บริการ OpenAI Codex พร้อมคีย์ API สำรอง

สำหรับโมเดลเอเจนต์ OpenAI การตรวจสอบสิทธิ์และรันไทม์แยกจากกัน openai/gpt-* จะยังคงทำงานบนระบบ Codex ขณะที่การตรวจสอบสิทธิ์สามารถหมุนเวียนระหว่างโปรไฟล์การสมัครใช้บริการ Codex และคีย์ API สำรองของ OpenAI ได้

ใช้ auth.order.openai สำหรับลำดับที่ผู้ใช้มองเห็น:

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

ใช้ openai:* สำหรับทั้งโปรไฟล์ OAuth ของ ChatGPT/Codex และโปรไฟล์คีย์ API ของ OpenAI เมื่อการสมัครใช้บริการถึงขีดจำกัดการใช้งาน Codex OpenClaw จะบันทึกเวลารีเซ็ตที่แน่นอนเมื่อ Codex ระบุไว้ ลองใช้โปรไฟล์การตรวจสอบสิทธิ์ถัดไปตามลำดับ และคงการทำงานไว้ภายในระบบ Codex เมื่อพ้นเวลารีเซ็ตแล้ว โปรไฟล์การสมัครใช้บริการจะมีสิทธิ์ใช้งานอีกครั้ง และการเลือกอัตโนมัติครั้งถัดไปสามารถกลับไปใช้โปรไฟล์นั้นได้

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

ช่วงพัก

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

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

• ล้มเหลวครั้งที่ 1: 30 วินาที
• ล้มเหลวครั้งที่ 2: 1 นาที
• ล้มเหลวครั้งที่ 3 ขึ้นไป: 5 นาที (ขีดสูงสุด)

ตัวนับจะรีเซ็ตเมื่อพ้นช่วงเวลาความล้มเหลวของโปรไฟล์ (auth.cooldowns.failureWindowHours ค่าเริ่มต้นคือ 24)

สถานะถูกจัดเก็บในสถานะการยืนยันตัวตน SQLite ประจำเอเจนต์ภายใต้ usageStats:

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

การปิดใช้งานเนื่องจากการเรียกเก็บเงิน

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

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

สถานะถูกจัดเก็บในสถานะการยืนยันตัวตน SQLite ประจำเอเจนต์:

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

ค่าเริ่มต้น (auth.cooldowns.*):

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

โมเดลสำรอง

หากโปรไฟล์ทั้งหมดของผู้ให้บริการล้มเหลว OpenClaw จะย้ายไปยังโมเดลถัดไปใน agents.defaults.model.fallbacks พฤติกรรมนี้ใช้กับความล้มเหลวด้านการยืนยันตัวตน การจำกัดอัตรา และการหมดเวลาที่ใช้การหมุนโปรไฟล์จนหมดแล้ว (ข้อผิดพลาดประเภทอื่นจะไม่เลื่อนไปยังโมเดลสำรอง) ข้อผิดพลาดจากผู้ให้บริการที่ไม่แสดงรายละเอียดเพียงพอยังคงถูกติดป้ายอย่างแม่นยำในสถานะโมเดลสำรอง: empty_response หมายถึงผู้ให้บริการไม่ได้ส่งคืนข้อความหรือสถานะที่ใช้งานได้ no_error_details หมายถึงผู้ให้บริการส่งคืน Unknown error (no error details in response) อย่างชัดเจน และ unclassified หมายถึง OpenClaw เก็บตัวอย่างข้อมูลดิบไว้ แต่ยังไม่มีตัวจำแนกใดตรงกับข้อผิดพลาดนั้น

สัญญาณว่าผู้ให้บริการไม่ว่าง เช่น ModelNotReadyException จะถูกจัดไว้ในกลุ่มโหลดเกิน และใช้นโยบายหมุนหนึ่งครั้งแล้วใช้โมเดลสำรองเช่นเดียวกับการจำกัดอัตรา (ดูตารางค่าเริ่มต้นด้านบน)

เมื่อการทำงานเริ่มจากโมเดลหลักค่าเริ่มต้นที่กำหนดค่าไว้ โมเดลหลักของงาน Cron โมเดลหลักของเอเจนต์ที่มีโมเดลสำรองระบุไว้อย่างชัดเจน หรือการแทนที่โมเดลสำรองที่เลือกโดยอัตโนมัติ OpenClaw สามารถไล่ตามลำดับโมเดลสำรองที่กำหนดค่าไว้ซึ่งตรงกันได้ โมเดลหลักของเอเจนต์ที่ไม่มีโมเดลสำรองระบุไว้อย่างชัดเจนและการเลือกโดยผู้ใช้อย่างชัดเจน (เช่น /model ollama/qwen3.5:27b ตัวเลือกโมเดล sessions.patch หรือการแทนที่ผู้ให้บริการ/โมเดลแบบครั้งเดียวผ่าน CLI) จะใช้กฎแบบเข้มงวด: หากไม่สามารถเข้าถึงผู้ให้บริการ/โมเดลนั้น หรือเกิดความล้มเหลวก่อนสร้างคำตอบ OpenClaw จะรายงานความล้มเหลวแทนที่จะตอบจากโมเดลสำรองที่ไม่เกี่ยวข้อง

กฎของลำดับตัวเลือก

OpenClaw สร้างรายการตัวเลือกจาก provider/model ที่ร้องขอในขณะนั้นร่วมกับโมเดลสำรองที่กำหนดค่าไว้

ข้อผิดพลาดใดบ้างที่เลื่อนไปยังโมเดลสำรอง

พฤติกรรมการข้ามช่วงพักเทียบกับการตรวจสอบ

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

การแทนที่ของเซสชันและการสลับโมเดลขณะทำงาน

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

ดังนั้น การลองโมเดลสำรองใหม่จึงต้องประสานงานกับการสลับโมเดลขณะทำงาน:

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

วิธีนี้ป้องกันสภาวะแข่งขันแบบคลาสสิก:

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

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

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

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

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

เมื่อผู้สมัครทุกรายล้มเหลว OpenClaw จะโยน FallbackSummaryError ตัวดำเนินการตอบกลับชั้นนอกสามารถใช้ข้อผิดพลาดนี้เพื่อสร้างข้อความที่เฉพาะเจาะจงยิ่งขึ้น เช่น "ขณะนี้โมเดลทั้งหมดถูกจำกัดอัตราการใช้งานชั่วคราว" และระบุเวลาสิ้นสุดช่วงพักที่เร็วที่สุด หากทราบ

สรุปช่วงพักดังกล่าวจะคำนึงถึงโมเดล:

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

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

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

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• การกำหนดเส้นทาง agents.defaults.imageModel

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