chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
01088d8536
commit
0cefc3536d
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Діагностика ротації профілів автентифікації, періодів охолодження або поведінки резервного перемикання моделей
|
||||
- Оновлення правил резервного перемикання для профілів автентифікації або моделей
|
||||
- Розуміння того, як перевизначення моделей сеансу взаємодіють із повторними спробами резервного перемикання
|
||||
- Діагностика ротації auth profiles, cooldown-періодів або поведінки резервного переходу між моделями
|
||||
- Оновлення правил резервного переходу для auth profiles або моделей
|
||||
- Розуміння того, як перевизначення моделі сеансу взаємодіють із повторними спробами резервного переходу
|
||||
sidebarTitle: Model failover
|
||||
summary: Як OpenClaw ротує профілі автентифікації та виконує резервне перемикання між моделями
|
||||
title: Резервне перемикання моделей
|
||||
summary: Як OpenClaw змінює auth profiles по черзі та виконує резервний перехід між моделями
|
||||
title: Резервний перехід між моделями
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T08:25:08Z"
|
||||
generated_at: "2026-04-27T08:31:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b652e0bfb30aa698f0badbd341e615eb110254ca08abb1896189e95b0f9d4c61
|
||||
source_hash: 7b6fd539fddce6f7dfee9bf04076026b09fb1b84c5c170578bca9643e0105bd4
|
||||
source_path: concepts/model-failover.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw обробляє збої у два етапи:
|
||||
|
||||
1. **Ротація профілів автентифікації** в межах поточного провайдера.
|
||||
2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`.
|
||||
1. **Ротація auth profiles** у межах поточного провайдера.
|
||||
2. **Резервний перехід між моделями** до наступної моделі в `agents.defaults.model.fallbacks`.
|
||||
|
||||
У цьому документі пояснюються правила виконання під час роботи та дані, на яких вони базуються.
|
||||
Цей документ пояснює правила виконання під час роботи та дані, на яких вони базуються.
|
||||
|
||||
## Потік виконання
|
||||
|
||||
@ -28,45 +28,46 @@ OpenClaw обробляє збої у два етапи:
|
||||
|
||||
<Steps>
|
||||
<Step title="Визначення стану сеансу">
|
||||
Визначте активну модель сеансу та налаштування профілю автентифікації. Перевизначення сеансу з `modelOverrideSource: "auto"` походить із попереднього резервного перемикання, тому наступний запуск спочатку очищує його та знову пробує налаштовану основну модель; перевизначення, вибрані користувачем, залишаються закріпленими.
|
||||
Визначте активну модель сеансу та налаштування пріоритету auth-profile.
|
||||
</Step>
|
||||
<Step title="Побудова ланцюжка кандидатів">
|
||||
Побудуйте ланцюжок кандидатів моделей на основі поточної вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у заданому порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення.
|
||||
Побудуйте ланцюжок кандидатів моделей із поточної вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у вказаному порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення.
|
||||
</Step>
|
||||
<Step title="Спроба з поточним провайдером">
|
||||
Спробуйте поточного провайдера з правилами ротації/охолодження профілів автентифікації.
|
||||
Спробуйте поточного провайдера з правилами ротації/cooldown для auth-profile.
|
||||
</Step>
|
||||
<Step title="Перехід далі при помилках, що варті резервного перемикання">
|
||||
Якщо цей провайдер вичерпано через помилку, що варта резервного перемикання, перейдіть до наступного кандидата моделі.
|
||||
<Step title="Перехід далі на помилках, що допускають резервний перехід">
|
||||
Якщо ресурси цього провайдера вичерпано через помилку, що допускає резервний перехід, перейдіть до наступної моделі-кандидата.
|
||||
</Step>
|
||||
<Step title="Збереження перевизначення резервного перемикання">
|
||||
Збережіть вибране перевизначення резервного перемикання до початку повторної спроби, щоб інші читачі сеансу бачили того самого провайдера/модель, яких виконавець ось-ось використає. Збережене перевизначення моделі позначається як `modelOverrideSource: "auto"`.
|
||||
<Step title="Збереження перевизначення резервного переходу">
|
||||
Збережіть вибране перевизначення резервного переходу до початку повторної спроби, щоб інші читачі стану сеансу бачили того самого провайдера/модель, яких виконавець збирається використати. Збережене перевизначення моделі позначається як `modelOverrideSource: "auto"`.
|
||||
</Step>
|
||||
<Step title="Вузьке відкочування при збої">
|
||||
Якщо кандидат резервного перемикання не вдається, відкочуйте лише ті поля перевизначення сеансу, що належать резервному перемиканню, якщо вони все ще відповідають цьому невдалому кандидату.
|
||||
<Step title="Вузьке відкочування в разі збою">
|
||||
Якщо кандидат резервного переходу завершується з помилкою, відкочуйте лише поля перевизначення сеансу, що належать резервному переходу, якщо вони все ще відповідають цьому невдалому кандидату.
|
||||
</Step>
|
||||
<Step title="Викидання FallbackSummaryError, якщо кандидати вичерпано">
|
||||
Якщо всі кандидати завершилися невдачею, викиньте `FallbackSummaryError` із деталями по кожній спробі та найближчим часом завершення охолодження, якщо він відомий.
|
||||
<Step title="Викидання FallbackSummaryError, якщо варіанти вичерпано">
|
||||
Якщо кожен кандидат завершується помилкою, викиньте `FallbackSummaryError` із деталями по кожній спробі та найближчим моментом завершення cooldown, якщо він відомий.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Це навмисно вужче, ніж «зберегти та відновити весь сеанс». Виконавець відповіді зберігає лише поля вибору моделі, якими він керує для резервного перемикання:
|
||||
Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Виконавець відповіді зберігає лише поля вибору моделі, якими він володіє для резервного переходу:
|
||||
|
||||
- `providerOverride`
|
||||
- `modelOverride`
|
||||
- `modelOverrideSource`
|
||||
- `authProfileOverride`
|
||||
- `authProfileOverrideSource`
|
||||
- `authProfileOverrideCompactionCount`
|
||||
|
||||
Це запобігає ситуації, коли невдала повторна спроба резервного перемикання перезаписує новіші несуміжні зміни сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби.
|
||||
Це запобігає ситуації, коли невдала повторна спроба резервного переходу перезаписує новіші, не пов’язані із цим зміни сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби.
|
||||
|
||||
## Сховище автентифікації (ключі + OAuth)
|
||||
|
||||
OpenClaw використовує **профілі автентифікації** як для API-ключів, так і для OAuth-токенів.
|
||||
OpenClaw використовує **auth profiles** як для API-ключів, так і для OAuth-токенів.
|
||||
|
||||
- Секрети зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (застарілий шлях: `~/.openclaw/agent/auth-profiles.json`).
|
||||
- Стан маршрутизації автентифікації під час роботи зберігається в `~/.openclaw/agents/<agentId>/agent/auth-state.json`.
|
||||
- Конфігурації `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів).
|
||||
- Конфігурація `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів).
|
||||
- Застарілий файл OAuth лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання).
|
||||
|
||||
Докладніше: [OAuth](/uk/concepts/oauth)
|
||||
@ -78,16 +79,16 @@ OpenClaw використовує **профілі автентифікації*
|
||||
|
||||
## Ідентифікатори профілів
|
||||
|
||||
OAuth-входи створюють окремі профілі, щоб могли співіснувати кілька облікових записів.
|
||||
OAuth-входи створюють окремі профілі, щоб кілька облікових записів могли співіснувати.
|
||||
|
||||
- За замовчуванням: `provider:default`, якщо email недоступний.
|
||||
- OAuth з email: `provider:<email>` (наприклад, `google-antigravity:user@gmail.com`).
|
||||
|
||||
Профілі зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` у розділі `profiles`.
|
||||
Профілі зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` у секції `profiles`.
|
||||
|
||||
## Порядок ротації
|
||||
|
||||
Коли провайдер має кілька профілів, OpenClaw вибирає порядок так:
|
||||
Коли провайдер має кілька профілів, OpenClaw визначає порядок так:
|
||||
|
||||
<Steps>
|
||||
<Step title="Явна конфігурація">
|
||||
@ -97,73 +98,73 @@ OAuth-входи створюють окремі профілі, щоб могл
|
||||
`auth.profiles`, відфільтровані за провайдером.
|
||||
</Step>
|
||||
<Step title="Збережені профілі">
|
||||
Записи в `auth-profiles.json` для провайдера.
|
||||
Записи в `auth-profiles.json` для цього провайдера.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо явний порядок не налаштовано, OpenClaw використовує порядок round‑robin:
|
||||
Якщо явний порядок не налаштовано, OpenClaw використовує порядок round-robin:
|
||||
|
||||
- **Основний ключ:** тип профілю (**OAuth перед API-ключами**).
|
||||
- **Другорядний ключ:** `usageStats.lastUsed` (найстаріший спочатку в межах кожного типу).
|
||||
- **Профілі в охолодженні/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим часом завершення.
|
||||
- **Первинний ключ:** тип профілю (**OAuth перед API-ключами**).
|
||||
- **Вторинний ключ:** `usageStats.lastUsed` (найстаріші спочатку в межах кожного типу).
|
||||
- **Профілі в cooldown/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим завершенням строку.
|
||||
|
||||
### Закріплення сеансу (сприятливе для кешу)
|
||||
### Прив’язка до сеансу (дружньо до кешу)
|
||||
|
||||
OpenClaw **закріплює вибраний профіль автентифікації на рівні сеансу**, щоб кеші провайдера залишалися прогрітими. Він **не** виконує ротацію при кожному запиті. Закріплений профіль використовується повторно, доки:
|
||||
OpenClaw **закріплює вибраний auth profile за кожним сеансом**, щоб кеші провайдера залишалися «теплими». Він **не** виконує ротацію для кожного запиту. Закріплений профіль використовується повторно, доки:
|
||||
|
||||
- сеанс не буде скинуто (`/new` / `/reset`)
|
||||
- не завершиться Compaction (лічильник compaction збільшиться)
|
||||
- профіль не перейде в охолодження / не буде вимкнений
|
||||
- не завершиться Compaction (лічильник compaction збільшується)
|
||||
- профіль не перейде в cooldown/не буде вимкнений
|
||||
|
||||
Ручний вибір через `/model …@<profileId>` задає **перевизначення користувача** для цього сеансу й не ротуватиметься автоматично, доки не почнеться новий сеанс.
|
||||
Ручний вибір через `/model …@<profileId>` встановлює **користувацьке перевизначення** для цього сеансу і не ротуватиметься автоматично, доки не почнеться новий сеанс.
|
||||
|
||||
<Note>
|
||||
Автоматично закріплені профілі (вибрані маршрутизатором сеансу) розглядаються як **уподобання**: вони пробуються першими, але OpenClaw може переключитися на інший профіль у разі лімітів швидкості/тайм-аутів. Профілі, закріплені користувачем, залишаються зафіксованими на цьому профілі; якщо він не спрацьовує і налаштовано резервне перемикання моделей, OpenClaw переходить до наступної моделі замість зміни профілю.
|
||||
Автоматично закріплені профілі (вибрані маршрутизатором сеансу) вважаються **перевагою**: їх пробують першими, але OpenClaw може переключитися на інший профіль у разі rate limit/тайм-аутів. Профілі, закріплені користувачем, залишаються жорстко прив’язаними до цього профілю; якщо він завершується помилкою і налаштовано резервні переходи між моделями, OpenClaw переходить до наступної моделі замість перемикання профілів.
|
||||
</Note>
|
||||
|
||||
### Чому OAuth може «виглядати втраченим»
|
||||
|
||||
Якщо для одного й того самого провайдера у вас є і OAuth-профіль, і профіль API-ключа, round‑robin може перемикатися між ними між повідомленнями, якщо профіль не закріплено. Щоб примусово використовувати один профіль:
|
||||
Якщо для одного й того самого провайдера у вас є і OAuth-профіль, і профіль з API-ключем, round-robin може перемикатися між ними між повідомленнями, якщо профіль не закріплено. Щоб примусово використовувати один профіль:
|
||||
|
||||
- Закріпіть його через `auth.order[provider] = ["provider:profileId"]`, або
|
||||
- Використовуйте перевизначення для конкретного сеансу через `/model …` із перевизначенням профілю (де це підтримується вашим UI/поверхнею чату).
|
||||
- Використайте перевизначення для конкретного сеансу через `/model …` із перевизначенням профілю (коли це підтримується вашим інтерфейсом/UI або поверхнею чату).
|
||||
|
||||
## Періоди охолодження
|
||||
## Cooldown
|
||||
|
||||
Коли профіль завершується помилкою через автентифікацію/ліміти швидкості (або через тайм-аут, схожий на обмеження швидкості), OpenClaw позначає його як такий, що перебуває в охолодженні, і переходить до наступного профілю.
|
||||
Коли профіль завершується помилкою через збої автентифікації/rate limit (або тайм-аут, схожий на rate limiting), OpenClaw переводить його в cooldown і переходить до наступного профілю.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Що потрапляє до категорії лімітів швидкості / тайм-аутів">
|
||||
Ця категорія лімітів швидкості ширша за звичайний `429`: вона також включає повідомлення провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні обмеження в межах вікна використання, як-от `weekly/monthly limit reached`.
|
||||
<Accordion title="Що потрапляє до категорії rate limit / timeout">
|
||||
Категорія rate limit ширша, ніж просто `429`: вона також включає повідомлення провайдерів на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні ліміти вікна використання, як-от `weekly/monthly limit reached`.
|
||||
|
||||
Помилки формату/некоректного запиту (наприклад, помилки валідації ідентифікатора виклику інструмента Cloud Code Assist) вважаються такими, що варті резервного перемикання, і використовують ті самі періоди охолодження. Помилки stop-reason у стилі OpenAI-compatible, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали тайм-ауту/резервного перемикання.
|
||||
Помилки формату/некоректного запиту (наприклад, помилки валідації ідентифікатора виклику інструмента Cloud Code Assist) вважаються такими, що допускають резервний перехід, і використовують ті самі cooldown. Помилки OpenAI-compatible stop-reason, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали timeout/failover.
|
||||
|
||||
Загальний текст серверних помилок також може потрапляти до цієї категорії тайм-аутів, якщо джерело відповідає відомому тимчасовому шаблону. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається таким, що варте резервного перемикання, для кожного провайдера, оскільки pi-ai повертає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON-повідомлення `api_error` із тимчасовим серверним текстом, таким як `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також вважаються тайм-аутами, що варті резервного перемикання.
|
||||
Загальний серверний текст також може потрапити до цієї категорії timeout, якщо джерело відповідає відомому шаблону тимчасового збою. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається таким, що допускає резервний перехід, для всіх провайдерів, оскільки pi-ai видає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON-повідомлення `api_error` з тимчасовим серверним текстом, як-от `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також розглядаються як timeout, що допускають резервний перехід.
|
||||
|
||||
Загальний upstream-текст, специфічний для OpenRouter, як-от просте `Provider returned error`, вважається тайм-аутом лише тоді, коли контекст провайдера справді є OpenRouter. Загальний внутрішній текст резервного перемикання, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервне перемикання.
|
||||
Специфічний для OpenRouter загальний текст upstream-помилки на кшталт простого `Provider returned error` вважається timeout лише тоді, коли контекст провайдера справді OpenRouter. Загальний внутрішній текст резервного переходу, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервний перехід.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Обмеження retry-after у SDK">
|
||||
Деякі SDK провайдерів інакше можуть заснути на довге вікно `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на базі Stainless, як-от Anthropic і OpenAI, OpenClaw за замовчуванням обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і негайно повертає довші відповіді, придатні до повтору, щоб цей шлях резервного перемикання міг спрацювати. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry).
|
||||
<Accordion title="Обмеження Retry-After у SDK">
|
||||
Деякі SDK провайдерів інакше можуть чекати довге вікно `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на базі Stainless, як-от Anthropic і OpenAI, OpenClaw за замовчуванням обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і одразу повертає довші відповіді, які можна повторити, щоб цей шлях резервного переходу міг спрацювати. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry).
|
||||
</Accordion>
|
||||
<Accordion title="Періоди охолодження на рівні моделі">
|
||||
Періоди охолодження через ліміти швидкості також можуть бути прив’язані до моделі:
|
||||
<Accordion title="Cooldown із прив’язкою до моделі">
|
||||
Cooldown rate limit також можуть бути прив’язані до моделі:
|
||||
|
||||
- OpenClaw записує `cooldownModel` для збоїв через ліміти швидкості, коли ідентифікатор моделі, що завершилася помилкою, відомий.
|
||||
- Сусідню модель у того самого провайдера все ще можна спробувати, коли охолодження прив’язане до іншої моделі.
|
||||
- Вікна блокування через білінг/вимкнення все одно блокують увесь профіль для всіх моделей.
|
||||
- OpenClaw записує `cooldownModel` для помилок rate limit, коли ідентифікатор моделі, що завершилася помилкою, відомий.
|
||||
- Сусідню модель у того самого провайдера все ще можна спробувати, якщо cooldown прив’язаний до іншої моделі.
|
||||
- Вікна білінгу/вимкнення все одно блокують увесь профіль для всіх моделей.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Періоди охолодження використовують експоненційне збільшення затримки:
|
||||
Для cooldown використовується експоненційне збільшення інтервалу:
|
||||
|
||||
- 1 хвилина
|
||||
- 5 хвилин
|
||||
- 25 хвилин
|
||||
- 1 година (максимум)
|
||||
|
||||
Стан зберігається в `auth-state.json` у розділі `usageStats`:
|
||||
Стан зберігається в `auth-state.json` у `usageStats`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -179,12 +180,12 @@ OpenClaw **закріплює вибраний профіль автентифі
|
||||
|
||||
## Вимкнення через білінг
|
||||
|
||||
Збої через білінг/кредити (наприклад, «недостатньо кредитів» / «занадто низький кредитний баланс») вважаються такими, що варті резервного перемикання, але зазвичай вони не є тимчасовими. Замість короткого періоду охолодження OpenClaw позначає профіль як **вимкнений** (із довшим backoff) і переходить до наступного профілю/провайдера.
|
||||
Збої білінгу/кредитів (наприклад, «insufficient credits» / «credit balance too low») вважаються такими, що допускають резервний перехід, але зазвичай вони не є тимчасовими. Замість короткого cooldown OpenClaw позначає профіль як **disabled** (із довшим backoff) і переходить до наступного профілю/провайдера.
|
||||
|
||||
<Note>
|
||||
Не кожна відповідь, схожа на білінгову, є `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст, пов’язаний із білінгом, у білінговому сценарії навіть тоді, коли провайдер натомість повертає `401` або `403`, але matchers, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`).
|
||||
Не кожна відповідь, схожа на білінгову, має код `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст про білінг у категорії billing навіть тоді, коли провайдер натомість повертає `401` або `403`, але спеціалізовані матчери провайдера залишаються обмеженими тим провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`).
|
||||
|
||||
Тим часом тимчасові помилки `402`, пов’язані з вікном використання та лімітами витрат організації/робочого простору, класифікуються як `rate_limit`, коли повідомлення виглядає придатним до повтору (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого охолодження/резервного перемикання, а не довгого шляху вимкнення через білінг.
|
||||
Тим часом тимчасові помилки `402`, пов’язані з вікном використання, а також лімітами витрат організації/робочого простору, класифікуються як `rate_limit`, коли повідомлення виглядає як таке, що допускає повторну спробу (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого cooldown/резервного переходу замість шляху довгого вимкнення через білінг.
|
||||
</Note>
|
||||
|
||||
Стан зберігається в `auth-state.json`:
|
||||
@ -202,118 +203,118 @@ OpenClaw **закріплює вибраний профіль автентифі
|
||||
|
||||
Значення за замовчуванням:
|
||||
|
||||
- Backoff для білінгу починається з **5 годин**, подвоюється після кожного збою через білінг і обмежується **24 годинами**.
|
||||
- Лічильники backoff скидаються, якщо профіль не завершувався помилкою протягом **24 годин** (можна налаштувати).
|
||||
- Повторні спроби при перевантаженні дозволяють **1 ротацію профілю того самого провайдера** перед резервним перемиканням моделі.
|
||||
- Backoff для білінгу починається з **5 годин**, подвоюється після кожного збою білінгу й обмежується **24 годинами**.
|
||||
- Лічильники backoff скидаються, якщо профіль не мав збоїв протягом **24 годин** (можна налаштувати).
|
||||
- Повторні спроби при перевантаженні дозволяють **1 ротацію профілю того самого провайдера** перед резервним переходом між моделями.
|
||||
- Повторні спроби при перевантаженні за замовчуванням використовують backoff **0 мс**.
|
||||
|
||||
## Резервне перемикання моделей
|
||||
## Резервний перехід між моделями
|
||||
|
||||
Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до збоїв автентифікації, лімітів швидкості та тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервне перемикання).
|
||||
Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до збоїв автентифікації, rate limit і тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервний перехід).
|
||||
|
||||
Помилки перевантаження та лімітів швидкості обробляються агресивніше, ніж періоди охолодження через білінг. За замовчуванням OpenClaw дозволяє одну повторну спробу профілю автентифікації в межах того самого провайдера, а потім без очікування переходить до наступної налаштованої резервної моделі. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють до цієї категорії перевантаження. Це можна налаштувати через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`.
|
||||
Помилки перевантаження та rate limit обробляються агресивніше, ніж cooldown для білінгу. За замовчуванням OpenClaw дозволяє одну повторну спробу auth-profile у того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють до цієї категорії перевантаження. Це можна налаштувати через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`.
|
||||
|
||||
Коли запуск починається з перевизначення моделі (hooks або CLI), резервні перемикання все одно завершуються на `agents.defaults.model.primary` після спроб усіх налаштованих резервних варіантів.
|
||||
Коли запуск починається з перевизначення моделі (hooks або CLI), резервні переходи все одно завершуються на `agents.defaults.model.primary` після спроб будь-яких налаштованих резервних варіантів.
|
||||
|
||||
### Правила ланцюжка кандидатів
|
||||
|
||||
OpenClaw будує список кандидатів із поточно запитаного `provider/model` та налаштованих резервних варіантів.
|
||||
OpenClaw будує список кандидатів із поточно запитаного `provider/model` плюс налаштовані резервні варіанти.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Правила">
|
||||
- Запитана модель завжди перша.
|
||||
- Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за allowlist моделей. Вони вважаються явним наміром оператора.
|
||||
- Якщо поточний запуск уже використовує налаштований резервний варіант у межах тієї самої сім’ї провайдерів, OpenClaw продовжує використовувати весь налаштований ланцюжок.
|
||||
- Якщо поточний запуск використовує іншого провайдера, ніж указано в конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервного перемикання, OpenClaw не додає несуміжні налаштовані резервні варіанти від іншого провайдера.
|
||||
- Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг повернутися до звичайного стандартного значення після вичерпання попередніх кандидатів.
|
||||
- Якщо поточний запуск уже працює на налаштованій резервній моделі в тій самій сім’ї провайдера, OpenClaw продовжує використовувати весь налаштований ланцюжок.
|
||||
- Якщо поточний запуск використовує іншого провайдера, ніж у конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервних переходів, OpenClaw не додає не пов’язані налаштовані резервні варіанти від іншого провайдера.
|
||||
- Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг зрештою повернутися до звичайного стандартного варіанту після вичерпання попередніх кандидатів.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Які помилки просувають резервне перемикання
|
||||
### Які помилки просувають резервний перехід
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Продовжується для">
|
||||
- збоїв автентифікації
|
||||
- лімітів швидкості та вичерпання періодів охолодження
|
||||
- rate limit і вичерпання cooldown
|
||||
- помилок перевантаження/зайнятості провайдера
|
||||
- помилок резервного перемикання, схожих на тайм-аут
|
||||
- помилок резервного переходу, схожих на timeout
|
||||
- вимкнень через білінг
|
||||
- `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного перемикання, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб
|
||||
- `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного переходу, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб
|
||||
- інших нерозпізнаних помилок, коли ще залишаються кандидати
|
||||
</Tab>
|
||||
<Tab title="Не продовжується для">
|
||||
- явних переривань, які не мають форми тайм-ауту/резервного перемикання
|
||||
- явних переривань, які не схожі на timeout/резервний перехід
|
||||
- помилок переповнення контексту, які мають залишатися в межах логіки Compaction/повторних спроб (наприклад, `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model` або `ollama error: context length exceeded`)
|
||||
- фінальної невідомої помилки, коли кандидатів більше не залишилося
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Поведінка пропуску охолодження та пробних спроб
|
||||
### Поведінка пропуску cooldown порівняно з probe
|
||||
|
||||
Коли всі профілі автентифікації для провайдера вже перебувають в охолодженні, OpenClaw не пропускає цього провайдера назавжди автоматично. Він приймає рішення окремо для кожного кандидата:
|
||||
Коли всі auth profiles для провайдера вже перебувають у cooldown, OpenClaw не пропускає цього провайдера автоматично назавжди. Він приймає рішення окремо для кожного кандидата:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Рішення для кожного кандидата">
|
||||
- Стійкі збої автентифікації негайно пропускають усього провайдера.
|
||||
- Вимкнення через білінг зазвичай призводять до пропуску, але основного кандидата все ще можна пробно перевірити з throttle, щоб відновлення було можливим без перезапуску.
|
||||
- Основного кандидата можна пробно перевірити ближче до завершення охолодження, з throttle на рівні провайдера.
|
||||
- Сусідні резервні варіанти того самого провайдера можна пробувати попри охолодження, коли збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо важливо, коли ліміт швидкості прив’язаний до моделі, а сусідня модель може відновитися негайно.
|
||||
- Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера за один запуск резервного перемикання, щоб один провайдер не затримував резервне перемикання між провайдерами.
|
||||
- Постійні збої автентифікації одразу пропускають увесь провайдер.
|
||||
- Вимкнення через білінг зазвичай пропускаються, але основного кандидата все ще можна probe-ити з throttle, щоб відновлення було можливим без перезапуску.
|
||||
- Основного кандидата можна probe-ити ближче до завершення cooldown, із throttle для кожного провайдера.
|
||||
- Сусідні резервні моделі того самого провайдера можна спробувати попри cooldown, якщо збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо важливо, коли rate limit прив’язаний до моделі, а сусідня модель усе ще може відновитися негайно.
|
||||
- Тимчасові cooldown-probe обмежені одним на провайдера за один запуск резервного переходу, щоб один провайдер не затримував резервний перехід між провайдерами.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Перевизначення сеансу та перемикання моделей у live-сеансі
|
||||
## Перевизначення сеансу та live-перемикання моделей
|
||||
|
||||
Зміни моделей сеансу — це спільний стан. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та узгодження live-сеансу читають або записують частини одного й того самого запису сеансу.
|
||||
Зміни моделі сеансу — це спільний стан. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та live-узгодження сеансу читають або записують частини одного й того самого запису сеансу.
|
||||
|
||||
Це означає, що повторні спроби резервного перемикання мають координуватися з перемиканням моделей у live-сеансі:
|
||||
Це означає, що повторні спроби резервного переходу мають узгоджуватися з live-перемиканням моделі:
|
||||
|
||||
- Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`.
|
||||
- Зміни моделі, ініційовані системою, як-от ротація резервного перемикання, перевизначення Heartbeat або Compaction, ніколи самі по собі не позначають очікуване live-перемикання.
|
||||
- Перед початком повторної спроби резервного перемикання виконавець відповіді зберігає вибрані поля перевизначення резервного перемикання в записі сеансу.
|
||||
- На наступному запуску автоматичні перевизначення резервного перемикання очищуються перед вибором моделі, щоб знову спробувати налаштовану основну модель. Якщо вона все ще нездорова, цикл резервного перемикання записує нове автоматичне перевизначення для цієї нової спроби.
|
||||
- Перевизначення моделей користувача (`modelOverrideSource: "user"`) і застарілі перевизначення без поля джерела залишаються постійними між ходами.
|
||||
- Узгодження live-сеансу надає перевагу збереженим перевизначенням сеансу над застарілими полями моделі під час виконання.
|
||||
- Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюжку резервного перемикання, OpenClaw одразу переходить до цієї вибраної моделі замість того, щоб спочатку проходити несуміжних кандидатів.
|
||||
- Якщо спроба резервного перемикання не вдається, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату.
|
||||
- Зміни моделі, ініційовані системою, як-от ротація резервного переходу, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване live-перемикання.
|
||||
- Перед початком повторної спроби резервного переходу виконавець відповіді зберігає вибрані поля перевизначення резервного переходу в записі сеансу.
|
||||
- Автоматичні перевизначення резервного переходу залишаються вибраними в наступних ходах, щоб OpenClaw не probe-ив завідомо погану основну модель у кожному повідомленні. `/new`, `/reset` і `sessions.reset` очищають перевизначення з джерелом auto і повертають сеанс до налаштованого стандартного значення.
|
||||
- `/status` показує вибрану модель, а коли стан резервного переходу відрізняється — активну резервну модель і причину.
|
||||
- Live-узгодження сеансу надає перевагу збереженим перевизначенням сеансу над застарілими полями моделі під час виконання.
|
||||
- Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюжку резервного переходу, OpenClaw одразу переходить до цієї вибраної моделі замість того, щоб спочатку проходити не пов’язаних кандидатів.
|
||||
- Якщо спроба резервного переходу завершується помилкою, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату.
|
||||
|
||||
Це запобігає класичній гонці:
|
||||
|
||||
<Steps>
|
||||
<Step title="Основна модель завершується невдачею">
|
||||
Вибрана основна модель завершується невдачею.
|
||||
<Step title="Збій основної моделі">
|
||||
Вибрана основна модель завершується помилкою.
|
||||
</Step>
|
||||
<Step title="Резервний варіант вибрано в пам’яті">
|
||||
<Step title="Резервний кандидат вибрано в пам’яті">
|
||||
Резервного кандидата вибрано в пам’яті.
|
||||
</Step>
|
||||
<Step title="Сховище сеансу все ще вказує стару основну модель">
|
||||
Сховище сеансу все ще відображає стару основну модель.
|
||||
</Step>
|
||||
<Step title="Live-узгодження читає застарілий стан">
|
||||
Узгодження live-сеансу читає застарілий стан сеансу.
|
||||
Live-узгодження сеансу читає застарілий стан сеансу.
|
||||
</Step>
|
||||
<Step title="Повторну спробу повернуто назад">
|
||||
Повторну спробу повертає назад до старої моделі ще до початку спроби резервного перемикання.
|
||||
Повторну спробу повертає назад до старої моделі ще до початку спроби резервного переходу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Збережене перевизначення резервного перемикання закриває це вікно, а вузьке відкочування зберігає недоторканими новіші ручні або виконувані під час роботи зміни сеансу.
|
||||
Збережене перевизначення резервного переходу закриває це вікно, а вузьке відкочування зберігає недоторканими новіші ручні або runtime-зміни сеансу.
|
||||
|
||||
## Спостережуваність і зведення збоїв
|
||||
|
||||
`runWithModelFallback(...)` записує деталі кожної спроби, які використовуються в журналах і повідомленнях для користувача про періоди охолодження:
|
||||
`runWithModelFallback(...)` записує деталі по кожній спробі, які використовуються в логах і в повідомленнях для користувача про cooldown:
|
||||
|
||||
- спробуваний provider/model
|
||||
- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного перемикання)
|
||||
- спробувані provider/model
|
||||
- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного переходу)
|
||||
- необов’язковий status/code
|
||||
- зрозуміле людині зведення помилки
|
||||
|
||||
Коли всі кандидати завершуються невдачею, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати точніше повідомлення, наприклад «усі моделі тимчасово обмежені лімітами швидкості», і включити найближчий час завершення охолодження, якщо він відомий.
|
||||
Коли всі кандидати завершуються помилкою, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати точніше повідомлення, наприклад «усі моделі тимчасово обмежені через rate limit», і додати найближчий час завершення cooldown, якщо він відомий.
|
||||
|
||||
Це зведення охолодження враховує модель:
|
||||
Це зведення cooldown враховує модель:
|
||||
|
||||
- несуміжні ліміти швидкості, прив’язані до моделі, ігноруються для ланцюжка спробуваних provider/model
|
||||
- якщо блокування, що залишилося, є відповідним лімітом швидкості, прив’язаним до моделі, OpenClaw повідомляє про останній відповідний час завершення, який і далі блокує цю модель
|
||||
- не пов’язані rate limit із прив’язкою до моделі ігноруються для ланцюжка спробуваних provider/model
|
||||
- якщо блокування, що лишилося, є відповідним rate limit із прив’язкою до моделі, OpenClaw повідомляє останній відповідний час завершення, який і далі блокує цю модель
|
||||
|
||||
## Пов’язана конфігурація
|
||||
|
||||
@ -327,4 +328,4 @@ OpenClaw будує список кандидатів із поточно зап
|
||||
- `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
|
||||
- маршрутизації `agents.defaults.imageModel`
|
||||
|
||||
Див. [Моделі](/uk/concepts/models), щоб ознайомитися з ширшим оглядом вибору моделей і резервного перемикання.
|
||||
Див. [Моделі](/uk/concepts/models), щоб ознайомитися з ширшим оглядом вибору моделей і резервного переходу.
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете розгортати моделі зі свого GPU-сервера
|
||||
- Ви хочете обслуговувати моделі з власного сервера з GPU
|
||||
- Ви налаштовуєте LM Studio або OpenAI-сумісний проксі
|
||||
- Вам потрібні найбезпечніші рекомендації щодо локальних моделей
|
||||
summary: Запуск OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні кінцеві точки OpenAI)
|
||||
title: Локальні моделі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T08:18:08Z"
|
||||
generated_at: "2026-04-27T08:31:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d6d44f451e14e74f49b8fb23c7c890c8a13a76c56ef82e5d271cfbb7d90f7c81
|
||||
source_hash: 0e2733bd1d6f9e57f0b0fb888d28beebff321d12684a6ea670bee327d2ced8dc
|
||||
source_path: gateway/local-models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Локальний запуск можливий, але OpenClaw очікує великий контекст + сильний захист від prompt injection. Малі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 Mac Studio у максимальній конфігурації або еквівалентний GPU-риг (~$30k+)**. Один GPU на **24 ГБ** підходить лише для легших запитів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик prompt injection (див. [Безпека](/uk/gateway/security)).
|
||||
Локальний запуск можливий, але OpenClaw очікує великий контекст і надійний захист від інʼєкцій у промпти. Невеликі відеокарти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 повністю укомплектовані Mac Studio або еквівалентна GPU-система (~$30k+)**. Одна GPU на **24 GB** підходить лише для простіших запитів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик інʼєкцій у промпти (див. [Безпека](/uk/gateway/security)).
|
||||
|
||||
Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — рекомендаційний посібник для потужніших локальних стеків і власних локальних серверів, сумісних з OpenAI.
|
||||
Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — рекомендаційний посібник для локальних стеків вищого класу та власних локальних серверів, сумісних з OpenAI.
|
||||
|
||||
## Рекомендовано: LM Studio + велика локальна модель (Responses API)
|
||||
|
||||
@ -60,15 +60,15 @@ x-i18n:
|
||||
**Контрольний список налаштування**
|
||||
|
||||
- Встановіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
|
||||
- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small” / сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` показує її.
|
||||
- Замініть `my-local-model` на фактичний ID моделі, показаний у LM Studio.
|
||||
- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small” і сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` її показує.
|
||||
- Замініть `my-local-model` на фактичний ідентифікатор моделі, показаний у LM Studio.
|
||||
- Тримайте модель завантаженою; холодне завантаження додає затримку запуску.
|
||||
- За потреби змініть `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється.
|
||||
- Скоригуйте `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється.
|
||||
- Для WhatsApp дотримуйтеся Responses API, щоб надсилався лише фінальний текст.
|
||||
|
||||
Тримайте розміщені моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб резервні варіанти залишалися доступними.
|
||||
Залишайте хостингові моделі налаштованими навіть під час локальної роботи; використовуйте `models.mode: "merge"`, щоб запасні варіанти залишалися доступними.
|
||||
|
||||
### Гібридна конфігурація: основна розміщена модель, локальна резервна
|
||||
### Гібридна конфігурація: хостингова основна модель, локальна запасна
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -109,18 +109,18 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### Насамперед локально, із резервом у хмарі
|
||||
### Спочатку локальна модель, із хостинговою страховкою
|
||||
|
||||
Поміняйте місцями основну модель і порядок резервних; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було переключитися на Sonnet або Opus, коли локальний сервер недоступний.
|
||||
Поміняйте місцями основну модель і порядок запасних; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було переключитися на Sonnet або Opus, коли локальний сервер недоступний.
|
||||
|
||||
### Регіональний хостинг / маршрутизація даних
|
||||
|
||||
- Розміщені варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з кінцевими точками, прив’язаними до регіону (наприклад, розміщеними у США). Виберіть там регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для резервних Anthropic/OpenAI.
|
||||
- Лише локальний запуск залишається найкращим варіантом для конфіденційності; регіональна маршрутизація для розміщених моделей — проміжний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних.
|
||||
- Хостингові варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з кінцевими точками, привʼязаними до регіону (наприклад, хостинг у США). Виберіть там регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для запасних варіантів Anthropic/OpenAI.
|
||||
- Лише локальний режим залишається найсильнішим шляхом для приватності; регіональна маршрутизація хостингових моделей — це компромісний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних.
|
||||
|
||||
## Інші локальні проксі, сумісні з OpenAI
|
||||
|
||||
vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщо вони надають кінцеву точку `/v1` у стилі OpenAI. Замініть блок provider вище на вашу кінцеву точку та ID моделі:
|
||||
vLLM, LiteLLM, OAI-proxy або власні шлюзи підходять, якщо вони надають кінцеву точку `/v1` у стилі OpenAI. Замініть блок provider вище на свою кінцеву точку та ідентифікатор моделі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -149,64 +149,37 @@ vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщ
|
||||
}
|
||||
```
|
||||
|
||||
Зберігайте `models.mode: "merge"`, щоб розміщені моделі залишалися доступними як резервні.
|
||||
Використовуйте `models.providers.<id>.timeoutSeconds` для повільних локальних або віддалених
|
||||
серверів моделей, перш ніж збільшувати `agents.defaults.timeoutSeconds`. Тайм-аут провайдера
|
||||
застосовується лише до HTTP-запитів моделі, зокрема до встановлення з’єднання, заголовків, потокової
|
||||
передачі тіла відповіді та загального переривання guarded-fetch.
|
||||
Залишайте `models.mode: "merge"`, щоб хостингові моделі були доступні як запасні.
|
||||
Використовуйте `models.providers.<id>.timeoutSeconds` для повільних локальних або віддалених серверів моделей, перш ніж збільшувати `agents.defaults.timeoutSeconds`. Тайм-аут провайдера застосовується лише до HTTP-запитів моделі, включно з підключенням, заголовками, потоковою передачею тіла та загальним guarded-fetch abort.
|
||||
|
||||
Примітка щодо поведінки для локальних/проксійованих бекендів `/v1`:
|
||||
Примітка щодо поведінки локальних/проксійованих бекендів `/v1`:
|
||||
|
||||
- OpenClaw розглядає їх як проксі-маршрути, сумісні з OpenAI, а не як нативні
|
||||
кінцеві точки OpenAI
|
||||
- тут не застосовується формування запитів лише для нативного OpenAI: немає
|
||||
`service_tier`, немає Responses `store`, немає формування payload для сумісності
|
||||
з OpenAI reasoning і немає підказок для кешу prompt
|
||||
- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`)
|
||||
не додаються до цих власних URL проксі
|
||||
- OpenClaw розглядає їх як проксі-маршрути, сумісні з OpenAI, а не як нативні кінцеві точки OpenAI
|
||||
- тут не застосовується формування запитів, яке працює лише для нативного OpenAI: без `service_tier`, без Responses `store`, без формування payload для сумісності з міркуваннями OpenAI і без підказок кешу промптів
|
||||
- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`) не додаються до цих власних проксі-URL
|
||||
|
||||
Примітки щодо сумісності для суворіших бекендів, сумісних з OpenAI:
|
||||
Примітки щодо сумісності для суворіших OpenAI-сумісних бекендів:
|
||||
|
||||
- Деякі сервери приймають лише рядковий `messages[].content` у Chat Completions, а не
|
||||
структуровані масиви частин контенту. Для таких кінцевих точок встановіть
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- Деякі локальні моделі виводять окремі запити до інструментів у дужках як текст, наприклад
|
||||
`[tool_name]`, після якого йде JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює
|
||||
їх на справжні виклики інструментів лише тоді, коли назва точно збігається із зареєстрованим
|
||||
інструментом для цього ходу; інакше блок розглядається як непідтримуваний текст і
|
||||
приховується від видимих для користувача відповідей.
|
||||
- Якщо модель виводить JSON, XML або текст у стилі ReAct, що виглядає як виклик
|
||||
інструмента, але провайдер не передав структурований виклик, OpenClaw залишає це
|
||||
як текст і записує попередження з run id, провайдером/моделлю, виявленим шаблоном і
|
||||
назвою інструмента, якщо вона доступна. Розцінюйте це як несумісність
|
||||
викликів інструментів на рівні провайдера/моделі, а не як завершений запуск інструмента.
|
||||
- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною
|
||||
формою prompt середовища виконання агента OpenClaw, особливо коли включені схеми інструментів. Якщо
|
||||
бекенд працює для маленьких прямих викликів `/v1/chat/completions`, але не працює у звичайних
|
||||
ходах агента OpenClaw, спочатку спробуйте
|
||||
`agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі
|
||||
стандартні інструменти, як-от `browser`, `cron` і `message`; це експериментальний
|
||||
прапорець, а не стабільне налаштування режиму за замовчуванням. Див.
|
||||
[Експериментальні можливості](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false`.
|
||||
- Якщо бекенд і далі не працює лише на більших запусках OpenClaw, то проблема, як правило,
|
||||
полягає у можливостях моделі/сервера на стороні постачальника або у багу бекенда, а не в транспортному шарі OpenClaw.
|
||||
- Деякі сервери приймають лише рядковий `messages[].content` у Chat Completions, а не структуровані масиви частин вмісту. Для таких кінцевих точок установіть `models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- Деякі локальні моделі виводять окремі запити інструментів у дужках як текст, наприклад `[tool_name]`, потім JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює їх на реальні виклики інструментів лише тоді, коли назва точно збігається із зареєстрованим інструментом для цього ходу; інакше блок вважається непідтримуваним текстом і приховується від видимих користувачу відповідей.
|
||||
- Якщо модель виводить JSON, XML або текст у стилі ReAct, що виглядає як виклик інструмента, але провайдер не повернув структурований виклик, OpenClaw залишає це як текст і записує попередження з ідентифікатором запуску, провайдером/моделлю, виявленим шаблоном і назвою інструмента, якщо вона доступна. Розглядайте це як несумісність викликів інструментів у провайдера/моделі, а не як завершене виконання інструмента.
|
||||
- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною формою промпта середовища агента OpenClaw, особливо коли включені схеми інструментів. Якщо бекенд працює для маленьких прямих викликів `/v1/chat/completions`, але не працює для звичайних ходів агента OpenClaw, спочатку спробуйте `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі інструменти за замовчуванням, такі як `browser`, `cron` і `message`; це експериментальний прапорець, а не стабільний параметр стандартного режиму. Див. [Експериментальні можливості](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте `models.providers.<provider>.models[].compat.supportsTools: false`.
|
||||
- Якщо бекенд і далі не працює лише на більших запусках OpenClaw, то решта проблеми зазвичай повʼязана з обмеженнями моделі/сервера на боці upstream або з помилкою бекенда, а не з транспортним рівнем OpenClaw.
|
||||
|
||||
## Усунення проблем
|
||||
## Усунення несправностей
|
||||
|
||||
- Gateway може під’єднатися до проксі? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- Модель у LM Studio вивантажена? Завантажте її знову; холодний старт — часта причина “зависання”.
|
||||
- OpenClaw попереджає, коли виявлене вікно контексту менше за **32k**, і блокує роботу нижче **16k**. Якщо ви натрапили на цю попередню перевірку, збільшіть ліміт контексту сервера/моделі або виберіть більшу модель.
|
||||
- Помилки контексту? Зменште `contextWindow` або підвищте ліміт сервера.
|
||||
- Сервер, сумісний з OpenAI, повертає `messages[].content ... expected a string`?
|
||||
- Gateway може дістатися до проксі? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- Модель LM Studio вивантажена? Завантажте знову; холодний старт — поширена причина “зависання”.
|
||||
- Локальний сервер повідомляє `terminated`, `ECONNRESET` або закриває потік посеред ходу?
|
||||
OpenClaw записує низькокардинальний `model.call.error.failureKind`, а також знімок RSS/heap процесу OpenClaw у діагностику. Для тиску на памʼять у LM Studio/Ollama зіставте цей час із журналом сервера або журналом аварій macOS / jetsam, щоб підтвердити, чи було вбито сервер моделі.
|
||||
- OpenClaw попереджає, коли виявлене вікно контексту нижче за **32k**, і блокує, якщо нижче за **16k**. Якщо ви натрапили на цю попередню перевірку, збільште ліміт контексту сервера/моделі або виберіть більшу модель.
|
||||
- Помилки контексту? Зменште `contextWindow` або збільште ліміт вашого сервера.
|
||||
- OpenAI-сумісний сервер повертає `messages[].content ... expected a string`?
|
||||
Додайте `compat.requiresStringContent: true` у запис цієї моделі.
|
||||
- Маленькі прямі виклики `/v1/chat/completions` працюють, але `openclaw infer model run`
|
||||
не працює з Gemma або іншою локальною моделлю? Спочатку вимкніть схеми інструментів через
|
||||
`compat.supportsTools: false`, а потім повторіть перевірку. Якщо сервер і далі падає лише
|
||||
на більших prompt OpenClaw, розцінюйте це як обмеження сервера/моделі на стороні постачальника.
|
||||
- Безпека: локальні моделі оминають фільтри на стороні провайдера; тримайте агентів вузькоспеціалізованими, а Compaction увімкненим, щоб обмежити радіус ураження від prompt injection.
|
||||
- Прямі маленькі виклики `/v1/chat/completions` працюють, але `openclaw infer model run` не працює на Gemma або іншій локальній моделі? Спочатку вимкніть схеми інструментів через `compat.supportsTools: false`, а потім перевірте ще раз. Якщо сервер і далі аварійно завершується лише на більших промптах OpenClaw, розглядайте це як обмеження моделі/сервера на боці upstream.
|
||||
- Безпека: локальні моделі обходяться без фільтрів на боці провайдера; звужуйте агентів і тримайте увімкненим Compaction, щоб обмежити радіус ураження від інʼєкцій у промпти.
|
||||
|
||||
## Пов’язане
|
||||
## Повʼязане
|
||||
|
||||
- [Довідник з конфігурації](/uk/gateway/configuration-reference)
|
||||
- [Перемикання на резервну модель](/uk/concepts/model-failover)
|
||||
- [Резервне перемикання моделей](/uk/concepts/model-failover)
|
||||
|
||||
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете надсилати дані про використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry
|
||||
- Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого бекенда OTLP
|
||||
- Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення
|
||||
- Ви налаштовуєте traces, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда
|
||||
- Вам потрібні точні назви метрик, spans або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення
|
||||
summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP)
|
||||
title: експорт OpenTelemetry
|
||||
title: Експорт OpenTelemetry
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T21:17:06Z"
|
||||
generated_at: "2026-04-27T08:31:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1ad923fff12ff89766999370fe39a75c1aa5f386ce4641fde1c385b24439cc1b
|
||||
source_hash: e9d06589d281223ebb57e76f6f19441d30c138b9f7b0636198ab7bae5fad3c8a
|
||||
source_path: gateway/opentelemetry.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`
|
||||
з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP,
|
||||
працює без змін у коді. Для локальних файлових журналів і того, як їх читати, див.
|
||||
за допомогою **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP,
|
||||
працює без змін у коді. Для локальних файлових журналів і способів їх читання див.
|
||||
[Журналювання](/uk/logging).
|
||||
|
||||
## Як це працює разом
|
||||
|
||||
- **Діагностичні події** — це структуровані внутрішньопроцесні записи, які створюються
|
||||
Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг
|
||||
- **Події діагностики** — це структуровані внутрішньопроцесні записи, які видають
|
||||
Gateway і вбудовані plugins для запусків моделей, потоку повідомлень, сесій, черг
|
||||
та exec.
|
||||
- **Plugin `diagnostics-otel`** підписується на ці події й експортує їх як
|
||||
OpenTelemetry **метрики**, **трасування** та **журнали** через OTLP/HTTP.
|
||||
- **Виклики провайдера** отримують заголовок W3C `traceparent` із контексту
|
||||
довіреного span виклику моделі OpenClaw, якщо транспорт провайдера приймає власні
|
||||
заголовки. Контекст трасування, створений Plugin, не передається далі.
|
||||
- Експортери підключаються лише тоді, коли увімкнено і поверхню діагностики, і Plugin,
|
||||
тому внутрішньопроцесна вартість за замовчуванням залишається майже нульовою.
|
||||
- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як
|
||||
OpenTelemetry **метрики**, **traces** і **журнали** через OTLP/HTTP.
|
||||
- **Виклики провайдера** отримують заголовок W3C `traceparent` із довіреного
|
||||
контексту span виклику моделі OpenClaw, якщо транспорт провайдера приймає
|
||||
користувацькі заголовки. Контекст trace, який видає Plugin, не поширюється.
|
||||
- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і plugin,
|
||||
тому внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими.
|
||||
|
||||
## Швидкий старт
|
||||
## Швидкий початок
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -59,7 +59,7 @@ OpenClaw експортує діагностику через вбудовани
|
||||
}
|
||||
```
|
||||
|
||||
Ви також можете увімкнути Plugin з CLI:
|
||||
Ви також можете ввімкнути plugin з CLI:
|
||||
|
||||
```bash
|
||||
openclaw plugins enable diagnostics-otel
|
||||
@ -71,13 +71,13 @@ openclaw plugins enable diagnostics-otel
|
||||
|
||||
## Експортовані сигнали
|
||||
|
||||
| Сигнал | Що до нього входить |
|
||||
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску пам’яті. |
|
||||
| **Трасування** | Спани для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. |
|
||||
| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. |
|
||||
| Signal | Що в нього входить |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Metrics** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску пам’яті. |
|
||||
| **Traces** | Spans для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. |
|
||||
| **Logs** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. |
|
||||
|
||||
Перемикайте `traces`, `metrics` і `logs` незалежно. За замовчуванням усі три
|
||||
Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням
|
||||
увімкнені, коли `diagnostics.otel.enabled` має значення true.
|
||||
|
||||
## Довідник конфігурації
|
||||
@ -99,7 +99,7 @@ openclaw plugins enable diagnostics-otel
|
||||
metrics: true,
|
||||
logs: true,
|
||||
sampleRate: 0.2, // root-span sampler, 0.0..1.0
|
||||
flushIntervalMs: 60000, // metric export interval (min 1000ms)
|
||||
flushIntervalMs: 60000, // interval exportu метрик (мінімум 1000ms)
|
||||
captureContent: {
|
||||
enabled: false,
|
||||
inputMessages: false,
|
||||
@ -115,68 +115,68 @@ openclaw plugins enable diagnostics-otel
|
||||
|
||||
### Змінні середовища
|
||||
|
||||
| Змінна | Призначення |
|
||||
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для конкретних сигналів, які використовуються, коли не задано відповідний ключ конфігурації `diagnostics.otel.*Endpoint`. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою. |
|
||||
| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб виводити останній експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інше preload-рішення або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. |
|
||||
| Variable | Призначення |
|
||||
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для окремих сигналів, що використовуються, коли не задано відповідний ключ конфігурації `diagnostics.otel.*Endpoint`. Конфігурація для конкретного сигналу має пріоритет над env для конкретного сигналу, яке має пріоритет над спільною кінцевою точкою. |
|
||||
| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб видавати найновіший експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інший preload або host process уже зареєстрував глобальний SDK OpenTelemetry. Тоді plugin пропустить власний життєвий цикл NodeSDK, але все одно підключить слухачі діагностики та врахує `traces`/`metrics`/`logs`. |
|
||||
|
||||
## Конфіденційність і захоплення вмісту
|
||||
|
||||
Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять
|
||||
обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані request id)
|
||||
і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані
|
||||
інструментів або ключі сесій.
|
||||
Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Spans містять
|
||||
обмежені ідентифікатори (канал, провайдер, модель, категорію помилки, ідентифікатори запитів
|
||||
лише у вигляді хешів) і ніколи не включають текст prompt, текст відповіді, вхідні дані
|
||||
інструментів, вихідні дані інструментів або ключі сесії.
|
||||
|
||||
Вихідні запити до моделі можуть містити заголовок W3C `traceparent`. Цей заголовок
|
||||
генерується лише з діагностичного контексту трасування, що належить OpenClaw, для активного виклику
|
||||
моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому Plugins або
|
||||
власні параметри провайдера не можуть підробити походження трасування між сервісами.
|
||||
генерується лише з контексту trace діагностики, що належить OpenClaw, для активного
|
||||
виклику моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому plugins або
|
||||
користувацькі параметри провайдера не можуть підробити походження cross-service trace.
|
||||
|
||||
Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш колектор і
|
||||
політика зберігання схвалені для тексту промптів, відповідей, інструментів або системних промптів.
|
||||
Кожен підключ окремо вмикається явно:
|
||||
Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш колектор
|
||||
і політика зберігання схвалені для тексту prompt, відповіді, інструментів або system prompt.
|
||||
Кожен вкладений ключ вмикається окремо:
|
||||
|
||||
- `inputMessages` — вміст користувацького промпту.
|
||||
- `inputMessages` — вміст prompt користувача.
|
||||
- `outputMessages` — вміст відповіді моделі.
|
||||
- `toolInputs` — корисні навантаження аргументів інструментів.
|
||||
- `toolOutputs` — корисні навантаження результатів інструментів.
|
||||
- `systemPrompt` — зібраний системний/розробницький промпт.
|
||||
- `toolInputs` — payload аргументів інструментів.
|
||||
- `toolOutputs` — payload результатів інструментів.
|
||||
- `systemPrompt` — зібраний system/developer prompt.
|
||||
|
||||
Коли ввімкнено будь-який підключ, спани моделі та інструментів отримують обмежені, відредаговані
|
||||
атрибути `openclaw.content.*` лише для цього класу.
|
||||
Коли ввімкнено будь-який вкладений ключ, spans моделей та інструментів отримують обмежені,
|
||||
відредаговані атрибути `openclaw.content.*` лише для цього класу.
|
||||
|
||||
## Семплювання та скидання
|
||||
|
||||
- **Трасування:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає все,
|
||||
`1.0` зберігає все).
|
||||
- **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`).
|
||||
- **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). Вони використовують
|
||||
шлях редагування діагностичних log record, а не форматування консолі. Для інсталяцій із великим
|
||||
обсягом даних краще використовувати семплювання/фільтрацію в колекторі OTLP, а не локальне семплювання.
|
||||
- **Кореляція файлових журналів:** журнали JSONL включають верхньорівневі `traceId`,
|
||||
`spanId`, `parentSpanId` і `traceFlags`, коли виклик журналювання містить коректний
|
||||
діагностичний контекст трасування, що дає змогу обробникам журналів поєднувати локальні рядки журналу
|
||||
з експортованими спанами.
|
||||
- **Traces:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає всі,
|
||||
`1.0` зберігає всі).
|
||||
- **Metrics:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`).
|
||||
- **Logs:** OTLP logs враховують `logging.level` (рівень файлового журналу). Вони використовують
|
||||
шлях редагування діагностичних log record, а не форматування консолі. Для інсталяцій із
|
||||
великим обсягом даних слід надавати перевагу семплюванню/фільтрації в колекторі OTLP, а не локальному семплюванню.
|
||||
- **Кореляція файлових журналів:** JSONL-файли журналів містять верхньорівневі `traceId`,
|
||||
`spanId`, `parentSpanId` і `traceFlags`, коли виклик журналу несе чинний діагностичний
|
||||
контекст trace, що дозволяє процесорам журналів поєднувати локальні рядки журналу з
|
||||
експортованими spans.
|
||||
- **Кореляція запитів:** HTTP-запити Gateway і кадри WebSocket створюють внутрішню
|
||||
область трасування запиту. Журнали та діагностичні події в цій області за замовчуванням
|
||||
успадковують трасування запиту, тоді як спани запуску агента та виклику моделі
|
||||
створюються як дочірні, щоб заголовки провайдера `traceparent` залишалися в межах того самого трасування.
|
||||
область trace запиту. Журнали й події діагностики в цій області за замовчуванням
|
||||
успадковують trace запиту, тоді як spans запуску агента та виклику моделі
|
||||
створюються як дочірні, щоб заголовки провайдера `traceparent` залишалися в межах того самого trace.
|
||||
|
||||
## Експортовані метрики
|
||||
|
||||
### Використання моделей
|
||||
### Використання моделі
|
||||
|
||||
- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`)
|
||||
- `openclaw.cost.usd` (лічильник, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.run.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.context.tokens` (гістограма, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `gen_ai.client.token.usage` (гістограма, метрика семантичних конвенцій GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних конвенцій GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`)
|
||||
- `openclaw.model_call.duration_ms` (гістограма, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`)
|
||||
- `gen_ai.client.token.usage` (гістограма, метрика семантичних угод GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних угод GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`)
|
||||
- `openclaw.model_call.duration_ms` (гістограма, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, а також `openclaw.errorCategory` і `openclaw.failureKind` для класифікованих помилок)
|
||||
- `openclaw.model_call.request_bytes` (гістограма, розмір у байтах UTF-8 фінального payload запиту до моделі; без необробленого вмісту payload)
|
||||
- `openclaw.model_call.response_bytes` (гістограма, розмір у байтах UTF-8 потокових подій відповіді моделі; без необробленого вмісту відповіді)
|
||||
- `openclaw.model_call.time_to_first_byte_ms` (гістограма, час до першої потокової події відповіді)
|
||||
@ -203,9 +203,9 @@ openclaw plugins enable diagnostics-otel
|
||||
- `openclaw.session.stuck_age_ms` (гістограма, attrs: `openclaw.state`)
|
||||
- `openclaw.run.attempt` (лічильник, attrs: `openclaw.attempt`)
|
||||
|
||||
### Життєвий цикл harness
|
||||
### Життєвий цикл Harness
|
||||
|
||||
- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` для помилок)
|
||||
- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` у разі помилок)
|
||||
|
||||
### Exec
|
||||
|
||||
@ -219,23 +219,24 @@ openclaw plugins enable diagnostics-otel
|
||||
- `openclaw.tool.loop.iterations` (лічильник, attrs: `openclaw.toolName`, `openclaw.outcome`)
|
||||
- `openclaw.tool.loop.duration_ms` (гістограма, attrs: `openclaw.toolName`, `openclaw.outcome`)
|
||||
|
||||
## Експортовані спани
|
||||
## Експортовані spans
|
||||
|
||||
- `openclaw.model.usage`
|
||||
- `openclaw.channel`, `openclaw.provider`, `openclaw.model`
|
||||
- `openclaw.tokens.*` (input/output/cache_read/cache_write/total)
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні конвенції GenAI
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*`
|
||||
- `openclaw.run`
|
||||
- `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory`
|
||||
- `openclaw.model.call`
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні конвенції GenAI
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`
|
||||
- `openclaw.errorCategory` і необов’язковий `openclaw.failureKind` у разі помилок
|
||||
- `openclaw.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms`
|
||||
- `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для upstream request id провайдера; сирі id не експортуються)
|
||||
- `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для upstream request id провайдера; необроблені id не експортуються)
|
||||
- `openclaw.harness.run`
|
||||
- `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.provider`, `openclaw.model`, `openclaw.channel`
|
||||
- Під час завершення: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active`
|
||||
- Після завершення: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active`
|
||||
- У разі помилки: `openclaw.harness.phase`, `openclaw.errorCategory`, необов’язковий `openclaw.harness.cleanup_failed`
|
||||
- `openclaw.tool.execution`
|
||||
- `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*`
|
||||
@ -252,27 +253,27 @@ openclaw plugins enable diagnostics-otel
|
||||
- `openclaw.session.stuck`
|
||||
- `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth`
|
||||
- `openclaw.context.assembled`
|
||||
- `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту промпту, історії, відповіді або ключа сесії)
|
||||
- `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, history, response або session key)
|
||||
- `openclaw.tool.loop`
|
||||
- `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента)
|
||||
- `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, params або виводу інструмента)
|
||||
- `openclaw.memory.pressure`
|
||||
- `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes`
|
||||
|
||||
Коли захоплення вмісту явно ввімкнене, спани моделі та інструментів також можуть
|
||||
Якщо захоплення вмісту явно ввімкнено, spans моделей та інструментів також можуть
|
||||
включати обмежені, відредаговані атрибути `openclaw.content.*` для конкретних
|
||||
класів вмісту, на які ви дали згоду.
|
||||
класів вмісту, які ви ввімкнули.
|
||||
|
||||
## Каталог діагностичних подій
|
||||
## Каталог подій діагностики
|
||||
|
||||
Наведені нижче події лежать в основі метрик і спанів вище. Plugins також можуть
|
||||
підписуватися на них безпосередньо без експорту OTLP.
|
||||
Наведені нижче події є основою для метрик і spans вище. Plugins також можуть підписуватися
|
||||
на них напряму без експорту OTLP.
|
||||
|
||||
**Використання моделей**
|
||||
**Використання моделі**
|
||||
|
||||
- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал,
|
||||
id сесій. `usage` — це облік провайдера/ходу для вартості й телеметрії;
|
||||
`context.used` — це поточний знімок промпту/контексту і він може бути меншим за
|
||||
`usage.total` провайдера, коли задіяно кешоване введення або виклики циклу інструментів.
|
||||
id сесії. `usage` — це облік провайдера/ходу для вартості й телеметрії;
|
||||
`context.used` — це поточний знімок prompt/контексту, який може бути меншим за
|
||||
`usage.total` провайдера, коли задіяно кешований ввід або виклики циклу інструментів.
|
||||
|
||||
**Потік повідомлень**
|
||||
|
||||
@ -285,15 +286,15 @@ openclaw plugins enable diagnostics-otel
|
||||
- `queue.lane.enqueue` / `queue.lane.dequeue`
|
||||
- `session.state` / `session.stuck`
|
||||
- `run.attempt`
|
||||
- `diagnostic.heartbeat` (агреговані лічильники: webhook/черга/сесія)
|
||||
- `diagnostic.heartbeat` (агреговані лічильники: webhooks/queue/session)
|
||||
|
||||
**Життєвий цикл harness**
|
||||
**Життєвий цикл Harness**
|
||||
|
||||
- `harness.run.started` / `harness.run.completed` / `harness.run.error` —
|
||||
життєвий цикл кожного запуску для harness агента. Включає `harnessId`, необов’язковий
|
||||
`pluginId`, провайдер/модель/канал і id запуску. Завершення додає
|
||||
життєвий цикл agent harness для кожного запуску. Включає `harnessId`, необов’язковий
|
||||
`pluginId`, провайдера/модель/канал і id запуску. Завершення додає
|
||||
`durationMs`, `outcome`, необов’язкові `resultClassification`, `yieldDetected`
|
||||
і лічильники `itemLifecycle`. Помилки додають `phase`
|
||||
та лічильники `itemLifecycle`. Помилки додають `phase`
|
||||
(`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` і
|
||||
необов’язковий `cleanupFailed`.
|
||||
|
||||
@ -305,7 +306,7 @@ openclaw plugins enable diagnostics-otel
|
||||
|
||||
## Без експортера
|
||||
|
||||
Ви можете залишити діагностичні події доступними для Plugins або власних приймачів без
|
||||
Ви можете залишити події діагностики доступними для plugins або користувацьких sinks без
|
||||
запуску `diagnostics-otel`:
|
||||
|
||||
```json5
|
||||
@ -314,8 +315,8 @@ openclaw plugins enable diagnostics-otel
|
||||
}
|
||||
```
|
||||
|
||||
Для цільового виводу налагодження без підвищення `logging.level` використовуйте
|
||||
прапорці діагностики. Прапорці нечутливі до регістру й підтримують шаблони (наприклад, `telegram.*` або
|
||||
Для цільового налагоджувального виводу без підвищення `logging.level` використовуйте
|
||||
прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-вирази (наприклад, `telegram.*` або
|
||||
`*`):
|
||||
|
||||
```json5
|
||||
@ -324,13 +325,13 @@ openclaw plugins enable diagnostics-otel
|
||||
}
|
||||
```
|
||||
|
||||
Або як одноразове перевизначення через змінну середовища:
|
||||
Або як одноразове перевизначення через env:
|
||||
|
||||
```bash
|
||||
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
```
|
||||
|
||||
Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще
|
||||
Вивід прапорців надходить до стандартного файла журналу (`logging.file`) і все ще
|
||||
редагується через `logging.redactSensitive`. Повний посібник:
|
||||
[Прапорці діагностики](/uk/diagnostics/flags).
|
||||
|
||||
@ -347,8 +348,8 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, перегляд через CLI та вкладка Журнали в Control UI
|
||||
- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Прапорці діагностики](/uk/diagnostics/flags) — прапорці цільового журналювання для налагодження
|
||||
- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент підтримки для збору пакета даних оператора (окремо від експорту OTEL)
|
||||
- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, tailing у CLI та вкладка Logs у Control UI
|
||||
- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналів налагодження
|
||||
- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент operator support bundle (окремо від експорту OTEL)
|
||||
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user