# Усунення несправностей

🌐 **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_*` у відповідності зі значеннями на стороні сервера

### Cloud `stream=false` Повертає 500

**Симптом:** `Unexpected token 'd'...` на хмарній кінцевій точці для непотокових викликів.

**Причина:** Upstream повертає корисне навантаження SSE, тоді як клієнт очікує JSON.

**Рішення:** використовуйте `stream=true` для прямих дзвінків із хмари. Місцеве середовище виконання включає SSE→JSON.

### Хмара повідомляє, що підключено, але "недійсний ключ API"

1. Створіть новий ключ із локальної інформаційної панелі (`/api/keys`)
2. Запустіть хмарну синхронізацію: увімкніть Cloud → Синхронізувати зараз
3. Старі/несинхронізовані ключі все ще можуть повертати `401` у хмарі

---

## Проблеми Docker

### Інструмент 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. Використовуйте безкоштовний рівень (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`
- Переконайтеся, що постачальник підключено в **Інформаційна панель → Постачальники**

### Транскрипція повертається порожньою або не вдається

- Перевірте підтримувані аудіоформати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
- Переконайтеся, що розмір файлу відповідає обмеженням постачальника (зазвичай < 25 МБ)
- Перевірте дійсність ключа 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 с)
- **Множник** — скільки збільшити затримку на послідовну помилку (за замовчуванням: 2x)

### Протигромове стадо

Коли багато одночасних запитів надходять до постачальника з обмеженою швидкістю, OmniRoute використовує м’ютекс + автоматичне обмеження швидкості для серіалізації запитів і запобігання каскадним помилкам. Це відбувається автоматично для постачальників ключів API.

---

## Все ще застрягли?

- **Проблеми GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **Архітектура**: див. [link](ARCHITECTURE.md) для внутрішніх деталей
- **API Reference**: див. [link](API_REFERENCE.md) для всіх кінцевих точок
- **Інформаційна панель справності**: перевірте **Інформаційна панель → Здоров’я**, щоб дізнатися про стан системи в реальному часі
- **Перекладач**: використовуйте **Інформаційна панель → Перекладач** для усунення проблем із форматом
