# การแก้ไขปัญหา

🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)

ปัญหาและวิธีแก้ปัญหาทั่วไปสำหรับ OmniRoute

---

## แก้ไขด่วน

| ปัญหา                           | โซลูชั่น                                                               |
| ------------------------------- | ---------------------------------------------------------------------- |
| การเข้าสู่ระบบครั้งแรกไม่ทำงาน  | ทำเครื่องหมาย `INITIAL_PASSWORD` ใน `.env` (ค่าเริ่มต้น: `123456`)     |
| แดชบอร์ดเปิดบนพอร์ตผิด          | ตั้งค่า `PORT=20128` และ `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
| ไม่มีบันทึกคำขอภายใต้ `logs/`   | ตั้งค่า `ENABLE_REQUEST_LOGS=true`                                     |
| EACCES: การอนุญาตถูกปฏิเสธ      | ตั้งค่า `DATA_DIR=/path/to/writable/dir` เพื่อแทนที่ `~/.omniroute`    |
| กลยุทธ์การกำหนดเส้นทางไม่บันทึก | อัปเดตเป็น v1.4.11+ (แก้ไข Zod schema สำหรับการคงอยู่ของการตั้งค่า)    |

---

## ปัญหาของผู้ให้บริการ

### "โมเดลภาษาไม่ได้ให้ข้อความ"

**สาเหตุ:** โควต้าของผู้ให้บริการหมดลง

**แก้ไข:**

1. ตรวจสอบตัวติดตามโควต้าแดชบอร์ด
2. ใช้คอมโบที่มีระดับทางเลือก
3. เปลี่ยนไปใช้ระดับที่ถูกกว่า/ฟรี

### การจำกัดอัตรา

**สาเหตุ:** โควต้าการสมัครใช้งานหมดลง

**แก้ไข:**

- เพิ่มทางเลือก: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
- ใช้ GLM/MiniMax เป็นข้อมูลสำรองราคาถูก

### โทเค็น OAuth หมดอายุแล้ว

OmniRoute รีเฟรชโทเค็นอัตโนมัติ หากปัญหายังคงอยู่:

1. แดชบอร์ด → ผู้ให้บริการ → เชื่อมต่อใหม่
2. ลบและเพิ่มการเชื่อมต่อผู้ให้บริการอีกครั้ง

---

## ปัญหาคลาวด์

### ข้อผิดพลาดการซิงค์คลาวด์

1. ตรวจสอบ `BASE_URL` ชี้ไปยังอินสแตนซ์ที่ทำงานอยู่ของคุณ (เช่น `http://localhost:20128`)
2. ตรวจสอบ `CLOUD_URL` ชี้ไปยังจุดสิ้นสุดระบบคลาวด์ของคุณ (เช่น `https://omniroute.dev`)
3. เก็บค่า `NEXT_PUBLIC_*` ให้สอดคล้องกับค่าฝั่งเซิร์ฟเวอร์

### คลาวด์ `stream=false` ส่งคืน 500

**อาการ:** `Unexpected token 'd'...` บนจุดปลายทางคลาวด์สำหรับการโทรที่ไม่ใช่การสตรีม

**สาเหตุ:** อัปสตรีมส่งคืนเพย์โหลด SSE ในขณะที่ไคลเอ็นต์คาดหวัง JSON

**วิธีแก้ปัญหา:** ใช้ `stream=true` สำหรับการโทรโดยตรงบนคลาวด์ รันไทม์ในเครื่องรวมถึงทางเลือก SSE → JSON

### Cloud บอกว่าเชื่อมต่อแล้ว แต่ "คีย์ API ไม่ถูกต้อง"

1. สร้างคีย์ใหม่จากแดชบอร์ดในเครื่อง (`/api/keys`)
2. เรียกใช้คลาวด์ซิงค์: เปิดใช้งานคลาวด์ → ซิงค์ทันที
3. คีย์เก่า/ที่ไม่ได้ซิงค์ยังสามารถส่งคืน `401` บนคลาวด์ได้

---

## ปัญหานักเทียบท่า

### เครื่องมือ CLI แสดงว่าไม่ได้ติดตั้ง

