---
read_when:
    - การวินิจฉัยพฤติกรรมการหมุนเวียนโปรไฟล์การยืนยันตัวตน ช่วงพักการใช้งาน หรือการใช้โมเดลสำรอง
    - การอัปเดตกฎการสลับไปใช้ระบบสำรองสำหรับโปรไฟล์การยืนยันตัวตนหรือโมเดล
    - ทำความเข้าใจว่าการแทนที่โมเดลของเซสชันมีปฏิสัมพันธ์กับการลองใหม่โดยใช้โมเดลสำรองอย่างไร
sidebarTitle: Model failover
summary: วิธีที่ OpenClaw หมุนเวียนโปรไฟล์การยืนยันตัวตนและสลับไปใช้โมเดลสำรอง
title: การสลับโมเดลเมื่อขัดข้อง
x-i18n:
    generated_at: "2026-07-20T05:53:54Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: e520ed160969b57bd50c2ed647ff7c0e60ec19ab983db226241b6301dafb503d
    source_path: concepts/model-failover.md
    workflow: 16
---

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

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

## ลำดับการทำงานขณะรันไทม์

<Steps>
  <Step title="ระบุสถานะเซสชัน">
    ระบุโมเดลของเซสชันที่ใช้งานอยู่และการกำหนดค่าโปรไฟล์การยืนยันตัวตนที่ต้องการ
  </Step>
  <Step title="สร้างลำดับตัวเลือก">
    สร้างลำดับโมเดลตัวเลือกจากการเลือกโมเดลปัจจุบันและนโยบายสำรองของแหล่งที่มาของการเลือกนั้น ค่าเริ่มต้นที่กำหนดไว้ โมเดลหลักของงาน cron และโมเดลสำรองที่เลือกโดยอัตโนมัติสามารถใช้โมเดลสำรองที่กำหนดไว้ได้ ส่วนการเลือกเซสชันโดยผู้ใช้อย่างชัดเจนจะใช้แบบเคร่งครัด
  </Step>
  <Step title="ลองใช้ผู้ให้บริการปัจจุบัน">
    ลองใช้ผู้ให้บริการปัจจุบันตามกฎการหมุนเวียน/คูลดาวน์ของโปรไฟล์การยืนยันตัวตน
  </Step>
  <Step title="เลื่อนไปยังตัวเลือกถัดไปเมื่อเกิดข้อผิดพลาดที่ควรทำ failover">
    หากลองผู้ให้บริการนั้นจนครบแล้วและเกิดข้อผิดพลาดที่ควรทำ failover ให้ไปยังโมเดลตัวเลือกถัดไป
  </Step>
  <Step title="ใช้ตัวเลือกสำรองสำหรับรอบปัจจุบัน">
    เรียกใช้ตัวเลือกสำรองที่สำเร็จโดยไม่เปลี่ยนผู้ให้บริการ/โมเดลที่เลือกไว้ของเซสชัน
  </Step>
  <Step title="ลองใหม่เมื่อทุกตัวเลือกล้มเหลวจากภาระงานล้นเพียงอย่างเดียวอย่างปลอดภัย">
    หากทุกตัวเลือกล้มเหลวเพียงเพราะผู้ให้บริการมีภาระงานล้น ให้ลองลำดับภายในรอบทั้งหมดใหม่ได้สูงสุด 10 ครั้งด้วยการหน่วงเวลาแบบทวีคูณ ตราบใดที่ยังไม่มีการเรียกใช้เครื่องมือหรือเริ่มส่งเอาต์พุตของผู้ช่วย หลังจาก 30 วินาที ให้ส่งการแจ้งสถานะหนึ่งครั้งเพื่อไม่ให้ผู้ใช้รอโดยไม่มีข้อมูล
  </Step>
  <Step title="ส่ง FallbackSummaryError หากลองครบทุกตัวเลือกแล้ว">
    หากทุกตัวเลือกล้มเหลว ให้ส่ง `FallbackSummaryError` พร้อมรายละเอียดของแต่ละครั้งที่ลองและเวลาสิ้นสุดคูลดาวน์ที่เร็วที่สุดเมื่อทราบ
  </Step>
</Steps>

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

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

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

