diff --git a/docs/uk/concepts/context.md b/docs/uk/concepts/context.md index 5df77a3e7..0e1cb1356 100644 --- a/docs/uk/concepts/context.md +++ b/docs/uk/concepts/context.md @@ -1,15 +1,15 @@ --- read_when: - Ви хочете зрозуміти, що означає «контекст» в OpenClaw - - Ви налагоджуєте, чому модель щось «знає» (або забула це) + - Ви налагоджуєте, чому модель «знає» щось (або забула це) - Ви хочете зменшити накладні витрати контексту (`/context`, `/status`, `/compact`) -summary: 'Контекст: що бачить модель, як він будується та як його перевірити' +summary: 'Контекст: що бачить модель, як він формується та як його перевірити' title: Контекст x-i18n: - generated_at: "2026-04-05T18:48:31Z" + generated_at: "2026-04-06T12:42:54Z" model: gpt-5.4 provider: openai - source_hash: fe7dfe52cb1a64df229c8622feed1804df6c483a6243e0d2f309f6ff5c9fe521 + source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0 source_path: concepts/context.md workflow: 15 --- @@ -20,51 +20,51 @@ x-i18n: Проста ментальна модель для початківців: -- **Системний запит** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та впроваджені файли робочого простору. -- **Історія розмови**: ваші повідомлення + повідомлення помічника для цієї сесії. +- **Системний prompt** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та вбудовані файли робочого простору. +- **Історія розмови**: ваші повідомлення + повідомлення асистента для цієї сесії. - **Виклики/результати інструментів + вкладення**: вивід команд, читання файлів, зображення/аудіо тощо. -Контекст _не є тим самим_, що й «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що міститься в поточному вікні моделі. +Контекст _це не те саме_, що «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що знаходиться всередині поточного вікна моделі. ## Швидкий старт (перевірка контексту) -- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + параметри сесії. -- `/context list` → що впроваджено + приблизні розміри (для кожного файла + загальні). -- `/context detail` → глибший розбір: для кожного файла, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного запиту. -- `/usage tokens` → додає нижній колонтитул використання для кожної відповіді до звичайних відповідей. -- `/compact` → узагальнює старішу історію в компактний запис, щоб звільнити місце у вікні. +- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + налаштування сесії. +- `/context list` → що вбудовано + приблизні розміри (для кожного файла + загалом). +- `/context detail` → детальніший розподіл: пофайлово, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного prompt. +- `/usage tokens` → додає нижній колонтитул із використанням до звичайних відповідей. +- `/compact` → підсумовує старішу історію в компактний запис, щоб звільнити місце у вікні. -Див. також: [Слеш-команди](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Компресія](/uk/concepts/compaction). +Див. також: [Slash commands](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Стиснення](/uk/concepts/compaction). ## Приклад виводу -Значення залежать від моделі, провайдера, політики інструментів і того, що є у вашому робочому просторі. +Значення відрізняються залежно від моделі, провайдера, політики інструментів і вмісту вашого робочого простору. ### `/context list` ``` 🧠 Розподіл контексту Робочий простір: -Макс. bootstrap на файл: 20,000 chars +Максимум bootstrap на файл: 20,000 символів Пісочниця: mode=non-main sandboxed=false -Системний запит (запуск): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) +Системний prompt (запуск): 38,412 символів (~9,603 ток) (Контекст проєкту 23,901 символів (~5,976 ток)) -Впроваджені файли робочого простору: -- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) -- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) -- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) -- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) -- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) +Вбудовані файли робочого простору: +- AGENTS.md: OK | raw 1,742 символів (~436 ток) | injected 1,742 символів (~436 ток) +- SOUL.md: OK | raw 912 символів (~228 ток) | injected 912 символів (~228 ток) +- TOOLS.md: TRUNCATED | raw 54,210 символів (~13,553 ток) | injected 20,962 символів (~5,241 ток) +- IDENTITY.md: OK | raw 211 символів (~53 ток) | injected 211 символів (~53 ток) +- USER.md: OK | raw 388 символів (~97 ток) | injected 388 символів (~97 ток) - HEARTBEAT.md: MISSING | raw 0 | injected 0 -- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) +- BOOTSTRAP.md: OK | raw 0 символів (~0 ток) | injected 0 символів (~0 ток) -Список Skills (текст системного запиту): 2,184 chars (~546 tok) (12 skills) +Список Skills (текст системного prompt): 2,184 символів (~546 ток) (12 skills) Інструменти: read, edit, write, exec, process, browser, message, sessions_send, … -Список інструментів (текст системного запиту): 1,032 chars (~258 tok) -Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховуються в контексті; не показуються як текст) -Інструменти: (те саме, що вище) +Список інструментів (текст системного prompt): 1,032 символів (~258 ток) +Схеми інструментів (JSON): 31,988 символів (~7,997 ток) (враховуються в контексті; не показані як текст) +Інструменти: (ті самі, що вище) -Токени сесії (кешовані): 14,250 total / ctx=32,000 +Токени сесії (кешовані): 14,250 усього / ctx=32,000 ``` ### `/context detail` @@ -72,44 +72,44 @@ x-i18n: ``` 🧠 Розподіл контексту (детально) … -Найбільші skills (розмір запису в запиті): -- frontend-design: 412 chars (~103 tok) -- oracle: 401 chars (~101 tok) -… (+ще 10 skills) +Найбільші skills (розмір запису в prompt): +- frontend-design: 412 символів (~103 ток) +- oracle: 401 символ (~101 ток) +… (+10 more skills) Найбільші інструменти (розмір схеми): -- browser: 9,812 chars (~2,453 tok) -- exec: 6,240 chars (~1,560 tok) -… (+ще N) +- browser: 9,812 символів (~2,453 ток) +- exec: 6,240 символів (~1,560 ток) +… (+N more tools) ``` ## Що враховується у вікні контексту -Враховується все, що отримує модель, зокрема: +Усе, що отримує модель, враховується, зокрема: -- Системний запит (усі розділи). +- Системний prompt (усі розділи). - Історія розмови. - Виклики інструментів + результати інструментів. - Вкладення/транскрипти (зображення/аудіо/файли). -- Підсумки компресії та артефакти обрізання. +- Підсумки стиснення та артефакти обрізання. - «Обгортки» провайдера або приховані заголовки (не видимі, але все одно враховуються). -## Як OpenClaw будує системний запит +## Як OpenClaw будує системний prompt -Системний запит **належить OpenClaw** і перебудовується для кожного запуску. Він містить: +Системний prompt **належить OpenClaw** і перебудовується для кожного запуску. Він містить: - Список інструментів + короткі описи. - Список Skills (лише метадані; див. нижче). - Розташування робочого простору. - Час (UTC + перетворений час користувача, якщо налаштовано). - Метадані середовища виконання (хост/ОС/модель/thinking). -- Впроваджені bootstrap-файли робочого простору в розділі **Project Context**. +- Вбудовані bootstrap-файли робочого простору в розділі **Контекст проєкту**. -Повний розбір: [Системний запит](/uk/concepts/system-prompt). +Повний розбір: [System Prompt](/uk/concepts/system-prompt). -## Впроваджені файли робочого простору (Project Context) +## Вбудовані файли робочого простору (Контекст проєкту) -Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони є): +Типово OpenClaw вбудовує фіксований набір файлів робочого простору (якщо вони є): - `AGENTS.md` - `SOUL.md` @@ -119,68 +119,69 @@ x-i18n: - `HEARTBEAT.md` - `BOOTSTRAP.md` (лише під час першого запуску) -Великі файли обрізаються окремо для кожного файла за допомогою `agents.defaults.bootstrapMaxChars` (типово `20000` символів). OpenClaw також застосовує загальне обмеження на впровадження bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. +Великі файли обрізаються для кожного файла окремо за допомогою `agents.defaults.bootstrapMaxChars` (типове значення `20000` символів). OpenClaw також застосовує загальне обмеження на вбудовування bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типове значення `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. -Коли відбувається обрізання, середовище виконання може впровадити в запит блок попередження в розділі Project Context. Налаштовується це через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`). +Коли відбувається обрізання, середовище виконання може вставити в prompt блок попередження в розділі Контекст проєкту. Це налаштовується через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типове значення `once`). -## Skills: впроваджені чи завантажені на вимогу +## Skills: вбудовані чи завантажувані на вимогу -Системний запит містить компактний **список skills** (назва + опис + розташування). Цей список створює реальні накладні витрати. +Системний prompt містить компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати. -Інструкції skill _не_ включаються типово. Очікується, що модель виконає `read` для `SKILL.md` цього skill **лише за потреби**. +Інструкції skill _не_ включаються типово. Очікується, що модель прочитає `SKILL.md` відповідного skill через `read` **лише за потреби**. -## Інструменти: є дві складові вартості +## Інструменти: є дві складові витрат Інструменти впливають на контекст двома способами: -1. **Текст списку інструментів** у системному запиті (те, що ви бачите як “Tooling”). -2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, навіть якщо ви не бачите їх як звичайний текст. +1. **Текст списку інструментів** у системному prompt (те, що ви бачите як «Інструменти»). +2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, хоча ви не бачите їх як звичайний текст. `/context detail` розбиває найбільші схеми інструментів, щоб ви могли побачити, що домінує. ## Команди, директиви та "вбудовані скорочення" -Слеш-команди обробляються Gateway. Існує кілька різних варіантів поведінки: +Slash-команди обробляються Gateway. Є кілька різних варіантів поведінки: -- **Окремі команди**: повідомлення, яке складається лише з `/...`, виконується як команда. -- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення. - - Повідомлення лише з директивами зберігають параметри сесії. +- **Окремі команди**: повідомлення, що складається лише з `/...`, виконується як команда. +- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` видаляються до того, як модель побачить повідомлення. + - Повідомлення, що містять лише директиви, зберігають налаштування сесії. - Вбудовані директиви у звичайному повідомленні діють як підказки для конкретного повідомлення. -- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` усередині звичайного повідомлення можуть виконуватися негайно (приклад: “hey /status”), а потім прибираються до того, як модель побачить решту тексту. +- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` всередині звичайного повідомлення можуть виконуватися негайно (наприклад: «hey /status»), і видаляються до того, як модель побачить решту тексту. -Докладніше: [Слеш-команди](/uk/tools/slash-commands). +Докладніше: [Slash commands](/uk/tools/slash-commands). -## Сесії, компресія та обрізання (що зберігається) +## Сесії, стиснення та обрізання (що зберігається) Що саме зберігається між повідомленнями, залежить від механізму: -- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснута/обрізана відповідно до політики. -- **Компресія** зберігає підсумок у транскрипті та залишає недавні повідомлення без змін. -- **Обрізання** видаляє старі результати інструментів із _внутрішньої_ підказки для запуску, але не переписує транскрипт. +- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснена/обрізана згідно з політикою. +- **Стиснення** зберігає підсумок у транскрипті та залишає недоторканими нещодавні повідомлення. +- **Обрізання** видаляє старі результати інструментів із prompt _у пам’яті_ для запуску, але не переписує транскрипт. -Документація: [Сесія](/uk/concepts/session), [Компресія](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning). +Документація: [Сесія](/uk/concepts/session), [Стиснення](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning). -Типово OpenClaw використовує вбудований контекстний рушій `legacy` для збирання -та компресії. Якщо ви встановите плагін, який надає `kind: "context-engine"`, і +Типово OpenClaw використовує вбудований рушій контексту `legacy` для складання +та стиснення. Якщо ви встановите plugin, який надає `kind: "context-engine"`, і виберете його через `plugins.slots.contextEngine`, OpenClaw натомість делегує -цьому рушію збирання контексту, `/compact` і пов’язані гачки життєвого циклу -контексту субагента. `ownsCompaction: false` не вмикає автоматичний fallback до -рушія legacy; активний рушій усе одно має коректно реалізовувати `compact()`. Див. +складання контексту, `/compact` і пов’язані гачки життєвого циклу контексту +підлеглого агента цьому рушію. `ownsCompaction: false` не викликає +автоматичного повернення до рушія `legacy`; активний рушій усе одно має +коректно реалізовувати `compact()`. Див. [Context Engine](/uk/concepts/context-engine), щоб ознайомитися з повним підключуваним інтерфейсом, гачками життєвого циклу та конфігурацією. ## Що насправді показує `/context` -`/context` за можливості віддає перевагу найновішому звіту про системний запит, **побудований під час запуску**: +`/context` за можливості віддає перевагу найновішому звіту про системний prompt, **побудований під час запуску**: -- `System prompt (run)` = зафіксований з останнього вбудованого запуску (з підтримкою інструментів) і збережений у сховищі сесії. -- `System prompt (estimate)` = обчислений на льоту, якщо звіту про запуску ще немає. +- `System prompt (run)` = захоплений з останнього вбудованого запуску (із підтримкою інструментів) і збережений у сховищі сесії. +- `System prompt (estimate)` = обчислений на льоту, коли звіт про запуск відсутній (або під час роботи через бекенд CLI, який не генерує цей звіт). -У будь-якому випадку він показує розміри та найбільших учасників; він **не** вивантажує повний системний запит або схеми інструментів. +У будь-якому разі він повідомляє розміри та найбільші складові; він **не** виводить повний системний prompt або схеми інструментів. ## Пов’язане -- [Context Engine](/uk/concepts/context-engine) — користувацьке впровадження контексту через плагіни -- [Компресія](/uk/concepts/compaction) — узагальнення довгих розмов -- [Системний запит](/uk/concepts/system-prompt) — як будується системний запит +- [Context Engine](/uk/concepts/context-engine) — користувацьке вбудовування контексту через plugins +- [Стиснення](/uk/concepts/compaction) — підсумовування довгих розмов +- [System Prompt](/uk/concepts/system-prompt) — як будується системний prompt - [Цикл агента](/uk/concepts/agent-loop) — повний цикл виконання агента diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index e20554903..06712c43a 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,40 +1,40 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Ви хочете приклади конфігурацій або команд CLI для онбордингу постачальників моделей + - Вам потрібні приклади конфігурацій або команд CLI для онбордингу постачальників моделей summary: Огляд постачальників моделей із прикладами конфігурацій і потоків CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-05T23:54:07Z" + generated_at: "2026-04-06T12:44:34Z" model: gpt-5.4 provider: openai - source_hash: 15e4b82e07221018a723279d309e245bb4023bc06e64b3c910ef2cae3dfa2599 + source_hash: ec33cbfeec86c3f79ea0ec38932eebb819eba5932024b73fcf3acbc41fbce203 source_path: concepts/model-providers.md workflow: 15 --- # Постачальники моделей -Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). +На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених значень. +- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених моделей. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Правила резервного перемикання під час виконання, перевірки стану після cooldown і збереження перевизначень сесії - задокументовано в [/concepts/model-failover](/uk/concepts/model-failover). +- Правила резервного перемикання під час виконання, проби періоду охолодження та збереження перевизначень сесії + задокументовані в [/concepts/model-failover](/uk/concepts/model-failover). - `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання. -- Плагіни постачальників можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`; - OpenClaw об’єднує цей вивід у `models.providers` перед записом +- Плагіни постачальників можуть додавати каталоги моделей через `registerProvider({ catalog })`; + OpenClaw об'єднує цей вивід у `models.providers` перед записом `models.json`. - Маніфести постачальників можуть оголошувати `providerAuthEnvVars`, щоб загальним перевіркам - автентифікації через змінні середовища не потрібно було завантажувати код плагіна під час виконання. Решта мапи змінних середовища в core - тепер призначена лише для неплагінових/core постачальників і кількох випадків - загального пріоритету, як-от онбординг Anthropic зі сценарієм «спочатку API-ключ». -- Плагіни постачальників також можуть керувати поведінкою постачальника під час виконання через + автентифікації на основі змінних середовища не потрібно було завантажувати середовище виконання плагіна. Решта мапи змінних середовища ядра + тепер використовується лише для не-плагінних/вбудованих постачальників і кількох випадків + загального пріоритету, як-от онбординг Anthropic із пріоритетом API-ключа. +- Плагіни постачальників також можуть володіти логікою виконання постачальника через `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -52,170 +52,177 @@ x-i18n: `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and `onModelSelected`. -- Примітка: `capabilities` постачальника під час виконання — це спільні метадані runner-а (сімейство постачальника, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), - яка описує, що саме реєструє плагін (текстовий inference, speech тощо). +- Примітка: `capabilities` середовища виконання постачальника — це спільні метадані виконавця (сімейство постачальника, + особливості транскрипту/інструментів, підказки щодо транспорту/кешу). Це не + те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), + яка описує, що реєструє плагін (текстовий inference, мовлення тощо). -## Поведінка постачальника, якою володіє плагін +## Поведінка постачальника, що належить плагіну -Плагіни постачальників тепер можуть керувати більшістю логіки, специфічної для постачальника, тоді як OpenClaw зберігає +Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає загальний цикл inference. Типовий розподіл: -- `auth[].run` / `auth[].runNonInteractive`: постачальник керує потоками онбордингу/входу +- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу для `openclaw onboard`, `openclaw models auth` і безголового налаштування -- `wizard.setup` / `wizard.modelPicker`: постачальник керує мітками вибору автентифікації, - застарілими псевдонімами, підказками щодо allowlist під час онбордингу та записами налаштування у вибірниках онбордингу/моделей -- `catalog`: постачальник з’являється в `models.providers` +- `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації, + застарілими псевдонімами, підказками для списку дозволених моделей під час онбордингу та записами налаштування у вибірниках онбордингу/моделей +- `catalog`: постачальник з'являється в `models.providers` - `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед пошуком або канонізацією -- `normalizeTransport`: постачальник нормалізує transport-family `api` / `baseUrl` - перед загальним збиранням моделі; OpenClaw спочатку перевіряє відповідного постачальника, - потім інші плагіни постачальників, здатні виконувати цей hook, доки один із них справді не змінить - transport +- `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту + перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника, + потім інші плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить + транспорт - `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед використанням під час виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші - плагіни постачальників, здатні виконувати цей hook, доки один із них справді не змінить конфігурацію. Якщо жоден - hook постачальника не переписує конфігурацію, вбудовані допоміжні засоби для сімейства Google все одно + плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить конфігурацію. Якщо жоден + хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно нормалізують підтримувані записи постачальників Google. -- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності для нативного streaming-usage, зумовлене endpoint, для конфігурованих постачальників -- `resolveConfigApiKey`: постачальник визначає автентифікацію через env-marker для конфігурованих постачальників - без примусового повного завантаження runtime-автентифікації. `amazon-bedrock` також має тут - вбудований resolver AWS env-marker, хоча runtime-автентифікація Bedrock використовує - стандартний ланцюжок AWS SDK. -- `resolveSyntheticAuth`: постачальник може повідомляти про доступність локальної/self-hosted або іншої - автентифікації, що базується на конфігурації, без збереження відкритих секретів -- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні заповнювачі профілю - як менш пріоритетні, ніж автентифікація через env/config +- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності нативного обліку використання потокового режиму для постачальників конфігурації, зумовлені кінцевою точкою +- `resolveConfigApiKey`: постачальник визначає автентифікацію маркера середовища для постачальників конфігурації + без примусового повного завантаження автентифікації під час виконання. `amazon-bedrock` тут також має + вбудований резолвер маркерів середовища AWS, хоча автентифікація Bedrock під час виконання використовує + ланцюжок за замовчуванням AWS SDK. +- `resolveSyntheticAuth`: постачальник може показувати доступність локальної/self-hosted або іншої + автентифікації на основі конфігурації без збереження відкритих секретів +- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні профілі- + заповнювачі як такі, що мають нижчий пріоритет, ніж автентифікація на основі env/config - `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному статичному каталозі -- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою +- `prepareDynamicModel`: постачальнику потрібно оновити метадані перед повторною спробою динамічного визначення -- `normalizeResolvedModel`: постачальнику потрібні переписування transport або base URL +- `normalizeResolvedModel`: постачальнику потрібно переписати транспорт або базову URL-адресу - `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх - моделей постачальника, навіть коли вони надходять через інший сумісний transport -- `capabilities`: постачальник публікує особливості transcript/tooling/provider-family -- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як вбудований - runner їх побачить -- `inspectToolSchemas`: постачальник показує транспортно-специфічні попередження щодо схем + моделей постачальника, навіть коли вони надходять через інший сумісний транспорт +- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальників +- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як їх побачить + вбудований виконавець +- `inspectToolSchemas`: постачальник показує специфічні для транспорту попередження схеми після нормалізації -- `resolveReasoningOutputMode`: постачальник обирає нативні або теговані - контракти reasoning-output -- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі -- `createStreamFn`: постачальник замінює звичайний шлях stream повністю - користувацьким transport -- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту -- `resolveTransportTurnState`: постачальник надає нативні заголовки transport або метадані - для кожного turn +- `resolveReasoningOutputMode`: постачальник вибирає нативні чи теговані + контракти виводу reasoning +- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для окремих моделей +- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю + кастомним транспортом +- `wrapStreamFn`: постачальник застосовує обгортки сумісності запиту заголовків/тіла/моделі +- `resolveTransportTurnState`: постачальник надає нативні заголовки транспорту + або метадані для кожного ходу - `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket - або політику cooldown сесії -- `createEmbeddingProvider`: постачальник керує поведінкою embedding для пам’яті, коли вона - належить плагіну постачальника, а не core-перемикачу embedding -- `formatApiKey`: постачальник форматує збережені профілі автентифікації в runtime-рядок - `apiKey`, який очікує transport -- `refreshOAuth`: постачальник керує оновленням OAuth, коли спільних - refresher-ів `pi-ai` недостатньо -- `buildAuthDoctorHint`: постачальник додає підказку щодо виправлення, коли оновлення OAuth - завершується помилкою + або політику охолодження сесії +- `createEmbeddingProvider`: постачальник володіє логікою embedding для пам'яті, коли вона + належить плагіну постачальника, а не центральному перемикачу embedding у ядрі +- `formatApiKey`: постачальник форматує збережені профілі автентифікації у + рядок `apiKey`, який очікує транспорт під час виконання +- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних + оновлювачів `pi-ai` недостатньо +- `buildAuthDoctorHint`: постачальник додає вказівки з відновлення, коли оновлення OAuth + не вдається - `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника - помилки переповнення контекстного вікна, які загальні евристики не виявляють -- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки transport/API - із причинами резервного перемикання, наприклад обмеження швидкості або перевантаження -- `isCacheTtlEligible`: постачальник визначає, які upstream-ідентифікатори моделей підтримують TTL кешу prompt + помилки переповнення вікна контексту, які загальні евристики можуть пропустити +- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки транспорту/API + з причинами резервного перемикання, як-от ліміт запитів або перевантаження +- `isCacheTtlEligible`: постачальник визначає, які ідентифікатори моделей вище за потоком підтримують TTL кешу підказок - `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації - на специфічну для постачальника підказку щодо відновлення + на специфічну для постачальника підказку з відновлення - `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки й може повертати - помилку від постачальника у разі збоїв прямого визначення + помилку, що належить постачальнику, для прямих збоїв визначення - `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після - виявлення та злиття конфігурації -- `isBinaryThinking`: постачальник керує UX двійкового thinking увімк./вимк. -- `supportsXHighThinking`: постачальник додає вибраним моделям підтримку `xhigh` -- `resolveDefaultThinkingLevel`: постачальник керує типовою політикою `/think` для + виявлення та об'єднання конфігурації +- `isBinaryThinking`: постачальник володіє UX двійкового thinking увімк./вимк. +- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей +- `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для сімейства моделей -- `applyConfigDefaults`: постачальник застосовує специфічні для постачальника глобальні значення за замовчуванням - під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей -- `isModernModelRef`: постачальник керує зіставленням пріоритетних моделей для live/smoke -- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткочасний - runtime-токен -- `resolveUsageAuth`: постачальник визначає облікові дані usage/quota для `/usage` - і пов’язаних поверхонь status/reporting -- `fetchUsageSnapshot`: постачальник керує отриманням/парсингом endpoint usage, тоді як - core усе ще керує оболонкою зведення та форматуванням -- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, наприклад - телеметрію або ведення сесії, що належить постачальнику +- `applyConfigDefaults`: постачальник застосовує глобальні значення за замовчуванням, специфічні для постачальника, + під час матеріалізації конфігурації залежно від режиму автентифікації, середовища чи сімейства моделей +- `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke +- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий + токен для виконання +- `resolveUsageAuth`: постачальник визначає облікові дані використання/квоти для `/usage` + та пов'язаних поверхонь статусу/звітності +- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором кінцевої точки використання, тоді як + ядро все ще володіє оболонкою підсумку та форматуванням +- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, як-от + телеметрію або облік сесії, що належить постачальнику Поточні вбудовані приклади: -- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки щодо ремонту автентифікації, отримання - endpoint usage, метадані cache-TTL/provider-family та глобальні - значення конфігурації за замовчуванням, що враховують автентифікацію -- `amazon-bedrock`: визначення переповнення контексту й класифікація - причин failover для специфічних помилок Bedrock про throttle/not-ready, а також - спільне сімейство повторного програвання `anthropic-by-model` для захистів політики replay лише для Claude +- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання даних + з кінцевої точки використання, метадані TTL кешу/сімейства постачальника та глобальні + значення конфігурації за замовчуванням з урахуванням автентифікації +- `amazon-bedrock`: специфічне для постачальника зіставлення переповнення контексту та + класифікація причин резервного перемикання для помилок Bedrock throttle/not-ready, а також + спільне сімейство відтворення `anthropic-by-model` для захистів політики повтору лише Claude на трафіку Anthropic -- `anthropic-vertex`: захисти політики replay лише для Claude на Anthropic-message +- `anthropic-vertex`: захисти політики повтору лише Claude на Anthropic-message трафіку -- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо - можливостей постачальника, очищення thought-signature Gemini на проксійованому Gemini-трафіку, - впровадження reasoning для proxy через сімейство stream `openrouter-thinking`, - передавання метаданих маршрутизації та політика cache-TTL -- `github-copilot`: онбординг/вхід із пристрою, резервна сумісність моделей уперед, - підказки щодо transcript для Claude-thinking, обмін runtime-токенів і отримання endpoint - usage -- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація transport OpenAI, +- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника, + санітизація підпису thought у Gemini-трафіку через проксі, ін'єкція reasoning через проксі + через сімейство потоків `openrouter-thinking`, пересилання метаданих маршрутизації + та політика TTL кешу +- `github-copilot`: онбординг/вхід через пристрій, резервна сумісність уперед моделей, + підказки транскрипту Claude-thinking, обмін токенів під час виконання та отримання даних + з кінцевої точки використання +- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI, підказки про відсутню автентифікацію з урахуванням Codex, приглушення Spark, синтетичні - рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів usage-token - (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство stream `openai-responses-defaults` для нативних - обгорток OpenAI/Codex, метадані сімейства постачальника, реєстрація - вбудованого постачальника генерації зображень для `gpt-image-1` і вбудованого постачальника - генерації відео для `sora-2` -- `google`: резервна сумісність уперед для Gemini 3.1, нативна перевірка replay Gemini, - очищення bootstrap replay, режим тегованого reasoning-output, - зіставлення modern-model, реєстрація вбудованого постачальника генерації зображень для - Gemini image-preview models і вбудованого постачальника генерації відео - для моделей Veo -- `moonshot`: спільний transport, нормалізація payload thinking, якою володіє плагін -- `kilocode`: спільний transport, заголовки запитів, якими володіє плагін, нормалізація payload reasoning, - очищення thought-signature для proxy-Gemini та політика cache-TTL -- `zai`: резервна сумісність уперед для GLM-5, значення `tool_stream` за замовчуванням, cache-TTL - policy, binary-thinking/live-model policy, а також usage auth + отримання квот; - невідомі ідентифікатори `glm-5*` синтезуються на основі вбудованого шаблону `glm-4.7` -- `xai`: нативна нормалізація transport Responses, переписування псевдонімів `/fast` для + рядки каталогу OpenAI/Codex, політика thinking/live-моделей, нормалізація псевдонімів токенів використання + (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків + `openai-responses-defaults` для нативних обгорток OpenAI/Codex, + метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень + для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео + для `sora-2` +- `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1, + нативна валідація повтору Gemini, санітизація bootstrap-повтору, тегований + режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника + генерації зображень для preview-моделей Gemini image та вбудована + реєстрація постачальника генерації відео для моделей Veo; Gemini CLI OAuth також + володіє форматуванням токенів профілю автентифікації, розбором токенів використання та + отриманням кінцевої точки квоти для поверхонь використання +- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну +- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, payload reasoning + нормалізація, санітизація підпису thought у проксі-Gemini та політика TTL кешу +- `zai`: резервна сумісність уперед для GLM-5, типові значення `tool_stream`, політика TTL кешу, + політика двійкового thinking/live-моделей і автентифікація використання + отримання квоти; + невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` +- `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для швидких варіантів Grok, типове `tool_stream`, очищення схем інструментів / - payload reasoning, специфічне для xAI, і реєстрація вбудованого постачальника генерації відео + payload reasoning, специфічне для xAI, і вбудована реєстрація постачальника генерації відео для `grok-imagine-video` -- `mistral`: метадані можливостей, якими володіє плагін -- `opencode` і `opencode-go`: метадані можливостей, якими володіє плагін, плюс - очищення thought-signature для proxy-Gemini -- `alibaba`: каталог генерації відео, яким володіє плагін, для прямих посилань на моделі Wan - таких як `alibaba/wan2.6-t2v` -- `byteplus`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео +- `mistral`: метадані можливостей, що належать плагіну +- `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс + санітизація підпису thought у проксі-Gemini +- `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan + як-от `alibaba/wan2.6-t2v` +- `byteplus`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео для моделей Seedance text-to-video/image-to-video -- `fal`: реєстрація вбудованого постачальника генерації відео для розміщених сторонніх - моделей, реєстрація постачальника генерації зображень для моделей FLUX плюс вбудована - реєстрація постачальника генерації відео для розміщених сторонніх відеомоделей +- `fal`: вбудована реєстрація постачальника генерації відео для хостованих сторонніх + моделей, реєстрація постачальника генерації зображень для моделей зображень FLUX, а також вбудована + реєстрація постачальника генерації відео для хостованих сторонніх відеомоделей - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`: - лише каталоги, якими володіє плагін -- `qwen`: каталоги текстових моделей, якими володіє плагін, плюс спільні + лише каталоги, що належать плагіну +- `qwen`: каталоги, що належать плагіну, для текстових моделей плюс спільні реєстрації постачальників media-understanding і генерації відео для його - мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` -- `runway`: реєстрація постачальника генерації відео, якою володіє плагін, для нативних - моделей Runway на основі завдань, таких як `gen4.5` -- `minimax`: каталоги, якими володіє плагін, вбудована реєстрація постачальника генерації відео - для моделей Hailuo video, вбудована реєстрація постачальника генерації зображень - для `image-01`, гібридний вибір політики replay Anthropic/OpenAI, - а також логіка usage auth/snapshot -- `together`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео - для моделей Wan video -- `xiaomi`: каталоги, якими володіє плагін, плюс логіка usage auth/snapshot + мультимодальних поверхонь; генерація відео Qwen використовує стандартні відео- + кінцеві точки DashScope з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` +- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних + моделей Runway на основі завдань, як-от `gen4.5` +- `minimax`: каталоги, що належать плагіну, вбудована реєстрація постачальника генерації відео + для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень + для `image-01`, гібридний вибір політики повтору Anthropic/OpenAI та логіка + автентифікації/знімка використання +- `together`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео + для відеомоделей Wan +- `xiaomi`: каталоги, що належать плагіну, плюс логіка + автентифікації/знімка використання Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальника: `openai` і `openai-codex`. -Це охоплює постачальників, які все ще вписуються в звичайні transports OpenClaw. Постачальник, -якому потрібен повністю користувацький виконавець запитів, — це окрема, глибша -поверхня розширення. +Це охоплює постачальників, які ще вписуються в звичайні транспорти OpenClaw. Постачальник, +якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня +розширення. ## Ротація API-ключів @@ -227,37 +234,37 @@ x-i18n: - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) - Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант. - Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на обмеження швидкості (наприклад +- Запити повторюються з наступним ключем лише у відповідь на відповіді з обмеженням швидкості (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Збої, не пов’язані з обмеженням швидкості, завершуються помилкою одразу; ротація ключів не виконується. -- Коли всі кандидати-ключі не спрацьовують, повертається фінальна помилка з останньої спроби. +- Збої, не пов'язані з лімітом запитів, завершуються негайно; ротація ключів не виконується. +- Коли всі можливі ключі не спрацьовують, повертається фінальна помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** -потребують конфігурації `models.providers`; просто налаштуйте автентифікацію й оберіть модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** +конфігурація `models.providers`; достатньо налаштувати автентифікацію й вибрати модель. ### OpenAI - Постачальник: `openai` - Автентифікація: `OPENAI_API_KEY` -- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) +- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Transport за замовчуванням — `auto` (спочатку WebSocket, потім резервно SSE) +- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`) +- Розігрів WebSocket для OpenAI Responses типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` - `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses із `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до - загальних OpenAI-сумісних proxy -- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу prompt і - формування payload сумісності reasoning OpenAI; proxy-маршрути — ні -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark розглядається лише як Codex + `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не + до загальних проксі, сумісних з OpenAI +- Нативні маршрути OpenAI також зберігають `store` для Responses, підказки кешу промптів і + формування payload сумісності reasoning OpenAI; проксі-маршрути — ні +- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex ```json5 { @@ -269,12 +276,12 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Постачальник: `anthropic` - Автентифікація: `ANTHROPIC_API_KEY` -- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) +- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим через API-ключ і OAuth, який надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` або `standard_only`) -- Примітка щодо білінгу: для Anthropic в OpenClaw практичний поділ — це **API key** або **Claude subscription with Extra Usage**. Anthropic повідомив користувачам OpenClaw **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що шлях входу Claude через **OpenClaw** вважається використанням через сторонній harness і потребує **Extra Usage**, що тарифікується окремо від підписки. Наші локальні відтворення також показують, що рядок prompt, який ідентифікує OpenClaw, не відтворюється на шляху Anthropic SDK + API key. -- Setup-токен Anthropic знову доступний як застарілий/ручний шлях OpenClaw. Використовуйте його з урахуванням того, що Anthropic повідомив користувачам OpenClaw, що цей шлях потребує **Extra Usage**. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік, автентифікований через API-ключ і OAuth, надісланий до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо білінгу: для Anthropic в OpenClaw практичний поділ — це **API-ключ** або **підписка Claude з Extra Usage**. Anthropic повідомила користувачів OpenClaw **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що шлях входу Claude у **OpenClaw** вважається використанням через сторонній harness і потребує **Extra Usage**, що оплачується окремо від підписки. Наші локальні відтворення також показують, що рядок промпту, який ідентифікує OpenClaw, не відтворюється на шляху Anthropic SDK + API-ключ. +- Токен налаштування Anthropic знову доступний як застарілий/ручний шлях OpenClaw. Використовуйте його з розумінням, що Anthropic повідомила користувачів OpenClaw, що цей шлях потребує **Extra Usage**. ```json5 { @@ -288,16 +295,16 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Автентифікація: OAuth (ChatGPT) - Приклад моделі: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Transport за замовчуванням — `auto` (спочатку WebSocket, потім резервно SSE) +- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) - `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на - `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy -- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли її надає каталог Codex OAuth; залежить від entitlement -- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типове runtime-значення `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/потоків роботи, таких як OpenClaw. + `chatgpt.com/backend-api`, а не до загальних проксі, сумісних з OpenAI +- Має спільний перемикач `/fast` і конфігурацію `params.fastMode`, як і прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від прав доступу +- `openai-codex/gpt-5.4` зберігає нативне `contextWindow = 1050000` і типове обмеження під час виконання `contextTokens = 272000`; перевизначте це обмеження через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/робочих процесів, як-от OpenClaw. ```json5 { @@ -317,17 +324,17 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста } ``` -### Інші розміщені варіанти у стилі підписки +### Інші хостовані варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): OAuth або доступ за API key для MiniMax Coding Plan -- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint-и +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення кінцевих точок Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan +- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні кінцеві точки API ### OpenCode - Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Постачальник Zen runtime: `opencode` -- Постачальник Go runtime: `opencode-go` +- Постачальник виконання Zen: `opencode` +- Постачальник виконання Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -337,24 +344,35 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста } ``` -### Google Gemini (API key) +### Google Gemini (API-ключ) - Постачальник: `google` - Автентифікація: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов'язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застаріле `cached_content`) для пересилання нативного для постачальника - дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` + (або застарілий `cached_content`) для пересилання нативного для постачальника + дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` -### Google Vertex +### Google Vertex і Gemini CLI -- Постачальник: `google-vertex` -- Автентифікація: gcloud ADC - - JSON-відповіді Gemini CLI парсяться з `response`; usage резервно береться з - `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. +- Постачальники: `google-vertex`, `google-gemini-cli` +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI — власний потік OAuth +- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і, якщо вирішите продовжити, використовуйте некритичний обліковий запис. +- Gemini CLI OAuth постачається як частина вбудованого плагіна `google`. + - Спочатку встановіть Gemini CLI: + - `brew install gemini-cli` + - або `npm install -g @google/gemini-cli` + - Увімкнення: `openclaw plugins enable google` + - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` + - Типова модель: `google-gemini-cli/gemini-3.1-pro-preview` + - Примітка: вам **не потрібно** вставляти client id або secret в `openclaw.json`. Потік входу CLI зберігає + токени в профілях автентифікації на gateway host. + - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host. + - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з + `stats`, при цьому `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -363,7 +381,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Приклад моделі: `zai/glm-5` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню + - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово використовують конкретну поверхню ### Vercel AI Gateway @@ -378,9 +396,10 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Автентифікація: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` +- Базова URL-адреса: `https://api.kilo.ai/api/gateway/` - Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення - `https://api.kilo.ai/api/gateway/models` може додатково розширювати runtime-каталог. + `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог + під час виконання. - Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. @@ -390,26 +409,26 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Приклад моделі: `openrouter/auto` -- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли - запит справді спрямований на `openrouter.ai` -- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежуються - перевіреними маршрутами OpenRouter, а не довільними proxy URL -- OpenRouter лишається на шляху proxy-стилю OpenAI-compatible, тому специфічне лише для нативного - OpenAI формування запитів (`serviceTier`, Responses `store`, - підказки кешу prompt, payload сумісності reasoning OpenAI) не пересилається -- Посилання OpenRouter на базі Gemini зберігають лише очищення thought-signature для proxy-Gemini; - нативна перевірка replay Gemini та переписування bootstrap залишаються вимкненими +- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді, + коли запит дійсно спрямовано на `openrouter.ai` +- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені + перевіреними маршрутами OpenRouter, а не довільними URL-адресами проксі +- OpenRouter залишається на проксі-шляху у стилі OpenAI-compatible, тому нативне + формування запитів лише для OpenAI (`serviceTier`, `store` для Responses, + підказки кешу промптів, payload сумісності reasoning OpenAI) не пересилається +- Посилання OpenRouter на базі Gemini зберігають лише санітизацію підпису thought у проксі-Gemini; + нативна валідація повтору Gemini та переписування bootstrap залишаються вимкненими - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Приклад моделі: `kilocode/kilo/auto` -- Посилання Kilo на базі Gemini зберігають той самий шлях очищення thought-signature - для proxy-Gemini; `kilocode/kilo/auto` та інші підказки, які не підтримують proxy-reasoning, - пропускають упровадження reasoning для proxy -- MiniMax: `minimax` (API key) і `minimax-portal` (OAuth) +- Посилання Kilo на базі Gemini зберігають той самий шлях санітизації підпису thought + у проксі-Gemini; `kilocode/kilo/auto` та інші підказки, що не підтримують reasoning через проксі, + пропускають ін'єкцію reasoning через проксі +- MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth) - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` - Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7` -- Налаштування MiniMax через онбординг/API key записує явні визначення моделей M2.7 з - `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання - лише для тексту, доки конфігурація цього постачальника не буде матеріалізована +- Налаштування MiniMax під час онбордингу/API-ключа записує явні визначення моделей M2.7 з + `input: ["text", "image"]`; вбудований каталог постачальника тримає chat-посилання + лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Приклад моделі: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`) @@ -421,7 +440,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - NVIDIA: `nvidia` (`NVIDIA_API_KEY`) - Приклад моделі: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` - StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`) -- Приклади моделей: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` +- Приклад моделі: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` - Together: `together` (`TOGETHER_API_KEY`) - Приклад моделі: `together/moonshotai/Kimi-K2.5` - Venice: `venice` (`VENICE_API_KEY`) @@ -438,33 +457,33 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Нативні вбудовані запити xAI використовують шлях xAI Responses - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast` - - `tool_stream` типово ввімкнений; установіть - `agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб + - `tool_stream` типово ввімкнено; задайте + `agents.defaults.models["xai/"].params.tool_stream` як `false`, щоб вимкнути його - Mistral: `mistral` (`MISTRAL_API_KEY`) - Приклад моделі: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Моделі GLM у Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. - - Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. + - Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. + - Базова URL-адреса, сумісна з OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface). -## Постачальники через `models.providers` (custom/base URL) +## Постачальники через `models.providers` (кастомна/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **custom** постачальників або -OpenAI/Anthropic‑сумісні proxy. +Використовуйте `models.providers` (або `models.json`), щоб додати **кастомних** постачальників або +проксі, сумісні з OpenAI/Anthropic. Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -типовий base URL, заголовки або список моделей. +типову базову URL-адресу, заголовки або список моделей. ### Moonshot AI (Kimi) Moonshot постачається як вбудований плагін постачальника. Використовуйте вбудованого постачальника -типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли -потрібно перевизначити base URL або метадані моделі: +типово й додавайте явний запис `models.providers.moonshot` лише тоді, коли +потрібно перевизначити базову URL-адресу або метадані моделі: - Постачальник: `moonshot` - Автентифікація: `MOONSHOT_API_KEY` @@ -503,7 +522,7 @@ Moonshot постачається як вбудований плагін пос ### Kimi Coding -Kimi Coding використовує Anthropic-compatible endpoint Moonshot AI: +Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: - Постачальник: `kimi` - Автентифікація: `KIMI_API_KEY` @@ -518,7 +537,7 @@ Kimi Coding використовує Anthropic-compatible endpoint Moonshot AI: } ``` -Застарілий `kimi/k2p5` усе ще приймається як ідентифікатор моделі для сумісності. +Застарілий `kimi/k2p5` і далі приймається як сумісний ідентифікатор моделі. ### Volcano Engine (Doubao) @@ -537,13 +556,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу типово використовується coding-поверхня, але загальний каталог `volcengine/*` -реєструється одночасно. +Під час онбордингу типово використовується поверхня coding, але загальний каталог `volcengine/*` +реєструється водночас. -У вибірниках моделей онбордингу/налаштування Volcengine варіант автентифікації -віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній -вибірник, прив’язаний до постачальника. +У вибірниках онбордингу/налаштування моделі варіант автентифікації Volcengine надає перевагу і рядкам +`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній +вибірник у межах постачальника. Доступні моделі: @@ -553,7 +572,7 @@ OpenClaw повертається до нефільтрованого катал - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -Coding-моделі (`volcengine-plan`): +Моделі coding (`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -563,7 +582,7 @@ Coding-моделі (`volcengine-plan`): ### BytePlus (International) -BytePlus ARK надає доступ до тих самих моделей, що й Volcano Engine, для міжнародних користувачів. +BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. - Постачальник: `byteplus` (coding: `byteplus-plan`) - Автентифікація: `BYTEPLUS_API_KEY` @@ -578,13 +597,13 @@ BytePlus ARK надає доступ до тих самих моделей, що } ``` -Під час онбордингу типово використовується coding-поверхня, але загальний каталог `byteplus/*` -реєструється одночасно. +Під час онбордингу типово використовується поверхня coding, але загальний каталог `byteplus/*` +реєструється водночас. -У вибірниках моделей онбордингу/налаштування варіант автентифікації BytePlus віддає перевагу як -рядкам `byteplus/*`, так і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній -вибірник, прив’язаний до постачальника. +У вибірниках онбордингу/налаштування моделі варіант автентифікації BytePlus надає перевагу і рядкам +`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній +вибірник у межах постачальника. Доступні моделі: @@ -592,7 +611,7 @@ OpenClaw повертається до нефільтрованого катал - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -Coding-моделі (`byteplus-plan`): +Моделі coding (`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -602,7 +621,7 @@ Coding-моделі (`byteplus-plan`): ### Synthetic -Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`: +Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: - Постачальник: `synthetic` - Автентифікація: `SYNTHETIC_API_KEY` @@ -630,27 +649,27 @@ Synthetic надає Anthropic-compatible моделі через постача ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint-и: +MiniMax налаштовується через `models.providers`, оскільки використовує кастомні кінцеві точки: - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API key (Global): `--auth-choice minimax-global-api` -- MiniMax API key (CN): `--auth-choice minimax-cn-api` +- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` +- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-compatible streaming-шляху MiniMax OpenClaw типово вимикає thinking, -якщо ви явно його не вкажете, а `/fast on` переписує +На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, +якщо ви явно його не задаєте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розподіл можливостей, якими володіє плагін: +Розподіл можливостей, що належать плагіну: -- Типові значення для тексту/chat лишаються на `minimax/MiniMax-M2.7` +- Типові значення тексту/чату залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, яким володіє плагін, на обох шляхах автентифікації MiniMax -- Вебпошук лишається на ідентифікаторі постачальника `minimax` +- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax +- Вебпошук залишається на ідентифікаторі постачальника `minimax` ### Ollama @@ -659,10 +678,10 @@ Ollama постачається як вбудований плагін пост - Постачальник: `ollama` - Автентифікація: не потрібна (локальний сервер) - Приклад моделі: `ollama/llama3.3` -- Установлення: [https://ollama.com/download](https://ollama.com/download) +- Встановлення: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Встановіть Ollama, потім завантажте модель: ollama pull llama3.3 ``` @@ -674,10 +693,10 @@ ollama pull llama3.3 } ``` -Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви ввімкнули її через +Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте її через `OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до `openclaw onboard` і вибірника моделей. Див. [/providers/ollama](/uk/providers/ollama) -для онбордингу, режиму cloud/local і custom-конфігурації. +щодо онбордингу, хмарного/локального режиму та кастомної конфігурації. ### vLLM @@ -685,16 +704,16 @@ vLLM постачається як вбудований плагін поста серверів, сумісних з OpenAI: - Постачальник: `vllm` -- Автентифікація: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:8000/v1` +- Автентифікація: необов'язкова (залежить від вашого сервера) +- Типова базова URL-адреса: `http://127.0.0.1:8000/v1` -Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, повернених `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -712,17 +731,17 @@ SGLang постачається як вбудований плагін пост серверів, сумісних з OpenAI: - Постачальник: `sglang` -- Автентифікація: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:30000/v1` +- Автентифікація: необов'язкова (залежить від вашого сервера) +- Типова базова URL-адреса: `http://127.0.0.1:30000/v1` -Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, повернених `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -734,9 +753,9 @@ export SGLANG_API_KEY="sglang-local" Деталі див. у [/providers/sglang](/uk/providers/sglang). -### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) +### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (сумісний з OpenAI): +Приклад (OpenAI-compatible): ```json5 { @@ -771,21 +790,20 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для custom-постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх пропущено, OpenClaw використовує такі типові значення: +- Для кастомних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов'язковими. + Якщо їх не вказано, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: задавайте явні значення, які відповідають лімітам вашого proxy/моделі. -- Для `api: "openai-completions"` на ненативних endpoint-ах (будь-який непорожній `baseUrl`, у якого host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок 400 від постачальника для непідтримуваних ролей `developer`. -- Маршрути OpenAI-compatible у стилі proxy також пропускають специфічне лише для нативного OpenAI - формування запиту: без `service_tier`, без `store` у Responses, без підказок кешу prompt, без - формування payload сумісності reasoning OpenAI та без прихованих заголовків атрибуції - OpenClaw. -- Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає типову поведінку OpenAI (яка зіставляється з `api.openai.com`). -- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint-ах `openai-completions`. +- Рекомендація: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на не-нативних кінцевих точках (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. +- Проксі-маршрути у стилі OpenAI-compatible також пропускають нативне + формування запитів лише для OpenAI: без `service_tier`, без `store` для Responses, без підказок кешу промптів, без + формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. +- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). +- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не-нативних кінцевих точках `openai-completions`. ## Приклади CLI @@ -797,9 +815,9 @@ openclaw models list Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов’язане +## Пов'язане - [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми - [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб - [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделі -- [Providers](/uk/providers) — інструкції з налаштування для кожного постачальника +- [Providers](/uk/providers) — окремі посібники з налаштування постачальників diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md new file mode 100644 index 000000000..f4079a610 --- /dev/null +++ b/docs/uk/gateway/cli-backends.md @@ -0,0 +1,294 @@ +--- +read_when: + - Вам потрібен надійний резервний варіант, коли API-провайдери не працюють + - Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх + - Ви хочете зрозуміти MCP loopback-міст для доступу CLI-бекенду до інструментів +summary: 'CLI-бекенди: локальний резервний AI CLI з необов’язковим мостом інструментів MCP' +title: CLI-бекенди +x-i18n: + generated_at: "2026-04-06T12:43:15Z" + model: gpt-5.4 + provider: openai + source_hash: fe30bb4d5f51adcda53bf69a4f88e27832e78630ed5bfd8a33a66b6412b66f2d + source_path: gateway/cli-backends.md + workflow: 15 +--- + +# CLI-бекенди (резервне середовище виконання) + +OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні, +обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід: + +- **Інструменти OpenClaw не впроваджуються безпосередньо**, але бекенди з `bundleMcp: true` + можуть отримувати інструменти gateway через loopback-міст MCP. +- **JSONL-стримінг** для CLI, які це підтримують. +- **Сеанси підтримуються** (тому наступні звернення залишаються узгодженими). +- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень. + +Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли вам +потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. + +Якщо вам потрібне повноцінне середовище виконання harness із керуванням сеансами ACP, фоновими завданнями, +прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте +[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP. + +## Швидкий старт для початківців + +Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI +реєструє бекенд за замовчуванням): + +```bash +openclaw agent --message "hi" --model codex-cli/gpt-5.4 +``` + +Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише +шлях до команди: + +```json5 +{ + agents: { + defaults: { + cliBackends: { + "codex-cli": { + command: "/opt/homebrew/bin/codex", + }, + }, + }, + }, +} +``` + +Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. + +Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на +хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація +явно посилається на цей бекенд у model ref або в +`agents.defaults.cliBackends`. + +## Використання як резервного варіанта + +Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі не працюють: + +```json5 +{ + agents: { + defaults: { + model: { + primary: "anthropic/claude-opus-4-6", + fallbacks: ["codex-cli/gpt-5.4"], + }, + models: { + "anthropic/claude-opus-4-6": { alias: "Opus" }, + "codex-cli/gpt-5.4": {}, + }, + }, + }, +} +``` + +Примітки: + +- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі CLI-бекенду. +- Якщо основний провайдер завершується помилкою (автентифікація, обмеження частоти, тайм-аути), OpenClaw + спробує CLI-бекенд наступним. + +## Огляд конфігурації + +Усі CLI-бекенди розміщуються тут: + +``` +agents.defaults.cliBackends +``` + +Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`). +Ідентифікатор провайдера стає лівою частиною вашого model ref: + +``` +/ +``` + +### Приклад конфігурації + +```json5 +{ + agents: { + defaults: { + cliBackends: { + "codex-cli": { + command: "/opt/homebrew/bin/codex", + }, + "my-cli": { + command: "my-cli", + args: ["--json"], + output: "json", + input: "arg", + modelArg: "--model", + modelAliases: { + "claude-opus-4-6": "opus", + "claude-sonnet-4-6": "sonnet", + }, + sessionArg: "--session", + sessionMode: "existing", + sessionIdFields: ["session_id", "conversation_id"], + systemPromptArg: "--system", + systemPromptWhen: "first", + imageArg: "--image", + imageMode: "repeat", + serialize: true, + }, + }, + }, + }, +} +``` + +## Як це працює + +1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). +2. **Формує system prompt** із використанням того самого prompt OpenClaw і контексту робочого простору. +3. **Виконує CLI** з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою. +4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. +5. **Зберігає ідентифікатори сеансів** для кожного бекенду, щоб наступні звернення повторно використовували той самий сеанс CLI. + + +Вбудований бекенд Anthropic `claude-cli` було видалено після того, як змінилася +межа білінгу OpenClaw в Anthropic. OpenClaw і далі підтримує загальні CLI- +бекенди, але трафік Anthropic API слід спрямовувати безпосередньо через провайдера Anthropic, +а не через видалений локальний шлях Claude CLI. + + +## Сеанси + +- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або + `sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити + в кілька прапорців. +- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте + `resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput` + (для відновлення не у форматі JSON). +- `sessionMode`: + - `always`: завжди передавати ідентифікатор сеансу (новий UUID, якщо нічого не збережено). + - `existing`: передавати ідентифікатор сеансу, лише якщо його вже було збережено. + - `none`: ніколи не передавати ідентифікатор сеансу. + +Примітки щодо серіалізації: + +- `serialize: true` зберігає впорядкованість запусків у тій самій смузі. +- Більшість CLI серіалізують роботу в одній смузі провайдера. +- OpenClaw скидає повторне використання збереженого CLI-сеансу, коли змінюється стан автентифікації бекенду, зокрема після повторного входу, ротації токена або зміни облікових даних профілю автентифікації. + +## Зображення (передавання далі) + +Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`: + +```json5 +imageArg: "--image", +imageMode: "repeat" +``` + +OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці +шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає +шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично +завантажують локальні файли зі звичайних шляхів. + +## Входи / виходи + +- `output: "json"` (типово) намагається розібрати JSON і витягти текст та ідентифікатор сеансу. +- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а + дані використання — зі `stats`, коли `usage` відсутній або порожній. +- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента, а також ідентифікатори сеансу, + якщо вони присутні. +- `output: "text"` трактує stdout як фінальну відповідь. + +Режими введення: + +- `input: "arg"` (типово) передає prompt як останній аргумент CLI. +- `input: "stdin"` надсилає prompt через stdin. +- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. + +## Типові значення (належать плагіну) + +Вбудований плагін OpenAI також реєструє типові значення для `codex-cli`: + +- `command: "codex"` +- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` +- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` +- `output: "jsonl"` +- `resumeOutput: "text"` +- `modelArg: "--model"` +- `imageArg: "--image"` +- `sessionMode: "existing"` + +Вбудований плагін Google також реєструє типові значення для `google-gemini-cli`: + +- `command: "gemini"` +- `args: ["--prompt", "--output-format", "json"]` +- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]` +- `modelArg: "--model"` +- `sessionMode: "existing"` +- `sessionIdFields: ["session_id", "sessionId"]` + +Передумова: локальна Gemini CLI має бути встановлена та доступна як +`gemini` у `PATH` (`brew install gemini-cli` або +`npm install -g @google/gemini-cli`). + +Примітки щодо JSON у Gemini CLI: + +- Текст відповіді зчитується з поля JSON `response`. +- Дані використання беруться зі `stats`, якщо `usage` відсутній або порожній. +- `stats.cached` нормалізується у `cacheRead` OpenClaw. +- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із + `stats.input_tokens - stats.cached`. + +Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`). + +## Типові значення, що належать плагіну + +Типові значення CLI-бекенду тепер є частиною поверхні плагіна: + +- Плагіни реєструють їх через `api.registerCliBackend(...)`. +- `id` бекенду стає префіксом провайдера в model ref. +- Конфігурація користувача в `agents.defaults.cliBackends.` і далі перевизначає типове значення плагіна. +- Очищення конфігурації, специфічне для бекенду, і далі належить плагіну через необов’язковий + хук `normalizeConfig`. + +## Bundle MCP overlays + +CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може +увімкнути згенероване накладання конфігурації MCP за допомогою `bundleMcp: true`. + +Поточна вбудована поведінка: + +- `codex-cli`: без накладання bundle MCP +- `google-gemini-cli`: без накладання bundle MCP + +Коли bundle MCP увімкнено, OpenClaw: + +- запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI +- автентифікує міст за допомогою токена для кожного сеансу (`OPENCLAW_MCP_TOKEN`) +- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу +- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору +- об’єднує їх із будь-яким наявним `--mcp-config` бекенду +- переписує аргументи CLI, щоб передати `--strict-mcp-config --mcp-config ` + +Якщо жоден MCP-сервер не ввімкнено, OpenClaw однаково впроваджує strict-конфігурацію, коли +бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими. + +## Обмеження + +- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у + протокол CLI-бекенду. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають + `bundleMcp: true`. +- **Стримінг залежить від бекенду.** Деякі бекенди транслюють JSONL; інші буферизують + до завершення. +- **Структуровані виходи** залежать від формату JSON CLI. +- **Сеанси Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш + структуровано, ніж початковий запуск `--json`. Сеанси OpenClaw однаково працюють + нормально. + +## Усунення неполадок + +- **CLI не знайдено**: задайте `command` як повний шлях. +- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. +- **Немає безперервності сеансу**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює + `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). +- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів). diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 01406091d..eb5592d2a 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,23 +1,23 @@ --- read_when: - - Вам потрібна точна семантика полів конфігурації або значення за замовчуванням на рівні полів - - Ви перевіряєте блоки конфігурації каналів, моделей, шлюзу або інструментів + - Потрібна точна семантика або значення за замовчуванням для полів конфігурації + - Ви перевіряєте блоки конфігурації каналу, моделі, gateway або інструментів summary: Повний довідник для кожного ключа конфігурації OpenClaw, значень за замовчуванням і налаштувань каналів title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-06T04:36:41Z" + generated_at: "2026-04-06T12:47:39Z" model: gpt-5.4 provider: openai - source_hash: 6ae6c19666f65433361e1c8b100ae710448c8aa055a60c140241a8aea09b98a5 + source_hash: 67e3197e2dca37f43285b8aa0e5c77ef1662e1ba28ee874d4e7cbc90e6160ca3 source_path: gateway/configuration-reference.md workflow: 15 --- # Довідник з конфігурації -Усі поля, доступні в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду за завданнями див. [Configuration](/uk/gateway/configuration). -Формат конфігурації — **JSON5** (дозволені коментарі та коми в кінці). Усі поля необов'язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- @@ -29,28 +29,28 @@ x-i18n: Усі канали підтримують політики DM і політики груп: -| Політика DM | Поведінка | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (default) | Невідомі відправники отримують одноразовий код прив'язки; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів після прив'язки) | -| `open` | Дозволити всі вхідні DM (потрібен `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| Політика DM | Поведінка | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код зв’язування; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених після зв’язування) | +| `open` | Дозволити всі вхідні DM (потрібен `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | | Політика груп | Поведінка | | --------------------- | ----------------------------------------------------- | -| `allowlist` (default) | Лише групи, що відповідають налаштованому списку дозволів | -| `open` | Обходити списки дозволів для груп (перевірка згадувань усе ще застосовується) | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `open` | Обійти списки дозволених для груп (обмеження за згадуванням усе ще застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` постачальника не встановлено. -Коди прив'язки спливають через 1 годину. Кількість очікувальних запитів на прив'язку DM обмежена **3 на канал**. -Якщо блок постачальника повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) з попередженням під час запуску. +`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` у провайдера не встановлено. +Коди зв’язування спливають через 1 годину. Кількість очікуючих запитів на зв’язування DM обмежена **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. -### Перевизначення моделей для каналів +### Перевизначення моделі для каналу -Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналів застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналів застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`). ```json5 { @@ -71,9 +71,9 @@ x-i18n: } ``` -### Значення за замовчуванням для каналів і heartbeat +### Типові значення каналів і heartbeat -Використовуйте `channels.defaults` для спільної політики груп і поведінки heartbeat у всіх постачальників: +Використовуйте `channels.defaults` для спільної поведінки політики груп і heartbeat у різних провайдерів: ```json5 { @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні постачальника не встановлено. -- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (default, включає весь процитований/потоковий/історичний контекст), `allowlist` (включає контекст лише від відправників зі списку дозволів), `allowlist_quote` (як `allowlist`, але зберігає явний контекст цитати/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати стани здорових каналів у вивід heartbeat. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/потоків/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитат/відповідей). Перевизначення на рівні каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати стани справних каналів у вивід heartbeat. - `channels.defaults.heartbeat.showAlerts`: включати стани деградації/помилок у вивід heartbeat. -- `channels.defaults.heartbeat.useIndicator`: рендерити компактний вивід heartbeat у стилі індикатора. +- `channels.defaults.heartbeat.useIndicator`: виводити компактний heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив'язана сесія. +WhatsApp працює через веб-канал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. ```json5 { @@ -110,7 +110,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // сині галочки (false у режимі self-chat) groups: { "*": { requireMention: true }, }, @@ -150,10 +150,10 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- Вихідні команди за замовчуванням використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (відсортований). -- Необов'язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` у `whatsapp/default`. -- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди за замовчуванням використовують обліковий запис `default`, якщо він є; інакше — перший налаштований `account id` (у відсортованому порядку). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Застарілий однообліковий каталог автентифікації Baileys переноситься командою `openclaw doctor` у `whatsapp/default`. +- Перевизначення для окремих облікових записів: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,24 +171,24 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "Відповідай коротко.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "Тримайся теми.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Git-резервна копія" }, + { command: "generate", description: "Створити зображення" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникати обмежень частоти для редагування попереднього перегляду) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Необов'язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- У конфігураціях із кількома обліковими записами (2+ ID облікових записів) встановіть явний обліковий запис за замовчуванням (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення недійсне. -- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив'язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в прямих і групових чатах). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- У багатооблікових конфігураціях (2+ `account id`) задайте явний типовий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення невалідне. +- `configWrites: false` блокує ініційовані через Telegram записи в конфігурацію (міграції ID supergroup, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форумів (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потоку Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). - Політика повторних спроб: див. [Retry policy](/uk/concepts/retry). ### Discord @@ -264,7 +264,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Лише короткі відповіді.", }, }, }, @@ -272,7 +272,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress відображається як partial у Discord) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in для `sessions_spawn({ thread: true })` }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Прямі вихідні виклики, що передають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання. -- Необов'язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. -- Slug guild завжди в нижньому регістрі, а пробіли замінюються на `-`; ключі каналів використовують назву у вигляді slug (без `#`). Надавайте перевагу ID guild. -- Повідомлення, створені ботами, за замовчуванням ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення для каналів) відкидає повідомлення, що згадують іншого користувача чи роль, але не бота (окрім @everyone/@here). -- `maxLinesPerMessage` (default 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією, прив'язаною до потоків Discord: - - `enabled`: перевизначення Discord для можливостей сесій, прив'язаних до потоку (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив'язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного зняття фокусу через неактивність у годинах (`0` вимикає) +- Токен: `channels.discord.token`, із `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; числові ID без префікса відхиляються. +- Slug guild — у нижньому регістрі, з пробілами, заміненими на `-`; ключі каналів використовують slug-ім’я (без `#`). Віддавайте перевагу ID guild. +- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення для каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до потоків Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до потоків (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` та прив’язана доставка/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного зняття фокуса після неактивності в годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив'язки потоків через `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив'язки для каналів і потоків (використовуйте id каналу/потоку в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord v2. -- `channels.discord.voice` вмикає розмови у голосових каналах Discord і необов'язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE для `@discordjs/voice` (`true` і `24` за замовчуванням). -- OpenClaw додатково намагається відновити приймання голосу, виходячи та знову входячи в голосову сесію після повторних помилок дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. -- `channels.discord.autoPresence` відображає доступність середовища виконання на статус бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов'язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінними іменами/тегами (режим сумісності break-glass). -- `channels.discord.execApprovals`: нативна доставка погоджень exec у Discord та авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (default). В auto mode погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов'язковий список дозволених ID агентів. Якщо пропущено, погодження пересилаються для всіх агентів. - - `sessionFilter`: необов'язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (default) надсилає в DM тих, хто погоджує, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли target включає `"channel"`, кнопками можуть користуватися лише визначені ті, хто погоджує. - - `cleanupAfterResolve`: коли `true`, видаляє DM-повідомлення про погодження після погодження, відхилення або тайм-ауту. + - `spawnSubagentSessions`: opt-in перемикач для автоматичного створення/прив’язки потоку `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і потоків (використовуйте ID каналу/потоку в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів Discord components v2. +- `channels.discord.voice` вмикає розмови у голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). +- OpenClaw додатково намагається відновити приймання голосу, виходячи та повторно приєднуючись до голосової сесії після повторних збоїв дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. +- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінними ім’ям/тегом (режим аварійної сумісності). +- `channels.discord.execApprovals`: нативна доставка погоджень exec у Discord і авторизація тих, хто погоджує. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли approvers можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено погоджувати запити exec. Якщо пропущено, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає їх у DM approver’ам, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Якщо target включає `"channel"`, кнопками можуть користуватися лише визначені approver’и. + - `cleanupAfterResolve`: коли `true`, видаляє DM із погодженням після схвалення, відмови або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, за замовчуванням), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). +**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). ### Google Chat @@ -379,11 +379,11 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- JSON облікового запису служби: вбудовано (`serviceAccount`) або через файл (`serviceAccountFile`). -- Також підтримується SecretRef для облікового запису служби (`serviceAccountRef`). +- JSON сервісного облікового запису: вбудований (`serviceAccount`) або з файла (`serviceAccountFile`). +- Також підтримується SecretRef для сервісного облікового запису (`serviceAccountRef`). - Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email-principal (режим сумісності break-glass). +- Використовуйте `spaces/` або `users/` як цілі доставки. +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email principal (режим аварійної сумісності). ### Slack @@ -405,7 +405,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Лише короткі відповіді.", }, }, historyLimit: 50, @@ -433,8 +433,8 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: "partial", // off | partial | block | progress (режим попереднього перегляду) + nativeStreaming: true, // використовувати нативний API потокової передачі Slack, коли streaming=partial mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,34 +448,34 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для облікового запису за замовчуванням). -- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті - рядки або об'єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу облікових даних, як-от - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, в HTTP mode, +- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного підхоплення зі змінних середовища типового облікового запису). +- **HTTP mode** вимагає `botToken` плюс `signingSecret` (на корені або для окремого облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні + рядки або об’єкти SecretRef. +- Знімки облікових записів Slack показують поля джерела/статусу для кожного + облікового запису, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode — `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштований через SecretRef, але поточний шлях команди/середовища виконання не зміг + налаштовано через SecretRef, але поточний шлях команди/runtime не зміг отримати значення секрету. -- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. -- Необов'язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- `channels.slack.streaming` — канонічний ключ режиму потокової передачі. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. -- Використовуйте `user:` (DM) або `channel:` для цілей доставки. +- `configWrites: false` блокує ініційовані через Slack записи в конфігурацію. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- `channels.slack.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. +- Використовуйте `user:` (DM) або `channel:` як цілі доставки. -**Режими сповіщень про реакції:** `off`, `own` (default), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій потоків:** `thread.historyScope` — окремо для потоку (за замовчуванням) або спільно для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові потоки. +**Ізоляція сесій потоків:** `thread.historyScope` — окремо для потоку (типово) або спільно для каналу. `thread.inheritParent` копіює розшифровку батьківського каналу в нові потоки. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а після завершення видаляє її. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна доставка погоджень exec у Slack та авторизація тих, хто погоджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: нативна доставка погоджень exec у Slack і авторизація тих, хто погоджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | За замовчуванням | Примітки | -| ------------ | ---------------- | ------------------------ | -| reactions | увімкнено | Реакції + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріпити/відкріпити/перелічити | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких емодзі | +| Група дій | Типово | Примітки | +| ------------- | -------- | ----------------------- | +| reactions | увімкнено | Реакції + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріпити/відкріпити/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких emoji | ### Mattermost @@ -499,7 +499,7 @@ Mattermost постачається як plugin: `openclaw plugins install @open native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // Необов’язкова явна URL-адреса для розгортань через reverse proxy/публічних розгортань callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,23 +509,23 @@ Mattermost постачається як plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на @-згадування, за замовчуванням), `onmessage` (на кожне повідомлення), `onchar` (на повідомлення, що починаються з префікса-тригера). +Режими чату: `oncall` (відповідати на згадування через @, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з тригерного префікса). -Коли нативні команди Mattermost увімкнено: +Коли нативні команди Mattermost увімкнені: -- `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повним URL. -- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути доступним із сервера Mattermost. -- Нативні callbacks slash-команд автентифікуються через токени для кожної команди, які Mattermost повертає - під час реєстрації slash-команди. Якщо реєстрація не вдасться або жодні - команди не будуть активовані, OpenClaw відхилятиме callbacks з +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. +- `commands.callbackUrl` має вказувати на endpoint gateway OpenClaw і бути доступним із сервера Mattermost. +- Нативні callbacks slash-команд автентифікуються токенами для кожної команди, які + Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або не + активовано жодної команди, OpenClaw відхиляє callbacks із повідомленням `Unauthorized: invalid command token.` - Для приватних/tailnet/internal хостів callback Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback. - Використовуйте значення хоста/домену, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. + щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив callback host/domain. + Використовуйте значення host/domain, а не повні URL-адреси. +- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані через Mattermost записи в конфігурацію. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення перевірки згадувань для окремого каналу (`"*"` для значення за замовчуванням). -- Необов'язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. ### Signal @@ -534,7 +534,7 @@ Mattermost постачається як plugin: `openclaw plugins install @open channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // необов’язкова прив’язка облікового запису dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -546,11 +546,11 @@ Mattermost постачається як plugin: `openclaw plugins install @open } ``` -**Режими сповіщень про реакції:** `off`, `own` (default), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: прив'язати запуск каналу до конкретної ідентичності облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. -- Необов'язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. +- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити ініційовані через Signal записи в конфігурацію. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. ### BlueBubbles @@ -562,21 +562,21 @@ BlueBubbles — рекомендований шлях для iMessage (на ба bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, керування групами та розширені дії: + // див. /channels/bluebubbles }, }, } ``` - Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов'язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив'язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте BlueBubbles handle або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте BlueBubbles handle або target string (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Жоден daemon або порт не потрібен. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. ```json5 { @@ -600,17 +600,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Жоден dae } ``` -- Необов'язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. - Потрібен Full Disk Access до БД Messages. -- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-wrapper; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. -- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (за замовчуванням: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ relay-host уже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив'язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. +- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). +- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ relay-host уже є в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити ініційовані через iMessage записи в конфігурацію. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -652,18 +652,18 @@ Matrix працює через extension і налаштовується в `cha ``` - Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явно заданий HTTP(S)-proxy. Іменовані облікові записи можуть перевизначити це через `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. - `channels.matrix.allowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і `allowPrivateNetwork` — незалежні механізми керування. -- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у конфігураціях із кількома обліковими записами. -- `channels.matrix.execApprovals`: нативна доставка погоджень exec у Matrix та авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (default). В auto mode погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити. - - `agentFilter`: необов'язковий список дозволених ID агентів. Якщо пропущено, погодження пересилаються для всіх агентів. - - `sessionFilter`: необов'язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (default), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сесії: `per-user` (за замовчуванням) ділить за маршрутизованим peer, а `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і пошуки в live-directory використовують ту саму політику proxy, що й трафік середовища виконання. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. +- `channels.matrix.execApprovals`: нативна доставка погоджень exec у Matrix і авторизація тих, хто погоджує. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли approvers можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено погоджувати запити exec. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення для окремих облікових записів: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і пошук у live directory використовують ту саму політику proxy, що й трафік runtime. - Повну конфігурацію Matrix, правила адресації та приклади налаштування описано в [Matrix](/uk/channels/matrix). ### Microsoft Teams @@ -676,15 +676,15 @@ Microsoft Teams працює через extension і налаштовуєтьс msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, політики команд/каналів: + // див. /channels/msteams }, }, } ``` - Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політику DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). +- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих команд/каналів) описано в [Microsoft Teams](/uk/channels/msteams). ### IRC @@ -710,12 +710,12 @@ IRC працює через extension і налаштовується в `channe ``` - Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов'язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим ID облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/mention gating) описано в [IRC](/uk/channels/irc). +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадуванням) описано в [IRC](/uk/channels/irc). ### Багатообліковість (усі канали) -Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): +Запускайте кілька облікових записів для одного каналу (кожен зі своїм `accountId`): ```json5 { @@ -723,11 +723,11 @@ IRC працює через extension і налаштовується в `channe telegram: { accounts: { default: { - name: "Primary bot", + name: "Основний бот", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Бот для сповіщень", botToken: "987654:XYZ...", }, }, @@ -737,27 +737,27 @@ IRC працює через extension і налаштовується в `channe ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени з env застосовуються лише до облікового запису **default**. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені на рівні облікового запису. +- Токени зі змінних середовища застосовуються лише до **типового** облікового запису. +- Базові параметри каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або онбординг каналу), перебуваючи на top-level конфігурації каналу для одного облікового запису, OpenClaw спочатку переносить top-level значення для одного облікового запису, прив'язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис і надалі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти вже наявну відповідну іменовану/default-ціль. -- Наявні прив'язки лише на рівні каналу (без `accountId`) і надалі відповідатимуть default-обліковому запису; прив'язки на рівні облікового запису залишаються необов'язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи top-level значення для одного облікового запису, прив'язані до облікового запису, у promoted-обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти вже наявну відповідну іменовану/default-ціль. +- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або онбординг каналу), поки конфігурація каналу ще однооблікова на верхньому рівні, OpenClaw спочатку переносить account-scoped значення верхнього рівня для однооблікової конфігурації в карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Для більшості каналів вони переміщуються в `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Наявні прив’язки лише для каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з `accountId` залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи account-scoped однооблікові значення верхнього рівня в підвищений обліковий запис, обраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/default ціль. -### Інші канали-extensions +### Інші канали extension -Багато каналів-extension налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів extension налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Перевірка згадувань у групових чатах +### Обмеження за згадуванням у групових чатах -Для групових повідомлень за замовчуванням **потрібне згадування** (метадані згадування або безпечні regex-патерни). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні шаблони regex). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. -**Типи згадувань:** +**Типи згадок:** -- **Згадування в метаданих**: нативні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові патерни**: безпечні regex-патерни в `agents.list[].groupChat.mentionPatterns`. Недійсні патерни й небезпечні вкладені повторення ігноруються. -- Перевірка згадувань застосовується лише тоді, коли виявлення можливе (нативні згадування або щонайменше один патерн). +- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Невалідні шаблони й небезпечні вкладені повтори ігноруються. +- Обмеження за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадки або хоча б один шаблон). ```json5 { @@ -770,7 +770,7 @@ IRC працює через extension і налаштовується в `channe } ``` -`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути. #### Ліміти історії DM @@ -787,13 +787,13 @@ IRC працює через extension і налаштовується в `channe } ``` -Порядок визначення: перевизначення для конкретного DM → значення за замовчуванням постачальника → без ліміту (зберігається все). +Розв’язання: перевизначення для окремого DM → типове значення провайдера → без ліміту (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадування, відповідає лише на текстові патерни): +Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, реагує лише на текстові шаблони): ```json5 { @@ -814,18 +814,18 @@ IRC працює через extension і налаштовується в `channe } ``` -### Команди (обробка команд чату) +### Команди (обробка команд у чаті) ```json5 { commands: { - native: "auto", // register native commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // реєструвати нативні команди там, де це підтримується + text: true, // розбирати /commands у повідомленнях чату + bash: false, // дозволити ! (псевдонім: /bash) bashForegroundMs: 2000, - config: false, // allow /config - debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + config: false, // дозволити /config + debug: false, // дозволити /debug + restart: false, // дозволити /restart + інструмент перезапуску gateway allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -835,28 +835,28 @@ IRC працює через extension і налаштовується в `channe } ``` - + -- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`. -- `native: "auto"` вмикає нативні команди для Discord/Telegram, але лишає Slack вимкненим. -- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для shell хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; режим лише читання `/config show` залишається доступним для звичайних операторських клієнтів із правом запису. -- `channels..configWrites` керує мутаціями конфігурації на рівні каналу (за замовчуванням: true). -- Для багатьох облікових записів `channels..accounts..configWrites` також керує записами, що націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `allowFrom` задається окремо для постачальника. Якщо встановлено, це **єдине** джерело авторизації (списки дозволів каналів/прив'язка та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не задано. +- Текстові команди мають бути **окремими** повідомленнями з початковим `/`. +- `native: "auto"` вмикає нативні команди для Discord/Telegram, але залишає Slack вимкненим. +- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищує раніше зареєстровані команди. +- `channels.telegram.customCommands` додає додаткові записи в меню бота Telegram. +- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів із правом запису. +- `channels..configWrites` контролює мутації конфігурації для кожного каналу (типово: true). +- Для багатооблікових каналів `channels..accounts..configWrites` також контролює записи, що націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналу/зв’язування та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. --- -## Значення за замовчуванням для агентів +## Типові налаштування агентів ### `agents.defaults.workspace` -За замовчуванням: `~/.openclaw/workspace`. +Типово: `~/.openclaw/workspace`. ```json5 { @@ -866,7 +866,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.repoRoot` -Необов'язковий корінь репозиторію, що показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw визначає його автоматично, піднімаючись вгору від workspace. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, підіймаючись угору від workspace. ```json5 { @@ -876,7 +876,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.skills` -Необов'язковий список дозволених Skills за замовчуванням для агентів, які не задають +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -884,23 +884,23 @@ IRC працює через extension і налаштовується в `channe agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // успадковує github, weather + { id: "docs", skills: ["docs-search"] }, // замінює типові значення + { id: "locked-down", skills: [] }, // без Skills ], }, } ``` -- Пропустіть `agents.defaults.skills`, щоб за замовчуванням Skills були без обмежень. -- Пропустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням. -- Установіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. -- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; - він не об'єднується зі значеннями за замовчуванням. +- Пропустіть `agents.defaults.skills`, щоб типово Skills не обмежувалися. +- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. +- Задайте `agents.list[].skills: []`, щоб не мати Skills. +- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він + не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` -Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Вимикає автоматичне створення файлів bootstrap workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -910,9 +910,9 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вбудовуються в системний prompt. За замовчуванням: `"always"`. +Керує тим, коли файли bootstrap workspace вбудовуються в системний prompt. Типово: `"always"`. -- `"continuation-skip"`: безпечні продовжувальні ходи (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після compacting усе одно перебудовують контекст. ```json5 { @@ -922,7 +922,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл workspace до усічення. За замовчуванням: `20000`. +Максимальна кількість символів на файл bootstrap workspace до обрізання. Типово: `20000`. ```json5 { @@ -932,7 +932,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів workspace. За замовчуванням: `150000`. +Максимальна загальна кількість символів, що вбудовуються з усіх файлів bootstrap workspace. Типово: `150000`. ```json5 { @@ -942,12 +942,12 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст усічено. -За замовчуванням: `"once"`. +Керує видимим для агента текстом попередження, коли контекст bootstrap обрізається. +Типово: `"once"`. - `"off"`: ніколи не вбудовувати текст попередження в системний prompt. -- `"once"`: вбудовувати попередження один раз для кожного унікального підпису усічення (рекомендовано). -- `"always"`: вбудовувати попередження при кожному запуску, коли є усічення. +- `"once"`: вбудовувати попередження один раз на кожну унікальну сигнатуру обрізання (рекомендовано). +- `"always"`: вбудовувати попередження при кожному запуску, коли є обрізання. ```json5 { @@ -957,10 +957,10 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами постачальника. -За замовчуванням: `1200`. +Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. +Типово: `1200`. -Менші значення зазвичай зменшують використання vision-token і розмір запиту для сценаріїв зі значною кількістю скриншотів. +Менші значення зазвичай зменшують використання vision-token і розмір корисного навантаження запиту для сценаріїв із великою кількістю скриншотів. Більші значення зберігають більше візуальних деталей. ```json5 @@ -971,7 +971,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не вказано, використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -981,7 +981,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.timeFormat` -Формат часу в системному prompt. За замовчуванням: `auto` (налаштування ОС). +Формат часу в системному prompt. Типово: `auto` (налаштування ОС). ```json5 { @@ -1019,7 +1019,7 @@ IRC працює через extension і налаштовується в `channe primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // глобальні типові параметри провайдера pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1034,43 +1034,43 @@ IRC працює через extension і налаштовується в `channe } ``` -- `model`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - - Рядкова форма задає лише primary model. - - Об'єктна форма задає primary model і впорядкований failover-моделей. -- `imageModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-model. - - Також використовується як резервна маршрутизація, коли вибрана/default model не може приймати вхідні зображення. -- `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). +- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). + - Форма рядка задає лише основну модель. + - Форма об’єкта задає основну модель плюс впорядкований список резервних. +- `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). + - Використовується шляхом інструмента `image` як конфігурація vision-model. + - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. +- `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images. - - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію постачальника/API key (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо поле пропущено, `image_generate` усе одно може вивести provider default на основі автентифікації. Спочатку воно пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. -- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо пропущено, `image_generate` все одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. +- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо поле пропущено, `music_generate` усе одно може вивести provider default на основі автентифікації. Спочатку воно пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації музики в порядку provider-id. - - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію постачальника/API key. -- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). + - Якщо пропущено, `music_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. +- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо поле пропущено, `video_generate` усе одно може вивести provider default на основі автентифікації. Спочатку воно пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації відео в порядку provider-id. - - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію постачальника/API key. - - Вбудований постачальник генерації відео Qwen зараз підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня постачальника `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. -- `pdfModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо поле пропущено, PDF-інструмент повертається до `imageModel`, а потім — до визначеної model сесії/default. -- `pdfMaxBytesMb`: default-ліміт розміру PDF для інструмента `pdf`, якщо `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: default максимальна кількість сторінок, яка враховується в режимі резервного витягування для інструмента `pdf`. -- `verboseDefault`: default рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. За замовчуванням: `"off"`. -- `elevatedDefault`: default рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. За замовчуванням: `"on"`. -- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте provider, OpenClaw спочатку пробує alias, потім — унікальний збіг exact model id серед налаштованих постачальників, і лише потім повертається до налаштованого постачальника за замовчуванням (застаріла сумісна поведінка, тож надавайте перевагу явному `provider/model`). Якщо цей постачальник більше не надає налаштовану default model, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле default від видаленого постачальника. -- `models`: налаштований каталог моделей і список дозволів для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (параметри, специфічні для постачальника, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні параметри постачальника за замовчуванням, що застосовуються до всіх моделей. Встановлюються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфіг): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного agent id) перевизначає за ключем. Детальніше див. у [Prompt Caching](/uk/reference/prompt-caching). -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну object form і по можливості зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів у сесіях (кожна сесія все одно серіалізується). За замовчуванням: 4. + - Якщо пропущено, `video_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. + - Вбудований провайдер генерації відео Qwen наразі підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. +- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). + - Використовується інструментом `pdf` для маршрутизації моделей. + - Якщо пропущено, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель. +- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується в режимі резервного витягування для інструмента `pdf`. +- `verboseDefault`: типовий рівень деталізації для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`. +- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропустите провайдера, OpenClaw спочатку спробує alias, потім унікальний match серед налаштованих провайдерів для точного ID моделі, і лише потім повернеться до налаштованого типового провайдера (застаріла сумісність, тому краще явно використовувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення від видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених моделей для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ID агента) перевизначає за ключами. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. -**Вбудовані скорочення alias** (працюють лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочені alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): | Alias | Модель | | ------------------- | -------------------------------------- | @@ -1083,14 +1083,45 @@ IRC працює через extension і налаштовується в `channe | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані alias завжди мають пріоритет над значеннями за замовчуванням. +Ваші налаштовані alias завжди мають вищий пріоритет за типові. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. -Моделі Z.AI за замовчуванням вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 за замовчуванням використовується `adaptive` thinking, якщо не задано явний рівень thinking. +Для моделей Z.AI GLM-4.x автоматично вмикається режим thinking, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Задайте `agents.defaults.models["zai/"].params.tool_stream` як `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, якщо не задано явний рівень thinking. -- Сесії підтримуються, коли встановлено `sessionArg`. -- Пряме передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. +### `agents.defaults.cliBackends` + +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. + +```json5 +{ + agents: { + defaults: { + cliBackends: { + "codex-cli": { + command: "/opt/homebrew/bin/codex", + }, + "my-cli": { + command: "my-cli", + args: ["--json"], + output: "json", + modelArg: "--model", + sessionArg: "--session", + sessionMode: "existing", + systemPromptArg: "--system", + systemPromptWhen: "first", + imageArg: "--image", + imageMode: "repeat", + }, + }, + }, + }, +} +``` + +- CLI-бекенди орієнтовані на текст; інструменти завжди вимкнені. +- Сесії підтримуються, якщо задано `sessionArg`. +- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.heartbeat` @@ -1101,16 +1132,16 @@ IRC працює через extension і налаштовується в `channe agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace + isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... + prompt: "Прочитай HEARTBEAT.md, якщо він існує...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1119,13 +1150,13 @@ IRC працює через extension і налаштовується в `channe } ``` -- `every`: рядок тривалості (ms/s/m/h). За замовчуванням: `30m` (автентифікація через API key) або `1h` (OAuth-автентифікація). Установіть `0m`, щоб вимкнути. -- `suppressToolErrorWarnings`: якщо true, пригнічує payload попереджень про помилки інструментів під час запусків heartbeat. -- `directPolicy`: політика прямої/DM-доставки. `allow` (default) дозволяє доставку за прямою ціллю. `block` пригнічує доставку за прямою ціллю та видає `reason=dm-blocked`. -- `lightContext`: якщо true, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: якщо true, кожен запуск heartbeat виконується в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у cron `sessionTarget: "isolated"`. Зменшує витрати токенів на heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: установіть `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускатиметься **лише для цих агентів**. -- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. +- `suppressToolErrorWarnings`: коли true, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. +- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та видає `reason=dm-blocked`. +- `lightContext`: коли true, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: коли true, кожен heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeats запускаються **лише для цих агентів**. +- Heartbeats виконують повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1138,15 +1169,15 @@ IRC працює через extension і налаштовується в `channe timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Зберігайте ID розгортання, ID квитків і пари host:port точно без змін.", // використовується, коли identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction + notifyUser: true, // надсилати коротке повідомлення, коли починається compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Сесія наближається до compaction. Збережіть довготривалі спогади зараз.", + prompt: "Запишіть будь-які тривалі нотатки в memory/YYYY-MM-DD.md; дайте точну тиху відповідь токеном NO_REPLY, якщо нічого зберігати.", }, }, }, @@ -1154,18 +1185,18 @@ IRC працює через extension і налаштовується в `channe } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw перериває її. За замовчуванням: `900`. -- `identifierPolicy`: `strict` (default), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час compaction summarization. -- `identifierInstructions`: необов'язковий текст користувацьких вказівок щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов'язкові назви секцій H2/H3 з AGENTS.md, які повторно вбудовуються після compaction. За замовчуванням `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вбудовування. Коли поле не задано або явно дорівнює цій парі за замовчуванням, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. -- `model`: необов'язкове перевизначення `provider/model-id` лише для summarization під час compaction. Використовуйте це, коли основна сесія має лишатися на одній моделі, але summaries compaction мають виконуватися на іншій; якщо не задано, compaction використовує primary model сесії. -- `notifyUser`: якщо `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). За замовчуванням вимкнено, щоб compaction відбувався непомітно. -- `memoryFlush`: тихий agentic-хід перед auto-compaction для збереження довготривалої пам'яті. Пропускається, коли workspace лише для читання. +- `mode`: `default` або `safeguard` (узагальнення довгих історій шматками). Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типово: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. +- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які слід повторно вбудувати після compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Якщо не встановлено або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має працювати на одній моделі, а підсумки compaction — на іншій; якщо не встановлено, compaction використовує основну модель сесії. +- `notifyUser`: коли `true`, надсилає користувачу коротке сповіщення, коли починається compaction (наприклад, "Compacting context..."). За замовчуванням вимкнено, щоб compaction залишався тихим. +- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження довготривалих спогадів. Пропускається, коли workspace лише для читання. ### `agents.defaults.contextPruning` -Очищає **старі результати інструментів** з in-memory-контексту перед відправленням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням у LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1173,13 +1204,13 @@ IRC працює через extension і налаштовується в `channe defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Вміст старого результату інструмента очищено]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1190,22 +1221,22 @@ IRC працює через extension і налаштовується в `channe - `mode: "cache-ttl"` вмикає проходи pruning. -- `ttl` керує тим, як часто pruning може запускатися знову (після останнього дотику до cache). -- Pruning спочатку м'яко обрізає надто великі результати інструментів, а потім за потреби жорстко очищає старіші результати інструментів. +- `ttl` керує тим, як часто pruning може запускатися знову (після останнього торкання кешу). +- Pruning спочатку м’яко обрізає завеликі результати інструментів, а потім повністю очищує старіші результати інструментів, якщо це потрібно. -**Soft-trim** зберігає початок і кінець та вставляє `...` посередині. +**Soft-trim** зберігає початок і кінець, вставляючи `...` посередині. -**Hard-clear** повністю замінює результат інструмента на placeholder. +**Hard-clear** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються/не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. -- Якщо повідомлень assistant менше, ніж `keepLastAssistants`, pruning пропускається. +- Блоки зображень ніколи не обрізаються й не очищуються. +- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. +- Якщо є менше ніж `keepLastAssistants` повідомлень помічника, pruning пропускається. -Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). +Докладніше див. [Session Pruning](/uk/concepts/session-pruning). ### Блокова потокова передача @@ -1217,19 +1248,19 @@ IRC працює через extension і налаштовується в `channe blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs) }, }, } ``` -- Не-Telegram канали потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналу: `channels..blockStreamingCoalesce` (та варіанти на рівні облікового запису). Для Signal/Slack/Discord/Google Chat за замовчуванням `minChars: 1500`. +- Для каналів, окрім Telegram, потрібен явний `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. - `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Деталі поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming). +Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про поведінку та деталі chunking. -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -1242,7 +1273,7 @@ IRC працює через extension і налаштовується в `channe } ``` -- За замовчуванням: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадування. +- Типові значення: `instant` для приватних чатів/згадок, `message` для групових чатів без згадки. - Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1251,7 +1282,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.sandbox` -Необов'язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1297,7 +1328,7 @@ IRC працює через extension і налаштовується в `channe identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // Також підтримуються SecretRefs / вбудований вміст: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1346,22 +1377,22 @@ IRC працює через extension і налаштовується в `channe } ``` - + -**Backend:** +**Бекенд:** -- `docker`: локальне середовище виконання Docker (за замовчуванням) -- `ssh`: загальне віддалене середовище виконання на базі SSH -- `openshell`: середовище виконання OpenShell +- `docker`: локальний runtime Docker (типово) +- `ssh`: загальний віддалений runtime на базі SSH +- `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для середовища виконання, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до `plugins.entries.openshell.config`. -**Конфігурація backend SSH:** +**Конфігурація SSH-бекенда:** - `target`: SSH-ціль у форматі `user@host[:port]` -- `command`: команда SSH-клієнта (за замовчуванням: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь для workspace за кожною областю +- `command`: команда SSH-клієнта (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, який використовується для workspace за scope - `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH @@ -1371,27 +1402,27 @@ IRC працює через extension і налаштовується в `channe - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка secrets runtime перед початком sandbox-сесії +- Значення `*Data` на базі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox -**Поведінка backend SSH:** +**Поведінка SSH-бекенда:** -- один раз ініціалізує віддалений workspace після створення або повторного створення -- далі зберігає віддалений SSH-workspace канонічним -- маршрутизує `exec`, файлові інструменти та шляхи до media через SSH -- не синхронізує автоматично віддалені зміни назад на хост -- не підтримує контейнерів браузера в sandbox +- один раз засіває віддалений workspace після створення або перевідтворення +- потім підтримує віддалений SSH-workspace як канонічний +- маршрутизує `exec`, файлові інструменти та media-шляхи через SSH +- не синхронізує віддалені зміни назад на хост автоматично +- не підтримує браузерні контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox за кожною областю в `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано лише для читання в `/agent` +- `none`: workspace sandbox за scope під `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано тільки для читання в `/agent` - `rw`: workspace агента змонтовано для читання/запису в `/workspace` -**Область:** +**Scope:** -- `session`: окремий контейнер + workspace на сесію -- `agent`: один контейнер + workspace на агента (за замовчуванням) -- `shared`: спільний контейнер і workspace (без міжсесійної ізоляції) +- `session`: окремий контейнер + workspace для кожної сесії +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без ізоляції між сесіями) **Конфігурація plugin OpenShell:** @@ -1406,10 +1437,10 @@ IRC працює через extension і налаштовується в `channe from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // необов’язково + gatewayEndpoint: "https://lab.example", // необов’язково + policy: "strict", // необов’язковий ID політики OpenShell + providers: ["openai"], // необов’язково autoProviders: true, timeoutSeconds: 120, }, @@ -1421,30 +1452,30 @@ IRC працює через extension і налаштовується в `channe **Режим OpenShell:** -- `mirror`: ініціалізувати віддалене середовище з локального перед exec, синхронізувати назад після exec; локальний workspace лишається канонічним -- `remote`: один раз ініціалізувати віддалене середовище під час створення sandbox, далі віддалений workspace лишається канонічним +- `mirror`: засіяти remote з local перед exec, синхронізувати назад після exec; local workspace лишається канонічним +- `remote`: засіяти remote один раз при створенні sandbox, потім підтримувати remote workspace як канонічний -У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але plugin володіє життєвим циклом sandbox і необов'язковою синхронізацією mirror. +У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після кроку засівання. +Транспорт — це SSH у sandbox OpenShell, але plugin володіє життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного root і користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, доступний для запису root і root user. -**Контейнери за замовчуванням мають `network: "none"`** — установіть `"bridge"` (або кастомну bridge-мережу), якщо агенту потрібен вихід назовні. -`"host"` заблоковано. `"container:"` за замовчуванням теж заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). +**Для контейнерів типовим є `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід у мережу. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). -**Вхідні вкладення** staging'уються до `media/inbound/*` в активному workspace. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні й агентські binds об'єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні й агентні `binds` об’єднуються. -**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний prompt. Не потребує `browser.enabled` в `openclaw.json`. -Доступ спостерігача через noVNC за замовчуванням використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб розкривати пароль у спільному URL). -- `allowHostControl: false` (default) блокує націлювання sandboxed-сесій на браузер хоста. -- `network` за замовчуванням дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам справді потрібна глобальна bridge-зв'язність. +- `allowHostControl: false` (типово) блокує націлювання на браузер хоста із sandbox-сесій. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна загальна bridge-зв’язність. - `cdpSourceRange` за потреби обмежує вхід до CDP на межі контейнера CIDR-діапазоном (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox-browser. Якщо параметр задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. -- Значення запуску за замовчуванням визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо встановлено (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску задано в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1461,28 +1492,28 @@ IRC працює через extension і налаштовується в `channe - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (за замовчуванням увімкнено) + - `--disable-extensions` (типово увімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - увімкнені за замовчуванням і можуть бути вимкнені через + типово увімкнені й можуть бути вимкнені через `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо від них - залежить ваш сценарій роботи. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо ваш робочий процес + від них залежить. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - стандартне обмеження процесів Chromium. - - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. - - Значення за замовчуванням є базовими для образу контейнера; використовуйте користувацький browser image з власним - entrypoint, щоб змінити типові налаштування контейнера. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; задайте `0`, щоб використати + типове обмеження процесів Chromium. + - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; використовуйте власний browser image з власною + entrypoint, щоб змінити типові параметри контейнера. -Ізоляція браузера та `sandbox.docker.binds` наразі підтримуються лише для Docker. +Sandboxing браузера і `sandbox.docker.binds` наразі доступні лише для Docker. -Збирання образів: +Зібрати образи: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) @@ -1494,18 +1525,18 @@ scripts/sandbox-browser-setup.sh # optional browser image { id: "main", default: true, - name: "Main Agent", + name: "Головний агент", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } + thinkingDefault: "high", // перевизначення рівня thinking для окремого агента + reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента + fastModeDefault: false, // перевизначення fast mode для окремого агента + params: { cacheRetention: "none" }, // перевизначає ключі matching defaults.models params + skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", - theme: "helpful sloth", + theme: "кориснивий лінивець", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1533,26 +1564,26 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: стабільний ID агента (обов'язково). -- `default`: якщо встановлено для кількох, перший має пріоритет (записується попередження). Якщо не встановлено для жодного, default — перший елемент списку. -- `model`: рядкова форма перевизначає лише `primary`; об'єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron jobs, які перевизначають лише `primary`, все одно успадковують default fallback, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для агентоспецифічних перевизначень, наприклад `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. -- `skills`: необов'язковий список дозволених Skills для окремого агента. Якщо його пропущено, агент успадковує `agents.defaults.skills`, якщо той задано; явний список замінює значення за замовчуванням, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов'язковий default рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення на рівні повідомлення або сесії. -- `reasoningDefault`: необов'язкове default перевизначення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning на рівні повідомлення або сесії. -- `fastModeDefault`: необов'язкове default перевизначення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast-mode на рівні повідомлення або сесії. -- `runtime`: необов'язковий опис runtime для окремого агента. Використовуйте `type: "acp"` разом з default-значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати ACP-harness sessions. -- `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI. -- `identity` виводить значення за замовчуванням: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених agent id для `sessions_spawn` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (вимагає явного вибору профілю; за замовчуванням: false). +- `id`: стабільний ID агента (обов’язково). +- `default`: якщо встановлено для кількох, перший перемагає (із попередженням у журналі). Якщо не встановлено ні для кого, типовим стає перший елемент списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallbacks). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallbacks, якщо ви не задасте `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для агентних перевизначень, наприклад `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо він заданий; явний список замінює типові значення, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення або сесії. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast-mode для окремого повідомлення або сесії. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії ACP harness. +- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `subagents.allowAgents`: список дозволених ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які виконувалися б без sandbox. +- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). --- -## Маршрутизація кількох агентів +## Маршрутизація з кількома агентами -Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1571,27 +1602,27 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Поля match для binding -- `type` (необов'язково): `route` для звичайної маршрутизації (відсутній type означає route), `acp` для постійних ACP-прив'язок розмов. -- `match.channel` (обов'язково) -- `match.accountId` (необов'язково; `*` = будь-який обліковий запис; якщо пропущено = default-обліковий запис) -- `match.peer` (необов'язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов'язково; залежить від каналу) -- `acp` (необов'язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` за замовчуванням означає route), `acp` для постійних ACP-прив’язок розмов. +- `match.channel` (обов’язково) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) +- `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок збігу:** +**Детермінований порядок match:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (по всьому каналу) -6. Default-агент +5. `match.accountId: "*"` (на рівні каналу) +6. Типовий агент -У межах кожного рівня перший відповідний запис `bindings` має пріоритет. +У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route binding, наведений вище. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route binding, описаний вище. -### Профілі доступу для окремого агента +### Профілі доступу для окремих агентів @@ -1611,7 +1642,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1640,7 +1671,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1690,7 +1721,7 @@ scripts/sandbox-browser-setup.sh # optional browser image --- -## Session +## Сесія ```json5 { @@ -1712,22 +1743,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // пропустити fork батьківського потоку вище цього числа токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // тривалість або false + maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет + highWaterBytes: "400mb", // необов’язкова ціль очищення }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) + maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // застаріле (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1737,48 +1768,48 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - - `per-sender` (за замовчуванням): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу ділять одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). + - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст справді потрібен). - **`dmScope`**: як групуються DM. - - `main`: усі DM використовують main session. - - `per-peer`: ізоляція за sender id між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox з багатьма користувачами). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості). -- **`identityLinks`**: відображення канонічних id на peer з префіксом provider для спільного використання сесії між каналами. -- **`reset`**: основна політика reset. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що настане раніше. -- **`resetByType`**: перевизначення для типів (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення forked thread session (за замовчуванням `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову thread session замість успадкування історії transcript батьківської сесії. - - Установіть `0`, щоб вимкнути цей запобіжник і завжди дозволяти fork від батьківської сесії. -- **`mainKey`**: застаріле поле. Тепер середовище виконання завжди використовує `"main"` для основного direct-chat bucket. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обмінів agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. -- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny має пріоритет. -- **`maintenance`**: очищення сховища сесій + контроль retention. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: віковий cutoff для застарілих записів (за замовчуванням `30d`). - - `maxEntries`: максимальна кількість записів у `sessions.json` (за замовчуванням `500`). - - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (за замовчуванням `10mb`). - - `resetArchiveRetention`: retention для архівів transcript `*.reset.`. За замовчуванням дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов'язковий ліміт дискового простору для каталогу сесій. У режимі `warn` логуються попередження; у режимі `enforce` спочатку видаляються найстаріші артефакти/сесії. - - `highWaterBytes`: необов'язкова ціль після очищення за бюджетом. За замовчуванням дорівнює `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні значення за замовчуванням для можливостей сесій, прив'язаних до потоків. - - `enabled`: головний перемикач за замовчуванням (postачальники можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: default авто-зняття фокусу через неактивність у годинах (`0` вимикає; postачальники можуть перевизначати) - - `maxAgeHours`: default жорсткий максимальний вік у годинах (`0` вимикає; postачальники можуть перевизначати) + - `main`: усі DM використовують спільну головну сесію. + - `per-peer`: ізоляція за ID відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багато користувацьких inbox). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). +- **`identityLinks`**: мапа канонічних ID до peers із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` — після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що закінчується раніше. +- **`resetByType`**: перевизначення для окремих типів (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений при створенні forked thread session (типово `100000`). + - Якщо `totalTokens` батьківської сесії вищий за це значення, OpenClaw запускає нову thread session замість успадкування історії transcript батьківської сесії. + - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти parent forking. +- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для головного кошика direct-chat. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у форматі reply-back між агентами під час agent-to-agent обміну (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. +- **`sendPolicy`**: match за `channel`, `chatType` (`direct|group|channel`, зі старим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша відмова перемагає. +- **`maintenance`**: очищення сховища сесій + керування строком зберігання. + - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. + - `pruneAfter`: граничний вік для застарілих записів (типово `30d`). + - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). + - `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: строк зберігання архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` він лише пише попередження в журнал; у режимі `enforce` він спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. + - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) + - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) --- -## Messages +## Повідомлення ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // або "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1793,7 +1824,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 вимикає byChannel: { whatsapp: 5000, slack: 1500, @@ -1807,7 +1838,7 @@ scripts/sandbox-browser-setup.sh # optional browser image Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення (перемагає найспецифічніше): account → channel → global. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Розв’язання (найспецифічніше перемагає): account → channel → global. `""` вимикає та зупиняє каскад. `"auto"` виводиться як `[{identity.name}]`. **Змінні шаблону:** @@ -1815,26 +1846,26 @@ scripts/sandbox-browser-setup.sh # optional browser image | ----------------- | ----------------------- | --------------------------- | | `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва постачальника | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | +| `{identity.name}` | Ім’я ідентичності агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. -### Ack reaction +### Реакція підтвердження -- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: account → channel → `messages.ackReaction` → резервний варіант з identity. -- Область: `group-mentions` (за замовчуванням), `group-all`, `direct`, `all`. +- Порядок розв’язання: account → channel → `messages.ackReaction` → резервне значення з identity. +- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. - `removeAckAfterReply`: видаляє ack після відповіді у Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. - У Slack і Discord, якщо параметр не задано, реакції статусу лишаються увімкненими, коли активні ack reaction. - У Telegram потрібно явно встановити `true`, щоб увімкнути реакції статусу життєвого циклу. +- `messages.statusReactions.enabled`: вмикає реакції життєвого циклу статусу у Slack, Discord і Telegram. + У Slack і Discord відсутнє значення зберігає status reactions увімкненими, коли активні ack reactions. + У Telegram явно задайте `true`, щоб увімкнути status reactions. -### Debounce для вхідних повідомлень +### Вхідний debounce -Об'єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Media/вкладення скидаються одразу. Керувальні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. ### TTS (text-to-speech) @@ -1877,18 +1908,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує auto-TTS. `/tts off|always|inbound|tagged` перевизначає налаштування для сесії. -- `summaryModel` перевизначає `agents.defaults.model.primary` для auto-summary. -- `modelOverrides` увімкнено за замовчуванням; для `modelOverrides.allowProvider` за замовчуванням встановлено `false` (потрібне явне ввімкнення). +- `auto` керує автоматичним TTS. `/tts off|always|inbound|tagged` перевизначає це для сесії. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автопідсумку. +- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово `false` (opt-in). - API keys резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: config, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на не-OpenAI endpoint, OpenClaw розглядає його як OpenAI-compatible TTS server і послаблює перевірку model/voice. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-compatible TTS server і послаблює перевірку model/voice. --- ## Talk -Значення за замовчуванням для режиму Talk (macOS/iOS/Android). +Типові налаштування для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1912,51 +1943,51 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька Talk providers. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) сумісні лише для зворотної сумісності й автоматично мігруються в `talk.providers.`. +- `talk.provider` має відповідати ключу в `talk.providers`, якщо налаштовано кілька Talk-провайдерів. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) сумісні лише для підтримки та автоматично мігруються в `talk.providers.`. - Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає відкриті рядки або об'єкти SecretRef. -- Резервний `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` визначає, скільки Talk mode чекатиме після мовчання користувача, перш ніж надіслати transcript. Якщо не встановлено, зберігається pause window платформи за замовчуванням (`700 ms на macOS і Android, 900 ms на iOS`). +- `providers.*.apiKey` приймає звичайні рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. +- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні імена. +- `silenceTimeoutMs` визначає, скільки Talk mode чекає після мовчання користувача, перш ніж надіслати transcript. Якщо не задано, використовується типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- -## Tools +## Інструменти ### Профілі інструментів -`tools.profile` задає базовий список дозволів перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: -Під час локального онбордингу нові локальні конфігурації за замовчуванням отримують `tools.profile: "coding"`, якщо параметр не встановлено (наявні явні профілі зберігаються). +Локальний онбординг за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Містить | +| Профіль | Включає | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (так само, як якщо не задано) | +| `full` | Без обмежень (те саме, що й відсутність значення) | ### Групи інструментів -| Група | Інструменти | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без provider plugins) | +| Група | Інструменти | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation`| `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (без provider plugins) | ### `tools.allow` / `tools.deny` -Глобальна політика allow/deny для інструментів (deny має пріоритет). Регістронезалежна, підтримує шаблони `*`. Застосовується, навіть коли Docker sandbox вимкнено. +Глобальна політика allow/deny для інструментів (deny має вищий пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -1966,7 +1997,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.byProvider` -Додатково обмежує інструменти для конкретних постачальників або моделей. Порядок: базовий profile → profile постачальника → allow/deny. +Додатково обмежує інструменти для певних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny. ```json5 { @@ -2000,7 +2031,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціллю exec є `node`). +- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2024,8 +2055,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки tool-loop **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб активувати виявлення. -Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб активувати виявлення. +Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2046,14 +2077,14 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `historySize`: максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. +- `criticalThreshold`: вищий поріг повторів для блокування критичних циклів. - `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. -- `detectors.genericRepeat`: попереджати про повторювані виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування без прогресу у парах викликів. -- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. +- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати чергування шаблонів без прогресу. +- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. ### `tools.web` @@ -2063,14 +2094,14 @@ scripts/sandbox-browser-setup.sh # optional browser image web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // або BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // необов’язково; пропустіть для auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2087,7 +2118,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.media` -Налаштовує розуміння вхідних media (зображення/аудіо/відео): +Налаштовує розуміння вхідного медіаконтенту (зображення/аудіо/відео): ```json5 { @@ -2095,7 +2126,7 @@ scripts/sandbox-browser-setup.sh # optional browser image media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: надсилати завершені асинхронні музичні/відеозавдання безпосередньо в канал }, audio: { enabled: true, @@ -2121,30 +2152,30 @@ scripts/sandbox-browser-setup.sh # optional browser image -**Запис постачальника** (`type: "provider"` або пропущено): +**Запис провайдера** (`type: "provider"` або пропущено): -- `provider`: ID API-постачальника (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення model id -- `profile` / `preferredProfile`: вибір profile у `auth-profiles.json` +- `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `model`: перевизначення ID моделі +- `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` **CLI-запис** (`type: "cli"`): - `command`: виконуваний файл -- `args`: аргументи-шаблони (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: параметризовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** -- `capabilities`: необов'язковий список (`image`, `audio`, `video`). За замовчуванням: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного запису. -- Помилки переводять виконання до наступного запису. +- `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. +- У разі помилки використовується наступний запис. -Автентифікація постачальників дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. +Автентифікація провайдера використовує стандартний порядок: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Поля async completion:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. За замовчуванням: `false` - (застарілий шлях requester-session wake/model-delivery). + і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типово: `false` + (застарілий шлях пробудження requester-session/model-delivery). @@ -2163,9 +2194,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, які сесії можуть бути ціллю для session tools (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, які сесії можуть бути цілями для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). -За замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). +Типово: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). ```json5 { @@ -2180,26 +2211,26 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `self`: лише поточний session key. +- `self`: лише ключ поточної сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (subagents). -- `agent`: будь-яка сесія, що належить поточному agent id (може включати інших користувачів, якщо ви використовуєте per-sender sessions під тим самим agent id). +- `agent`: будь-яка сесія, що належить поточному ID агента (може включати інших користувачів, якщо ви використовуєте сесії per-sender під одним ID агента). - `all`: будь-яка сесія. Націлення між агентами все одно потребує `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. +- Sandbox clamp: коли поточна сесія виконується в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Керує підтримкою inline-вкладень для `sessions_spawn`. +Керує підтримкою вбудованих вкладень для `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: установіть true, щоб дозволити вбудовані вкладення файлів + maxTotalBytes: 5242880, // 5 MB сумарно для всіх файлів maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB на файл + retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep" }, }, }, @@ -2209,21 +2240,21 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. ACP runtime їх відхиляє. -- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується з transcript persistence. -- Base64-входи перевіряються за суворими правилами алфавіту/відступів і з перевіркою розміру до декодування. -- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Файли матеріалізуються в child workspace за шляхом `.openclaw/attachments//` з файлом `.manifest.json`. +- Вміст вкладень автоматично редагується з persistence transcript. +- Входи Base64 перевіряються зі строгими правилами alphabet/padding і захистом розміру до декодування. +- Дозволи на файли: `0700` для каталогів і `0600` для файлів. +- Очищення підкоряється політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Експериментальні прапорці для вбудованих інструментів. За замовчуванням вимкнено, якщо не діє автоматичне ввімкнення, специфічне для runtime. +Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не діє правило автоматичного ввімкнення, залежне від runtime. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // увімкнути експериментальний update_plan }, }, } @@ -2232,8 +2263,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- За замовчуванням: `false` для не-OpenAI постачальників. Під час запусків OpenAI і OpenAI Codex він вмикається автоматично. -- Коли ввімкнено, системний prompt також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи та тримала щонайбільше один крок у стані `in_progress`. +- Типово: `false` для провайдерів, відмінних від OpenAI. Запуски OpenAI та OpenAI Codex вмикають його автоматично. +- Коли ввімкнено, системний prompt також додає інструкції з використання, щоб модель застосовувала його лише для суттєвої роботи й утримувала не більше одного кроку в стані `in_progress`. ### `agents.defaults.subagents` @@ -2253,21 +2284,21 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: default model для породжених sub-agent. Якщо пропущено, sub-agents успадковують model викликача. -- `allowAgents`: default список дозволених target agent id для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). -- `runTimeoutSeconds`: default timeout (у секундах) для `sessions_spawn`, коли у виклику інструмента пропущено `runTimeoutSeconds`. `0` означає відсутність timeout. +- `model`: типова модель для spawned sub-agents. Якщо пропущено, sub-agents успадковують модель викликача. +- `allowAgents`: типовий список дозволених ID цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. - Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Користувацькі постачальники та base URL +## Власні провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких постачальників через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (типово) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2291,48 +2322,48 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для спеціальних потреб автентифікації. -- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). -- Пріоритет злиття для однакових provider ID: +- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. +- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). +- Пріоритет злиття для відповідних ID провайдера: - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. - - Непорожні значення `apiKey` з агента мають пріоритет лише тоді, коли цей provider не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` для provider, керованих через SecretRef, оновлюються з source marker (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження визначених секретів. - - Значення заголовків provider, керованих через SecretRef, оновлюються з source marker (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). - - Порожні або відсутні `apiKey`/`baseUrl` в агенті повертаються до `models.providers` у конфігурації. - - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явний runtime cap, коли той заданий; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження marker є source-authoritative: markers записуються з активного знімка вихідної конфігурації (до визначення), а не з визначених runtime secret values. + - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження вже визначених секретів. + - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). + - Порожні або відсутні `apiKey`/`baseUrl` агента резервно беруться з `models.providers` у конфігурації. + - Для відповідних моделей `contextWindow`/`maxTokens` використовується вище значення з явної конфігурації та неявних значень каталогу. + - Для відповідних моделей `contextTokens` зберігає явне runtime-обмеження, якщо воно присутнє; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю перезаписала `models.json`. + - Збереження маркерів є авторитетним відносно джерела: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних runtime-значень секретів. -### Деталі полів постачальника +### Деталі полів провайдера -- `models.mode`: поведінка каталогу постачальників (`merge` або `replace`). -- `models.providers`: карта користувацьких постачальників за ключем provider id. -- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані постачальника (краще через SecretRef/env substitution). +- `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). +- `models.providers`: мапа власних провайдерів за ключем provider id. +- `models.providers.*.api`: адаптер запиту (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). +- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/env substitution). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовувати `options.num_ctx` у запити (за замовчуванням: `true`). -- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, якщо це потрібно. -- `models.providers.*.baseUrl`: базовий URL зовнішнього API. -- `models.providers.*.headers`: додаткові статичні заголовки для proxy/tenant-routing. +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. +- `models.providers.*.baseUrl`: базова URL upstream API. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. - `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (зливаються зі стандартними заголовками постачальника). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію постачальника), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов'язковим `prefix`). - - `request.proxy`: перевизначення HTTP-proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов'язковий підоб'єкт `tls`. - - `request.tls`: перевизначення TLS для прямих з'єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. -- `models.providers.*.models`: явні записи каталогу моделей постачальника. -- `models.providers.*.models.*.contextWindow`: метадані нативного context window моделі. -- `models.providers.*.models.*.contextTokens`: необов'язкове runtime-обмеження контексту. Використовуйте це, коли хочете мати менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов'язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім не-нативним `baseUrl` (host не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час виконання. Порожній/пропущений `baseUrl` зберігає стандартну поведінку OpenAI. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань auto-discovery Bedrock. + - `request.headers`: додаткові заголовки (об’єднуються з типовими заголовками провайдера). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). + - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. + - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. +- `models.providers.*.models`: явні записи каталогу моделей провайдера. +- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. +- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативне `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/відсутній `baseUrl` зберігає типову поведінку OpenAI. +- `plugins.entries.amazon-bedrock.config.discovery`: кореневі налаштування auto-discovery Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне discovery. -- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS region для discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов'язковий фільтр provider-id для цільового discovery. +- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового discovery. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення discovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне context window для виявлених моделей. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для знайдених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для знайдених моделей. -### Приклади постачальників +### Приклади провайдерів @@ -2402,11 +2433,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. Приймаються alias `z.ai/*` і `z-ai/*`. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` -- Endpoint для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте користувацького постачальника з перевизначенням base URL. +- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте власного провайдера з перевизначенням base URL. @@ -2445,11 +2476,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Для endpoint Китаю: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. +Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot декларують сумісність використання streaming на спільному +Нативні endpoints Moonshot оголошують сумісність зі streaming usage на спільному транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями endpoint, -а не лише за built-in provider id. +а не лише за вбудованим provider id. @@ -2467,11 +2498,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Вбудований постачальник, сумісний з Anthropic. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2510,7 +2541,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - + ```json5 { @@ -2549,17 +2580,17 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. -Каталог моделей тепер за замовчуванням містить лише M2.7. -На Anthropic-compatible streaming path OpenClaw за замовчуванням вимикає thinking для MiniMax, -якщо ви явно не встановите `thinking` самостійно. `/fast on` або -`params.fastMode: true` переписує `MiniMax-M2.7` у +Каталог моделей тепер типово містить лише M2.7. +На Anthropс-compatible streaming path OpenClaw типово вимикає MiniMax thinking, +якщо ви явно самі не задасте `thinking`. `/fast on` або +`params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на потужному обладнанні; залишайте hosted models злитими як резервний варіант. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте хостовані моделі в режимі merge як резерв. @@ -2580,7 +2611,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або звичайний рядок env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2590,14 +2621,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов'язковий список дозволених лише для bundled Skills (managed/workspace Skills це не зачіпає). +- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (managed/workspace Skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли true, віддавати перевагу інсталяторам Homebrew, якщо - `brew` доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: пріоритет node-інсталятора для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли true, віддавати перевагу інсталяторам Homebrew, якщо `brew` + доступний, перш ніж повертатися до інших типів інсталяторів. +- `install.nodeManager`: бажаний node installer для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає Skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручне поле API key для Skills, які оголошують основну env var (відкритий рядок або об'єкт SecretRef). +- `entries..apiKey`: зручне поле API key для Skills, які оголошують primary env var (звичайний рядок або об’єкт SecretRef). --- @@ -2626,10 +2657,6 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. -- Discovery приймає нативні plugins OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude без manifest у стандартному layout. -- **Зміни конфігурації потребують перезапуску шлюзу.** -- `allow`: необов'язковий список дозволених plugins (завантажуються лише перелічені plugins). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні plugin (коли plugin це підтримує). -- `plugins.entries..env`: карта env vars для окремого plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Це стосується нативних plugin hooks і підтримуваних каталогів hooks, наданих пакетами. -- `plugins.entries..subagent.allowModelOverride \ No newline at end of file +- Discovery приймає нативні OpenClaw plugins, а також сумісні пакети Codex і Claude, включно з manifestless Claude default-layout bundles. +- **Зміни конфігурації вимагають перезапуску gateway.** +- `allow`: необов’язковий список дозволених (завантажуються лише перелічені plugins). `deny` має вищий \ No newline at end of file diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index dbda51f3c..f04790639 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,22 +1,21 @@ --- read_when: - Додавання або зміна міграцій doctor - - Упровадження несумісних змін конфігурації -summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки виправлення' + - Запровадження несумісних змін конфігурації +summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-05T18:04:19Z" + generated_at: "2026-04-06T12:44:06Z" model: gpt-5.4 provider: openai - source_hash: 6c0a15c522994552a1eef39206bed71fc5bf45746776372f24f31c101bfbd411 + source_hash: f20637d373c3b1be7c4a3d5424228908b5639cfded8ad5acb9c29f882d0f8d2b source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` — це інструмент відновлення й міграції для OpenClaw. Він виправляє застарілий -стан/конфігурацію, перевіряє працездатність і надає практичні кроки для виправлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для виправлення. ## Швидкий старт @@ -24,38 +23,38 @@ x-i18n: openclaw doctor ``` -### Headless / автоматизація +### Безголовий режим / автоматизація ```bash openclaw doctor --yes ``` -Прийняти типові варіанти без запитів (включно з кроками відновлення restart/service/sandbox, якщо застосовно). +Приймає типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно). ```bash openclaw doctor --repair ``` -Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). +Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). ```bash openclaw doctor --repair --force ``` -Застосувати також агресивні виправлення (перезаписує власні конфігурації supervisor). +Застосовує також агресивні виправлення (перезаписує користувацькі конфігурації supervisor). ```bash openclaw doctor --non-interactive ``` -Запуск без запитів із застосуванням лише безпечних міграцій (нормалізація конфігурації + переміщення стану на диску). Пропускає дії restart/service/sandbox, які потребують підтвердження людини. +Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, якщо їх виявлено. ```bash openclaw doctor --deep ``` -Просканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks). +Сканує системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks). Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: @@ -65,62 +64,62 @@ cat ~/.openclaw/openclaw.json ## Що він робить (коротко) -- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі). -- Перевірка актуальності протоколу UI (перезбирає Control UI, якщо схема протоколу новіша). -- Перевірка стану + запит на перезапуск. -- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан плагінів. +- Необов’язкове передстартове оновлення для git-інсталяцій (лише в інтерактивному режимі). +- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). +- Перевірка справності + запит на перезапуск. +- Зведення стану Skills (доступні/відсутні/заблоковані) і стану плагінів. - Нормалізація конфігурації для застарілих значень. -- Міграція конфігурації Talk із застарілих плоских полів `talk.*` до `talk.provider` + `talk.providers.`. -- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. -- Попередження щодо перевизначень провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Перевірка передумов TLS для OAuth-профілів OpenAI Codex. -- Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth). -- Міграція застарілих ключів контракту manifest плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні webhook-завдання з `notify: true`). -- Перевірка lock-файлів сесій і очищення застарілих lock. -- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). -- Перевірки прав доступу до файлу конфігурації (chmod 600) під час локального запуску. -- Стан auth для моделей: перевіряє строк дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/disabled стани auth-профілів. -- Виявлення додаткового каталогу workspace (`~/openclaw`). -- Відновлення образу sandbox, якщо sandboxing увімкнено. +- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. +- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. +- Попередження про перевизначення постачальника OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. +- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). +- Міграція застарілих ключів контрактів маніфесту плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні webhook-завдання з `notify: true`). +- Перевірка файлів блокування сесій і очищення застарілих блокувань. +- Перевірки цілісності стану та прав доступу (сесії, транскрипти, каталог стану). +- Перевірки прав доступу до файла конфігурації (`chmod 600`) при локальному запуску. +- Справність автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для профілів автентифікації. +- Виявлення додаткового робочого каталогу (`~/openclaw`). +- Відновлення образу пісочниці, коли ізоляцію ввімкнено. - Міграція застарілих служб і виявлення додаткових gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). -- Перевірки runtime gateway (службу встановлено, але вона не працює; кешований label launchd). -- Попередження щодо стану каналів (перевіряються із запущеного gateway). +- Перевірки runtime gateway (службу встановлено, але вона не запущена; кешований launchd label). +- Попередження про стан каналів (перевіряються із запущеного gateway). - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. - Перевірки найкращих практик runtime gateway (Node проти Bun, шляхи version manager). - Діагностика конфліктів порту gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. -- Перевірки auth gateway для локального режиму token (пропонує генерацію token, якщо джерела token немає; не перезаписує конфігурації token SecretRef). -- Перевірка `systemd linger` у Linux. -- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до межі для контекстних файлів). -- Перевірка стану shell completion і автоматичне встановлення/оновлення. -- Перевірка готовності провайдера embeddings для memory search (локальна модель, віддалений API key або бінарний файл QMD). -- Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній бінарний файл tsx). -- Запис оновленої конфігурації + метаданих wizard. +- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, якщо джерела токена немає; не перезаписує конфігурації токена через SecretRef). +- Перевірка systemd linger у Linux. +- Перевірка розміру bootstrap-файлів робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). +- Перевірка стану shell completion та автоінсталяція/оновлення. +- Перевірка готовності постачальника embedding для memory search (локальна модель, віддалений API-ключ або бінарник QMD). +- Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарник tsx). +- Записує оновлену конфігурацію + метадані wizard. ## Докладна поведінка та обґрунтування ### 0) Необов’язкове оновлення (git-інсталяції) Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує -оновити (fetch/rebase/build) перед запуском doctor. +оновитися (fetch/rebase/build) перед запуском doctor. ### 1) Нормалізація конфігурації -Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction` +Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. -Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — +Це також включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` у мапу провайдерів. +`talk.apiKey` у мапу постачальників. ### 2) Міграції застарілих ключів конфігурації -Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися та просять -запустити `openclaw doctor`. +Коли конфігурація містить застарілі ключі, інші команди відмовляються працювати +й просять запустити `openclaw doctor`. Doctor: @@ -129,8 +128,9 @@ Doctor: - Перезапише `~/.openclaw/openclaw.json` оновленою схемою. Gateway також автоматично запускає міграції doctor під час старту, коли виявляє -застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. -Міграції сховища cron обробляються через `openclaw doctor --fix`. +застарілий формат конфігурації, тож застарілі конфігурації виправляються без +ручного втручання. +Міграції сховища cron завдань обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -154,249 +154,253 @@ Gateway також автоматично запускає міграції doct - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Для каналів з іменованими `accounts`, але зі збереженими однокористувацькими значеннями каналу на верхньому рівні, перенести ці значення, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) +- Для каналів з іменованими `accounts`, але зі збереженими верхньорівневими значеннями каналу для одиничного акаунта, перемістити ці значення, прив’язані до акаунта, у підвищений акаунт, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- видалити `browser.relayBindHost` (застаріле налаштування relay для розширення) +- видалення `browser.relayBindHost` (застаріле налаштування relay для розширення) -Попередження doctor також містять рекомендації щодо account-default для каналів із кількома обліковими записами: +Попередження doctor також включають рекомендації щодо акаунта за замовчуванням для багатокаунтних каналів: -- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис. -- Якщо `channels..defaultAccount` установлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. +- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт. +- Якщо `channels..defaultAccount` вказано на невідомий ID акаунта, doctor попереджає і перелічує налаштовані ID акаунтів. -### 2b) Перевизначення провайдера OpenCode +### 2b) Перевизначення постачальника OpenCode Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. -Це може примусово спрямовувати моделі до неправильного API або обнулювати вартість. Doctor попереджає, щоб ви могли прибрати це перевизначення й відновити маршрутизацію API + вартість для кожної моделі. +Через це моделі можуть використовувати неправильний API або мати нульову вартість. Doctor попереджає про це, щоб ви +могли прибрати перевизначення і відновити маршрутизацію API та вартість для кожної моделі. -### 2c) Міграція browser і готовність Chrome MCP +### 2c) Міграція браузера і готовність Chrome MCP -Якщо ваша конфігурація browser все ще вказує на вилучений шлях розширення Chrome, doctor -нормалізує її до поточної моделі локального під’єднання Chrome MCP на тому самому хості: +Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor +нормалізує її до поточної моделі підключення host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється -Doctor також виконує аудит локального шляху Chrome MCP на тому ж хості, коли ви використовуєте `defaultProfile: +Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - перевіряє, чи встановлено Google Chrome на тому самому хості для типових - профілів з auto-connect + профілів автопідключення - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 -- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, +- нагадує ввімкнути remote debugging на сторінці inspect у браузері (наприклад, + `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, або `edge://inspect/#remote-debugging`) -Doctor не може ввімкнути це налаштування на боці Chrome за вас. Локальний Chrome MCP -і надалі вимагає: +Doctor не може ввімкнути це налаштування у Chrome за вас. Host-local Chrome MCP +усе ще вимагає: - браузер на базі Chromium 144+ на хості gateway/node - локально запущений браузер - увімкнений remote debugging у цьому браузері -- схвалення першого запиту на attach у браузері +- підтвердження першого запиту згоди на підключення в браузері -Готовність тут стосується лише передумов для локального attach. Existing-session зберігає +Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, -перехоплення завантажень і пакетні дії, як і раніше потребують керованого -browser або сирого профілю CDP. +перехоплення завантажень і пакетні дії, як і раніше, потребують керованого +браузера або сирого профілю CDP. Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших -headless-сценаріїв. Вони, як і раніше, використовують сирий CDP. +безголових сценаріїв. Вони, як і раніше, використовують сирий CDP. -### 2d) Передумови TLS для OAuth +### 2d) TLS-передумови OAuth -Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє endpoint авторизації OpenAI, -щоб переконатися, що локальний стек TLS Node/OpenSSL може валідувати ланцюжок сертифікатів. Якщо -перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed сертифікат), -doctor виводить платформо-специфічні інструкції з виправлення. У macOS з Node із Homebrew -виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується, +Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації +OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може +перевірити ланцюжок сертифікатів. Якщо перевірка не проходить через помилку сертифіката (наприклад, +`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), +doctor виводить рекомендації щодо виправлення для конкретної платформи. У macOS із Node, встановленим через Homebrew, +виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть якщо gateway справний. -### 3) Міграції застарілого стану (структура на диску) +### 3) Міграції застарілого стану (розмітка на диску) -Doctor може мігрувати старіші структури на диску до поточної: +Doctor може мігрувати старіші розмітки на диску до поточної структури: -- Сховище сесій + transcripts: +- Сховище сесій + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` -- Agent dir: +- Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` -- Стан auth WhatsApp (Baileys): +- Стан автентифікації WhatsApp (Baileys): - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий ID акаунта: `default`) -Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor видає попередження, коли -залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрують -застарілі sessions + agent dir під час старту, тож history/auth/models потрапляють у -шлях для конкретного агента без ручного запуску doctor. Auth WhatsApp навмисно -мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер -порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють -повторних холостих змін `doctor --fix`. +Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо +залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує +застарілі сесії + каталог агента під час старту, тож історія/автентифікація/моделі потрапляють у +каталог для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно +мігрується лише через `openclaw doctor`. Нормалізація постачальника Talk/мапи постачальників тепер +порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють +повторних порожніх змін `doctor --fix`. -### 3a) Міграції застарілих manifest плагінів +### 3a) Міграції застарілих маніфестів плагінів -Doctor сканує всі встановлені manifest плагінів на наявність застарілих верхньорівневих -ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor сканує всі встановлені маніфести плагінів на наявність застарілих верхньорівневих ключів +можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, -`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` -і переписати файл manifest безпосередньо. Ця міграція є ідемпотентною; +`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об’єкт `contracts` +і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. ### 3b) Міграції застарілого сховища cron -Doctor також перевіряє сховище cron jobs (типово `~/.openclaw/cron/jobs.json`, -або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще -приймає для сумісності. +Doctor також перевіряє сховище cron завдань (`~/.openclaw/cron/jobs.json` типово, +або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник +досі приймає для сумісності. Поточні очищення cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` -- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` -- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` +- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` +- верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - псевдоніми delivery `provider` у payload → явний `delivery.channel` -- прості застарілі резервні webhook-завдання з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` +- прості застарілі резервні webhook-завдання з `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook` -Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це -без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним -режимом доставки, що не є webhook, doctor попереджає і залишає це завдання для ручної перевірки. +Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без +зміни поведінки. Якщо завдання поєднує застарілий резервний notify з уже наявним +не-webhook режимом delivery, doctor попереджає і залишає це завдання для ручної перевірки. -### 3c) Очищення session lock +### 3c) Очищення блокувань сесій -Doctor сканує каталог сесій кожного агента на наявність застарілих файлів lock запису — файлів, -які залишилися після аварійного завершення сесії. Для кожного знайденого lock-файлу він повідомляє: -шлях, PID, чи PID ще активний, вік lock і чи -вважається він застарілим (мертвий PID або старіший за 30 хвилин). У режимі `--fix` / `--repair` -він автоматично видаляє застарілі lock-файли; інакше друкує примітку та -інструктує повторно запустити з `--fix`. +Doctor сканує кожен каталог сесій агента на наявність застарілих write-lock файлів — файлів, що залишилися +після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: +шлях, PID, чи PID досі активний, вік блокування і чи +вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` +він видаляє застарілі файли блокування автоматично; інакше лише виводить примітку і +просить повторно запустити з `--fix`. -### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека) +### 4) Перевірки цілісності стану (збереження сесій, маршрутизація і безпека) -Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите -сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій деінде). +Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите +сесії, облікові дані, журнали і конфігурацію (якщо тільки у вас немає резервних копій деінде). Doctor перевіряє: -- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити +- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує заново створити каталог і нагадує, що не може відновити відсутні дані. -- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права - (і показує підказку `chown`, якщо виявлено невідповідність owner/group). -- **Каталог стану macOS із хмарною синхронізацією**: попереджає, коли стан розташовується в iCloud Drive +- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу + (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). +- **Каталог стану під хмарною синхронізацією macOS**: попереджає, коли стан знаходиться в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O - і конфлікти lock/sync. -- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовується на джерелі монтування `mmcblk*`, - оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису сесій і облікових даних. -- **Відсутні каталоги сесій**: `sessions/` і каталог сховища сесій - потрібні для збереження history і запобігання збоям `ENOENT`. -- **Невідповідність transcript**: попереджає, коли у нещодавніх записах сесій відсутні - файли transcript. -- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний transcript має лише один - рядок (history не накопичується). + і конфлікти блокувань/синхронізації. +- **Каталог стану на Linux на SD або eMMC**: попереджає, коли стан знаходиться на джерелі монтування `mmcblk*`, + оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій + під час запису сесій та облікових даних. +- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій + потрібні для збереження історії та уникнення збоїв `ENOENT`. +- **Невідповідність транскриптів**: попереджає, коли в останніх записах сесій відсутні + файли транскриптів. +- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний транскрипт має лише один + рядок (історія не накопичується). - **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних - home-каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може + домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). -- **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запустити +- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там). -- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` - доступний для читання групою/усіма, і пропонує обмежити права до `600`. +- **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є + доступним для читання групою/усіма, і пропонує обмежити до `600`. -### 5) Стан auth для моделей (строк дії OAuth) +### 5) Справність автентифікації моделей (строк дії OAuth) -Doctor перевіряє OAuth-профілі в сховищі auth, попереджає, коли токени -скоро спливають/вже спливли, і може оновити їх, коли це безпечно. Якщо OAuth/token-профіль -Anthropic застарів, він пропонує API-ключ Anthropic або застарілий +Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени +ось-ось закінчаться або вже прострочені, і може оновити їх, коли це безпечно. Якщо профіль +Anthropic OAuth/token застарів, він радить використати Anthropic API key або застарілий шлях setup-token Anthropic. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. -Doctor також виявляє застарілий вилучений стан Anthropic Claude CLI. Якщо старі +Doctor також виявляє застарілий видалений стан Anthropic Claude CLI. Якщо старі байти облікових даних `anthropic:claude-cli` все ще існують у `auth-profiles.json`, -doctor перетворює їх назад на токен-/OAuth-профілі Anthropic і переписує -застарілі посилання на моделі `claude-cli/...`. -Якщо байтів уже немає, doctor видаляє застарілу конфігурацію та виводить -команди для відновлення. +doctor перетворює їх назад на профілі Anthropic token/OAuth і переписує +застарілі посилання на моделі `claude-cli/...` та `agents.defaults.cliBackends.claude-cli`. +Якщо цих байтів уже немає, doctor видаляє застарілу конфігурацію і виводить команди для відновлення. -Doctor також повідомляє про auth-профілі, які тимчасово непридатні через: +Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: -- короткі cooldown (rate limit/timeouts/auth failures) -- довші вимкнення (помилки billing/credit) +- короткі cooldown (rate limit/timeout/auth failure) +- триваліші відключення (збій billing/credit) -### 6) Валідація моделі hooks +### 6) Перевірка моделі Hooks -Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель щодо -каталогу й allowlist та попереджає, коли воно не буде визначене або заборонене. +Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель щодо +каталогу та allowlist і попереджає, якщо воно не буде розв’язане або заборонене. ### 7) Відновлення образу sandbox -Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або -перейти на застарілі імена, якщо поточний образ відсутній. +Коли sandboxing увімкнено, doctor перевіряє Docker-образи і пропонує зібрати їх або +перейти на застарілі назви, якщо поточний образ відсутній. ### 7b) Runtime-залежності вбудованих плагінів -Doctor перевіряє, чи присутні runtime-залежності вбудованих плагінів (наприклад -runtime-пакунки плагіна Discord) у корені інсталяції OpenClaw. -Якщо чогось бракує, doctor повідомляє про пакунки й установлює їх у режимі +Doctor перевіряє, що runtime-залежності вбудованих плагінів (наприклад, +пакети runtime плагіна Discord) присутні в корені інсталяції OpenClaw. +Якщо чогось бракує, doctor повідомляє про пакети і встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. ### 8) Міграції служб gateway і підказки з очищення Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і -пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. -Він також може просканувати наявність додаткових gateway-подібних служб і показати підказки для очищення. -Іменовані служби gateway OpenClaw на основі профілів вважаються повноцінними й не позначаються як "extra". +пропонує видалити їх та встановити службу OpenClaw з поточним +портом gateway. Він також може сканувати додаткові gateway-подібні служби і виводити підказки щодо очищення. +Служби OpenClaw gateway, названі за профілем, вважаються повноцінними і не +позначаються як "додаткові". ### 8b) Стартова міграція Matrix -Коли обліковий запис каналу Matrix має очікувану або актуальну міграцію застарілого стану, -doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім +Коли обліковий запис каналу Matrix має відкладену або придатну до виконання міграцію застарілого стану, +doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім запускає кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а -startup продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка +старт продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. ### 9) Попередження безпеки -Doctor видає попередження, коли провайдер відкритий для DM без allowlist, або -коли політика налаштована небезпечним чином. +Doctor виводить попередження, коли постачальник відкритий для DM без allowlist +або коли політику налаштовано небезпечним чином. ### 10) systemd linger (Linux) -Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що lingering увімкнено, щоб +Якщо запуск відбувається як служба користувача systemd, doctor перевіряє, що linger увімкнено, щоб gateway залишався активним після виходу з системи. -### 11) Стан workspace (skills, плагіни та застарілі каталоги) +### 11) Стан робочого простору (Skills, плагіни і застарілі каталоги) -Doctor друкує підсумок стану workspace для типового агента: +Doctor виводить зведення стану робочого простору для типового агента: -- **Стан Skills**: кількість доступних, із відсутніми вимогами та заблокованих allowlist навичок. -- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace - існують поруч із поточним workspace. -- **Стан плагінів**: кількість завантажених/вимкнених/помилкових плагінів; перелічує ID плагінів для - будь-яких помилок; повідомляє про можливості bundle plugin. -- **Попередження про сумісність плагінів**: позначає плагіни, які мають проблеми сумісності з +- **Стан Skills**: підраховує доступні, з відсутніми вимогами та заблоковані allowlist Skills. +- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору + існують поруч із поточним робочим простором. +- **Стан плагінів**: підраховує завантажені/вимкнені/з помилками плагіни; перелічує ID плагінів для будь-яких + помилок; повідомляє про можливості bundle plugin. +- **Попередження сумісності плагінів**: позначає плагіни, які мають проблеми сумісності з поточним runtime. -- **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, видані - реєстром плагінів. +- **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, які були + видані реєстром плагінів. -### 11b) Розмір bootstrap-файлів +### 11b) Розмір bootstrap-файлу -Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, -`CLAUDE.md` або інші інʼєктовані контекстні файли) наближаються до -налаштованого символьного бюджету або перевищують його. Він показує для кожного файла кількість сирих та інʼєктованих символів, відсоток обрізання, -причину обрізання (`max/file` або `max/total`) і загальну кількість інʼєктованих -символів як частку загального бюджету. Коли файли обрізаються або наближаються до межі, -doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` +Doctor перевіряє, чи файли bootstrap робочого простору (наприклад, `AGENTS.md`, +`CLAUDE.md` або інші інжектовані контекстні файли) не наближаються або не перевищують налаштований +ліміт символів. Він повідомляє для кожного файла необроблену кількість символів порівняно з інжектованою, +відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість +інжектованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються +до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion -Doctor перевіряє, чи встановлено tab completion для поточної оболонки +Doctor перевіряє, чи встановлено автодоповнення для поточної оболонки (zsh, bash, fish або PowerShell): - Якщо профіль оболонки використовує повільний шаблон динамічного completion @@ -407,95 +411,97 @@ Doctor перевіряє, чи встановлено tab completion для п - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). -Виконайте `openclaw completion --write-state`, щоб вручну перегенерувати кеш. +Запустіть `openclaw completion --write-state`, щоб вручну перегенерувати кеш. -### 12) Перевірки auth gateway (локальний token) +### 12) Перевірки автентифікації gateway (локальний токен) -Doctor перевіряє готовність локальної auth gateway у режимі token. +Doctor перевіряє готовність автентифікації локального токена gateway. -- Якщо режим token потребує token і джерела token немає, doctor пропонує згенерувати його. -- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. -- `openclaw doctor --generate-gateway-token` примусово генерує token лише тоді, коли token SecretRef не налаштовано. +- Якщо режим токена потребує токена і джерела токена немає, doctor пропонує згенерувати його. +- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. +- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли токен SecretRef не налаштований. -### 12b) Виправлення лише для читання з урахуванням SecretRef +### 12b) Відновлення лише для читання з урахуванням SecretRef Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки runtime. -- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. -- Приклад: відновлення `@username` у `allowFrom` / `groupAllowFrom` Telegram намагається використовувати налаштовані облікові дані бота, коли вони доступні. -- Якщо token бота Telegram налаштований через SecretRef, але недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість збою або хибного повідомлення про відсутність token. +- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. +- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. +- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. -### 13) Перевірка стану gateway + перезапуск +### 13) Перевірка справності gateway + перезапуск -Doctor запускає перевірку стану і пропонує перезапустити gateway, якщо той -виглядає несправним. +Doctor виконує перевірку справності і пропонує перезапустити gateway, коли він виглядає +несправним. ### 13b) Готовність memory search -Doctor перевіряє, чи готовий налаштований провайдер embeddings для memory search -для типового агента. Поведінка залежить від налаштованого backend і провайдера: +Doctor перевіряє, чи готовий налаштований постачальник embedding для memory search +для типового агента. Поведінка залежить від налаштованого backend і provider: -- **Backend QMD**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`. - Якщо ні, виводить інструкції з виправлення, включно з npm-пакунком і ручним варіантом шляху до бінарного файла. -- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаваного - віддаленого/завантажуваного URL моделі. Якщо він відсутній, пропонує перейти на віддалений провайдер. -- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи - присутній API key у середовищі або сховищі auth. Якщо його немає, показує практичні підказки щодо виправлення. -- **Auto provider**: спочатку перевіряє доступність локальної моделі, а потім пробує кожен віддалений - провайдер у порядку автовибору. +- **QMD backend**: перевіряє, чи доступний і чи може запускатися бінарник `qmd`. + Якщо ні, виводить рекомендації щодо виправлення, зокрема npm-пакет і параметр ручного шляху до бінарника. +- **Явно вказаний локальний provider**: перевіряє наявність локального файла моделі або розпізнаного + URL віддаленої/завантажуваної моделі. Якщо нічого не знайдено, пропонує перейти на віддаленого provider. +- **Явно вказаний віддалений provider** (`openai`, `voyage` тощо): перевіряє, чи присутній API key + у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. +- **Auto provider**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого + provider у порядку автодобору. Коли доступний результат перевірки gateway (gateway був справний на момент -перевірки), doctor звіряє його з конфігурацією, видимою в CLI, і зазначає +перевірки), doctor зіставляє його з конфігурацією, видимою з CLI, і зазначає будь-які розбіжності. -Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embeddings у runtime. +Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime. -### 14) Попередження щодо стану каналів +### 14) Попередження про стан каналів -Якщо gateway справний, doctor виконує перевірку стану каналів і повідомляє -попередження разом із запропонованими виправленнями. +Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє +попередження з рекомендованими виправленнями. ### 15) Аудит конфігурації supervisor + відновлення -Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на -наявність відсутніх або застарілих типових значень (наприклад, залежності systemd від network-online та -затримки перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може -переписати service file/task відповідно до поточних типових значень. +Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність +відсутніх або застарілих типових значень (наприклад, залежностей systemd network-online і +затримки перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може +перезаписати файл служби/завдання відповідно до поточних типових значень. Примітки: -- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. +- `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor. - `openclaw doctor --yes` приймає типові запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. -- `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor. -- Якщо token auth потребує token і `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані відкриті значення token у метаданих середовища служби supervisor. -- Якщо token auth потребує token і налаштований token SecretRef не може бути розв’язаний, doctor блокує шлях install/repair і надає практичні інструкції. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує install/repair, доки режим не буде явно встановлено. -- Для Linux user-systemd units перевірки розбіжностей token у doctor тепер включають як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих auth служби. -- Ви завжди можете примусово переписати все через `openclaw gateway install --force`. +- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. +- Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення служби перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби supervisor. +- Якщо автентифікація токеном потребує токена, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні рекомендації. +- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим явно не буде встановлено. +- Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. +- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. -### 16) Runtime gateway + діагностика портів +### 16) Діагностика runtime gateway + порту -Doctor перевіряє runtime служби (PID, статус останнього завершення) і попереджає, коли -службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти -на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено, SSH tunnel). +Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли +службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти +на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже +запущений, SSH-тунель). ### 17) Найкращі практики runtime gateway -Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому version manager +Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому через version manager (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, -а шляхи version manager можуть ламатися після оновлень, оскільки служба не -завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, якщо +а шляхи через version manager можуть ламатися після оновлень, оскільки служба не +завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, коли вона доступна (Homebrew/apt/choco). ### 18) Запис конфігурації + метадані wizard -Doctor зберігає будь-які зміни конфігурації та ставить позначки в метаданих wizard, щоб зафіксувати запуск doctor. +Doctor зберігає всі зміни конфігурації і проставляє метадані wizard, щоб зафіксувати +запуск doctor. -### 19) Поради щодо workspace (резервне копіювання + система пам’яті) +### 19) Поради щодо робочого простору (резервні копії + система пам’яті) -Doctor пропонує систему пам’яті для workspace, якщо її немає, і друкує пораду про резервне копіювання, -якщо workspace ще не перебуває під git. +Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, +якщо робочий простір ще не перебуває під git. -Див. [/concepts/agent-workspace](/concepts/agent-workspace) для повного посібника зі -структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). +Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника щодо +структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index f8d2a571e..e038ab195 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Відповідь на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час роботи + - Відповідь на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання - Тріаж проблем, про які повідомляють користувачі, перед глибшим налагодженням -summary: Часті запитання про налаштування, конфігурацію та використання OpenClaw -title: ЧаПи +summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw +title: Поширені запитання x-i18n: - generated_at: "2026-04-06T00:38:53Z" + generated_at: "2026-04-06T12:48:08Z" model: gpt-5.4 provider: openai - source_hash: 4d6d09621c6033d580cbcf1ff46f81587d69404d6f64c8d8fd8c3f09185bb920 + source_hash: 391262b77c6c9b35253fd46b7d6fab324816c3cc25830f322f840fad0c9f58cf source_path: help/faq.md workflow: 15 --- -# ЧаПи +# Поширені запитання -Швидкі відповіді та глибше усунення проблем для реальних сценаріїв налаштування (локальна розробка, VPS, multi-agent, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час роботи див. [Усунення проблем](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, мультиагентність, OAuth/API-ключі, відмовостійкість моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурація](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося @@ -25,15 +25,15 @@ x-i18n: openclaw status ``` - Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, agents/sessions, конфігурація провайдера + проблеми під час роботи (коли gateway доступний). + Швидкий локальний зведений стан: ОС + оновлення, доступність gateway/служби, агенти/сеанси, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). -2. **Звіт, який можна вставити (безпечний для поширення)** +2. **Звіт, який можна вставити й поширити (безпечний для спільного доступу)** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом логів (токени приховані). + Діагностика лише для читання з хвостом журналу (токени приховано). 3. **Стан демона + порту** @@ -41,18 +41,18 @@ x-i18n: openclaw gateway status ``` - Показує runtime супервізора порівняно з доступністю RPC, URL цілі probe та яку конфігурацію сервіс, імовірно, використав. + Показує стан supervisor під час виконання порівняно з доступністю RPC, цільовий URL probe і яку конфігурацію, імовірно, використовувала служба. -4. **Глибокі probe-перевірки** +4. **Поглиблені probe-перевірки** ```bash openclaw status --deep ``` - Запускає live probe перевірки health gateway, включно з probe перевірками каналів, коли це підтримується + Виконує живу probe-перевірку працездатності gateway, включно з перевірками каналів, де це підтримується (потрібен доступний gateway). Див. [Стан](/uk/gateway/health). -5. **Переглянути останній лог у реальному часі** +5. **Перегляд останнього журналу в реальному часі** ```bash openclaw logs --follow @@ -64,56 +64,56 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові логи відокремлені від логів сервісу; див. [Логування](/uk/logging) та [Усунення проблем](/uk/gateway/troubleshooting). + Файлові журнали відокремлені від службових журналів; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). -6. **Запустити doctor (виправлення)** +6. **Запустіть doctor (виправлення)** ```bash openclaw doctor ``` - Виправляє/мігрує config/state + запускає перевірки health. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію та стан + запускає перевірки працездатності. Див. [Doctor](/uk/gateway/doctor). 7. **Знімок gateway** ```bash openclaw health --json - openclaw health --verbose # shows the target URL + config path on errors + openclaw health --verbose # показує цільовий URL + шлях до конфігурації у разі помилок ``` - Запитує у запущеного gateway повний знімок (лише WS). Див. [Стан](/uk/gateway/health). + Запитує в запущеного gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). -## Швидкий старт і перше налаштування +## Швидкий старт і початкове налаштування - - Використайте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати - в Discord, тому що більшість випадків "я застряг(ла)" — це **локальні проблеми конфігурації або середовища**, + + Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж запитувати + у Discord, тому що більшість випадків "я застряг" — це **локальні проблеми конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, виконувати команди, перевіряти логи й допомагати виправляти - налаштування на рівні машини (PATH, сервіси, дозволи, auth-файли). Надайте їм **повний checkout вихідного коду** через - hackable-встановлення (git): + Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали та допомагати виправляти + налаштування на рівні машини (PATH, служби, дозволи, файли автентифікації). Надайте їм **повну копію вихідного коду** + через hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **із git checkout**, тож агент може читати код + документацію і - міркувати про точну версію, яку ви запускаєте. Ви завжди можете повернутися до stable пізніше, + Це встановлює OpenClaw **з git checkout**, тому агент може читати код і документацію та + міркувати про точну версію, яку ви запускаєте. Пізніше ви завжди можете повернутися до стабільної версії, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть агента **спланувати й супроводжувати** виправлення (крок за кроком), а потім виконати лише - потрібні команди. Це зменшує масштаб змін і спрощує аудит. + Порада: попросіть агента **спланувати й проконтролювати** виправлення (крок за кроком), а потім виконати лише + потрібні команди. Так зміни залишаться невеликими, і їх буде легше перевірити. - Якщо ви знайдете реальний баг або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Почніть із цих команд (поділіться виводом, коли просите про допомогу): + Почніть із цих команд (діліться виводом, коли просите про допомогу): ```bash openclaw status @@ -123,15 +123,15 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок health gateway/agent + базової конфігурації. - - `openclaw models status`: перевіряє auth провайдера + доступність моделей. - - `openclaw doctor`: перевіряє та виправляє типові проблеми config/state. + - `openclaw status`: швидкий знімок стану gateway/агента + базової конфігурації. + - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє типові проблеми конфігурації/стану. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). - Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Документація з встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). @@ -139,122 +139,122 @@ x-i18n: Поширені причини пропуску heartbeat: - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній/заголовковий шаблон - - `no-tasks-due`: режим задач `HEARTBEAT.md` активний, але жоден із інтервалів задач ще не настав - - `alerts-disabled`: уся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/заголовкову заготовку + - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але жоден із інтервалів завдань ще не настав + - `alerts-disabled`: всю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі задач часові мітки due оновлюються лише після завершення - реального запуску heartbeat. Пропущені запуски не позначають задачі як виконані. + У режимі завдань часові позначки настання лише просуваються після завершення + реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. - Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та задачі](/uk/automation). + Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). - Репозиторій рекомендує запуск із вихідного коду та використання онбордингу: + У репозиторії рекомендується запускати з вихідного коду та використовувати онбординг: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати UI-ресурси. Після онбордингу ви зазвичай запускаєте Gateway на порту **18789**. + Майстер також може автоматично зібрати UI-ресурси. Після онбордингу зазвичай Gateway працює на порту **18789**. - Із вихідного коду (contributors/dev): + Із вихідного коду (для контриб'юторів/розробників): ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build - pnpm ui:build # auto-installs UI deps on first run + pnpm ui:build # автоматично встановлює залежності UI під час першого запуску openclaw onboard ``` - Якщо у вас ще немає глобального встановлення, запустіть через `pnpm openclaw onboard`. + Якщо у вас ще немає глобального встановлення, запускайте через `pnpm openclaw onboard`. - Майстер відкриває у вашому браузері чисту (без токенізованого URL) адресу dashboard одразу після онбордингу, а також друкує посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надрукований URL на тій самій машині. + Майстер відкриває браузер із чистим (без токена в URL) URL dashboard одразу після онбордингу, а також друкує посилання у зведенні. Залиште цю вкладку відкритою; якщо вона не відкрилася, скопіюйте/вставте надрукований URL на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитує auth через shared secret, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Якщо запитується автентифікація за shared secret, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо shared secret ще не налаштовано, згенеруйте токен через `openclaw doctor --generate-gateway-token`. + - Якщо shared secret ще не налаштовано, згенеруйте токен командою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, виконайте `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють auth для Control UI/WebSocket (без вставляння shared secret, за умови довіреного gateway host); HTTP API, як і раніше, вимагають auth через shared secret, якщо ви навмисно не використовуєте private-ingress `none` або auth HTTP через trusted-proxy. - Некоректні одночасні спроби auth від того самого клієнта через Serve серіалізуються до того, як limiter невдалої auth їх зафіксує, тому вже друга помилкова повторна спроба може показати `retry later`. - - **Bind tailnet**: виконайте `openclaw gateway --bind tailnet --token ""` (або налаштуйте auth через пароль), відкрийте `http://:18789/`, потім вставте відповідний shared secret у налаштування dashboard. - - **Identity-aware reverse proxy**: залиште Gateway за trusted proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL proxy. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` потім відкрийте `http://127.0.0.1:18789/`. Auth через shared secret і далі застосовується через tunnel; вставте налаштований токен або пароль, якщо буде запит. + - **Tailscale Serve** (рекомендовано): залиште loopback bind, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставляння shared secret, за умови довіреного gateway host); HTTP API все одно вимагають автентифікації shared secret, якщо ви навмисно не використовуєте private-ingress `none` або автентифікацію HTTP через trusted-proxy. + Некоректні одночасні спроби автентифікації Serve від того самого клієнта серіалізуються ще до того, як failed-auth limiter зафіксує їх, тому вже друга невдала повторна спроба може показувати `retry later`. + - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, потім вставте відповідний shared secret у налаштування dashboard. + - **Identity-aware reverse proxy**: залиште Gateway за trusted proxy не на loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. + - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація shared secret через tunnel усе одно застосовується; якщо буде запит, вставте налаштований токен або пароль. - Див. [Dashboard](/web/dashboard) і [Web surfaces](/web) для подробиць щодо режимів bind і auth. + Див. [Dashboard](/web/dashboard) і [Web-поверхні](/web) для режимів bind і деталей автентифікації. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на approval до призначень чату - - `channels..execApprovals`: робить цей канал нативним approval-клієнтом для exec-approval + - `approvals.exec`: пересилає запити на схвалення до чат-призначень + - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals - Політика host exec усе ще є реальною перепоною approval. Конфігурація чату лише керує тим, - де з’являються запити на approval і як люди можуть на них відповідати. + Політика exec на host усе одно залишається справжнім бар'єром схвалення. Конфігурація чату лише керує тим, + де з'являються запити на схвалення і як люди можуть на них відповідати. - У більшості налаштувань вам **не** потрібні обидві: + У більшості сценаріїв вам **не** потрібні обидві: - Якщо чат уже підтримує команди й відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначити approver-ів, OpenClaw тепер автоматично вмикає DM-first native approvals, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. - - Коли доступні нативні картки/кнопки approval, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що approvals у чаті недоступні або ручний approval — єдиний шлях. - - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати в інші чати або явні ops-room. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на approval публікувалися назад у вихідну кімнату/тему. - - approvals для plugins знову ж таки окремі: вони за замовчуванням використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають додаткову обробку plugin-approval-native. + - Якщо підтримуваний нативний канал може безпечно вивести схвалювачів, OpenClaw тепер автоматично вмикає native approvals із пріоритетом DM, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. + - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; агент повинен включати ручну команду `/approve` лише якщо результат інструмента каже, що чат-схвалення недоступні або ручне схвалення — єдиний шлях. + - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати до інших чатів або окремих операційних кімнат. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише якщо ви явно хочете, щоб запити на схвалення публікувалися назад у вихідну кімнату/тему. + - Схвалення plugins — це окрема категорія: вони за замовчуванням використовують `/approve` у тому самому чаті, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-approval. - Коротко: пересилання — це про маршрутизацію, конфігурація нативного клієнта — про багатший UX, специфічний для каналу. + Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендовано** для Gateway. + + Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun для Gateway **не рекомендується**. - Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 ядра** і близько **500MB** - диска, і зазначено, що **Raspberry Pi 4 може це запускати**. + Так. Gateway легковаговий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 ядра** і приблизно **500MB** + диска, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (логи, медіа, інші сервіси), **рекомендовано 2GB**, але це + Якщо вам потрібен додатковий запас (журнали, медіа, інші служби), **рекомендується 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може хостити Gateway, а ви можете підключати **nodes** на ноутбуці/телефоні для - локального screen/camera/canvas або виконання команд. Див. [Nodes](/uk/nodes). + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете підключати **nodes** на ноутбуці/телефоні для + локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - - Коротко: працює, але очікуйте шерехів. + + Коротко: це працює, але очікуйте шорстких кутів. - - Використовуйте **64-bit** ОС і Node >= 22. - - Надавайте перевагу **hackable (git) install**, щоб бачити логи й швидко оновлюватися. - - Почніть без channels/Skills, потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з бінарниками, це зазвичай проблема **ARM-сумісності**. + - Використовуйте **64-бітну** ОС і Node >= 22. + - Віддавайте перевагу **hackable (git) install**, щоб бачити журнали та швидко оновлюватися. + - Починайте без channels/skills, а потім додавайте їх по одному. + - Якщо натрапляєте на дивні проблеми з бінарниками, зазвичай це проблема **сумісності ARM**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від доступності й автентифікації Gateway. TUI також автоматично надсилає - "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** - і токени лишаються 0, агент так і не запустився. + + Цей екран залежить від доступності та автентифікації Gateway. TUI також надсилає + "Wake up, my friend!" автоматично під час першого вилуплення. Якщо ви бачите цей рядок **без відповіді** + і токени залишаються на 0, агент так і не запустився. 1. Перезапустіть Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. Перевірте статус + auth: + 2. Перевірте статус + автентифікацію: ```bash openclaw status @@ -276,29 +276,29 @@ x-i18n: openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з’єднання активне і що UI - спрямовано на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). + Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з'єднання активне і що UI + вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - - Так. Скопіюйте **каталог state** і **workspace**, потім один раз запустіть Doctor. Це - збереже вашого бота "точно таким самим" (memory, history сесій, auth і channel - state), якщо ви скопіюєте **обидва** місця: + + Так. Скопіюйте **каталог стану** та **workspace**, а потім один раз запустіть Doctor. Це + збереже вашого бота **точно таким самим** (пам'ять, історія сеансів, автентифікація та + стан каналів), якщо ви скопіюєте **обидва** розташування: - 1. Встановіть OpenClaw на нову машину. + 1. Установіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). - 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. + 4. Запустіть `openclaw doctor` і перезапустіть службу Gateway. - Це збереже config, auth-профілі, облікові дані WhatsApp, sessions і memory. Якщо ви в - remote mode, пам’ятайте, що саме gateway host володіє сховищем сесій і workspace. + Це збереже конфігурацію, профілі автентифікації, облікові дані WhatsApp, сеанси й пам'ять. Якщо ви в + remote mode, пам'ятайте, що store сеансів і workspace належать gateway host. - **Важливо:** якщо ви лише commit/push ваш workspace на GitHub, ви резервуєте - **memory + bootstrap-файли**, але **не** history сесій і не auth. Вони живуть + **Важливо:** якщо ви лише commit/push свій workspace у GitHub, ви створюєте резервну копію + **пам'яті + bootstrap-файлів**, але **не** історії сеансів чи автентифікації. Вони живуть у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де що лежить на диску](#де-що-лежить-на-диску), + Пов'язане: [Міграція](/uk/install/migrating), [Де що лежить на диску](#де-що-лежить-на-диску), [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), [Віддалений режим](/uk/gateway/remote). @@ -308,15 +308,15 @@ x-i18n: Перевірте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи зверху. Якщо верхню секцію позначено як **Unreleased**, наступна датована - секція — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** та - **Fixes** (а також docs/іншими секціями за потреби). + Найновіші записи — вгорі. Якщо верхній розділ позначено як **Unreleased**, то наступний датований + розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і + **Fixes** (а також розділами документації/іншими, за потреби). - - Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity - Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. + + Деякі підключення Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity + Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім спробуйте ще раз. Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: @@ -330,21 +330,21 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний - крок просування переносить цю саму версію в `latest`. Maintainers також можуть - за потреби публікувати відразу в `latest`. Саме тому beta і stable можуть + Зазвичай stable-реліз спочатку з'являється в **beta**, а потім окремий + крок просування переміщує цю ж версію в `latest`. За потреби супроводжувачі також можуть + публікувати одразу в `latest`. Саме тому beta і stable можуть вказувати на **ту саму версію** після просування. - Подивитися, що змінилося: + Дивіться, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Однорядкові команди для встановлення і різницю між beta та dev дивіться в акордеоні нижче. + Для однорядкових команд встановлення та різниці між beta і dev дивіться accordion нижче. - - **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). - **Dev** — це рухома голова `main` (git); коли її публікують, вона використовує npm dist-tag `dev`. + + **Beta** — це npm dist-tag `beta` (після просування може збігатися з `latest`). + **Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -356,7 +356,7 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Windows installer (PowerShell): + Інсталятор для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). @@ -380,9 +380,9 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це дає вам локальний repo, який можна редагувати, а потім оновлювати через git. + Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому clone вручну, використайте: + Якщо ви віддаєте перевагу чистому ручному clone, використайте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -396,31 +396,31 @@ x-i18n: - + Орієнтовно: - **Встановлення:** 2-5 хвилин - - **Onboarding:** 5-15 хвилин залежно від кількості channels/models, які ви налаштовуєте + - **Онбординг:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте - Якщо все зависло, скористайтеся [Застряг інсталятор](#швидкий-старт-і-перше-налаштування) - і швидким циклом налагодження в [Я застряг(ла)](#швидкий-старт-і-перше-налаштування). + Якщо щось зависає, скористайтеся [Застряг інсталятор](#швидкий-старт-і-початкове-налаштування) + і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). - + Повторно запустіть інсталятор із **докладним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Beta-встановлення з verbose: + Встановлення beta з докладним виводом: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для hackable-встановлення (git): + Для hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -429,47 +429,47 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 has no dedicated -Verbose flag yet. + # install.ps1 ще не має окремого прапорця -Verbose. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - Більше варіантів: [Прапорці інсталятора](/uk/install/installer). + Більше параметрів: [Прапорці інсталятора](/uk/install/installer). - Дві поширені проблеми у Windows: + Дві поширені проблеми на Windows: **1) npm error spawn git / git not found** - - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - - Закрийте й знову відкрийте PowerShell, потім повторно запустіть інсталятор. + - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. + - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. - **2) openclaw is not recognized after install** + **2) openclaw is not recognized після встановлення** - - Ваша глобальна тека bin npm не додана до PATH. + - Ваша глобальна папка bin npm не входить до PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - - Закрийте й знову відкрийте PowerShell після оновлення PATH. + - Додайте цей каталог до вашого user PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Після оновлення PATH закрийте й знову відкрийте PowerShell. - Якщо ви хочете найгладше налаштування у Windows, використовуйте **WSL2**, а не нативну Windows. + Якщо вам потрібне найгладше налаштування на Windows, використовуйте **WSL2**, а не нативний Windows. Документація: [Windows](/uk/platforms/windows). - - Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. + + Зазвичай це невідповідність code page консолі в нативних оболонках Windows. Симптоми: - - Вивід `system.run`/`exec` відображає китайський текст як mojibake + - Вивід `system.run`/`exec` показує китайські символи як mojibake - Та сама команда виглядає нормально в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -487,15 +487,15 @@ x-i18n: openclaw gateway restart ``` - Якщо на останній версії OpenClaw проблема все ще відтворюється, відстежуйте/повідомляйте тут: + Якщо це все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **hackable (git) install**, щоб мати повні локальні вихідні коди й документацію, а потім запитайте - свого бота (або Claude/Codex) _з цієї теки_, щоб він міг читати repo і відповісти точно. + Використайте **hackable (git) install**, щоб мати повний вихідний код і документацію локально, а потім запитайте + вашого бота (або Claude/Codex) _з цієї папки_, щоб він міг читати репозиторій і відповідати точно. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -505,37 +505,37 @@ x-i18n: - - Коротка відповідь: дотримуйтеся інструкції для Linux, потім запустіть onboarding. + + Коротка відповідь: дотримуйтесь інструкції для Linux, а потім запустіть онбординг. - - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). + - Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - Інсталятор + оновлення: [Встановлення та оновлення](/uk/install/updating). - - Підійде будь-який Linux VPS. Встановіть на сервері, потім використовуйте SSH/Tailscale для доступу до Gateway. + + Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингів** із поширеними провайдерами. Оберіть один і дотримуйтеся інструкції: + + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть одного й дотримуйтесь інструкції: - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте доступ до нього - з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace - живуть на сервері, тож сприймайте host як джерело істини й робіть резервні копії. + Як це працює в хмарі: **Gateway працює на сервері**, а ви звертаєтеся до нього + з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + workspace + живуть на сервері, тому сприймайте host як джерело істини й робіть його резервні копії. Ви можете підключати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ до - локальних screen/camera/canvas або виконувати команди на ноутбуці, залишаючи + локального екрана/камери/canvas або запускати команди на своєму ноутбуці, зберігаючи Gateway у хмарі. Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). @@ -543,10 +543,10 @@ x-i18n: - - Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити - Gateway (що розірве активну сесію), може вимагати чистого git checkout і - може запитати підтвердження. Безпечніше: запускати оновлення з оболонки як оператор. + + Коротка відповідь: **можливо, але не рекомендується**. Процес оновлення може перезапустити + Gateway (що скине активний сеанс), може вимагати чистого git checkout і + може запитати підтвердження. Безпечніше запускати оновлення з оболонки від імені оператора. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вже треба автоматизувати з агента: + Якщо вам усе ж потрібно автоматизувати це з агента: ```bash openclaw update --yes --no-restart @@ -569,40 +569,40 @@ x-i18n: - - `openclaw onboard` — рекомендований шлях налаштування. У **local mode** він проводить вас через: + + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування model/auth** (OAuth провайдера, API-ключі, legacy setup-token Anthropic, а також варіанти локальних моделей, такі як LM Studio) + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, legacy setup-token Anthropic, а також локальні варіанти моделей, як-от LM Studio) - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) - - **Встановлення daemon** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) - - **Перевірки health** і вибір **Skills** + - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) + - **Встановлення демона** (LaunchAgent на macOS; user unit systemd на Linux/WSL2) + - **Перевірки працездатності** і вибір **Skills** - Він також попереджає, якщо налаштована модель невідома або для неї бракує auth. + Він також попереджає, якщо налаштована модель невідома або для неї бракує автентифікації. - + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з - **лише локальними моделями**, щоб ваші дані лишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. + **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude + Pro/Max або OpenAI Codex) — це необов'язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **Anthropic API key**: звичайна тарифікація Anthropic API - - **Claude subscription auth in OpenClaw**: Anthropic повідомила користувачам OpenClaw - **4 квітня 2026 о 12:00 PT / 20:00 BST**, що для цього потрібне - **Extra Usage**, яке виставляється окремо від підписки + - **API-ключ Anthropic**: звичайний білінг Anthropic API + - **Автентифікація підпискою Claude в OpenClaw**: Anthropic повідомила користувачам OpenClaw + **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що для цього потрібне + **Extra Usage**, яке оплачується окремо від підписки Наші локальні відтворення також показують, що `claude -p --append-system-prompt ...` може натрапляти на той самий захист Extra Usage, коли доданий prompt ідентифікує OpenClaw, тоді як той самий рядок prompt **не** відтворює це блокування на - шляху Anthropic SDK + API-key. OpenAI Codex OAuth офіційно + шляху Anthropic SDK + API key. OpenAI Codex OAuth явно підтримується для зовнішніх інструментів, таких як OpenClaw. - OpenClaw також підтримує інші hosted-варіанти з підписочною моделлю, включно з - **Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, і + OpenClaw також підтримує інші хостингові варіанти з підписною моделлю, зокрема + **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), @@ -613,31 +613,31 @@ x-i18n: - Так, але сприймайте це як **Claude subscription auth with Extra Usage**. + Так, але сприймайте це як **автентифікацію підпискою Claude з Extra Usage**. - Підписки Claude Pro/Max не включають API-ключ. В OpenClaw це - означає, що застосовується специфічне для OpenClaw повідомлення Anthropic про тарифікацію: - трафік за підпискою потребує **Extra Usage**. Якщо ви хочете трафік Anthropic без - цього шляху Extra Usage, натомість використовуйте API-ключ Anthropic. + Підписки Claude Pro/Max не включають API-ключ. У контексті OpenClaw це + означає, що застосовується спеціальне повідомлення Anthropic про білінг для OpenClaw: трафік + за підпискою вимагає **Extra Usage**. Якщо ви хочете трафік Anthropic без + цього шляху Extra Usage, використовуйте замість цього API-ключ Anthropic. - - Так, але тепер підтримуване трактування таке: + + Так, але підтримуване трактування тепер таке: - Anthropic в OpenClaw із підпискою означає **Extra Usage** - Anthropic в OpenClaw без цього шляху означає **API key** - Setup-token Anthropic усе ще доступний як legacy/manual-шлях OpenClaw, - і специфічне для OpenClaw повідомлення Anthropic про тарифікацію тут також діє. Ми - також локально відтворили той самий захист тарифікації за прямого використання + Anthropic setup-token і далі доступний як legacy/manual шлях OpenClaw, + і спеціальне повідомлення Anthropic про білінг для OpenClaw усе ще діє для нього. Ми + також локально відтворили той самий білінговий захист при прямому використанні `claude -p --append-system-prompt ...`, коли доданий prompt - ідентифікує OpenClaw, тоді як той самий рядок prompt **не** відтворився на - шляху Anthropic SDK + API-key. + ідентифікує OpenClaw, тоді як той самий рядок prompt **не** відтворювався на + шляху Anthropic SDK + API key. - Для production або multi-user-навантажень auth через API-ключ Anthropic — - безпечніший і рекомендований вибір. Якщо вам потрібні інші hosted-варіанти - з підписочною моделлю в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Для production або багатокористувацьких навантажень автентифікація API key Anthropic — + безпечніший і рекомендований вибір. Якщо ви хочете інші хостингові + варіанти з підписною моделлю в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM Models](/uk/providers/glm). @@ -645,115 +645,122 @@ x-i18n: -Це означає, що вашу **квоту/ліміт швидкості Anthropic** вичерпано для поточного вікна. Якщо ви -використовуєте **Claude CLI**, дочекайтеся скидання вікна або підвищте свій тариф. Якщо ви -використовуєте **Anthropic API key**, перевірте Anthropic Console -на використання/тарифікацію та за потреби підвищте ліміти. +Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви +використовуєте **Claude CLI**, зачекайте, поки вікно скинеться, або підвищте тариф. Якщо ви +використовуєте **API key Anthropic**, перевірте Anthropic Console +на предмет використання/білінгу і за потреби підвищте ліміти. Якщо повідомлення конкретно таке: - `Extra usage is required for long context requests`, запит намагається використовувати - beta 1M context Anthropic (`context1m: true`). Це працює лише коли ваш - credential має право на long-context billing (тарифікація через API-ключ або - шлях OpenClaw Claude-login з увімкненим Extra Usage). + `Extra usage is required for long context requests`, то запит намагається використати + бета-функцію Anthropic із контекстом 1M (`context1m: true`). Це працює лише тоді, коли ваш + обліковий запис має право на білінг довгого контексту (білінг API key або + шлях входу в Claude через OpenClaw з увімкненим Extra Usage). - Порада: налаштуйте **fallback model**, щоб OpenClaw міг продовжувати відповідати, коли провайдер упирається в rate limit. + Порада: установіть **fallback model**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений за rate limit. Див. [Моделі](/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має bundled-провайдера **Amazon Bedrock (Converse)**. Якщо присутні AWS env-маркери, OpenClaw може автоматично виявити streaming/text-каталог Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати ручний запис провайдера. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock також є коректним варіантом. + Так. OpenClaw має bundled-провайдер **Amazon Bedrock (Converse)**. Якщо присутні AWS env markers, OpenClaw може автоматично виявляти каталог потокових/текстових моделей Bedrock і об'єднувати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати ручний запис провайдера. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо вам зручніше керований шлях із ключем, OpenAI-сумісний проксі перед Bedrock також лишається коректним варіантом. - - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Onboarding може провести OAuth-flow і встановить модель за замовчуванням `openai-codex/gpt-5.4`, коли це доречно. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). + + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Під час онбордингу можна пройти OAuth-процес, і за потреби буде встановлено модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - - Так. OpenClaw повністю підтримує **subscription OAuth OpenAI Code (Codex)**. - OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/робочих процесах, - як-от OpenClaw. Onboarding може провести OAuth-flow за вас. + + Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. + OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/процесах + на кшталт OpenClaw. Онбординг може провести OAuth-процес за вас. - Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - Gemini CLI використовує **plugin auth flow**, а не client id або secret у `openclaw.json`. + Gemini CLI використовує **plugin auth flow**, а не client id чи secret у `openclaw.json`. - Натомість використовуйте провайдера Gemini API: + Кроки: - 1. Увімкніть plugin: `openclaw plugins enable google` - 2. Запустіть `openclaw onboard --auth-choice gemini-api-key` - 3. Встановіть модель Google, наприклад `google/gemini-3.1-pro-preview` + 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` + - Homebrew: `brew install gemini-cli` + - npm: `npm install -g @google/gemini-cli` + 2. Увімкніть plugin: `openclaw plugins enable google` + 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` + 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3.1-pro-preview` + 5. Якщо запити не проходять, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host + + Це зберігає OAuth-токени в auth profiles на gateway host. Деталі: [Провайдери моделей](/uk/concepts/model-providers). - Зазвичай ні. OpenClaw потребує великого context + сильного безпекового профілю; малі картки обрізаються й протікають. Якщо вже дуже треба, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані моделі збільшують ризик prompt injection — див. [Безпека](/uk/gateway/security). + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; невеликі карти обрізають контекст і допускають витоки. Якщо вже потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і дивіться [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Обирайте endpoint-и з прив’язкою до регіону. OpenRouter надає розміщені в США варіанти для MiniMax, Kimi і GLM; оберіть варіант, розміщений у США, щоб зберегти дані в регіоні. Ви все одно можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб fallbacks лишалися доступними, водночас поважаючи обраного вами регіонального провайдера. + + Вибирайте endpoint-и, прив'язані до регіону. OpenRouter пропонує US-hosted варіанти для MiniMax, Kimi і GLM; виберіть US-hosted варіант, щоб зберегти дані в межах регіону. Ви все одно можете перелічувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб fallback-и залишалися доступними, водночас поважаючи вибраного регіонального провайдера. - - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий; - дехто купує його як хост, що працює постійно, але підійде й невеликий VPS, домашній сервер або box рівня Raspberry Pi. + + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini не обов'язковий — деякі люди + купують його як завжди увімкнений host, але підійде й невеликий VPS, домашній сервер або коробка рівня Raspberry Pi. - Mac потрібен лише для **інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші macOS-only tools, запускайте Gateway на Mac або підключайте macOS node. + Mac потрібен лише **для інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — + сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключайте node macOS. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Вам потрібен **якийсь пристрій macOS**, увійдений у Messages. Це **не обов’язково** Mac mini — - підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, а Gateway може працювати на Linux або деінде. + + Вам потрібен **якийсь пристрій macOS**, увійшовший у Messages. Це **не обов'язково** має бути Mac mini — + підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. - Типові варіанти: + Поширені сценарії: - - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, увійденому в Messages. - - Запускайте все на Mac, якщо хочете найпростішу одно-машинну конфігурацію. + - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, увійшовшому в Messages. + - Запускайте все на Mac, якщо хочете найпростіше однокомп'ютерне налаштування. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключитися як - **node** (companion device). Nodes не запускають Gateway — вони надають додаткові + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як + **node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. - Типова схема: + Поширений шаблон: - Gateway на Mac mini (завжди увімкнений). - - MacBook Pro запускає macOS-app або node host і з’єднується з Gateway. - - Для перегляду використовуйте `openclaw nodes status` / `openclaw nodes list`. + - MacBook Pro запускає застосунок macOS або node host і підключається до Gateway. + - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - - Bun **не рекомендовано**. Ми бачимо баги під час роботи, особливо з WhatsApp і Telegram. - Для stable gateway використовуйте **Node**. + + Bun **не рекомендується**. Ми бачимо помилки під час виконання, особливо з WhatsApp і Telegram. + Використовуйте **Node** для стабільних gateway. - Якщо ви все ж хочете експериментувати з Bun, робіть це на non-production gateway + Якщо ви все ж хочете експериментувати з Bun, робіть це на непродукційному gateway без WhatsApp/Telegram. - - `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не username бота. + + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім'я користувача бота. - Onboarding приймає ввід `@username` і перетворює його на числовий ID, але авторизація OpenClaw використовує лише числові ID. + Під час онбордингу можна ввести `@username`, і він буде перетворений на числовий ID, але авторизація OpenClaw використовує лише числові ID. Безпечніше (без стороннього бота): - - Напишіть боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть боту в DM, потім запустіть `openclaw logs --follow` і подивіться `from.id`. Офіційний Bot API: @@ -761,18 +768,18 @@ x-i18n: Сторонній варіант (менш приватний): - - Напишіть у DM `@userinfobot` або `@getidsbot`. + - Напишіть `@userinfobot` або `@getidsbot`. Див. [/channels/telegram](/uk/channels/telegram#access-control-and-activation). - - Так, через **multi-agent routing**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника, як-от `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть із **того самого облікового запису WhatsApp**, а контроль доступу для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для цього облікового запису WhatsApp. Див. [Multi-Agent Routing](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **маршрутизацію мультиагентів**. Прив'яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і store сеансів. Відповіді все одно надходитимуть від **того самого облікового запису WhatsApp**, а контроль доступу для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація мультиагентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте multi-agent routing: дайте кожному agent його власну модель за замовчуванням, а потім прив’яжіть вхідні routes (обліковий запис провайдера або конкретних peers) до кожного agent. Приклад конфігурації наведено в [Multi-Agent Routing](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію мультиагентів: задайте кожному агенту власну модель за замовчуванням, а потім прив'яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації є в [Маршрутизація мультиагентів](/uk/concepts/multi-agent). Також див. [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -785,24 +792,24 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу включає `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в non-login оболонках. - Останні збірки також додають попереду поширені user bin-каталоги в Linux systemd-сервісах (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо їх задано. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, знаходилися в non-login оболонках. + Останні збірки також додають поширені user bin-каталоги в Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. - - **Hackable (git) install:** повний checkout вихідного коду, редагований, найкраще для contributors. - Ви локально виконуєте збирання і можете патчити код/документацію. - - **npm install:** глобальне встановлення CLI без repo, найкраще для сценарію "просто запустити". - Оновлення приходять із npm dist-tags. + - **Hackable (git) install:** повний checkout вихідного коду, редагований, найкращий для контриб'юторів. + Ви локально запускаєте збірки й можете виправляти код/документацію. + - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію "просто запустити". + Оновлення надходять із npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - - Так. Встановіть інший варіант, потім запустіть Doctor, щоб сервіс gateway вказував на новий entrypoint. - Це **не видаляє ваші дані** — воно лише змінює встановлення коду OpenClaw. Ваш state + + Так. Установіть інший варіант, а потім запустіть Doctor, щоб служба gateway вказувала на нову entrypoint. + Це **не видаляє ваші дані** — змінюється лише інсталяція коду OpenClaw. Ваш стан (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. Із npm на git: @@ -824,66 +831,66 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (в automation використовуйте `--repair`). + Doctor виявляє невідповідність entrypoint служби gateway і пропонує переписати конфігурацію служби відповідно до поточного встановлення (у автоматизації використовуйте `--repair`). - Поради щодо резервних копій: див. [Стратегія резервного копіювання](#де-що-лежить-на-диску). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-лежить-на-диску). - - Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібне - найменше тертя й вас влаштовують сон/перезапуски, запускайте локально. + + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо ви хочете + мінімум тертя й вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Плюси:** без вартості сервера, прямий доступ до локальних файлів, видиме вікно браузера. - - **Мінуси:** сон/обриви мережі = розриви з’єднання, оновлення/перезавантаження ОС переривають роботу, машину треба тримати активною. + - **Плюси:** безкоштовний сервер, прямий доступ до локальних файлів, видиме вікно браузера. + - **Мінуси:** сон/обриви мережі = розриви з'єднання, оновлення ОС/перезавантаження переривають роботу, машина має залишатися активною. **VPS / хмара** - - **Плюси:** завжди ввімкнено, стабільна мережа, немає проблем через сон ноутбука, легше підтримувати постійну роботу. - - **Мінуси:** часто headless-режим (використовуйте скриншоти), доступ до файлів лише віддалено, для оновлень потрібен SSH. + - **Плюси:** завжди увімкнено, стабільна мережа, немає проблем зі сном ноутбука, простіше підтримувати в роботі. + - **Мінуси:** часто працює без голови (використовуйте знімки екрана), доступ до файлів лише віддалений, для оновлень потрібен SSH. - **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord усі добре працюють із VPS. Єдиний реальний компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). + **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний реальний компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). - **Рекомендовано за замовчуванням:** VPS, якщо у вас уже були розриви gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете доступ до локальних файлів або UI-автоматизацію з видимим браузером. + **Рекомендований варіант за замовчуванням:** VPS, якщо у вас уже були розриви gateway. Локальний варіант чудовий, коли ви активно користуєтеся Mac і хочете доступ до локальних файлів або UI-автоматизацію з видимим браузером. - Не обов’язково, але **рекомендовано для надійності та ізоляції**. + Це не обов'язково, але **рекомендується для надійності та ізоляції**. - - **Окремий host (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу. - - **Спільний ноутбук/desktop:** цілком підходить для тестування та активного використання, але очікуйте пауз, коли машина засинає або оновлюється. + - **Виділений host (VPS/Mac mini/Pi):** завжди увімкнений, менше перебоїв через сон/перезавантаження, чистіші дозволи, легше підтримувати в роботі. + - **Спільний ноутбук/ПК:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. - Якщо ви хочете поєднати найкраще з обох світів, тримайте Gateway на окремому host і підключайте ноутбук як **node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). - Поради з безпеки див. у [Безпека](/uk/gateway/security). + Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному host і підключайте ноутбук як **node** для локальних screen/camera/exec інструментів. Див. [Nodes](/uk/nodes). + Для рекомендацій із безпеки прочитайте [Безпека](/uk/gateway/security). - OpenClaw легкий. Для базового Gateway + одного chat-каналу: + OpenClaw легковаговий. Для базового Gateway + одного чат-каналу: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (логи, медіа, кілька каналів). Node tools і browser automation можуть потребувати багато ресурсів. + - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше із запасом (журнали, медіа, кілька каналів). Інструменти node і автоматизація браузера можуть бути ресурсомісткими. - ОС: використовуйте **Ubuntu LTS** (або будь-яку сучасну Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях установлення на Linux там протестовано найкраще. Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - - Так. Ставтеся до VM так само, як до VPS: вона має бути постійно увімкнена, доступна і мати достатньо + + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди увімкненою, доступною й мати достатньо RAM для Gateway та будь-яких увімкнених каналів. - Базові орієнтири: + Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, browser automation або media tools. - - **ОС:** Ubuntu LTS або інша сучасна Debian/Ubuntu. + - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіаінструменти. + - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. - Якщо ви на Windows, **WSL2 — найпростіший стиль налаштування VM** і має найкращу + Якщо ви на Windows, **WSL2 — найпростіший варіант у стилі VM** і має найкращу сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -894,80 +901,80 @@ x-i18n: - OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і bundled channel plugins, такі як QQ Bot), а також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це постійно увімкнена control plane; помічник і є продуктом. + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на тих платформах обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, такі як QQ Bot) і також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнена control plane; сам помічник і є продуктом. - OpenClaw — це не "просто обгортка для Claude". Це **local-first control plane**, яка дозволяє вам запускати - потужного помічника на **власному обладнанні**, доступного з chat-застосунків, якими ви вже користуєтесь, зі - stateful sessions, memory та tools — без передачі контролю над вашими workflow хостинговому + OpenClaw — це не "просто обгортка для Claude". Це **локальна control plane**, яка дає змогу запускати + потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі + станними сеансами, пам'яттю та інструментами — без передавання контролю над вашими процесами хостинговому SaaS. Основні переваги: - - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і тримайте - workspace + history сесій локально. - - **Реальні канали, а не web-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, - а також mobile voice і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією - та failover на рівні agent. - - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли лишатися на вашому пристрої**, якщо бажаєте. - - **Multi-agent routing:** окремі agents за каналом, обліковим записом або задачею, кожен із власним - workspace і параметрами за замовчуванням. - - **Відкритий код і hackable:** перевіряйте, розширюйте й self-host без vendor lock-in. + - **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте + workspace + історію сеансів локально. + - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + плюс мобільний голос і Canvas на підтримуваних платформах. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією + і failover на рівні агента. + - **Варіант лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. + - **Маршрутизація мультиагентів:** окремі агенти для каналу, облікового запису або завдання, кожен зі своїм + workspace та значеннями за замовчуванням. + - **Відкритий код і можливість модифікації:** перевіряйте, розширюйте й самостійно розміщуйте без vendor lock-in. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), - [Пам’ять](/uk/concepts/memory). + Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Мультиагентність](/uk/concepts/multi-agent), + [Пам'ять](/uk/concepts/memory). - + Хороші перші проєкти: - Створити вебсайт (WordPress, Shopify або простий статичний сайт). - Прототипувати мобільний застосунок (структура, екрани, план API). - - Упорядкувати файли й теки (очищення, найменування, теги). - - Підключити Gmail і автоматизувати зведення чи follow-up. + - Організувати файли та папки (очищення, іменування, теги). + - Підключити Gmail і автоматизувати підсумки чи follow-ups. - Він може впоратися з великими задачами, але найкраще працює, коли ви ділите їх на фази й + Він може працювати з великими завданнями, але найкраще працює, коли ви ділите їх на фази й використовуєте sub agents для паралельної роботи. - - Повсякденні виграші зазвичай виглядають так: + + Повсякденні переваги зазвичай виглядають так: - - **Персональні зведення:** підсумки inbox, календаря й важливих для вас новин. - - **Дослідження й чернетки:** швидкий ресерч, зведення та перші чернетки листів або документів. - - **Нагадування і follow-up:** nudges і чеклісти на базі cron або heartbeat. - - **Автоматизація браузера:** заповнення форм, збирання даних і повторення web-задач. - - **Координація між пристроями:** надішліть задачу з телефону, дайте Gateway виконати її на сервері й отримайте результат назад у чаті. + - **Персональні брифінги:** підсумки inbox, календаря та новин, які вас цікавлять. + - **Дослідження та чернетки:** швидке дослідження, підсумки й перші чернетки для листів або документів. + - **Нагадування та follow-ups:** підказки й чеклісти на основі cron або heartbeat. + - **Автоматизація браузера:** заповнення форм, збирання даних і повторення веб-завдань. + - **Координація між пристроями:** надішліть завдання з телефону, дозвольте Gateway виконати його на сервері й отримайте результат назад у чат. - - Так — для **дослідження, кваліфікації та створення чернеток**. Він може сканувати сайти, будувати shortlists, - підсумовувати prospects і писати чернетки outreach або рекламних текстів. + + Так — для **дослідження, кваліфікації й підготовки чернеток**. Він може сканувати сайти, складати короткі списки, + підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів. - Для **outreach або запуску реклами** тримайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ, і перевіряйте все перед надсиланням. Найбезпечніший шаблон — нехай - OpenClaw створює чернетку, а ви схвалюєте. + Для **outreach або рекламних кампаній** залишайте людину в контурі. Уникайте спаму, дотримуйтеся місцевих законів і + політик платформ та перевіряйте все перед відправленням. Найбезпечніший шаблон — дозволити + OpenClaw підготувати чернетку, а вам — затвердити її. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний помічник** і координаційний рівень, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу кодування всередині repo. Використовуйте OpenClaw, коли вам - потрібні довготривала memory, доступ із різних пристроїв і orchestration tools. + OpenClaw — це **персональний помічник** і координаційний шар, а не заміна IDE. Використовуйте + Claude Code або Codex для найшвидшого прямого циклу кодування в репозиторії. Використовуйте OpenClaw, коли + вам потрібні довготривала пам'ять, доступ із різних пристроїв і оркестрація інструментів. Переваги: - - **Стійка memory + workspace** між сесіями - - **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, files, scheduling, hooks) - - **Постійно увімкнений Gateway** (запуск на VPS, взаємодія звідусіль) + - **Постійна пам'ять + workspace** між сеансами + - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (браузер, файли, планування, hooks) + - **Завжди ввімкнений Gateway** (працює на VPS, взаємодіяйте звідусіль) - **Nodes** для локального browser/screen/camera/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -978,69 +985,69 @@ x-i18n: ## Skills і автоматизація - - Використовуйте керовані override-и замість редагування копії в repo. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте теку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані override-и все одно мають перевагу над bundled Skills без втручання в git. Якщо вам потрібно, щоб Skill був встановлений глобально, але видимий лише деяким agents, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні upstream, мають жити в repo і виходити як PR. + + Використовуйте керовані overrides замість редагування копії в репозиторії. Помістіть ваші зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тому керовані overrides все одно мають вищий пріоритет за bundled skills без дотику до git. Якщо skill має бути встановлений глобально, але видимий лише деяким агентам, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні upstream, мають жити в репозиторії й надсилатися як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Стандартний пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` типово встановлює у `./skills`, які OpenClaw розглядає як `/skills` у наступній сесії. Якщо Skill має бути видимим лише певним agents, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw трактує як `/skills` у наступному сеансі. Якщо skill має бути видимий лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - + Сьогодні підтримуються такі шаблони: - - **Cron jobs**: ізольовані jobs можуть задавати override `model` для кожної job. - - **Sub-agents**: маршрутизуйте задачі до окремих agents із різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб змінити модель поточної сесії в будь-який момент. + - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. + - **Sub-agents**: маршрутизуйте завдання до окремих агентів із різними моделями за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточного сеансу. - Див. [Cron jobs](/uk/automation/cron-jobs), [Multi-Agent Routing](/uk/concepts/multi-agent) і [Слеш-команди](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація мультиагентів](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands). - Використовуйте **sub-agents** для довгих або паралельних задач. Sub-agents працюють у власній сесії, + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власному сеансі, повертають підсумок і зберігають чутливість вашого основного чату. Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб побачити, що Gateway робить просто зараз (і чи він зайнятий). + Використовуйте `/status` у чаті, щоб побачити, що зараз робить Gateway (і чи зайнятий він). - Порада щодо токенів: як довгі задачі, так і sub-agents споживають токени. Якщо вартість критична, задайте - дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: довгі завдання й sub-agents обидва споживають токени. Якщо вас + турбує вартість, задайте дешевшу модель для sub-agents через `agents.defaults.subagents.model`. - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте thread bindings. Ви можете прив’язати Discord thread до subagent або цілі session, щоб наступні повідомлення в цьому thread лишалися в межах прив’язаної session. + + Використовуйте прив'язки thread. Ви можете прив'язати Discord thread до subagent або session target, щоб подальші повідомлення в цьому thread залишалися на прив'язаному сеансі. Базовий процес: - - Створіть через `sessions_spawn` з `thread: true` (і за потреби `mode: "session"` для стійкого follow-up). - - Або прив’яжіть вручну через `/focus `. - - Використовуйте `/agents`, щоб перевірити стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним unfocus. - - Використовуйте `/unfocus`, щоб від’єднати thread. + - Створіть через `sessions_spawn` із `thread: true` (і за бажанням `mode: "session"` для сталого follow-up). + - Або вручну прив'яжіть через `/focus `. + - Використовуйте `/agents`, щоб перевірити стан прив'язки. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати авто-скасуванням фокусу. + - Використовуйте `/unfocus`, щоб від'єднати thread. Потрібна конфігурація: - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - Override-и Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоприв’язка під час spawn: встановіть `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Автоприв'язка під час spawn: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Слеш-команди](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands). - - Спочатку перевірте визначений requester route: + + Спочатку перевірте розв'язаний маршрут requester: - - Доставка completion-mode subagent надає перевагу будь-якому прив’язаному thread або conversation route, якщо він існує. - - Якщо походження completion містить лише канал, OpenClaw відступає до збереженого route requester session (`lastChannel` / `lastTo` / `lastAccountId`), тож пряма доставка все одно може спрацювати. - - Якщо немає ні прив’язаного route, ні придатного збереженого route, пряма доставка може не вдатися, і результат переходить до queued session delivery замість негайної публікації в чат. - - Невалідні або застарілі цілі все одно можуть змусити перейти до queue fallback або остаточної невдачі доставки. - - Якщо остання видима відповідь assistant у child — це точний тихий токен `NO_REPLY` / `no_reply`, або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого ранішого progress. - - Якщо child перевищив timeout лише після викликів tools, announce може згорнути це в короткий підсумок часткового progress замість відтворення сирого виводу tools. + - Доставка completion-mode subagent віддає перевагу будь-якому прив'язаному thread або маршруту розмови, якщо такий існує. + - Якщо completion origin містить лише канал, OpenClaw повертається до збереженого маршруту сеансу requester (`lastChannel` / `lastTo` / `lastAccountId`), тож пряма доставка все одно може спрацювати. + - Якщо немає ані прив'язаного маршруту, ані придатного збереженого маршруту, пряма доставка може не вдатися, і результат повертається до queued session delivery замість негайної публікації в чат. + - Невалідні або застарілі цілі все одно можуть примусити fallback до черги або остаточну помилку доставки. + - Якщо остання видима відповідь assistant дочірнього агента — точний тихий токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу. + - Якщо дочірній агент перевищив тайм-аут після одних лише викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1048,19 +1055,19 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks), [Session Tools](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент сеансів](/uk/concepts/session-tool). - Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно, - заплановані jobs не запускатимуться. + Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно, + заплановані завдання не запускатимуться. Контрольний список: - - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. + - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. - Переконайтеся, що Gateway працює 24/7 (без сну/перезапусків). - - Перевірте налаштування часового поясу для job (`--tz` проти часового поясу host). + - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу host). Налагодження: @@ -1069,21 +1076,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation). - + Спочатку перевірте режим доставки: - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. - - Відсутня або невалідна announce-ціль (`channel` / `to`) означає, що runner пропустив outbound delivery. - - Збої auth каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але credentials заблокували це. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно недоставним, тож runner також пригнічує queued fallback delivery. + - Відсутня або невалідна announce-ціль (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але облікові дані це заблокували. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` лише) вважається навмисно недоставлюваним, тому runner також пригнічує queued fallback delivery. - Для ізольованих cron jobs фінальною доставкою володіє runner. Очікується, - що agent поверне plain-text summary, який runner надішле. `--no-deliver` зберігає - цей результат внутрішнім; це не дозволяє agent натомість напряму надсилати через + Для ізольованих cron-завдань runner відповідає за фінальну доставку. Від агента + очікується повернення текстового підсумку, який runner надішле. `--no-deliver` зберігає + цей результат внутрішнім; це не дозволяє агенту напряму надсилати через message tool. Налагодження: @@ -1093,27 +1100,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові задачі](/uk/automation/tasks). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). - - Зазвичай це шлях live model-switch, а не дублювання розкладу. + + Зазвичай це шлях живого перемикання моделі, а не дублювання планування. Ізольований cron може зберігати runtime handoff моделі та повторювати спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого - provider/model, а якщо switch ніс новий override auth profile, cron - також зберігає його перед повторною спробою. + запуск викидає `LiveSessionModelSwitchError`. Повтор зберігає перемкнутого + provider/model, і якщо перемикання містило новий override auth profile, cron + також зберігає це перед повтором. - Пов’язані правила вибору: + Пов'язані правила вибору: - Override моделі Gmail hook має найвищий пріоритет, коли застосовно. - - Потім `model` для job. - - Потім будь-який збережений override моделі cron-session. - - Потім звичайний вибір моделі agent/default. + - Потім — `model` для кожного завдання. + - Потім — будь-який збережений override моделі cron-сеансу. + - Потім — звичайний вибір моделі агента/за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 switch-повторів - cron завершується замість нескінченного циклу. + Цикл повторів обмежений. Після початкової спроби плюс 2 повторів перемикання + cron перериває виконання замість нескінченного циклу. Налагодження: @@ -1126,9 +1133,9 @@ x-i18n: - - Використовуйте нативні команди `openclaw skills` або просто кладіть Skills у свій workspace. UI Skills для macOS недоступний на Linux. - Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). + + Використовуйте нативні команди `openclaw skills` або просто помістіть skills у ваш workspace. Інтерфейс Skills для macOS недоступний на Linux. + Переглядати skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1141,39 +1148,39 @@ x-i18n: openclaw skills check ``` - Нативний `openclaw skills install` записує в каталог `skills/` - активного workspace. Встановлюйте окремий CLI `clawhub` лише якщо хочете публікувати або - синхронізувати власні Skills. Для спільних встановлень між agents кладіть Skill у + Нативний `openclaw skills install` записує у каталог `skills/` + активного workspace. Окремий CLI `clawhub` потрібен лише якщо ви хочете публікувати або + синхронізувати власні skills. Для спільного встановлення між агентами помістіть skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете обмежити видимість певним agents. + `agents.list[].skills`, якщо хочете обмежити, які агенти можуть його бачити. - + Так. Використовуйте планувальник Gateway: - - **Cron jobs** для запланованих або повторюваних задач (зберігаються після перезапусків). - - **Heartbeat** для періодичних перевірок "головної session". - - **Ізольовані jobs** для автономних agents, які публікують підсумки або доставляють їх у чати. + - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). + - **Heartbeat** для періодичних перевірок "основного сеансу". + - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють у чати. - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation), + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не напряму. Skills на macOS обмежуються через `metadata.openclaw.os` плюс потрібні бінарники, і Skills з’являються в system prompt лише тоді, коли вони доступні на **Gateway host**. На Linux Skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. + + Напряму — ні. Skills для macOS контролюються `metadata.openclaw.os` плюс потрібними бінарниками, а skills з'являються в system prompt лише коли вони придатні на **gateway host**. На Linux skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не override-нете перевірку. - Є три підтримувані шаблони: + У вас є три підтримувані шаблони: - **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються як зазвичай, бо Gateway host — це macOS. + **Варіант A — запустити Gateway на Mac (найпростіше).** + Запустіть Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-порти-вже-запущені-і-віддалений-режим) або через Tailscale. Skills завантажаться нормально, бо gateway host — це macOS. - **Варіант B — використовувати macOS node (без SSH).** - Запускайте Gateway на Linux, під’єднайте macOS node (menubar app) і встановіть **Node Run Commands** у "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати macOS-only Skills доступними, коли потрібні бінарники існують на node. Агент запускає ці Skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додає цю команду до allowlist. + **Варіант B — використати node macOS (без SSH).** + Запустіть Gateway на Linux, підключіть node macOS (menubar app) і встановіть **Node Run Commands** у "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарники існують на node. Агент запускає ці skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. - **Варіант C — проксувати бінарники macOS через SSH (просунуто).** - Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники визначалися як SSH-обгортки, які виконуються на Mac. Потім перевизначте Skill, щоб дозволити Linux і він лишався доступним. + **Варіант C — проксіювати бінарники macOS через SSH (розширений).** + Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники резолвилися в SSH-обгортки, які запускаються на Mac. Потім override-ніть skill, щоб дозволити Linux і зберегти його придатним. 1. Створіть SSH-обгортку для бінарника (приклад: `memo` для Apple Notes): @@ -1183,8 +1190,8 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Додайте обгортку в `PATH` на Linux host (наприклад, `~/bin/memo`). - 3. Перевизначте metadata Skill (workspace або `~/.openclaw/skills`) так, щоб дозволити Linux: + 2. Помістіть обгортку в `PATH` на Linux host (наприклад `~/bin/memo`). + 3. Override-ніть метадані skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- @@ -1194,157 +1201,158 @@ x-i18n: --- ``` - 4. Почніть нову session, щоб snapshot Skills оновився. + 4. Почніть новий сеанс, щоб знімок skills оновився. - - Вбудованої зараз немає. + + Вбудованої наразі немає. Варіанти: - - **Custom skill / plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. + - **Користувацький skill / plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Автоматизація браузера:** працює без коду, але повільніша і крихкіша. - Якщо ви хочете зберігати context для кожного клієнта (workflows агентства), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (агентські процеси), простий шаблон такий: - - Одна сторінка Notion на клієнта (context + preferences + активна робота). - - Попросіть agent витягувати цю сторінку на початку session. + - Одна сторінка Notion на клієнта (контекст + уподобання + активна робота). + - Попросіть агента зчитувати цю сторінку на початку сеансу. - Якщо хочете нативну інтеграцію, відкрийте feature request або створіть Skill, - який працює з цими API. + Якщо вам потрібна нативна інтеграція, відкрийте feature request або створіть skill + для цих API. - Встановлення Skills: + Установлення skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між agents розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі agents, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарники, встановлені через Homebrew; на Linux це означає Linuxbrew (див. запис ЧаП про Homebrew Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі skills очікують встановлення бінарників через Homebrew; на Linux це означає Linuxbrew (див. вище пункт FAQ про Homebrew на Linux). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP: + + Використовуйте вбудований браузерний профіль `user`, який підключається через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо ви хочете власну назву, створіть явний MCP-профіль: + Якщо вам потрібна власна назва, створіть явний MCP-профіль: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях є локальним для host. Якщо Gateway працює деінде, або запускайте node host на машині з браузером, або використовуйте remote CDP. + Цей шлях є локальним для host. Якщо Gateway працює деінде, або запустіть node host на машині з браузером, або використовуйте remote CDP. Поточні обмеження `existing-session` / `user`: - - дії базуються на ref, а не на CSS-selector - - завантаження файлів потребує `ref` / `inputRef` і зараз підтримує лише один файл за раз - - `responsebody`, експорт PDF, interception завантажень і batch-дії все ще потребують керованого браузера або сирого CDP-профілю + - дії прив'язані до ref, а не до CSS-selector + - завантаження файлів вимагає `ref` / `inputRef` і наразі підтримує по одному файлу за раз + - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP -## Пісочниця і пам’ять +## Пісочниця та пам'ять Так. Див. [Пісочниця](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або sandbox images), див. [Docker](/uk/install/docker). - - Образ за замовчуванням орієнтований на безпеку і працює від користувача `node`, тому він не - містить системних пакетів, Homebrew або bundled-браузерів. Для повнішого налаштування: + + Типовий образ орієнтований на безпеку і працює від користувача `node`, тому не + містить системних пакетів, Homebrew або bundled browsers. Для повнішого налаштування: - - Збережіть `/home/node` у `OPENCLAW_HOME_VOLUME`, щоб кеші переживали перезапуски. - - Запікайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - - Встановіть браузери Playwright через bundled CLI: + - Зробіть `/home/node` постійним за допомогою `OPENCLAW_HOME_VOLUME`, щоб кеші зберігалися. + - Додайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Установіть Playwright browsers через bundled CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Встановіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. + - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях є постійним. Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). - - Так — якщо ваш приватний трафік це **DM**, а публічний трафік — **groups**. + + Так — якщо ваш приватний трафік — це **DM**, а публічний трафік — це **групи**. - Використайте `agents.defaults.sandbox.mode: "non-main"`, щоб group/channel sessions (ключі не main) запускалися в Docker, а головна DM-session лишалася на host. Потім обмежте, які tools доступні в sandboxed sessions, через `tools.sandbox.tools`. + Використайте `agents.defaults.sandbox.mode: "non-main"`, щоб сеанси груп/каналів (ключі не-main) запускалися в Docker, а головний DM-сеанс залишався на host. Потім обмежте набір інструментів, доступних у sandbox-сеансах, через `tools.sandbox.tools`. Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Ключове посилання на конфігурацію: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідник із ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Встановіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Global + per-agent bind-и об’єднуються; bind-и per-agent ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що bind-и обходять файлові стіни sandbox. + + Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад `"/home/user/src:/src:ro"`). Глобальні й поагентні прив'язки зливаються; поагентні прив'язки ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам'ятайте, що прив'язки обходять файлові стіни sandbox. - OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, визначеним через найглибшого наявного предка. Це означає, що вихід через symlink-parent усе одно буде fail closed, навіть якщо останній сегмент шляху ще не існує, а перевірки allowed-root і далі застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв'язаним через найглибший наявний батьківський каталог. Це означає, що обходи через symlink-батьків усе одно блокуються навіть тоді, коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв'язання symlink. - Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і зауваг із безпеки. + Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і зауваг щодо безпеки. - - Пам’ять OpenClaw — це просто Markdown-файли в workspace агента: + + Пам'ять OpenClaw — це просто Markdown-файли у workspace агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Кураторські довгострокові нотатки в `MEMORY.md` (лише main/private sessions) + - Кураторські довгострокові нотатки в `MEMORY.md` (лише основні/приватні сеанси) - OpenClaw також запускає **тихий pre-compaction memory flush**, щоб нагадати моделі - записати стійкі нотатки перед auto-compaction. Це виконується лише тоді, коли workspace - доступний на запис (read-only sandbox пропускає це). Див. [Пам’ять](/uk/concepts/memory). + OpenClaw також виконує **тихе скидання пам'яті перед compaction**, щоб нагадати моделі + записати стійкі нотатки перед auto-compaction. Це запускається лише коли workspace + доступний для запису (read-only sandbox пропускає це). Див. [Пам'ять](/uk/concepts/memory). - - Попросіть бота **записати факт у memory**. Довгострокові нотатки належать у `MEMORY.md`, - короткостроковий context — у `memory/YYYY-MM-DD.md`. + + Попросіть бота **записати факт у пам'ять**. Довгострокові нотатки мають бути в `MEMORY.md`, + короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще напрям, який ми покращуємо. Допомагає нагадувати моделі зберігати спогади; - вона знатиме, що робити. Якщо все одно забуває, перевірте, чи Gateway використовує той самий - workspace щоразу під час запуску. + Це все ще область, яку ми вдосконалюємо. Корисно нагадувати моделі зберігати спогади; + вона зрозуміє, що робити. Якщо вона все одно забуває, перевірте, що Gateway використовує той самий + workspace під час кожного запуску. - Документація: [Пам’ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). + Документація: [Пам'ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). - - Файли пам’яті живуть на диску і зберігаються, доки ви їх не видалите. Обмеження — це ваше - сховище, а не модель. **Контекст сесії** все одно обмежений вікном контексту моделі, - тому довгі розмови можуть стискатися або обрізатися. Саме тому існує memory search — - він повертає в context лише релевантні частини. + + Файли пам'яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеження — це + сховище, а не модель. **Контекст сеансу** все одно обмежений вікном + контексту моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому + існує semantic memory search — він повертає в контекст лише релевантні частини. - Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). + Документація: [Пам'ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - - Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває chat/completions і + + Лише якщо ви використовуєте **embeddings OpenAI**. Codex OAuth покриває chat/completions і **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід через Codex CLI)** не допомагає для semantic memory search. Для embeddings OpenAI - усе ще потрібен справжній API-ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + вхід у Codex CLI)** не допоможе для semantic memory search. Для embeddings OpenAI + усе одно потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли - може знайти API-ключ (auth profiles, `models.providers.*.apiKey` або env vars). - Він надає перевагу OpenAI, якщо є ключ OpenAI, інакше Gemini, якщо є ключ Gemini, + може знайти API key (auth profiles, `models.providers.*.apiKey` або env vars). + Він віддає перевагу OpenAI, якщо знаходить ключ OpenAI, інакше Gemini, якщо знаходить ключ Gemini, потім Voyage, потім Mistral. Якщо жодного віддаленого ключа немає, memory - search лишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний шлях до локальної моделі, OpenClaw - надає перевагу `local`. Ollama підтримується, якщо ви явно задаєте + search залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний + локальний шлях до моделі, OpenClaw + надає перевагу `local`. Ollama підтримується, коли ви явно встановлюєте `memorySearch.provider = "ollama"`. - Якщо ви волієте залишитися локально, встановіть `memorySearch.provider = "local"` (і необов’язково - `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, встановіть + Якщо ви хочете залишатися локальними, установіть `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо ви хочете embeddings Gemini, установіть `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - див. [Пам’ять](/uk/concepts/memory) для деталей налаштування. + `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** + — деталі налаштування див. у [Пам'ять](/uk/concepts/memory). @@ -1352,52 +1360,52 @@ x-i18n: ## Де що лежить на диску - - Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. + + Ні — **стан OpenClaw локальний**, але **зовнішні служби все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** sessions, memory-файли, config і workspace живуть на Gateway host - (`~/.openclaw` + ваш каталог workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте модельним провайдерам (Anthropic/OpenAI тощо), ідуть - до їхніх API, а chat-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + - **Локально за замовчуванням:** сеанси, файли пам'яті, конфігурація та workspace живуть на gateway host + (`~/.openclaw` + каталог вашого workspace). + - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), ідуть до + їхніх API, а платформи чатів (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте слід:** використання локальних моделей залишає prompts на вашій машині, але трафік - каналів усе одно проходить через сервери каналу. + - **Ви контролюєте слід:** використання локальних моделей зберігає prompts на вашій машині, але трафік + каналів усе одно проходить через сервери цих каналів. - Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). + Пов'язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам'ять](/uk/concepts/memory). - Усе живе під `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): + Усе живе в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): - | Path | Purpose | - | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (копіюється в auth profiles при першому використанні) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys та необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язковий file-backed payload secret для провайдерів `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл legacy compatibility (статичні записи `api_key` очищені) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан на рівні agent (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | History розмов і state (для кожного agent) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadata сесій (для кожного agent) | + | Path | Призначення | + | --------------------------------------------------------------- | ------------------------------------------------------------------- | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy-імпорт OAuth (копіюється в auth profiles під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys і необов'язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов'язкове файлове secret payload для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy-файл сумісності (статичні записи `api_key` очищуються) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Поагентний стан (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (по агенту) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сеансів (по агенту) | - Legacy single-agent path: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). + Legacy-шлях single-agent: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`). - Ваш **workspace** (AGENTS.md, memory-файли, Skills тощо) є окремим і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (AGENTS.md, файли пам'яті, skills тощо) є окремим і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). Ці файли живуть у **workspace агента**, а не в `~/.openclaw`. - - **Workspace (для кожного agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + - **Workspace (на агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md` (або legacy fallback `memory.md`, коли `MEMORY.md` відсутній), - `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - - **Каталог state (`~/.openclaw`)**: config, state каналів/провайдерів, auth profiles, sessions, logs, - та спільні Skills (`~/.openclaw/skills`). + `memory/YYYY-MM-DD.md`, необов'язковий `HEARTBEAT.md`. + - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, auth profiles, sessions, logs, + і спільні skills (`~/.openclaw/skills`). - Workspace за замовчуванням — `~/.openclaw/workspace`, це можна налаштувати через: + Workspace за замовчуванням — `~/.openclaw/workspace`, налаштовується через: ```json5 { @@ -1405,24 +1413,24 @@ x-i18n: } ``` - Якщо бот "забуває" після перезапуску, підтвердьте, що Gateway використовує той самий - workspace під час кожного запуску (і пам’ятайте: remote mode використовує **gateway host** - workspace, а не ваш локальний ноутбук). + Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway щоразу використовує той самий + workspace (і пам'ятайте: remote mode використовує **workspace gateway host**, + а не вашого локального ноутбука). - Порада: якщо ви хочете стійку поведінку або вподобання, попросіть бота **записати це в - AGENTS.md або MEMORY.md**, а не покладатися на history чату. + Порада: якщо ви хочете зберегти сталу поведінку або вподобання, попросіть бота **записати це в + AGENTS.md або MEMORY.md**, а не покладатися на історію чату. - Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). + Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам'ять](/uk/concepts/memory). - Помістіть ваш **workspace агента** в **приватний** git repo і робіть його резервну копію десь - приватно (наприклад, у GitHub private). Це зберігає memory + файли AGENTS/SOUL/USER - і дозволяє відновити "розум" помічника пізніше. + Зберігайте **workspace агента** у **приватному** git-репозиторії та робіть його резервні копії + у приватному місці (наприклад, приватний GitHub). Це захоплює пам'ять + файли AGENTS/SOUL/USER + і дає змогу пізніше відновити "розум" помічника. - **Не** commit-те нічого з `~/.openclaw` (credentials, sessions, tokens або encrypted payload secrets). - Якщо вам потрібне повне відновлення, окремо робіть резервні копії і workspace, і каталогу state + **Не** комітьте нічого з `~/.openclaw` (облікові дані, сеанси, токени або зашифровані secret payloads). + Якщо вам потрібне повне відновлення, окремо робіть резервні копії і workspace, і каталогу стану (див. питання про міграцію вище). Документація: [Workspace агента](/uk/concepts/agent-workspace). @@ -1430,19 +1438,19 @@ x-i18n: - Див. окрему інструкцію: [Видалення](/uk/install/uninstall). + Див. окремий посібник: [Видалення](/uk/install/uninstall). - - Так. Workspace — це **cwd за замовчуванням** і якір memory, а не жорстка sandbox. - Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших - місць на host, якщо sandboxing не увімкнено. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або sandbox-налаштування для окремих agents. Якщо ви - хочете, щоб repo був робочим каталогом за замовчуванням, вкажіть для цього agent - `workspace` як корінь repo. Repo OpenClaw — це лише вихідний код; тримайте - workspace окремо, якщо тільки ви навмисно не хочете, щоб agent працював усередині нього. + + Так. Workspace — це **типовий cwd** і якір пам'яті, а не жорстка sandbox. + Відносні шляхи резолвляться всередині workspace, але абсолютні шляхи можуть звертатися до інших + розташувань host, якщо пісочниця не ввімкнена. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або поагентні налаштування sandbox. Якщо ви + хочете, щоб репозиторій був типовим робочим каталогом, направте `workspace` + цього агента в корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. - Приклад (repo як cwd за замовчуванням): + Приклад (репозиторій як типовий cwd): ```json5 { @@ -1456,30 +1464,30 @@ x-i18n: - - Станом session володіє **gateway host**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). + + Стан сеансів належить **gateway host**. Якщо ви в remote mode, потрібний вам store сеансів знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сеансами](/uk/concepts/session). ## Основи конфігурації - - OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов'язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються доволі безпечні значення за замовчуванням (включно з workspace за замовчуванням `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема типовий workspace `~/.openclaw/workspace`). - - Bind-и без loopback **вимагають валідного шляху auth для gateway**. На практиці це означає: + + Bind-и не на loopback **вимагають валідного шляху автентифікації gateway**. На практиці це означає: - - auth через shared secret: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy без loopback + - автентифікація shared secret: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не на loopback ```json5 { @@ -1495,32 +1503,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` самі по собі **не** вмикають auth локального gateway. + - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише коли `gateway.auth.*` не задано. - - Для auth через пароль замість цього встановіть `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його неможливо визначити, визначення завершується fail closed (без маскування через remote fallback). - - Налаштування shared-secret у Control UI автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення shared secrets у URL. - - З `gateway.auth.mode: "trusted-proxy"` same-host reverse proxy через loopback все одно **не** задовольняє auth trusted-proxy. Trusted proxy має бути налаштованим джерелом без loopback. + - Для автентифікації паролем установіть `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв'язати, розв'язання закривається з помилкою (без маскувального remote fallback). + - Налаштування Control UI із shared secret автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення shared secrets в URL. + - Із `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback на тому ж host усе одно **не** задовольняє trusted-proxy auth. Trusted proxy має бути налаштованим джерелом не на loopback. - - OpenClaw примусово вимагає auth для gateway за замовчуванням, включно з loopback. У звичайному сценарії за замовчуванням це означає auth через токен: якщо не налаштовано явний шлях auth, запуск gateway переходить у режим токена і автоматично генерує його, зберігаючи в `gateway.auth.token`, тому **локальні WS-клієнти мають автентифікуватися**. Це блокує інші локальні процеси від виклику Gateway. + + OpenClaw за замовчуванням примусово вимагає автентифікацію gateway, зокрема на loopback. У звичайному типовому шляху це означає token auth: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим token і автоматично генерує токен, зберігаючи його в `gateway.auth.token`, тож **локальні WS-клієнти мають автентифікуватися**. Це блокує іншим локальним процесам можливість викликати Gateway. - Якщо ви віддаєте перевагу іншому шляху auth, ви можете явно вибрати режим пароля (або, для identity-aware reverse proxy без loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у своїй config. Doctor може згенерувати токен у будь-який момент: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для identity-aware reverse proxy не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен у будь-який момент: `openclaw doctor --generate-gateway-token`. - - Gateway стежить за config і підтримує hot-reload: + + Gateway стежить за конфігурацією й підтримує hot-reload: - - `gateway.reload.mode: "hybrid"` (за замовчуванням): безпечні зміни застосовуються hot, критичні — через перезапуск + - `gateway.reload.mode: "hybrid"` (типово): hot-apply безпечних змін, перезапуск для критичних - також підтримуються `hot`, `restart`, `off` - Встановіть `cli.banner.taglineMode` у config: + Установіть `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1532,24 +1540,24 @@ x-i18n: } ``` - - `off`: приховує текст слогана, але зберігає рядок із назвою/версією banner. + - `off`: приховує текст слогану, але залишає рядок із назвою/версією банера. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: змінні кумедні/сезонні слогани (поведінка за замовчуванням). - - Якщо ви не хочете banner взагалі, встановіть env `OPENCLAW_HIDE_BANNER=1`. + - `random`: циклічні кумедні/сезонні слогани (типова поведінка). + - Якщо ви взагалі не хочете банер, установіть env `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` працює без API-ключа. `web_search` залежить від вибраного + + `web_fetch` працює без API key. `web_search` залежить від обраного провайдера: - - Провайдери з API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API-ключа. - - Ollama Web Search не потребує ключа, але використовує налаштований host Ollama і вимагає `ollama signin`. - - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа / може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, вимагають своїх звичайних налаштувань API key. + - Ollama Web Search не потребує ключа, але використовує налаштований вами Ollama host і вимагає `ollama signin`. + - DuckDuckGo не потребує ключа, але це неофіційна HTML-інтеграція. + - SearXNG не потребує ключа/самостійно розміщується; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть провайдера. - Альтернативи через environment: + **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. + Альтернативи через середовище: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1584,66 +1592,66 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // необов'язково; опустіть для auto-detect }, }, }, } ``` - Специфічна для провайдера конфігурація web-search тепер живе в `plugins.entries..config.webSearch.*`. - Legacy-шляхи провайдера `tools.web.search.*` все ще тимчасово завантажуються для сумісності, але їх не слід використовувати в нових config. - Конфігурація fallback для web-fetch Firecrawl живе в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація вебпошуку, специфічна для провайдера, тепер живе в `plugins.entries..config.webSearch.*`. + Legacy-шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але не повинні використовуватися в нових конфігураціях. + Конфігурація fallback web-fetch Firecrawl живе в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. + - Якщо ви використовуєте allowlist-и, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового fallback-провайдера fetch на основі доступних credentials. Зараз bundled-провайдер — це Firecrawl. - - Демони читають env vars із `~/.openclaw/.env` (або з environment сервісу). + - Якщо `tools.web.fetch.provider` опущено, OpenClaw автоматично виявляє першого готового fallback-провайдера fetch із доступних облікових даних. Наразі bundled-провайдер — Firecrawl. + - Демони читають env vars із `~/.openclaw/.env` (або середовища служби). - Документація: [Web tools](/uk/tools/web). + Документація: [Вебінструменти](/uk/tools/web). - - `config.apply` замінює **всю конфігурацію повністю**. Якщо ви надсилаєте частковий об’єкт, усе - інше видаляється. + + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об'єкт, усе + інше буде видалено. Відновлення: - Відновіть із резервної копії (git або скопійований `~/.openclaw/openclaw.json`). - - Якщо резервної копії немає, знову запустіть `openclaw doctor` і переналаштуйте channels/models. - - Якщо це сталося неочікувано, створіть bug-report і додайте вашу останню відому config або будь-яку резервну копію. - - Локальний coding agent часто може відновити робочу config з логів або history. + - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і переналаштуйте канали/моделі. + - Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію. + - Локальний coding agent часто може відновити робочу конфігурацію з журналів або історії. Як уникнути: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Використовуйте `config.schema.lookup` спочатку, коли не впевнені в точному path або формі поля; він повертає вузол shallow schema плюс короткі підсумки безпосередніх дочірніх елементів для подальшого заглиблення. - - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни config. - - Якщо ви використовуєте owner-only інструмент `gateway` із запуску agent, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно з legacy-аліасами `tools.bash.*`, які нормалізуються до тих самих захищених exec-шляхів). + - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені в точному шляху або формі поля; він повертає вузол shallow schema плюс підсумки безпосередніх дочірніх елементів для поступового уточнення. + - Використовуйте `config.patch` для часткових RPC-редагувань; залиште `config.apply` лише для повної заміни конфігурації. + - Якщо ви використовуєте інструмент `gateway`, доступний лише власнику, із запуску агента, він усе одно відхиляє записи в `tools.exec.ask` / `tools.exec.security` (включно з legacy-аліасами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/uk/gateway/doctor). + Документація: [Конфігурація](/cli/config), [Налаштування](/cli/configure), [Doctor](/uk/gateway/doctor). - + Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє channels (Signal/WhatsApp), routing і sessions. - - **Nodes (пристрої):** Macs/iOS/Android підключаються як периферія й відкривають локальні tools (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі мозки/workspaces для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). - - **Sub-agents:** породжують фонову роботу з main agent, коли потрібен паралелізм. - - **TUI:** підключається до Gateway і перемикає agents/sessions. + - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сеансами. + - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (працівники):** окремі "мізки"/workspace для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). + - **Sub-agents:** запускають фонову роботу з основного агента, коли потрібен паралелізм. + - **TUI:** підключається до Gateway і перемикає агентів/сеанси. - Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Multi-Agent Routing](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). + Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). - - Так. Це параметр конфігурації: + + Так. Це опція конфігурації: ```json5 { @@ -1656,150 +1664,150 @@ x-i18n: } ``` - За замовчуванням `false` (із вікном). Headless частіше викликає anti-bot перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). + Типове значення — `false` (із вікном). Headless частіше провокує антибот-перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). - Headless використовує **той самий Chromium engine** і працює для більшості automation-сценаріїв (форми, кліки, scraping, logins). Основні відмінності: + Headless використовує **той самий Chromium engine** і працює для більшості автоматизацій (форми, кліки, скрапінг, входи). Основні відмінності: - - Немає видимого вікна браузера (використовуйте скриншоти, якщо вам потрібні візуальні підтвердження). - - Деякі сайти суворіше ставляться до automation у headless-режимі (CAPTCHA, anti-bot). - Наприклад, X/Twitter часто блокує headless sessions. + - Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуальна інформація). + - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, антибот). + Наприклад, X/Twitter часто блокує headless-сеанси. - Встановіть `browser.executablePath` на ваш бінарник Brave (або будь-який браузер на базі Chromium) і перезапустіть Gateway. + Установіть `browser.executablePath` на ваш бінарник Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway. Повні приклади конфігурації див. у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені gateway і nodes +## Віддалені gateway та nodes - - Повідомлення Telegram обробляються **gateway**. Gateway запускає agent і + + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і лише потім викликає nodes через **Gateway WebSocket**, коли потрібен node tool: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідний трафік провайдерів; вони отримують лише виклики node RPC. + Nodes не бачать вхідний трафік провайдера; вони отримують лише виклики node RPC. - - Коротка відповідь: **підключіть свій комп’ютер як node**. Gateway працює деінде, але він може + + Коротка відповідь: **підключіть ваш комп'ютер як node**. Gateway працює деінде, але може викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на host, який завжди увімкнений (VPS/home server). - 2. Додайте Gateway host і ваш комп’ютер в один tailnet. - 3. Переконайтеся, що Gateway WS доступний (bind tailnet або SSH tunnel). - 4. Відкрийте macOS-app локально і підключіться в режимі **Remote over SSH** (або напряму через tailnet), - щоб вона могла зареєструватися як node. - 5. Підтвердьте node на Gateway: + 1. Запустіть Gateway на завжди ввімкненому host (VPS/домашній сервер). + 2. Додайте gateway host і ваш комп'ютер до одного tailnet. + 3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH tunnel). + 4. Локально відкрийте застосунок macOS і підключіться в режимі **Remote over SSH** (або напряму через tailnet), + щоб він міг зареєструватися як node. + 5. Схваліть node на Gateway: ```bash openclaw devices list openclaw devices approve ``` - Окремий TCP-bridge не потрібен; nodes підключаються через Gateway WebSocket. + Окремий TCP bridge не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування щодо безпеки: підключення macOS node дозволяє `system.run` на цій машині. Підключайте - лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). + Нагадування про безпеку: підключення node macOS дозволяє `system.run` на цій машині. Підключайте + лише ті пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). - Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). + Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). - - Перевірте базові речі: + + Перевірте основи: - Gateway працює: `openclaw gateway status` - - Health Gateway: `openclaw status` - - Health каналів: `openclaw channels status` + - Стан Gateway: `openclaw status` + - Стан каналів: `openclaw channels status` - Потім перевірте auth і routing: + Потім перевірте автентифікацію та маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо підключаєтеся через SSH tunnel, підтвердьте, що локальний tunnel активний і вказує на правильний порт. - - Підтвердьте, що ваші allowlist-и (DM або group) включають ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` встановлено правильно. + - Якщо ви підключаєтеся через SSH tunnel, підтвердьте, що локальний tunnel працює й указує на правильний порт. + - Переконайтеся, що ваші allowlist-и (DM або група) включають ваш обліковий запис. Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - - Так. Вбудованого bridge "bot-to-bot" немає, але це можна з’єднати кількома + + Так. Вбудованого мосту "бот-до-бота" немає, але це можна реалізувати кількома надійними способами: - **Найпростіше:** використовуйте звичайний chat-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Bot A надсилає повідомлення Bot B, а далі Bot B відповідає як зазвичай. + **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай бот A надішле повідомлення боту B, а потім бот B відповість як звично. - **CLI bridge (універсально):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючись на чат, де інший бот - слухає. Якщо один бот працює на віддаленому VPS, націльте ваш CLI на той віддалений Gateway + **CLI-міст (універсально):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націлюючи на чат, де інший бот + слухає. Якщо один із ботів працює на віддаленому VPS, направте ваш CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускайте на машині, яка може дістатися до цільового Gateway): + Приклад шаблону (запускається з машини, яка може досягти цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися безкінечно (лише згадування, channel - allowlists або правило "не відповідати на повідомлення ботів"). + Порада: додайте обмежувач, щоб два боти не зациклилися нескінченно (відповідати лише на згадки, channel + allowlist-и або правило "не відповідати на повідомлення ботів"). Документація: [Віддалений доступ](/uk/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/uk/tools/agent-send). - - Ні. Один Gateway може хостити кілька agents, кожен із власним workspace, моделями за замовчуванням - і routing. Це стандартне налаштування, і воно значно дешевше та простіше, ніж запускати - один VPS на agent. + + Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм workspace, моделями за замовчуванням, + і маршрутизацією. Це типовий сценарій, і він набагато дешевший і простіший, ніж запускати + окремий VPS на кожного агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні config, якими ви не хочете ділитися. Інакше тримайте один Gateway і - використовуйте кілька agents або sub-agents. + різні конфігурації, якими ви не хочете ділитися. В інших випадках достатньо одного Gateway і + кількох агентів або sub-agents. - - Так — nodes є first-class способом доступу до вашого ноутбука з віддаленого Gateway, і вони - дають більше, ніж просто доступ до shell. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (достатньо невеликого VPS або box рівня Raspberry Pi; 4 GB RAM більш ніж достатньо), тому поширене - налаштування — це host, який завжди увімкнений, плюс ваш ноутбук як node. + + Так — nodes є першокласним способом доступу до ноутбука з віддаленого Gateway, і вони + дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є + легковаговим (невеликий VPS або коробка рівня Raspberry Pi цілком підходять; 4 GB RAM більш ніж достатньо), тож поширений + сценарій — host, що завжди увімкнений, плюс ваш ноутбук як node. - - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристрою. - - **Безпечніший контроль виконання.** `system.run` контролюється allowlist-ами/approval на node на цьому ноутбуці. - - **Більше інструментів пристрою.** Nodes відкривають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або під’єднуйтеся до локального Chrome на host через Chrome MCP. + - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристроїв. + - **Безпечніший контроль виконання.** `system.run` контролюється allowlist-ами/схваленнями node на цьому ноутбуці. + - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або підключайтеся до локального Chrome на host через Chrome MCP. - SSH підходить для епізодичного доступу до shell, але nodes простіші для постійних workflow агентів і + SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних робочих процесів агентів і автоматизації пристроїв. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Браузер](/uk/tools/browser). - - Ні. Лише **один gateway** має працювати на host, якщо тільки ви навмисно не запускаєте ізольовані profiles (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферія, яка підключається - до gateway (nodes iOS/Android, або macOS "node mode" у menubar app). Для headless node - hosts і керування через CLI див. [Node host CLI](/cli/node). + + Ні. На одному host зазвичай має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферія, яка підключається + до gateway (nodes iOS/Android або режим "node mode" у menubar app на macOS). Для headless node + host-ів і керування через CLI див. [Node host CLI](/cli/node). - Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. + Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. Так. - - `config.schema.lookup`: перевірити одне піддерево config разом із його вузлом shallow schema, відповідною UI-підказкою та короткими підсумками безпосередніх дочірніх елементів перед записом - - `config.get`: отримати поточний snapshot + hash - - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань) - - `config.apply`: перевірити + повністю замінити config, потім перезапустити - - Owner-only runtime tool `gateway` і далі відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; legacy-аліаси `tools.bash.*` нормалізуються до тих самих захищених exec-шляхів + - `config.schema.lookup`: перевірити одне піддерево конфігурації разом із shallow schema node, відповідною UI-підказкою та підсумками безпосередніх дочірніх елементів перед записом + - `config.get`: отримати поточний знімок + hash + - `config.patch`: безпечне часткове оновлення (переважний варіант для більшості RPC-редагувань) + - `config.apply`: перевірити + повністю замінити конфігурацію, а потім перезапустити + - Runtime tool `gateway`, доступний лише власнику, як і раніше відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; legacy-аліаси `tools.bash.*` нормалізуються до тих самих захищених шляхів exec @@ -1818,18 +1826,18 @@ x-i18n: Мінімальні кроки: - 1. **Встановити + увійти на VPS** + 1. **Установіть і увійдіть на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Встановити + увійти на Mac** - - Використайте застосунок Tailscale і ввійдіть у той самий tailnet. - 3. **Увімкнути MagicDNS (рекомендовано)** - - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. - 4. **Використовувати hostname tailnet** + 2. **Установіть і увійдіть на Mac** + - Використовуйте застосунок Tailscale і ввійдіть у той самий tailnet. + 3. **Увімкніть MagicDNS (рекомендовано)** + - В admin console Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім'я. + 4. **Використовуйте hostname tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1839,53 +1847,53 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив'язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - - Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через той самий endpoint Gateway WS. + + Serve відкриває **Control UI + WS Gateway**. Nodes підключаються через той самий endpoint Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS + Mac перебувають в одному tailnet**. - 2. **Використовуйте macOS-app у Remote mode** (SSH target може бути hostname tailnet). - App зробить tunnel порту Gateway і підключиться як node. - 3. **Підтвердьте node** на gateway: + 1. **Переконайтеся, що VPS і Mac в одному tailnet**. + 2. **Використовуйте застосунок macOS у Remote mode** (ціллю SSH може бути hostname tailnet). + Застосунок пробросить порт Gateway і підключиться як node. + 3. **Схваліть node** на gateway: ```bash openclaw devices list openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Виявлення](/uk/gateway/discovery), [віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Протокол Gateway](/uk/gateway/protocol), [Виявлення](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). - - Якщо вам потрібні лише **локальні tools** (screen/camera/exec) на другому ноутбуці, додайте його як - **node**. Це дозволяє залишити один Gateway і уникнути дублювання config. Локальні node tools + + Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як + **node**. Це дозволяє зберегти один Gateway і уникнути дублювання конфігурації. Локальні node tools наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. - Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). -## Env vars і завантаження .env +## Змінні середовища та завантаження .env - + OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - `.env` із поточного робочого каталогу - глобальний fallback `.env` із `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із `.env` файлів не перевизначає вже наявні env vars. + Жоден із файлів `.env` не перевизначає наявні env vars. - Ви також можете визначити inline env vars у config (застосовуються лише якщо відсутні в process env): + Ви також можете задати inline env vars у конфігурації (застосовуються лише якщо відсутні в env процесу): ```json5 { @@ -1896,15 +1904,15 @@ x-i18n: } ``` - Див. [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел. + Повний порядок пріоритету та джерела див. у [/environment](/uk/help/environment). - + Два поширені виправлення: - 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої shell. - 2. Увімкніть імпорт shell env (зручно, але лише за бажанням): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися навіть тоді, коли служба не успадковує env вашої оболонки. + 2. Увімкніть імпорт оболонки (зручна опція за вибором): ```json5 { @@ -1917,52 +1925,52 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти env var: + Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` повідомляє, чи увімкнено **імпорт shell env**. "Shell env: off" - **не** означає, що env vars відсутні — це лише означає, що OpenClaw не завантажуватиме + + `openclaw models status` повідомляє, чи ввімкнено **імпорт env з оболонки**. "Shell env: off" + **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично. - Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує ваше shell - environment. Виправлення: зробіть одне з цього: + Якщо Gateway працює як служба (launchd/systemd), він не успадковує середовище + вашої оболонки. Виправлення — зробити одне з цього: - 1. Помістіть токен у `~/.openclaw/.env`: + 1. Помістити токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт shell (`env.shellEnv.enabled: true`). - 3. Або додайте його до блоку `env` у config (застосовується лише якщо відсутній). + 2. Або ввімкнути імпорт оболонки (`env.shellEnv.enabled: true`). + 3. Або додати його в блок `env` конфігурації (застосовується лише якщо відсутній). - Потім перезапустіть gateway і перевірте знову: + Потім перезапустіть gateway і перевірте ще раз: ```bash openclaw models status ``` - Copilot-токени читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). + Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). -## Сесії та кілька чатів +## Сеанси та кілька чатів - Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сесіями](/uk/concepts/session). + Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сеансами](/uk/concepts/session). - - Сесії можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типово **0**). - Встановіть додатне значення, щоб увімкнути завершення через простій. Коли це увімкнено, **наступне** - повідомлення після періоду простою створює новий session id для цього ключа чату. - Це не видаляє транскрипти — лише починає нову session. + + Сеанси можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). + Установіть додатне значення, щоб увімкнути завершення за бездіяльністю. Коли воно ввімкнене, **наступне** + повідомлення після періоду бездіяльності починає новий session id для цього chat key. + Це не видаляє транскрипти — просто починається новий сеанс. ```json5 { @@ -1974,34 +1982,34 @@ x-i18n: - - Так, через **multi-agent routing** і **sub-agents**. Ви можете створити одного координатора - agent і кількох робочих agents із власними workspaces і моделями. + + Так, через **маршрутизацію мультиагентів** і **sub-agents**. Ви можете створити одного координуючого + агента і кількох робочих агентів із власними workspace та моделями. - Водночас це краще сприймати як **цікавий експеримент**. Це витрачає багато токенів і часто - менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми - уявляємо, — один бот, з яким ви говорите, але з різними сесіями для паралельної роботи. Цей - бот також може породжувати sub-agents за потреби. + Водночас це краще сприймати як **цікавий експеримент**. Це дорого з погляду токенів і часто + менш ефективно, ніж використовувати одного бота з окремими сеансами. Типова модель, яку ми + уявляємо, — це один бот, з яким ви спілкуєтеся, з різними сеансами для паралельної роботи. Цей + бот також може за потреби запускати sub-agents. - Документація: [Multi-agent routing](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). + Документація: [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). - - Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи tools або багато + + Контекст сеансу обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато файлів можуть викликати compaction або truncation. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими задачами і `/new` під час зміни тем. - - Тримайте важливий context у workspace і просіть бота перечитати його. - - Використовуйте sub-agents для довгих або паралельних робіт, щоб основний чат лишався меншим. - - Обирайте модель із більшим вікном контексту, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями та `/new` під час зміни тем. + - Тримайте важливий контекст у workspace і просіть бота перечитувати його. + - Використовуйте sub-agents для довгих або паралельних завдань, щоб основний чат залишався меншим. + - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. - + Використовуйте команду reset: ```bash @@ -2014,7 +2022,7 @@ x-i18n: openclaw reset --scope full --yes --non-interactive ``` - Потім заново запустіть налаштування: + Потім повторно виконайте налаштування: ```bash openclaw onboard --install-daemon @@ -2022,16 +2030,16 @@ x-i18n: Примітки: - - Onboarding також пропонує **Reset**, якщо бачить наявну config. Див. [Onboarding (CLI)](/uk/start/wizard). - - Якщо ви використовували profiles (`--profile` / `OPENCLAW_PROFILE`), скидайте кожен каталог state окремо (типово це `~/.openclaw-`). + - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скидайте кожен каталог стану окремо (типово це `~/.openclaw-`). - Dev reset: `openclaw gateway --dev --reset` (лише для dev; стирає dev config + credentials + sessions + workspace). - Використайте один із варіантів: + Використовуйте один із цих варіантів: - - **Стиснення** (зберігає розмову, але підсумовує старіші ходи): + - **Compact** (зберігає розмову, але підсумовує старіші ходи): ``` /compact @@ -2039,7 +2047,7 @@ x-i18n: або `/compact `, щоб спрямувати підсумок. - - **Скидання** (новий session ID для того самого ключа чату): + - **Reset** (новий session ID для того самого chat key): ``` /new @@ -2048,48 +2056,48 @@ x-i18n: Якщо це повторюється: - - Увімкніть або налаштуйте **обрізання сесій** (`agents.defaults.contextPruning`) для підрізання старого виводу tools. + - Увімкніть або налаштуйте **обрізання сеансів** (`agents.defaults.contextPruning`), щоб прибирати старий вивід інструментів. - Використовуйте модель із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання сесій](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Обрізання сеансів](/uk/concepts/session-pruning), [Керування сеансами](/uk/concepts/session). - Це помилка валідації провайдера: модель видала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що history сесії застаріла або пошкоджена (часто після довгих thread-ів + Це помилка валідації провайдера: модель видала блок `tool_use` без обов'язкового + `input`. Зазвичай це означає, що історія сеансу застаріла або пошкоджена (часто після довгих thread або зміни tool/schema). - Виправлення: почніть нову session через `/new` (окремим повідомленням). + Виправлення: почніть новий сеанс за допомогою `/new` (окреме повідомлення). - За замовчуванням heartbeats запускаються кожні **30m** (**1h** у разі використання OAuth auth). Налаштуйте або вимкніть їх: + Heartbeats за замовчуванням запускаються кожні **30m** (**1h** при використанні OAuth auth). Налаштуйте або вимкніть їх: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // or "0m" to disable + every: "2h", // або "0m", щоб вимкнути }, }, }, } ``` - Якщо `HEARTBEAT.md` існує, але фактично порожній (лише пусті рядки й markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб зекономити API-виклики. - Якщо файл відсутній, heartbeat усе одно запускається, а модель сама вирішує, що робити. + Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки + на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики. + Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити. - Override-и для окремих agents використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Для override-ів на агента використовуйте `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює з **вашим власним обліковим записом**, тож якщо ви є в групі, OpenClaw може її бачити. - За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + + Ні. OpenClaw працює на **вашому власному обліковому записі**, тож якщо ви є в групі, OpenClaw може її бачити. + За замовчуванням відповіді в групах блокуються, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). Якщо ви хочете, щоб лише **ви** могли запускати відповіді в групі: @@ -2107,7 +2115,7 @@ x-i18n: - Варіант 1 (найшвидший): переглядайте логи й надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): дивіться журнали в реальному часі й надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json @@ -2116,61 +2124,61 @@ x-i18n: Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/є в allowlist): перелічіть групи з config: + Варіант 2 (якщо вже налаштовано/дозволено): перелічіть групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Логи](/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Журнали](/cli/logs). - Дві типові причини: + Дві поширені причини: - - Увімкнено gating за згадкою (за замовчуванням). Ви повинні @згадати бота (або відповідати `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і група не входить до allowlist. + - Увімкнено перевірку згадок (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групи немає в allowlist. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - Direct-чати за замовчуванням згортаються до main session. Groups/channels мають власні session keys, а теми Telegram / thread-и Discord — це окремі sessions. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + Прямі чати за замовчуванням згортаються в основний сеанс. Групи/канали мають власні session keys, а теми Telegram / thread-и Discord — це окремі сеанси. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але слідкуйте за: + + Жорстких обмежень немає. Десятки (навіть сотні) — нормально, але слідкуйте за: - **Зростанням диска:** sessions + transcripts живуть у `~/.openclaw/agents//sessions/`. - - **Вартістю токенів:** більше agents означає більше одночасного використання моделей. - - **Операційними накладними витратами:** auth profiles, workspaces і channel routing на рівні agent. + - **Вартістю токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційною складністю:** auth profiles, workspaces і channel routing на агента. Поради: - - Тримайте один **активний** workspace на agent (`agents.defaults.workspace`). - - Очищайте старі sessions (видаляйте JSONL або записи зі сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб знаходити зайві workspaces і невідповідності profiles. + - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). + - Очищайте старі сеанси (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб знаходити stray workspace і невідповідності профілів. - - Так. Використовуйте **Multi-Agent Routing**, щоб запускати кілька ізольованих agents і маршрутизувати вхідні повідомлення за - channel/account/peer. Slack підтримується як канал і може бути прив’язаний до конкретних agents. + + Так. Використовуйте **Маршрутизацію мультиагентів**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив'язаний до конкретних агентів. - Доступ до браузера потужний, але це не "може все, що може людина" — anti-bot, CAPTCHA та MFA все - ще можуть блокувати automation. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на host, - або CDP на машині, яка фактично запускає браузер. + Доступ до браузера потужний, але це не рівнозначно "може робити все, що й людина" — антибот-захист, CAPTCHA і MFA + усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на host, + або CDP на машині, де насправді запускається браузер. - Найкраща практика налаштування: + Найкращий шаблон налаштування: - - Host Gateway, який завжди увімкнений (VPS/Mac mini). - - Один agent на роль (bindings). - - Канал(и) Slack, прив’язані до цих agents. + - Host Gateway, що завжди увімкнений (VPS/Mac mini). + - Один агент на роль (bindings). + - Канали Slack, прив'язані до цих агентів. - Локальний браузер через Chrome MCP або node за потреби. - Документація: [Multi-Agent Routing](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + Документація: [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). @@ -2179,73 +2187,4 @@ x-i18n: ## Моделі: значення за замовчуванням, вибір, аліаси, перемикання - - Модель OpenClaw за замовчуванням — це те, що ви встановили в: - - ``` - agents.defaults.model.primary - ``` - - На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг налаштованого provider для цього точного model id, і лише після цього відступає до налаштованого провайдера за замовчуванням як до застарілого compatibility-path. Якщо цей provider більше не відкриває налаштовану default model, OpenClaw відступає до першого налаштованого provider/model замість того, щоб показувати застаріле default від видаленого provider. Однак вам усе одно слід **явно** встановлювати `provider/model`. - - - - - **Рекомендовано за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. - **Для агентів із tools або недовіреним вводом:** віддавайте перевагу силі моделі над вартістю. - **Для рутинного/низькоризикового чату:** використовуйте дешевші fallback-моделі й маршрутизуйте за роллю agent. - - Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і - [Локальні моделі](/uk/gateway/local-models). - - Загальне правило: використовуйте **найкращу модель, яку можете собі дозволити** для високоризикової роботи, а дешевшу - модель — для рутинного чату або підсумків. Ви можете маршрутизувати моделі по agents і використовувати sub-agents для - паралелізації довгих задач (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і - [Sub-agents](/uk/tools/subagents). - - Сильне попередження: слабші/надто квантовані моделі вразливіші до prompt - injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). - - Більше контексту: [Моделі](/uk/concepts/models). - - - - - Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни config. - - Безпечні варіанти: - - - `/model` у чаті (швидко, для однієї session) - - `openclaw models set ...` (оновлює лише config моделі) - - `openclaw configure --section model` (інтерактивно) - - редагування `agents.defaults.model` у `~/.openclaw/openclaw.json` - - Уникайте `config.apply` із частковим об’єктом, якщо ви не маєте наміру замінити всю config. - Для RPC-редагувань спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Payload lookup дає нормалізований path, документи/обмеження shallow schema та короткі підсумки безпосередніх дочірніх елементів. - для часткових оновлень. - Якщо ви таки перезаписали config, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. - - Документація: [Моделі](/uk/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/uk/gateway/doctor). - - - - - Так. Ollama — найпростіший шлях до локальних моделей. - - Найшвидше налаштування: - - 1. Встановіть Ollama з `https://ollama.com/download` - 2. Завантажте локальну модель, наприклад `ollama pull glm-4.7-flash` - 3. Якщо вам потрібні також cloud-моделі, виконайте `ollama signin` - 4. Запустіть `openclaw onboard` і виберіть `Ollama` - 5. Виберіть `Local` або `Cloud + Local` - - Примітки: - - - `Cloud + Local` дає вам cloud-моделі плюс ваші локальні моделі Ollama - - cloud-моделі, як-от `kimi-k2.5:cloud`, не потребують локального pull - - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - - Примітка з безпеки: менші або сильно квантовані моделі вразливіші до prompt - injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати tools. - Якщо ви все ж хочете малі моделі, увімк \ No newline at end of file + ` щоб примусово задати кількість worker-ів (обмеження — 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. -- Обсяг: - - Наскрізна поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing вузлів і складніший networking + - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - Працює в тихому режимі за замовчуванням, щоб зменшити накладні витрати на консольний I/O. +- Корисні перевизначення: + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. +- Охоплення: + - Наскрізна поведінка multi-instance gateway + - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестів (може працювати повільніше) -### E2E: smoke бекенда OpenShell +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Обсяг: +- Охоплення: - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Проганяє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє поведінку remote-canonical filesystem через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і справний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox -- Корисні overrides: + - Потрібні локальний CLI `openshell` і працездатний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox +- Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) @@ -138,142 +138,182 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Обсяг: - - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool-calling, проблем auth і поведінки rate limit +- Охоплення: + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику tool, проблем auth і поведінки rate limit - Очікування: - - Навмисно не стабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом не є CI-stable (реальні мережі, реальні політики провайдера, квоти, збої) - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth матеріали у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежно від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте per-live override через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. +- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише коли навмисно хочете, щоб live-тести використовували вашу реальну домашню директорію. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежить від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдерів помітно активні навіть коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway відразу транслюються під час live-запусків. - - Налаштовуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера було видно як активні навіть тоді, коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. + - Налаштовуйте heartbeats прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeats gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який набір запускати? +## Який набір мені запускати? Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) -- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо зміни значні) +- Торкаєтеся мережевої логіки gateway / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклики tool: запустіть звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: sweep можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз рекламує** підключений Android node, і перевірити поведінку контракту команди. -- Обсяг: - - Налаштування вручну як передумова (набір не встановлює/не запускає/не pair-ить app). - - Валідація `node.invoke` gateway по командах для вибраного Android node. -- Обов’язкове попереднє налаштування: - - Android app уже підключено й pair-ено з gateway. - - App має залишатися на передньому плані. - - Права/згоду на захоплення надано для можливостей, які ви очікуєте як успішні. -- Необов’язкові overrides цілі: +- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android node, і перевірити поведінку контракту команд. +- Охоплення: + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить застосунок). + - Перевірка `node.invoke` gateway для кожної команди на вибраному Android node. +- Потрібне попереднє налаштування: + - Android-застосунок уже підключений і pair-ений із gateway. + - Застосунок утримується на передньому плані. + - Дозволи/підтвердження захоплення надані для можливостей, які ви очікуєте успішно пройти. +- Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні деталі налаштування Android: [Android App](/uk/platforms/android) +- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke моделей (ключі профілів) +## Live: smoke моделей (profile keys) -Live-тести розділено на два рівні, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. +- «Direct model» показує, чи взагалі провайдер/модель може відповісти з наданим ключем. - «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). -### Рівень 1: Пряме завершення моделі (без gateway) +### Шар 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і точкові регресії там, де потрібно) + - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався сфокусованим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern` для запуску сучасного allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - Як вибирати провайдерів: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity"` (allowlist через кому) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: зі сховища профілів і env fallback-ів - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: profile store і резервні варіанти через env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: replay міркувань OpenAI Responses/Codex Responses + потоки tool-call) + - Відокремлює «API провайдера зламаний / ключ невалідний» від «pipeline gateway agent зламаний» + - Містить малі ізольовані регресії (наприклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) -### Рівень 2: smoke gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/оновити session `agent:dev:*` (override моделі для кожного запуску) - - Перебрати моделі з ключами й перевірити: - - «змістовну» відповідь (без tools) - - що працює реальний виклик інструмента (read probe) - - необов’язкові додаткові probe інструментів (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) і далі працюють -- Деталі probe (щоб можна було швидко пояснити збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` зчитати його назад. - - image probe: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. + - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) + - Пройтися моделями-з-ключами і перевірити: + - «осмислену» відповідь (без tools) + - що працює реальний виклик tool (read probe) + - необов’язкові додаткові tool probes (exec+read probe) + - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють +- Подробиці probes (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить agent виконати `read` цього файла та повернути nonce. + - `exec+read` probe: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` повернути його. + - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити набір -- Як вибирати провайдерів (уникати «усе з OpenRouter»): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,openai,anthropic,zai,minimax"` (allowlist через кому) -- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на tools) - - image probe запускається, коли модель оголошує підтримку image input + - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist + - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити +- Як вибирати провайдерів (уникати «OpenRouter для всього»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) +- Tool + image probes у цьому live-тесті завжди ввімкнені: + - `read` probe + `exec+read` probe (навантаження на tool) + - image probe виконується, коли модель оголошує підтримку image input - Потік (на високому рівні): - - Тест генерує маленький PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Вбудований агент пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (толерантність до OCR: незначні помилки допускаються) + - Embedded agent пересилає multimodal user message до моделі + - Перевірка: відповідь містить `cat` + код (OCR tolerance: дрібні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` +## Live: smoke CLI backend (Codex CLI або інші локальні CLI) + +- Тест: `src/gateway/gateway-cli-backend.live.test.ts` +- Мета: перевірити pipeline Gateway + agent через локальний CLI backend, не торкаючись вашої типової config. +- Увімкнення: + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) + - `OPENCLAW_LIVE_CLI_BACKEND=1` +- Типові значення: + - Модель: `codex-cli/gpt-5.4` + - Команда: `codex` + - Аргументи: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]` +- Перевизначення (необов’язково): + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` + - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` + - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи вставляються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість вставляння в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням аргументів зображення, коли задано `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити resume flow. + +Приклад: + +```bash +OPENCLAW_LIVE_CLI_BACKEND=1 \ + OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \ + pnpm test:live src/gateway/gateway-cli-backend.live.test.ts +``` + +Рецепт для Docker: + +```bash +pnpm test:docker:live-cli-backend +``` + +Примітки: + +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає smoke live CLI-backend усередині Docker-образу репозиторію від непривілейованого користувача `node`. +- Для `codex-cli` він встановлює Linux-пакет `@openai/codex` у кешований префікс із правом запису за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). + ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP-агентом: +- Мета: перевірити реальний conversation-bind flow ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати synthetic розмову message-channel на місці - - надіслати звичайний follow-up у цій самій розмові - - перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії + - прив’язати synthetic conversation каналу повідомлень на місці + - надіслати звичайне follow-up повідомлення в тій самій conversation + - перевірити, що follow-up потрапив у transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP-агент: `claude` - - Synthetic channel: контекст розмови в стилі Slack DM + - ACP agent: `claude` + - Synthetic channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` -- Overrides: +- Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця доріжка використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли приєднати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. + - Ця лінія використовує поверхню `chat.send` gateway з admin-only synthetic полями originating-route, щоб тести могли приєднати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -283,29 +323,29 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker-рецепт: +Рецепт для Docker: ```bash pnpm test:docker:live-acp-bind ``` -Примітки щодо Docker: +Примітки для Docker: - Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Він використовує `~/.profile`, додає відповідні матеріали auth CLI в контейнер, установлює `acpx` у записуваний npm prefix, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env vars провайдера з використаного profile доступними для дочірнього harness CLI. +- Він читає `~/.profile`, підготовлює відповідні CLI auth material у контейнері, встановлює `acpx` у npm-префікс із правом запису, а потім за потреби встановлює запитаний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`). +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав доступність змінних середовища провайдера із завантаженого profile для дочірнього harness CLI. -### Рекомендовані live-рецепти +### Рекомендовані рецепти live-запусків -Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: +Вузькі явні allowlist — найшвидші та найменш нестабільні: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling через кілька провайдерів: +- Виклики tool для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -315,17 +355,21 @@ pnpm test:docker:live-acp-bind Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст Antigravity OAuth (agent endpoint у стилі Cloud Code Assist). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окремі auth та особливості tooling). +- Gemini API проти Gemini CLI: + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (auth через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власний auth і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. +Немає фіксованого «списку моделей CI» (live є opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. -### Сучасний smoke-набір (tool calling + image) +### Сучасний набір smoke (виклик tool + image) -Це запуск «типових моделей», який ми очікуємо підтримувати в робочому стані: +Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: -- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -333,12 +377,12 @@ pnpm test:docker:live-acp-bind - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустити gateway smoke з tools + image: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базовий рівень: виклик tool (Read + необов’язковий Exec) -Виберіть принаймні одну модель з кожного сімейства провайдерів: +Виберіть щонайменше одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -346,75 +390,75 @@ pnpm test:docker:live-acp-bind - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (корисно мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API) -### Vision: надсилання зображення (attachment → мультимодальне повідомлення) +### Vision: надсилання image (вкладення → multimodal message) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб прогнати image probe. -### Aggregators / альтернативні gateway +### Агрегатори / альтернативні gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): -- Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зашивати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ключі, які доступні. +Порада: не намагайтеся жорстко фіксувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth на рівні агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означають «ключі профілів» у live-тестах) +- Профілі auth на agent: `~/.openclaw/agents//agent/auth-profiles.json` (це й означає «profile keys» у live-тестах) - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але це не основне сховище ключів профілів) -- Локальні live-запуски типово копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні CLI auth-каталоги в тимчасовий test home; overrides шляху `agents.*.workspace` / `agentDir` у цьому staged config прибираються, щоб probes не торкалися вашого реального host workspace. +- Директорія legacy state: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутня, але це не основне сховище profile-key) +- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного agent, legacy `credentials/` і підтримувані зовнішні директорії auth CLI у тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються з цієї staged config, щоб probes не працювали у вашому реальному host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або скористайтеся Docker-ранерами нижче (вони можуть монтувати `~/.profile` в контейнер). -## Live Deepgram (аудіотранскрипція) +## Deepgram live (транскрипція аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## BytePlus coding plan live - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live ComfyUI workflow media +## ComfyUI workflow media live - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` +- Охоплення: + - Проганяє вбудовані шляхи comfy для image, video і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації plugin + - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації plugin -## Live генерація зображень +## Live для генерації зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` -- Обсяг: - - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не перекривали реальні shell credentials - - Пропускає провайдерів без придатного auth/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime capability: +- Охоплення: + - Перелічує кожен зареєстрований plugin-провайдер генерації зображень + - Завантажує відсутні provider env vars із вашого login shell (`~/.profile`) перед probes + - Типово використовує live/env API-ключі раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдери без придатного auth/profile/model + - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -427,17 +471,17 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати env-only overrides + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища profiles і ігнорувати перевизначення лише через env -## Live генерація музики +## Live для генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації музики +- Охоплення: + - Проганяє спільний вбудований шлях провайдера генерації музики - Наразі покриває Google і MiniMax - - Завантажує env vars провайдера з вашого login shell (`~/.profile`) перед probe - - Пропускає провайдерів без придатного auth/profile/model + - Завантажує provider env vars із вашого login shell (`~/.profile`) перед probes + - Пропускає провайдери без придатного auth/profile/model - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` @@ -446,179 +490,180 @@ Live-тести знаходять облікові дані так само, я Ці Docker-ранери поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (і використовуючи `~/.profile`, якщо змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live типово використовують менший smoke-ліміт, щоб повний Docker-sweep залишався практичним: +- Ранери для live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний config dir і workspace (а також читають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker-ранери для live-запусків типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, + `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначте ці env vars, коли - вам навмисно потрібне більший вичерпний scan. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-доріжок live. -- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли + вам явно потрібне ширше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Ранери Docker для live-моделей також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без змін у host auth store: +Docker-ранери для live-моделей також bind-mount лише потрібні домівки auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашню директорію контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи auth store на хості: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) - Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Міст каналу MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke інсталяції + псевдонім `/plugin` + семантика restart для бандла Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Ранери Docker для live-моделей також bind-mount-ять поточний checkout лише для читання і -стейджать його у тимчасовий workdir усередині контейнера. Це зберігає runtime -образ компактним, але водночас дає запускати Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні кеші та build-артефакти app, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. +Docker-ранери для live-моделей також монтують поточний checkout лише для читання і +розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime +image компактним і водночас дає змогу запускати Vitest точно по вашому локальному source/config. +Під час підготовки пропускаються великі локальні кеші й артефакти збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні директорії виводу `.build` або +Gradle, тож Docker live-запуски не витрачають хвилини на копіювання +машинно-специфічних артефактів. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали реальні воркери каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway -live із цієї Docker-доріжки. +`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway +live-покриття з цієї Docker-лінії. `test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, +контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat request через proxy `/api/chat/completions` в Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути -образ Open WebUI, а Open WebUI може потребувати завершити власне cold-start налаштування. -Ця доріжка очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його у Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat request через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити +образ Open WebUI, а самому Open WebUI — завершити холодний старт. +Для цієї лінії потрібен придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON-пейлоад на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального акаунта Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway, -стартує другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень, -поведінку live event queue, маршрутизацію outbound send, а також сповіщення про канал + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -напряму аналізує сирі stdio MCP frames, тож smoke перевіряє те, що -міст справді випромінює, а не лише те, що випадково показує певний client SDK. +реального облікового запису Telegram, Discord чи iMessage. Він піднімає seeded Gateway +контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення conversation через routing, читання transcript, metadata вкладень, +поведінку live event queue, routing вихідного надсилання і channel- та +permission-сповіщення в стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +інспектує raw stdio MCP frames напряму, тож smoke перевіряє саме те, що +міст реально випромінює, а не лише те, що вміє показати конкретний клієнтський SDK. -Ручний smoke plain-language thread ACP (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Залишайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки routing ACP thread, тому не видаляйте його. Корисні env vars: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker -- Зовнішні CLI auth-каталоги/файли в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - - Типові каталоги: `.minimax` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker +- Зовнішні auth dirs/files CLI у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів + - Типові директорії: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Звужені запуски провайдерів монтують лише потрібні директорії/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища profiles (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, який використовується для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt з перевіркою nonce, який використовує smoke Open WebUI - `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки docs після редагування документації: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли потрібні також перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки документації: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків на сторінці: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Tool calling gateway (mock OpenAI, реальний gateway + agent loop): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway wizard (WS `wizard.start`/`wizard.next`, записує config + примусове auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик tools gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусовий auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агентів (Skills) +## Оцінювання надійності agent (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: -- Mock tool-calling через реальний gateway + agent loop (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють wiring сесій і вплив config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні wizard flows, що перевіряють wiring session і ефекти config (`src/gateway/gateway.test.ts`). Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти робочого процесу:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? +- **Compliance:** чи читає agent `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Workflow contracts:** багатокрокові сценарії, що перевіряють порядок tool, перенесення history session і межі sandbox. -Майбутні evals мають передусім залишатися детермінованими: +Майбутні evals спершу мають залишатися детермінованими: -- Раннер сценаріїв, що використовує mock-провайдери для перевірки викликів tools + порядку, читання skill-файлів і wiring сесій. +- Сценарний runner з mock-провайдерами для перевірки викликів tool + порядку, читання skill-файлів і wiring session. - Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live evals (opt-in, env-gated) — лише після того, як буде готовий безпечний для CI набір. +- Необов’язкові live evals (opt-in, із керуванням через env) лише після того, як безпечний для CI набір буде на місці. -## Контрактні тести (форма plugin і channel) +## Contract tests (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-доріжка `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо, +Contract tests перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму interface contract. Вони проходять по всіх знайдених plugins і запускають набір +перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте команди contract явно, коли торкаєтеся спільних поверхонь channel або provider. ### Команди -- Усі контракти: `pnpm test:contracts` -- Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Усі contracts: `pnpm test:contracts` +- Лише contracts channel: `pnpm test:contracts:channels` +- Лише contracts provider: `pnpm test:contracts:plugins` -### Контракти channel +### Contracts channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **setup** - Contract майстра setup +- **session-binding** - Поведінка прив’язування session - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка thread ID -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групових політик +- **directory** - API directory/roster +- **group-policy** - Застосування group policy -### Контракти статусу provider +### Contracts status провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe-и статусу channel -- **registry** - Форма реєстру plugin +- **status** - Status probes каналу +- **registry** - Форма registry plugin -### Контракти provider +### Contracts provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth +- **auth** - Contract потоку auth - **auth-choice** - Вибір/selection auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin - **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер налаштування +- **shape** - Форма/interface plugin +- **wizard** - Майстер setup ### Коли запускати -- Після зміни exports або subpath-ів plugin-sdk +- Після зміни exports або subpaths у plugin-sdk - Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації plugin або discovery +- Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI й не потребують реальних API-ключів. +Contract tests запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додавайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо це за своєю природою лише live-випадок (rate limits, політики auth), тримайте live-тест вузьким і opt-in через env vars -- Намагайтеся націлюватися на найменший рівень, який ловить баг: - - баг конвертації/replay запиту провайдера → тест direct models +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або захоплення точної трансформації форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Намагайтеся націлюватися на найменший шар, який виявляє баг: + - баг перетворення/повторення запиту провайдера → direct models test - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test -- Захисна умова обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній sampled target для кожного класу SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. +- Захисне правило обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибраній цілі на клас SecretRef з metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 8c64f4fbb..1047abc36 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -3,31 +3,31 @@ read_when: - Створення або налагодження нативних плагінів OpenClaw - Розуміння моделі можливостей плагінів або меж володіння - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація хуків runtime для провайдерів або плагінів каналів + - Реалізація хуків часу виконання постачальника або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішня будова плагінів: модель можливостей, межі володіння, контракти, конвеєр завантаження та допоміжні засоби runtime' -title: Внутрішня будова плагінів +summary: 'Внутрішні механізми плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' +title: Внутрішні механізми плагінів x-i18n: - generated_at: "2026-04-06T12:35:52Z" + generated_at: "2026-04-06T12:47:19Z" model: gpt-5.4 provider: openai - source_hash: 44f8354fffab48f31dacc6b1c0e57ef35710d3312d8f79c0d56ae7e2a4530e8f + source_hash: b2f7f48bd5599b9897aa851fb25d501d9643d76f66084f5867b3866fec91cef6 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішня будова плагінів +# Внутрішні механізми плагінів - Це **довідник із поглибленої архітектури**. Практичні посібники див. тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача - - [Початок роботи](/uk/plugins/building-plugins) — перший посібник зі створення плагіна + Це **довідник з глибокої архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей + - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації -На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. +Ця сторінка охоплює внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей @@ -37,147 +37,150 @@ x-i18n: | Можливість | Метод реєстрації | Приклади плагінів | | --------------------- | ----------------------------------------------- | ------------------------------------ | | Текстовий висновок | `api.registerProvider(...)` | `openai`, `anthropic` | +| Бекенд висновку CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | | Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | | Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | | Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | | Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | | Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -Плагін, який реєструє нуль можливостей, але надає hooks, tools або -services, є **застарілим hook-only** плагіном. Такий шаблон усе ще повністю підтримується. +Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або +служби, є **застарілим плагіном лише з хуками**. Цей шаблон і далі повністю підтримується. ### Позиція щодо зовнішньої сумісності -Модель можливостей уже реалізована в core і використовується в bundled/native plugins -сьогодні, але сумісність зовнішніх плагінів усе ще потребує вищої планки, ніж -«це експортується, отже це заморожено». +Модель можливостей уже інтегрована в ядро та сьогодні використовується +вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще +потребує вищої планки, ніж «це експортується, отже це заморожено». Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі hooks; розглядайте +- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; розглядайте це як базовий рівень сумісності -- **нові bundled/native plugins:** надавайте перевагу явній реєстрації можливостей замість - vendor-specific доступу напряму або нових hook-only дизайнів -- **зовнішні плагіни, що переходять на реєстрацію можливостей:** дозволено, але розглядайте - допоміжні поверхні, специфічні для можливостей, як такі, що розвиваються, якщо в документації контракт не позначено як стабільний +- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей, а не + vendor-специфічним зверненням усередину чи новим схемам лише з хуками +- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але розглядайте + допоміжні поверхні, специфічні для можливостей, як такі, що еволюціонують, якщо документація + явно не позначає контракт як стабільний Практичне правило: -- API реєстрації можливостей — це цільовий напрямок -- legacy hooks лишаються найбезпечнішим шляхом без поломок для зовнішніх плагінів під час +- API реєстрації можливостей — це бажаний напрямок +- застарілі хуки залишаються найбезпечнішим шляхом без ламання для зовнішніх плагінів під час переходу -- не всі експортовані helper subpaths однакові; надавайте перевагу вузькому документованому - контракту, а не випадковим допоміжним експортам +- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому документованому + контракту, а не випадковим експортам допоміжних засобів ### Форми плагінів OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки під час реєстрації (а не лише статичних метаданих): +поведінки під час реєстрації, а не лише статичних метаданих: -- **plain-capability** -- реєструє рівно один тип можливості (наприклад, - плагін лише провайдера, як-от `mistral`) -- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, +- **plain-capability** — реєструє рівно один тип можливості (наприклад, + плагін лише постачальника, як-от `mistral`) +- **hybrid-capability** — реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим висновком, мовленням, розумінням медіа та генерацією зображень) -- **hook-only** -- реєструє лише hooks (типізовані або custom), без можливостей, - tools, commands або services -- **non-capability** -- реєструє tools, commands, services або routes, але не можливості +- **hook-only** — реєструє лише хуки (типізовані або користувацькі), без можливостей, + інструментів, команд чи служб +- **non-capability** — реєструє інструменти, команди, служби або маршрути, але без + можливостей -Використайте `openclaw plugins inspect `, щоб побачити форму плагіна та -розподіл його можливостей. Докладніше див. у [довідці CLI](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та розклад +його можливостей. Подробиці дивіться в [довіднику CLI](/cli/plugins#inspect). -### Legacy hooks +### Застарілі хуки -Хук `before_agent_start` лишається підтримуваним як шлях сумісності для -hook-only плагінів. Реальні legacy-плагіни все ще від нього залежать. +Хук `before_agent_start` залишається підтримуваним як шлях сумісності для +плагінів лише з хуками. Застарілі реальні плагіни все ще залежать від нього. Напрямок: - зберігати його працездатність - документувати його як застарілий -- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve` -- для мутації prompt надавати перевагу `before_prompt_build` -- видаляти лише після зниження реального використання і після того, як покриття fixture підтвердить безпечність міграції +- для роботи з перевизначенням моделі/постачальника віддавати перевагу `before_model_resolve` +- для змінення prompt віддавати перевагу `before_prompt_build` +- видаляти лише після зниження реального використання та коли покриття фікстурами підтвердить безпеку міграції ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити одну з таких позначок: -| Сигнал | Значення | -| -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація коректно парситься, а плагіни успішно резолвляться | +| Сигнал | Значення | +| ------------------------ | ------------------------------------------------------------ | +| **config valid** | Конфігурація успішно розбирається, а плагіни успішно визначаються | | **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | +| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | +| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | -Ні `hook-only`, ні `before_agent_start` не зламають ваш плагін сьогодні -- +Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш плагін — `hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці -сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. +сигнали також відображаються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить кандидатів у плагіни за налаштованими шляхами, коренями workspace, - глобальними коренями розширень і bundled extensions. Під час виявлення спочатку читаються нативні - маніфести `openclaw.plugin.json` та підтримувані bundle manifests. + OpenClaw знаходить кандидатів у плагіни в налаштованих шляхах, коренях workspace, + глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json`, а також підтримувані маніфести пакетів. 2. **Увімкнення + валідація** - Core вирішує, чи виявлений плагін увімкнений, вимкнений, заблокований або - вибраний для ексклюзивного слота, наприклад memory. -3. **Завантаження runtime** - Нативні плагіни OpenClaw завантажуються в поточний процес через jiti і реєструють - можливості в центральному реєстрі. Сумісні bundles нормалізуються в - записи реєстру без імпорту коду runtime. -4. **Споживання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати tools, channels, налаштування provider, - hooks, HTTP routes, CLI commands і services. + Ядро вирішує, чи знайдений плагін увімкнений, вимкнений, заблокований або + вибраний для ексклюзивного слота, наприклад пам’яті. +3. **Завантаження часу виконання** + Нативні плагіни OpenClaw завантажуються в межах процесу через jiti і реєструють + можливості в центральному реєстрі. Сумісні пакети нормалізуються в записи + реєстру без імпорту коду часу виконання. +4. **Споживання поверхні** + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування постачальників, + хуки, HTTP-маршрути, команди CLI та служби. -Зокрема для CLI плагінів виявлення кореневих команд поділено на дві фази: +Зокрема для CLI плагінів, виявлення кореневих команд поділено на дві фази: -- метадані часу парсингу надходять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI плагіна може лишатися lazy і реєструватися під час першого виклику +- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI плагіна може залишатися лінивим і реєструватися при першому виклику -Це дозволяє зберігати код CLI, що належить плагіну, всередині плагіна, водночас даючи OpenClaw -змогу резервувати імена кореневих команд до парсингу. +Це дає змогу зберігати код CLI, що належить плагіну, всередині плагіна, водночас дозволяючи OpenClaw +резервувати імена кореневих команд до розбору. Важлива межа дизайну: - виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** без виконання коду плагіна -- нативна поведінка runtime походить із шляху модуля плагіна `register(api)` +- нативна поведінка часу виконання походить із шляху `register(api)` модуля плагіна -Цей поділ дає OpenClaw змогу валідувати конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки UI/схем до повної активації runtime. +Це розділення дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки для UI/схеми до того, як повноцінний час виконання стане активним. -### Плагіни каналів і спільний tool повідомлень +### Плагіни каналів і спільний інструмент повідомлень -Плагінам каналів не потрібно реєструвати окремий tool для send/edit/react для -звичайних дій чату. OpenClaw зберігає один спільний `message` tool у core, а +Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для +звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у ядрі, а плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. Поточна межа така: -- core володіє спільним хостом `message` tool, підключенням prompt, обліком сесій/гілок - і диспетчеризацією виконання -- плагіни каналів володіють scoped виявленням дій, виявленням можливостей і будь-якими - фрагментами схем, специфічними для каналу -- плагіни каналів володіють граматикою розмови сесії, специфічною для провайдера, зокрема - тим, як id розмов кодують id гілок або успадковуються від батьківських розмов -- плагіни каналів виконують фінальну дію через свій action adapter +- ядро володіє хостом спільного інструмента `message`, wiring для prompt, веденням + обліку сесій/гілок та диспетчеризацією виконання +- плагіни каналів володіють виявленням дій в обмеженому контексті, виявленням можливостей і будь-якими + фрагментами схеми, специфічними для каналу +- плагіни каналів володіють граматикою розмов для сесій, специфічною для постачальника, наприклад тим, + як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов +- плагіни каналів виконують фінальну дію через свій адаптер дій -Для плагінів каналів поверхня SDK — +Для плагінів каналів поверхня SDK — це `ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну повертати видимі дії, можливості й внески до схеми +дозволяє плагіну повернути видимі дії, можливості та внески до схеми разом, щоб ці частини не розходилися. -Core передає scope runtime у цей крок виявлення. Важливі поля: +Ядро передає область часу виконання в цей крок виявлення. Важливі поля: - `accountId` - `currentChannelId` @@ -188,123 +191,122 @@ Core передає scope runtime у цей крок виявлення. Важ - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для context-sensitive плагінів. Канал може приховувати або показувати -message actions залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або -довіреної особи запитувача без жорстко закладених гілок, специфічних для каналу, у -core `message` tool. +Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати +дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або +довіреної ідентичності запитувача, не хардкодячи специфічні для каналу гілки в +базовий інструмент `message`. -Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner -відповідає за пересилання поточної ідентичності чату/сесії в межу -виявлення плагіна, щоб спільний `message` tool показував правильну поверхню, -якою володіє канал, для поточного ходу. +Саме тому зміни маршрутизації embedded-runner і далі залишаються роботою плагіна: runner +відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб спільний +інструмент `message` відкривав правильну поверхню, що належить каналу, для поточного ходу. -Для допоміжних засобів виконання, що належать каналу, bundled plugins мають тримати runtime -виконання у своїх власних модулях розширень. Core більше не володіє runtime -message-action для Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі subpaths `plugin-sdk/*-action-runtime`, і bundled -plugins мають імпортувати власний локальний код runtime напряму зі своїх -модулів розширень. +Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати середовище +виконання всередині власних модулів розширення. Ядро більше не володіє середовищами +виконання дій повідомлень Discord, Slack, Telegram або WhatsApp під `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані +плагіни мають імпортувати власний локальний код часу виконання безпосередньо зі своїх +модулів, що належать розширенню. -Та сама межа застосовується до іменованих поверхонь SDK провайдерів загалом: -core не повинен імпортувати зручні barrel-файли, специфічні для каналів Slack, Discord, Signal, -WhatsApp чи подібних розширень. Якщо core потрібна певна поведінка, або використайте -власний barrel bundled plugin `api.ts` / `runtime-api.ts`, або підніміть цю потребу -до вузької загальної можливості у спільному SDK. +Та сама межа застосовується й до іменованих за постачальниками швів SDK загалом: ядро не має +імпортувати зручні барелі, специфічні для каналів Slack, Discord, Signal, +WhatsApp чи подібних розширень. Якщо ядру потрібна певна поведінка, воно має або +використовувати власний барель `api.ts` / `runtime-api.ts` вбудованого плагіна, або +підняти потребу до вузької загальної можливості в спільному SDK. -Зокрема для опитувань є два шляхи виконання: +Зокрема для опитувань існує два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, що відповідають спільній - моделі опитувань -- `actions.handleAction("poll")` — бажаний шлях для семантики опитувань, специфічної для каналу, - або додаткових параметрів опитування +- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну + модель опитування +- `actions.handleAction("poll")` — бажаний шлях для специфічної для каналу + семантики опитувань або додаткових параметрів опитування -Core тепер відкладає спільний розбір опитувань до того, як диспетчеризація опитування плагіна відхилить -дію, тому обробники опитувань, що належать плагіну, можуть приймати поля опитувань, специфічні для каналу, -і generic parser опитувань не блокуватиме їх раніше. +Тепер ядро відкладає спільний розбір опитування до моменту, коли dispatch +опитування плагіна відхиляє дію, щоб обробники опитувань, що належать плагіну, могли приймати +специфічні для каналу поля опитування, не блокуючись спершу загальним парсером опитувань. -Повну послідовність запуску див. у розділі [Конвеєр завантаження](#load-pipeline). +Повну послідовність запуску дивіться в [Конвеєр завантаження](#load-pipeline). ## Модель володіння можливостями OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір розрізнених інтеграцій. +**функції**, а не як набір не пов’язаних інтеграцій. Це означає: - плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії - плагін функції зазвичай має володіти всією поверхнею функції, яку він додає -- канали мають споживати спільні можливості core, а не довільно перевпроваджувати - поведінку провайдерів +- канали мають споживати спільні можливості ядра замість того, щоб довільно повторно реалізовувати + поведінку постачальника Приклади: -- bundled plugin `openai` володіє поведінкою провайдера моделей OpenAI і поведінкою OpenAI - для speech + realtime-voice + media-understanding + image-generation -- bundled plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs -- bundled plugin `microsoft` володіє поведінкою мовлення Microsoft -- bundled plugin `google` володіє поведінкою провайдера моделей Google плюс поведінкою Google - для media-understanding + image-generation + web-search -- bundled plugin `firecrawl` володіє поведінкою web-fetch Firecrawl -- bundled plugins `minimax`, `mistral`, `moonshot` і `zai` володіють своїми - backend-ами media-understanding -- bundled plugin `qwen` володіє поведінкою текстового провайдера Qwen плюс - media-understanding і video-generation -- плагін `voice-call` — це плагін функції: він володіє транспортом дзвінків, tools, - CLI, routes і мостом Twilio media-stream, але споживає спільні можливості speech - плюс realtime-transcription і realtime-voice замість прямого імпорту vendor plugins +- вбудований плагін `openai` володіє поведінкою постачальника моделей OpenAI та поведінкою OpenAI + для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs +- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft +- вбудований плагін `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google для + розуміння медіа + генерації зображень + вебпошуку +- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для отримання вебданих +- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми + бекендами розуміння медіа +- вбудований плагін `qwen` володіє поведінкою текстового постачальника Qwen, а також + поведінкою розуміння медіа і генерації відео +- плагін `voice-call` є плагіном функції: він володіє транспортом дзвінків, інструментами, + CLI, маршрутами й мостом медіапотоку Twilio, але споживає спільні можливості мовлення, + а також транскрипції та голосу в реальному часі замість прямого імпорту vendor-плагінів Бажаний кінцевий стан: -- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та +- OpenAI знаходиться в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший вендор може зробити те саме для своєї власної поверхні -- каналам не важливо, який плагін вендора володіє провайдером; вони споживають - спільний контракт можливості, який надає core +- інший вендор може робити те саме для власної області +- канали не мають перейматися тим, який vendor-плагін володіє постачальником; вони споживають + спільний контракт можливості, що відкривається ядром Ось ключова відмінність: - **plugin** = межа володіння -- **capability** = контракт core, який кілька плагінів можуть реалізовувати або споживати +- **capability** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів -Тож якщо OpenClaw додає нову предметну область, як-от відео, перше питання не -«який провайдер має жорстко закодувати обробку відео?» Перше питання — «яким є -контракт основної можливості відео?» Щойно цей контракт існує, vendor plugins -можуть реєструватися для нього, а channel/feature plugins можуть його споживати. +Тому якщо OpenClaw додає нову сферу, наприклад відео, перше питання не +«який постачальник має хардкодити обробку відео?» Перше питання — «який +контракт можливості відео в ядрі?» Щойно такий контракт з’явиться, vendor-плагіни +зможуть реєструватися для нього, а плагіни каналів/функцій зможуть його споживати. -Якщо можливість ще не існує, правильний крок зазвичай такий: +Якщо можливості ще не існує, правильний крок зазвичай такий: -1. визначити відсутню можливість у core -2. відкрити її через API/runtime плагіна у типізований спосіб -3. підключити канали/функції до цієї можливості -4. дозволити vendor plugins реєструвати реалізації +1. визначити відсутню можливість у ядрі +2. відкрити її через API/час виконання плагіна у типізований спосіб +3. прив’язати канали/функції до цієї можливості +4. дозволити vendor-плагінам реєструвати реалізації -Так володіння лишається явним і водночас уникається поведінка core, яка залежить від +Це зберігає явне володіння й водночас уникає поведінки ядра, що залежить від одного вендора або одноразового шляху коду, специфічного для плагіна. ### Шарування можливостей -Користуйтеся цією ментальною моделлю, коли вирішуєте, де має бути код: +Використовуйте цю ментальну модель, коли вирішуєте, де має належати код: -- **шар можливостей core**: спільна оркестрація, політика, fallback, правила +- **шар можливостей ядра**: спільна оркестрація, політики, fallback, правила злиття конфігурації, семантика доставки та типізовані контракти -- **шар vendor plugin**: API, auth, каталоги моделей, синтез мовлення, - генерація зображень, майбутні backend-и відео, ендпоїнти використання -- **шар channel/feature plugin**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості core і показує їх на своїй поверхні +- **шар vendor-плагіна**: vendor-специфічні API, auth, каталоги моделей, синтез мовлення, + генерація зображень, майбутні відеобекенди, endpoints використання +- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, + яка споживає можливості ядра та подає їх на поверхню Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канал +- ядро володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канали - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає helper runtime TTS для телефонії +- `voice-call` споживає допоміжний засіб часу виконання TTS для телефонії -Такому ж шаблону слід надавати перевагу і для майбутніх можливостей. +Той самий шаблон слід вважати бажаним і для майбутніх можливостей. -### Приклад плагіна компанії з кількома можливостями +### Приклад багатоможливісного плагіна компанії -Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні +Ззовні плагін компанії має виглядати цілісно. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, web fetch і web search, +генерації зображень, генерації відео, отримання вебданих і вебпошуку, вендор може володіти всіма своїми поверхнями в одному місці: ```ts @@ -359,12 +361,12 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви helpers. Важлива форма: +Важливі не точні назви допоміжних функцій. Важлива форма: - один плагін володіє поверхнею вендора -- core усе ще володіє контрактами можливостей -- канали та плагіни функцій споживають helpers `api.runtime.*`, а не код вендора -- contract tests можуть перевіряти, що плагін зареєстрував можливості, якими +- ядро все ще володіє контрактами можливостей +- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора +- контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими він заявляє, що володіє ### Приклад можливості: розуміння відео @@ -372,206 +374,206 @@ export default plugin; OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується і тут: -1. core визначає контракт media-understanding -2. vendor plugins реєструють `describeImage`, `transcribeAudio` і - `describeVideo`, де це доречно -3. канали та плагіни функцій споживають спільну поведінку core замість - прямого підключення до коду вендора +1. ядро визначає контракт розуміння медіа +2. vendor-плагіни реєструють `describeImage`, `transcribeAudio` і + `describeVideo`, де це застосовно +3. канали та плагіни функцій споживають спільну поведінку ядра замість + прямого прив’язування до коду вендора -Це не дозволяє закласти припущення одного провайдера щодо відео в core. Плагін володіє -поверхнею вендора; core володіє контрактом можливості та поведінкою fallback. +Це не дає вбудовувати в ядро припущення одного постачальника щодо відео. Плагін володіє +поверхнею вендора; ядро володіє контрактом можливості та поведінкою fallback. -Генерація відео вже використовує таку саму послідовність: core володіє типізованим -контрактом можливості та helper runtime, а vendor plugins реєструють -реалізації `api.registerVideoGenerationProvider(...)` для нього. +Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим +контрактом можливості та допоміжним засобом часу виконання, а vendor-плагіни +реєструють реалізації `api.registerVideoGenerationProvider(...)` для неї. -Потрібен конкретний чекліст розгортання? Див. -[Capability Cookbook](/uk/plugins/architecture). +Потрібен конкретний чекліст розгортання? Дивіться +[Посібник з можливостей](/uk/plugins/architecture). -## Контракти та примусове дотримання +## Контракти та контроль -Поверхня API плагінів навмисно типізована і централізована в +Поверхня API плагінів навмисно типізована та централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -helpers runtime, на які може покладатися плагін. +допоміжні засоби часу виконання, на які плагін може покладатися. Чому це важливо: - автори плагінів отримують один стабільний внутрішній стандарт -- core може відхилити дубльоване володіння, наприклад коли два плагіни реєструють один і той самий - id провайдера -- під час запуску можна показати діагностику для некоректної реєстрації, придатну до дії -- contract tests можуть примусово контролювати володіння bundled-plugin і запобігати тихому дрейфу +- ядро може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють однаковий id постачальника +- під час запуску можна показувати придатну для дії діагностику для некоректної реєстрації +- контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати непомітному дрейфу -Є два шари примусового контролю: +Є два шари контролю: -1. **контроль під час реєстрації в runtime** - Реєстр плагінів валідує реєстрації під час завантаження плагінів. Приклади: - дублікати id провайдерів, дублікати id speech-провайдерів і некоректні +1. **контроль реєстрації під час виконання** + Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: + дубльовані id постачальників, дубльовані id постачальників мовлення та некоректні реєстрації породжують діагностику плагіна замість невизначеної поведінки. -2. **contract tests** - Bundled plugins фіксуються в contract registries під час тестових запусків, щоб - OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для model - providers, speech providers, web search providers і володіння реєстрацією bundled. +2. **контрактні тести** + Вбудовані плагіни фіксуються в контрактних реєстрах під час тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для + постачальників моделей, постачальників мовлення, постачальників вебпошуку та володіння + реєстраціями вбудованих плагінів. -Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін володіє якою -поверхнею. Це дозволяє core і каналам безшовно поєднуватися, оскільки володіння -заявлене, типізоване й тестоване, а не неявне. +Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою +поверхнею володіє. Це дозволяє ядру та каналам безшовно поєднуватися, бо +володіння оголошене, типізоване та тестоване, а не неявне. -### Що має входити в контракт +### Що має входити до контракту Хороші контракти плагінів: - типізовані -- невеликі -- специфічні до можливості -- належать core -- багаторазово використовуються кількома плагінами -- можуть споживатися каналами/функціями без знання про вендора +- малі +- специфічні для можливості +- належать ядру +- придатні для повторного використання кількома плагінами +- споживані каналами/функціями без знання про вендора Погані контракти плагінів: -- політика, специфічна для вендора, прихована в core -- одноразові обхідні шляхи для плагінів, що обходять реєстр -- код каналу, що напряму звертається до реалізації вендора -- довільні runtime-об’єкти, які не входять до `OpenClawPluginApi` або +- vendor-специфічна політика, прихована в ядрі +- одноразові обхідні шляхи для плагінів, які оминають реєстр +- код каналу, який напряму звертається до реалізації вендора +- довільні об’єкти часу виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім -дозвольте плагінам у неї підключатися. +дозвольте плагінам підключатися до неї. ## Модель виконання -Нативні плагіни OpenClaw працюють **у поточному процесі** разом із Gateway. Вони не +Нативні плагіни OpenClaw працюють **усередині процесу** разом із Gateway. Вони не ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й -код core. +код ядра. Наслідки: -- нативний плагін може реєструвати tools, network handlers, hooks і services -- помилка нативного плагіна може призвести до збою gateway або його дестабілізації +- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та служби +- помилка в нативному плагіні може призвести до збою або дестабілізації gateway - зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні bundles безпечніші за замовчуванням, тому що OpenClaw наразі розглядає їх -як пакети метаданих/контенту. У поточних випусках це переважно означає bundled -skills. +Сумісні пакети безпечніші за замовчуванням, оскільки наразі OpenClaw розглядає їх +як пакети метаданих/контенту. У поточних випусках це переважно означає +вбудовані Skills. -Використовуйте allowlists і явні шляхи встановлення/завантаження для небандлених плагінів. Розглядайте -workspace plugins як код часу розробки, а не як виробничі значення за замовчуванням. +Для не вбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте +workspace-плагіни як код для етапу розробки, а не як виробниче значення за замовчуванням. -Для назв пакетів bundled workspace тримайте id плагіна прив’язаним до npm-імені: -`@openclaw/` за замовчуванням або затверджений типізований суфікс, як-от +Для назв пакетів у вбудованому workspace зберігайте id плагіна прив’язаним до npm-імені: +`@openclaw/` за замовчуванням, або затверджений типізований суфікс, такий як `-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли -пакет навмисно надає вужчу роль плагіна. +пакет навмисно відкриває вужчу роль плагіна. Важлива примітка щодо довіри: - `plugins.allow` довіряє **id плагінів**, а не походженню джерела. -- Workspace plugin з тим самим id, що й bundled plugin, навмисно затіняє - bundled-копію, коли такий workspace plugin увімкнено/внесено до allowlist. -- Це нормально й корисно для локальної розробки, тестування патчів і hotfixes. +- Workspace-плагін із тим самим id, що й вбудований плагін, навмисно затіняє + вбудовану копію, коли такий workspace-плагін увімкнено/додано до allowlist. +- Це нормально й корисно для локальної розробки, тестування патчів і хотфіксів. ## Межа експорту -OpenClaw експортує можливості, а не зручні для реалізації допоміжні засоби. +OpenClaw експортує можливості, а не зручні реалізації. -Зберігайте публічною реєстрацію можливостей. Скорочуйте helper-експорти, що не є контрактом: +Зберігайте реєстрацію можливостей публічною. Обрізайте експорти допоміжних засобів, які не є контрактами: -- helper subpaths, специфічні для bundled-plugin -- runtime plumbing subpaths, не призначені як публічний API -- зручні helpers, специфічні для вендора -- helpers налаштування/onboarding, які є деталями реалізації +- підшляхи допоміжних засобів, специфічних для вбудованих плагінів +- підшляхи plumbing часу виконання, не призначені як публічний API +- vendor-специфічні зручні допоміжні засоби +- допоміжні засоби setup/onboarding, які є деталями реалізації -Деякі helper subpaths bundled-plugin усе ще присутні у згенерованій карті експорту SDK -заради сумісності та підтримки bundled-plugin. Поточні приклади: -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в +згенерованій карті експортів SDK задля сумісності та підтримки вбудованих плагінів. +Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані детальні експорти реалізації, а не як рекомендований шаблон SDK для +зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх плагінів. ## Конвеєр завантаження Під час запуску OpenClaw приблизно робить таке: -1. виявляє корені плагінів-кандидатів -2. читає native або compatible bundle manifests і метадані пакетів +1. виявляє корені кандидатів у плагіни +2. читає нативні або сумісні маніфести пакетів і метадані пакетів 3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. вирішує, чи вмикати кожного кандидата -6. завантажує увімкнені native modules через jiti -7. викликає native hooks `register(api)` (або `activate(api)` — legacy alias) і збирає реєстрації до реєстру плагінів -8. відкриває реєстр для surfaces команд/runtime +5. визначає стан увімкнення для кожного кандидата +6. завантажує увімкнені нативні модулі через jiti +7. викликає хуки нативних `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів +8. відкриває реєстр для команд/поверхонь часу виконання -`activate` — це legacy alias для `register` — loader резолвить те, що присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі bundled plugins використовують `register`; для нових плагінів надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються, -якщо entry виходить за межі кореня плагіна, шлях доступний на запис усім, або -володіння шляхом виглядає підозріло для небандлених плагінів. +Перевірки безпеки відбуваються **до** виконання часу виконання. Кандидати блокуються, +коли entrypoint виходить за межі кореня плагіна, шлях є доступним для запису всім, або +володіння шляхом виглядає підозріло для не вбудованих плагінів. ### Поведінка «спочатку маніфест» Маніфест — це джерело істини control-plane. OpenClaw використовує його, щоб: - ідентифікувати плагін -- виявляти оголошені channels/skills/config schema або можливості bundle -- валідувати `plugins.entries..config` -- доповнювати labels/placeholders у Control UI +- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- перевіряти `plugins.entries..config` +- доповнювати мітки/плейсхолдери Control UI - показувати метадані встановлення/каталогу -Для нативних плагінів модуль runtime — це частина data-plane. Він реєструє -фактичну поведінку, як-от hooks, tools, commands або потоки provider. +Для нативних плагінів модуль часу виконання є частиною data-plane. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки постачальників. -### Що кешує loader +### Що кешує завантажувач -OpenClaw зберігає короткочасні кеші в поточному процесі для: +OpenClaw зберігає короткі внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- реєстрів завантажених плагінів +- завантажених реєстрів плагінів -Ці кеші зменшують навантаження від ривкового запуску та повторних команд. Їх безпечно -сприймати як короткоживучі кеші продуктивності, а не як збереження стану. +Ці кеші зменшують стрибкоподібні витрати запуску та повторних команд. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як постійне сховище. Примітка щодо продуктивності: - Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштовуйте вікна кешування через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені плагіни не змінюють напряму довільні глобальні об’єкти core. Вони +Завантажені плагіни не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в центральному реєстрі плагінів. Реєстр відстежує: -- записи плагінів (ідентичність, джерело, походження, статус, діагностика) -- tools -- legacy hooks і типізовані hooks -- channels -- providers -- обробники Gateway RPC -- HTTP routes +- записи плагінів (ідентичність, джерело, походження, стан, діагностика) +- інструменти +- застарілі хуки й типізовані хуки +- канали +- постачальників +- обробники gateway RPC +- HTTP-маршрути - реєстратори CLI -- фонові services -- commands, що належать плагінам +- фонові служби +- команди, що належать плагінам -Потім функції core читають із цього реєстру замість прямого звернення до модулів плагінів. +Потім функції ядра читають із цього реєстру, а не звертаються безпосередньо до модулів плагінів. Це зберігає односторонність завантаження: - модуль плагіна -> реєстрація в реєстрі -- runtime core -> споживання реєстру +- час виконання ядра -> споживання реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: «прочитати реєстр», а не «додати спецобробку для кожного модуля плагіна». +Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна +лише одна точка інтеграції: «читати реєстр», а не «додавати окремі випадки для кожного модуля плагіна». -## Колбеки прив’язки розмови +## Колбеки прив’язки розмов -Плагіни, що прив’язують розмову, можуть реагувати, коли схвалення вирішено. +Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на прив’язку схвалено або відхилено: @@ -598,22 +600,22 @@ export default { - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: резолвлена прив’язка для схвалених запитів +- `binding`: визначена прив’язка для схвалених запитів - `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей callback призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати -розмову, і виконується після завершення обробки схвалення в core. +Цей callback призначений лише для сповіщення. Він не змінює того, хто має право +прив’язувати розмову, і виконується після завершення обробки схвалення ядром. -## Хуки runtime провайдера +## Хуки часу виконання постачальника -Плагіни провайдерів тепер мають два шари: +Тепер плагіни постачальників мають два шари: - метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до - завантаження runtime, плюс `providerAuthChoices` для дешевих labels onboarding/auth-choice - і метаданих прапорців CLI до завантаження runtime -- hooks часу конфігурації: `catalog` / legacy `discovery` плюс `applyConfigDefaults` -- hooks runtime: `normalizeModelId`, `normalizeTransport`, + завантаження часу виконання, а також `providerAuthChoices` для дешевих міток onboarding/auth-choice + і метаданих прапорців CLI до завантаження часу виконання +- хуки часу конфігурації: `catalog` / застарілий `discovery`, а також `applyConfigDefaults` +- хуки часу виконання: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalOAuthProfiles`, @@ -633,84 +635,84 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw як і раніше володіє загальним циклом агента, failover, обробкою transcript і -політикою tools. Ці hooks — поверхня розширення для поведінки, специфічної для провайдера, без -потреби в цілком custom inference transport. +OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскрипту та +політикою інструментів. Ці хуки — поверхня розширення для поведінки постачальника без +потреби в цілком власному транспорті висновку. -Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, -які generic auth/status/model-picker шляхи мають бачити без завантаження runtime плагіна. -Використовуйте маніфест `providerAuthChoices`, коли поверхні onboarding/auth-choice CLI -мають знати id вибору провайдера, labels груп і просте підключення auth -через один прапорець без завантаження runtime провайдера. Зберігайте runtime провайдера -`envVars` для підказок оператору, наприклад labels onboarding або vars для -налаштування OAuth client-id/client-secret. +Використовуйте `providerAuthEnvVars` у маніфесті, коли постачальник має облікові дані на основі env, +які мають бачити загальні шляхи auth/status/model-picker без завантаження +часу виконання плагіна. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні +CLI onboarding/auth-choice повинні знати id вибору постачальника, мітки груп і просту +однопрапорцеву auth-прив’язку без завантаження часу виконання постачальника. Зберігайте `envVars` +часу виконання постачальника для підказок, орієнтованих на оператора, таких як мітки onboarding або +змінні налаштування OAuth client-id/client-secret. -### Порядок і використання hooks +### Порядок хуків і використання -Для плагінів моделей/провайдерів OpenClaw викликає hooks приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий довідник для прийняття рішень. +Для плагінів моделей/постачальників OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це швидкий посібник для вибору. -| # | Hook | Що він робить | Коли використовувати | -| --- | --------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями base URL за замовчуванням | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(це не hook плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує legacy або preview псевдоніми model-id до пошуку | Провайдер володіє очищенням псевдонімів до канонічного резолву моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням transport для custom provider ids у тому самому сімействі transport | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` до runtime/provider resolution | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; bundled Google-family helpers також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від ендпоїнта | -| 7 | `resolveConfigApiKey` | Резолвить auth env-marker для провайдерів конфігурації до завантаження runtime auth | Провайдер має власний резолвер API-key через env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі config без збереження відкритого тексту | Провайдер може працювати із synthetic/local credential marker | -| 9 | `resolveExternalOAuthProfiles` | Накладає external OAuth profiles; типове `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Провайдер повторно використовує external OAuth credentials без збереження скопійованих refresh tokens | -| 10 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених synthetic placeholder profiles порівняно з auth на основі env/config | Провайдер зберігає synthetic placeholder profiles, які не мають вигравати за пріоритетом | -| 11 | `resolveDynamicModel` | Синхронний fallback для model ids, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні model ids вищого рівня | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані до резолву невідомих ids | -| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використає резолвлену модель | Провайдеру потрібні переписування transport, але він усе ще використовує transport core | -| 14 | `contributeResolvedModelCompat` | Додає compat flags для моделей вендора за іншим сумісним transport | Провайдер розпізнає власні моделі на proxy transports без перехоплення самого провайдера | -| 15 | `capabilities` | Метадані transcript/tooling, що належать провайдеру й використовуються спільною логікою core | Провайдеру потрібні особливості transcript/provider-family | -| 16 | `normalizeToolSchemas` | Нормалізує схеми tools до того, як embedded runner їх побачить | Провайдеру потрібне очищення схем для сімейства transport | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про keywords без навчання core правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку custom transport | Провайдеру потрібен custom wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності headers/body/model без custom transport | -| 22 | `resolveTransportTurnState` | Прикріплює native headers або метадані transport на кожен хід | Провайдер хоче, щоб generic transports надсилали ідентичність ходу, нативну для провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native WebSocket headers або політику паузи сесії | Провайдер хоче, щоб generic WS transports налаштовували headers сесії або політику fallback | -| 24 | `formatApiKey` | Форматер auth-profile: збережений profile стає runtime-рядком `apiKey` | Провайдер зберігає додаткові auth metadata і потребує custom shape runtime token | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для custom refresh endpoints або політики помилки refresh | Провайдер не відповідає спільним refreshers `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається при помилці OAuth refresh | Провайдеру потрібні власні вказівки з виправлення auth після помилки refresh | -| 27 | `matchesContextOverflowError` | Матчер переповнення context-window, що належить провайдеру | Провайдер має сирі помилки переповнення, які generic heuristics пропустять | -| 28 | `classifyFailoverReason` | Класифікація причини failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/transport із rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна generic повідомлення про відновлення при відсутності auth | Провайдеру потрібна власна підказка відновлення auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream моделей плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховувати застарілі рядки upstream або замінювати їх підказкою вендора | -| 32 | `augmentModelCatalog` | Synthetic/final рядки каталогу додаються після виявлення | Провайдеру потрібні synthetic рядки прямої сумісності в `models list` і вибірниках | -| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер підтримує лише двійкове вмикання/вимикання thinking | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | -| 36 | `isModernModelRef` | Матчер modern-model для live profile filters і відбору smoke | Провайдер володіє зіставленням preferred-model для live/smoke | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime token/key безпосередньо перед inference | Провайдеру потрібен обмін token або короткоживучі облікові дані запиту | -| 38 | `resolveUsageAuth` | Резолвить облікові дані usage/billing для `/usage` і пов’язаних поверхонь status | Провайдеру потрібен custom розбір usage/quota token або інші облікові дані usage | -| 39 | `fetchUsageSnapshot` | Отримує й нормалізує snapshots usage/quota, специфічні для провайдера, після резолву auth | Провайдеру потрібен власний ендпоїнт usage або parser payload | -| 40 | `createEmbeddingProvider` | Створює adapter embedding, що належить провайдеру, для memory/search | Поведінка embedding для memory має належати плагіну провайдера | -| 41 | `buildReplayPolicy` | Повертає політику replay, яка контролює обробку transcript для провайдера | Провайдеру потрібна custom політика transcript (наприклад, видалення thinking-block) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні helpers компактування | -| 43 | `validateReplayTurns` | Фінальна валідація або переформування ходів replay перед embedded runner | Transport провайдера потребує суворішої валідації ходів після загального очищення | -| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | -------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або значеннями base URL за замовчуванням | +| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей постачальника | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(це не хук плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id до пошуку | Постачальник володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника до загального збирання моделі | Постачальник володіє очищенням транспорту для користувацьких id постачальників у тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення часу виконання/постачальника | Постачальнику потрібно очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігураційних постачальників | Постачальнику потрібні виправлення метаданих native streaming usage, що залежать від endpoint | +| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для конфігураційних постачальників до завантаження runtime auth | Постачальник має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований визначник AWS env-marker | +| 8 | `resolveSyntheticAuth` | Виводить локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Постачальник може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalOAuthProfiles` | Накладає зовнішні профілі OAuth; значення `persistence` за замовчуванням — `runtime-only` для облікових даних, що належать CLI/застосунку | Постачальник повторно використовує зовнішні облікові дані OAuth без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з auth на основі env/конфігурації | Постачальник зберігає синтетичні профілі-заповнювачі, які не мають перемагати за пріоритетом | +| 11 | `resolveDynamicModel` | Синхронний fallback для model id, що належать постачальнику, але ще не є в локальному реєстрі | Постачальник приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Постачальнику потрібні мережеві метадані до визначення невідомих id | +| 13 | `normalizeResolvedModel` | Фінальне переписування до того, як embedded runner використовує визначену модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Постачальник розпізнає власні моделі на proxy-транспортах, не перебираючи контроль над постачальником | +| 15 | `capabilities` | Метадані транскрипту/інструментарію, що належать постачальнику і використовуються спільною логікою ядра | Постачальнику потрібні особливості транскрипту/сімейства постачальника | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Постачальнику потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження про ключові слова, не навчаючи ядро правилам, специфічним для постачальника | +| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт reasoning-output | Постачальнику потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних обгорток параметрів потоку | Постачальнику потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного постачальника | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Постачальнику потрібен власний wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Постачальнику потрібні обгортки заголовків/тіла/сумісності моделі запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає native-заголовки або метадані транспорту для кожного ходу | Постачальник хоче, щоб загальні транспорти надсилали native-ідентичність ходу постачальника | +| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Постачальник хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику fallback | +| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` під час виконання | Постачальник зберігає додаткові auth-метадані й потребує користувацької форми токена часу виконання | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких endpoints оновлення або політики збоїв refresh | Постачальник не вписується в спільні refreshers `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли OAuth refresh завершується невдачею | Постачальнику потрібні власні вказівки з відновлення auth після збою refresh | +| 27 | `matchesContextOverflowError` | Визначник переповнення context window, що належить постачальнику | Постачальник має сирі помилки переповнення, які пропустили б загальні евристики | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить постачальнику | Постачальник може зіставити сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-постачальників | Постачальнику потрібне специфічне для proxy керування TTL кешу | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутньому auth | Постачальнику потрібна власна підказка відновлення при відсутньому auth | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Постачальнику потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Постачальнику потрібні синтетичні рядки forward-compat у `models list` і селекторах | +| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників binary-thinking | Постачальник відкриває лише двійкове thinking увімк./вимк. | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Постачальник хоче `xhigh` лише для підмножини моделей | +| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Постачальник володіє політикою `/think` за замовчуванням для сімейства моделей | +| 36 | `isModernModelRef` | Визначник сучасної моделі для live-фільтрів профілів і вибору smoke | Постачальник володіє зіставленням бажаних live/smoke-моделей | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ часу виконання безпосередньо перед висновком | Постачальнику потрібен обмін токенів або короткоживучі облікові дані для запиту | +| 38 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та споріднених поверхонь статусу | Постачальнику потрібен користувацький парсинг токена usage/quota або інші облікові дані для usage | +| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника знімки usage/quota після визначення auth | Постачальнику потрібен специфічний для нього endpoint usage або парсер payload | +| 40 | `createEmbeddingProvider` | Будує адаптер embedding, що належить постачальнику, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати разом із плагіном постачальника | +| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для постачальника | Постачальнику потрібна користувацька політика транскрипту (наприклад, видалення thinking-блоків) | +| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Постачальнику потрібні специфічні для нього переписування replay понад спільні допоміжні засоби компакції | +| 43 | `validateReplayTurns` | Фінальна валідація або переформування ходів replay перед embedded runner | Транспорт постачальника потребує суворішої валідації ходів після загальної санітизації | +| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або стан постачальника, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших hook-capable provider plugins, -доки хтось справді не змінить id моделі або transport/config. Це дозволяє -shim-ам alias/compat провайдерів працювати без потреби для викликача знати, який -bundled plugin володіє переписуванням. Якщо жоден hook провайдера не переписує підтримуваний -запис конфігурації Google-family, bundled normalizer конфігурації Google усе одно застосує -це очищення сумісності. +відповідний плагін постачальника, а потім переходять до інших плагінів постачальників, здатних обробляти хуки, +доки якийсь із них справді не змінить id моделі або транспорт/конфігурацію. Це +дає змогу працювати shim-постачальникам для псевдонімів/сумісності без вимоги, щоб викликач знав, +який вбудований плагін володіє переписуванням. Якщо жоден хук постачальника не перепише +підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google +усе одно застосує це очищення сумісності. -Якщо провайдеру потрібен повністю custom wire protocol або custom request executor, -це інший клас розширення. Ці hooks призначені для поведінки провайдера, -яка все ще працює на звичайному inference loop OpenClaw. +Якщо постачальнику потрібен повністю користувацький wire protocol або користувацький виконавець запитів, +це вже інший клас розширення. Ці хуки призначені для поведінки постачальника, +яка все ще працює на звичайному циклі висновку OpenClaw. -### Приклад провайдера +### Приклад постачальника ```ts api.registerProvider({ @@ -769,114 +771,112 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - і `wrapStreamFn`, оскільки володіє прямою сумісністю Claude 4.6, - підказками сімейства провайдера, інструкціями з виправлення auth, інтеграцією - ендпоїнта usage, придатністю prompt-cache, значеннями конфігурації за замовчуванням, що враховують auth, - політикою thinking Claude за замовчуванням/адаптивною, а також stream shaping, специфічним для Anthropic, - для beta headers, `/fast` / `serviceTier` і `context1m`. -- Специфічні для Claude stream helpers Anthropic поки що залишаються у власному - публічному шві bundled plugin `api.ts` / `contract-api.ts`. Ця поверхня пакета + і `wrapStreamFn`, тому що він володіє forward-compat для Claude 4.6, + підказками сімейства постачальника, вказівками з відновлення auth, інтеграцією + endpoint usage, придатністю prompt-cache, auth-aware значеннями конфігурації за замовчуванням, політикою + thinking за замовчуванням/адаптивного thinking для Claude та специфічним для Anthropic формуванням потоку для + beta-заголовків, `/fast` / `serviceTier` і `context1m`. +- Допоміжні засоби потоку Anthropic, специфічні для Claude, поки що залишаються у + власному публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі - builders обгорток Anthropic замість розширення generic SDK навколо правил beta-header - одного провайдера. + конструктори обгорток Anthropic замість розширення загального SDK навколо правил + beta-заголовків одного постачальника. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - оскільки володіє прямою сумісністю GPT-5.4, прямою нормалізацією OpenAI + тому що він володіє GPT-5.4 forward-compat, прямою нормалізацією OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приховуванням Spark, synthetic рядками списку OpenAI і політикою GPT-5 thinking / - live-model; сімейство stream `openai-responses-defaults` володіє - спільними native OpenAI Responses wrappers для attribution headers, - `/fast`/`serviceTier`, текстової багатослівності, native Codex web search, - формування payload reasoning-compat і керування context Responses. + приглушенням Spark, синтетичними рядками списку OpenAI та політикою thinking / + live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє + спільними native-обгортками OpenAI Responses для заголовків attribution, + `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex, + формування payload reasoning-compat і керування контекстом Responses. - OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, тому що провайдер є pass-through і може відкривати нові - model ids до оновлення статичного каталогу OpenClaw; він також використовує - `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати - request headers, routing metadata, patches reasoning і політику prompt-cache, - специфічні для провайдера, поза core. Його політика replay походить із сімейства - `passthrough-gemini`, а сімейство stream `openrouter-thinking` + `prepareDynamicModel`, тому що цей постачальник є pass-through і може відкривати нові + model id до оновлення статичного каталогу OpenClaw; він також використовує + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб + тримати специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і + політику prompt-cache поза ядром. Його політика replay походить від сімейства + `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` володіє proxy-ін’єкцією reasoning і пропусками unsupported-model / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, - оскільки йому потрібні device login, що належить провайдеру, поведінка fallback моделей, - особливості transcript Claude, обмін GitHub token -> Copilot token - і endpoint usage, що належить провайдеру. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому + потрібні device login, що належить постачальнику, поведінка fallback моделей, особливості транскрипту Claude, + обмін токена GitHub на токен Copilot і endpoint usage, що належить постачальнику. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він - усе ще працює на transports core OpenAI, але володіє своєю нормалізацією - transport/base URL, політикою fallback OAuth refresh, вибором transport за замовчуванням, - synthetic рядками каталогу Codex і інтеграцією ендпоїнта usage ChatGPT; він - використовує те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI. -- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, + досі працює на основних транспортах OpenAI, але володіє нормалізацією + свого транспорту/base URL, політикою fallback оновлення OAuth, вибором транспорту за замовчуванням, + синтетичними рядками каталогу Codex і інтеграцією endpoint usage ChatGPT; він + використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. +- Google AI Studio та Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що - сімейство replay `google-gemini` володіє fallback сумісності Gemini 3.1, - native валідацією replay Gemini, очищенням bootstrap replay, - режимом tagged reasoning-output і зіставленням modern-model, а - сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; + сімейство replay `google-gemini` володіє fallback сумісності вперед для Gemini 3.1, + native-валідацією replay Gemini, санітизацією bootstrap replay, tagged-режимом + reasoning-output і зіставленням сучасних моделей, тоді як + сімейство потоків `google-thinking` володіє нормалізацією payload thinking для Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування token, розбору token і підключення - endpoint quota. + `fetchUsageSnapshot` для форматування токенів, розбору токенів і + підключення endpoint quota. - Anthropic Vertex використовує `buildReplayPolicy` через сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося - обмеженим id Claude, а не кожним transport `anthropic-messages`. + обмеженим id Claude, а не кожним транспортом `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що він володіє класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, - для трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий - захист лише для Claude `anthropic-by-model`. + для трафіку Anthropic-on-Bedrock; його політика replay все ще спирається на той самий + guard лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini - через transports, сумісні з OpenAI, і потребують очищення thought-signature Gemini - без native валідації replay Gemini або переписувань bootstrap. + через сумісні з OpenAI транспорти та потребують санітизації + thought-signature Gemini без native-валідації replay Gemini або переписувань bootstrap. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один провайдер володіє семантикою як - повідомлень Anthropic, так і OpenAI-compatible; він зберігає видалення thinking-block - лише для Claude на стороні Anthropic, водночас перевизначаючи режим reasoning - output назад на native, а сімейство stream `minimax-fast-mode` володіє - переписуваннями моделей fast-mode на спільному stream path. -- Moonshot використовує `catalog` плюс `wrapStreamFn`, тому що все ще використовує - спільний transport OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; сімейство - stream `moonshot-thinking` зіставляє config плюс стан `/think` на його - native binary thinking payload. + сімейство replay `hybrid-anthropic-openai`, тому що один постачальник володіє і + семантикою повідомлень Anthropic, і OpenAI-сумісною семантикою; він зберігає видалення + thinking-блоків лише для Claude на стороні Anthropic, водночас перевизначаючи режим + reasoning output назад на native, а сімейство потоків `minimax-fast-mode` володіє + переписуванням моделей fast-mode на спільному шляху потоку. +- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він все ще використовує спільний + транспорт OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство потоків + `moonshot-thinking` відображає config плюс стан `/think` на свій + native двійковий payload thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні request headers, специфічні для провайдера, - нормалізація payload reasoning, підказки transcript Gemini і керування - TTL кешу Anthropic; сімейство stream `kilocode-thinking` зберігає ін’єкцію Kilo thinking - на шляху спільного proxy stream, водночас пропускаючи `kilo/auto` та - інші proxy model ids, які не підтримують явний payload reasoning. + `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, що належать постачальнику, + нормалізація payload reasoning, підказки транскрипту Gemini і керування + TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію + thinking Kilo на спільному proxy-шляху потоку, водночас пропускаючи `kilo/auto` та + інші proxy model id, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback GLM-5, - значеннями `tool_stream` за замовчуванням, UX binary thinking, зіставленням modern-model - і як auth usage, так і отриманням quota; сімейство stream `tool-stream-default-on` - тримає wrapper `tool_stream` з увімкненням за замовчуванням поза написаним вручну glue для кожного провайдера. + `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він володіє fallback GLM-5, + значеннями `tool_stream` за замовчуванням, UX двійкового thinking, зіставленням сучасних моделей, + а також auth usage і отриманням quota; сімейство потоків `tool-stream-default-on` + не допускає винесення обгортки `tool_stream`, увімкненої за замовчуванням, у рукописну glue-логіку кожного постачальника. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - оскільки володіє нормалізацією native xAI Responses transport, переписуванням + тому що він володіє нормалізацією native-транспорту xAI Responses, переписуваннями псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / - payload reasoning, fallback повторним використанням auth для tools, що належать плагіну, - резолвом прямих сумісних моделей Grok і patches compat, що належать провайдеру, як-от профіль схем tools xAI, - непідтримувані keywords схем, native `web_search` і декодування HTML-entity - аргументів виклику tool. -- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, - щоб винести особливості transcript/tooling за межі core. -- Bundled providers лише з каталогом, як-от `byteplus`, `cloudflare-ai-gateway`, + reasoning-payload, повторним використанням fallback auth для інструментів, що належать плагіну, + визначенням моделей Grok із forward-compat та compat-патчами, що належать постачальнику, + такими як профіль схем інструментів xAI, непідтримувані ключові слова схеми, native `web_search` і декодування аргументів виклику інструментів із HTML-entities. +- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб + тримати особливості транскрипту/інструментарію поза ядром. +- Вбудовані постачальники лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації - media-understanding і video-generation для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс hooks usage, тому що їхня поведінка `/usage` - належить плагіну, хоча inference усе ще працює через спільні transports. +- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації + розуміння медіа й генерації відео для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, тому що їхня поведінка + `/usage` належить плагіну, навіть якщо висновок і далі проходить через спільні транспорти. -## Helpers runtime +## Допоміжні засоби часу виконання -Плагіни можуть отримувати доступ до вибраних helpers core через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -897,14 +897,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload виводу TTS core для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію core `messages.tts` і вибір провайдера. -- Повертає PCM audio buffer + sample rate. Плагіни мають виконувати ресемплінг/кодування для провайдерів. -- `listVoices` необов’язковий для кожного провайдера. Використовуйте його для voice pickers або setup flows, що належать вендору. -- Списки голосів можуть містити багатші метадані, як-от locale, gender і personality tags для picker-ів, що враховують провайдера. +- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію ядра `messages.tts` і вибір постачальника. +- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни повинні ресемплювати/кодувати для постачальників. +- `listVoices` є необов’язковим для кожного постачальника. Використовуйте це для голосових селекторів або потоків setup, що належать вендору. +- Переліки голосів можуть містити багатші метадані, такі як локаль, стать і теги особистості для селекторів, обізнаних про постачальника. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Плагіни також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -924,15 +924,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповіді в core. -- Використовуйте speech providers для поведінки синтезу, що належить вендору. -- Legacy-ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один vendor plugin може володіти - text, speech, image і майбутніми media providers, щойно OpenClaw додасть ці - контракти можливостей. +- Зберігайте політику TTS, fallback і доставку відповіді в ядрі. +- Використовуйте постачальників мовлення для поведінки синтезу, що належить вендору. +- Застарілий ввід Microsoft `edge` нормалізується до id постачальника `microsoft`. +- Бажана модель володіння є орієнтованою на компанію: один vendor-плагін може володіти + текстовими, мовленнєвими, графічними та майбутніми медіапостачальниками, у міру того як OpenClaw додає + контракти цих можливостей. -Для розуміння зображень/аудіо/відео плагіни реєструють один типізований -провайдер media-understanding замість generic key/value bag: +Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого +постачальника media-understanding замість загального мішка ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -946,16 +946,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, config і підключення каналів у core. -- Зберігайте поведінку вендора в плагіні провайдера. -- Адитивне розширення має лишатися типізованим: нові необов’язкові методи, нові необов’язкові +- Зберігайте оркестрацію, fallback, конфігурацію та wiring каналів у ядрі. +- Зберігайте поведінку вендора в плагіні постачальника. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та helper runtime - - vendor plugins реєструють `api.registerVideoGenerationProvider(...)` - - feature/channel plugins споживають `api.runtime.videoGeneration.*` +- Генерація відео вже дотримується того ж шаблону: + - ядро володіє контрактом можливості та допоміжним засобом часу виконання + - vendor-плагіни реєструють `api.registerVideoGenerationProvider(...)` + - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для helpers runtime media-understanding плагіни можуть викликати: +Для допоміжних засобів часу виконання media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -970,8 +970,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для аудіотранскрипції плагіни можуть використовувати або runtime media-understanding, -або старий псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або час виконання media-understanding, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -984,11 +984,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для +- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо core media-understanding (`tools.media.audio`) і порядок fallback провайдерів. -- Повертає `{ text: undefined }`, коли не було отримано результату транскрипції (наприклад, для пропущеного/непідтримуваного вводу). -- `api.runtime.stt.transcribeAudioFile(...)` лишається alias сумісності. +- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) та порядок fallback постачальників. +- Повертає `{ text: undefined }`, коли не отримано виходу транскрипції (наприклад, вхід пропущено/не підтримується). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. Плагіни також можуть запускати фонові підзапуски subagent через `api.runtime.subagent`: @@ -1004,14 +1004,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для конкретного запуску, а не постійні зміни сесії. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Для резервних запусків, що належать плагіну, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. - Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски subagent від недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються замість тихого fallback. +- Запуски subagent недовірених плагінів і далі працюють, але запити на перевизначення відхиляються замість тихого fallback. -Для web search плагіни можуть споживати спільний helper runtime замість -звернення до підключення agent tool: +Для вебпошуку плагіни можуть споживати спільний допоміжний засіб часу виконання замість +звернення до wiring інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1027,14 +1027,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати web-search providers через +Плагіни також можуть реєструвати постачальників вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, резолв облікових даних і спільну семантику запитів у core. -- Використовуйте web-search providers для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для feature/channel plugins, яким потрібна поведінка пошуку без залежності від обгортки agent tool. +- Зберігайте вибір постачальника, визначення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте постачальників вебпошуку для vendor-специфічних транспортів пошуку. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1049,10 +1049,10 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка постачальників генерації зображень. +- `listProviders(...)`: перелічити доступних постачальників генерації зображень і їхні можливості. -## HTTP routes Gateway +## HTTP-маршрути Gateway Плагіни можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. @@ -1069,37 +1069,36 @@ api.registerHttpRoute({ }); ``` -Поля route: +Поля маршруту: -- `path`: шлях route у межах HTTP-сервера gateway. -- `auth`: обов’язково. Використовуйте `"gateway"` для звичайної auth gateway або `"plugin"` для auth/webhook verification, якими керує плагін. -- `match`: необов’язково. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язково. Дозволяє тому самому плагіну замінити власну наявну реєстрацію route. -- `handler`: повертайте `true`, коли route обробив запит. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове. Використовуйте `"gateway"` для вимоги звичайного auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує плагін. +- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` видалено, і він спричинить помилку завантаження плагіна. Використовуйте `api.registerHttpRoute(...)`. -- Routes плагіна мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити route іншого плагіна. -- Перекривні routes з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` мають бути лише в межах одного рівня auth. -- Routes `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для webhook/signature verification, якими керує плагін, а не для привілейованих викликів helpers Gateway. -- Routes `auth: "gateway"` працюють у межах runtime scope запиту Gateway, але цей scope навмисно консервативний: - - bearer auth на спільному секреті (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scopes route плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах plugin-route з ідентичністю, runtime scope повертається до `operator.write` -- Практичне правило: не вважайте route плагіна з gateway-auth неявною адміністративною поверхнею. Якщо вашому route потрібна поведінка лише для admin, вимагайте auth-режим із перенесенням ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було видалено й воно спричинить помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. +- Маршрути плагінів повинні явно оголошувати `auth`. +- Конфлікти однакового `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області часу виконання оператора. Вони призначені для webhook/перевірки підпису, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. +- Маршрути `auth: "gateway"` виконуються в межах області часу виконання запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області часу виконання маршруту плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з ідентичністю, область часу виконання повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. -## Шляхи імпорту Plugin SDK +## Шляхи імпорту SDK плагінів -Під час створення плагінів використовуйте subpaths SDK замість монолітного імпорту -`openclaw/plugin-sdk`: +Під час авторингу плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: - `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. - `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. - `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`). -- Стабільні примітиви каналів, як-от `openclaw/plugin-sdk/channel-setup`, +- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1111,17 +1110,17 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного підключення налаштування/auth/reply/webhook. - `channel-inbound` — це спільний дім для debounce, mention matching, - форматування envelope та helpers контексту inbound envelope. - `channel-setup` — вузький шов setup для необов’язкового встановлення. - `setup-runtime` — безпечна для runtime поверхня setup, яку використовують `setupEntry` / - відкладений запуск, включно з адаптерами патчів setup, безпечними для імпорту. - `setup-adapter-runtime` — шов account-setup adapter, що враховує env. - `setup-tools` — малий шов допоміжних засобів CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` для спільного wiring setup/auth/reply/webhook. + `channel-inbound` — це спільний дім для debounce, зіставлення згадок, + форматування envelope і допоміжних засобів контексту вхідного envelope. + `channel-setup` — це вузький шов setup для необов’язкового встановлення. + `setup-runtime` — це безпечна для часу виконання поверхня setup, яку використовують `setupEntry` / + відкладений запуск, включно з безпечними для імпорту patch-адаптерами setup. + `setup-adapter-runtime` — це шов адаптера setup облікового запису з урахуванням env. + `setup-tools` — це малий шов допоміжних засобів CLI/архіву/документації (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Domain subpaths, як-от `openclaw/plugin-sdk/channel-config-helpers`, +- Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1136,190 +1135,191 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних helpers runtime/config. - `telegram-command-config` — це вузький публічний шов для нормалізації/валідації custom - команд Telegram і лишається доступним, навіть якщо поверхня контракту bundled + `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів часу виконання/конфігурації. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації користувацьких + команд Telegram і він залишається доступним, навіть якщо поверхня контракту вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний шов text/markdown/logging, включно з - видаленням assistant-visible-text, helpers render/chunking markdown, helpers редагування, - helpers directive-tag і utilities безпечного тексту. -- Для approval-specific channel seams слід надавати перевагу одному контракту - `approvalCapability` у плагіні. Тоді core читає auth доставки схвалень, delivery, render і - native-routing через цю одну можливість замість змішування + `text-runtime` — це спільний шов тексту/markdown/логування, включно з + видаленням видимого для асистента тексту, допоміжними засобами рендерингу/розбиття markdown, засобами редагування, + допоміжними засобами тегів директив і утилітами безпечного тексту. +- Шви каналів, специфічні для схвалення, мають віддавати перевагу одному контракту `approvalCapability` + на плагіні. Потім ядро читає auth, доставку, рендеринг і + native-маршрутизацію схвалення через цю одну можливість замість змішування поведінки схвалення з не пов’язаними полями плагіна. -- `openclaw/plugin-sdk/channel-runtime` є застарілим і лишається лише - як compatibility shim для старіших плагінів. Новий код має імпортувати вужчі - generic primitives, а код репозиторію не повинен додавати нові імпорти цього shim. -- Внутрішні частини bundled extension лишаються приватними. Зовнішні плагіни мають використовувати лише - subpaths `openclaw/plugin-sdk/*`. Код/тести core OpenClaw можуть використовувати - публічні entry points репозиторію під коренем пакета плагіна, як-от `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js`, і вузькоспрямовані файли, як-от - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з +- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як + shim сумісності для старіших плагінів. Новий код має імпортувати натомість вужчі + загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього shim. +- Внутрішні механізми вбудованих розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати + публічні entrypoint репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` і вузько обмежені файли, такі як + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра чи з іншого розширення. -- Поділ entry point у репозиторії: - `/api.js` — це barrel helpers/types, - `/runtime-api.js` — barrel лише для runtime, - `/index.js` — entry bundled plugin, - а `/setup-entry.js` — entry setup plugin. -- Поточні приклади bundled providers: - - Anthropic використовує `api.js` / `contract-api.js` для Claude stream helpers, таких - як `wrapAnthropicProviderStream`, helpers beta-header і парсинг `service_tier`. - - OpenAI використовує `api.js` для builders провайдерів, helpers моделей за замовчуванням і builders realtime provider. - - OpenRouter використовує `api.js` для builder провайдера, а також helpers onboarding/config, - тоді як `register.runtime.js` усе ще може реекспортувати generic - helpers `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні entry points, завантажені через facade, надають перевагу активному snapshot конфігурації runtime, - якщо він існує, а інакше повертаються до резолвленого файла конфігурації на диску, коли - OpenClaw ще не надає snapshot runtime. -- Generic shared primitives лишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір сумісності branded helper seams bundled channel усе ще - існує. Розглядайте їх як шви для підтримки/сумісності bundled, а не як нові цілі імпорту для третіх сторін; нові міжканальні контракти все одно мають - додаватися до generic subpaths `plugin-sdk/*` або локальних barrels плагіна `api.js` / +- Розділення entrypoint у репозиторії: + `/api.js` — це барель допоміжних засобів/типів, + `/runtime-api.js` — це барель лише для часу виконання, + `/index.js` — це entrypoint вбудованого плагіна, + а `/setup-entry.js` — це entrypoint setup-плагіна. +- Поточні приклади вбудованих постачальників: + - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких + як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`. + - OpenAI використовує `api.js` для конструкторів постачальників, допоміжних засобів моделей за замовчуванням і + конструкторів realtime-постачальників. + - OpenRouter використовує `api.js` для свого конструктора постачальника плюс допоміжні + засоби onboarding/config, тоді як `register.runtime.js` усе ще може повторно експортувати загальні + допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні entrypoint, завантажені через фасад, віддають перевагу активному знімку конфігурації часу виконання, + якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли + OpenClaw ще не віддає знімок часу виконання. +- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір швів допоміжних засобів каналів під брендом вбудованих рішень усе ще + існує. Розглядайте їх як шви підтримки вбудованих/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти все одно мають потрапляти на + загальні підшляхи `plugin-sdk/*` або локальні барелі плагіна `api.js` / `runtime-api.js`. Примітка щодо сумісності: -- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. -- Насамперед надавайте перевагу вузьким стабільним primitives. Новіші subpaths setup/pairing/reply/ - feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це цільовий контракт для нової роботи з - bundled і зовнішніми плагінами. - Розбір/зіставлення цілей належить до `openclaw/plugin-sdk/channel-targets`. - Перевірки message action та helpers id повідомлень реакцій належать до +- Уникайте кореневого бареля `openclaw/plugin-sdk` у новому коді. +- Насамперед віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи + setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool — це бажаний контракт для нової роботи + з вбудованими та зовнішніми плагінами. + Розбір/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`. + Шлюзи дій повідомлень і допоміжні засоби id повідомлень реакцій мають належати `openclaw/plugin-sdk/channel-actions`. -- Helper barrels, специфічні для bundled extension, не є стабільними за замовчуванням. Якщо - helper потрібен лише bundled extension, тримайте його за локальним - швом розширення `api.js` або `runtime-api.js` замість просування до +- Барелі допоміжних засобів, специфічних для вбудованих розширень, не є стабільними за замовчуванням. Якщо + допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальним + швом `api.js` або `runtime-api.js` цього розширення замість просування до `openclaw/plugin-sdk/`. -- Нові шви спільних helpers мають бути generic, а не branded під канал. Спільний розбір - цілей належить до `openclaw/plugin-sdk/channel-targets`; внутрішні частини, специфічні для каналу, - лишаються за локальним швом `api.js` або `runtime-api.js` плагіна-власника. -- Subpaths, специфічні для можливостей, як-от `image-generation`, - `media-understanding` і `speech`, існують, тому що bundled/native plugins використовують - їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper — це - довгостроковий заморожений зовнішній контракт. +- Нові шви спільних допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір + цілей належить `openclaw/plugin-sdk/channel-targets`; специфічні для каналу + внутрішні механізми залишаються за локальним швом `api.js` або `runtime-api.js` + плагіна-власника. +- Підшляхи, специфічні для можливостей, такі як `image-generation`, + `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є + довгостроковим замороженим зовнішнім контрактом. -## Схеми message tool +## Схеми інструмента повідомлень -Плагіни мають володіти внесками до схем `describeMessageTool(...)`, специфічними для каналу. -Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному core. +Плагіни повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. +Тримайте поля, специфічні для постачальника, у плагіні, а не в спільному ядрі. -Для спільних portable фрагментів схеми повторно використовуйте generic helpers, експортовані через +Для спільних переносимих фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованих payload карток +- `createMessageToolCardSchema()` для структурованого payload картки -Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному -вихідному коді цього плагіна, а не просувайте її до спільного SDK. +Якщо форма схеми має сенс лише для одного постачальника, визначайте її у власному +коді цього плагіна замість просування до спільного SDK. -## Резолв цілей каналу +## Визначення цілей каналу -Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -outbound host generic і використовуйте поверхню messaging adapter для правил провайдера: +Плагіни каналів повинні володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний host узагальненим і використовуйте поверхню адаптера повідомлень для правил постачальника: -- `messaging.inferTargetChatType({ to })` вирішує, чи слід трактувати нормалізовану ціль - як `direct`, `group` або `channel` до пошуку в directory. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи слід - одразу перейти до резолву як id, а не шукати в directory. +- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль + трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи + має вхід перейти одразу до визначення за схожістю з id замість пошуку в каталозі. - `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли - core потрібен остаточний резолв, що належить провайдеру, після нормалізації або - після промаху в directory. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічного для провайдера, - після того, як ціль резолвлено. + ядру потрібне фінальне визначення, що належить постачальнику, після нормалізації або + після промаху в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, + специфічною для постачальника, після того як ціль визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для категоризації, яка має відбуватися до +- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають відбуватися до пошуку peers/groups. -- Використовуйте `looksLikeId` для перевірок «вважати це явним/native target id». -- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для - широкого пошуку в directory. -- Тримайте provider-native ids, як-от chat ids, thread ids, JIDs, handles і room - ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в generic полях SDK. +- Використовуйте `looksLikeId` для перевірок на кшталт «розглядати це як явний/native id цілі». +- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для постачальника, а не для + широкого пошуку в каталозі. +- Зберігайте native id постачальника, такі як chat id, thread id, JID, handle і room id, + усередині значень `target` або параметрів, специфічних для постачальника, а не в загальних полях SDK. ## Каталоги на основі конфігурації -Плагіни, які виводять записи directory із config, мають тримати цю логіку в -плагіні й повторно використовувати спільні helpers із +Плагіни, які виводять записи каталогу з конфігурації, повинні тримати цю логіку в +плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі config, наприклад: +Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, такі як: -- DM peers, керовані allowlist -- налаштовані відображення channel/group -- статичні account-scoped fallback-и directory +- DM-peers на основі allowlist +- налаштовані карти каналів/груп +- статичні fallback-каталоги в межах облікового запису -Спільні helpers у `directory-runtime` обробляють лише generic операції: +Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрація запитів -- застосування ліміту -- дедуплікація/helpers нормалізації -- побудова `ChannelDirectoryEntry[]` +- фільтрацію запитів +- застосування обмежень +- дедуплікацію/нормалізацію +- побудову `ChannelDirectoryEntry[]` -Перевірка account та нормалізація id, специфічні для каналу, мають лишатися в реалізації -плагіна. +Специфічна для каналу перевірка облікового запису та нормалізація id мають залишатися в +реалізації плагіна. -## Каталоги провайдерів +## Каталоги постачальників -Плагіни провайдерів можуть визначати каталоги моделей для inference за допомогою +Плагіни постачальників можуть визначати каталоги моделей для висновку через `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: -- `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдера +- `{ provider }` для одного запису постачальника +- `{ providers }` для кількох записів постачальників -Використовуйте `catalog`, коли плагін володіє model ids, значеннями base URL за замовчуванням або -метаданими моделей з керуванням через auth, специфічними для провайдера. +Використовуйте `catalog`, коли плагін володіє model id, специфічними для постачальника, значеннями base URL +за замовчуванням або метаданими моделей, що залежать від auth. `catalog.order` керує тим, коли каталог плагіна зливається відносно -вбудованих неявних провайдерів OpenClaw: +вбудованих неявних постачальників OpenClaw: -- `simple`: прості провайдери на основі API-key або env -- `profile`: провайдери, які з’являються, коли існують auth profiles -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів -- `late`: останній прохід після інших неявних провайдерів +- `simple`: звичайні постачальники на основі API-ключа або env +- `profile`: постачальники, що з’являються, коли існують auth-профілі +- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників +- `late`: останній прохід, після інших неявних постачальників -Пізніші провайдери перемагають при конфлікті ключів, тому плагіни можуть навмисно -перевизначити вбудований запис провайдера з тим самим id провайдера. +Пізніші постачальники перемагають при колізії ключів, тож плагіни можуть навмисно +перевизначати вбудований запис постачальника з тим самим id постачальника. Сумісність: -- `discovery` досі працює як legacy alias +- `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Інспекція каналів у режимі лише читання +## Канальне інспектування лише для читання -Якщо ваш плагін реєструє канал, надавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що credentials - повністю матеріалізовані, і швидко завершуватися помилкою, коли обов’язкових секретів бракує. -- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`, +- `resolveAccount(...)` — це шлях часу виконання. Він може припускати, що облікові дані + повністю матеріалізовані, і може швидко завершуватися помилкою, коли потрібні секрети відсутні. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config - repair, не повинні потребувати матеріалізації credentials runtime лише для + repair, не повинні вимагати матеріалізації облікових даних часу виконання лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: -- Повертає лише описовий стан account. +- Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/статусу credentials, коли це доречно, наприклад: +- Включає поля джерела/стану облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення token лише для звітування про доступність у режимі лише читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела) достатньо для команд у стилі status. -- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але - він недоступний у поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але + вони недоступні в поточному шляху команди. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного звіту про те, що account не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість збоїв або хибного повідомлення, що обліковий запис не налаштований. -## Пакетні набори +## Package packs Каталог плагіна може містити `package.json` з `openclaw.extensions`: @@ -1333,64 +1333,62 @@ outbound host generic і використовуйте поверхню messaging } ``` -Кожен entry стає плагіном. Якщо набір містить кілька extensions, id плагіна +Кожен запис стає плагіном. Якщо pack перелічує кілька розширень, id плагіна стає `name/`. -Якщо ваш плагін імпортує npm dependencies, установіть їх у цьому каталозі, щоб +Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Запобіжник безпеки: кожен entry у `openclaw.extensions` має залишатися в межах каталогу плагіна -після резолву symlink. Entries, які виходять за межі каталогу пакета, -відхиляються. +Захисне обмеження безпеки: кожен запис `openclaw.extensions` повинен залишатися в межах каталогу плагіна +після визначення symlink. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка з безпеки: `openclaw plugins install` встановлює dependencies плагіна за допомогою -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies у runtime). Зберігайте дерева залежностей плагінів як «чисті JS/TS» і уникайте пакетів, яким потрібні збірки через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей під час виконання). Зберігайте дерева залежностей плагінів у стилі «чистий JS/TS» і уникайте пакетів, яким потрібні збірки `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для setup. -Коли OpenClaw потребує surfaces setup для вимкненого channel plugin або -коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повного entry плагіна. Це робить запуск і setup легшими, -коли ваш основний entry плагіна також підключає tools, hooks або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легковаговий модуль лише для setup. +Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу, або +коли плагін каналу увімкнено, але він іще не налаштований, він завантажує `setupEntry` +замість повного entrypoint плагіна. Це робить запуск і setup легшими, +коли ваш основний entrypoint плагіна також прив’язує інструменти, хуки або інший код лише для часу виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести channel plugin на той самий шлях `setupEntry` під час +може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску gateway до початку прослуховування, навіть якщо канал уже налаштовано. -Використовуйте це лише коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне прослуховувати. На практиці це означає, що entry setup -має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка повинна існувати +до того, як gateway почне слухати. На практиці це означає, що entrypoint setup +повинен реєструвати кожну можливість, що належить каналу, від якої залежить запуск, таку як: -- саму реєстрацію каналу -- будь-які HTTP routes, які мають бути доступні до початку прослуховування gateway -- будь-які методи gateway, tools або services, які мають існувати в тому самому вікні +- сама реєстрація каналу +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати +- будь-які методи gateway, інструменти або служби, які мають існувати в це саме вікно часу -Якщо ваш повний entry усе ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте -цей прапорець. Залишайте плагін у типові поведінці і дозвольте OpenClaw завантажити -повний entry під час запуску. +Якщо ваш повний entrypoint усе ще володіє будь-якою необхідною можливістю для запуску, не вмикайте +цей прапорець. Залиште плагін на типовій поведінці й дозвольте OpenClaw завантажити +повний entrypoint під час запуску. -Bundled channels також можуть публікувати helpers surface контракту лише для setup, до яких core -може звертатися до завантаження повного runtime каналу. Поточна поверхня -підвищення setup така: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, до яких ядро +може звертатися до завантаження повного середовища виконання каналу. Поточна поверхня +просування setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли йому потрібно перевести legacy single-account channel -config у `channels..accounts.*` без завантаження повного entry плагіна. -Поточний приклад bundled — Matrix: він переносить лише ключі auth/bootstrap у -іменований обліковий запис після підвищення, коли іменовані облікові записи вже існують, і може +Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію +однокористувацького каналу в `channels..accounts.*` без завантаження повного entrypoint плагіна. +Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap до +іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів setup тримають виявлення поверхні контракту bundled lazy. Час -імпорту залишається малим; поверхня підвищення завантажується лише при першому використанні -замість повторного входу в запуск bundled channel під час імпорту модуля. +Ці patch-адаптери setup зберігають ліниве виявлення поверхні контракту вбудованих рішень. +Час імпорту залишається малим; поверхня просування завантажується лише при першому використанні, замість повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають gateway RPC methods, тримайте їх під -специфічним для плагіна префіксом. Простори імен core admin (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди резолвляться -до `operator.admin`, навіть якщо плагін запитує вужчий scope. +Коли ці поверхні запуску включають gateway RPC methods, тримайте їх на +префіксі, специфічному для плагіна. Простори імен адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються +як `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -1409,8 +1407,8 @@ config у `channels..accounts.*` без завантаження повно ### Метадані каталогу каналів -Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє ядру каталогу не містити даних. +Плагіни каналів можуть рекламувати метадані setup/discovery через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити дані каталогу. Приклад: @@ -1438,41 +1436,41 @@ config у `channels..accounts.*` без завантаження повно } ``` -Корисні поля `openclaw.channel` поза мінімальним прикладом: +Корисні поля `openclaw.channel` понад мінімальний приклад: -- `detailLabel`: вторинний label для багатших поверхонь каталогу/status -- `docsLabel`: перевизначає текст посилання на документацію -- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування копірайтом для поверхонь вибору -- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо outbound formatting +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `docsLabel`: перевизначення тексту посилання для посилання на документацію +- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має перевершувати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом на поверхні вибору +- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо вихідного форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: legacy aliases усе ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки account, навіть коли існує лише один account -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час резолву announce targets +- `exposure.setup`: приховує канал з інтерактивних селекторів setup/configure, якщо встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документацією +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` +- `quickstartAllowFrom`: вмикає для каналу стандартний потік quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку сесії під час визначення announce-target -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). -Розмістіть JSON-файл у одному з таких шляхів: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Розмістіть JSON-файл в одному з таких місць: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має -містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser також приймає `"packages"` або `"plugins"` як legacy aliases для ключа `"entries"`. +один чи кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл повинен +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Плагіни context engine +## Плагіни механізму контексту -Плагіни context engine володіють оркестрацією контексту сесії для ingest, assembly -і compaction. Зареєструйте їх зі свого плагіна через -`api.registerContextEngine(id, factory)`, а потім виберіть активний engine через +Плагіни механізму контексту володіють оркестрацією контексту сесії для інжесту, збирання +та компакції. Реєструйте їх зі свого плагіна через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через `plugins.slots.contextEngine`. Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр context, а не просто додати memory search або hooks. +конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. ```ts export default function (api) { @@ -1491,8 +1489,8 @@ export default function (api) { } ``` -Якщо ваш engine **не** володіє алгоритмом compaction, збережіть реалізацію `compact()` -і явно делегуйте її: +Якщо ваш механізм **не** володіє алгоритмом компакції, залишайте `compact()` +реалізованим і явно делегуйте його: ```ts import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"; @@ -1519,45 +1517,45 @@ export default function (api) { ## Додавання нової можливості -Коли плагіну потрібна поведінка, яка не вкладається в поточний API, не обходьте -систему плагінів приватним прямим доступом. Додайте відсутню можливість. +Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте +систему плагінів через приватний доступ усередину. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політика, fallback, злиття config, - життєвий цикл, семантика для каналів і форма helper runtime. -2. додайте типізовані поверхні реєстрації/runtime плагіна - Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною +1. визначте контракт ядра + Вирішіть, якою спільною поведінкою має володіти ядро: політикою, fallback, злиттям конфігурації, + життєвим циклом, семантикою для каналів і формою допоміжних засобів часу виконання. +2. додайте типізовані поверхні реєстрації/часу виконання плагіна + Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть споживачів core + каналів/функцій - Канали та плагіни функцій мають споживати нову можливість через core, - а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендорів - Потім vendor plugins реєструють свої backend-и для цієї можливості. -5. додайте contract coverage - Додайте тести, щоб із часом володіння та форма реєстрації залишалися явними. +3. прив’яжіть споживачів ядра + каналів/функцій + Канали та плагіни функцій повинні споживати нову можливість через ядро, + а не через прямий імпорт реалізації вендора. +4. зареєструйте реалізації вендора + Потім vendor-плагіни реєструють свої бекенди для цієї можливості. +5. додайте контрактне покриття + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw лишається послідовним, не стаючи жорстко прив’язаним до світогляду -одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного чекліста файлів і розгорнутого прикладу. +Саме так OpenClaw залишається виразним, не стаючи хардкодженим під світогляд +одного постачальника. Дивіться [Посібник з можливостей](/uk/plugins/architecture), +щоб отримати конкретний чекліст файлів і готовий приклад. ### Чекліст можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих -поверхонь разом: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися +цих поверхонь: -- типи контракту core у `src//types.ts` -- runner/helper runtime core у `src//runtime.ts` +- типи контракту ядра в `src//types.ts` +- runner/допоміжний засіб часу виконання ядра в `src//runtime.ts` - поверхня реєстрації API плагіна в `src/plugins/types.ts` -- підключення реєстру плагінів у `src/plugins/registry.ts` -- відкриття runtime плагіна в `src/plugins/runtime/*`, коли feature/channel - plugins мають її споживати -- helpers захоплення/тестування в `src/test-utils/plugin-registration.ts` -- перевірки володіння/контрактів у `src/plugins/contracts/registry.ts` +- wiring реєстру плагінів у `src/plugins/registry.ts` +- відкриття часу виконання плагіна в `src/plugins/runtime/*`, коли + плагіни функцій/каналів мають це споживати +- засоби фіксації/тестування в `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` - документація для операторів/плагінів у `docs/` -Якщо якоїсь із цих поверхонь бракує, це зазвичай ознака того, що можливість +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1588,7 +1586,7 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Шаблон contract test: +Шаблон контрактного тесту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1596,7 +1594,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- core володіє контрактом можливості + оркестрацією -- vendor plugins володіють реалізаціями вендорів -- feature/channel plugins споживають helpers runtime -- contract tests зберігають володіння явним +- ядро володіє контрактом можливості + оркестрацією +- vendor-плагіни володіють реалізаціями вендора +- плагіни функцій/каналів споживають допоміжні засоби часу виконання +- контрактні тести зберігають володіння явним diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index d49352f45..0bb4bc371 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -2,61 +2,62 @@ read_when: - Ви хочете створити новий plugin для OpenClaw - Вам потрібен швидкий старт для розробки plugin - - Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw + - Ви додаєте до OpenClaw новий канал, провайдера, інструмент або іншу можливість sidebarTitle: Getting Started summary: Створіть свій перший plugin для OpenClaw за лічені хвилини -title: Створення Plugins +title: Розробка Plugins x-i18n: - generated_at: "2026-04-06T00:52:25Z" + generated_at: "2026-04-06T12:43:45Z" model: gpt-5.4 provider: openai - source_hash: 9be344cb300ecbcba08e593a95bcc93ab16c14b28a0ff0c29b26b79d8249146c + source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef source_path: plugins/building-plugins.md workflow: 15 --- -# Створення Plugins +# Розробка Plugins Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, -мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, -генерація відео, отримання вебсторінок, вебпошук, інструменти агента або будь-яка -комбінація. +мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння +медіа, генерація зображень, генерація відео, web fetch, web search, інструменти +агента або будь-яка комбінація цього. Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub) або npm, а користувачі встановлять його за допомогою -`openclaw plugins install `. OpenClaw спочатку пробує ClawHub, а потім -автоматично переходить до npm. +`openclaw plugins install `. OpenClaw спочатку намагається знайти +його в ClawHub, а потім автоматично переходить до npm. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для plugin у репозиторії: клонований репозиторій і виконано `pnpm install` +- Для plugin у репозиторії: клонований репозиторій і виконаний `pnpm install` -## Який тип plugin? +## Який саме plugin? - - Підключає OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) + + Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - - Додає провайдера моделей (LLM, проксі або власну кінцеву точку) + + Додайте провайдера моделей (LLM, проксі або користувацьку кінцеву точку) - - Реєструє інструменти агента, хуки подій або сервіси — продовжуйте нижче + + Зареєструйте інструменти агента, hooks подій або сервіси — продовжуйте нижче -Якщо channel plugin є необов'язковим і може бути не встановлений під час +Якщо plugin каналу є необов’язковим і може бути не встановлений під час onboarding/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування та майстра, -яка повідомляє про вимогу встановлення і блокує реальний запис конфігурації, -доки plugin не буде встановлено. +`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптер налаштування + +майстер, яка повідомляє про вимогу встановлення й безпечно блокує реальний запис +конфігурації, доки plugin не буде встановлено. -## Швидкий старт: tool plugin +## Швидкий старт: plugin інструмента -У цьому прикладі створюється мінімальний plugin, який реєструє інструмент агента. Для channel -і provider plugins є окремі посібники, посилання на які наведено вище. +У цьому прикладі створюється мінімальний plugin, який реєструє інструмент +агента. Для plugin каналів і провайдерів є окремі посібники за посиланнями +вище. @@ -93,9 +94,9 @@ onboarding/налаштування, використовуйте `createOptiona ``` - Кожному plugin потрібен маніфест, навіть без конфігурації. Дивіться - [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти для публікації в ClawHub - розміщено в `docs/snippets/plugin-publish/`. + Кожному plugin потрібен маніфест, навіть без конфігурації. Повну схему див. + у [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub + містяться в `docs/snippets/plugin-publish/`. @@ -123,15 +124,16 @@ onboarding/налаштування, використовуйте `createOptiona }); ``` - `definePluginEntry` призначений для plugins, які не є каналами. Для каналів використовуйте - `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). - Повний список параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints). + `definePluginEntry` використовується для plugin, які не є каналами. Для + каналів використовуйте `defineChannelPluginEntry` — див. + [Channel Plugins](/uk/plugins/sdk-channel-plugins). Повний перелік параметрів + точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints). - + - **Зовнішні plugins:** виконайте перевірку та опублікуйте через ClawHub, потім встановіть: + **Зовнішні plugins:** перевірте й опублікуйте через ClawHub, потім установіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -139,8 +141,8 @@ onboarding/налаштування, використовуйте `createOptiona openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, як-от - `@myorg/openclaw-my-plugin`. + OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій + пакетів, таких як `@myorg/openclaw-my-plugin`. **Plugins у репозиторії:** розміщуйте їх у дереві робочого простору bundled plugin — вони виявляються автоматично. @@ -155,10 +157,11 @@ onboarding/налаштування, використовуйте `createOptiona Один plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`: -| Можливість | Метод реєстрації | Детальний посібник | -| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ | -| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | +| Можливість | Метод реєстрації | Детальний посібник | +| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- | +| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | +| Бекенд CLI inference | `api.registerCliBackend(...)` | [CLI Backends](/gateway/cli-backends) | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | | Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | @@ -166,43 +169,49 @@ onboarding/налаштування, використовуйте `createOptiona | Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Отримання вебсторінок | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Інструменти агента | `api.registerTool(...)` | Нижче | -| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| Хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) | -| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Інструменти агента | `api.registerTool(...)` | Нижче | +| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Hooks подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api). -Якщо ваш plugin реєструє власні методи gateway RPC, використовуйте для них -префікс, специфічний для plugin. Простори назв адміністрування ядра (`config.*`, +Якщо ваш plugin реєструє користувацькі методи gateway RPC, залишайте їх у +префіксі, специфічному для plugin. Простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди -прив’язуються до `operator.admin`, навіть якщо plugin запитує вужчу область доступу. +зіставляються з `operator.admin`, навіть якщо plugin запитує вужчу область +доступу. -Семантика guard для hook, про яку варто пам’ятати: +Варто пам’ятати про семантику захисту hooks: -- `before_tool_call`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` вважається відсутністю рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента та запитує схвалення користувача через накладення схвалення exec, кнопки Telegram, інтеракції Discord або команду `/approve` у будь-якому каналі. -- `before_install`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` вважається відсутністю рішення. -- `message_sending`: `{ cancel: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` вважається відсутністю рішення. +- `before_tool_call`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, інтеракції Discord або команду `/approve` на будь-якому каналі. +- `before_install`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом. +- `before_install`: `{ block: false }` розглядається як відсутність рішення. +- `message_sending`: `{ cancel: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення. -Команда `/approve` обробляє і схвалення exec, і схвалення plugin з обмеженим fallback: коли ідентифікатор схвалення exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через схвалення plugin. Переспрямування схвалень plugin можна налаштувати окремо через `approvals.plugin` у конфігурації. +Команда `/approve` обробляє і схвалення exec, і схвалення plugin із обмеженим +fallback: коли ідентифікатор схвалення exec не знайдено, OpenClaw повторно +пробує той самий ідентифікатор через схвалення plugin. Переспрямування +схвалення plugin можна налаштувати окремо через `approvals.plugin` у конфігурації. -Якщо власній логіці схвалення потрібно виявляти цей самий випадок обмеженого fallback, -використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime`, -замість ручного зіставлення рядків про завершення строку дії схвалення. +Якщо користувацька логіка схвалення має виявляти цей самий випадок обмеженого +fallback, використовуйте `isApprovalNotFoundError` з +`openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків +про завершення строку дії схвалення. -Докладніше див. у [семантиці рішень hook в SDK Overview](/uk/plugins/sdk-overview#hook-decision-semantics). +Докладніше див. у [SDK Overview hook decision semantics](/uk/plugins/sdk-overview#hook-decision-semantics). ## Реєстрація інструментів агента -Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди -доступними) або необов’язковими (увімкнення користувачем): +Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути +обов’язковими (завжди доступними) або необов’язковими (користувач вмикає їх за +бажанням): ```typescript register(api) { @@ -239,13 +248,13 @@ register(api) { } ``` -- Назви інструментів не повинні конфліктувати з інструментами ядра (конфліктні пропускаються) -- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до двійкових файлів -- Користувачі можуть увімкнути всі інструменти з plugin, додавши ідентифікатор plugin до `tools.allow` +- Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються) +- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів +- Користувачі можуть увімкнути всі інструменти plugin, додавши ідентифікатор plugin до `tools.allow` -## Угоди щодо імпорту +## Правила імпорту -Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/`: +Завжди імпортуйте з вузькоспрямованих шляхів `openclaw/plugin-sdk/`: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -257,70 +266,72 @@ import { ... } from "openclaw/plugin-sdk"; Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview). -Усередині вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для +У межах вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK. -Для provider plugins зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах -кореня пакета, якщо тільки межа не є справді універсальною. Поточні bundled приклади: +Для plugin провайдерів зберігайте допоміжні функції, специфічні для провайдера, +у цих barrel-файлах на рівні кореня пакета, якщо лише цей шов не є справді +загальним. Поточні bundled-приклади: -- Anthropic: обгортки потоків Claude і helper-функції для `service_tier` / beta -- OpenAI: builder-и провайдерів, helper-и моделей за замовчуванням, провайдери реального часу -- OpenRouter: builder провайдера плюс helper-и для onboarding/конфігурації +- Anthropic: обгортки потоків Claude і допоміжні функції `service_tier` / beta +- OpenAI: збирачі провайдерів, допоміжні функції моделей за замовчуванням, провайдери realtime +- OpenRouter: збирач провайдера плюс допоміжні функції onboarding/конфігурації -Якщо helper корисний лише в межах одного bundled provider package, залишайте його на цій -межі кореня пакета замість перенесення до `openclaw/plugin-sdk/*`. +Якщо допоміжна функція корисна лише в межах одного bundled-пакета провайдера, +залишайте її на цьому шві рівня кореня пакета замість того, щоб переносити її в +`openclaw/plugin-sdk/*`. -Деякі згенеровані helper-межі `openclaw/plugin-sdk/` усе ще існують для -підтримки bundled plugin і сумісності, наприклад -`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Вважайте їх зарезервованими -поверхнями, а не типовим шаблоном для нових сторонніх plugins. +Деякі згенеровані шви допоміжних функцій `openclaw/plugin-sdk/` усе +ще існують для підтримки й сумісності bundled-plugin, наприклад +`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як +зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins. ## Контрольний список перед надсиланням -**package.json** має правильні метадані `openclaw` -Маніфест **openclaw.plugin.json** присутній і коректний +**package.json** містить правильні метадані `openclaw` +Маніфест **openclaw.plugin.json** присутній і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` -Усі імпорти використовують цільові шляхи `plugin-sdk/` +Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/` Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK Тести проходять (`pnpm test -- /my-plugin/`) -`pnpm check` проходить (для plugins у репозиторії) +`pnpm check` проходить (для plugin у репозиторії) -## Тестування beta-релізів +## Тестування бета-релізів -1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів. -2. Протестуйте свій plugin на beta-тегу щойно він з’явиться. Вікно до stable-релізу зазвичай триває лише кілька годин. -3. Після тестування напишіть у гілці вашого plugin у каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. -4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і додайте мітку `beta-blocker`. Додайте посилання на issue у вашу гілку. -5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у вашу гілку в Discord. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Blocker-и з PR будуть злиті; blocker-и без PR можуть усе ж потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування. -6. Тиша означає, що все добре. Якщо ви пропустите це вікно, ваш виправлення, ймовірно, потрапить уже в наступний цикл. +1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для оголошень про релізи. +2. Протестуйте свій plugin на бета-тезі щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин. +3. Після тестування напишіть у гілці свого plugin в Discord-каналі `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. +4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у свою Discord-гілку. Учасники не можуть ставити мітки PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Blockers із PR зливаються; blockers без PR можуть вийти в реліз попри це. Мейнтейнери стежать за цими гілками під час бета-тестування. +6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваш виправлення, імовірно, потрапить до наступного циклу. -## Подальші кроки +## Наступні кроки - Створіть plugin для каналу обміну повідомленнями + Створіть plugin каналу обміну повідомленнями - Створіть plugin для провайдера моделей + Створіть plugin провайдера моделей - Довідник з карти імпортів і API реєстрації + Довідник карти імпортів і API реєстрації - TTS, пошук, subagent через api.runtime + TTS, пошук, підлеглий агент через api.runtime - Утиліти та шаблони для тестування + Утиліти та шаблони тестування - Повний довідник зі схеми маніфесту + Повний довідник схеми маніфесту ## Пов’язане -- [Plugin Architecture](/uk/plugins/architecture) — детальний розбір внутрішньої архітектури +- [Архітектура plugin](/uk/plugins/architecture) — поглиблений розбір внутрішньої архітектури - [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK - [Manifest](/uk/plugins/manifest) — формат маніфесту plugin -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — розробка plugin каналів +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — розробка plugin провайдерів diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index b1f0d5bd2..3b264dfba 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,74 +1,76 @@ --- read_when: - - Ви створюєте plugin для OpenClaw - - Вам потрібно постачати схему конфігурації plugin або налагодити помилки валідації plugin -summary: Вимоги до маніфесту plugin + JSON Schema (сувора валідація конфігурації) -title: Маніфест Plugin + - Ви створюєте плагін OpenClaw + - Вам потрібно постачати schema конфігурації плагіна або налагодити помилки валідації плагіна +summary: Маніфест плагіна + вимоги до JSON schema (сувора валідація конфігурації) +title: Маніфест плагіна x-i18n: - generated_at: "2026-04-06T00:52:57Z" + generated_at: "2026-04-06T12:44:47Z" model: gpt-5.4 provider: openai - source_hash: f6f915a761cdb5df77eba5d2ccd438c65445bd2ab41b0539d1200e63e8cf2c3a + source_hash: 15f70fd171d1aad334f01272e035e9a322a4c5c8a983180e6c38f4298b9e9158 source_path: plugins/manifest.md workflow: 15 --- -# Маніфест plugin (`openclaw.plugin.json`) +# Маніфест плагіна (openclaw.plugin.json) -Ця сторінка стосується лише **нативного маніфесту plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**. -Сумісні макети bundle описано тут: [Набори plugin](/uk/plugins/bundles). +Сумісні макети bundle описано в [Plugin bundles](/uk/plugins/bundles). Сумісні формати bundle використовують інші файли маніфесту: -- bundle Codex: `.codex-plugin/plugin.json` -- bundle Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- bundle Cursor: `.cursor-plugin/plugin.json` +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети bundle, але вони не проходять -валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію +за schema `openclaw.plugin.json`, описаною тут. -Для сумісних bundle OpenClaw зараз читає метадані bundle, а також оголошені -корені Skills, корені команд Claude, типові значення `settings.json` bundle Claude, -типові значення LSP bundle Claude і підтримувані набори hooks, якщо макет -відповідає очікуванням середовища виконання OpenClaw. +Для сумісних bundle OpenClaw наразі зчитує метадані bundle разом із оголошеними +коренями Skills, коренями команд Claude, типових значеннях Claude bundle `settings.json`, +типових значеннях Claude bundle LSP і підтримуваних наборах hook, коли макет відповідає +очікуванням середовища виконання OpenClaw. -Кожен нативний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у -**корені plugin**. OpenClaw використовує цей маніфест, щоб валідувати конфігурацію -**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються -помилками plugin і блокують валідацію конфігурації. +Кожен власний плагін OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у +**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду плагіна**. Відсутні або недійсні маніфести вважаються +помилками плагіна і блокують валідацію конфігурації. -Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin). -Щодо нативної моделі можливостей і актуальних рекомендацій із зовнішньої сумісності: -[Модель можливостей](/uk/plugins/architecture#public-capability-model). +Дивіться повний посібник із системи плагінів: [Plugins](/uk/tools/plugin). +Для моделі власних можливостей і поточних рекомендацій щодо зовнішньої сумісності: +[Capability model](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням коду -вашого plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням +коду вашого плагіна. Використовуйте його для: -- ідентичності plugin +- ідентичності плагіна - валідації конфігурації -- метаданих auth і онбордингу, які мають бути доступні без запуску середовища виконання plugin -- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання plugin -- скорочених метаданих належності до сімейств моделей, які мають автоматично активувати - plugin до завантаження середовища виконання -- статичних знімків належності можливостей, що використовуються для сумісної логіки bundled plugin і +- метаданих автентифікації та онбордингу, які мають бути доступні без запуску + середовища виконання плагіна +- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження + середовища виконання плагіна +- метаданих володіння скороченими сімействами моделей, які мають автоматично + активувати плагін до завантаження середовища виконання +- статичних знімків володіння можливостями, що використовуються для вбудованої compat-обв’язки та покриття контрактів -- метаданих конфігурації, специфічних для channel, які мають об’єднуватися в поверхні каталогу та валідації +- метаданих конфігурації каналів, специфічних для каналу, які мають зливатися в поверхні каталогу та валідації без завантаження середовища виконання -- підказок UI для конфігурації +- підказок UI конфігурації Не використовуйте його для: - реєстрації поведінки середовища виконання -- оголошення code entrypoints +- оголошення code entrypoint - метаданих встановлення npm -Для цього призначені код plugin і `package.json`. +Для цього призначені код вашого плагіна та `package.json`. ## Мінімальний приклад @@ -89,12 +91,13 @@ OpenClaw також автоматично визначає ці макети bu { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Плагін провайдера OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { "modelPrefixes": ["router-"] }, + "cliBackends": ["openrouter-cli"], "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, @@ -103,19 +106,19 @@ OpenClaw також автоматично визначає ці макети bu "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Ключ API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Ключ API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Ключ API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -134,61 +137,62 @@ OpenClaw також автоматично визначає ці макети bu ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Канонічний id plugin. Це id, що використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений типово. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin був типово вимкнений. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, що нормалізуються до цього канонічного id plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id channel, що належать цьому plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id provider, що належать цьому plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту й використовуються для автоматичного завантаження plugin до запуску середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані env для auth provider, які OpenClaw може перевіряти без завантаження коду plugin. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів auth для селекторів онбордингу, визначення preferred provider і простого зв’язування CLI flags. | -| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tools. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Зрозуміла людині назва plugin. | -| `description` | Ні | `string` | Короткий опис, що відображається в поверхнях plugin. | -| `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholder-и та підказки чутливості для полів конфігурації. | +| Field | Required | Type | What it means | +| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Yes | `string` | Канонічний id плагіна. Це id, який використовується в `plugins.entries.`. | +| `configSchema` | Yes | `object` | Вбудована JSON Schema для конфігурації цього плагіна. | +| `enabledByDefault` | No | `true` | Позначає вбудований плагін як увімкнений типово. Пропустіть його або задайте будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим типово. | +| `legacyPluginIds` | No | `string[]` | Застарілі id, які нормалізуються до цього канонічного id плагіна. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли на них посилаються автентифікація, конфігурація або model ref. | +| `kind` | No | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. | +| `channels` | No | `string[]` | Id каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. | +| `providers` | No | `string[]` | Id провайдерів, якими володіє цей плагін. | +| `modelSupport` | No | `object` | Метадані скорочених сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження плагіна до середовища виконання. | +| `cliBackends` | No | `string[]` | Id CLI-бекендів inference, якими володіє цей плагін. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. | +| `providerAuthEnvVars` | No | `Record` | Легкі метадані env автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | +| `providerAuthChoices` | No | `object[]` | Легкі метадані варіантів автентифікації для онбординг-пікерів, визначення preferred-provider та простого зв’язування прапорців CLI. | +| `contracts` | No | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `channelConfigs` | No | `Record` | Метадані конфігурації каналу, що належать маніфесту та зливаються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | No | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | +| `name` | No | `string` | Людинозрозуміла назва плагіна. | +| `description` | No | `string` | Короткий опис, який показується в поверхнях плагіна. | +| `version` | No | `string` | Інформаційна версія плагіна. | +| `uiHints` | No | `Record` | Мітки UI, placeholder і підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth. -OpenClaw читає це до завантаження середовища виконання provider. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. +OpenClaw зчитує це до завантаження середовища виконання провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| -------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id provider, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу auth, за яким виконується маршрутизація. | -| `choiceId` | Так | `string` | Стабільний id варіанта auth, що використовується в онбордингу та потоках CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | -| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але залишає можливість ручного вибору через CLI. | -| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним flag. | -| `cliFlag` | Ні | `string` | Назва CLI flag, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | +| Field | Required | Type | What it means | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Yes | `string` | Id провайдера, до якого належить цей варіант. | +| `method` | Yes | `string` | Id методу автентифікації, до якого слід маршрутизувати. | +| `choiceId` | Yes | `string` | Стабільний id варіанта автентифікації, який використовується в онбордингу та CLI-потоках. | +| `choiceLabel` | No | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | +| `choiceHint` | No | `string` | Короткий допоміжний текст для пікера. | +| `assistantPriority` | No | `number` | Менші значення сортуються раніше в інтерактивних пікерах, керованих помічником. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Ховає варіант із пікерів помічника, але все ще дозволяє ручний вибір у CLI. | +| `deprecatedChoiceIds` | No | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | +| `groupId` | No | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | +| `groupLabel` | No | `string` | Мітка цієї групи для користувача. | +| `groupHint` | No | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | No | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | No | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | No | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | No | `string` | Опис, який використовується в довідці CLI. | +| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа імен полів конфігурації до невеликих підказок рендерингу. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Ключ API", + "help": "Використовується для запитів OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -196,9 +200,9 @@ OpenClaw читає це до завантаження середовища ви } ``` -Кожна підказка поля може містити: +Підказка кожного поля може містити: -| Поле | Тип | Що воно означає | +| Field | Type | What it means | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Мітка поля для користувача. | | `help` | `string` | Короткий допоміжний текст. | @@ -209,8 +213,8 @@ OpenClaw читає це до завантаження середовища ви ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може -прочитати без імпорту середовища виконання plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +зчитати без імпортування середовища виконання плагіна. ```json { @@ -228,23 +232,23 @@ OpenClaw читає це до завантаження середовища ви } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ----------------------------------------------------------- | -| `speechProviders` | `string[]` | Id provider speech, що належать цьому plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id provider realtime-transcription, що належать цьому plugin. | -| `realtimeVoiceProviders` | `string[]` | Id provider realtime-voice, що належать цьому plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id provider media-understanding, що належать цьому plugin. | -| `imageGenerationProviders` | `string[]` | Id provider image-generation, що належать цьому plugin. | -| `videoGenerationProviders` | `string[]` | Id provider video-generation, що належать цьому plugin. | -| `webFetchProviders` | `string[]` | Id provider web-fetch, що належать цьому plugin. | -| `webSearchProviders` | `string[]` | Id provider web-search, що належать цьому plugin. | -| `tools` | `string[]` | Назви agent tools, що належать цьому plugin для перевірок bundled-контрактів. | +| Field | Type | What it means | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | Id провайдерів speech, якими володіє цей плагін. | +| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime-transcription, якими володіє цей плагін. | +| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime-voice, якими володіє цей плагін. | +| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. | +| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. | +| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. | +| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. | +| `webSearchProviders` | `string[]` | Id провайдерів web-search, якими володіє цей плагін. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для перевірок вбудованих контрактів. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли plugin channel потребує недорогих метаданих конфігурації до +Використовуйте `channelConfigs`, коли плагіну каналу потрібні легкі метадані конфігурації до завантаження середовища виконання. ```json @@ -260,32 +264,32 @@ OpenClaw читає це до завантаження середовища ви }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Підключення до homeserver Matrix", "preferOver": ["matrix-legacy"] } } } ``` -Кожен запис channel може містити: +Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholder-и/підказки чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Мітка channel, що об’єднується з поверхнями вибору та перевірки, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь перевірки та каталогу. | -| `preferOver` | `string[]` | Застарілі або нижчого пріоритету id plugin, які цей channel має випереджати в поверхнях вибору. | +| Field | Type | What it means | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/placeholder/підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що зливається в поверхні пікера та inspect, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь inspect і каталогу. | +| `preferOver` | `string[]` | Id застарілих або менш пріоритетних плагінів, які цей канал має випереджати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш plugin provider за -скороченими id моделей, як-от `gpt-5.4` або `claude-sonnet-4.6`, до завантаження середовища виконання plugin. +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера з +коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження середовища виконання плагіна. ```json { @@ -296,76 +300,76 @@ OpenClaw читає це до завантаження середовища ви } ``` -OpenClaw застосовує такий пріоритет: +OpenClaw застосовує таку пріоритетність: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику -- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes` -- якщо збігаються один небандлований plugin і один bundled plugin, перемагає небандлований - plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть provider +- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать відповідному плагіну +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований + плагін +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Field | Type | What it means | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, які перевіряються через `startsWith` для скорочених id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використайте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне +`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як -належність можливостей. +володіння можливостями. -## Маніфест і `package.json` +## Маніфест і package.json -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Для чого використовувати | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoints, обмежень встановлення, налаштування або метаданих каталогу | +| File | Use it for | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: +Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw повинен знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, entry files або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw має знати про нього до завантаження коду плагіна, помістіть його в `openclaw.plugin.json` +- якщо це стосується пакування, вхідних файлів або поведінки встановлення npm, помістіть це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля package.json, які впливають на виявлення -Деякі метадані plugin до запуску середовища виконання навмисно розміщені в `package.json` у блоці +Деякі метадані плагіна для етапу до середовища виконання навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує нативні entrypoints plugin. | -| `openclaw.setupEntry` | Легковажний entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску channel. | -| `openclaw.channel` | Недорогі метадані каталогу channel, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Недорогі метадані перевірки налаштованого стану, які можуть відповісти на питання "чи вже існує налаштування лише через env?" без завантаження повного середовища виконання channel. | -| `openclaw.channel.persistedAuthState` | Недорогі метадані перевірки збереженого auth, які можуть відповісти на питання "чи вже є активний вхід?" без завантаження повного середовища виконання channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення bundled plugin і externally published plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled plugin, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для налаштування завантажуватися до повного plugin channel під час запуску. | +| Field | What it means | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує власні entrypoint плагіна. | +| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. | +| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже щось увійшло в систему?» без завантаження повного середовища виконання каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver, наприклад `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого плагіна, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. | `openclaw.install.minHostVersion` застосовується під час встановлення та -завантаження реєстру маніфесту. Невалідні значення відхиляються; новіші, але валідні -значення пропускають plugin на старіших хостах. +завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення пропускають +плагін на старіших хостах. `openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно -не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення -відновлюватися після конкретних застарілих збоїв оновлення bundled plugin, наприклад -відсутнього шляху до bundled plugin або застарілого запису `channels.` для того самого -bundled plugin. Не пов’язані помилки конфігурації все одно блокують встановлення і направляють операторів +не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє +потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованих плагінів, таких як +відсутній шлях до вбудованого плагіна або застарілий запис `channels.` для цього самого +вбудованого плагіна. Непов’язані помилки конфігурації й далі блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані package для маленького -модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -381,13 +385,13 @@ bundled plugin. Не пов’язані помилки конфігурації } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна недорога -перевірка auth у форматі yes/no до завантаження повного plugin channel. Цільовий export має бути невеликою -функцією, яка читає лише збережений стан; не маршрутизуйте її через повний -barrel середовища виконання channel. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна легка +yes/no перевірка автентифікації до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою +функцією, яка зчитує лише збережений стан; не маршрутизуйте її через повний barrel середовища виконання +каналу. -`openclaw.channel.configuredState` має таку саму форму для недорогих перевірок -налаштованого стану лише через env: +`openclaw.channel.configuredState` має ту саму форму для легких перевірок +configured-state лише через env: ```json { @@ -403,59 +407,59 @@ barrel середовища виконання channel. } ``` -Використовуйте це, коли channel може визначити налаштований стан із env або інших малих -неruntime-джерел. Якщо перевірка потребує повного розв’язання конфігурації або реального -середовища виконання channel, залиште цю логіку в hook `config.hasConfiguredState` -plugin. +Використовуйте це, коли канал може визначити configured-state через env або інші малі +невиконувані входи. Якщо перевірці потрібне повне визначення конфігурації або реальне +середовище виконання каналу, залиште цю логіку в hook `config.hasConfiguredState` +плагіна. ## Вимоги до JSON Schema -- **Кожен plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми валідуються під час читання/запису конфігурації, а не під час виконання. +- **Кожен плагін має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Schema проходять валідацію під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено - маніфестом plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено + маніфестом плагіна. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **виявлювані** id plugin. Невідомі id є **помилками**. -- Якщо plugin встановлено, але має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, - а в Doctor і журналах відображається **попередження**. + мають посилатися на **виявлювані** id плагінів. Невідомі id є **помилками**. +- Якщо плагін встановлено, але його маніфест або schema зламані чи відсутні, + валідація завершується помилкою, і Doctor повідомляє про помилку плагіна. +- Якщо конфігурація плагіна існує, але плагін **вимкнено**, конфігурація зберігається, і + в Doctor + логах показується **попередження**. -Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration). +Дивіться [Configuration reference](/uk/gateway/configuration), щоб переглянути повну schema `plugins.*`. ## Примітки -- Маніфест **обов’язковий для нативних plugin OpenClaw**, включно із завантаженням із локальної файлової системи. -- Середовище виконання, як і раніше, завантажує модуль plugin окремо; маніфест призначений лише для +- Маніфест **обов’язковий для власних плагінів OpenClaw**, зокрема для локальних завантажень із файлової системи. +- Середовище виконання й далі завантажує модуль плагіна окремо; маніфест використовується лише для виявлення + валідації. -- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, завершаючі коми та - ключі без лапок допускаються, якщо фінальне значення все одно є object. +- Власні маніфести розбираються за допомогою JSON5, тож коментарі, кінцеві коми та + ключі без лапок приймаються, якщо фінальне значення все ще є об’єктом. - Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання власних ключів верхнього рівня сюди. -- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок auth, валідації маркерів env - та подібних поверхонь auth provider, які не повинні запускати середовище виконання plugin +- `providerAuthEnvVars` — це легкий шлях метаданих для перевірок автентифікації, валідації + env-маркерів і подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна лише для перевірки назв env. -- `providerAuthChoices` — це недорогий шлях метаданих для селекторів варіантів auth, - визначення `--auth-choice`, мапінгу preferred provider і простої реєстрації CLI flags - для онбордингу до завантаження середовища виконання provider. Метадані wizard середовища виконання, - що потребують коду provider, дивіться в - [Hooks середовища виконання provider](/uk/plugins/architecture#provider-runtime-hooks). -- Виключні типи plugin вибираються через `plugins.slots.*`. +- `providerAuthChoices` — це легкий шлях метаданих для пікерів варіантів автентифікації, + визначення `--auth-choice`, мапінгу preferred-provider і простої реєстрації прапорців CLI + до завантаження середовища виконання провайдера. Для метаданих wizard у середовищі виконання, + яким потрібен код провайдера, дивіться + [Provider runtime hooks](/uk/plugins/architecture#provider-runtime-hooks). +- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`. - `kind: "memory"` вибирається через `plugins.slots.memory`. - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` (типово: вбудований `legacy`). -- `channels`, `providers` і `skills` можна не вказувати, якщо - plugin їх не потребує. -- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які - вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо + плагіну вони не потрібні. +- Якщо ваш плагін залежить від власних модулів, задокументуйте кроки збирання та будь-які + вимоги до allowlist пакетного менеджера (наприклад, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Пов’язані сторінки +## Пов’язане -- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins -- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK +- [Building Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами +- [Plugin Architecture](/uk/plugins/architecture) — внутрішня архітектура +- [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 7f2800924..d7abea323 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - Вам потрібно знати, з якого підшляху SDK імпортувати - - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Ви хочете мати довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview summary: Карта імпортів, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-06T12:17:16Z" + generated_at: "2026-04-06T12:45:46Z" model: gpt-5.4 provider: openai - source_hash: 6dfd7a632101c2f6da8ba43b3cb4e673794ebaed00908ae897059fe115782f54 + source_hash: e045097753f33d13d570f6ce5297d2a7c0f0ad8b31515d0d9021386c8004354c source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між plugins і core. Ця сторінка є -довідником щодо **що імпортувати** і **що можна реєструвати**. +Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є +довідником про **що імпортувати** і **що можна зареєструвати**. **Шукаєте практичний посібник?** - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Channel plugin? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Provider plugin? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) -## Угода щодо імпорту +## Правило імпорту Завжди імпортуйте з конкретного підшляху: @@ -36,318 +36,318 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий +Кожен підшлях — це невеликий, самодостатній модуль. Це забезпечує швидкий запуск і запобігає проблемам із циклічними залежностями. Для специфічних для -каналів допоміжних функцій entry/build віддавайте перевагу -`openclaw/plugin-sdk/channel-core`; використовуйте `openclaw/plugin-sdk/core` -для ширшої узагальненої поверхні та спільних допоміжних функцій, таких як +каналів допоміжних функцій точки входу/збирання віддавайте перевагу +`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +ширшої umbrella-поверхні та спільних допоміжних функцій, таких як `buildChannelConfigSchema`. -Не додавайте і не використовуйте іменовані за provider зручні шари, такі як -`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +Не додавайте і не використовуйте convenience-шви, названі на честь провайдерів, +такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шари з брендуванням channel. Bundled plugins мають компонувати -загальні підшляхи SDK у власних barrels `api.ts` або `runtime-api.ts`, а core -має або використовувати ці локальні barrels plugin, або додавати вузький -загальний контракт SDK, коли потреба справді є міжканальною. +допоміжні шви з брендингом каналів. Bundled plugins мають комбінувати загальні +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро +має або використовувати ці plugin-локальні barrel-файли, або додавати вузький +загальний контракт SDK, якщо потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір допоміжних шарів +Згенерована карта експортів усе ще містить невеликий набір допоміжних швів для bundled-plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці підшляхи існують лише для підтримки bundled-plugin і сумісності; їх навмисно -не включено до загальної таблиці нижче, і вони не є рекомендованим шляхом +не включено до спільної таблиці нижче, і вони не є рекомендованим шляхом імпорту для нових сторонніх plugins. ## Довідник підшляхів Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із -понад 200 підшляхів знаходиться в `scripts/lib/plugin-sdk-entrypoints.json`. +понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. Зарезервовані допоміжні підшляхи bundled-plugin усе ще з’являються в цьому -згенерованому списку. Розглядайте їх як деталі реалізації або поверхні -сумісності, якщо тільки сторінка документації явно не позначає одну з них як -публічну. +згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності, +якщо лише якась сторінка документації явно не оголошує один із них публічним. -### Вхід plugin +### Точка входу plugin -| Subpath | Ключові експорти | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Підшлях | Ключові експорти | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Subpath | Ключові експорти | + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування, запити allowlist, побудовники статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування, запити allowlist, збирачі статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні функції для конфігурації та action gate мультиакаунтів, допоміжні функції fallback для акаунта за замовчуванням | + | `plugin-sdk/account-core` | Допоміжні функції багатoакаунтної конфігурації/керування обмеженнями дій, допоміжні функції fallback для акаунта за замовчуванням | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні функції пошуку акаунта + fallback до акаунта за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції для списку акаунтів/дій із акаунтами | + | `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні функції fallback за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції списків акаунтів/дій над акаунтами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із fallback на bundled contract | + | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із fallback на bundled-contract | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршрутизації вхідних подій + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису й диспетчеризації вхідних повідомлень | - | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення target | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції вхідних маршрутів + побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису й диспетчеризації вхідних подій | + | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні функції для вихідної ідентичності та send delegate | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції життєвого циклу та адаптерів thread-binding | - | `plugin-sdk/agent-media-payload` | Застарілий builder payload медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки conversation/thread, pairing і configured-binding | + | `plugin-sdk/outbound-runtime` | Допоміжні функції вихідної ідентичності/делегата надсилання | + | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл thread-binding і допоміжні функції адаптера | + | `plugin-sdk/agent-media-payload` | Legacy-збирач медіапейлоада агента | + | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмови/thread, pairing і configured-binding | | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція snapshot конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні функції визначення policy груп під час runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні функції snapshot/summary статусу каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу | + | `plugin-sdk/runtime-group-policy` | Допоміжні функції розв’язання групової політики runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні функції snapshot/summary стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin | - | `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо доступу груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні функції авторизації/захисту direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/зведення payload інтерактивних відповідей | + | `plugin-sdk/allowlist-config-edit` | Допоміжні функції читання/редагування конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні функції auth/guard для direct-DM | + | `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/скорочення інтерактивного reply payload | | `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, допоміжні функції envelope | - | `plugin-sdk/channel-send-result` | Типи результатів reply | + | `plugin-sdk/channel-send-result` | Типи результату reply | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення target | - | `plugin-sdk/channel-contract` | Типи контрактів channel | - | `plugin-sdk/channel-feedback` | Налаштування feedback/reaction | + | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/channel-contract` | Типи контракту каналу | + | `plugin-sdk/channel-feedback` | Зв’язування feedback/reaction | - - | Subpath | Ключові експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted provider, сумісних з OpenAI | - | `plugin-sdk/provider-auth-runtime` | Допоміжні функції визначення API key під час runtime для provider plugins | - | `plugin-sdk/provider-auth-api-key` | Допоміжні функції onboarding/profile-write для API key, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний builder auth-result для OAuth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для provider plugins | - | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку env vars для авторизації provider | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime-розв’язання API-ключів для plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції onboarding/запису профілю API-ключа, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth auth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища для auth провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, допоміжні функції endpoint provider і нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі replay-policy, допоміжні функції endpoint провайдерів і нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/capability endpoint provider | - | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування provider web-fetch | - | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/конфігурації provider web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | + | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей endpoint провайдера | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування web-fetch провайдера | + | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/конфігурації web-search провайдера | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібні | | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні функції wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні функції patch конфігурації onboarding | + | `plugin-sdk/provider-onboard` | Допоміжні функції виправлення конфігурації onboarding | | `plugin-sdk/global-singleton` | Допоміжні функції process-local singleton/map/cache | - - | Subpath | Ключові експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, допоміжні функції авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції визначення approver та action-auth у тому ж чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання approver і auth дій у межах того самого чату | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції native exec approval profile/filter | + | `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval | | `plugin-sdk/approval-native-runtime` | Допоміжні функції native approval target + account-binding | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді на approval exec/plugin | - | `plugin-sdk/command-auth-native` | Допоміжні функції native command auth + native session-target | - | `plugin-sdk/command-detection` | Спільні допоміжні функції визначення команд | - | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні функції command-surface | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply payload для approval exec/plugin | + | `plugin-sdk/command-auth-native` | Native command auth + допоміжні функції native session-target | + | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | + | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні функції поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, DM gating, external-content і збору секретів | + | `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, обмеження DM, зовнішнього контенту та збирання секретів | | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватних мереж | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF та політики SSRF | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF і політики SSRF | | `plugin-sdk/secret-input` | Допоміжні функції розбору secret input | | `plugin-sdk/webhook-ingress` | Допоміжні функції webhook request/target | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції для розміру body request/timeout | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла request/тайм-ауту | - | Subpath | Ключові експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широка поверхня допоміжних функцій runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції runtime env, logger, timeout, retry і backoff | + | `plugin-sdk/runtime` | Широкі допоміжні функції runtime/логування/резервних копій/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env runtime, logger, timeout, retry і backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції для команд/hook/http/interactive plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні функції pipeline для webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні функції exec процесів | - | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, wait і version | - | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта gateway і patch статусу каналу | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції plugin command/hook/http/interactive | + | `plugin-sdk/hook-runtime` | Спільні допоміжні функції webhook та внутрішнього hook pipeline | + | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy-імпорту/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні функції виконання process | + | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування та версій | + | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway і виправлення статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація назви/опису команд Telegram і перевірки на дублікати/конфлікти, навіть коли поверхня bundled Telegram contract недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні функції approval exec/plugin, builder-и approval capability, допоміжні функції auth/profile, допоміжні функції native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для inbound/reply, chunking, dispatch, heartbeat, planner reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize reply | - | `plugin-sdk/reply-history` | Спільні допоміжні функції коротковіконної history reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки дублікатів/конфліктів, навіть коли bundled Telegram contract surface недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні функції approval exec/plugin, збирачі approval-capability, auth/profile, native routing/runtime helpers | + | `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для inbound/reply, chunking, dispatch, heartbeat, планувальник reply | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize для reply | + | `plugin-sdk/reply-history` | Спільні допоміжні функції короткого вікна історії reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown | | `plugin-sdk/session-store-runtime` | Допоміжні функції шляху session store + updated-at | - | `plugin-sdk/state-paths` | Допоміжні функції шляху до каталогу state/OAuth | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів до каталогів state/OAuth | | `plugin-sdk/routing` | Допоміжні функції route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні функції summary статусу channel/account, значення runtime-state за замовчуванням і допоміжні функції метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції визначення target | - | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/string | - | `plugin-sdk/request-url` | Витягування URL-адрес рядків із fetch/request-like input | - | `plugin-sdk/run-command` | Запуск команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витягування канонічних полів target відправлення з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів до тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні функції subsystem logger і redaction | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму таблиць Markdown | - | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису JSON state | - | `plugin-sdk/file-lock` | Допоміжні функції повторно-вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні функції дискового dedupe cache | + | `plugin-sdk/status-helpers` | Спільні допоміжні функції summary стану каналу/акаунта, типові значення runtime-state і допоміжні функції метаданих issues | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції розв’язання цілей | + | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних входів | + | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів інструмента | + | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні функції subsystem logger і редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму markdown-таблиць | + | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису JSON-стану | + | `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні функції disk-backed dedupe cache | | `plugin-sdk/acp-runtime` | Допоміжні функції ACP runtime/session і reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Нестрогий читач boolean-параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції визначення збігу небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні функції device bootstrap і токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel і допоміжні функції статусу | - | `plugin-sdk/models-provider-runtime` | Допоміжні функції відповіді `/models` command/provider | - | `plugin-sdk/skill-commands-runtime` | Допоміжні функції переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize native commands | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції визначення endpoint Z.A.I | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | + | `plugin-sdk/boolean-param` | Зчитувач нечітких boolean-параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні функції bootstrap пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу та допоміжні функції статусу | + | `plugin-sdk/models-provider-runtime` | Допоміжні функції команд `/models` і reply провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні функції виведення списку skill-команд | + | `plugin-sdk/native-command-registry` | Допоміжні функції native command registry/build/serialize | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.AI | | `plugin-sdk/infra-runtime` | Допоміжні функції system event/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого cache | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні функції класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні функції wrapped fetch, proxy і pinned lookup | + | `plugin-sdk/error-runtime` | Допоміжні функції графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Обгорнуті допоміжні функції fetch, proxy і pinned lookup | | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і запуску retry | - | `plugin-sdk/agent-runtime` | Допоміжні функції каталогу/ідентичності/workspace агента | - | `plugin-sdk/directory-runtime` | Запит до каталогу на основі config/dedup | + | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні функції dir/identity/workspace агента | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Subpath | Ключові експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа плюс builder-и payload медіа | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover для генерації медіа, вибір candidate і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи provider для розуміння медіа плюс експорти допоміжних функцій для provider для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції для text/markdown/logging, такі як видалення видимого асистенту тексту, рендеринг/chunking/table helpers markdown, redaction helpers, directive-tag helpers і safe-text utilities | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа плюс збирачі media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа плюс експорти допоміжних функцій зображень/аудіо для провайдерів | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/логування, такі як видалення видимого для асистента тексту, рендер/chunking/table helpers для markdown, допоміжні функції редагування чутливих даних, тегів директив і safe-text utilities | | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech provider плюс експорти допоміжних функцій для provider для directive, registry і validation | - | `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive і допоміжні функції normalізації | - | `plugin-sdk/realtime-transcription` | Типи provider для realtime transcription і допоміжні функції registry | - | `plugin-sdk/realtime-voice` | Типи provider для realtime voice і допоміжні функції registry | - | `plugin-sdk/image-generation` | Типи provider для генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції registry | - | `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошуку provider і розбору model-ref | - | `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку provider і розбору model-ref | - | `plugin-sdk/webhook-targets` | Допоміжні функції реєстру webhook target і встановлення route | + | `plugin-sdk/speech` | Типи speech-провайдера плюс експорти допоміжних функцій директив, реєстру та валідації для провайдерів | + | `plugin-sdk/speech-core` | Спільні типи speech-провайдера, реєстр, директиви та допоміжні функції нормалізації | + | `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі та допоміжні функції реєстру | + | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні функції реєстру | + | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції реєстру | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошуку провайдера та розбору model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref | + | `plugin-sdk/webhook-targets` | Допоміжні функції реєстру webhook target і встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху webhook | | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | + | `plugin-sdk/zod` | Повторний експорт `zod` для користувачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Subpath | Ключові експорти | + + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Допоміжна поверхня bundled memory-core для manager/config/file/CLI helpers | - | `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексування/пошуку memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine memory host | - | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine memory host | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine memory host | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine memory host | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal memory host | - | `plugin-sdk/memory-core-host-query` | Допоміжні функції query memory host | - | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret memory host | - | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій memory host | - | `plugin-sdk/memory-core-host-status` | Допоміжні функції status memory host | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції CLI runtime memory host | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime memory host | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції file/runtime memory host | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора alias для допоміжних функцій core runtime memory host | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора alias для допоміжних функцій журналу подій memory host | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора alias для допоміжних функцій file/runtime memory host | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції managed-markdown для plugins, суміжних із memory | - | `plugin-sdk/memory-host-search` | Активна runtime facade memory для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора alias для допоміжних функцій status memory host | - | `plugin-sdk/memory-lancedb` | Допоміжна поверхня bundled memory-lancedb | + | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для менеджера/конфігурації/файлів/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексації/пошуку в пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні функції секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції runtime CLI хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних функцій core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних функцій журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції керованого markdown для plugins, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Активний runtime-фасад пам’яті для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних функцій статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb | - | Family | Поточні підшляхи | Призначення | + | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin (`browser-support` залишається barrel сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Допоміжна/runtime surface bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Допоміжна/runtime surface bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Допоміжна surface bundled IRC | - | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари сумісності/допоміжні шари bundled channel | - | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні шари bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin (`browser-support` лишається barrel-файлом сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних функцій/runtime bundled Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime bundled LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій bundled IRC | + | Допоміжні функції для конкретних каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні шви bundled-каналів | + | Допоміжні функції для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні шви bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Callback `register(api)` отримує об’єкт `OpenClawPluginApi` із такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Method | Що реєструє | -| ------------------------------------------------ | ------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | +| Метод | Що реєструє | +| ----------------------------------------------- | ------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerCliBackend(...)` | Локальний backend CLI inference | | `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція realtime | -| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії realtime | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Двосторонні голосові сесії в реальному часі | | `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | | `api.registerImageGenerationProvider(...)` | Генерація зображень | | `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Provider для web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Пошук у вебі | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Web search | ### Інструменти та команди -| Method | Що реєструє | -| ------------------------------- | -------------------------------------------- | +| Метод | Що реєструє | +| ------------------------------ | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацьку команду (в оминання LLM) | ### Інфраструктура -| Method | Що реєструє | -| ---------------------------------------------- | -------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook події | -| `api.registerHttpRoute(params)` | HTTP endpoint gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний corpus пошуку/читання memory | +| Метод | Що реєструє | +| --------------------------------------------- | ------------------------------------ | +| `api.registerHook(events, handler, opts?)` | Hook події | +| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway | +| `api.registerGatewayMethod(name, handler)` | Метод Gateway RPC | +| `api.registerCli(registrar, opts?)` | Підкоманду CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | -Зарезервовані простори імен адміністратора core (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити -вужчу область gateway method. Віддавайте перевагу префіксам, специфічним для plugin, для -методів, що належать plugin. +Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, +`wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin +намагається призначити методу gateway вужчу область доступу. Для методів, що +належать plugin, віддавайте перевагу специфічним для plugin префіксам. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: - `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для - довідки кореневого CLI, маршрутизації та відкладеної реєстрації CLI plugin +- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, маршрутизації та лінивої реєстрації CLI plugin -Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною у звичайному -шляху кореневого CLI, надайте `descriptors`, які покривають кожен корінь -команди верхнього рівня, відкритий цим registrar. +Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в +звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен +корінь команди верхнього рівня, що експонується цим registrar. ```typescript api.registerCli( @@ -359,7 +359,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -367,113 +367,122 @@ api.registerCli( ); ``` -Використовуйте лише `commands` тільки тоді, коли вам не потрібна лінива -реєстрація кореневого CLI. Цей eager-шлях сумісності все ще підтримується, -але він не встановлює placeholders на основі descriptors для лінивого -завантаження під час парсингу. +Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореня +CLI. Цей eager-шлях сумісності все ще підтримується, але він не встановлює +placeholder-и на основі descriptor для лінивого завантаження під час парсингу. + +### Реєстрація CLI backend + +`api.registerCliBackend(...)` дає plugin змогу володіти типовою конфігурацією +локального backend AI CLI, такого як `codex-cli`. + +- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`. +- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх типової конфігурації plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після злиття (наприклад, для нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Method | Що реєструє | -| ------------------------------------------ | ----------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) | -| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt memory | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime memory | +| Метод | Що реєструє | +| ----------------------------------------- | ----------------------------------- | +| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один) | +| `api.registerMemoryPromptSection(builder)` | Збирач розділу prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding для memory +### Адаптери embedding пам’яті -| Method | Що реєструє | -| ---------------------------------------------- | ------------------------------------------------ | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin | +| Метод | Що реєструє | +| --------------------------------------------- | -------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` є ексклюзивними для plugins memory. -- `registerMemoryEmbeddingProvider` дозволяє активному plugin memory реєструвати один - або кілька id адаптерів embedding (наприклад `openai`, `gemini` або - custom id, визначений plugin). -- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, визначається відносно цих - зареєстрованих id адаптерів. + `registerMemoryRuntime` є ексклюзивними для plugins пам’яті. +- `registerMemoryEmbeddingProvider` дає активному plugin пам’яті змогу + реєструвати один або більше id адаптерів embedding (наприклад `openai`, + `gemini` або користувацький id, визначений plugin). +- Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, зіставляється з цими + зареєстрованими id адаптерів. ### Події та життєвий цикл -| Method | Що робить | -| -------------------------------------------- | -------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Callback прив’язки conversation | +| Метод | Що робить | +| ------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | ### Семантика рішень hook -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перехоплює dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропущений `cancel`), а не як перевизначення. ### Поля об’єкта API -| Field | Type | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія plugin (необов’язково) | -| `api.description` | `string?` | Опис plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела plugin | -| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime в пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Специфічна для plugin конфігурація з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні функції runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з областю дії (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня plugin | +| Поле | Тип | Опис | +| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Ідентифікатор plugin | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія plugin (необов’язково) | +| `api.description` | `string?` | Опис plugin (необов’язково) | +| `api.source` | `string` | Шлях до джерела plugin | +| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime у пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для plugin, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Розв’язує шлях відносно кореня plugin | -## Угода щодо внутрішніх модулів +## Внутрішня угода для модулів -Усередині свого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні експорти runtime + runtime-api.ts # Лише внутрішні runtime-експорти index.ts # Точка входу plugin - setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) + setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. Facade-loaded публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер надають -перевагу активному snapshot конфігурації runtime, коли OpenClaw уже запущено. -Якщо snapshot runtime ще не існує, вони використовують fallback до визначеного -на диску файлу конфігурації. +`index.ts`, `setup-entry.ts` та подібні публічні файли входу) тепер віддають +перевагу активному snapshot конфігурації runtime, якщо OpenClaw уже запущено. +Якщо snapshot runtime ще не існує, вони використовують fallback до розв’язаного +файла конфігурації на диску. -Provider plugins також можуть відкривати вузький локальний barrel контракту plugin, -коли допоміжна функція навмисно є специфічною для provider і поки що не належить -до загального підшляху SDK. Поточний bundled-приклад: provider Anthropic тримає -свої допоміжні функції потоку Claude у власному публічному шарі `api.ts` / `contract-api.ts` -замість просування логіки beta-header Anthropic і `service_tier` у загальний -контракт `plugin-sdk/*`. +Plugins провайдерів також можуть експортувати вузький plugin-локальний contract +barrel, коли допоміжна функція навмисно є специфічною для провайдера і поки що +не належить до загального підшляху SDK. Поточний bundled-приклад: провайдер +Anthropic зберігає свої допоміжні функції потоків Claude у власному публічному +шві `api.ts` / `contract-api.ts` замість перенесення логіки Anthropic beta-header +і `service_tier` до загального контракту `plugin-sdk/*`. Інші поточні bundled-приклади: -- `@openclaw/openai-provider`: `api.ts` експортує builder-и provider, - допоміжні функції моделей за замовчуванням і builder-и provider realtime -- `@openclaw/openrouter-provider`: `api.ts` експортує builder provider, а також - допоміжні функції onboarding/config +- `@openclaw/openai-provider`: `api.ts` експортує builder-и провайдерів, + допоміжні функції моделей за замовчуванням і builder-и realtime-провайдерів +- `@openclaw/openrouter-provider`: `api.ts` експортує builder провайдера та + допоміжні функції onboarding/конфігурації Production-код extension також має уникати імпортів - `openclaw/plugin-sdk/`. Якщо допоміжна функція справді спільна, - перенесіть її до нейтрального підшляху SDK, наприклад + `openclaw/plugin-sdk/`. Якщо допоміжна функція справді є + спільною, перенесіть її до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на capability, замість жорсткого зв’язування двох plugins. + capability-орієнтованої поверхні, замість жорсткого зв’язування двох plugins. ## Пов’язане @@ -482,5 +491,5 @@ Provider plugins також можуть відкривати вузький л - [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` - [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації - [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint -- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей +- [SDK Migration](/uk/plugins/sdk-migration) — міграція з застарілих поверхонь +- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура і модель можливостей diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 46d86e4bb..9a0c9a784 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,30 +1,30 @@ --- read_when: - Ви створюєте новий плагін постачальника моделей - - Ви хочете додати сумісний з OpenAI проксі або власну LLM до OpenClaw - - Вам потрібно зрозуміти автентифікацію постачальників, каталоги та runtime-хуки + - Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw + - Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime hooks sidebarTitle: Provider Plugins summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw title: Створення плагінів постачальників x-i18n: - generated_at: "2026-04-06T12:29:08Z" + generated_at: "2026-04-06T12:45:52Z" model: gpt-5.4 provider: openai - source_hash: 21c888a988f6128f2c77b73ee4962ae7ad7b8a6c1b7d302610788c81ad25b0db + source_hash: 89e7402742c87cb31265db1d98b34ca17ba57ad1c61952fa8c7da834306986f5 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Створення плагінів постачальників -У цьому посібнику розглянуто створення плагіна постачальника, який додає -постачальника моделей (LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей, -автентифікацією за API-ключем і динамічним визначенням моделей. +Цей посібник пояснює, як створити плагін постачальника, який додає до OpenClaw +постачальника моделей (LLM). Наприкінці у вас буде постачальник із каталогом моделей, +автентифікацією через API key і динамічним визначенням моделей. - Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою структурою - пакета та налаштуванням маніфесту. + Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте + [Початок роботи](/uk/plugins/building-plugins) для базової структури пакета + та налаштування маніфесту. ## Покроковий розбір @@ -88,10 +88,10 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов’язковим - і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ідентифікаторами моделей, - такими як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте + і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ID моделей + на кшталт `acme-large` ще до появи runtime hooks. Якщо ви публікуєте постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build` - є обов’язковими в `package.json`. + у `package.json` є обов’язковими. @@ -171,9 +171,9 @@ x-i18n: `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Для вбудованих постачальників, які реєструють лише одного текстового постачальника з - автентифікацією за API-ключем плюс один runtime на основі каталогу, краще використовувати вужчий хелпер - `defineSingleProviderPluginEntry(...)`: + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією через API key + і одним runtime на основі каталогу, надавайте перевагу вужчому + хелперу `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -208,25 +208,24 @@ x-i18n: }); ``` - Якщо ваш потік автентифікації також має змінювати `models.providers.*`, псевдоніми та - модель агента за замовчуванням під час онбордингу, використовуйте preset-хелпери з + Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми та + типову модель агента під час onboarding, використовуйте preset-хелпери з `openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери: `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативна кінцева точка постачальника підтримує потокові блоки usage у - звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з - `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко прописаним - перевіркам ідентифікатора постачальника. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей - кінцевої точки, тож нативні кінцеві точки у стилі Moonshot/DashScope також - зможуть підключатися, навіть якщо плагін використовує власний ідентифікатор постачальника. + Коли нативний endpoint постачальника підтримує streamed usage blocks на + звичайному транспорті `openai-completions`, надавайте перевагу спільним хелперам каталогів із + `openclaw/plugin-sdk/provider-catalog-shared` замість жорстко закодованих перевірок `provider-id`. Функції + `supportsNativeStreamingUsageCompat(...)` і + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, тож + нативні endpoint у стилі Moonshot/DashScope також можуть підключатися, навіть якщо плагін використовує власний `provider id`. - Якщо ваш постачальник приймає довільні ідентифікатори моделей (наприклад, проксі або маршрутизатор), + Якщо ваш постачальник приймає довільні ID моделей (наприклад, проксі або маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -249,16 +248,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - прогрівання — після його завершення `resolveDynamicModel` виконується знову. + попереднього прогріву — після його завершення `resolveDynamicModel` буде запущено знову. - - Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки - поступово, у міру того як це потрібно вашому постачальнику. + + Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks + поступово, у міру того як цього вимагатиме ваш постачальник. - Спільні builder-хелпери тепер охоплюють найпоширеніші сімейства replay/tool-compat, - тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо: + Спільні builder-хелпери тепер охоплюють найтиповіші сімейства replay/tool-compat, + тому плагінам зазвичай не потрібно вручну підключати кожен hook окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -282,15 +281,15 @@ x-i18n: | Family | Що воно підключає | | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для транспортів, сумісних з OpenAI, включно з санітизацією ідентифікаторів викликів інструментів, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де вона потрібна транспорту | - | `anthropic-by-model` | Політика replay з урахуванням Claude, що обирається за `modelId`, тому транспорти Anthropic-message отримують очищення thinking-блоків, специфічне для Claude, лише коли визначена модель справді є ідентифікатором Claude | - | `google-gemini` | Нативна політика replay для Gemini плюс bootstrap-санітизація replay і режим tagged reasoning-output | - | `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через сумісні з OpenAI проксі-транспорти; не вмикає нативну валідацію replay Gemini або bootstrap-перезаписування | - | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-блоків лише для Claude залишається обмеженим стороною Anthropic | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною перевіркою Gemini-turn там, де цього потребує транспорт | + | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель дійсно має Claude id | + | `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим tagged reasoning-output | + | `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну перевірку replay Gemini або переписування bootstrap | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | Реальні вбудовані приклади: - - `google`: `google-gemini` + - `google` і `google-gemini-cli`: `google-gemini` - `openrouter`, `kilocode`, `opencode` і `opencode-go`: `passthrough-gemini` - `amazon-bedrock` і `anthropic-vertex`: `anthropic-by-model` - `minimax`: `hybrid-anthropic-openai` @@ -300,17 +299,17 @@ x-i18n: | Family | Що воно підключає | | --- | --- | - | `google-thinking` | Нормалізація payload thinking Gemini у спільному stream-шляху | - | `kilocode-thinking` | Обгортка reasoning Kilo у спільному proxy stream-шляху, де `kilo/auto` та непідтримувані proxy reasoning id пропускають інжектований thinking | - | `moonshot-thinking` | Мапінг бінарного payload native-thinking Moonshot з config + рівня `/think` | - | `minimax-fast-mode` | Перезапис моделі fast-mode MiniMax у спільному stream-шляху | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution-заголовки, `/fast`/`serviceTier`, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, із централізованою обробкою пропусків для непідтримуваних моделей/`auto` | - | `tool-stream-default-on` | Увімкнена за замовчуванням обгортка `tool_stream` для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнено явно | + | `google-thinking` | Нормалізація payload thinking Gemini на спільному stream-шляху | + | `kilocode-thinking` | Обгортка reasoning Kilo на спільному proxy stream-шляху, де `kilo/auto` і непідтримувані proxy reasoning id пропускають інжектований thinking | + | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot з конфігурації + рівня `/think` | + | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному stream-шляху | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution headers, `/fast`/`serviceTier`, text verbosity, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена типово, для постачальників на кшталт Z.AI, яким потрібен streaming інструментів, якщо його явно не вимкнено | Реальні вбудовані приклади: - - `google`: `google-thinking` + - `google` і `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` - `moonshot`: `moonshot-thinking` - `minimax` і `minimax-portal`: `minimax-fast-mode` @@ -319,8 +318,8 @@ x-i18n: - `zai`: `tool-stream-default-on` `openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств replay - плюс спільні хелпери, з яких ці сімейства побудовані. Поширені публічні - експорти включають: + плюс спільні хелпери, з яких ці сімейства побудовані. Поширені публічні експорти + включають: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` @@ -328,13 +327,13 @@ x-i18n: `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` і `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - хелпери replay для Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` + - хелпери replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` і `resolveTaggedReasoningOutputMode()` - - хелпери кінцевих точок/моделей, такі як `resolveProviderEndpoint(...)`, + - хелпери endpoint/model, такі як `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` надає і builder сімейств, і + `openclaw/plugin-sdk/provider-stream` надає і builder сімейства, і публічні wrapper-хелпери, які ці сімейства повторно використовують. Поширені публічні експорти включають: @@ -354,45 +353,45 @@ x-i18n: приклад: `@openclaw/anthropic-provider` експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і - низькорівневі builder-и обгорток Anthropic зі свого публічного seam `api.ts` / + низькорівневі builder-и обгорток Anthropic зі свого публічного шва `api.ts` / `contract-api.ts`. Ці хелпери залишаються специфічними для Anthropic, оскільки - також кодують обробку Claude OAuth beta і gating `context1m`. + вони також кодують обробку Claude OAuth beta і gating `context1m`. - Інші вбудовані постачальники також тримають специфічні для транспорту обгортки локально, коли - цю поведінку неможливо чисто поділити між сімействами. Поточний приклад: вбудований + Інші вбудовані постачальники також залишають transport-специфічні обгортки локальними, коли + цю поведінку неможливо чисто розділити між сімействами. Поточний приклад: вбудований плагін xAI зберігає нативне формування xAI Responses у власному - `wrapStreamFn`, включно з перезаписуванням псевдонімів `/fast`, `tool_stream` - за замовчуванням, очищенням непідтримуваних strict-tool і видаленням payload reasoning, - специфічного для xAI. + `wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, типовим `tool_stream`, + очищенням непідтримуваних strict-tool і видаленням reasoning-payload, + специфічним для xAI. `openclaw/plugin-sdk/provider-tools` наразі надає одне спільне сімейство tool-schema плюс спільні хелпери schema/compat: - - `ProviderToolCompatFamily` документує наявний сьогодні інвентар спільних сімейств. - - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення Gemini schema + - `ProviderToolCompatFamily` документує наявний перелік спільних сімейств. + - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів. - `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)` - є базовими публічними Gemini schema-хелперами. - - `resolveXaiModelCompatPatch()` повертає вбудований compat-патч xAI: - `toolSchemaProfile: "xai"`, непідтримувані ключові слова schema, нативну підтримку - `web_search` і декодування аргументів викликів інструментів із HTML-сутностями. - - `applyXaiModelCompat(model)` застосовує той самий compat-патч xAI до - визначеної моделі, перш ніж вона потрапить до runner-а. + — це базові публічні хелпери схем Gemini. + - `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI: + `toolSchemaProfile: "xai"`, непідтримувані ключові слова схеми, нативну + підтримку `web_search` і декодування HTML-entity аргументів виклику інструментів. + - `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до + визначеної моделі до того, як вона потрапить до runner. Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс - `contributeResolvedModelCompat`, щоб зберегти метадані compat у власності - постачальника, а не жорстко прописувати правила xAI в core. + `contributeResolvedModelCompat`, щоб ці compat-метадані залишалися у + власності постачальника, а не були жорстко закодовані в core. - Той самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників: + Такий самий шаблон package-root також підтримує інші вбудовані постачальники: - `@openclaw/openai-provider`: `api.ts` експортує builder-и постачальника, - хелпери моделі за замовчуванням і builder-и realtime-постачальника + хелпери типових моделей і builder-и realtime provider - `@openclaw/openrouter-provider`: `api.ts` експортує builder - постачальника плюс хелпери онбордингу/конфігурації + постачальника плюс хелпери onboarding/config - - Для постачальників, яким потрібен обмін токенів перед кожним викликом inference: + + Для постачальників, яким потрібен обмін токенами перед кожним викликом inference: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -406,7 +405,7 @@ x-i18n: ``` - Для постачальників, яким потрібні користувацькі заголовки запитів або зміни тіла запиту: + Для постачальників, яким потрібні користувацькі заголовки запиту або модифікації тіла: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -424,8 +423,8 @@ x-i18n: ``` - Для постачальників, яким потрібні нативні заголовки або метадані запитів/сесій на - узагальнених HTTP- або WebSocket-транспортах: + Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в + універсальних HTTP- або WebSocket-транспортах: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -445,8 +444,8 @@ x-i18n: }), ``` - - Для постачальників, які надають дані usage/білінгу: + + Для постачальників, які надають дані про використання/білінг: ```typescript resolveUsageAuth: async (ctx) => { @@ -460,75 +459,75 @@ x-i18n: - - OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2-3: + + OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2–3: | # | Hook | Коли використовувати | | --- | --- | --- | - | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | - | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization конфігурації | - | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів ідентифікаторів моделей перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним складанням моделі | + | 1 | `catalog` | Каталог моделей або типові значення `base URL` | + | 2 | `applyConfigDefaults` | Глобальні типові значення, що належать постачальнику, під час матеріалізації конфігурації | + | 3 | `normalizeModelId` | Очищення псевдонімів застарілих/preview model id перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Перезаписування native streaming-usage compat для config-постачальників | - | 7 | `resolveConfigApiKey` | Визначення автентифікації за env-marker, що належить постачальнику | - | 8 | `resolveSyntheticAuth` | Синтетична автентифікація local/self-hosted або на основі config | - | 9 | `shouldDeferSyntheticProfileAuth` | Опустити синтетичні placeholder-и збереженого профілю нижче за env/config auth | - | 10 | `resolveDynamicModel` | Приймати довільні ідентифікатори моделей upstream | + | 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для config providers | + | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або конфігураційного сценарію | + | 9 | `shouldDeferSyntheticProfileAuth` | Зниження пріоритету синтетичних placeholder-ів збереженого профілю відносно env/config auth | + | 10 | `resolveDynamicModel` | Приймати довільні upstream model ID | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | - | 12 | `normalizeResolvedModel` | Перезаписування транспорту перед runner-ом | + | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші - плагіни постачальників, здатні обробляти хуки, доки один із них справді не змінить конфігурацію. - Якщо жоден хук постачальника не перепише підтримуваний запис конфігурації сімейства Google, - усе одно буде застосовано вбудований нормалізатор конфігурації Google. - - `resolveConfigApiKey` використовує хук постачальника, якщо він наданий. Вбудований + - `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші + плагіни постачальників, здатні працювати з hooks, доки хтось із них справді не змінить конфігурацію. + Якщо жоден provider hook не перепише підтримуваний запис конфігурації сімейства Google, + усе одно застосовується вбудований normalizer конфігурації Google. + - `resolveConfigApiKey` використовує hook постачальника, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, - хоча runtime-автентифікація Bedrock досі використовує стандартний - AWS SDK chain. + навіть попри те, що runtime auth Bedrock і далі використовує типовий + ланцюжок AWS SDK. | 13 | `contributeResolvedModelCompat` | Compat-прапорці для вендорських моделей за іншим сумісним транспортом | - | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення схеми інструментів, що належить постачальнику, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належить постачальнику | - | 17 | `resolveReasoningOutputMode` | Контракт reasoning-output: tagged чи native | - | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | + | 14 | `capabilities` | Застарілий статичний контейнер можливостей; лише для сумісності | + | 15 | `normalizeToolSchemas` | Очищення tool-schema, що належить постачальнику, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика tool-schema, що належить постачальнику | + | 17 | `resolveReasoningOutputMode` | Tagged vs native контракт reasoning-output | + | 18 | `prepareExtraParams` | Типові параметри запиту | | 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn | - | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла в стандартному stream-шляху | + | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному stream-шляху | | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / охолодження | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS/cool-down | | 23 | `formatApiKey` | Користувацька форма runtime-токена | | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Підказка щодо виправлення автентифікації | - | 26 | `matchesContextOverflowError` | Виявлення переповнення, що належить постачальнику | + | 25 | `buildAuthDoctorHint` | Рекомендації для відновлення автентифікації | + | 26 | `matchesContextOverflowError` | Визначення переповнення контексту, що належить постачальнику | | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | - | 28 | `isCacheTtlEligible` | Gating TTL кешу prompt-ів | + | 28 | `isCacheTtlEligible` | Gating TTL кешу prompt | | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховати застарілі рядки upstream | - | 31 | `augmentModelCatalog` | Синтетичні рядки для прямої сумісності вперед | - | 32 | `isBinaryThinking` | Бінарне thinking увімк./вимк. | + | 30 | `suppressBuiltInModel` | Приховати застарілі upstream-рядки | + | 31 | `augmentModelCatalog` | Синтетичні рядки forward-compat | + | 32 | `isBinaryThinking` | Бінарний thinking увімк./вимк. | | 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` | - | 34 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням | + | 34 | `resolveDefaultThinkingLevel` | Типова політика `/think` | | 35 | `isModernModelRef` | Відповідність live/smoke моделей | - | 36 | `prepareRuntimeAuth` | Обмін токенів перед inference | - | 37 | `resolveUsageAuth` | Користувацький розбір облікових даних usage | - | 38 | `fetchUsageSnapshot` | Користувацька кінцева точка usage | + | 36 | `prepareRuntimeAuth` | Обмін токенами перед inference | + | 37 | `resolveUsageAuth` | Користувацький розбір облікових даних використання | + | 38 | `fetchUsageSnapshot` | Користувацький endpoint використання | | 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для memory/search | - | 40 | `buildReplayPolicy` | Користувацька політика replay/compaction транскрипту | - | 41 | `sanitizeReplayHistory` | Перезаписування replay, специфічні для постачальника, після загального очищення | - | 42 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner-ом | - | 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, telemetry) | + | 40 | `buildReplayPolicy` | Користувацька політика replay/compaction для транскриптів | + | 41 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | + | 42 | `validateReplayTurns` | Сувора перевірка replay-turn перед вбудованим runner | + | 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) | - Примітка щодо налаштування prompt-ів: + Примітка щодо налаштування prompt: - `resolveSystemPromptContribution` дозволяє постачальнику інжектувати - cache-aware підказки системного prompt-а для сімейства моделей. Віддавайте йому перевагу перед + cache-aware рекомендації для system prompt для сімейства моделей. Надавайте перевагу цьому hook над `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі і має зберігати стабільний/динамічний поділ кешу. - Детальні описи та приклади з реального світу дивіться у - [Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks). + Докладні описи й реальні приклади див. у + [Внутрішні механізми: runtime hooks постачальника](/uk/plugins/architecture#provider-runtime-hooks). @@ -645,15 +644,15 @@ x-i18n: } ``` - OpenClaw класифікує це як плагін **hybrid-capability**. Це + OpenClaw класифікує це як плагін **гібридних можливостей**. Це рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див. - [Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model). + [Внутрішні механізми: модель володіння можливостями](/uk/plugins/architecture#capability-ownership-model). - Для генерації відео віддавайте перевагу показаній вище структурі можливостей, що враховує режими: - `generate`, `imageToVideo` і `videoToVideo`. Старіші пласкі поля, такі + Для генерації відео надавайте перевагу показаній вище структурі можливостей з урахуванням режимів: + `generate`, `imageToVideo` і `videoToVideo`. Старі пласкі поля, такі як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, усе ще працюють - як агреговані резервні обмеження, але вони не можуть так само чисто описувати - обмеження для окремих режимів або вимкнені режими трансформації. + як сукупні резервні ліміти, але не можуть так чисто описувати обмеження для окремих режимів або + вимкнені режими перетворення. @@ -694,14 +693,14 @@ x-i18n: ## Публікація в ClawHub -Плагіни постачальників публікуються так само, як і будь-які інші зовнішні кодові плагіни: +Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів повинні використовувати +Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів мають використовувати `clawhub package publish`. ## Структура файлів @@ -716,21 +715,21 @@ clawhub package publish your-org/your-plugin └── usage.ts # Usage endpoint (optional) ``` -## Довідка щодо порядку каталогу +## Довідник порядку каталогу -`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих +`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих постачальників: -| Order | Коли | Випадок використання | -| --------- | ------------- | ---------------------------------------------- | -| `simple` | Перший прохід | Звичайні постачальники з API-ключем | -| `profile` | Після simple | Постачальники, прив’язані до профілів автентифікації | -| `paired` | Після profile | Синтез кількох пов’язаних записів | -| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) | +| Order | Коли | Варіант використання | +| --------- | ------------- | ----------------------------------------------- | +| `simple` | Перший прохід | Звичайні постачальники з API key | +| `profile` | Після simple | Постачальники, що залежать від auth profiles | +| `paired` | Після profile | Синтез кількох пов’язаних записів | +| `late` | Останній прохід | Перевизначення наявних постачальників (виграє при конфлікті) | -## Подальші кроки +## Наступні кроки -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал - [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent) -- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпорту subpath -- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — деталі хуків і вбудовані приклади +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath +- [Внутрішні механізми плагінів](/uk/plugins/architecture#provider-runtime-hooks) — деталі hooks і приклади вбудованих реалізацій diff --git a/docs/uk/providers/anthropic.md b/docs/uk/providers/anthropic.md index 36e00f2eb..340e96546 100644 --- a/docs/uk/providers/anthropic.md +++ b/docs/uk/providers/anthropic.md @@ -1,13 +1,13 @@ --- read_when: - Ви хочете використовувати моделі Anthropic в OpenClaw -summary: Використання Anthropic Claude через API-ключі в OpenClaw +summary: Використовуйте Anthropic Claude через API-ключі в OpenClaw title: Anthropic x-i18n: - generated_at: "2026-04-05T18:13:54Z" + generated_at: "2026-04-06T12:45:07Z" model: gpt-5.4 provider: openai - source_hash: bbc6c4938674aedf20ff944bc04e742c9a7e77a5ff10ae4f95b5718504c57c2d + source_hash: 6af35571debf5889b63e3b4f6a05aa4e046f39740287e6e1c492916ca00df44b source_path: providers/anthropic.md workflow: 15 --- @@ -15,29 +15,29 @@ x-i18n: # Anthropic (Claude) Anthropic створює сімейство моделей **Claude** і надає доступ через API. -У OpenClaw нове налаштування Anthropic має використовувати API-ключ. Наявні застарілі -профілі токенів Anthropic і далі враховуються під час виконання, якщо вони вже +У OpenClaw для нового налаштування Anthropic слід використовувати API-ключ. Наявні legacy +профілі токенів Anthropic і далі підтримуються під час виконання, якщо вони вже налаштовані. -Для Anthropic в OpenClaw розподіл білінгу такий: +Для Anthropic в OpenClaw розподіл оплати такий: -- **Anthropic API key**: звичайний білінг Anthropic API. +- **Anthropic API key**: звичайна оплата Anthropic API. - **Claude subscription auth всередині OpenClaw**: Anthropic повідомила користувачам OpenClaw - **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що це вважається - використанням стороннього harness і вимагає **Extra Usage** (pay-as-you-go, - оплачується окремо від підписки). + **4 квітня 2026 року о 12:00 PT / 20:00 BST**, що це вважається + використанням стороннього harness і вимагає **Extra Usage** (оплата за фактом використання, + виставляється окремо від підписки). -Наші локальні відтворення підтверджують цей розподіл: +Наші локальні відтворення підтверджують цей поділ: - прямий `claude -p` усе ще може працювати -- `claude -p --append-system-prompt ...` може активувати перевірку Extra Usage, коли +- `claude -p --append-system-prompt ...` може активувати захист Extra Usage, коли prompt ідентифікує OpenClaw -- той самий system prompt у стилі OpenClaw **не** відтворює блокування на шляху - Anthropic SDK + `ANTHROPIC_API_KEY` +- той самий системний prompt у стилі OpenClaw **не** відтворює блокування на + шляху Anthropic SDK + `ANTHROPIC_API_KEY` Тож практичне правило таке: **Anthropic API key або Claude subscription з -Extra Usage**. Якщо вам потрібен найочевидніший production-шлях, використовуйте Anthropic API +Extra Usage**. Якщо вам потрібен найзрозуміліший production-шлях, використовуйте Anthropic API key. Поточна публічна документація Anthropic: @@ -48,17 +48,18 @@ key. - [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) - [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) -Якщо вам потрібен найзрозуміліший шлях білінгу, натомість використовуйте Anthropic API key. +Якщо вам потрібен найзрозуміліший шлях оплати, натомість використовуйте Anthropic API +key. OpenClaw також підтримує інші варіанти у стилі підписки, зокрема [OpenAI -Codex](/providers/openai), [Qwen Cloud Coding Plan](/providers/qwen), -[MiniMax Coding Plan](/providers/minimax) і [Z.AI / GLM Coding -Plan](/providers/glm). +Codex](/uk/providers/openai), [Qwen Cloud Coding Plan](/uk/providers/qwen), +[MiniMax Coding Plan](/uk/providers/minimax) і [Z.AI / GLM Coding +Plan](/uk/providers/glm). ## Варіант A: Anthropic API key -**Найкраще для:** стандартного доступу до API та білінгу на основі використання. -Створіть свій API-ключ у Anthropic Console. +**Найкраще для:** стандартного доступу до API та оплати за використання. +Створіть свій API key у Anthropic Console. ### Налаштування CLI @@ -70,7 +71,7 @@ openclaw onboard openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ``` -### Фрагмент конфігурації Anthropic +### Фрагмент config Anthropic ```json5 { @@ -81,20 +82,20 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ## Типові параметри thinking (Claude 4.6) -- Для моделей Anthropic Claude 4.6 в OpenClaw за замовчуванням використовується `adaptive` thinking, якщо не задано явний рівень thinking. -- Ви можете перевизначити це для окремого повідомлення (`/think:`) або в параметрах моделі: +- Для моделей Anthropic Claude 4.6 в OpenClaw за замовчуванням використовується `adaptive` thinking, якщо явно не задано рівень thinking. +- Ви можете перевизначити його для кожного повідомлення (`/think:`) або в params моделі: `agents.defaults.models["anthropic/"].params.thinking`. - Пов’язана документація Anthropic: - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) -## Швидкий режим (Anthropic API) +## Fast mode (Anthropic API) -Спільний перемикач `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, включно із запитами з auth через API-key та OAuth, надісланими до `api.anthropic.com`. +Спільний перемикач `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, включно із запитами, автентифікованими через API key і OAuth, що надсилаються до `api.anthropic.com`. - `/fast on` відповідає `service_tier: "auto"` - `/fast off` відповідає `service_tier: "standard_only"` -- Значення конфігурації за замовчуванням: +- Типове значення в config: ```json5 { @@ -113,22 +114,22 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" Важливі обмеження: - OpenClaw додає рівні сервісу Anthropic лише для прямих запитів до `api.anthropic.com`. Якщо ви маршрутизуєте `anthropic/*` через proxy або gateway, `/fast` не змінює `service_tier`. -- Явні параметри моделі Anthropic `serviceTier` або `service_tier` мають пріоритет над типовим значенням `/fast`, якщо задано обидва. -- Anthropic повідомляє про фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без доступної місткості Priority Tier значення `service_tier: "auto"` усе одно може звестися до `standard`. +- Явно задані params моделі Anthropic `serviceTier` або `service_tier` мають пріоритет над типовою поведінкою `/fast`, якщо задано обидва параметри. +- Anthropic повідомляє фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без доступної ємності Priority Tier значення `service_tier: "auto"` усе одно може зводитися до `standard`. ## Кешування prompt (Anthropic API) -OpenClaw підтримує можливість кешування prompt від Anthropic. Це **лише для API**; застаріла auth через токен Anthropic не враховує налаштування кешу. +OpenClaw підтримує функцію кешування prompt від Anthropic. Це **лише API**; legacy Anthropic token auth не враховує параметри кешу. ### Конфігурація -Використовуйте параметр `cacheRetention` у конфігурації моделі: +Використовуйте параметр `cacheRetention` у config моделі: -| Значення | Тривалість кешу | Опис | -| ------- | --------------- | ---- | +| Value | Тривалість кешу | Опис | +| ------- | --------------- | ------------------------ | | `none` | Без кешування | Вимкнути кешування prompt | -| `short` | 5 хвилин | Значення за замовчуванням для auth через API Key | -| `long` | 1 година | Розширений кеш | +| `short` | 5 хвилин | Типово для auth через API Key | +| `long` | 1 година | Розширений кеш | ```json5 { @@ -144,13 +145,13 @@ OpenClaw підтримує можливість кешування prompt ві } ``` -### Значення за замовчуванням +### Типові значення -Під час використання автентифікації через Anthropic API Key OpenClaw автоматично застосовує `cacheRetention: "short"` (кеш на 5 хвилин) для всіх моделей Anthropic. Ви можете перевизначити це, явно задавши `cacheRetention` у своїй конфігурації. +Під час використання автентифікації через Anthropic API Key OpenClaw автоматично застосовує `cacheRetention: "short"` (5-хвилинний кеш) для всіх моделей Anthropic. Ви можете перевизначити це, явно задавши `cacheRetention` у своїй config. -### Перевизначення cacheRetention для окремих агентів +### Перевизначення `cacheRetention` для окремого agent -Використовуйте параметри на рівні моделі як базовий варіант, а потім перевизначайте конкретних агентів через `agents.list[].params`. +Використовуйте params на рівні моделі як базовий рівень, а потім перевизначайте конкретних agent через `agents.list[].params`. ```json5 { @@ -159,34 +160,34 @@ OpenClaw підтримує можливість кешування prompt ві model: { primary: "anthropic/claude-opus-4-6" }, models: { "anthropic/claude-opus-4-6": { - params: { cacheRetention: "long" }, // базове значення для більшості агентів + params: { cacheRetention: "long" }, // baseline for most agents }, }, }, list: [ { id: "research", default: true }, - { id: "alerts", params: { cacheRetention: "none" } }, // перевизначення лише для цього агента + { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only ], }, } ``` -Порядок злиття конфігурації для параметрів, пов’язаних із кешем: +Порядок злиття config для параметрів, пов’язаних із кешем: 1. `agents.defaults.models["provider/model"].params` 2. `agents.list[].params` (відповідний `id`, перевизначення за ключем) -Це дозволяє одному агенту зберігати довгоживучий кеш, тоді як інший агент на тій самій моделі вимикає кешування, щоб уникнути витрат на запис для імпульсного трафіку або трафіку з низьким повторним використанням. +Це дає змогу одному agent зберігати довготривалий кеш, а іншому agent на тій самій моделі вимикати кешування, щоб уникнути витрат на запис для імпульсного трафіку або трафіку з низьким повторним використанням. ### Примітки щодо Bedrock Claude -- Моделі Anthropic Claude у Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо її налаштовано. -- Для моделей Bedrock, які не є Anthropic, під час виконання примусово встановлюється `cacheRetention: "none"`. -- Розумні типові значення Anthropic API-key також задають `cacheRetention: "short"` для посилань на моделі Claude-on-Bedrock, якщо явне значення не встановлено. +- Моделі Anthropic Claude на Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо це налаштовано. +- Для моделей Bedrock не від Anthropic під час виконання примусово встановлюється `cacheRetention: "none"`. +- Розумні типові значення Anthropic API-key також встановлюють `cacheRetention: "short"` для посилань на моделі Claude-on-Bedrock, якщо явне значення не задано. ## Вікно контексту 1M (бета Anthropic) -Вікно контексту 1M від Anthropic є бета-можливістю з обмеженим доступом. У OpenClaw увімкніть його для окремої моделі +Вікно контексту Anthropic 1M доступне лише в beta. У OpenClaw його можна ввімкнути для кожної моделі окремо через `params.context1m: true` для підтримуваних моделей Opus/Sonnet. ```json5 @@ -203,73 +204,75 @@ OpenClaw підтримує можливість кешування prompt ві } ``` -OpenClaw зіставляє це з `anthropic-beta: context-1m-2025-08-07` у запитах +OpenClaw відображає це в `anthropic-beta: context-1m-2025-08-07` у запитах Anthropic. Це активується лише тоді, коли `params.context1m` явно встановлено в `true` для цієї моделі. Вимога: Anthropic має дозволяти використання довгого контексту для цих облікових даних -(зазвичай білінг через API key або шлях Claude-login / застарілу auth через токен в OpenClaw +(зазвичай це оплата через API key або шлях Claude-login / legacy token auth у OpenClaw з увімкненим Extra Usage). Інакше Anthropic повертає: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. -Примітка: наразі Anthropic відхиляє бета-запити `context-1m-*` при використанні -застарілої auth через токен Anthropic (`sk-ant-oat-*`). Якщо ви налаштуєте -`context1m: true` з цим застарілим режимом auth, OpenClaw запише попередження в журнал і +Примітка: наразі Anthropic відхиляє beta-запити `context-1m-*` під час використання +legacy Anthropic token auth (`sk-ant-oat-*`). Якщо ви налаштуєте +`context1m: true` з цим legacy режимом auth, OpenClaw запише попередження в журнал і повернеться до стандартного вікна контексту, пропустивши beta-заголовок context1m, -але зберігши потрібні beta-параметри OAuth. +зберігши при цьому обов’язкові OAuth beta. -## Видалено: бекенд Claude CLI +## Видалено: backend Claude CLI -Вбудований бекенд Anthropic `claude-cli` було видалено. +Вбудований backend Anthropic `claude-cli` було видалено. - У повідомленні Anthropic від 4 квітня 2026 року сказано, що трафік Claude-login, ініційований OpenClaw, є використанням стороннього harness і вимагає **Extra Usage**. - Наші локальні відтворення також показують, що прямий - `claude -p --append-system-prompt ...` може натрапити на ту саму перевірку, коли + `claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли доданий prompt ідентифікує OpenClaw. -- Та сама форма system prompt у стилі OpenClaw не викликає цю перевірку на +- Той самий системний prompt у стилі OpenClaw не активує цей захист на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. -- Для трафіку Anthropic в OpenClaw використовуйте API-ключі Anthropic. +- Для трафіку Anthropic в OpenClaw використовуйте Anthropic API keys. +- Якщо вам потрібен локальний резервний runtime на основі CLI, використовуйте інший підтримуваний CLI backend, + наприклад Codex CLI. Див. [/gateway/cli-backends](/gateway/cli-backends). ## Примітки -- Публічна документація Anthropic для Claude Code усе ще описує пряме використання CLI, зокрема +- Публічна документація Anthropic для Claude Code усе ще описує пряме використання CLI, наприклад `claude -p`, але окреме повідомлення Anthropic для користувачів OpenClaw каже, що шлях Claude-login у **OpenClaw** є використанням стороннього harness і вимагає - **Extra Usage** (pay-as-you-go, що оплачується окремо від підписки). + **Extra Usage** (оплата за фактом використання, окремо від підписки). Наші локальні відтворення також показують, що прямий - `claude -p --append-system-prompt ...` може натрапити на ту саму перевірку, коли - доданий prompt ідентифікує OpenClaw, тоді як та сама форма prompt не - відтворює це на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. Для production ми - натомість рекомендуємо Anthropic API-ключі. -- Anthropic setup-token знову доступний в OpenClaw як застарілий/ручний шлях. Повідомлення Anthropic щодо білінгу для OpenClaw усе ще застосовується, тож використовуйте його з розумінням того, що Anthropic вимагає **Extra Usage** для цього шляху. -- Деталі auth і правила повторного використання наведено в [/concepts/oauth](/uk/concepts/oauth). + `claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли + доданий prompt ідентифікує OpenClaw, тоді як той самий формат prompt не + відтворюється на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. Для production ми + натомість рекомендуємо Anthropic API keys. +- setup-token Anthropic знову доступний в OpenClaw як legacy/manual шлях. Повідомлення Anthropic про оплату, специфічне для OpenClaw, і далі застосовується, тож використовуйте його з розумінням, що Anthropic вимагає **Extra Usage** для цього шляху. +- Подробиці auth і правила повторного використання наведені в [/concepts/oauth](/uk/concepts/oauth). -## Усунення несправностей +## Усунення проблем -**Помилки 401 / токен раптово став недійсним** +**Помилки 401 / токен раптово став невалідним** -- Застаріла auth через токен Anthropic може завершитися або бути відкликаною. +- Legacy Anthropic token auth може завершитися або бути відкликаним. - Для нового налаштування перейдіть на Anthropic API key. -**Не знайдено API key для provider "anthropic"** +**Не знайдено API key для провайдера "anthropic"** -- Auth є **для кожного агента окремо**. Нові агенти не успадковують ключі головного агента. -- Повторно запустіть онбординг для цього агента або налаштуйте API key на host +- Auth є **для кожного agent окремо**. Нові agent не успадковують ключі головного agent. +- Повторно запустіть onboarding для цього agent або налаштуйте API key на хості gateway, а потім перевірте через `openclaw models status`. -**Не знайдено облікові дані для профілю `anthropic:default`** +**Не знайдено облікових даних для profile `anthropic:default`** -- Запустіть `openclaw models status`, щоб побачити, який профіль auth активний. -- Повторно запустіть онбординг або налаштуйте API key для цього шляху профілю. +- Запустіть `openclaw models status`, щоб побачити, який auth profile активний. +- Повторно запустіть onboarding або налаштуйте API key для цього шляху profile. -**Немає доступного профілю auth (усі в cooldown/unavailable)** +**Немає доступного auth profile (усі в cooldown/недоступні)** -- Перевірте `openclaw models status --json` для `auth.unusableProfiles`. -- Cooldown через обмеження швидкості Anthropic може бути прив’язаний до моделі, тож сусідня модель Anthropic - все ще може бути придатною до використання, навіть якщо поточна перебуває в cooldown. -- Додайте ще один профіль Anthropic або дочекайтеся завершення cooldown. +- Перевірте `openclaw models status --json` на `auth.unusableProfiles`. +- Cooldown rate limit Anthropic може бути прив’язаним до моделі, тож споріднена модель Anthropic + усе ще може бути придатною, навіть коли поточна перебуває в cooldown. +- Додайте ще один profile Anthropic або дочекайтеся завершення cooldown. -Докладніше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/help/faq). +Більше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/uk/help/faq). diff --git a/docs/uk/providers/google.md b/docs/uk/providers/google.md index 3190509d6..56ed1cbcf 100644 --- a/docs/uk/providers/google.md +++ b/docs/uk/providers/google.md @@ -1,37 +1,38 @@ --- read_when: - Ви хочете використовувати моделі Google Gemini з OpenClaw - - Вам потрібен потік автентифікації за ключем API -summary: Налаштування Google Gemini (ключ API, генерація зображень, розуміння медіа, вебпошук) + - Вам потрібен потік автентифікації через API-ключ або OAuth +summary: Налаштування Google Gemini (API-ключ + OAuth, генерація зображень, розуміння медіа, вебпошук) title: Google (Gemini) x-i18n: - generated_at: "2026-04-06T00:51:57Z" + generated_at: "2026-04-06T12:44:57Z" model: gpt-5.4 provider: openai - source_hash: 358d33a68275b01ebd916a3621dd651619cb9a1d062e2fb6196a7f3c501c015a + source_hash: 36cc7c7d8d19f6d4a3fb223af36c8402364fc309d14ffe922bd004203ceb1754 source_path: providers/google.md workflow: 15 --- # Google (Gemini) -Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до -генерації зображень, розуміння медіа (зображення/аудіо/відео) і вебпошуку через +Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також +до генерації зображень, розуміння медіа (зображення/аудіо/відео) і вебпошуку через Gemini Grounding. -- Провайдер: `google` +- Постачальник: `google` - Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY` - API: Google Gemini API +- Альтернативний постачальник: `google-gemini-cli` (OAuth) ## Швидкий старт -1. Установіть ключ API: +1. Задайте API-ключ: ```bash openclaw onboard --auth-choice gemini-api-key ``` -2. Установіть модель за замовчуванням: +2. Задайте типову модель: ```json5 { @@ -52,6 +53,46 @@ openclaw onboard --non-interactive \ --gemini-api-key "$GEMINI_API_KEY" ``` +## OAuth (Gemini CLI) + +Альтернативний постачальник `google-gemini-cli` використовує PKCE OAuth замість API- +ключа. Це неофіційна інтеграція; деякі користувачі повідомляють про обмеження +облікового запису. Використовуйте на власний ризик. + +- Типова модель: `google-gemini-cli/gemini-3.1-pro-preview` +- Псевдонім: `gemini-cli` +- Обов'язкова передумова для встановлення: локальний Gemini CLI, доступний як `gemini` + - Homebrew: `brew install gemini-cli` + - npm: `npm install -g @google/gemini-cli` +- Вхід: + +```bash +openclaw models auth login --provider google-gemini-cli --set-default +``` + +Змінні середовища: + +- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID` +- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET` + +(Або варіанти `GEMINI_CLI_*`.) + +Якщо запити Gemini CLI OAuth не працюють після входу, задайте +`GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host і +повторіть спробу. + +Якщо вхід завершується помилкою до початку потоку в браузері, переконайтеся, що локальна команда `gemini` +встановлена й присутня в `PATH`. OpenClaw підтримує як встановлення через Homebrew, +так і глобальні встановлення npm, зокрема поширені Windows/npm-схеми. + +Примітки щодо використання Gemini CLI JSON: + +- Текст відповіді береться з поля CLI JSON `response`. +- Дані використання резервно беруться з `stats`, коли CLI залишає `usage` порожнім. +- `stats.cached` нормалізується в OpenClaw `cacheRead`. +- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з + `stats.input_tokens - stats.cached`. + ## Можливості | Можливість | Підтримується | @@ -60,22 +101,22 @@ openclaw onboard --non-interactive \ | Генерація зображень | Так | | Генерація музики | Так | | Розуміння зображень | Так | -| Транскрибування аудіо | Так | +| Транскрипція аудіо | Так | | Розуміння відео | Так | | Вебпошук (Grounding) | Так | -| Мислення/міркування | Так (Gemini 3.1+) | +| Thinking/reasoning | Так (Gemini 3.1+) | ## Пряме повторне використання кешу Gemini Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw тепер -передає налаштований дескриптор `cachedContent` у запити до Gemini. +передає налаштований дескриптор `cachedContent` у запити Gemini. -- Налаштовуйте параметри для окремої моделі або глобально за допомогою - `cachedContent` або застарілого `cached_content` +- Налаштуйте параметри для окремої моделі або глобально через + `cachedContent` або застарілий `cached_content` - Якщо присутні обидва, пріоритет має `cachedContent` - Приклад значення: `cachedContents/prebuilt-context` -- Використання Gemini cache-hit нормалізується в OpenClaw як `cacheRead` з - вхідного `cachedContentTokenCount` +- Використання потрапляння в кеш Gemini нормалізується в OpenClaw `cacheRead` з + upstream `cachedContentTokenCount` Приклад: @@ -97,18 +138,19 @@ openclaw onboard --non-interactive \ ## Генерація зображень -Вбудований провайдер генерації зображень `google` за замовчуванням використовує +Вбудований постачальник генерації зображень `google` типово використовує `google/gemini-3.1-flash-image-preview`. - Також підтримує `google/gemini-3-pro-image-preview` -- Генерація: до 4 зображень на запит +- Генерація: до 4 зображень за запит - Режим редагування: увімкнено, до 5 вхідних зображень - Керування геометрією: `size`, `aspectRatio` і `resolution` -Генерація зображень, розуміння медіа та Gemini Grounding усе ще використовують -ідентифікатор провайдера `google`. +Постачальник `google-gemini-cli`, доступний лише через OAuth, — це окрема +поверхня текстового inference. Генерація зображень, розуміння медіа та Gemini Grounding залишаються +на ідентифікаторі постачальника `google`. -Щоб використовувати Google як провайдера зображень за замовчуванням: +Щоб використовувати Google як типовий постачальник зображень: ```json5 { @@ -122,20 +164,20 @@ openclaw onboard --non-interactive \ } ``` -Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні -параметри інструмента, вибір провайдера та поведінку аварійного перемикання. +Див. [Image Generation](/uk/tools/image-generation) щодо спільних параметрів +інструмента, вибору постачальника та поведінки резервного перемикання. ## Генерація відео Вбудований плагін `google` також реєструє генерацію відео через спільний інструмент `video_generate`. -- Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview` -- Режими: text-to-video, image-to-video і потоки з одним еталонним відео +- Типова відеомодель: `google/veo-3.1-fast-generate-preview` +- Режими: text-to-video, image-to-video і потоки з одним референсним відео - Підтримує `aspectRatio`, `resolution` і `audio` - Поточне обмеження тривалості: **від 4 до 8 секунд** -Щоб використовувати Google як провайдера відео за замовчуванням: +Щоб використовувати Google як типовий постачальник відео: ```json5 { @@ -149,22 +191,22 @@ openclaw onboard --non-interactive \ } ``` -Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні -параметри інструмента, вибір провайдера та поведінку аварійного перемикання. +Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів +інструмента, вибору постачальника та поведінки резервного перемикання. ## Генерація музики Вбудований плагін `google` також реєструє генерацію музики через спільний інструмент `music_generate`. -- Модель музики за замовчуванням: `google/lyria-3-clip-preview` +- Типова музична модель: `google/lyria-3-clip-preview` - Також підтримує `google/lyria-3-pro-preview` -- Керування запитом: `lyrics` і `instrumental` -- Формат виводу: `mp3` за замовчуванням, а також `wav` для `google/lyria-3-pro-preview` -- Еталонні вхідні дані: до 10 зображень -- Запуски на основі сесій відокремлюються через спільний потік завдань/стану, включно з `action: "status"` +- Керування промптом: `lyrics` і `instrumental` +- Формат виводу: типово `mp3`, а також `wav` для `google/lyria-3-pro-preview` +- Референсні входи: до 10 зображень +- Запуски з підтримкою сесії від'єднуються через спільний потік завдання/статусу, включно з `action: "status"` -Щоб використовувати Google як музичного провайдера за замовчуванням: +Щоб використовувати Google як типовий постачальник музики: ```json5 { @@ -178,8 +220,8 @@ openclaw onboard --non-interactive \ } ``` -Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні -параметри інструмента, вибір провайдера та поведінку аварійного перемикання. +Див. [Music Generation](/uk/tools/music-generation) щодо спільних параметрів +інструмента, вибору постачальника та поведінки резервного перемикання. ## Примітка щодо середовища diff --git a/docs/uk/providers/models.md b/docs/uk/providers/models.md index 50fca0114..279a4e4d7 100644 --- a/docs/uk/providers/models.md +++ b/docs/uk/providers/models.md @@ -1,27 +1,27 @@ --- read_when: - - Ви хочете вибрати постачальника моделей - - Ви хочете швидкі приклади налаштування автентифікації LLM і вибору моделі -summary: Постачальники моделей (LLM), які підтримує OpenClaw -title: Швидкий старт для постачальника моделей + - Ви хочете вибрати провайдера моделі + - Вам потрібні швидкі приклади налаштування автентифікації LLM і вибору моделі +summary: Провайдери моделей (LLM), які підтримує OpenClaw +title: Швидкий старт провайдерів моделей x-i18n: - generated_at: "2026-04-06T00:47:22Z" + generated_at: "2026-04-06T12:44:59Z" model: gpt-5.4 provider: openai - source_hash: c0314fb1c754171e5fc252d30f7ba9bb6acdbb978d97e9249264d90351bac2e7 + source_hash: 500191bfe853241096f97928ced2327a13b6f7f62003cb7452b24886c272e6ba source_path: providers/models.md workflow: 15 --- -# Постачальники моделей +# Провайдери моделей -OpenClaw може використовувати багато постачальників LLM. Виберіть одного, пройдіть автентифікацію, а потім встановіть типову -модель як `provider/model`. +OpenClaw може використовувати багато провайдерів LLM. Виберіть одного, пройдіть автентифікацію, а потім задайте типову +модель у форматі `provider/model`. ## Швидкий старт (два кроки) -1. Пройдіть автентифікацію у постачальника (зазвичай через `openclaw onboard`). -2. Встановіть типову модель: +1. Пройдіть автентифікацію у провайдера (зазвичай через `openclaw onboard`). +2. Задайте типову модель: ```json5 { @@ -29,18 +29,18 @@ OpenClaw може використовувати багато постачаль } ``` -## Підтримувані постачальники (стартовий набір) +## Підтримувані провайдери (стартовий набір) - [Alibaba Model Studio](/uk/providers/alibaba) - [Anthropic (API + Claude CLI)](/uk/providers/anthropic) - [Amazon Bedrock](/uk/providers/bedrock) - [BytePlus (міжнародний)](/uk/concepts/model-providers#byteplus-international) - [Chutes](/uk/providers/chutes) -- [ComfyUI](/providers/comfy) +- [ComfyUI](/uk/providers/comfy) - [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway) - [fal](/uk/providers/fal) - [Fireworks](/uk/providers/fireworks) -- [Моделі GLM](/uk/providers/glm) +- [GLM models](/uk/providers/glm) - [MiniMax](/uk/providers/minimax) - [Mistral](/uk/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot) @@ -57,10 +57,10 @@ OpenClaw може використовувати багато постачаль - [xAI](/uk/providers/xai) - [Z.AI](/uk/providers/zai) -## Додаткові варіанти вбудованих постачальників +## Додаткові варіанти вбудованих провайдерів -- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, коли доступні облікові дані Vertex; окремий вибір автентифікації під час онбордингу не потрібен +- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, коли доступні облікові дані Vertex; окремий варіант автентифікації для онбордингу не потрібен - `copilot-proxy` - локальний міст VS Code Copilot Proxy; використовуйте `openclaw onboard --auth-choice copilot-proxy` +- `google-gemini-cli` - неофіційний OAuth-потік Gemini CLI; потребує локально встановленого `gemini` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`); типова модель `google-gemini-cli/gemini-3.1-pro-preview`; використовуйте `openclaw onboard --auth-choice google-gemini-cli` або `openclaw models auth login --provider google-gemini-cli --set-default` -Повний каталог постачальників (xAI, Groq, Mistral тощо) і розширене налаштування -дивіться в розділі [Постачальники моделей](/uk/concepts/model-providers). +Повний каталог провайдерів (xAI, Groq, Mistral тощо) і розширену конфігурацію дивіться в [Model providers](/uk/concepts/model-providers). diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index db0e4fe9c..564b8bfb4 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,32 +1,32 @@ --- read_when: - - Потрібно налагодити ідентифікатори сесій, JSONL транскрипту або поля в sessions.json - - Ви змінюєте поведінку автоущільнення або додаєте службові дії “перед ущільненням” + - Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json + - Ви змінюєте поведінку автокомпакції або додаєте господарські дії «перед компакцією» - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Глибокий розбір: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)ущільнення' -title: Глибокий розбір керування сесіями +summary: 'Поглиблений розбір: сховище сесій і транскрипти, життєвий цикл та внутрішня логіка (авто)компакції' +title: Поглиблений розбір керування сесіями x-i18n: - generated_at: "2026-04-05T18:49:16Z" + generated_at: "2026-04-06T12:45:52Z" model: gpt-5.4 provider: openai - source_hash: e0d8c2d30be773eac0424f7a4419ab055fdd50daac8bc654e7d250c891f2c3b8 + source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091 source_path: reference/session-management-compaction.md workflow: 15 --- -# Керування сесіями та ущільнення (глибокий розбір) +# Керування сесіями та компакція (поглиблений розбір) У цьому документі пояснюється, як OpenClaw керує сесіями наскрізно: - **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`) - **Сховище сесій** (`sessions.json`) і що воно відстежує -- **Збереження транскрипту** (`*.jsonl`) та його структура -- **Гігієна транскрипту** (виправлення для конкретних провайдерів перед запусками) +- **Збереження транскриптів** (`*.jsonl`) та їхня структура +- **Гігієна транскриптів** (виправлення, специфічні для постачальника, перед запусками) - **Обмеження контексту** (вікно контексту проти відстежуваних токенів) -- **Ущільнення** (ручне + автоущільнення) і куди підключати роботу перед ущільненням -- **Тихі службові дії** (наприклад, запис пам’яті, який не повинен створювати видимий для користувача вивід) +- **Компакція** (ручна + автокомпакція) і куди підключати логіку перед компакцією +- **Тихі господарські дії** (наприклад, записи в пам’ять, які не повинні створювати видимий користувачу вивід) -Якщо спочатку потрібен огляд вищого рівня, почніть із: +Якщо вам спочатку потрібен огляд вищого рівня, почніть із: - [/concepts/session](/uk/concepts/session) - [/concepts/compaction](/uk/concepts/compaction) @@ -39,32 +39,32 @@ x-i18n: ## Джерело істини: Gateway -OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. +OpenClaw спроєктовано навколо одного **процесу Gateway**, який володіє станом сесій. -- Інтерфейси (macOS app, веб-інтерфейс Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів. -- У віддаленому режимі файли сесій розміщені на віддаленому хості; “перевірка локальних файлів на Mac” не покаже те, що використовує Gateway. +- Інтерфейси користувача (macOS app, web Control UI, TUI) повинні запитувати Gateway щодо списків сесій і кількості токенів. +- У віддаленому режимі файли сесій розміщені на віддаленому хості; «перевірка локальних файлів Mac» не покаже те, що використовує Gateway. --- -## Два шари збереження +## Два рівні збереження -OpenClaw зберігає сесії у двох шарах: +OpenClaw зберігає сесії у двох рівнях: 1. **Сховище сесій (`sessions.json`)** - Мапа ключ/значення: `sessionKey -> SessionEntry` - - Маленьке, змінюване, безпечно редагувати (або видаляти записи) - - Відстежує метадані сесії (поточний id сесії, останню активність, перемикачі, лічильники токенів тощо) + - Невелике, змінюване, безпечне для редагування (або видалення записів) + - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - - Транскрипт лише з додаванням записів із деревоподібною структурою (записи мають `id` + `parentId`) - - Зберігає фактичну розмову + виклики інструментів + зведення ущільнення + - Транскрипт із дописуванням у кінець і деревоподібною структурою (записи мають `id` + `parentId`) + - Зберігає фактичну розмову + виклики інструментів + підсумки компакції - Використовується для відновлення контексту моделі для майбутніх ходів --- ## Розташування на диску -Для кожного агента, на хості Gateway: +Для кожного агента на хості Gateway: - Сховище: `~/.openclaw/agents//sessions/sessions.json` - Транскрипти: `~/.openclaw/agents//sessions/.jsonl` @@ -76,25 +76,25 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`. ## Обслуговування сховища та контроль диска -Збереження сесій має автоматичні механізми обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: +Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: - `mode`: `warn` (типово) або `enforce` - `pruneAfter`: поріг віку застарілих записів для очищення (типово `30d`) - `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) -- `rotateBytes`: ротація `sessions.json`, коли файл стає завеликим (типово `10mb`) -- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) -- `maxDiskBytes`: необов’язковий бюджет каталогу sessions на диску +- `rotateBytes`: ротація `sessions.json`, якщо файл завеликий (типово `10mb`) +- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: той самий, що й `pruneAfter`; `false` вимикає очищення) +- `maxDiskBytes`: необов’язковий бюджет каталогу сесій на диску - `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Порядок примусового очищення для бюджету диска (`mode: "enforce"`): +Порядок застосування політики очищення бюджету диска (`mode: "enforce"`): -1. Спочатку видалити найстаріші архівовані або осиротілі артефакти транскриптів. -2. Якщо все ще вище за ціль, витіснити найстаріші записи сесій і їхні файли транскриптів. -3. Продовжувати, доки використання не стане на рівні або нижче `highWaterBytes`. +1. Спочатку видаляються найстаріші архівовані або осиротілі артефакти транскриптів. +2. Якщо використання все ще вище цілі, витісняються найстаріші записи сесій та їхні файли транскриптів. +3. Процес триває, доки використання не стане меншим або рівним `highWaterBytes`. У режимі `mode: "warn"` OpenClaw повідомляє про можливі витіснення, але не змінює сховище/файли. -Запустити обслуговування на вимогу: +Запустіть обслуговування за потреби: ```bash openclaw sessions cleanup --dry-run @@ -105,10 +105,10 @@ openclaw sessions cleanup --enforce ## Cron-сесії та журнали запусків -Ізольовані запуски cron також створюють записи сесій/транскрипти, і для них є окремі налаштування зберігання: +Ізольовані запуски cron також створюють записи сесій/транскрипти, і для них є окремі параметри зберігання: -- `cron.sessionRetention` (типово `24h`) очищає старі сесії ізольованих запусків cron зі сховища сесій (`false` вимикає). -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` обрізають файли `~/.openclaw/cron/runs/.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків). +- `cron.sessionRetention` (типово `24h`) очищує старі сесії ізольованих cron-запусків зі сховища сесій (`false` вимикає). +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищують файли `~/.openclaw/cron/runs/.jsonl` (типово: `2_000_000` байт і `2000` рядків). --- @@ -118,13 +118,13 @@ openclaw sessions cleanup --enforce Поширені шаблони: -- Основний/приватний чат (на агента): `agent::` (типово `main`) +- Основний/прямий чат (на агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` - Webhook: `hook:` (якщо не перевизначено) -Канонічні правила задокументовано в [/concepts/session](/uk/concepts/session). +Канонічні правила описано в [/concepts/session](/uk/concepts/session). --- @@ -132,12 +132,12 @@ openclaw sessions cleanup --enforce Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову). -Основні правила: +Базові правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (типово о 4:00 ранку за місцевим часом на хості gateway) створює новий `sessionId` у наступному повідомленні після межі скидання. -- **Завершення через простій** (`session.reset.idleMinutes` або застаріле `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна простою. Якщо налаштовано і щоденне скидання, і простій, спрацьовує те, що настане раніше. -- **Захист від форку батьківського ланцюжка** (`session.parentForkMaxTokens`, типово `100000`) пропускає форк батьківського транскрипту, коли батьківська сесія вже надто велика; новий потік починається з нуля. Установіть `0`, щоб вимкнути. +- **Щоденне скидання** (типово о 4:00 за місцевим часом на хості gateway) створює новий `sessionId` на наступному повідомленні після межі скидання. +- **Завершення через неактивність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна неактивності. Якщо налаштовано і щоденне скидання, і неактивність, спрацьовує те, що закінчиться першим. +- **Захист від розгалуження батьківського транскрипту** (`session.parentForkMaxTokens`, типово `100000`) пропускає форк батьківського транскрипту, якщо батьківська сесія вже надто велика; новий потік починається з нуля. Встановіть `0`, щоб вимкнути. Деталь реалізації: рішення приймається в `initSessionState()` у `src/auto-reply/reply/session.ts`. @@ -147,99 +147,100 @@ openclaw sessions cleanup --enforce Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`. -Ключові поля (не вичерпний список): +Ключові поля (не вичерпно): -- `sessionId`: поточний id транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`) -- `updatedAt`: мітка часу останньої активності -- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту -- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання) +- `sessionId`: поточний ідентифікатор транскрипту (ім’я файла виводиться з нього, якщо не задано `sessionFile`) +- `updatedAt`: час останньої активності +- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту +- `chatType`: `direct | group | room` (допомагає UI і політиці надсилання) - `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - - `sendPolicy` (перевизначення для конкретної сесії) + - `sendPolicy` (перевизначення для окремої сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (best-effort / залежать від провайдера): +- Лічильники токенів (best-effort / залежать від постачальника): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: скільки разів автоущільнення завершувалося для цього ключа сесії -- `memoryFlushAt`: мітка часу останнього скидання пам’яті перед ущільненням -- `memoryFlushCompactionCount`: лічильник ущільнень, коли востаннє виконувався flush +- `compactionCount`: скільки разів автокомпакція завершувалась для цього ключа сесії +- `memoryFlushAt`: часовий штамп останнього скидання пам’яті перед компакцією +- `memoryFlushCompactionCount`: лічильник компакції на момент останнього скидання -Сховище безпечно редагувати, але Gateway є джерелом істини: під час виконання сесій він може переписувати або повторно гідратувати записи. +Сховище можна безпечно редагувати, але Gateway є джерелом істини: під час роботи сесій він може переписувати або перевідновлювати записи. --- ## Структура транскрипту (`*.jsonl`) -Транскриптами керує `SessionManager` з `@mariozechner/pi-coding-agent`. +Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`. Файл має формат JSONL: -- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язковий `parentSession`) +- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язково `parentSession`) - Далі: записи сесії з `id` + `parentId` (дерево) Помітні типи записів: -- `message`: повідомлення user/assistant/toolResult -- `custom_message`: повідомлення, інжектовані розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI) -- `custom`: стан розширення, який _не потрапляє_ у контекст моделі -- `compaction`: збережене зведення ущільнення з `firstKeptEntryId` і `tokensBefore` -- `branch_summary`: збережене зведення під час навігації гілкою дерева +- `message`: повідомлення користувача/асистента/toolResult +- `custom_message`: повідомлення, вставлені розширенням, які _входять_ у контекст моделі (можуть бути приховані від UI) +- `custom`: стан розширення, який _не входить_ у контекст моделі +- `compaction`: збережений підсумок компакції з `firstKeptEntryId` і `tokensBefore` +- `branch_summary`: збережений підсумок під час навігації гілкою дерева -OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису. +OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. --- ## Вікна контексту проти відстежуваних токенів -Важливі два різні поняття: +Мають значення два різні поняття: -1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і панелей) +1. **Вікно контексту моделі**: жорстке обмеження для моделі (токени, видимі моделі) +2. **Лічильники сховища сесій**: ковзна статистика, яка записується в `sessions.json` (використовується для /status і панелей) -Якщо ви налаштовуєте обмеження: +Якщо ви налаштовуєте ліміти: - Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — це оцінка/значення звітності під час виконання; не сприймайте його як сувору гарантію. +- `contextTokens` у сховищі — це оцінка/звітне значення під час виконання; не сприймайте його як сувору гарантію. Докладніше див. у [/token-use](/uk/reference/token-use). --- -## Ущільнення: що це таке +## Компакція: що це таке -Ущільнення підсумовує старішу частину розмови в збережений запис `compaction` у транскрипті та залишає недоторканими недавні повідомлення. +Компакція підсумовує старішу частину розмови в збережений запис `compaction` у транскрипті та залишає недоторканими останні повідомлення. -Після ущільнення майбутні ходи бачать: +Після компакції майбутні ходи бачать: -- Зведення ущільнення +- Підсумок компакції - Повідомлення після `firstKeptEntryId` -Ущільнення є **постійним** (на відміну від очищення сесії). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). +Компакція є **постійною** (на відміну від обрізання сесії). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). -## Межі чанків ущільнення та поєднання інструментів +## Межі блоків компакції та парування інструментів -Коли OpenClaw розбиває довгий транскрипт на чанки для ущільнення, він зберігає -виклики інструментів асистента поєднаними з відповідними записами `toolResult`. +Коли OpenClaw розбиває довгий транскрипт на блоки для компакції, він зберігає +виклики інструментів асистента в парі з відповідними записами `toolResult`. - Якщо поділ за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw зміщує межу до повідомлення асистента з викликом інструмента, а не розділяє пару. -- Якщо кінцевий блок результатів інструмента інакше перевищив би цільовий розмір чанка, - OpenClaw зберігає цей очікувальний блок інструмента і залишає неузагальнений хвіст недоторканим. +- Якщо кінцевий блок результатів інструментів інакше виштовхнув би блок за цільовий розмір, + OpenClaw зберігає цей очікувальний блок інструмента й лишає непідсумований хвіст + недоторканим. - Перервані/помилкові блоки викликів інструментів не утримують відкритим очікувальний поділ. --- -## Коли відбувається автоущільнення (середовище Pi) +## Коли відбувається автокомпакція (середовище виконання Pi) -У вбудованому агенті Pi автоущільнення спрацьовує у двох випадках: +У вбудованому агенті Pi автокомпакція спрацьовує у двох випадках: 1. **Відновлення після переповнення**: модель повертає помилку переповнення контексту (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` та подібні варіанти, характерні для конкретних провайдерів) → ущільнити → повторити спробу. +exceeded` та подібні варіанти, оформлені постачальником) → компакція → повтор. 2. **Порогове обслуговування**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` @@ -249,13 +250,13 @@ exceeded` та подібні варіанти, характерні для ко - `contextWindow` — це вікно контексту моделі - `reserveTokens` — це запас токенів, зарезервований для промптів + наступного виводу моделі -Це семантика середовища Pi (OpenClaw споживає події, але коли ущільнювати, вирішує Pi). +Це семантика середовища виконання Pi (OpenClaw споживає події, але саме Pi вирішує, коли виконувати компакцію). --- -## Налаштування ущільнення (`reserveTokens`, `keepRecentTokens`) +## Налаштування компакції (`reserveTokens`, `keepRecentTokens`) -Налаштування ущільнення Pi зберігаються в налаштуваннях Pi: +Налаштування компакції Pi живуть у налаштуваннях Pi: ```json5 { @@ -267,14 +268,14 @@ exceeded` та подібні варіанти, характерні для ко } ``` -OpenClaw також застосовує мінімальний захисний поріг для вбудованих запусків: +OpenClaw також забезпечує мінімальний поріг безпеки для вбудованих запусків: -- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує значення. +- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw збільшує його. - Типовий поріг — `20000` токенів. -- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. -- Якщо значення вже вище, OpenClaw залишає його без змін. +- Встановіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. +- Якщо значення вже вище, OpenClaw не змінює його. -Чому: залишити достатньо запасу для багатокрокових “службових” дій (наприклад, записів пам’яті), перш ніж ущільнення стане неминучим. +Навіщо: залишити достатньо запасу для багатокрокових «господарських» дій (наприклад, записів у пам’ять), перш ніж компакція стане неминучою. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). @@ -283,46 +284,46 @@ OpenClaw також застосовує мінімальний захисний ## Поверхні, видимі користувачу -Ви можете спостерігати ущільнення і стан сесії через: +Ви можете спостерігати компакцію та стан сесії через: -- `/status` (у будь-якому чаті сесії) +- `/status` (у будь-якій сесії чату) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Режим verbose: `🧹 Auto-compaction complete` + кількість ущільнень +- Режим verbose: `🧹 Auto-compaction complete` + кількість компакцій --- -## Тихі службові дії (`NO_REPLY`) +## Тихі господарські дії (`NO_REPLY`) -OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. +OpenClaw підтримує «тихі» ходи для фонових завдань, коли користувач не повинен бачити проміжний вивід. -Умова: +Домовленість: -- Асистент починає свій вивід з точного тихого токена `NO_REPLY` / - `no_reply`, щоб позначити “не доставляти відповідь користувачу”. -- OpenClaw прибирає/приглушує це на рівні доставки. -- Приглушення точного тихого токена нечутливе до регістру, тож `NO_REPLY` і - `no_reply` обидва зараховуються, коли весь payload — це лише тихий токен. -- Це лише для справді фонових ходів/ходів без доставки; це не скорочений шлях - для звичайних практичних запитів користувача. +- Асистент починає свій вивід із точного тихого токена `NO_REPLY` / + `no_reply`, щоб позначити «не доставляти відповідь користувачу». +- OpenClaw видаляє/пригнічує це на рівні доставки. +- Пригнічення точного тихого токена не залежить від регістру, тож `NO_REPLY` і + `no_reply` обидва враховуються, коли весь payload — це лише тихий токен. +- Це призначено лише для справді фонових/безвідповідних ходів; це не скорочення + для звичайних дієвих запитів користувача. -Починаючи з `2026.1.10`, OpenClaw також приглушує **чернетковий/набірний стримінг**, коли -частковий чанк починається з `NO_REPLY`, щоб тихі операції не видавали частковий +Починаючи з `2026.1.10`, OpenClaw також пригнічує **чернетковий/набірний streaming**, коли +частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали частковий вивід посеред ходу. --- -## "Скидання пам’яті" перед ущільненням (реалізовано) +## «Скидання пам’яті» перед компакцією (реалізовано) -Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який записує стійкий -стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб ущільнення не могло +Мета: перед тим як відбудеться автокомпакція, виконати тихий агентний хід, який запише стійкий +стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб компакція не могла стерти критичний контекст. -OpenClaw використовує підхід **flush до порога**: +OpenClaw використовує підхід **скидання перед порогом**: 1. Відстежувати використання контексту сесії. -2. Коли воно перетинає “м’який поріг” (нижчий за поріг ущільнення Pi), виконати тиху - директиву “запиши пам’ять зараз” для агента. +2. Коли воно перетинає «м’який поріг» (нижче за поріг компакції Pi), виконати тиху + інструкцію «запиши пам’ять зараз» для агента. 3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач нічого не бачив. @@ -330,29 +331,29 @@ OpenClaw використовує підхід **flush до порога**: - `enabled` (типово: `true`) - `softThresholdTokens` (типово: `4000`) -- `prompt` (повідомлення user для ходу flush) -- `systemPrompt` (додатковий системний промпт, який додається для ходу flush) +- `prompt` (повідомлення користувача для ходу скидання) +- `systemPrompt` (додатковий системний промпт, який додається для ходу скидання) Примітки: -- Типові значення prompt/system prompt містять підказку `NO_REPLY` для приглушення +- Типові `prompt`/`systemPrompt` містять підказку `NO_REPLY` для пригнічення доставки. -- Flush виконується один раз за цикл ущільнення (відстежується в `sessions.json`). -- Flush виконується лише для вбудованих сесій Pi. -- Flush пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Memory](/uk/concepts/memory) щодо структури файлів робочого простору та шаблонів запису. +- Скидання виконується один раз за цикл компакції (відстежується в `sessions.json`). +- Скидання виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають). +- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Схему файлів робочого простору та шаблони запису див. у [Memory](/uk/concepts/memory). -Pi також надає хук `session_before_compact` в API розширень, але логіка flush в OpenClaw -сьогодні живе на боці Gateway. +Pi також надає хук `session_before_compact` в API розширення, але логіка +скидання в OpenClaw сьогодні живе на боці Gateway. --- -## Контрольний список усунення несправностей +## Контрольний список для усунення несправностей - Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і перевірте `sessionKey` у `/status`. -- Невідповідність між сховищем і транскриптом? Перевірте хост Gateway і шлях до сховища з `openclaw status`. -- Спам ущільненням? Перевірте: +- Невідповідність сховища й транскрипту? Перевірте хост Gateway і шлях до сховища з `openclaw status`. +- Спам компакції? Перевірте: - вікно контексту моделі (замале) - - налаштування ущільнення (`reserveTokens` завелике для вікна моделі може спричиняти раніше ущільнення) - - роздуття tool-result: увімкніть/налаштуйте очищення сесії -- Тихі ходи протікають? Переконайтеся, що відповідь починається з `NO_REPLY` (нечутливий до регістру точний токен) і що у вас збірка, яка містить виправлення приглушення стримінгу. + - налаштування компакції (`reserveTokens`, завелике для вікна моделі, може спричиняти раннішу компакцію) + - роздування через tool-result: увімкніть/налаштуйте обрізання сесії +- Протікають тихі ходи? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення streaming. diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index 08a2b744a..16e422820 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,229 +1,233 @@ --- read_when: - - Запуск harness-оточень для кодування через ACP - - Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями - - Прив’язування розмови в каналі повідомлень до постійного сеансу ACP - - Усунення несправностей бекенду ACP і підключення плагінів - - Керування командами /acp з чату -summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness -title: Агенти ACP + - Запуск coding harness через ACP + - Налаштування ACP-сеансів, прив’язаних до розмови, у каналах обміну повідомленнями + - Прив’язка розмови в каналі повідомлень до постійного ACP-сеансу + - Усунення неполадок бекенду ACP і обв’язки плагіна + - Керування командами /acp із чату +summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших harness-агентів +title: ACP Agents x-i18n: - generated_at: "2026-04-05T18:49:57Z" + generated_at: "2026-04-06T12:47:45Z" model: gpt-5.4 provider: openai - source_hash: 302f3fe25b1ffe0576592b6e0ad9e8a5781fa5702b31d508d9ba8908f7df33bd + source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6 source_path: tools/acp-agents.md workflow: 15 --- -# Агенти ACP +# ACP-агенти -Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають змогу OpenClaw запускати зовнішні harness-оточення для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX-harness-оточення) через плагін бекенду ACP. +Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harness (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harness) через плагін ACP-бекенду. -Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у гілці», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). +Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до власного середовища виконання sub-agent). Кожен запуск ACP-сеансу відстежується як [фонове завдання](/uk/automation/tasks). Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо -до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp) -замість ACP. +до наявних розмов у каналах OpenClaw, використовуйте +[`openclaw mcp serve`](/cli/mcp) замість ACP. -## Яку сторінку мені потрібно? +## Яка сторінка мені потрібна? Поруч є три поверхні, які легко сплутати: -| Ви хочете... | Використовуйте це | Примітки | -| --------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------- | -| Запускати Codex, Claude Code, Gemini CLI або інше зовнішнє harness-оточення _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сеанси, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування середовищем виконання | -| Відкрити сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим мосту. IDE/клієнт спілкується з OpenClaw через ACP поверх stdio/WebSocket | +| You want to... | Use this | Notes | +| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: ACP Agents | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime | +| Відкрити сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим bridge. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket | +| Повторно використовувати локальний AI CLI як лише текстову резервну модель | [CLI Backends](/gateway/cli-backends) | Це не ACP. Немає інструментів OpenClaw, немає елементів керування ACP, немає середовища виконання harness | -## Це працює одразу після встановлення? +## Чи працює це одразу після встановлення? Зазвичай так. - Нові встановлення тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`. -- Вбудований плагін `acpx` віддає перевагу своєму локально закріпленому бінарному файлу `acpx`. -- Під час запуску OpenClaw перевіряє цей бінарний файл і за потреби самостійно його відновлює. +- Вбудований плагін `acpx` віддає перевагу власному зафіксованому бінарнику `acpx`, локальному для плагіна. +- Під час запуску OpenClaw перевіряє цей бінарник і за потреби самостійно відновлює його. - Почніть із `/acp doctor`, якщо хочете швидко перевірити готовність. -Що все ще може статися під час першого використання: +Що все ще може трапитися під час першого використання: -- Цільовий адаптер harness може бути завантажений за запитом через `npx` під час першого використання цього harness. -- На хості для цього harness все одно має бути наявна автентифікація постачальника. -- Якщо хост не має доступу до npm/мережі, перше завантаження адаптерів може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. +- Цільовий адаптер harness може бути завантажений за потреби через `npx` під час першого використання цього harness. +- На хості все одно має бути налаштована вендорна автентифікація для цього harness. +- Якщо хост не має доступу до npm/мережі, завантаження адаптерів під час першого запуску може завершитися невдачею, доки кеші не будуть прогріті або адаптер не буде встановлено іншим способом. Приклади: -- `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер Codex ACP усе ще може потребувати першого завантаження. -- `/acp spawn claude`: те саме для адаптера Claude ACP, плюс автентифікація на боці Claude на цьому хості. +- `/acp spawn codex`: OpenClaw має бути готовий завантажити `acpx`, але адаптер Codex ACP все ще може потребувати першого завантаження. +- `/acp spawn claude`: аналогічно для адаптера Claude ACP, плюс автентифікація на боці Claude на цьому хості. -## Швидкий операторський потік +## Швидкий операторський сценарій -Використовуйте це, якщо вам потрібна практична інструкція для `/acp`: +Використовуйте це, якщо вам потрібен практичний runbook для `/acp`: -1. Запустіть сеанс: +1. Створіть сеанс: - `/acp spawn codex --bind here` - `/acp spawn codex --mode persistent --thread auto` -2. Працюйте в прив’язаній розмові або гілці (або явно вкажіть ключ цього сеансу). +2. Працюйте у прив’язаній розмові або треді (або явно вкажіть ключ цього сеансу). 3. Перевірте стан середовища виконання: - `/acp status` 4. За потреби налаштуйте параметри середовища виконання: - `/acp model ` - `/acp permissions ` - `/acp timeout ` -5. Скоригуйте активний сеанс без заміни контексту: +5. Скоригуйте активний сеанс, не замінюючи контекст: - `/acp steer tighten logging and continue` 6. Зупиніть роботу: - `/acp cancel` (зупинити поточний хід), або - - `/acp close` (закрити сеанс і прибрати прив’язки) + - `/acp close` (закрити сеанс + видалити прив’язки) ## Швидкий старт для людей Приклади природних запитів: -- «Прив’яжи цей канал Discord до Codex». -- «Запусти тут постійний сеанс Codex у гілці й тримай його зосередженим». -- «Виконай це як одноразовий сеанс Claude Code ACP і підсумуй результат». -- «Прив’яжи цей чат iMessage до Codex і зберігай наступні повідомлення в тому самому робочому просторі». -- «Використай Gemini CLI для цього завдання в гілці, а потім зберігай наступні повідомлення в цій самій гілці». +- «Прив’яжи цей Discord-канал до Codex». +- «Запусти тут постійний сеанс Codex у треді та тримай його сфокусованим». +- «Запусти це як одноразовий ACP-сеанс Claude Code і підсумуй результат». +- «Прив’яжи цей чат iMessage до Codex і зберігай наступні звернення в тому самому workspace». +- «Використай Gemini CLI для цього завдання в треді, а потім зберігай наступні звернення в тому самому треді». Що має зробити OpenClaw: 1. Вибрати `runtime: "acp"`. -2. Визначити цільове harness-оточення (`agentId`, наприклад `codex`). -3. Якщо запитано прив’язку до поточної розмови й активний канал це підтримує, прив’язати сеанс ACP до цієї розмови. -4. Інакше, якщо запитано прив’язку до гілки й поточний канал це підтримує, прив’язати сеанс ACP до гілки. -5. Спрямовувати наступні прив’язані повідомлення до того самого сеансу ACP, доки він не буде розфокусований, закритий або прострочений. +2. Визначити запитану ціль harness (`agentId`, наприклад `codex`). +3. Якщо запитано прив’язку до поточної розмови і активний канал це підтримує, прив’язати ACP-сеанс до цієї розмови. +4. Інакше, якщо запитано прив’язку до треда і поточний канал це підтримує, прив’язати ACP-сеанс до треда. +5. Маршрутизувати наступні прив’язані повідомлення до того самого ACP-сеансу, доки його не буде розфокусовано/закрито/прострочено. -## ACP проти субагентів +## ACP проти sub-agents -Використовуйте ACP, коли потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, коли потрібні делеговані запуски OpenClaw. +Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте sub-agents, коли вам потрібні делеговані запуски, власні для OpenClaw. -| Область | Сеанс ACP | Запуск субагента | -| ------------- | -------------------------------------- | ----------------------------------- | -| Середовище виконання | Плагін бекенду ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw | -| Ключ сеансу | `agent::acp:` | `agent::subagent:` | -| Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | +| Area | ACP session | Sub-agent run | +| ------------- | ------------------------------------- | ---------------------------------------- | +| Runtime | Плагін ACP-бекенду (наприклад acpx) | Власне середовище виконання sub-agent OpenClaw | +| Session key | `agent::acp:` | `agent::subagent:` | +| Main commands | `/acp ...` | `/subagents ...` | +| Spawn tool | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) | -Див. також [Субагенти](/uk/tools/subagents). +Дивіться також [Sub-agents](/uk/tools/subagents). ## Як ACP запускає Claude Code Для Claude Code через ACP стек такий: -1. Площина керування сеансом OpenClaw ACP +1. Керувальна площина ACP-сеансів OpenClaw 2. вбудований плагін середовища виконання `acpx` 3. адаптер Claude ACP -4. механізм середовища виконання/сеансу на боці Claude +4. механізм runtime/session на боці Claude Важлива відмінність: -- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки. - Для операторів практичне правило таке: +- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треда. +- CLI-бекенди — це окремі локальні резервні середовища виконання лише для тексту. Дивіться [CLI Backends](/gateway/cli-backends). -- якщо потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness — використовуйте ACP +Для операторів практичне правило таке: + +- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP +- потрібен простий локальний резервний текстовий шлях через сирий CLI: використовуйте CLI-бекенди ## Прив’язані сеанси ### Прив’язки до поточної розмови -Використовуйте `/acp spawn --bind here`, коли хочете, щоб поточна розмова стала довговічним робочим простором ACP без створення дочірньої гілки. +Використовуйте `/acp spawn --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда. Поведінка: -- OpenClaw і далі керує транспортом каналу, автентифікацією, безпекою та доставкою. -- Поточна розмова закріплюється за ключем створеного сеансу ACP. -- Наступні повідомлення в цій розмові спрямовуються до того самого сеансу ACP. -- `/new` і `/reset` скидають той самий прив’язаний сеанс ACP на місці. -- `/acp close` закриває сеанс і прибирає прив’язку до поточної розмови. +- OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою. +- Поточна розмова закріплюється за ключем створеного ACP-сеансу. +- Наступні повідомлення в цій розмові маршрутизуються до того самого ACP-сеансу. +- `/new` і `/reset` скидають той самий прив’язаний ACP-сеанс на місці. +- `/acp close` закриває сеанс і видаляє прив’язку до поточної розмови. Що це означає на практиці: - `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал залишається поточним каналом. -- `--bind here` все одно може створити новий сеанс ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цей сеанс до поточної розмови. -- `--bind here` сам по собі не створює дочірню гілку Discord або тему Telegram. -- Середовище виконання ACP все одно може мати власну робочу директорію (`cwd`) або робочий простір на диску, яким керує бекенд. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нової гілки повідомлень. -- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не запитувача. -- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево. -- Якщо успадкований робочий простір існує, але доступ до нього неможливий (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`. +- `--bind here` все ще може створити новий ACP-сеанс, якщо ви запускаєте нову роботу. +- `--bind here` сам по собі не створює дочірній Discord-тред або тему Telegram. +- Середовище виконання ACP все ще може мати власний робочий каталог (`cwd`) або workspace на диску, керований бекендом. Цей workspace runtime відокремлений від поверхні чату і не означає створення нового треда повідомлень. +- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw типово успадковує workspace **цільового агента**, а не агента-запитувача. +- Якщо цей успадкований шлях до workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до типового `cwd` бекенду замість того, щоб мовчки повторно використовувати неправильне дерево. +- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), spawn повертає реальну помилку доступу замість пропуску `cwd`. Ментальна модель: -- поверхня чату: де люди продовжують спілкуватися (`канал Discord`, `тема Telegram`, `чат iMessage`) -- сеанс ACP: довговічний стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити -- дочірня гілка/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` -- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенду) +- поверхня чату: де люди продовжують спілкуватися (`Discord channel`, `Telegram topic`, `iMessage chat`) +- ACP-сеанс: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw +- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` +- workspace runtime: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, workspace бекенду) Приклади: -- `/acp spawn codex --bind here`: зберегти цей чат, створити або під’єднати сеанс Codex ACP і спрямовувати сюди майбутні повідомлення -- `/acp spawn codex --thread auto`: OpenClaw може створити дочірню гілку/тему і прив’язати там сеанс ACP -- `/acp spawn codex --bind here --cwd /workspace/repo`: та сама прив’язка до чату, що й вище, але Codex працює в `/workspace/repo` +- `/acp spawn codex --bind here`: залишити цей чат, створити або під’єднати сеанс Codex ACP і маршрутизувати сюди майбутні повідомлення +- `/acp spawn codex --thread auto`: OpenClaw може створити дочірній тред/тему і прив’язати там ACP-сеанс +- `/acp spawn codex --bind here --cwd /workspace/repo`: така сама прив’язка до чату, як вище, але Codex працює в `/workspace/repo` Підтримка прив’язки до поточної розмови: -- Чат-канали/канали повідомлень, які заявляють підтримку прив’язки до поточної розмови, можуть використовувати `--bind here` через спільний шлях прив’язки розмов. -- Канали з особливою семантикою гілок/тем усе одно можуть надавати канально-специфічну канонізацію за тим самим спільним інтерфейсом. +- Канали чату/повідомлень, які оголошують підтримку прив’язки до поточної розмови, можуть використовувати `--bind here` через спільний шлях прив’язки розмов. +- Канали з власною семантикою тредів/тем усе ще можуть надавати канонізацію, специфічну для каналу, через той самий спільний інтерфейс. - `--bind here` завжди означає «прив’язати поточну розмову на місці». -- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і зберігаються після звичайних перезапусків gateway. +- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і переживають звичайні перезапуски gateway. Примітки: -- `--bind here` і `--thread ...` взаємовиключні в `/acp spawn`. -- У Discord `--bind here` прив’язує поточний канал або гілку на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here`. -- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає зрозуміле повідомлення про непідтримку. -- `resume` і питання «нового сеансу» — це питання сеансу ACP, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату. +- `--bind here` і `--thread ...` взаємовиключні у `/acp spawn`. +- У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`. +- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримуваність. +- `resume` і питання «новий сеанс» — це питання ACP-сеансу, а не каналу. Ви можете повторно використовувати або замінювати стан runtime без зміни поточної поверхні чату. -### Сеанси з прив’язкою до гілки +### Сеанси, прив’язані до тредів -Коли для адаптера каналу ввімкнено прив’язки до гілок, сеанси ACP можна прив’язувати до гілок: +Коли для адаптера каналу увімкнено прив’язки до тредів, ACP-сеанси можна прив’язувати до тредів: -- OpenClaw прив’язує гілку до цільового сеансу ACP. -- Наступні повідомлення в цій гілці спрямовуються до прив’язаного сеансу ACP. -- Вивід ACP доставляється назад у ту саму гілку. -- Розфокусування, закриття, архівування, тайм-аут бездіяльності або завершення max-age прибирає прив’язку. +- OpenClaw прив’язує тред до цільового ACP-сеансу. +- Наступні повідомлення в цьому треді маршрутизуються до прив’язаного ACP-сеансу. +- Вивід ACP доставляється назад у той самий тред. +- Розфокусування/закриття/архівація/тайм-аут бездіяльності або завершення максимального віку видаляє прив’язку. -Підтримка прив’язки до гілки залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до гілки, OpenClaw повертає зрозуміле повідомлення про непідтримку/недоступність. +Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. -Необхідні прапорці функцій для ACP із прив’язкою до гілки: +Потрібні feature flags для ACP, прив’язаного до тредів: - `acp.enabled=true` -- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) -- Увімкнено прапорець запуску ACP у гілках адаптера каналу (залежить від адаптера) +- `acp.dispatch.enabled` увімкнено за замовчуванням (задайте `false`, щоб призупинити ACP-dispatch) +- Увімкнено прапорець spawn ACP-сеансів для тредів адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -### Канали з підтримкою гілок +### Канали з підтримкою тредів -- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/гілки. +- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/треда. - Поточна вбудована підтримка: - - гілки/канали Discord - - теми Telegram (форумні теми в групах/супергрупах і DM-теми) -- Канали-плагіни можуть додавати підтримку через той самий інтерфейс прив’язки. + - Discord threads/channels + - Telegram topics (теми форуму в групах/supergroups і DM topics) +- Канали плагінів можуть додавати підтримку через той самий інтерфейс прив’язки. ## Налаштування для конкретних каналів -Для неепізодичних робочих процесів налаштуйте постійні ACP-прив’язки в записах верхнього рівня `bindings[]`. +Для неепізодичних workflow налаштовуйте постійні ACP-прив’язки у верхньорівневих записах `bindings[]`. ### Модель прив’язки -- `bindings[].type="acp"` позначає постійну ACP-прив’язку розмови. +- `bindings[].type="acp"` позначає постійну ACP-прив’язку до розмови. - `bindings[].match` визначає цільову розмову: - - канал або гілка Discord: `match.channel="discord"` + `match.peer.id=""` - - форумна тема Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - чат BlueBubbles DM/груповий чат: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних прив’язок груп віддавайте перевагу `chat_id:*` або `chat_identifier:*`. - - чат iMessage DM/груповий чат: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних прив’язок груп віддавайте перевагу `chat_id:*`. + - Discord channel or thread: `match.channel="discord"` + `match.peer.id=""` + - Telegram forum topic: `match.channel="telegram"` + `match.peer.id=":topic:"` + - BlueBubbles DM/group chat: `match.channel="bluebubbles"` + `match.peer.id=""` + Для стабільних групових прив’язок надавайте перевагу `chat_id:*` або `chat_identifier:*`. + - iMessage DM/group chat: `match.channel="imessage"` + `match.peer.id=""` + Для стабільних групових прив’язок надавайте перевагу `chat_id:*`. - `bindings[].agentId` — це id агента OpenClaw-власника. -- Необов’язкові перевизначення ACP містяться в `bindings[].acp`: +- Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`: - `mode` (`persistent` або `oneshot`) - `label` - `cwd` - `backend` -### Стандартні параметри середовища виконання для кожного агента +### Типові значення runtime для кожного агента -Використовуйте `agents.list[].runtime`, щоб один раз визначити стандартні параметри ACP для кожного агента: +Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента: - `agents.list[].runtime.type="acp"` - `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`) @@ -231,11 +235,11 @@ x-i18n: - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Пріоритет перевизначень для прив’язаних сеансів ACP: +Пріоритет перевизначень для прив’язаних ACP-сеансів: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. глобальні стандартні параметри ACP (наприклад `acp.backend`) +3. глобальні типові значення ACP (наприклад `acp.backend`) Приклад: @@ -319,18 +323,18 @@ x-i18n: Поведінка: -- OpenClaw гарантує, що налаштований сеанс ACP існує до початку використання. -- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP. -- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. -- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на гілці) усе ще застосовуються, де вони є. -- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні успадковані шляхи до робочого простору призводять до повернення до стандартного cwd бекенду; невідсутні помилки доступу повертаються як помилки запуску. +- OpenClaw гарантує, що налаштований ACP-сеанс існує до використання. +- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого ACP-сеансу. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сеансу на місці. +- Тимчасові прив’язки runtime (наприклад створені потоками фокусування на треді) усе ще застосовуються там, де вони присутні. +- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента. +- Відсутні успадковані шляхи до workspace повертаються до типового `cwd` бекенду; помилки доступу для наявних шляхів повертаються як помилки spawn. -## Запуск сеансів ACP (інтерфейси) +## Запуск ACP-сеансів (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити ACP-сеанс із ходу агента або виклику інструмента. ```json { @@ -344,29 +348,29 @@ x-i18n: Примітки: -- `runtime` за замовчуванням має значення `subagent`, тому для сеансів ACP явно встановлюйте `runtime: "acp"`. -- Якщо `agentId` не вказано, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. +- `runtime` типово дорівнює `subagent`, тому для ACP-сеансів явно задавайте `runtime: "acp"`. +- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. - `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову. -Відомості про інтерфейс: +Подробиці інтерфейсу: -- `task` (обов’язково): початковий промпт, надісланий до сеансу ACP. +- `task` (обов’язково): початковий prompt, надісланий ACP-сеансу. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано. -- `thread` (необов’язково, за замовчуванням `false`): запитати потік прив’язки до гілки там, де це підтримується. -- `mode` (необов’язково): `run` (одноразовий) або `session` (постійний). - - за замовчуванням використовується `run` - - якщо `thread: true` і mode не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання +- `agentId` (необов’язково): id цільового ACP-harness. Якщо задано, використовується `acp.defaultAgent`. +- `thread` (необов’язково, типово `false`): запитати потік прив’язки до треда, де це підтримується. +- `mode` (необов’язково): `run` (одноразово) або `session` (постійно). + - типове значення — `run` + - якщо `thread: true` і mode пропущено, OpenClaw може типово вибрати постійну поведінку залежно від шляху runtime - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, під час запуску ACP успадковується робочий простір цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних параметрів бекенду, а реальні помилки доступу повертаються. -- `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера. -- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події. - - За наявності прийнятні відповіді включають `streamLogPath`, який вказує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. +- `cwd` (необов’язково): запитаний робочий каталог runtime (валідується політикою бекенду/runtime). Якщо пропущено, ACP spawn успадковує workspace цільового агента, коли його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенду, а реальні помилки доступу повертаються. +- `label` (необов’язково): операторська мітка, яка використовується в тексті сеансу/банера. +- `resumeSessionId` (необов’язково): відновити наявний ACP-сеанс замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` транслює зведення прогресу початкового ACP-запуску назад до сеансу-запитувача як системні події. + - Якщо доступно, допустимі відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. ### Відновлення наявного сеансу -Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює свою історію розмов через `session/load`, тому відновлює роботу з повним контекстом попередніх дій. +Використовуйте `resumeSessionId`, щоб продовжити попередній ACP-сеанс замість створення нового. Агент відтворює свою історію розмов через `session/load`, тож продовжує роботу з повним контекстом попереднього. ```json { @@ -377,32 +381,32 @@ x-i18n: } ``` -Типові сценарії використання: +Поширені сценарії використання: -- Передати сеанс Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися -- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, а тепер хочете виконувати безголово через агента -- Відновити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності +- Передати сеанс Codex із ноутбука на телефон — попросіть агента продовжити там, де ви зупинилися +- Продовжити coding-сеанс, який ви почали інтерактивно в CLI, а тепер запускаєте безголово через агента +- Підхопити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності Примітки: -- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента. -- `resumeSessionId` відновлює історію вхідної ACP-розмови; `thread` і `mode` як і раніше застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`. -- Цільовий агент має підтримувати `session/load` (Codex і Claude Code це підтримують). -- Якщо id сеансу не знайдено, запуск завершиться зрозумілою помилкою — без тихого повернення до нового сеансу. +- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання sub-agent. +- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`. +- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). +- Якщо id сеансу не знайдено, spawn завершується чіткою помилкою — без тихого переходу до нового сеансу. ### Операторський smoke test -Використовуйте це після розгортання gateway, коли потрібна швидка жива перевірка того, що запуск ACP -справді працює наскрізь, а не лише проходить модульні тести. +Використовуйте це після розгортання gateway, коли хочете швидко перевірити вживу, що ACP spawn +справді працює наскрізно, а не просто проходить unit-тести. -Рекомендований бар’єр перевірки: +Рекомендований gate: 1. Перевірте версію/коміт розгорнутого gateway на цільовому хості. -2. Підтвердьте, що розгорнуте джерело містить прийняття лінійності ACP у +2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). -3. Відкрийте тимчасовий сеанс мосту ACPX до живого агента (наприклад +3. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента (наприклад `razor(main)` на `jpclawhq`). -4. Попросіть цього агента викликати `sessions_spawn` із: +4. Попросіть цього агента викликати `sessions_spawn` з: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` @@ -411,9 +415,9 @@ x-i18n: - `accepted=yes` - реальний `childSessionKey` - відсутність помилки валідатора -6. Приберіть тимчасовий сеанс мосту ACPX. +6. Приберіть тимчасовий bridge-сеанс ACPX. -Приклад промпту для живого агента: +Приклад prompt для живого агента: ```text Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run". @@ -423,25 +427,25 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` - `--label ` -Див. [Слеш-команди](/uk/tools/slash-commands). +Дивіться [Slash Commands](/uk/tools/slash-commands). ## Визначення цілі сеансу @@ -471,49 +475,49 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=` | -| `/acp steer` | Надсилає інструкцію коригування до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закриває сеанс і відв’язує цілі гілок. | `/acp close` | -| `/acp status` | Показує бекенд, режим, стан, параметри середовища виконання, можливості. | `/acp status` | -| `/acp set-mode` | Встановлює режим середовища виконання для цільового сеансу. | `/acp set-mode plan` | -| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Встановлює перевизначення робочої директорії середовища виконання. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Встановлює профіль політики схвалення. | `/acp permissions strict` | -| `/acp timeout` | Встановлює тайм-аут середовища виконання (секунди). | `/acp timeout 120` | -| `/acp model` | Встановлює перевизначення моделі середовища виконання. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Прибирає перевизначення параметрів середовища виконання сеансу. | `/acp reset-options` | -| `/acp sessions` | Показує список нещодавніх сеансів ACP зі сховища. | `/acp sessions` | -| `/acp doctor` | Стан бекенду, можливості, практичні виправлення. | `/acp doctor` | -| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` | +| Command | What it does | Example | +| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------- | +| `/acp spawn` | Створити ACP-сеанс; необов’язкова поточна прив’язка або прив’язка до треда. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасувати хід у процесі для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Надіслати інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Закрити сеанс і відв’язати цілі тредів. | `/acp close` | +| `/acp status` | Показати бекенд, режим, стан, параметри runtime, можливості. | `/acp status` | +| `/acp set-mode` | Задати режим runtime для цільового сеансу. | `/acp set-mode plan` | +| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Задати перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Задати профіль політики затвердження. | `/acp permissions strict` | +| `/acp timeout` | Задати тайм-аут runtime (секунди). | `/acp timeout 120` | +| `/acp model` | Задати перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Видалити перевизначення параметрів runtime сеансу. | `/acp reset-options` | +| `/acp sessions` | Показати список нещодавніх ACP-сеансів зі сховища. | `/acp sessions` | +| `/acp doctor` | Стан здоров’я бекенду, можливості, дієві виправлення. | `/acp doctor` | +| `/acp install` | Вивести детерміновані кроки встановлення та увімкнення. | `/acp install` | `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів. -## Відображення параметрів середовища виконання +## Відображення параметрів runtime -`/acp` має зручні команди та загальний сеттер. +`/acp` має зручні команди і загальний setter. Еквівалентні операції: -- `/acp model ` відповідає ключу конфігурації середовища виконання `model`. -- `/acp permissions ` відповідає ключу конфігурації середовища виконання `approval_policy`. -- `/acp timeout ` відповідає ключу конфігурації середовища виконання `timeout`. -- `/acp cwd ` безпосередньо оновлює перевизначення cwd середовища виконання. +- `/acp model ` відповідає ключу конфігурації runtime `model`. +- `/acp permissions ` відповідає ключу конфігурації runtime `approval_policy`. +- `/acp timeout ` відповідає ключу конфігурації runtime `timeout`. +- `/acp cwd ` безпосередньо оновлює перевизначення `cwd` для runtime. - `/acp set ` — це загальний шлях. - - Особливий випадок: `key=cwd` використовує шлях перевизначення cwd. -- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу. + - Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`. +- `/acp reset-options` очищає всі перевизначення runtime для цільового сеансу. -## Підтримка harness acpx (поточна) +## Підтримка harness в acpx (поточна) -Поточні вбудовані псевдоніми harness acpx: +Поточні вбудовані псевдоніми harness в acpx: - `claude` - `codex` @@ -594,20 +598,20 @@ Then report only: accepted=; childSessionKey=; error=`, але цей сирий обхідний шлях є функцією CLI acpx (а не звичайним шляхом `agentId` в OpenClaw). +Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw `agentId`). -## Необхідна конфігурація +## Потрібна конфігурація -Базова конфігурація ACP: +Базова конфігурація ACP core: ```json5 { acp: { enabled: true, - // Необов’язково. За замовчуванням true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp. + // Необов’язково. Типове значення — true; задайте false, щоб призупинити ACP-dispatch, зберігши елементи керування /acp. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -639,7 +643,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` і повторна перевірка. Ви можете перевизначити команду/версію в конфігурації плагіна: @@ -731,28 +735,28 @@ openclaw plugins install ./path/to/local/acpx-plugin Примітки: -- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`). -- Відносні шляхи визначаються від директорії робочого простору OpenClaw. -- `expectedVersion: "any"` вимикає сувору перевірку відповідності версії. -- Коли `command` вказує на користувацький бінарний файл/шлях, автоматичне локальне встановлення плагіна вимикається. -- Запуск OpenClaw залишається неблокувальним, поки триває фонова перевірка стану бекенду. +- `command` приймає абсолютний шлях, відносний шлях або назву команди (`acpx`). +- Відносні шляхи визначаються від каталогу workspace OpenClaw. +- `expectedVersion: "any"` вимикає сувору перевірку збігу версій. +- Коли `command` вказує на користувацький бінарник/шлях, автоматичне встановлення локального для плагіна пакета вимикається. +- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду. -Див. [Плагіни](/uk/tools/plugin). +Дивіться [Plugins](/uk/tools/plugin). ### Автоматичне встановлення залежностей -Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності -середовища виконання acpx (платформозалежні бінарні файли) встановлюються автоматично -через хук postinstall. Якщо автоматичне встановлення завершується помилкою, gateway все одно запускається +Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx +(бінарники для конкретної платформи) встановлюються автоматично +через postinstall-hook. Якщо автоматичне встановлення завершується невдачею, gateway все одно запускається нормально і повідомляє про відсутню залежність через `openclaw acp doctor`. -### MCP-міст інструментів плагіна +### Міст MCP для інструментів плагіна -За замовчуванням сеанси ACPX **не** відкривають зареєстровані плагінами OpenClaw інструменти -для ACP-harness-оточення. +Типово сеанси ACPX **не** відкривають інструменти, зареєстровані плагінами OpenClaw, для +ACP-harness. Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені -інструменти плагінів OpenClaw, такі як збереження/отримання пам’яті, увімкніть спеціальний міст: +інструменти плагінів OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true @@ -760,79 +764,78 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Що це робить: -- Вбудовує в bootstrap сеансу ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`. -- Відкриває інструменти плагінів, уже зареєстровані встановленими та ввімкненими - плагінами OpenClaw. -- Робить цю функцію явною і вимкненою за замовчуванням. +- Впроваджує вбудований MCP-сервер з назвою `openclaw-plugin-tools` у bootstrap + сеансу ACPX. +- Відкриває інструменти плагінів, уже зареєстровані встановленими та увімкненими плагінами OpenClaw. +- Залишає цю можливість явною і вимкненою за замовчуванням. -Примітки щодо безпеки й довіри: +Примітки щодо безпеки та довіри: -- Це розширює поверхню інструментів ACP-harness-оточення. +- Це розширює поверхню інструментів ACP-harness. - ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway. -- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися - у самому OpenClaw. -- Перевіряйте встановлені плагіни перед увімкненням цієї функції. +- Сприймайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися всередині самого OpenClaw. +- Перегляньте встановлені плагіни перед увімкненням. -Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст інструментів плагінів є -додатковою зручною функцією за явним увімкненням, а не заміною загальної конфігурації MCP-сервера. +Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools — +це додаткова зручність за явною згодою, а не заміна загальної конфігурації MCP-сервера. -## Конфігурація дозволів +## Налаштування дозволів -Сеанси ACP працюють неінтерактивно — TTY для схвалення або відхилення запитів дозволів на запис у файли й виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів: +ACP-сеанси працюють неінтерактивно — TTY для схвалення або відхилення запитів на дозвіл запису файлів і виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які визначають, як обробляються дозволи: -Ці дозволи harness ACPX відокремлені від схвалень exec в OpenClaw і відокремлені від прапорців обходу постачальника в бекендах CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP. +Ці дозволи ACPX harness відокремлені від схвалень exec у OpenClaw і відокремлені від vendor-прапорців обходу в CLI-бекендах, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для ACP-сеансів. ### `permissionMode` Керує тим, які операції агент harness може виконувати без запиту. -| Значення | Поведінка | -| --------------- | -------------------------------------------------------- | -| `approve-all` | Автоматично схвалює всі записи у файли та shell-команди. | -| `approve-reads` | Автоматично схвалює лише читання; запис і exec вимагають запитів. | -| `deny-all` | Відхиляє всі запити дозволів. | +| Value | Behavior | +| --------------- | ---------------------------------------------------------------- | +| `approve-all` | Автоматично схвалювати всі записи файлів і shell-команди. | +| `approve-reads` | Автоматично схвалювати лише читання; запис і exec потребують запитів. | +| `deny-all` | Відхиляти всі запити на дозвіл. | ### `nonInteractivePermissions` -Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сеансів ACP це завжди так). +Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для ACP-сеансів це завжди так). -| Значення | Поведінка | -| -------- | ---------------------------------------------------------------- | -| `fail` | Перервати сеанс з `AcpRuntimeError`. **(за замовчуванням)** | -| `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). | +| Value | Behavior | +| ------ | ------------------------------------------------------------- | +| `fail` | Перервати сеанс з `AcpRuntimeError`. **(типово)** | +| `deny` | Мовчки відхилити дозвіл і продовжити роботу (graceful degradation). | ### Конфігурація -Налаштовується через конфігурацію плагіна: +Задається через конфігурацію плагіна: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail ``` -Після зміни цих значень перезапустіть gateway. +Перезапустіть gateway після зміни цих значень. -> **Важливо:** OpenClaw наразі за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сеансах ACP будь-який запис або exec, що викликає запит дозволу, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. +> **Важливо:** OpenClaw наразі типово використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних ACP-сеансах будь-який запис або exec, що викликає запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. > -> Якщо вам потрібно обмежити дозволи, встановіть `nonInteractivePermissions` у `deny`, щоб сеанси плавно деградували замість аварійного завершення. +> Якщо вам потрібно обмежити дозволи, задайте `nonInteractivePermissions` у значення `deny`, щоб сеанси деградували коректно замість аварійного завершення. -## Усунення несправностей +## Усунення неполадок -| Симптом | Імовірна причина | Виправлення | -| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ACP runtime backend is not configured` | Плагін бекенду відсутній або вимкнений. | Встановіть і ввімкніть плагін бекенду, потім виконайте `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Встановіть `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень у гілках вимкнено. | Встановіть `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | Агента немає у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. | -| `Unable to resolve session target: ...` | Неправильний токен ключа/id/мітки. | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язатися. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. | -| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть у підтримуваний канал. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть у цільову гілку або використайте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачу. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. | -| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до гілки. | Використовуйте `--thread off` або перейдіть у підтримуваний адаптер/канал. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на хості; сеанс-запитувач ізольований sandbox. | Використовуйте `runtime="subagent"` з ізольованих sandbox сеансів або запускайте ACP з неізольованого сеансу. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової ізоляції sandbox або ACP із `sandbox="inherit"` з неізольованого сеансу. | -| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, потім повторно прив’яжіть/сфокусуйте гілку. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/exec у неінтерактивному сеансі ACP. | Встановіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Конфігурація дозволів](#конфігурація-дозволів). | -| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів встановіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | -| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте за допомогою `ps aux \| grep acpx`; вручну завершіть завислі процеси. | +| Symptom | Likely cause | Fix | +| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ACP runtime backend is not configured` | Відсутній або вимкнений плагін бекенду. | Встановіть і увімкніть плагін бекенду, а потім виконайте `/acp doctor`. | +| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Задайте `acp.enabled=true`. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Вимкнено dispatch зі звичайних повідомлень треда. | Задайте `acp.dispatch.enabled=true`. | +| `ACP agent "" is not allowed by policy` | Агента немає у списку дозволених. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. | +| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть, або використайте spawn без прив’язки. | +| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневий `bindings[]` або перейдіть до підтримуваного каналу. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треда. | Перейдіть у цільовий тред або використайте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи тред. | +| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до тредів. | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime працює на хості; сеанс-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із sandboxed-сеансів або запускайте ACP spawn із сеансу без sandbox. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP було запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandboxing або ACP із `sandbox="inherit"` із сеансу без sandbox. | +| Missing ACP metadata for bound session | Застарілі/видалені метадані ACP-сеансу. | Створіть повторно через `/acp spawn`, а потім знову прив’яжіть/сфокусуйте тред. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/exec у неінтерактивному ACP-сеансі. | Задайте `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Дивіться [Permission configuration](#permission-configuration). | +| ACP session fails early with little output | Запити на дозволи блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте логи gateway на `AcpRuntimeError`. Для повних дозволів задайте `permissionMode=approve-all`; для graceful degradation задайте `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Процес harness завершився, але ACP-сеанс не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |