# Отстраняване на неизправности

🌐 **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 схема за постоянство на настройките) |

---

## Проблеми с доставчика

### „Езиковият модел не предостави съобщения“

**Причина:** Квотата на доставчика е изчерпана.

**Коригиране:**

1. Проверете инструмента за проследяване на квоти на таблото за управление
2. Използвайте комбо с резервни нива
3. Преминете към по-евтино/безплатно ниво

### Ограничаване на скоростта

**Причина:** Абонаментната квота е изчерпана.

**Коригиране:**

- Добавете резервен вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
- Използвайте GLM/MiniMax като евтино резервно копие

### OAuth Token е изтекъл

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. Стартирайте облачна синхронизация: Активирайте Облак → Синхронизирай сега
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`
- Уверете се, че размерът на файла е в границите на доставчика (обикновено < 25MB)
- Проверете валидността на API ключа на доставчика в картата на доставчика

---

## Отстраняване на грешки на преводача

Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с превода на формат:

| Режим               | Кога да използвате                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| **Детска площадка** | Сравнете входно/изходните формати един до друг — поставете неуспешна заявка, за да видите как се превежда |
| **Чат тестер**      | Изпращайте съобщения на живо и проверявайте пълния полезен товар на заявка/отговор, включително заглавки  |
| **Тестова стенда**  | Изпълнете пакетни тестове в комбинации от формати, за да откриете кои преводи са нарушени                 |
| **Монитор на живо** | Гледайте потока на заявките в реално време, за да уловите периодични проблеми с превода                   |

### Често срещани проблеми с формата

- **Мислещите етикети не се появяват** — Проверете дали целевият доставчик поддържа мисленето и настройката на бюджета за мислене
- **Отпадане на извикванията на инструменти** — Някои преводи на формати може да премахнат неподдържаните полета; потвърдете в режим Playground
- **Липсва системна подкана** — Клод и Джемини обработват системните подкани по различен начин; проверка на резултата за превод
- **SDK връща необработен низ вместо обект** — Коригирано във v1.1.0: дезинфекциращото средство за отговор вече премахва нестандартните полета (`x_groq`, `usage_breakdown` и т.н.), които причиняват неуспешно валидиране на OpenAI SDK Pydantic
- **GLM/ERNIE отхвърля `system` роля** — Коригирано във v1.1.0: нормализаторът на роли автоматично обединява системни съобщения в потребителски съобщения за несъвместими модели
- **`developer` ролята не е разпозната** — Коригирано във v1.1.0: автоматично преобразувано в `system` за доставчици, които не са OpenAI
- **`json_schema` не работи с Gemini** — Коригирано във v1.1.0: `response_format` сега се преобразува в `responseMimeType` + `responseSchema` на Gemini

---

## Настройки за устойчивост

### Автоматичното ограничение на скоростта не се задейства

- Автоматичното ограничение на скоростта се прилага само за доставчици на API ключове (не OAuth/абонамент)
- Уверете се, че **Настройки → Устойчивост → Профили на доставчици** има активиран автоматичен лимит на скоростта
- Проверете дали доставчикът връща `429` кодове за състояние или `Retry-After` заглавки

### Настройване на експоненциално забавяне

Профилите на доставчика поддържат тези настройки:

- **Базово забавяне** — Първоначално време на изчакване след първата повреда (по подразбиране: 1s)
- **Максимално забавяне** — Максимално ограничение на времето за изчакване (по подразбиране: 30 секунди)
- **Множител** — Колко да се увеличи закъснението за последователен отказ (по подразбиране: 2x)

### Анти-гръмотевично стадо

Когато много едновременни заявки попаднат на доставчик с ограничена скорост, OmniRoute използва mutex + автоматично ограничаване на скоростта, за да сериализира заявките и да предотврати каскадни грешки. Това е автоматично за доставчиците на API ключове.

---

## Все още сте заседнали?

- **Проблеми с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **Архитектура**: Вижте [link](ARCHITECTURE.md) за вътрешни подробности
- **API Reference**: Вижте [link](API_REFERENCE.md) за всички крайни точки
- **Табло за управление на здравето**: Проверете **Табло за управление → Здраве** за състоянието на системата в реално време
- **Преводач**: Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с формата