- **ค่าเริ่มต้นที่กำหนดไว้**: `agents.defaults.model.primary` ใช้ `agents.defaults.model.fallbacks`
- **โมเดลหลักของเอเจนต์**: `agents.list[].model` จะทำงานแบบเคร่งครัด เว้นแต่ออบเจ็กต์โมเดลของเอเจนต์นั้นจะมี `fallbacks` ของตนเอง ใช้ `fallbacks: []` เพื่อระบุพฤติกรรมแบบเคร่งครัดอย่างชัดเจน หรือใช้รายการที่ไม่ว่างเพื่ออนุญาตให้เอเจนต์นั้นใช้โมเดลสำรอง
- **ตัวเลือกสำรองขณะรันไทม์**: ตัวเลือกสำรองมีผลเฉพาะรอบปัจจุบัน รอบถัดไปจะเริ่มจากโมเดลหลักที่เลือกไว้อีกครั้ง OpenClaw ยังคงรู้จักรายการ `modelOverrideSource: "auto"` ที่บันทึกไว้ก่อนหน้านี้ ตรวจสอบต้นทางที่กำหนดไว้ทุก 5 นาที และล้างรายการเหล่านั้นเมื่อต้นทางกลับมาทำงานได้ `/new`, `/reset` และ `sessions.reset` จะล้างรายการเหล่านั้นด้วย
- **การแทนที่โดยเซสชันผู้ใช้**: `/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`

เลือกเปิดใช้การระงับความล้มเหลวของการยืนยันตัวตนซ้ำด้วย:

```bash
OPENCLAW_FALLBACK_SKIP_TTL_MS=60000
```

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

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

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

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

```text
↪️ ตัวเลือกสำรองของโมเดล: <fallback> (เลือกไว้ <primary>; <reason>)
```

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

```text
↪️ ล้างตัวเลือกสำรองของโมเดลแล้ว: <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](/th/concepts/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 จะเลือกลำดับดังนี้:

<Steps>
  <Step title="การกำหนดค่าที่ระบุไว้อย่างชัดเจน">
    `auth.order[provider]` (หากกำหนดไว้)
  </Step>
  <Step title="โปรไฟล์ที่กำหนดไว้">
    `auth.profiles` ที่กรองตามผู้ให้บริการ
  </Step>
  <Step title="โปรไฟล์ที่จัดเก็บไว้">
    รายการโปรไฟล์การยืนยันตัวตนใน SQLite ของแต่ละเอเจนต์สำหรับผู้ให้บริการ
  </Step>
</Steps>

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

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

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

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

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

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

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

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

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

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

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

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

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

## คูลดาวน์

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

<AccordionGroup>
  <Accordion title="รายการที่จัดอยู่ในกลุ่มขีดจำกัดอัตรา / การหมดเวลา">
    กลุ่มขีดจำกัดอัตรานั้นครอบคลุมมากกว่า `429` เพียงอย่างเดียว โดยยังรวมถึงข้อความจากผู้ให้บริการ เช่น `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` และขีดจำกัดช่วงเวลาการใช้งานเป็นระยะ เช่น `weekly limit reached` หรือ `monthly limit exhausted`

    ข้อผิดพลาดด้านรูปแบบ/คำขอไม่ถูกต้องมักถือเป็นข้อผิดพลาดที่ยุติการทำงาน เพราะการลองเพย์โหลดเดิมซ้ำจะล้มเหลวในลักษณะเดิม ดังนั้น OpenClaw จะแสดงข้อผิดพลาดเหล่านั้นแทนการหมุนเวียนโปรไฟล์การยืนยันตัวตน เส้นทางการซ่อมแซมและลองใหม่ที่รู้จักสามารถเลือกเปิดใช้ได้อย่างชัดเจน ตัวอย่างเช่น ความล้มเหลวในการตรวจสอบรหัสการเรียกใช้เครื่องมือของ Cloud Code Assist จะถูกปรับให้อยู่ในรูปแบบที่ปลอดภัยและลองใหม่หนึ่งครั้งผ่านนโยบาย `allowFormatRetry` ข้อผิดพลาดเหตุผลการหยุดที่เข้ากันได้กับ OpenAI เช่น `Unhandled stop reason: error`, `stop reason: error` และ `reason: error` จะถูกจัดประเภทเป็นสัญญาณการหมดเวลา/failover

    ข้อความทั่วไปจากเซิร์ฟเวอร์อาจอยู่ในกลุ่มการหมดเวลานั้นด้วยเมื่อแหล่งที่มาตรงกับรูปแบบชั่วคราวที่รู้จัก ตัวอย่างเช่น ข้อความตัวครอบสตรีมของรันไทม์โมเดลแบบไม่มีรายละเอียด `An unknown error occurred` จะถูกถือว่าควรทำ failover สำหรับผู้ให้บริการทุกราย เนื่องจากรันไทม์โมเดลที่ใช้ร่วมกันจะส่งข้อความนี้เมื่อสตรีมของผู้ให้บริการสิ้นสุดด้วย `stopReason: "aborted"` หรือ `stopReason: "error"` โดยไม่มีรายละเอียดเฉพาะ เพย์โหลด JSON `api_error` ที่มีข้อความเซิร์ฟเวอร์ชั่วคราว เช่น `internal server error`, `unknown error, 520`, `upstream error` หรือ `backend error` จะถูกถือว่าเป็นการหมดเวลาที่ควรทำ failover เช่นกัน

    ข้อความต้นทางทั่วไปที่เฉพาะเจาะจงกับ OpenRouter เช่น `Provider returned error` แบบไม่มีรายละเอียด จะถูกถือเป็นการหมดเวลาเฉพาะเมื่อบริบทของผู้ให้บริการเป็น OpenRouter จริงเท่านั้น ข้อความตัวเลือกสำรองภายในทั่วไป เช่น `LLM request failed with an unknown error.` จะยังคงใช้การพิจารณาอย่างระมัดระวังและไม่เรียกใช้ failover ด้วยตัวเอง

  </Accordion>
  <Accordion title="ขีดจำกัด retry-after ของ SDK">
    มิฉะนั้น SDK ของผู้ให้บริการบางรายอาจพักรอเป็นช่วงเวลา `Retry-After` ที่ยาวนานก่อนคืนการควบคุมให้ OpenClaw สำหรับ SDK ที่พัฒนาบน Stainless เช่น Anthropic และ OpenAI โดยค่าเริ่มต้น OpenClaw จะจำกัดการรอ `retry-after-ms` / `retry-after` ภายใน SDK ไว้ที่ 60 วินาที และส่งต่อการตอบกลับที่ลองใหม่ได้ซึ่งใช้เวลานานกว่านั้นทันที เพื่อให้เส้นทางการสลับเมื่อขัดข้องนี้ทำงานได้ ปรับหรือปิดขีดจำกัดด้วย `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; ดู[พฤติกรรมการลองใหม่](/th/concepts/retry)
  </Accordion>
  <Accordion title="ช่วงพักการใช้งานที่จำกัดขอบเขตตามโมเดล">
    ช่วงพักการใช้งานจากการจำกัดอัตราสามารถจำกัดขอบเขตตามโมเดลได้เช่นกัน:

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

  </Accordion>
