diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index eedbae1aa..476b7bc28 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -1,21 +1,21 @@ --- read_when: - Планування фонових завдань або пробуджень - - Підключення зовнішніх тригерів (Webhook, Gmail) до OpenClaw + - Підключення зовнішніх тригерів (Webhook-и, Gmail) до OpenClaw - Вибір між Heartbeat і Cron для запланованих завдань sidebarTitle: Scheduled tasks -summary: Заплановані завдання, Webhook та тригери Gmail PubSub для планувальника Gateway +summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-27T08:45:04Z" + generated_at: "2026-04-27T20:43:54Z" model: gpt-5.4 provider: openai - source_hash: a8764103e2d6a9b35b3112e3e95c9570d196c03ed86f4fcdcf4536049a05ac6d + source_hash: f61e85e3f4f334d611397e2d27e508ee7b20e342ccb52b8995b73555f2e6434b source_path: automation/cron-jobs.md workflow: 15 --- -Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може повертати результат назад у канал чату або на endpoint Webhook. +Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат у канал чату або на endpoint Webhook. ## Швидкий старт @@ -48,37 +48,37 @@ Cron — це вбудований планувальник Gateway. Він зб - Cron працює **всередині процесу Gateway** (а не всередині моделі). - Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів. -- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore. -- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть трактувати завдання як нові, оскільки поля стану виконання тепер містяться в `jobs-state.json`. -- Коли `jobs.json` редагується під час роботи Gateway або коли він зупинений, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота виконання і очищує застарілі значення `nextRunAtMs`. Зміни лише форматування або переписування лише порядку ключів зберігають очікуваний слот. +- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json` і додайте `jobs-state.json` до gitignore. +- Після цього розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, оскільки поля часу виконання тепер містяться в `jobs-state.json`. +- Коли `jobs.json` редагується під час роботи Gateway або коли він зупинений, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота часу виконання і очищає застарілі значення `nextRunAtMs`. Перезаписи лише з форматуванням або лише зі зміною порядку ключів зберігають очікуваний слот. - Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks). -- Одноразові завдання (`--at`) після успішного виконання типово видаляються автоматично. -- Ізольовані запуски cron у режимі best-effort закривають відстежувані вкладки/процеси браузера для їхньої сесії `cron:` після завершення запуску, щоб відокремлена автоматизація браузера не залишала сирітські процеси. -- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит для отримання фактичного результату перед доставкою. -- Ізольовані запуски cron віддають перевагу структурованим метаданим відмови виконання з вбудованого запуску, а потім використовують відомі маркери фінального підсумку/виводу, такі як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не була позначена як успішний запуск. -- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть якщо payload відповіді не створюється, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої замість того, щоб позначати завдання як успішне. +- Одноразові завдання (`--at`) за замовчуванням автоматично видаляються після успішного виконання. +- Ізольовані запуски cron у режимі best-effort закривають відстежувані вкладки браузера/процеси для своєї сесії `cron:` після завершення запуску, щоб від’єднана автоматизація браузера не залишала після себе завислі процеси. +- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки) і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит на фактичний результат перед доставкою. +- Ізольовані запуски cron віддають перевагу структурованим метаданим відмови у виконанні із вбудованого запуску, а потім, як запасний варіант, використовують відомі фінальні маркери підсумку/виводу, такі як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не позначалася як успішний запуск. +- Ізольовані запуски cron також розглядають збої агента на рівні запуску як помилки завдання навіть тоді, коли payload відповіді не формується, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої замість того, щоб позначати завдання як успішне. -Узгодження завдань для cron насамперед належить runtime, а вже потім спирається на стійку історію: активне завдання cron залишається активним, доки runtime cron і далі відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і минає 5-хвилинне вікно очікування, перевірки обслуговування аналізують збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця стійка історія містить термінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, що належить Gateway, може позначити завдання як `lost`. Автономний аудит CLI може відновитися зі стійкої історії, але не трактує власний порожній внутрішньопроцесний набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник. +Узгодження завдань для cron насамперед належить середовищу виконання, а по-друге — стійкій історії: активне завдання cron залишається активним, доки середовище виконання cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно середовище виконання перестає володіти завданням і минає 5-хвилинне вікно очікування, перевірки обслуговування звіряють збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця стійка історія показує фінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, що належить Gateway, може позначити завдання як `lost`. Офлайновий аудит CLI може відновитися зі стійкої історії, але він не вважає власний порожній внутрішньопроцесний набір активних завдань доказом того, що запуск cron, який належить Gateway, зник. ## Типи розкладу -| Вид | Прапорець CLI | Опис | -| ------- | ------------- | ---------------------------------------------------------- | -| `at` | `--at` | Одноразова мітка часу (ISO 8601 або відносна, наприклад `20m`) | -| `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | Cron-вираз із 5 або 6 полів з необов’язковим `--tz` | +| Вид | Прапорець CLI | Опис | +| ------- | ------------- | ------------------------------------------------------- | +| `at` | `--at` | Одноразова позначка часу (ISO 8601 або відносна, як `20m`) | +| `every` | `--every` | Фіксований інтервал | +| `cron` | `--cron` | Вираз cron із 5 або 6 полів із необов’язковим `--tz` | -Мітки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним часом. +Позначки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом. -Періодичні вирази на початок кожної години автоматично розподіляються зі зсувом до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово встановити точний час, або `--stagger 30s` для явного вікна. +Періодичні вирази на початок кожної години автоматично зсуваються до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово дотримуватися точного часу, або `--stagger 30s` для явного вікна. ### День місяця і день тижня використовують логіку OR -Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner вважає вираз таким, що збігається, коли збігається **будь-яке** з цих полів — а не обидва. Це стандартна поведінка Vixie cron. +Вирази cron парсяться за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner виконує збіг, коли **будь-яке** з полів збігається, а не обидва. Це стандартна поведінка Vixie cron. ``` # Intended: "9 AM on the 15th, only if it's a Monday" @@ -86,34 +86,34 @@ Cron-вирази розбираються за допомогою [croner](http 0 9 15 * 1 ``` -Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує типову OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` із Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання. +Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує стандартну OR-поведінку Croner. Щоб вимагати збіг обох умов, використовуйте модифікатор дня тижня `+` у Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання. ## Стилі виконання -| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | -| -------------- | -------------------- | ------------------------- | ------------------------------- | -| Основна сесія | `main` | Наступний такт Heartbeat | Нагадувань, системних подій | -| Ізольований | `isolated` | Окремий `cron:` | Звітів, фонових завдань | -| Поточна сесія | `current` | Прив’язується під час створення | Періодичної роботи з контекстом | -| Власна сесія | `session:custom-id` | Постійна іменована сесія | Робочих процесів, що накопичують історію | +| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | +| --------------- | -------------------- | ------------------------ | ------------------------------- | +| Основна сесія | `main` | Наступний цикл Heartbeat | Нагадувань, системних подій | +| Ізольований | `isolated` | Окремий `cron:` | Звітів, фонових завдань | +| Поточна сесія | `current` | Прив’язується під час створення | Повторюваної роботи з контекстом | +| Власна сесія | `session:custom-id` | Постійна іменована сесія | Процесів, що спираються на історію | - - Завдання **основної сесії** ставлять системну подію в чергу й за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують актуальність щоденного/неактивного скидання для цільової сесії. **Ізольовані** завдання виконують окремий такт агента з новою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. + + Завдання **основної сесії** ставлять системну подію в чергу та за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не продовжують актуальність скидання за день/бездіяльність для цільової сесії. **Ізольовані** завдання запускають окремий хід агента з новою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу створювати процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. - - Для ізольованих завдань «нова сесія» означає новий ідентифікатор transcript/session для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні перевизначення моделі/автентифікації, вибрані користувачем, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищені привілеї, origin або прив’язку runtime ACP. Використовуйте `current` або `session:`, якщо періодичне завдання має свідомо продовжувати той самий контекст розмови. + + Для ізольованих завдань «нова сесія» означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні перевизначення моделі/автентифікації, вибрані користувачем, але не успадковує фоновий контекст розмови зі старого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищені привілеї, походження або прив’язку середовища виконання ACP. Використовуйте `current` або `session:`, коли повторюване завдання має навмисно будуватися на тому самому контексті розмови. - - Для ізольованих завдань завершення runtime тепер включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, тому фактичний результат cron усе одно має пріоритет. + + Для ізольованих завдань завершення середовища виконання тепер включає очищення браузера для цієї cron-сесії в режимі best-effort. Помилки очищення ігноруються, тож фактичний результат cron усе одно має пріоритет. - Ізольовані запуски cron також звільняють будь-які екземпляри runtime MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як завершується робота клієнтів MCP основної сесії та власних сесій, тому ізольовані cron-завдання не спричиняють витоків дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками. + Ізольовані запуски cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як завершуються клієнти MCP для основної та власної сесій, тому ізольовані завдання cron не спричиняють витоків дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками. - - Коли ізольовані запуски cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка замість застарілого проміжного тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського запуску замість того, щоб оголошувати його. + + Коли ізольовані запуски cron оркеструють субагентів, під час доставки також надається перевага фінальному виводу дочірнього нащадка, а не застарілому проміжному тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. - Для цілей оголошення Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз замість повторного програвання і потокового/проміжного текстового payload, і фінальної відповіді. Медіа та структуровані payload Discord, як і раніше, доставляються окремими payload, щоб не втрачалися вкладення й компоненти. + Для цілей оголошення в Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз замість повторного програвання і потокового/проміжного текстового payload, і фінальної відповіді. Медіа- та структуровані payload Discord, як і раніше, доставляються як окремі payload, щоб не втрачалися вкладення та компоненти. @@ -121,7 +121,7 @@ Cron-вирази розбираються за допомогою [croner](http ### Параметри payload для ізольованих завдань - Текст prompt (обов’язковий для isolated). + Текст prompt (обов’язковий для ізольованого режиму). Перевизначення моделі; використовує вибрану дозволену модель для завдання. @@ -130,46 +130,46 @@ Cron-вирази розбираються за допомогою [croner](http Перевизначення рівня thinking. - Пропустити ін’єкцію bootstrap-файла робочого простору. + Пропустити ін’єкцію bootstrap-файлу робочого простору. Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`. -`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки fallback як і раніше застосовуються, але просте перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. +`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/моделі за замовчуванням для завдання. Налаштовані ланцюжки резервних варіантів, як і раніше, застосовуються, але просте перевизначення моделі без явного списку резервних варіантів для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. -Пріоритет вибору моделі для ізольованих завдань: +Пріоритет вибору моделі для ізольованих завдань такий: -1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) +1. Перевизначення моделі з hook Gmail (коли запуск надійшов із Gmail і це перевизначення дозволене) 2. `model` у payload конкретного завдання -3. Збережене перевизначення моделі cron-сесії, вибране користувачем -4. Вибір моделі агента/типової моделі +3. Збережене перевизначення моделі сесії cron, вибране користувачем +4. Вибір моделі агента/за замовчуванням -Швидкий режим також наслідує визначений актуальний вибір. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron типово використовує це значення. Збережене перевизначення сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках. +Швидкий режим також дотримується фактичного вибору в реальному часі. Якщо вибрана конфігурація моделі має `params.fastMode`, ізольований cron використовує це за замовчуванням. Збережене в сесії перевизначення `fastMode`, як і раніше, має пріоритет над конфігурацією в обох напрямках. -Якщо ізольований запуск під час роботи натрапляє на передачу керування через перемикання моделі, cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей актуальний вибір для поточного запуску перед повторною спробою. Якщо перемикання також містить новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації для поточного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб із перемиканням cron перериває виконання замість нескінченного циклу. +Якщо ізольований запуск натрапляє на передачу керування через перемикання моделі в реальному часі, cron повторює спробу з перемкненими провайдером/моделлю й зберігає цей фактичний вибір для активного запуску перед повторною спробою. Коли перемикання також несе новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації для активного запуску. Кількість повторних спроб обмежена: після початкової спроби плюс 2 повторні спроби через перемикання cron перериває виконання замість безкінечного циклу. ## Доставка і вивід -| Режим | Що відбувається | -| ---------- | ----------------------------------------------------------------- | -| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент не надіслав його | -| `webhook` | Надсилає payload події завершення через POST на URL | -| `none` | Немає резервної доставки з боку виконавця | +| Режим | Що відбувається | +| ---------- | ---------------------------------------------------------------- | +| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент його не надіслав | +| `webhook` | Надсилає payload події завершення через POST на URL | +| `none` | Без резервної доставки з боку runner | -Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `room:!room:server` із Matrix. +Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`; прямі виклики RPC/конфігурації також можуть передавати `delivery.threadId` як рядок або число. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний room ID або форму `room:!room:server` з Matrix. -Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що виконавець робить із фінальною відповіддю після такту агента. +Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` визначають лише те, що runner робить із фінальною відповіддю після ходу агента. -Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену актуальну ціль доставки для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдера не відновлюються з цих ключів, коли доступний поточний контекст чату. +Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену фактичну ціль доставки для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдера не відновлюються з цих ключів, коли доступний контекст поточного чату. -Сповіщення про збої використовують окремий шлях призначення: +Сповіщення про збої мають окремий маршрут призначення: -- `cron.failureDestination` задає глобальне типове місце призначення для сповіщень про збої. -- `job.delivery.failureDestination` перевизначає його для окремого завдання. -- Якщо не задано жодного з них і завдання вже доставляє результати через `announce`, сповіщення про збої тепер резервно використовують цю основну ціль оголошення. -- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. -- `failureAlert.includeSkipped: true` дає змогу для завдання або глобальної політики сповіщень cron повторювати сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому вони не впливають на backoff для помилок виконання. +- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про збої. +- `job.delivery.failureDestination` перевизначає його для конкретного завдання. +- Якщо не задано жодного з них і завдання вже доставляє через `announce`, сповіщення про збої тепер за замовчуванням надсилаються до цієї основної цілі оголошення. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. +- `failureAlert.includeSkipped: true` дозволяє для завдання або глобальної політики сповіщень cron повторювані сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому не впливають на backoff помилок виконання. ## Приклади CLI @@ -212,7 +212,7 @@ Cron-вирази розбираються за допомогою [croner](http -## Webhook +## Webhook-и Gateway може відкривати HTTP endpoint-и Webhook для зовнішніх тригерів. Увімкніть це в конфігурації: @@ -233,11 +233,11 @@ Gateway може відкривати HTTP endpoint-и Webhook для зовні - `Authorization: Bearer ` (рекомендовано) - `x-openclaw-token: ` -Токени в рядку запиту відхиляються. +Токени в query string відхиляються. - Поставити системну подію в чергу для основної сесії: + Додає системну подію в чергу для основної сесії: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -255,7 +255,7 @@ Gateway може відкривати HTTP endpoint-и Webhook для зовні - Запустити ізольований такт агента: + Запускає ізольований хід агента: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -268,27 +268,27 @@ Gateway може відкривати HTTP endpoint-и Webhook для зовні - Власні назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload у дії `wake` або `agent` за допомогою шаблонів або кодових трансформацій. + Власні назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload у дії `wake` або `agent` за допомогою шаблонів або перетворень коду. -Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним зворотним проксі. +Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним reverse proxy. - Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway. - Тримайте `hooks.path` на окремому підшляху; `/` відхиляється. -- Установіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. -- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. -- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесії. -- Payload hook-ів типово обгортаються межами безпеки. +- Налаштуйте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. +- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. +- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також налаштуйте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесії. +- Payload hook-ів за замовчуванням обгортаються межами безпеки. ## Інтеграція Gmail PubSub -Підключіть тригери вхідних Gmail до OpenClaw через Google PubSub. +Підключіть тригери вхідної пошти Gmail до OpenClaw через Google PubSub. -**Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint. +**Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hook-и OpenClaw, Tailscale для публічного HTTPS endpoint. ### Налаштування через майстер (рекомендовано) @@ -297,17 +297,17 @@ Gateway може відкривати HTTP endpoint-и Webhook для зовні openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push endpoint. +Це записує конфігурацію `hooks.gmail`, вмикає Gmail preset і використовує Tailscale Funnel для push endpoint. ### Автозапуск Gateway -Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час запуску запускає `gog gmail watch serve` і автоматично поновлює watch. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися від цього. +Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час запуску запускає `gog gmail watch serve` і автоматично поновлює watch. Щоб відмовитися, встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`. ### Ручне одноразове налаштування - Виберіть проєкт GCP, якому належить клієнт OAuth, що використовується `gog`: + Виберіть проєкт GCP, якому належить OAuth client, що використовується `gog`: ```bash gcloud auth login @@ -350,28 +350,28 @@ openclaw webhooks gmail setup --account openclaw@gmail.com ## Керування завданнями ```bash -# Перелічити всі завдання +# List all jobs openclaw cron list -# Показати одне завдання, включно з визначеним маршрутом доставки +# Show one job, including resolved delivery route openclaw cron show -# Відредагувати завдання +# Edit a job openclaw cron edit --message "Updated prompt" --model "opus" -# Примусово запустити завдання зараз +# Force run a job now openclaw cron run -# Запустити лише якщо час настав +# Run only if due openclaw cron run --due -# Переглянути історію запусків +# View run history openclaw cron runs --id --limit 50 -# Видалити завдання +# Delete a job openclaw cron remove -# Вибір агента (конфігурації з кількома агентами) +# Agent selection (multi-agent setups) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` @@ -381,8 +381,8 @@ openclaw cron edit --clear-agent - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. - Якщо модель дозволена, саме цей провайдер/модель потрапляє до ізольованого запуску агента. -- Якщо вона не дозволена, cron показує попередження і повертається до вибору моделі агента/типової моделі завдання. -- Налаштовані ланцюжки fallback як і раніше застосовуються, але просте перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. +- Якщо вона не дозволена, cron видає попередження і повертається до вибору моделі агента/за замовчуванням для завдання. +- Налаштовані ланцюжки резервних варіантів, як і раніше, застосовуються, але звичайне перевизначення `--model` без явного списку резервних варіантів для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. ## Конфігурація @@ -405,29 +405,29 @@ openclaw cron edit --clear-agent } ``` -`maxConcurrentRuns` обмежує як запланований dispatch cron, так і виконання ізольованих тактів агента. Ізольовані такти агента cron внутрішньо використовують окрему чергу виконання `cron-nested`, тому збільшення цього значення дає змогу незалежним cron-запускам LLM просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна некронова смуга `nested` цим параметром не розширюється. +`maxConcurrentRuns` обмежує як запланований запуск cron, так і виконання ізольованого ходу агента. Ізольовані ходи агента cron внутрішньо використовують окрему чергу виконання `cron-nested`, тому збільшення цього значення дає змогу незалежним cron-запускам LLM виконуватися паралельно, а не лише запускати свої зовнішні оболонки cron. Спільна не-cron доріжка `nested` цим параметром не розширюється. -Стан runtime у sidecar-файлі визначається на основі `cron.store`: для сховища `.json`, такого як `~/clawd/cron/jobs.json`, використовується `~/clawd/cron/jobs-state.json`, а для шляху сховища без суфікса `.json` додається `-state.json`. +Сайдкар стану середовища виконання виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища без суфікса `.json` додається `-state.json`. -Якщо ви редагуєте `jobs.json` вручну, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка повідомляє планувальнику, коли завданню, відредагованому поза системою, потрібен новий `nextRunAtMs`. +Якщо ви редагуєте `jobs.json` вручну, не включайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка підказує планувальнику, коли завданню, відредагованому зовні, потрібен новий `nextRunAtMs`. -Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. +Щоб вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. - **Повторна спроба одноразового завдання**: тимчасові помилки (ліміт швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикають завдання негайно. + **Повторна спроба для одноразового завдання**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів із експоненційною затримкою. Постійні помилки відразу вимикають завдання. - **Повторна спроба періодичного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску. + **Повторна спроба для періодичного завдання**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску затримка скидається. - `cron.sessionRetention` (типово `24h`) очищує записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищують файли журналів запусків. + `cron.sessionRetention` (типове значення `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналів запусків. -## Усунення несправностей +## Усунення проблем -### Ланцюжок команд +### Послідовність команд ```bash openclaw status @@ -443,33 +443,33 @@ openclaw doctor - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. - - Переконайтеся, що Gateway працює безперервно. - - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. - - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due` і час завдання ще не настав. + - Підтвердьте, що Gateway працює безперервно. + - Для розкладів `cron` перевірте часовий пояс (`--tz`) відносно часового поясу хоста. + - `reason: not-due` у виводі запуску означає, що ручний запуск був перевірений через `openclaw cron run --due`, але час виконання завдання ще не настав. - - Режим доставки `none` означає, що резервне надсилання з боку виконавця не очікується. Агент усе ще може надсилати повідомлення напряму через інструмент `message`, коли доступний маршрут чату. - - Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідну доставку було пропущено. - - Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, записаними в нижньому регістрі, можуть не працювати, оскільки ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` із Matrix. - - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку було заблоковано обліковими даними. - - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також резервний шлях queued summary, тому в чат нічого не буде опубліковано. - - Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` з попереднім чатом або явний канал/ціль). + - Режим доставки `none` означає, що резервне надсилання з боку runner не очікується. Агент усе ще може надсилати безпосередньо за допомогою інструмента `message`, коли маршрут чату доступний. + - Відсутня або недійсна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущене. + - Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, перетвореними в нижній регістр, можуть не працювати, оскільки room ID в Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` з Matrix. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку заблокували облікові дані. + - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне надсилання, а також резервний шлях підсумку в черзі, тому назад у чат нічого не публікується. + - Якщо агент має сам написати користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явно вказаний канал/ціль). - - - Актуальність щоденного скидання та скидання за неактивністю не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). - - Пробудження cron, запуски heartbeat, сповіщення exec і службові операції gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. - - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії в JSONL transcript, якщо файл усе ще доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як базу неактивності. + + - Актуальність щоденного скидання та скидання за бездіяльністю не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). + - Пробудження cron, запуски heartbeat, сповіщення exec і службові записи gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. + - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії в transcript JSONL, якщо файл усе ще доступний. Для застарілих неактивних рядків без `lastInteractionAt` OpenClaw використовує цей відновлений час початку як базову точку бездіяльності. - + - Cron без `--tz` використовує часовий пояс хоста gateway. - Розклади `at` без часового поясу трактуються як UTC. - - `activeHours` Heartbeat використовує налаштоване визначення часового поясу. + - `activeHours` у Heartbeat використовує налаштоване визначення часового поясу. ## Пов’язане -- [Автоматизація і завдання](/uk/automation) — усі механізми автоматизації з одного погляду +- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації з першого погляду - [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron -- [Heartbeat](/uk/gateway/heartbeat) — періодичні такти основної сесії +- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії - [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 0c706a24e..35681afb0 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,38 +1,38 @@ --- read_when: - - Ви створюєте новий плагін провайдера моделей - - Ви хочете додати сумісний з OpenAI проксі або власну LLM до OpenClaw - - Вам потрібно зрозуміти автентифікацію провайдера, каталоги та хуки середовища виконання + - Ви створюєте новий Plugin постачальника моделей + - Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw + - Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime-хуки sidebarTitle: Provider plugins -summary: Покроковий посібник зі створення плагіна провайдера моделей для OpenClaw -title: Створення плагінів провайдерів +summary: Покроковий посібник зі створення Plugin постачальника моделей для OpenClaw +title: Створення Plugin постачальників моделей x-i18n: - generated_at: "2026-04-27T11:02:16Z" + generated_at: "2026-04-27T20:43:56Z" model: gpt-5.4 provider: openai - source_hash: 4cd037c179a28ede6da91976cc886d062265e6223081da8bd19641fc20ccfedb + source_hash: 9a4f0d0bed655ccda7ce2731270999d46d83f29b89d5e8ba80832992161eb993 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -Цей посібник покроково показує, як створити плагін провайдера, який додає до OpenClaw провайдера моделей -(LLM). У результаті ви отримаєте провайдера з каталогом моделей, +Цей посібник описує створення Plugin постачальника, який додає постачальника +моделей (LLM) до OpenClaw. Наприкінці ви матимете постачальника з каталогом моделей, автентифікацією через API-ключ і динамічним визначенням моделей. - Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Початок роботи](/uk/plugins/building-plugins) для базової структури - пакета та налаштування маніфесту. + Якщо ви раніше не створювали жодного Plugin для OpenClaw, спочатку прочитайте + [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою + структурою пакета та налаштуванням маніфесту. - Плагіни провайдерів додають моделі до звичайного циклу inference в OpenClaw. Якщо модель - має працювати через нативний демон агента, який володіє гілками, Compaction або подіями - інструментів, поєднайте провайдера з [agent harness](/uk/plugins/sdk-agent-harness), - а не виносьте деталі протоколу демона в ядро. + Plugin постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель + має працювати через нативний демон агента, який керує потоками, Compaction або + подіями інструментів, поєднайте постачальника з [обв’язкою агента](/uk/plugins/sdk-agent-harness), + а не виносьте деталі протоколу демона в core. -## Покроковий приклад +## Покроковий посібник @@ -94,17 +94,17 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження середовища виконання вашого плагіна. Додавайте `providerAuthAliases`, - коли варіант провайдера має повторно використовувати auth іншого ID провайдера. `modelSupport` - необов’язковий і дає OpenClaw змогу автоматично завантажувати ваш плагін провайдера зі скорочених - ID моделей, як-от `acme-large`, ще до появи хуків середовища виконання. Якщо ви публікуєте - провайдера в ClawHub, поля `openclaw.compat` і `openclaw.build` + облікові дані без завантаження runtime вашого Plugin. Додавайте `providerAuthAliases`, + коли варіант постачальника має повторно використовувати автентифікацію іншого id постачальника. `modelSupport` + є необов’язковим і дає OpenClaw змогу автоматично завантажити ваш Plugin постачальника зі скорочених + id моделей, таких як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте + постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build` у `package.json` є обов’язковими. - - Мінімальному провайдеру потрібні `id`, `label`, `auth` і `catalog`: + + Мінімальному постачальнику потрібні `id`, `label`, `auth` і `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -175,11 +175,11 @@ x-i18n: }); ``` - Це вже робочий провайдер. Тепер користувачі можуть виконати + Це вже робочий постачальник. Тепер користувачі можуть виконати `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Якщо вищерозташований провайдер використовує інші керівні токени, ніж OpenClaw, додайте + Якщо постачальник upstream використовує інші керувальні токени, ніж OpenClaw, додайте невелике двонапрямне текстове перетворення замість заміни шляху потоку: ```typescript @@ -197,13 +197,13 @@ x-i18n: }); ``` - `input` переписує фінальний системний промпт і текстовий вміст повідомлень перед - передаванням. `output` переписує текстові дельти асистента та фінальний текст до того, - як OpenClaw розбере власні керівні маркери або доставку каналом. + `input` переписує фінальний системний prompt і вміст текстових повідомлень перед + передаванням. `output` переписує текстові дельти асистента та фінальний текст перед тим, як + OpenClaw розбере власні керувальні маркери або доставку каналу. - Для вбудованих провайдерів, які реєструють лише одного текстового провайдера з - автентифікацією через API-ключ і одним середовищем виконання на основі каталогу, краще - використовувати вужчий хелпер `defineSingleProviderPluginEntry(...)`: + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з + автентифікацією через API-ключ і одним runtime на основі каталогу, надавайте перевагу + вужчому helper `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -244,31 +244,32 @@ x-i18n: ``` `buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити реальну - автентифікацію провайдера. Він може виконувати специфічне для провайдера виявлення. Використовуйте - `buildStaticProvider` лише для офлайнових рядків, які безпечно показувати до налаштування auth; - він не повинен вимагати облікових даних або робити мережеві запити. - Поточне відображення `models list --all` в OpenClaw виконує статичні каталоги - лише для вбудованих плагінів провайдерів, з порожньою конфігурацією, порожнім env і без + автентифікацію постачальника. Він може виконувати специфічне для постачальника виявлення. + Використовуйте `buildStaticProvider` лише для офлайн-рядків, які безпечно показувати до налаштування + автентифікації; він не повинен вимагати облікових даних або виконувати мережеві запити. + Поточне відображення OpenClaw `models list --all` виконує статичні каталоги + лише для вбудованих Plugin постачальників, з порожньою конфігурацією, порожнім env і без шляхів агента/робочого простору. - Якщо ваш потік auth також має змінювати `models.providers.*`, псевдоніми та - типову модель агента під час онбордингу, використовуйте готові хелпери з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери: + Якщо вашому процесу автентифікації також потрібно оновлювати `models.providers.*`, + псевдоніми та модель агента за замовчуванням під час onboarding, використовуйте готові helper-и з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі helper-и: `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативна кінцева точка провайдера підтримує потокові блоки usage на - звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з - `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко кодуйте перевірки ID - провайдера. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з мапи можливостей кінцевої точки, - тож нативні кінцеві точки у стилі Moonshot/DashScope теж підключаються, навіть якщо плагін використовує власний ID провайдера. + Коли нативний endpoint постачальника підтримує потокові блоки використання в + звичайному транспорті `openai-completions`, надавайте перевагу спільним helper-ам каталогу з + `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко прописуйте перевірки provider-id. + `supportsNativeStreamingUsageCompat(...)` і + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, + тож нативні endpoint-и на кшталт Moonshot/DashScope усе одно можуть бути ввімкнені, навіть коли Plugin використовує + власний id постачальника. - - Якщо ваш провайдер приймає довільні ID моделей (наприклад, проксі або маршрутизатор), + + Якщо ваш постачальник приймає довільні id моделей (наприклад, проксі або маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -291,16 +292,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - прогріву — після його завершення `resolveDynamicModel` запускається знову. + прогріву — після його завершення `resolveDynamicModel` буде виконано знову. - - Більшості провайдерів потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки - поступово, у міру того як цього потребуватиме ваш провайдер. + + Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки + поступово, у міру того як цього вимагатиме ваш постачальник. - Спільні конструктори хелперів тепер покривають найпоширеніші сімейства сумісності replay/tool, - тож плагінам зазвичай не потрібно вручну підключати кожен хук окремо: + Спільні builder-helper-и тепер охоплюють найпоширеніші сімейства replay/tool-compat, + тому Plugin зазвичай не потрібно вручну підключати кожен хук окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -320,43 +321,43 @@ x-i18n: }); ``` - Доступні сьогодні сімейства replay: + Наразі доступні такі сімейства replay: - | Family | Що саме він підключає | Приклади у вбудованих | + | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, зокрема санітизація tool-call-id, виправлення порядку assistant-first і загальна перевірка Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | - | `anthropic-by-model` | Політика replay з урахуванням Claude, яка вибирається за `modelId`, тому транспорти повідомлень Anthropic отримують очищення thinking-блоків, специфічне для Claude, лише коли визначена модель справді є Claude ID | `amazon-bedrock`, `anthropic-vertex` | - | `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим tagged reasoning-output | `google`, `google-gemini-cli` | - | `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну перевірку replay Gemini або переписування bootstrap | `openrouter`, `kilocode`, `opencode`, `opencode-go` | - | `hybrid-anthropic-openai` | Гібридна політика для провайдерів, які поєднують поверхні моделей Anthropic-message та OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-блоків лише для Claude лишається обмеженим стороною Anthropic | `minimax` | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | + | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти повідомлень Anthropic отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді є id Claude | `amazon-bedrock`, `anthropic-vertex` | + | `google-gemini` | Нативна політика replay Gemini плюс початкове очищення replay і режим тегованого reasoning-output | `google`, `google-gemini-cli` | + | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або початкові переписування | `openrouter`, `kilocode`, `opencode`, `opencode-go` | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному Plugin; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | `minimax` | - Доступні сьогодні сімейства потоків: + Наразі доступні такі сімейства потоків: - | Family | Що саме він підключає | Приклади у вбудованих | + | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху потоку | `google`, `google-gemini-cli` | - | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані proxy reasoning ID пропускають впроваджений thinking | `kilocode` | - | `moonshot-thinking` | Мапінг payload нативного binary thinking Moonshot із конфігурації та рівня `/think` | `moonshot` | - | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху потоку | `minimax`, `minimax-portal` | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution headers, `/fast`/`serviceTier`, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності reasoning та керування контекстом Responses | `openai`, `openai-codex` | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів із централізованою обробкою пропусків unsupported-model/`auto` | `openrouter` | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для провайдерів на кшталт Z.AI, які хочуть потокове передавання інструментів, якщо його явно не вимкнено | `zai` | + | `google-thinking` | Нормалізація payload thinking Gemini у спільному шляху потоку | `google`, `google-gemini-cli` | + | `kilocode-thinking` | Обгортка reasoning Kilo у спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані proxy reasoning id пропускають ін’єкцію thinking | `kilocode` | + | `moonshot-thinking` | Мапінг бінарного payload native-thinking Moonshot із config + рівня `/think` | `moonshot` | + | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode у спільному шляху потоку | `minimax`, `minimax-portal` | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, текстова verbosity, нативний вебпошук Codex, формування payload reasoning-compat і керування контекстом Responses | `openai`, `openai-codex` | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, із централізованою обробкою пропусків unsupported-model/`auto` | `openrouter` | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її явно не вимкнено | `zai` | - - Кожен конструктор сімейства складається з нижчорівневих публічних хелперів, експортованих із того самого пакета; їх можна використовувати, коли провайдеру потрібно вийти за межі типового шаблону: + + Кожен builder сімейства складається з публічних helper-ів нижчого рівня, експортованих із того самого пакета, до яких можна звернутися, коли постачальнику потрібно вийти за межі типового шаблону: - - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і сирі конструктори replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує хелпери replay Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і хелпери endpoint/model (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). - - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), OpenAI-compatible обгортка DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`) і спільні proxy/provider обгортки (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). - - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові хелпери схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і хелпери сумісності xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований плагін xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у власності провайдера. + - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і необроблені builder-и replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує helper-и replay Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і helper-и endpoint/моделей (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). + - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), OpenAI-compatible-обгортка DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), очищення prefill payload thinking для Anthropic Messages (`createAnthropicThinkingPrefillPayloadWrapper`) і спільні обгортки proxy/постачальників (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). + - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові helper-и схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і helper-и сумісності xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований Plugin xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у власності постачальника. - Деякі потокові хелпери навмисно залишаються локальними для провайдера. `@openclaw/anthropic-provider` зберігає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі конструктори обгорток Anthropic у власному публічному seam `api.ts` / `contract-api.ts`, тому що вони кодують обробку бета-версій Claude OAuth і gating `context1m`. Плагін xAI так само зберігає формування нативних xAI Responses у власному `wrapStreamFn` (псевдоніми `/fast`, типовий `tool_stream`, очищення unsupported strict-tool, видалення payload reasoning, специфічне для xAI). + Деякі helper-и потоку навмисно залишаються локальними для постачальника. `@openclaw/anthropic-provider` тримає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і builder-и обгорток Anthropic нижчого рівня у власному публічному шві `api.ts` / `contract-api.ts`, оскільки вони кодують обробку Claude OAuth beta і gating `context1m`. Plugin xAI так само зберігає нативне формування xAI Responses у власному `wrapStreamFn` (псевдоніми `/fast`, `tool_stream` за замовчуванням, очищення unsupported strict-tool, видалення payload reasoning, специфічне для xAI). - Той самий шаблон кореня пакета також лежить в основі `@openclaw/openai-provider` (конструктори провайдера, хелпери типової моделі, конструктори realtime-провайдера) і `@openclaw/openrouter-provider` (конструктор провайдера плюс хелпери onboarding/config). + Такий самий шаблон на рівні кореня пакета також лежить в основі `@openclaw/openai-provider` (builder-и постачальників, helper-и моделей за замовчуванням, builder-и realtime-постачальників) і `@openclaw/openrouter-provider` (builder постачальника плюс helper-и onboarding/config). - Для провайдерів, яким потрібен обмін токенами перед кожним викликом inference: + Для постачальників, яким потрібен обмін токенами перед кожним викликом інференсу: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -370,7 +371,7 @@ x-i18n: ``` - Для провайдерів, яким потрібні власні заголовки запитів або модифікації тіла: + Для постачальників, яким потрібні власні заголовки запиту або зміни тіла: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -388,8 +389,8 @@ x-i18n: ``` - Для провайдерів, яким потрібні нативні заголовки запиту/сесії або метадані на - універсальних HTTP- або WebSocket-транспортах: + Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в + узагальнених транспортних механізмах HTTP або WebSocket: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -410,7 +411,7 @@ x-i18n: ``` - Для провайдерів, які надають дані про використання/білінг: + Для постачальників, які надають дані про використання/білінг: ```typescript resolveUsageAuth: async (ctx) => { @@ -424,77 +425,77 @@ x-i18n: - - OpenClaw викликає хуки в такому порядку. Більшості провайдерів потрібні лише 2–3: + + OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2–3: - | # | Hook | Коли використовувати | + | # | Хук | Коли використовувати | | --- | --- | --- | - | 1 | `catalog` | Каталог моделей або типові значення base URL | - | 2 | `applyConfigDefaults` | Глобальні типові значення, якими володіє провайдер, під час матеріалізації конфігурації | - | 3 | `normalizeModelId` | Очищення застарілих/preview-псевдонімів model-id перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства провайдера перед складанням загальної моделі | - | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування сумісності нативного потокового usage для конфігурованих провайдерів | - | 7 | `resolveConfigApiKey` | Визначення auth за env-marker, яким володіє провайдер | - | 8 | `resolveSyntheticAuth` | Синтетична auth для локальних/self-hosted або конфігураційних випадків | - | 9 | `shouldDeferSyntheticProfileAuth` | Опускати синтетичні placeholder-и збережених профілів нижче auth з env/config | - | 10 | `resolveDynamicModel` | Приймати довільні ID моделей від вищого рівня | + | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | + | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization конфігурації | + | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів model-id перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним збиранням моделі | + | 5 | `normalizeConfig` | Нормалізація config `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Переписування сумісності native streaming-usage для config-постачальників | + | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або config-backed сценарію | + | 9 | `shouldDeferSyntheticProfileAuth` | Пониження пріоритету synthetic placeholder-ів збереженого профілю нижче за автентифікацію env/config | + | 10 | `resolveDynamicModel` | Прийом довільних upstream model id | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | - | 12 | `normalizeResolvedModel` | Переписування транспорту перед раннером | - | 13 | `contributeResolvedModelCompat` | Прапорці сумісності для моделей постачальника за іншим сумісним транспортом | + | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | + | 13 | `contributeResolvedModelCompat` | Прапорці сумісності для моделей постачальника, що працюють через інший сумісний транспорт | | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення схем інструментів, яким володіє провайдер, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика схем інструментів, якою володіє провайдер | + | 15 | `normalizeToolSchemas` | Очищення схем інструментів, що належить постачальнику, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належить постачальнику | | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output | - | 18 | `prepareExtraParams` | Типові параметри запиту | + | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | | 19 | `createStreamFn` | Повністю власний транспорт StreamFn | - | 20 | `wrapStreamFn` | Обгортки власних заголовків/тіла на звичайному шляху потоку | - | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного ходу | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS/cool-down | - | 23 | `formatApiKey` | Власна форма токена середовища виконання | + | 20 | `wrapStreamFn` | Обгортки власних заголовків/тіла у звичайному шляху потоку | + | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cooldown | + | 23 | `formatApiKey` | Власна форма runtime-токена | | 24 | `refreshOAuth` | Власне оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Поради щодо відновлення auth | - | 26 | `matchesContextOverflowError` | Визначення переповнення, яким володіє провайдер | - | 27 | `classifyFailoverReason` | Класифікація rate-limit/перевантаження, якою володіє провайдер | - | 28 | `isCacheTtlEligible` | Gating TTL кешу промптів | - | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню auth | - | 30 | `suppressBuiltInModel` | Приховати застарілі рядки від вищого рівня | + | 25 | `buildAuthDoctorHint` | Підказка для виправлення автентифікації | + | 26 | `matchesContextOverflowError` | Визначення переповнення, що належить постачальнику | + | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | + | 28 | `isCacheTtlEligible` | Гейтинг TTL кешу prompt-ів | + | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Приховування застарілих upstream-рядків | | 31 | `augmentModelCatalog` | Синтетичні рядки прямої сумісності з майбутніми версіями | - | 32 | `resolveThinkingProfile` | Набір параметрів `/think`, специфічний для моделі | - | 33 | `isBinaryThinking` | Сумісність binary thinking увімк./вимк. | - | 34 | `supportsXHighThinking` | Сумісність підтримки reasoning `xhigh` | - | 35 | `resolveDefaultThinkingLevel` | Сумісність типової політики `/think` | - | 36 | `isModernModelRef` | Відповідність live/smoke-моделей | - | 37 | `prepareRuntimeAuth` | Обмін токенами перед inference | - | 38 | `resolveUsageAuth` | Власний розбір облікових даних usage | - | 39 | `fetchUsageSnapshot` | Власна кінцева точка usage | - | 40 | `createEmbeddingProvider` | Адаптер вбудовувань для пам’яті/пошуку, яким володіє провайдер | - | 41 | `buildReplayPolicy` | Власна політика replay/Compaction транскриптів | - | 42 | `sanitizeReplayHistory` | Переписування replay, специфічне для провайдера, після загального очищення | - | 43 | `validateReplayTurns` | Сувора перевірка ходів replay перед вбудованим раннером | - | 44 | `onModelSelected` | Зворотний виклик після вибору (наприклад, телеметрія) | + | 32 | `resolveThinkingProfile` | Набір опцій `/think`, специфічний для моделі | + | 33 | `isBinaryThinking` | Сумісність із двійковим thinking увімк./вимк. | + | 34 | `supportsXHighThinking` | Сумісність із reasoning `xhigh` | + | 35 | `resolveDefaultThinkingLevel` | Сумісність із політикою `/think` за замовчуванням | + | 36 | `isModernModelRef` | Відповідність моделі для live/smoke | + | 37 | `prepareRuntimeAuth` | Обмін токенами перед інференсом | + | 38 | `resolveUsageAuth` | Власний розбір облікових даних використання | + | 39 | `fetchUsageSnapshot` | Власний endpoint використання | + | 40 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку | + | 41 | `buildReplayPolicy` | Власна політика replay/Compaction транскрипту | + | 42 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | + | 43 | `validateReplayTurns` | Сувора валідація turn-ів replay перед вбудованим runner | + | 44 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) | - Примітки щодо резервного переходу під час виконання: + Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідний провайдер, а потім інші плагіни провайдерів із підтримкою хуків, доки хтось справді не змінить конфігурацію. Якщо жоден хук провайдера не переписує підтримуваний запис конфігурації сімейства Google, усе одно застосовується вбудований нормалізатор конфігурації Google. - - `resolveConfigApiKey` використовує хук провайдера, коли він доступний. Вбудований шлях `amazon-bedrock` також має вбудований AWS env-marker resolver саме тут, хоча автентифікація середовища виконання Bedrock, як і раніше, використовує типовий ланцюжок AWS SDK. - - `resolveSystemPromptContribution` дозволяє провайдеру впроваджувати cache-aware вказівки для системного промпту сімейства моделей. Віддавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному провайдеру/сімейству моделей і має зберігати стабільний/динамічний поділ кешу. + - `normalizeConfig` спочатку перевіряє відповідний постачальник, потім інші Plugin постачальників із підтримкою хуків, доки якийсь із них справді не змінить config. Якщо жоден хук постачальника не перепише підтримуваний запис config сімейства Google, усе ще застосовується вбудований normalizer config Google. + - `resolveConfigApiKey` використовує хук постачальника, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, хоча runtime-автентифікація Bedrock досі використовує стандартний ланцюжок AWS SDK. + - `resolveSystemPromptContribution` дозволяє постачальнику ін’єктувати підказки системного prompt, чутливі до кешу, для сімейства моделей. Надавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному постачальнику/сімейству моделей і має зберігати стабільний/динамічний поділ кешу. - Докладні описи й реальні приклади дивіться в [Внутрішні механізми: хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). + Докладні описи та приклади з реального світу дивіться в [Внутрішня архітектура: runtime-хуки постачальників](/uk/plugins/architecture-internals#provider-runtime-hooks). - Плагін провайдера може реєструвати синтез мовлення, транскрипцію в реальному часі, realtime - voice, розуміння медіа, генерацію зображень, генерацію відео, web fetch - і web search поряд зі звичайним текстовим inference. OpenClaw класифікує це як - плагін **hybrid-capability** — рекомендований шаблон для корпоративних плагінів - (один плагін на постачальника). Див. - [Внутрішні механізми: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). + Plugin постачальника може реєструвати мовлення, realtime-транскрипцію, realtime-голос, + розуміння медіа, генерацію зображень, генерацію відео, web fetch + і web search поряд із текстовим інференсом. OpenClaw класифікує це як + Plugin **hybrid-capability** — рекомендований шаблон для корпоративних Plugin + (один Plugin на постачальника). Див. + [Внутрішня архітектура: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). - Реєструйте кожну можливість усередині `register(api)` поряд із наявним - викликом `api.registerProvider(...)`. Вибирайте лише ті вкладки, які вам потрібні: + Реєструйте кожну можливість усередині `register(api)` поруч із вашим наявним + викликом `api.registerProvider(...)`. Обирайте лише ті вкладки, які вам потрібні: @@ -532,14 +533,14 @@ x-i18n: }); ``` - Використовуйте `assertOkOrThrowProviderError(...)` для HTTP-збоїв провайдера, щоб - плагіни спільно використовували обмежене читання тіла помилки, розбір JSON-помилок і + Використовуйте `assertOkOrThrowProviderError(...)` для HTTP-збоїв постачальника, щоб + Plugin спільно використовували обмежене читання тіла помилки, розбір JSON-помилок і суфікси request-id. - - Віддавайте перевагу `createRealtimeTranscriptionWebSocketSession(...)` — спільний - хелпер обробляє захоплення проксі, backoff повторних підключень, flush під час закриття, ready-handshake, - постановку аудіо в чергу та діагностику подій закриття. Ваш плагін лише відображає події вищого рівня. + + Надавайте перевагу `createRealtimeTranscriptionWebSocketSession(...)` — цей спільний + helper обробляє захоплення проксі, backoff повторного підключення, flush під час закриття, ready-handshake, постановку аудіо в чергу та діагностику подій закриття. Ваш Plugin + лише зіставляє upstream-події. ```typescript api.registerRealtimeTranscriptionProvider({ @@ -577,13 +578,13 @@ x-i18n: }); ``` - Провайдери пакетної STT, які надсилають multipart-аудіо через POST, мають використовувати + Пакетні STT-постачальники, які надсилають multipart-аудіо через POST, мають використовувати `buildAudioTranscriptionFormData(...)` з - `openclaw/plugin-sdk/provider-http`. Хелпер нормалізує - імена файлів завантаження, зокрема AAC-завантаження, яким для - сумісних API транскрипції потрібне ім’я файла у стилі M4A. + `openclaw/plugin-sdk/provider-http`. Цей helper нормалізує + імена файлів для завантаження, зокрема AAC-завантаження, яким потрібне ім’я файлу у стилі M4A для + сумісних API транскрипції. - + ```typescript api.registerRealtimeVoiceProvider({ id: "acme-ai", @@ -616,11 +617,11 @@ x-i18n: ``` - Можливості відео використовують **mode-aware** форму: `generate`, + Можливості відео використовують форму з **урахуванням режиму**: `generate`, `imageToVideo` і `videoToVideo`. Плоских агрегованих полів на кшталт - `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` недостатньо, щоб чисто оголосити - підтримку режимів перетворення або вимкнені режими. - Генерація музики використовує той самий шаблон із явними блоками `generate` / + `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` недостатньо, + щоб коректно оголошувати підтримку режиму transform або чисто вимикати режими. + Генерація музики дотримується того самого шаблону з явними блоками `generate` / `edit`. ```typescript @@ -717,49 +718,49 @@ x-i18n: ## Публікація в ClawHub -Плагіни провайдерів публікуються так само, як і будь-які інші зовнішні кодові плагіни: +Plugin постачальників публікуються так само, як і будь-який інший зовнішній Plugin коду: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий псевдонім публікації лише для skill; пакети плагінів повинні використовувати +Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети Plugin повинні використовувати `clawhub package publish`. ## Структура файлів ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with provider auth metadata +├── package.json # metadata openclaw.providers +├── openclaw.plugin.json # Маніфест із metadata автентифікації постачальника ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # Тести + └── usage.ts # Endpoint використання (необов’язково) ``` -## Довідник порядку каталогу +## Довідник порядку каталогів -`catalog.order` визначає, коли ваш каталог об’єднується відносно вбудованих -провайдерів: +`catalog.order` визначає, коли ваш каталог буде об’єднано відносно вбудованих +постачальників: -| Order | Коли | Випадок використання | -| --------- | ------------- | ---------------------------------------------- | -| `simple` | Перший прохід | Звичайні провайдери з API-ключем | -| `profile` | Після simple | Провайдери, обмежені профілями auth | -| `paired` | Після profile | Синтез кількох пов’язаних записів | -| `late` | Останній прохід | Перевизначення наявних провайдерів (перемагає при конфлікті) | +| Порядок | Коли | Випадок використання | +| --------- | ------------- | ----------------------------------------------- | +| `simple` | Перший прохід | Звичайні постачальники з API-ключем | +| `profile` | Після simple | Постачальники, обмежені профілями автентифікації | +| `paired` | Після profile | Синтез кількох пов’язаних записів | +| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) | ## Наступні кроки -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал -- [Середовище виконання SDK](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, пошук, субагент) -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту підшляхів -- [Внутрішні механізми плагінів](/uk/plugins/architecture-internals#provider-runtime-hooks) — деталі хуків і приклади вбудованих плагінів +- [Plugin каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш Plugin також надає канал +- [SDK Runtime](/uk/plugins/sdk-runtime) — helper-и `api.runtime` (TTS, search, subagent) +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath +- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals#provider-runtime-hooks) — подробиці про хуки та вбудовані приклади ## Пов’язане - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення плагінів](/uk/plugins/building-plugins) -- [Створення плагінів каналів](/uk/plugins/sdk-channel-plugins) +- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення Plugin каналів](/uk/plugins/sdk-channel-plugins) diff --git a/docs/uk/providers/cloudflare-ai-gateway.md b/docs/uk/providers/cloudflare-ai-gateway.md index abc677099..0d8d1fc6f 100644 --- a/docs/uk/providers/cloudflare-ai-gateway.md +++ b/docs/uk/providers/cloudflare-ai-gateway.md @@ -1,45 +1,50 @@ --- read_when: - Ви хочете використовувати Cloudflare AI Gateway з OpenClaw - - Вам потрібен ID облікового запису, ID Gateway або змінна середовища API key + - Вам потрібен ID облікового запису, ID Gateway або змінна середовища ключа API summary: Налаштування Cloudflare AI Gateway (автентифікація + вибір моделі) title: Cloudflare AI gateway x-i18n: - generated_at: "2026-04-23T22:14:39Z" + generated_at: "2026-04-27T20:43:53Z" model: gpt-5.4 provider: openai - source_hash: fb10ef4bd92db88b2b3dac1773439ab2ba37916a72d1925995d74ef787fa1c8b + source_hash: c7c567076a5b3fea0f09f44d772c0858aed2a4813f91f1cc9f87b0da39c2e5db source_path: providers/cloudflare-ai-gateway.md workflow: 15 --- -Cloudflare AI Gateway розташовується перед API провайдерів і дає змогу додавати аналітику, кешування та засоби контролю. Для Anthropic OpenClaw використовує Anthropic Messages API через ваш endpoint Gateway. +Cloudflare AI Gateway розташовується перед API постачальників і дає змогу додавати аналітику, кешування та елементи керування. Для Anthropic OpenClaw використовує Anthropic Messages API через вашу кінцеву точку Gateway. | Властивість | Значення | | ------------- | --------------------------------------------------------------------------------------- | -| Провайдер | `cloudflare-ai-gateway` | -| Базовий URL | `https://gateway.ai.cloudflare.com/v1///anthropic` | -| Модель за замовчуванням | `cloudflare-ai-gateway/claude-sonnet-4-6` | -| API key | `CLOUDFLARE_AI_GATEWAY_API_KEY` (ваш API key провайдера для запитів через Gateway) | +| Постачальник | `cloudflare-ai-gateway` | +| Базова URL | `https://gateway.ai.cloudflare.com/v1///anthropic` | +| Модель за замовчуванням | `cloudflare-ai-gateway/claude-sonnet-4-6` | +| Ключ API | `CLOUDFLARE_AI_GATEWAY_API_KEY` (ваш ключ API постачальника для запитів через Gateway) | -Для моделей Anthropic, маршрутизованих через Cloudflare AI Gateway, використовуйте свій **Anthropic API key** як ключ провайдера. +Для моделей Anthropic, маршрутизованих через Cloudflare AI Gateway, використовуйте ваш **ключ API Anthropic** як ключ постачальника. +Коли для моделей Anthropic Messages увімкнено thinking, OpenClaw видаляє кінцеві +попередньо заповнені ходи assistant перед надсиланням корисного навантаження через Cloudflare AI Gateway. +Anthropic відхиляє попереднє заповнення відповіді з extended thinking, тоді як звичайне +попереднє заповнення без thinking залишається доступним. + ## Початок роботи - + Запустіть онбординг і виберіть варіант автентифікації Cloudflare AI Gateway: ```bash openclaw onboard --auth-choice cloudflare-ai-gateway-api-key ``` - Буде запропоновано ввести ID вашого облікового запису, ID Gateway і API key. + Буде запропоновано ввести ID вашого облікового запису, ID Gateway і ключ API. - + Додайте модель до конфігурації OpenClaw: ```json5 @@ -53,7 +58,7 @@ Cloudflare AI Gateway розташовується перед API провайд ``` - + ```bash openclaw models list --provider cloudflare-ai-gateway ``` @@ -76,8 +81,8 @@ openclaw onboard --non-interactive \ ## Розширена конфігурація - - Якщо ви ввімкнули автентифікацію Gateway у Cloudflare, додайте заголовок `cf-aig-authorization`. Це **додатково до** API key вашого провайдера. + + Якщо ви ввімкнули автентифікацію Gateway у Cloudflare, додайте заголовок `cf-aig-authorization`. Це **додатково до** вашого ключа API постачальника. ```json5 { @@ -94,16 +99,16 @@ openclaw onboard --non-interactive \ ``` - Заголовок `cf-aig-authorization` автентифікує у самому Cloudflare Gateway, тоді як API key провайдера (наприклад, ваш ключ Anthropic) автентифікує у висхідного провайдера. + Заголовок `cf-aig-authorization` виконує автентифікацію із самим Cloudflare Gateway, тоді як ключ API постачальника (наприклад, ваш ключ Anthropic) виконує автентифікацію у висхідного постачальника. - Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `CLOUDFLARE_AI_GATEWAY_API_KEY` доступний цьому процесу. + Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `CLOUDFLARE_AI_GATEWAY_API_KEY` доступний для цього процесу. - Ключ, що зберігається лише в `~/.profile`, не допоможе демону launchd/systemd, якщо це середовище не буде також імпортовано туди. Укажіть ключ у `~/.openclaw/.env` або через `env.shellEnv`, щоб процес Gateway міг його прочитати. + Ключ, який зберігається лише в `~/.profile`, не допоможе демону launchd/systemd, якщо це середовище також не імпортовано туди. Задайте ключ у `~/.openclaw/.env` або через `env.shellEnv`, щоб процес gateway міг його прочитати. @@ -113,7 +118,7 @@ openclaw onboard --non-interactive \ - Вибір провайдерів, посилань на моделі та поведінки failover. + Вибір постачальників, посилань на моделі та поведінки перемикання при збої. Загальне усунення несправностей і поширені запитання. diff --git a/docs/uk/reference/transcript-hygiene.md b/docs/uk/reference/transcript-hygiene.md index f31f41b61..f7e4e7bae 100644 --- a/docs/uk/reference/transcript-hygiene.md +++ b/docs/uk/reference/transcript-hygiene.md @@ -1,62 +1,63 @@ --- read_when: - Ви налагоджуєте відхилення запитів провайдера, пов’язані з формою стенограми - - Ви змінюєте логіку санітизації стенограми або виправлення викликів інструментів + - Ви змінюєте логіку санітизації стенограм або виправлення викликів інструментів - Ви досліджуєте невідповідності ідентифікаторів викликів інструментів між провайдерами summary: 'Довідка: правила санітизації та виправлення стенограм, специфічні для провайдера' title: Гігієна стенограм x-i18n: - generated_at: "2026-04-27T07:31:02Z" + generated_at: "2026-04-27T20:43:55Z" model: gpt-5.4 provider: openai - source_hash: 2836499f6860b0d21a954355850b5a1b89abfc6887df0343a64c12a6be251d29 + source_hash: be3cef051f872ce2fa8d3e8f9db9c0a7d8a413ca2faa286582ce9bb886e92693 source_path: reference/transcript-hygiene.md workflow: 15 --- -OpenClaw застосовує **специфічні для провайдера виправлення** до стенограм перед запуском (побудовою контексту моделі). Більшість із них — це коригування **в пам’яті**, що використовуються для дотримання суворих вимог провайдера. Окремий етап відновлення файлу сесії також може переписувати збережений JSONL до завантаження сесії — або видаляючи некоректні рядки JSONL, або відновлюючи збережені ходи, які є синтаксично коректними, але відомо, що провайдер відхиляє їх під час повторного відтворення. Коли відновлення виконується, оригінальний файл резервно копіюється поруч +OpenClaw застосовує **специфічні для провайдера виправлення** до стенограм перед запуском (побудовою контексту моделі). Більшість із них — це коригування **в пам’яті**, які використовуються для задоволення суворих вимог провайдера. Окремий прохід відновлення файлу сесії також може переписувати збережений JSONL до завантаження сесії — або відкидаючи некоректні рядки JSONL, або виправляючи збережені ходи, які синтаксично коректні, але відомо, що провайдер відхиляє їх під час +повторного відтворення. Коли відновлення виконується, оригінальний файл резервно копіюється поруч із файлом сесії. -Область охоплює: +Обсяг охоплює: -- Контекст підказки лише для часу виконання, який не потрапляє до видимих користувачу ходів стенограми -- Санітизація ідентифікаторів викликів інструментів -- Валідація вхідних даних викликів інструментів +- Контекст підказки лише під час виконання, який не потрапляє до видимих користувачеві ходів стенограми +- Санітизацію ідентифікаторів викликів інструментів +- Валідацію вхідних даних викликів інструментів - Відновлення парування результатів інструментів -- Валідація / упорядкування ходів -- Очищення сигнатур thought +- Валідацію / впорядкування ходів +- Очищення сигнатур думок - Очищення сигнатур thinking -- Санітизація корисного навантаження зображень -- Позначення походження користувацького вводу (для підказок, маршрутизованих між сесіями) -- Відновлення порожніх ходів помилки assistant для повторного відтворення Bedrock Converse +- Санітизацію корисного навантаження зображень +- Позначення походження користувацького вводу (для маршрутованих підказок між сесіями) +- Відновлення порожніх ходів помилок асистента для повторного відтворення Bedrock Converse -Якщо вам потрібні подробиці про зберігання стенограм, дивіться: +Якщо вам потрібні подробиці про зберігання стенограм, див.: -- [Глибоке занурення в керування сесіями](/uk/reference/session-management-compaction) +- [Поглиблений розбір керування сесіями](/uk/reference/session-management-compaction) --- -## Глобальне правило: контекст часу виконання — це не користувацька стенограма +## Глобальне правило: контекст виконання не є користувацькою стенограмою -Контекст часу виконання / системний контекст можна додавати до підказки моделі для ходу, але це -не контент, створений кінцевим користувачем. OpenClaw зберігає окреме -тіло підказки, орієнтоване на стенограму, для відповідей Gateway, followup-дій у черзі, ACP, CLI та вбудованих запусків Pi. Збережені видимі користувацькі ходи використовують це -тіло стенограми замість підказки, збагаченої контекстом часу виконання. +Контекст виконання/системи можна додавати до підказки моделі для ходу, але це +не вміст, створений кінцевим користувачем. OpenClaw зберігає окреме тіло +підказки, орієнтоване на стенограму, для відповідей Gateway, поставлених у чергу подальших дій, ACP, CLI та вбудованих запусків Pi. Збережені видимі ходи користувача використовують це +тіло стенограми замість підказки, збагаченої контекстом виконання. -Для застарілих сесій, які вже зберегли обгортки часу виконання, поверхні історії Gateway -застосовують проєкцію відображення перед поверненням повідомлень до клієнтів WebChat, -TUI, REST або SSE. +Для застарілих сесій, які вже зберегли обгортки часу виконання, поверхні +історії Gateway застосовують проєкцію відображення перед поверненням повідомлень у WebChat, +TUI, REST або SSE-клієнтам. --- ## Де це виконується -Уся гігієна стенограм централізована у вбудованому ранері: +Уся гігієна стенограм централізована у вбудованому раннері: - Вибір політики: `src/agents/transcript-policy.ts` - Застосування санітизації/відновлення: `sanitizeSessionHistory` у `src/agents/pi-embedded-runner/replay-history.ts` -Політика використовує `provider`, `modelApi` і `modelId`, щоб вирішити, що саме застосовувати. +Політика використовує `provider`, `modelApi` і `modelId`, щоб визначити, що застосовувати. Окремо від гігієни стенограм, файли сесій відновлюються (за потреби) перед завантаженням: @@ -67,25 +68,25 @@ TUI, REST або SSE. ## Глобальне правило: санітизація зображень -Корисне навантаження зображень завжди санітизується, щоб запобігти відхиленню з боку провайдера через -обмеження розміру (зменшення масштабу / повторне стиснення завеликих base64-зображень). +Корисне навантаження зображень завжди санітизується, щоб запобігти відхиленню на боці провайдера через обмеження +розміру (зменшення роздільної здатності/повторне стиснення надто великих base64-зображень). -Це також допомагає контролювати тиск токенів, спричинений зображеннями, для моделей із підтримкою зору. -Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталізацію. +Це також допомагає контролювати тиск на токени, спричинений зображеннями, для моделей із підтримкою зору. +Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталі. Реалізація: - `sanitizeSessionMessagesImages` у `src/agents/pi-embedded-helpers/images.ts` - `sanitizeContentBlocksImages` у `src/agents/tool-images.ts` -- Максимальний розмір сторони зображення налаштовується через `agents.defaults.imageMaxDimensionPx` (типово: `1200`). +- Максимальний бік зображення налаштовується через `agents.defaults.imageMaxDimensionPx` (типове значення: `1200`). --- ## Глобальне правило: некоректні виклики інструментів -Блоки викликів інструментів assistant, у яких відсутні і `input`, і `arguments`, видаляються -до побудови контексту моделі. Це запобігає відхиленням з боку провайдера через частково -збережені виклики інструментів (наприклад, після помилки через обмеження частоти запитів). +Блоки викликів інструментів асистента, у яких відсутні і `input`, і `arguments`, відкидаються +до побудови контексту моделі. Це запобігає відхиленням провайдера через частково +збережені виклики інструментів (наприклад, після збою через обмеження швидкості). Реалізація: @@ -94,19 +95,20 @@ TUI, REST або SSE. --- -## Глобальне правило: походження вводу між сесіями +## Глобальне правило: походження міжсесійного вводу Коли агент надсилає підказку в іншу сесію через `sessions_send` (включно з -кроками відповіді/оголошення від агента до агента), OpenClaw зберігає створений користувацький хід із: +кроками відповіді/оголошення від агента до агента), OpenClaw зберігає створений хід користувача з: - `message.provenance.kind = "inter_session"` Ці метадані записуються під час додавання до стенограми і не змінюють роль -(`role: "user"` залишається для сумісності з провайдером). Читачі стенограм можуть використовувати -це, щоб не трактувати маршрутизовані внутрішні підказки як інструкції, створені кінцевим користувачем. +(`role: "user"` зберігається для сумісності з провайдерами). Читачі стенограм можуть +використовувати це, щоб не трактувати маршрутовані внутрішні підказки як інструкції, +створені кінцевим користувачем. -Під час повторної побудови контексту OpenClaw також додає на початку короткий маркер `[Inter-session message]` -до таких користувацьких ходів у пам’яті, щоб модель могла відрізняти їх від +Під час перебудови контексту OpenClaw також додає короткий маркер `[Inter-session message]` +на початок таких користувацьких ходів у пам’яті, щоб модель могла відрізняти їх від зовнішніх інструкцій кінцевого користувача. --- @@ -116,50 +118,52 @@ TUI, REST або SSE. **OpenAI / OpenAI Codex** - Лише санітизація зображень. -- Видалення осиротілих reasoning-сигнатур (окремі елементи reasoning без наступного блоку контенту) для стенограм OpenAI Responses/Codex, а також видалення відтворюваного OpenAI reasoning після перемикання маршруту моделі. +- Відкидання сирітських сигнатур міркування (окремих елементів reasoning без наступного блоку вмісту) для стенограм OpenAI Responses/Codex, а також відкидання відтворюваних міркувань OpenAI після перемикання маршруту моделі. - Без санітизації ідентифікаторів викликів інструментів. -- Відновлення парування результатів інструментів може переміщувати реальні відповідні виводи та синтезувати виводи у стилі Codex зі статусом `aborted` для відсутніх викликів інструментів. -- Без валідації або перевпорядкування ходів. -- Відсутні виводи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex. -- Без видалення thought-сигнатур. +- Відновлення парування результатів інструментів може переміщувати реальні відповідні виходи та синтезувати виходи `aborted` у стилі Codex для відсутніх викликів інструментів. +- Без валідації чи перевпорядкування ходів. +- Відсутні виходи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex. +- Без видалення сигнатур думок. **OpenAI-compatible Gemma 4** -- Історичні блоки thinking/reasoning assistant видаляються перед повторним відтворенням, щоб локальні - OpenAI-compatible сервери Gemma 4 не отримували reasoning-контент попередніх ходів. -- Продовження викликів інструментів у межах поточного того ж ходу зберігають reasoning-блок assistant, - прив’язаний до виклику інструмента, доки не буде повторно відтворено результат інструмента. +- Історичні блоки thinking/reasoning асистента видаляються перед повторним відтворенням, щоб локальні + OpenAI-compatible сервери Gemma 4 не отримували вміст міркувань із попередніх ходів. +- Продовження викликів інструментів у поточному тому самому ході зберігають блок reasoning асистента + прикріпленим до виклику інструмента, доки не буде повторно відтворено результат інструмента. **Google (Generative AI / Gemini CLI / Antigravity)** - Санітизація ідентифікаторів викликів інструментів: суворо буквено-цифрові. - Відновлення парування результатів інструментів і синтетичні результати інструментів. - Валідація ходів (чергування ходів у стилі Gemini). -- Виправлення порядку ходів Google (додавання на початок крихітного bootstrap-користувача, якщо історія починається з assistant). -- Antigravity Claude: нормалізація thinking-сигнатур; видалення непідписаних thinking-блоків. +- Виправлення порядку ходів Google (додавання крихітного початкового ходу користувача, якщо історія починається з асистента). +- Antigravity Claude: нормалізація thinking signatures; відкидання блоків thinking без сигнатури. **Anthropic / Minimax (сумісні з Anthropic)** - Відновлення парування результатів інструментів і синтетичні результати інструментів. -- Валідація ходів (об’єднання послідовних користувацьких ходів для дотримання суворого чергування). -- Thinking-блоки з відсутніми, порожніми або blank сигнатурами повторного відтворення - видаляються перед перетворенням для провайдера. Якщо через це хід assistant стає порожнім, OpenClaw зберігає - форму ходу з непорожнім текстом omitted-reasoning. -- Старіші ходи assistant, що містять лише thinking і які потрібно видалити, замінюються - непорожнім текстом omitted-reasoning, щоб адаптери провайдера не відкидали такий хід під час повторного відтворення. +- Валідація ходів (об’єднання послідовних ходів користувача для дотримання суворого чергування). +- Кінцеві попередньо заповнені ходи асистента видаляються з вихідних + корисних навантажень Anthropic Messages, коли thinking увімкнено, включно з маршрутами Cloudflare AI Gateway. +- Блоки thinking з відсутніми, порожніми або пустими сигнатурами повторного відтворення видаляються + перед перетворенням для провайдера. Якщо через це хід асистента стає порожнім, OpenClaw зберігає + форму ходу з непорожнім текстом пропущеного міркування. +- Старіші ходи асистента, що містять лише thinking і мають бути видалені, замінюються + непорожнім текстом пропущеного міркування, щоб адаптери провайдера не відкидали + хід під час повторного відтворення. **Amazon Bedrock (Converse API)** -- Порожні ходи assistant з помилкою потоку відновлюються до непорожнього резервного текстового блоку - перед повторним відтворенням. Bedrock Converse відхиляє повідомлення assistant із `content: []`, тому - збережені ходи assistant із `stopReason: "error"` і порожнім контентом також - відновлюються на диску до завантаження. -- Thinking-блоки Claude з відсутніми, порожніми або blank сигнатурами повторного відтворення - видаляються перед повторним відтворенням Converse. Якщо через це хід assistant стає порожнім, OpenClaw - зберігає форму ходу з непорожнім текстом omitted-reasoning. -- Старіші ходи assistant, що містять лише thinking і які потрібно видалити, замінюються - непорожнім текстом omitted-reasoning, щоб повторне відтворення Converse зберігало сувору форму ходу. -- Під час повторного відтворення відфільтровуються ходи assistant, інжектовані дзеркалом доставки OpenClaw і gateway. +- Порожні ходи помилок потоку асистента відновлюються до непорожнього резервного текстового блоку + перед повторним відтворенням. Bedrock Converse відхиляє повідомлення асистента з `content: []`, тому + збережені ходи асистента з `stopReason: "error"` і порожнім вмістом також відновлюються на диску до завантаження. +- Блоки thinking Claude з відсутніми, порожніми або пустими сигнатурами повторного відтворення + видаляються перед повторним відтворенням Converse. Якщо через це хід асистента стає порожнім, OpenClaw + зберігає форму ходу з непорожнім текстом пропущеного міркування. +- Старіші ходи асистента, що містять лише thinking і мають бути видалені, замінюються + непорожнім текстом пропущеного міркування, щоб повторне відтворення Converse зберігало сувору форму ходу. +- Під час повторного відтворення фільтруються ходи асистента OpenClaw delivery-mirror і вставлені Gateway. - Санітизація зображень застосовується через глобальне правило. **Mistral (включно з виявленням за model-id)** @@ -168,7 +172,7 @@ TUI, REST або SSE. **OpenRouter Gemini** -- Очищення thought-сигнатур: видалення значень `thought_signature`, які не є base64 (base64 зберігаються). +- Очищення сигнатур думок: видалення значень `thought_signature`, що не є base64 (base64 зберігаються). **Усе інше** @@ -178,18 +182,18 @@ TUI, REST або SSE. ## Історична поведінка (до 2026.1.22) -До релізу 2026.1.22 OpenClaw застосовував кілька рівнів гігієни стенограм: +До випуску 2026.1.22 OpenClaw застосовував кілька шарів гігієни стенограм: -- Розширення **transcript-sanitize** запускалося під час кожної побудови контексту й могло: - - Відновлювати парування використання інструментів / результатів. - - Санітизувати ідентифікатори викликів інструментів (включно з несуворим режимом, який зберігав `_`/`-`). +- Розширення **transcript-sanitize** виконувалося під час кожної побудови контексту і могло: + - Відновлювати парування використання/результатів інструментів. + - Санітизувати ідентифікатори викликів інструментів (включно з нестрогим режимом, який зберігав `_`/`-`). - Раннер також виконував санітизацію, специфічну для провайдера, що дублювало роботу. - Додаткові мутації відбувалися поза політикою провайдера, зокрема: - - Видалення тегів `` із тексту assistant перед збереженням. - - Видалення порожніх ходів помилки assistant. - - Обрізання контенту assistant після викликів інструментів. + - Видалення тегів `` з тексту асистента перед збереженням. + - Відкидання порожніх ходів помилок асистента. + - Обрізання вмісту асистента після викликів інструментів. -Ця складність спричинила регресії між провайдерами (зокрема парування +Ця складність спричиняла міжпровайдерні регресії (зокрема для парування `openai-responses` `call_id|fc_id`). Очищення 2026.1.22 прибрало розширення, централізувало логіку в раннері та зробило OpenAI **no-touch**, окрім санітизації зображень.