1. ตรวจสอบฟิลด์รันไทม์: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
2. สำหรับโหมดพกพา: ใช้เป้าหมายรูปภาพ `runner-cli` (CLI ที่รวมกลุ่ม)
3. สำหรับโหมดเมาต์โฮสต์: ตั้งค่า `CLI_EXTRA_PATHS` และเมาต์ไดเร็กทอรี bin โฮสต์เป็นแบบอ่านอย่างเดียว
4. หาก `installed=true` และ `runnable=false`: พบไบนารีแต่ตรวจสุขภาพไม่สำเร็จ

### การตรวจสอบรันไทม์ด่วน

```bash
curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
```

---

## ปัญหาต้นทุน

### ต้นทุนสูง

1. ตรวจสอบสถิติการใช้งานในแดชบอร์ด → การใช้งาน
2. สลับโมเดลหลักเป็น GLM/MiniMax
3. ใช้ Free Tier (Gemini CLI, iFlow) สำหรับงานที่ไม่สำคัญ
4. กำหนดงบประมาณต้นทุนต่อคีย์ API: แดชบอร์ด → คีย์ API → งบประมาณ

---

## การดีบัก

### เปิดใช้งานบันทึกคำขอ

ตั้งค่า `ENABLE_REQUEST_LOGS=true` ในไฟล์ `.env` ของคุณ บันทึกจะปรากฏภายใต้ไดเรกทอรี `logs/`

### ตรวจสอบสุขภาพของผู้ให้บริการ

```bash
# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health
```

### พื้นที่เก็บข้อมูลรันไทม์

- สถานะหลัก: `${DATA_DIR}/db.json` (ผู้ให้บริการ คอมโบ นามแฝง คีย์ การตั้งค่า)
- การใช้งาน: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
- บันทึกคำขอ: `<repo>/logs/...` (เมื่อ `ENABLE_REQUEST_LOGS=true`)

---

## ปัญหาเซอร์กิตเบรกเกอร์

### ผู้ให้บริการติดอยู่ในสถานะเปิด

เมื่อเซอร์กิตเบรกเกอร์ของผู้ให้บริการเปิดอยู่ คำขอจะถูกบล็อกจนกว่าคูลดาวน์จะหมดลง

**แก้ไข:**

1. ไปที่ **แดชบอร์ด → การตั้งค่า → ความยืดหยุ่น**
2. ตรวจสอบการ์ดเซอร์กิตเบรกเกอร์สำหรับผู้ให้บริการที่ได้รับผลกระทบ
3. คลิก **รีเซ็ตทั้งหมด** เพื่อล้างเบรกเกอร์ทั้งหมด หรือรอให้คูลดาวน์หมดลง
4. ตรวจสอบว่าผู้ให้บริการพร้อมใช้งานจริงก่อนที่จะรีเซ็ต

### ผู้ให้บริการสะดุดเบรกเกอร์อย่างต่อเนื่อง

หากผู้ให้บริการเข้าสู่สถานะเปิดซ้ำๆ:

1. ตรวจสอบ **แดชบอร์ด → สุขภาพ → สุขภาพของผู้ให้บริการ** เพื่อดูรูปแบบความล้มเหลว
2. ไปที่ **การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ** และเพิ่มเกณฑ์ความล้มเหลว
3. ตรวจสอบว่าผู้ให้บริการได้เปลี่ยนแปลงขีดจำกัด API หรือต้องมีการตรวจสอบสิทธิ์อีกครั้งหรือไม่
4. ตรวจสอบการวัดและส่งข้อมูลทางไกลเวลาแฝง — เวลาแฝงสูงอาจทำให้เกิดความล้มเหลวตามการหมดเวลา

---

## ปัญหาการถอดเสียง

### ข้อผิดพลาด "รุ่นที่ไม่รองรับ"

- ตรวจสอบให้แน่ใจว่าคุณใช้คำนำหน้าที่ถูกต้อง: `deepgram/nova-3` หรือ `assemblyai/best`
- ตรวจสอบว่าผู้ให้บริการเชื่อมต่ออยู่ใน **Dashboard → Providers**

### การถอดเสียงกลับว่างเปล่าหรือล้มเหลว

- ตรวจสอบรูปแบบเสียงที่รองรับ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
- ตรวจสอบขนาดไฟล์อยู่ภายในขีดจำกัดของผู้ให้บริการ (โดยทั่วไปคือ <25MB)
- ตรวจสอบความถูกต้องของคีย์ API ของผู้ให้บริการในการ์ดผู้ให้บริการ