</AccordionGroup>

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

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

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

สถานะจัดเก็บอยู่ในสถานะการตรวจสอบสิทธิ์ SQLite ของแต่ละเอเจนต์ภายใต้ `usageStats`:

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

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

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

<Note>
การตอบกลับที่มีลักษณะเกี่ยวกับการเรียกเก็บเงินไม่ได้เป็น `402` ทุกครั้ง และ HTTP `402` ก็ไม่ได้เข้ามายังเส้นทางนี้ทุกครั้ง OpenClaw จะคงข้อความเกี่ยวกับการเรียกเก็บเงินที่ชัดเจนไว้ในเส้นทางการเรียกเก็บเงิน แม้ผู้ให้บริการจะส่งคืน `401` หรือ `403` แทน แต่ตัวจับคู่เฉพาะผู้ให้บริการยังคงจำกัดขอบเขตไว้กับผู้ให้บริการที่เป็นเจ้าของ (เช่น OpenRouter `403 Key limit exceeded`)

ขณะเดียวกัน ข้อผิดพลาดชั่วคราวเกี่ยวกับช่วงการใช้งาน `402` และขีดจำกัดค่าใช้จ่ายขององค์กร/พื้นที่ทำงาน จะถูกจำแนกเป็น `rate_limit` เมื่อข้อความมีลักษณะว่าสามารถลองใหม่ได้ (เช่น `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` หรือ `organization spending limit exceeded`) ข้อผิดพลาดเหล่านี้จะยังอยู่ในเส้นทางช่วงพักการใช้งานสั้น/การสลับเมื่อขัดข้อง แทนที่จะเข้าสู่เส้นทางปิดใช้งานระยะยาวเนื่องจากการเรียกเก็บเงิน
</Note>

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

สถานะจัดเก็บอยู่ในสถานะการตรวจสอบสิทธิ์ SQLite ของแต่ละเอเจนต์:

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

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

## โมเดลสำรอง

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

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

