# פתרון בעיות

🌐 **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` |
| אסטרטגיית ניתוב לא שומרת       | עדכון לגרסה 1.4.11+ (תיקון סכמת Zod עבור התמדה בהגדרות)          |

---

## בעיות עם ספקים

### "מודל השפה לא סיפק הודעות"

**סיבה:** מיצתה מכסת הספקים.

**תיקון:**

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'...` בנקודת קצה בענן עבור שיחות שאינן זורמות.

**סיבה:** Upstream מחזיר מטען SSE בזמן שהלקוח מצפה ל-JSON.

**פתרון לעקיפת הבעיה:** השתמש ב-`stream=true` לשיחות ישירות בענן. זמן ריצה מקומי כולל SSE → JSON fallback.

### ענן אומר מחובר אבל "מפתח 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` ואת ספריית סל המארח כקריאה בלבד
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. השתמש בשכבה חינמית (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`)

---

## בעיות מפסקים

### הספק תקוע במצב OPEN

כאשר מפסק החשמל של ספק פתוח, הבקשות נחסמות עד לפקיעת הקירור.

**תיקון:**

1. עבור אל **לוח מחוונים ← הגדרות ← חוסן**
2. בדוק את כרטיס המפסק עבור הספק המושפע
3. לחץ על **אפס הכל** כדי לנקות את כל המפסקים, או המתן עד שתוקף הקירור יפוג
4. ודא שהספק אכן זמין לפני האיפוס

### הספק ממשיך להדליק את המפסק

אם ספק נכנס שוב ושוב למצב OPEN:

1. סמן את **לוח המחוונים ← תקינות ← תקינות הספק** עבור דפוס הכשל
2. עבור אל **הגדרות ← חוסן ← פרופילי ספקים** והגדל את סף הכשל
3. בדוק אם הספק שינה מגבלות API או שהוא דורש אימות מחדש
4. סקירת טלמטריית חביון - זמן אחזור גבוה עלול לגרום לכשלים מבוססי זמן קצוב

---

## בעיות בתמלול אודיו

### שגיאה "מודל לא נתמך".

- ודא שאתה משתמש בקידומת הנכונה: `deepgram/nova-3` או `assemblyai/best`
- ודא שהספק מחובר ב-**לוח מחוונים → ספקים**

### התמלול מחזיר ריק או נכשל

- בדוק פורמטי שמע נתמכים: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
- ודא שגודל הקובץ נמצא בגבולות הספק (בדרך כלל < 25MB)
- בדוק את תוקף מפתח ה-API של ספק בכרטיס הספק

---

## ניפוי באגים של מתרגם

השתמש ב**לוח המחוונים ← מתרגם** כדי לנפות באגים בבעיות תרגום בפורמט:

| מצב             | מתי להשתמש                                                                     |
| --------------- | ------------------------------------------------------------------------------ |
| **מגרש משחקים** | השווה פורמטים של קלט/פלט זה לצד זה - הדבק בקשה נכשלת כדי לראות איך היא מתורגמת |
| **בודק צ'אט**   | שלח הודעות חיות ובדוק את מטען הבקשה/תגובה המלא כולל כותרות                     |
| **ספסל מבחן**   | הפעל בדיקות אצווה על פני שילובי פורמטים כדי למצוא אילו תרגומים מקולקלים        |
| **שידור חי**    | צפה בזרם הבקשות בזמן אמת כדי לתפוס בעיות תרגום לסירוגין                        |

### בעיות פורמט נפוצות

- **תגי חשיבה לא מופיעים** — בדוק אם ספק היעד תומך בחשיבה ובהגדרת תקציב החשיבה
- **הורדת שיחות הכלים** - תרגומי פורמט מסוימים עשויים להסיר שדות שאינם נתמכים; לאמת במצב Playground
- **הנחיית מערכת חסרה** - קלוד וג'מיני מטפלים בהנחיות המערכת בצורה שונה; בדוק את פלט התרגום
- **SDK מחזיר מחרוזת גולמית במקום אובייקט** - תוקן בגרסה 1.1.0: ניקוי התגובה מסיר כעת שדות לא סטנדרטיים (`x_groq`, `usage_breakdown` וכו') שגורמים לכשלי אימות של OpenAI SDK Pydantic
- **GLM/ERNIE דוחה תפקיד `system`** - תוקן בגרסה 1.1.0: מנרמל תפקידים ממזג אוטומטית הודעות מערכת להודעות משתמש עבור דגמים לא תואמים
- **`developer` תפקיד לא מזוהה** - תוקן בגרסה 1.1.0: הומר אוטומטית ל`system` עבור ספקים שאינם OpenAI
- **`json_schema` לא עובד עם Gemini** - תוקן בגרסה 1.1.0: `response_format` הומר כעת ל-`responseMimeType` + `responseSchema` של Gemini

---

## הגדרות חוסן

### מגבלת שיעור אוטומטי לא מופעלת

- הגבלת תעריף אוטומטי חלה רק על ספקי מפתח API (לא OAuth/מינוי)
- ודא של **הגדרות ← חוסן ← פרופילי ספקים** מופעלת הגבלת תעריף אוטומטי
- בדוק אם הספק מחזיר `429` קודי סטטוס או כותרות `Retry-After`

### כוונון גיבוי אקספוננציאלי

פרופילי ספקים תומכים בהגדרות הבאות:

- **השהיית בסיס** - זמן המתנה ראשוני לאחר הכשל הראשון (ברירת מחדל: 1 שניות)
- **עיכוב מרבי** - מכסת זמן המתנה מקסימלית (ברירת מחדל: 30 שניות)
- **מכפיל** - כמה להגדיל את העיכוב לכל כשל רצוף (ברירת מחדל: פי 2)

### עדר נגד רעמים

כאשר בקשות בו-זמניות רבות פוגעות בספק מוגבל בקצב, OmniRoute משתמשת ב-mutex + הגבלת קצב אוטומטית כדי להדגיש בקשות ולמנוע כשלים מדורגים. זה אוטומטי עבור ספקי מפתחות API.

---

## עדיין תקוע?

- **בעיות GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **אדריכלות**: ראה [link](ARCHITECTURE.md) לפרטים פנימיים
- **הפניה ל-API**: ראה [link](API_REFERENCE.md) עבור כל נקודות הקצה
- **לוח מחוונים לבריאות**: בדוק את **לוח מחוונים ← בריאות** למצב מערכת בזמן אמת
- **מתרגם**: השתמש ב-**לוח מחוונים ← מתרגם** כדי לנפות באגים בפורמט