---

## การแก้ไขจุดบกพร่องของนักแปล

ใช้ **แดชบอร์ด → ตัวแปล** เพื่อแก้ไขปัญหาการแปลรูปแบบ:

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

### ปัญหารูปแบบทั่วไป

- **แท็กการคิดไม่ปรากฏ** — ตรวจสอบว่าผู้ให้บริการเป้าหมายสนับสนุนการคิดและการตั้งค่างบประมาณการคิดหรือไม่
- **การเรียกเครื่องมือลดลง** — การแปลรูปแบบบางรูปแบบอาจตัดช่องที่ไม่รองรับออก ตรวจสอบในโหมดสนามเด็กเล่น
- **การแจ้งเตือนของระบบหายไป** — ระบบแจ้งของ Claude และ Gemini แตกต่างกัน ตรวจสอบผลลัพธ์การแปล
- **SDK ส่งคืนสตริงดิบแทนที่จะเป็นวัตถุ** — แก้ไขในเวอร์ชัน 1.1.0: ตอนนี้ตัวล้างการตอบสนองจะตัดฟิลด์ที่ไม่ได้มาตรฐาน (`x_groq`, `usage_breakdown` ฯลฯ) ที่ทำให้การตรวจสอบ OpenAI SDK Pydantic ล้มเหลว
- **GLM/ERNIE ปฏิเสธบทบาท `system`** — แก้ไขในเวอร์ชัน 1.1.0: บทบาท Normalizer จะรวมข้อความระบบเข้ากับข้อความผู้ใช้โดยอัตโนมัติสำหรับรุ่นที่เข้ากันไม่ได้
- **`developer` ไม่รู้จักบทบาท** — แก้ไขใน v1.1.0: แปลงเป็น `system` โดยอัตโนมัติสำหรับผู้ให้บริการที่ไม่ใช่ OpenAI
- **`json_schema` ไม่ทำงานกับ Gemini** — แก้ไขใน v1.1.0: `response_format` ตอนนี้ถูกแปลงเป็น `responseMimeType` + `responseSchema` ของ Gemini แล้ว

---

## การตั้งค่าความยืดหยุ่น

### ขีดจำกัดอัตราอัตโนมัติไม่ทริกเกอร์

- การจำกัดอัตราอัตโนมัติใช้กับผู้ให้บริการคีย์ API เท่านั้น (ไม่ใช่ OAuth/การสมัครสมาชิก)
- ตรวจสอบ **การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ** ได้เปิดใช้งานการจำกัดอัตราอัตโนมัติแล้ว
- ตรวจสอบว่าผู้ให้บริการส่งคืนรหัสสถานะ `429` หรือส่วนหัว `Retry-After` หรือไม่

### การปรับแต่งการถอยกลับแบบเอ็กซ์โปเนนเชียล

โปรไฟล์ผู้ให้บริการรองรับการตั้งค่าเหล่านี้:

- **ความล่าช้าพื้นฐาน** — เวลารอเริ่มต้นหลังจากความล้มเหลวครั้งแรก (ค่าเริ่มต้น: 1 วินาที)
- **ความล่าช้าสูงสุด** — ขีดจำกัดเวลารอสูงสุด (ค่าเริ่มต้น: 30 วินาที)
- **ตัวคูณ** — จะต้องเพิ่มความล่าช้าเท่าใดต่อความล้มเหลวติดต่อกัน (ค่าเริ่มต้น: 2x)

### ฝูงต่อต้านฟ้าร้อง

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

---

## ยังติดอยู่เหรอ?

- **ปัญหา GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **สถาปัตยกรรม**: ดู [link](ARCHITECTURE.md) สำหรับรายละเอียดภายใน
- **การอ้างอิง API**: ดู [link](API_REFERENCE.md) สำหรับจุดสิ้นสุดทั้งหมด
- **แดชบอร์ดสุขภาพ**: ตรวจสอบ **แดชบอร์ด → สุขภาพ** เพื่อดูสถานะของระบบแบบเรียลไทม์
- **นักแปล**: ใช้ **แดชบอร์ด → นักแปล** เพื่อแก้ไขปัญหาเกี่ยวกับรูปแบบ