หากเชนตัวเลือกทั้งหมดหมดลงเพราะความล้มเหลวจากภาระงานเกินเท่านั้น ตัวประมวลผลการตอบกลับจะลองเชนใหม่สูงสุด 10 ครั้งภายในเทิร์นเดียวกัน อนุญาตให้ลองใหม่ทั้งเทิร์นได้เฉพาะก่อนเริ่มการเรียกใช้เครื่องมือหรือการส่งเอาต์พุตของผู้ช่วย เพื่อหลีกเลี่ยงการเปลี่ยนแปลงหรือข้อความซ้ำ หากเกิดภาระงานเกินหลังจากมีงานที่สังเกตเห็นได้แล้ว ระยะถอยกลับเริ่มที่ 2.5 วินาทีและเพิ่มเป็นสองเท่าจนถึงขีดสูงสุด 30 วินาที เมื่อเทิร์นรอครบ 30 วินาที OpenClaw จะส่งการแจ้งเตือนสถานะชั่วคราวหนึ่งครั้ง: `The AI service is temporarily overloaded. I’m still retrying; this may take a few minutes.` การลองใหม่และโมเดลสำรองที่สำเร็จจะมีผลเฉพาะในเทิร์น ส่วนข้อผิดพลาดชั่วคราวทั่วไปของเซิร์ฟเวอร์ยังคงใช้นโยบายลองใหม่หนึ่งครั้งแยกต่างหาก

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

### กฎของเชนตัวเลือก

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

<AccordionGroup>
  <Accordion title="กฎ">
    - โมเดลที่ร้องขอจะอยู่ลำดับแรกเสมอ
    - โมเดลสำรองที่กำหนดค่าไว้อย่างชัดเจนจะถูกตัดรายการซ้ำ แต่ไม่ถูกกรองด้วยรายการโมเดลที่อนุญาต โดยถือเป็นเจตนาอย่างชัดเจนของผู้ปฏิบัติงาน
    - หากการทำงานปัจจุบันอยู่บนโมเดลสำรองที่กำหนดค่าไว้ในตระกูลผู้ให้บริการเดียวกันอยู่แล้ว OpenClaw จะใช้เชนที่กำหนดค่าไว้ทั้งหมดต่อไป
    - เมื่อไม่ได้ระบุค่าทดแทนโมเดลสำรองอย่างชัดเจน ระบบจะลองโมเดลสำรองที่กำหนดค่าไว้ก่อนโมเดลหลักที่กำหนดค่าไว้ แม้โมเดลที่ร้องขอจะใช้ผู้ให้บริการรายอื่น
    - เมื่อไม่ได้ระบุค่าทดแทนโมเดลสำรองอย่างชัดเจนให้ตัวประมวลผลโมเดลสำรอง ระบบจะต่อท้ายโมเดลหลักที่กำหนดค่าไว้ เพื่อให้เชนกลับไปใช้ค่าเริ่มต้นปกติได้เมื่อใช้ตัวเลือกก่อนหน้าจนหมด
    - เมื่อผู้เรียกระบุ `fallbacksOverride` ตัวประมวลผลจะใช้เฉพาะโมเดลที่ร้องขอรวมกับรายการค่าทดแทนนั้น รายการว่างจะปิดใช้งานโมเดลสำรองและป้องกันไม่ให้ต่อท้ายโมเดลหลักที่กำหนดค่าไว้เป็นเป้าหมายลับสำหรับการลองใหม่

  </Accordion>
</AccordionGroup>

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

<Tabs>
  <Tab title="ดำเนินการต่อเมื่อ">
    - การตรวจสอบสิทธิ์ล้มเหลว
    - การจำกัดอัตราและการใช้ช่วงพักการใช้งานจนหมด
    - ข้อผิดพลาดจากภาระงานเกิน/ผู้ให้บริการไม่ว่าง
    - ข้อผิดพลาดการสลับเมื่อขัดข้องที่มีลักษณะเป็นการหมดเวลา
    - การปิดใช้งานเนื่องจากการเรียกเก็บเงิน
    - `LiveSessionModelSwitchError` ซึ่งถูกปรับให้อยู่ในเส้นทางการสลับเมื่อขัดข้อง เพื่อป้องกันไม่ให้โมเดลที่จัดเก็บไว้และล้าสมัยสร้างลูปการลองใหม่ชั้นนอก
    - ข้อผิดพลาดอื่นที่ไม่รู้จักเมื่อยังมีตัวเลือกเหลืออยู่

  </Tab>
  <Tab title="ไม่ดำเนินการต่อเมื่อ">
    - การยกเลิกอย่างชัดเจนที่ไม่มีลักษณะเป็นการหมดเวลา/การสลับเมื่อขัดข้อง
    - ข้อผิดพลาดจากบริบทล้นที่ควรอยู่ภายในตรรกะ Compaction/การลองใหม่ (เช่น `request_too_large`, `input token count exceeds the maximum number of input tokens`, `input exceeds the maximum number of tokens`, `input too long for the model` หรือ `ollama error: context length exceeded`)
    - ข้อผิดพลาดสุดท้ายที่ไม่รู้จักเมื่อไม่มีตัวเลือกเหลืออยู่
    - การปฏิเสธด้านความปลอดภัยของ Claude Fable 5; คำขอที่ใช้คีย์ API โดยตรงจะจัดการกรณีดังกล่าวในระดับผู้ให้บริการผ่านโมเดลสำรองฝั่งเซิร์ฟเวอร์ของ Anthropic ไปยัง `claude-opus-4-8` แทน (ดู [Anthropic](/th/providers/anthropic#safety-refusal-fallback-claude-fable-5))

  </Tab>
</Tabs>

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

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

<AccordionGroup>
  <Accordion title="การตัดสินใจแยกตามตัวเลือก">
    - ความล้มเหลวของการตรวจสอบสิทธิ์แบบถาวรจะข้ามผู้ให้บริการทั้งรายทันที
    - โดยทั่วไปการปิดใช้งานเนื่องจากการเรียกเก็บเงินจะถูกข้าม แต่ยังคงตรวจสอบตัวเลือกหลักตามการควบคุมความถี่ได้ เพื่อให้กู้คืนได้โดยไม่ต้องเริ่มระบบใหม่
    - อาจตรวจสอบตัวเลือกหลักเมื่อใกล้สิ้นสุดช่วงพักการใช้งาน โดยมีการควบคุมความถี่แยกตามผู้ให้บริการ
    - สามารถลองโมเดลสำรองพี่น้องจากผู้ให้บริการเดียวกันได้แม้อยู่ในช่วงพักการใช้งาน เมื่อความล้มเหลวมีลักษณะชั่วคราว (`rate_limit`, `overloaded` หรือไม่ทราบสาเหตุ) เรื่องนี้สำคัญเป็นพิเศษเมื่อการจำกัดอัตราจำกัดขอบเขตตามโมเดล และโมเดลพี่น้องอาจกู้คืนได้ทันที
    - การตรวจสอบช่วงพักการใช้งานชั่วคราวจำกัดไว้ที่หนึ่งครั้งต่อผู้ให้บริการต่อการทำงานของโมเดลสำรอง เพื่อไม่ให้ผู้ให้บริการรายเดียวทำให้การสลับข้ามผู้ให้บริการหยุดชะงัก

  </Accordion>
</AccordionGroup>

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

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

การสลับโมเดลแบบสดเป็นไปตามกฎเหล่านี้:

- เฉพาะการเปลี่ยนโมเดลที่ผู้ใช้ดำเนินการอย่างชัดเจนเท่านั้นที่จะทำเครื่องหมายการสลับแบบสดที่รอดำเนินการ ซึ่งรวมถึง `/model`, `session_status(model=...)` และ `sessions.patch`
- การเปลี่ยนโมเดลที่ระบบดำเนินการ เช่น การหมุนโมเดลสำรอง ค่าทดแทน Heartbeat หรือ Compaction จะไม่ทำเครื่องหมายการสลับแบบสดที่รอดำเนินการด้วยตัวเอง
- ค่าทดแทนโมเดลที่ผู้ใช้กำหนดถือเป็นการเลือกที่แน่นอนสำหรับนโยบายโมเดลสำรอง ดังนั้นผู้ให้บริการที่เลือกซึ่งไม่สามารถเข้าถึงได้จะแสดงเป็นความล้มเหลว แทนที่จะถูกปกปิดด้วย `agents.defaults.model.fallbacks`
- ตัวเลือกโมเดลสำรองขณะรันยังคงมีผลเฉพาะในเทิร์น เทิร์นถัดไปจะเริ่มจากโมเดลที่เลือกอยู่ในปัจจุบัน รวมถึงการเลือกด้วยตนเองที่เข้ามาระหว่างการทำงานก่อนหน้า
- ค่าทดแทนโมเดลสำรองอัตโนมัติที่จัดเก็บไว้ก่อนหน้านี้ยังคงรองรับ: 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](/th/gateway/configuration)สำหรับ:

- `auth.profiles` / `auth.order`
- `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel` การกำหนดเส้นทาง

ดู[โมเดล](/th/concepts/models)สำหรับภาพรวมที่ครอบคลุมยิ่งขึ้นเกี่ยวกับการเลือกโมเดลและการใช้ตัวเลือกสำรอง