diff --git a/docs/uk/concepts/context.md b/docs/uk/concepts/context.md index 5020670b0..5df77a3e7 100644 --- a/docs/uk/concepts/context.md +++ b/docs/uk/concepts/context.md @@ -1,40 +1,40 @@ --- read_when: - - Ви хочете зрозуміти, що означає “context” в OpenClaw - - Ви налагоджуєте, чому модель “знає” щось (або забула це) - - Ви хочете зменшити накладні витрати контексту (/context, /status, /compact) -summary: 'Контекст: що бачить модель, як він формується і як його перевірити' -title: Context + - Ви хочете зрозуміти, що означає «контекст» в OpenClaw + - Ви налагоджуєте, чому модель щось «знає» (або забула це) + - Ви хочете зменшити накладні витрати контексту (`/context`, `/status`, `/compact`) +summary: 'Контекст: що бачить модель, як він будується та як його перевірити' +title: Контекст x-i18n: - generated_at: "2026-04-05T18:00:56Z" + generated_at: "2026-04-05T18:48:31Z" model: gpt-5.4 provider: openai - source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0 + source_hash: fe7dfe52cb1a64df229c8622feed1804df6c483a6243e0d2f309f6ff5c9fe521 source_path: concepts/context.md workflow: 15 --- -# Context +# Контекст -«Контекст» — це **все, що OpenClaw надсилає моделі для одного запуску**. Він обмежений **вікном контексту** моделі (лімітом токенів). +«Контекст» — це **все, що OpenClaw надсилає моделі для запуску**. Він обмежений **вікном контексту** моделі (лімітом токенів). -Базова ментальна модель: +Проста ментальна модель для початківців: -- **System prompt** (побудований OpenClaw): правила, інструменти, список Skills, час/runtime та впроваджені файли робочого простору. -- **Історія розмови**: ваші повідомлення + повідомлення асистента для цієї сесії. +- **Системний запит** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та впроваджені файли робочого простору. +- **Історія розмови**: ваші повідомлення + повідомлення помічника для цієї сесії. - **Виклики/результати інструментів + вкладення**: вивід команд, читання файлів, зображення/аудіо тощо. -Контекст _це не те саме_, що й «memory»: memory може зберігатися на диску й повторно завантажуватися пізніше; context — це те, що міститься в поточному вікні моделі. +Контекст _не є тим самим_, що й «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що міститься в поточному вікні моделі. -## Швидкий старт (перевірка context) +## Швидкий старт (перевірка контексту) -- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + налаштування сесії. -- `/context list` → що впроваджується + приблизні розміри (для кожного файлу + підсумки). -- `/context detail` → глибший розбір: розміри для кожного файлу, для кожної схеми інструмента, для кожного запису skill і розмір system prompt. -- `/usage tokens` → додає до звичайних відповідей нижній колонтитул із використанням. -- `/compact` → підсумовує старішу історію в compact entry, щоб звільнити місце у вікні. +- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + параметри сесії. +- `/context list` → що впроваджено + приблизні розміри (для кожного файла + загальні). +- `/context detail` → глибший розбір: для кожного файла, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного запиту. +- `/usage tokens` → додає нижній колонтитул використання для кожної відповіді до звичайних відповідей. +- `/compact` → узагальнює старішу історію в компактний запис, щоб звільнити місце у вікні. -Див. також: [Slash commands](/tools/slash-commands), [Використання токенів і вартість](/reference/token-use), [Compaction](/concepts/compaction). +Див. також: [Слеш-команди](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Компресія](/uk/concepts/compaction). ## Приклад виводу @@ -43,11 +43,11 @@ x-i18n: ### `/context list` ``` -🧠 Розбивка контексту +🧠 Розподіл контексту Робочий простір: -Макс. bootstrap/file: 20,000 chars -Sandbox: mode=non-main sandboxed=false -System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) +Макс. bootstrap на файл: 20,000 chars +Пісочниця: mode=non-main sandboxed=false +Системний запит (запуск): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) Впроваджені файли робочого простору: - AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) @@ -58,58 +58,58 @@ System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5 - HEARTBEAT.md: MISSING | raw 0 | injected 0 - BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) -Список Skills (текст system prompt): 2,184 chars (~546 tok) (12 skills) -Tools: read, edit, write, exec, process, browser, message, sessions_send, … -Список інструментів (текст system prompt): 1,032 chars (~258 tok) -Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховується в context; не показується як текст) -Tools: (те саме, що вище) +Список Skills (текст системного запиту): 2,184 chars (~546 tok) (12 skills) +Інструменти: read, edit, write, exec, process, browser, message, sessions_send, … +Список інструментів (текст системного запиту): 1,032 chars (~258 tok) +Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховуються в контексті; не показуються як текст) +Інструменти: (те саме, що вище) -Токени сесії (cached): 14,250 total / ctx=32,000 +Токени сесії (кешовані): 14,250 total / ctx=32,000 ``` ### `/context detail` ``` -🧠 Розбивка контексту (детально) +🧠 Розподіл контексту (детально) … -Найбільші skills (розмір запису в prompt): +Найбільші skills (розмір запису в запиті): - frontend-design: 412 chars (~103 tok) - oracle: 401 chars (~101 tok) -… (+10 more skills) +… (+ще 10 skills) -Найбільші tools (розмір схеми): +Найбільші інструменти (розмір схеми): - browser: 9,812 chars (~2,453 tok) - exec: 6,240 chars (~1,560 tok) -… (+N more tools) +… (+ще N) ``` ## Що враховується у вікні контексту -Усе, що отримує модель, враховується, зокрема: +Враховується все, що отримує модель, зокрема: -- System prompt (усі розділи). +- Системний запит (усі розділи). - Історія розмови. - Виклики інструментів + результати інструментів. - Вкладення/транскрипти (зображення/аудіо/файли). -- Підсумки compaction і артефакти pruning. +- Підсумки компресії та артефакти обрізання. - «Обгортки» провайдера або приховані заголовки (не видимі, але все одно враховуються). -## Як OpenClaw будує system prompt +## Як OpenClaw будує системний запит -System prompt **належить OpenClaw** і перебудовується для кожного запуску. Він включає: +Системний запит **належить OpenClaw** і перебудовується для кожного запуску. Він містить: - Список інструментів + короткі описи. - Список Skills (лише метадані; див. нижче). - Розташування робочого простору. -- Час (UTC + перетворений користувацький час, якщо налаштовано). -- Метадані runtime (хост/OS/модель/thinking). +- Час (UTC + перетворений час користувача, якщо налаштовано). +- Метадані середовища виконання (хост/ОС/модель/thinking). - Впроваджені bootstrap-файли робочого простору в розділі **Project Context**. -Повна розбивка: [System Prompt](/concepts/system-prompt). +Повний розбір: [Системний запит](/uk/concepts/system-prompt). ## Впроваджені файли робочого простору (Project Context) -Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони існують): +Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони є): - `AGENTS.md` - `SOUL.md` @@ -119,68 +119,68 @@ System prompt **належить OpenClaw** і перебудовується д - `HEARTBEAT.md` - `BOOTSTRAP.md` (лише під час першого запуску) -Великі файли обрізаються для кожного файлу окремо через `agents.defaults.bootstrapMaxChars` (типово `20000` chars). OpenClaw також примусово застосовує загальне обмеження на впровадження bootstrap у всіх файлах через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` chars). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. +Великі файли обрізаються окремо для кожного файла за допомогою `agents.defaults.bootstrapMaxChars` (типово `20000` символів). OpenClaw також застосовує загальне обмеження на впровадження bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. -Коли відбувається обрізання, runtime може впровадити в prompt блок попередження в розділі Project Context. Це налаштовується через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`). +Коли відбувається обрізання, середовище виконання може впровадити в запит блок попередження в розділі Project Context. Налаштовується це через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`). ## Skills: впроваджені чи завантажені на вимогу -System prompt включає компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати. +Системний запит містить компактний **список skills** (назва + опис + розташування). Цей список створює реальні накладні витрати. -Інструкції Skills _типово не включаються_. Очікується, що модель викличе `read` для `SKILL.md` skill **лише за потреби**. +Інструкції skill _не_ включаються типово. Очікується, що модель виконає `read` для `SKILL.md` цього skill **лише за потреби**. -## Tools: є дві вартості +## Інструменти: є дві складові вартості -Інструменти впливають на context двома способами: +Інструменти впливають на контекст двома способами: -1. **Текст списку інструментів** у system prompt (те, що ви бачите як «Tooling»). -2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в context, навіть якщо ви не бачите їх як звичайний текст. +1. **Текст списку інструментів** у системному запиті (те, що ви бачите як “Tooling”). +2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, навіть якщо ви не бачите їх як звичайний текст. `/context detail` розбиває найбільші схеми інструментів, щоб ви могли побачити, що домінує. -## Команди, директиви й "inline shortcuts" +## Команди, директиви та "вбудовані скорочення" -Slash-команди обробляються Gateway. Є кілька різних типів поведінки: +Слеш-команди обробляються Gateway. Існує кілька різних варіантів поведінки: -- **Standalone commands**: повідомлення, яке складається лише з `/...`, виконується як команда. -- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення. - - Повідомлення лише з директивами зберігають налаштування сесії. - - Inline directives у звичайному повідомленні діють як підказки для конкретного повідомлення. -- **Inline shortcuts** (лише для allowlisted senders): деякі токени `/...` всередині звичайного повідомлення можуть виконуватися негайно (приклад: «hey /status») і прибираються до того, як модель побачить решту тексту. +- **Окремі команди**: повідомлення, яке складається лише з `/...`, виконується як команда. +- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення. + - Повідомлення лише з директивами зберігають параметри сесії. + - Вбудовані директиви у звичайному повідомленні діють як підказки для конкретного повідомлення. +- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` усередині звичайного повідомлення можуть виконуватися негайно (приклад: “hey /status”), а потім прибираються до того, як модель побачить решту тексту. -Подробиці: [Slash commands](/tools/slash-commands). +Докладніше: [Слеш-команди](/uk/tools/slash-commands). -## Sessions, compaction і pruning (що зберігається) +## Сесії, компресія та обрізання (що зберігається) -Те, що зберігається між повідомленнями, залежить від механізму: +Що саме зберігається між повідомленнями, залежить від механізму: -- **Normal history** зберігається в session transcript, доки не буде ущільнено/обрізано політикою. -- **Compaction** зберігає підсумок у transcript і залишає нещодавні повідомлення без змін. -- **Pruning** видаляє старі результати інструментів із prompt _у пам’яті_ для запуску, але не переписує transcript. +- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснута/обрізана відповідно до політики. +- **Компресія** зберігає підсумок у транскрипті та залишає недавні повідомлення без змін. +- **Обрізання** видаляє старі результати інструментів із _внутрішньої_ підказки для запуску, але не переписує транскрипт. -Документація: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning). +Документація: [Сесія](/uk/concepts/session), [Компресія](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning). -Типово OpenClaw використовує вбудований `legacy` context engine для збирання і -compaction. Якщо ви встановите plugin, який надає `kind: "context-engine"`, і -виберете його через `plugins.slots.contextEngine`, OpenClaw делегує збирання -context, `/compact` та пов’язані hooks життєвого циклу контексту субагентів цьому -engine. `ownsCompaction: false` не спричиняє автоматичний резервний перехід до -legacy engine; активний engine все одно має коректно реалізовувати `compact()`. Див. -[Context Engine](/concepts/context-engine), щоб ознайомитися з повним -інтерфейсом підключення, hooks життєвого циклу та конфігурацією. +Типово OpenClaw використовує вбудований контекстний рушій `legacy` для збирання +та компресії. Якщо ви встановите плагін, який надає `kind: "context-engine"`, і +виберете його через `plugins.slots.contextEngine`, OpenClaw натомість делегує +цьому рушію збирання контексту, `/compact` і пов’язані гачки життєвого циклу +контексту субагента. `ownsCompaction: false` не вмикає автоматичний fallback до +рушія legacy; активний рушій усе одно має коректно реалізовувати `compact()`. Див. +[Context Engine](/uk/concepts/context-engine), щоб ознайомитися з повним +підключуваним інтерфейсом, гачками життєвого циклу та конфігурацією. ## Що насправді показує `/context` -`/context` за можливості надає перевагу найсвіжішому звіту про system prompt, **побудованого під час запуску**: +`/context` за можливості віддає перевагу найновішому звіту про системний запит, **побудований під час запуску**: -- `System prompt (run)` = захоплено з останнього вбудованого запуску (з підтримкою інструментів) і збережено в session store. -- `System prompt (estimate)` = обчислено на льоту, коли звіту про запуск немає (або під час виконання через CLI backend, який не генерує такого звіту). +- `System prompt (run)` = зафіксований з останнього вбудованого запуску (з підтримкою інструментів) і збережений у сховищі сесії. +- `System prompt (estimate)` = обчислений на льоту, якщо звіту про запуску ще немає. -У будь-якому разі він повідомляє розміри та найбільші складові; він **не** виводить повний system prompt або схеми інструментів. +У будь-якому випадку він показує розміри та найбільших учасників; він **не** вивантажує повний системний запит або схеми інструментів. ## Пов’язане -- [Context Engine](/concepts/context-engine) — власне впровадження контексту через plugins -- [Compaction](/concepts/compaction) — підсумовування довгих розмов -- [System Prompt](/concepts/system-prompt) — як будується system prompt -- [Agent Loop](/concepts/agent-loop) — повний цикл виконання агента +- [Context Engine](/uk/concepts/context-engine) — користувацьке впровадження контексту через плагіни +- [Компресія](/uk/concepts/compaction) — узагальнення довгих розмов +- [Системний запит](/uk/concepts/system-prompt) — як будується системний запит +- [Цикл агента](/uk/concepts/agent-loop) — повний цикл виконання агента diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 2542fcab5..b1ad84512 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,56 +1,56 @@ --- read_when: - - Вам потрібна точна семантика конфігурації або типові значення на рівні полів - - Ви перевіряєте блоки конфігурації каналів, моделей, gateway або інструментів -summary: Повний довідник для кожного ключа конфігурації OpenClaw, типових значень і параметрів каналів -title: Довідник конфігурації + - Вам потрібна точна семантика полів конфігурації або значення за замовчуванням + - Ви перевіряєте блоки конфігурації каналу, моделі, шлюзу або інструментів +summary: Повний довідник для кожного ключа конфігурації OpenClaw, значень за замовчуванням і налаштувань каналів +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-05T18:08:12Z" + generated_at: "2026-04-05T18:53:56Z" model: gpt-5.4 provider: openai - source_hash: e0faf00dacd01d75d48acf77529155b6cd6b734dcad4d86fef316a62af259c92 + source_hash: c3b087ff868e25165e7b80dd7505f8b29c218cd6894304179b7a9426da231276 source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідник конфігурації +# Довідник з конфігурації -Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/gateway/configuration). +Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration). -Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні типові значення. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Кожен канал запускається автоматично, щойно існує його розділ конфігурації (якщо не задано `enabled: false`). +Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`). ### Доступ до DM і груп -Усі канали підтримують політики DM і групові політики: +Усі канали підтримують політики DM і політики груп: -| Політика DM | Поведінка | -| ------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має його підтвердити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів pairing) | -| `open` | Дозволити всі вхідні DM (потрібне `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| Політика DM | Поведінка | +| ------------------- | ---------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | +| `allowlist` | Лише відправники в `allowFrom` (або в парному сховищі дозволених) | +| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | -| Групова політика | Поведінка | -| -------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist | -| `open` | Обійти allowlist груп (gating за згадкою все одно діє) | -| `disabled` | Заблокувати всі повідомлення груп/кімнат | +| Політика груп | Поведінка | +| -------------------- | ------------------------------------------------------- | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `open` | Обійти списки дозволених для груп (обмеження за згадками все ще застосовується) | +| `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` провайдера не встановлено. -Коди pairing спливають через 1 годину. Очікувальні запити pairing для DM обмежені **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), групова політика runtime резервно встановлюється на `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не задано. +Коди сполучення спливають через 1 годину. Кількість очікуючих запитів на сполучення для DM обмежена **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску. ### Перевизначення моделі для каналу -Використовуйте `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` (типово, включати весь контекст цитат/тредів/історії), `allowlist` (включати контекст лише від відправників з allowlist), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати здорові стани каналів у вивід heartbeat. -- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові стани у вивід 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 у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал gateway (Baileys Web). Він запускається автоматично, коли існує пов’язана сесія. +WhatsApp працює через web-канал шлюзу (Baileys Web). Він запускається автоматично, коли існує зв’язана сесія. ```json5 { @@ -110,7 +110,7 @@ WhatsApp працює через вебканал gateway (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 }, }, @@ -132,7 +132,7 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` - + ```json5 { @@ -150,10 +150,10 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (після сортування). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Вихідні команди типово використовують обліковий запис `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`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -188,7 +188,7 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він historyLimit: 50, replyToMode: "first", // off | first | all 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,13 +211,13 @@ WhatsApp працює через вебканал gateway (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](/tools/acp-agents#channel-specific-settings). -- Preview streaming Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Політика повторних спроб](/concepts/retry). +- Токен бота: `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 супергруп, `/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` (працює в прямих і групових чатах). +- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -272,7 +272,7 @@ WhatsApp працює через вебканал gateway (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 у Discord відповідає partial) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp працює через вебканал gateway (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, @@ -320,35 +320,35 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він ``` - Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, які явно надають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політики облікового запису все одно беруться з вибраного облікового запису в активному snapshot runtime. -- Необов’язковий `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` (типово 17) ділить високі повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до тредів Discord: - - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також прив’язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного unfocus через бездіяльність у годинах (`0` вимикає) +- Прямі вихідні виклики, що передають явний Discord `token`, використовують саме цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному runtime snapshot. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. +- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; просто числові ID відхиляються. +- Slug-и guild мають нижній регістр, а пробіли замінено на `-`; ключі каналів використовують slugified ім’я (без `#`). Віддавайте перевагу 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 для авто-unfocus за неактивністю в годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки тредів через `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для каналів і тредів (використовуйте ID каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. -- `channels.discord.voice` вмикає розмови у voice-каналах Discord і необов’язкове auto-join + перевизначення TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в опції DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw додатково намагається відновити voice receive, виходячи й повторно входячи в voice-сесію після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму streaming. Застарілі значення `streamMode` і булевий `streaming` мігрують автоматично. -- `channels.discord.autoPresence` зіставляє доступність runtime із присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає змінюване зіставлення імен/тегів (режим сумісності break-glass). -- `channels.discord.execApprovals`: нативна доставка підтверджень exec для Discord і авторизація тих, хто підтверджує. - - `enabled`: `true`, `false` або `"auto"` (типово). В auto-режимі підтвердження exec активуються, коли approver-ів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено підтверджувати запити exec. Якщо не задано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, підтвердження пересилаються для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово) надсилає в DM approver-ам, `"channel"` — у вихідний канал, `"both"` — і туди, і туди. Якщо target містить `"channel"`, кнопки можуть використовувати лише визначені approver-и. - - `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` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). +- `channels.discord.execApprovals`: доставка нативних погоджень exec для Discord і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо пропущено, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачів, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені погоджувачі. + - `cleanupAfterResolve`: коли `true`, видаляє DM погодження після схвалення, відмови або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` на всіх повідомленнях). +**Режими сповіщень про реакції:** `off` (жодних), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). ### Google Chat @@ -379,11 +379,11 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- JSON сервісного облікового запису: вбудований (`serviceAccount`) або з файлу (`serviceAccountFile`). -- Також підтримується SecretRef для сервісного облікового запису (`serviceAccountRef`). -- Резервні env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Для цілей доставки використовуйте `spaces/` або `users/`. -- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає змінюване зіставлення email principal (режим break-glass сумісності). +- JSON службового облікового запису: inline (`serviceAccount`) або з файлу (`serviceAccountFile`). +- Також підтримується Service account SecretRef (`serviceAccountRef`). +- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` для цілей доставки. +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -433,8 +433,8 @@ WhatsApp працює через вебканал gateway (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,38 +448,38 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні env для типового облікового запису). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні рядки - або об’єкти SecretRef. -- Snapshot-и облікових записів Slack показують поля джерела/стану для кожних облікових даних, наприклад - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP-режимі — +- **Режим Socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанту через env для типового облікового запису). +- **HTTP mode** вимагає `botToken` плюс `signingSecret` (на корені або для окремого облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті + рядки або об’єкти SecretRef. +- Знімки облікових записів Slack містять поля джерела/статусу для кожного облікового запису, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode — `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштований через SecretRef, але поточний шлях команди/runtime не зміг - визначити значення секрету. -- `configWrites: false` блокує ініційовані Slack записи конфігурації. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. -- `channels.slack.streaming` — канонічний ключ режиму streaming. Застарілі значення `streamMode` і булевий `streaming` мігрують автоматично. -- Для цілей доставки використовуйте `user:` (DM) або `channel:`. + налаштовано через SecretRef, але поточний шлях команди/runtime не зміг + отримати значення секрету. +- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. +- `channels.slack.streaming` — канонічний ключ режиму стримінгу. Застарілі `streamMode` і булеві значення `streaming` автоматично мігруються. +- Використовуйте `user:` (DM) або `channel:` для цілей доставки. -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -**Ізоляція сесій тредів:** `thread.historyScope` — для кожного треду окремо (типово) або спільно на рівні каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові треди. +**Ізоляція сесій у гілках:** `thread.historyScope` — для окремої гілки (типово) або спільний на рівні каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові гілки. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім прибирає її після завершення. Використовуйте шорткод emoji 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, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте short code 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 | увімкнено | Реакції + список реакцій | +| Група дій | Типово | Примітки | +| ------------ | -------- | ---------------------- | +| reactions | увімкнено | Реагування + список реакцій | | messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріпити/відкріпити/переглянути | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список кастомних emoji | +| pins | увімкнено | Закріплення/відкріплення/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких emoji | ### Mattermost -Mattermost постачається як плагін: `openclaw plugins install @openclaw/mattermost`. +Mattermost постачається як plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -499,7 +499,7 @@ Mattermost постачається як плагін: `openclaw plugins install native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // Необов’язковий явний URL для reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,23 +509,23 @@ Mattermost постачається як плагін: `openclaw plugins install } ``` -Режими чату: `oncall` (відповідати за @-згадкою, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера). +Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера). -Коли власні команди Mattermost увімкнено: +Коли ввімкнено нативні команди Mattermost: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL. -- `commands.callbackUrl` має вказувати на ендпоїнт gateway OpenClaw і бути доступним із сервера Mattermost. -- Callback-и власних slash-команд автентифікуються токенами для кожної команди, які - Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або жодна - команда не активується, OpenClaw відхиляє callback-и з +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. +- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути досяжним із сервера Mattermost. +- Нативні callback-и slash-команд автентифікуються токенами для кожної команди, + які Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або не + активовано жодної команди, OpenClaw відхиляє callback-и з `Unauthorized: invalid command token.` -- Для приватних/tailnet/внутрішніх host callback-а Mattermost може вимагати, щоб - `ServiceSettings.AllowedUntrustedInternalConnections` містив host/domain callback-а. - Використовуйте значення host/domain, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані Mattermost записи конфігурації. +- Для приватних/tailnet/internal хостів callback-ів Mattermost може вимагати, + щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а. + Використовуйте значення хоста/домену, а не повні URL. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення gating за згадкою для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадками для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. ### Signal @@ -534,7 +534,7 @@ Mattermost постачається як плагін: `openclaw plugins install channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // необов’язкова прив’язка до облікового запису dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -546,15 +546,15 @@ Mattermost постачається як плагін: `openclaw plugins install } ``` -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -- `channels.signal.account`: прив’язати запуск каналу до конкретної Signal identity облікового запису. -- `channels.signal.configWrites`: дозволити або заборонити ініційовані Signal записи конфігурації. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. ### BlueBubbles -BlueBubbles — рекомендований шлях для iMessage (на базі плагіна, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях для iMessage (на основі plugin, налаштовується в `channels.bluebubbles`). ```json5 { @@ -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. Використовуйте handle BlueBubbles або рядок target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/tools/acp-agents#channel-specific-settings). -- Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/channels/bluebubbles). +- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте handle BlueBubbles або рядок цілі (`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). Демон або порт не потрібні. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Додатковий daemon або порт не потрібні. ```json5 { @@ -600,17 +600,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. -- Потрібен Full Disk Access до бази даних Messages. -- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- Потребує 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 використовує сувору перевірку host key, тому переконайтеся, що ключ relay-хоста вже є в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити ініційовані iMessage записи конфігурації. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/tools/acp-agents#channel-specific-settings). +- 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 @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює через розширення і налаштовується в `channels.matrix`. +Matrix підтримується extension і налаштовується в `channels.matrix`. ```json5 { @@ -651,23 +651,23 @@ Matrix працює через розширення і налаштовуєть } ``` -- Для автентифікації токеном використовується `accessToken`; для автентифікації паролем — `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.allowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і `allowPrivateNetwork` — незалежні засоби керування. +- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. +- `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"` (типово). В auto-режимі підтвердження exec активуються, коли approver-ів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено підтверджувати запити exec. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, підтвердження пересилаються для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. -- Перевірки статусу Matrix і live directory lookups використовують ту саму політику проксі, що й трафік runtime. -- Повну конфігурацію Matrix, правила target і приклади налаштування описано в [Matrix](/channels/matrix). +- `channels.matrix.execApprovals`: доставка нативних погоджень exec для Matrix і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено погоджувати exec-запити. + - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. +- Перевірки стану Matrix і live directory lookups використовують ту саму proxy policy, що й runtime traffic. +- Повну конфігурацію Matrix, правила targeting і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює через розширення й налаштовується в `channels.msteams`. +Microsoft Teams підтримується extension і налаштовується в `channels.msteams`. ```json5 { @@ -675,19 +675,19 @@ Microsoft Teams працює через розширення й налаштов msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, політики team/channel: + // див. /channels/msteams }, }, } ``` -- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політику DM/груп, перевизначення для окремих команд/каналів) описано в [Microsoft Teams](/channels/msteams). +- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, webhook, політики DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює через розширення й налаштовується в `channels.irc`. +IRC підтримується extension і налаштовується в `channels.irc`. ```json5 { @@ -708,11 +708,11 @@ IRC працює через розширення й налаштовується } ``` -- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/gating за згадкою) описано в [IRC](/channels/irc). +- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим `account id`. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlist-и/обмеження за згадками) задокументовано в [IRC](/uk/channels/irc). -### Кілька облікових записів (усі канали) +### Багатообліковість (усі канали) Запускайте кілька облікових записів на канал (кожен із власним `accountId`): @@ -736,27 +736,27 @@ IRC працює через розширення й налаштовується ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени з env застосовуються лише до **типового** облікового запису. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. +- Токени через env застосовуються лише до **типового** облікового запису. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначено для конкретного. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не типовий обліковий запис через `openclaw channels add` (або onboarding каналу), поки ще використовуєте конфігурацію верхнього рівня каналу для одного облікового запису, OpenClaw спершу переносить значення верхнього рівня, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix може зберегти наявну відповідну named/default ціль. -- Наявні прив’язки лише для каналу (без `accountId`) і далі збігаються з типовим обліковим записом; прив’язки для конкретного облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну named/default ціль. +- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або онбординг каналу), поки все ще використовуєте конфігурацію верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня, що стосуються облікового запису, у мапу облікових записів каналу, щоб початковий обліковий запис продовжував працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Наявні прив’язки лише каналу (без `accountId`) і далі відповідатимуть типовому обліковому запису; прив’язки з областю облікового запису лишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, що належать обліковому запису, у підвищений обліковий запис, обраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/default ціль. -### Інші канали розширень +### Інші extension-канали -Багато каналів розширень налаштовуються як `channels.` і описані на своїх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). -Див. повний індекс каналів: [Канали](/channels). +Багато extension-каналів налаштовуються як `channels.` і задокументовані на власних сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Див. повний індекс каналів: [Channels](/uk/channels). -### Gating згадок у груповому чаті +### Обмеження за згадками в групових чатах -Групові повідомлення типово **вимагають згадки** (метадані згадки або безпечні regex-шаблони). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні шаблони regex). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat для WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони й небезпечні вкладені повторення ігноруються. -- Gating згадок застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечне вкладене повторення ігноруються. +- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або хоча б один шаблон). ```json5 { @@ -769,9 +769,9 @@ IRC працює через розширення й налаштовується } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Задайте `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або на рівні облікового запису). Встановіть `0`, щоб вимкнути. -#### Ліміти історії DM +#### Обмеження історії DM ```json5 { @@ -786,13 +786,13 @@ IRC працює через розширення й налаштовується } ``` -Порядок визначення: перевизначення для конкретного DM → типове значення провайдера → без ліміту (зберігати все). +Порядок визначення: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Включіть власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): ```json5 { @@ -813,18 +813,18 @@ IRC працює через розширення й налаштовується } ``` -### Команди (обробка команд чату) +### Команди (обробка команд у чаті) ```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 + інструмент перезапуску шлюзу allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -834,28 +834,28 @@ IRC працює через розширення й налаштовується } ``` - + -- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`. -- `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`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; режим лише читання `/config show` лишається доступним звичайним клієнтам із правом запису. +- Текстові команди мають бути **окремими** повідомленнями з початковим `/`. +- `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`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; лише читання `/config show` лишається доступним для звичайних клієнтів оператора з правом запису. - `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true). -- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, які стосуються цього облікового запису (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (allowlist каналів/pairing і `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. +- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, які націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (allowlist-и/сполучення каналу і `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики access-group, якщо `allowFrom` не встановлено. --- -## Типові значення агентів +## Типові значення агента ### `agents.defaults.workspace` -Типове значення: `~/.openclaw/workspace`. +Типово: `~/.openclaw/workspace`. ```json5 { @@ -865,7 +865,7 @@ IRC працює через розширення й налаштовується ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного промпта. Якщо не задано, OpenClaw автоматично виявляє його, піднімаючись вгору від workspace. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt-а. Якщо не задано, OpenClaw визначає його автоматично, рухаючись угору від workspace. ```json5 { @@ -883,9 +883,9 @@ IRC працює через розширення й налаштовується 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 ], }, } @@ -893,9 +893,9 @@ IRC працює через розширення й налаштовується - Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Задайте `agents.list[].skills: []`, щоб не мати жодних Skills. +- Встановіть `agents.list[].skills: []`, щоб не було жодних Skills. - Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він - не зливається з типовими значеннями. + не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -909,7 +909,7 @@ IRC працює через розширення й налаштовується ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типове значення: `20000`. +Максимальна кількість символів у bootstrap-файлі workspace перед обрізанням. Типово: `20000`. ```json5 { @@ -919,7 +919,7 @@ IRC працює через розширення й налаштовується ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна сумарна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типове значення: `150000`. +Максимальна загальна кількість символів, що інжектуються в усі bootstrap-файли workspace. Типово: `150000`. ```json5 { @@ -930,11 +930,11 @@ IRC працює через розширення й налаштовується ### `agents.defaults.bootstrapPromptTruncationWarning` Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. -Типове значення: `"once"`. +Типово: `"once"`. -- `"off"`: ніколи не вставляти текст попередження в системний промпт. -- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). -- `"always"`: вставляти попередження на кожному запуску, якщо є обрізання. +- `"off"`: ніколи не інжектувати текст попередження в системний prompt. +- `"once"`: інжектувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: інжектувати попередження під час кожного запуску, коли існує обрізання. ```json5 { @@ -944,11 +944,11 @@ IRC працює через розширення й налаштовується ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. -Типове значення: `1200`. +Максимальний розмір у пікселях для довшої сторони зображення в блоках transcript/tool image перед викликами провайдера. +Типово: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скриншотів. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю скриншотів. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -958,7 +958,7 @@ IRC працює через розширення й налаштовується ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного промпта (не для часових міток повідомлень). Резервно використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt-а (не для часових міток повідомлень). За відсутності використовується часовий пояс хоста. ```json5 { @@ -968,7 +968,7 @@ IRC працює через розширення й налаштовується ### `agents.defaults.timeFormat` -Формат часу в системному промпті. Типове значення: `auto` (згідно з налаштуваннями ОС). +Формат часу в системному prompt-і. Типово: `auto` (налаштування ОС). ```json5 { @@ -1006,7 +1006,7 @@ IRC працює через розширення й налаштовується 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", @@ -1022,39 +1022,39 @@ IRC працює через розширення й налаштовується ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядковані резервні моделі failover. + - Форма рядка задає лише primary model. + - Форма об’єкта задає primary plus упорядковані failover models. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як конфігурація vision-model. + - Використовується шляхом інструмента `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` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ID провайдера. + - Якщо ви вибираєте конкретно провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API key (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо пропущено, `image_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. - `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` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео у порядку ID провайдера. - - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API key провайдера. - - Вбудований провайдер генерації відео Qwen наразі підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо пропущено, `video_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео у порядку `provider-id`. + - Якщо ви вибираєте конкретно провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/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`. + - Якщо пропущено, інструмент PDF повертається до `imageModel`, а потім — до визначеної моделі сесії/типової моделі. +- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується у fallback-режимі витягання для інструмента `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`. -- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо пропустити провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого провайдера для цього точного ID моделі, і лише потім резервно повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw резервно переходить до першого налаштованого провайдера/моделі, а не показує застаріле типове значення видаленого провайдера. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг налаштованого провайдера для точного id моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому віддавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого провайдера/моделі замість того, щоб показувати застаріле типове значення видаленого провайдера. - `models`: налаштований каталог моделей і allowlist для `/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 агента) перевизначає по ключах. Докладніше див. [Кешування промптів](/reference/prompt-caching). -- Записувачі конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і, де можливо, зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає по ключу. Докладніше див. [Кешування prompt-ів](/uk/reference/prompt-caching). +- Засоби запису конфігурації, які мутують ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну об’єктну форму і, коли можливо, зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізована). Типово: 4. -**Вбудовані короткі alias** (застосовуються лише коли модель є в `agents.defaults.models`): +**Вбудовані скорочені alias-и** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Псевдонім | Модель | +| Alias | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1065,15 +1065,14 @@ IRC працює через розширення й налаштовується | `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 mode, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. -Моделі Z.AI типово вмикають `tool_stream` для streaming викликів інструментів. Задайте `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 типово використовується thinking `adaptive`, якщо не задано явний рівень thinking. -- CLI-бекенди орієнтовані на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли встановлено `sessionArg`. -- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Сесії підтримуються, коли задано `sessionArg`. +- Pass-through зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.heartbeat` @@ -1084,15 +1083,15 @@ IRC працює через розширення й налаштовується 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 | ... + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1102,13 +1101,13 @@ IRC працює через розширення й налаштовується } ``` -- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація API key) або `1h` (OAuth-автентифікація). Задайте `0m`, щоб вимкнути. -- `suppressToolErrorWarnings`: якщо true, приглушує payload-и попереджень про помилки інструментів під час 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`, **heartbeat запускаються лише для цих агентів**. -- Heartbeat запускають повні ходи агента — коротші інтервали витрачають більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API key) або `1h` (OAuth-автентифікація). Встановіть `0m`, щоб вимкнути. +- `suppressToolErrorWarnings`: коли true, пригнічує payload-и попереджень про помилки інструментів під час запусків 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`, heartbeat запускаються **лише для цих агентів**. +- Heartbeat виконують повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1121,10 +1120,10 @@ IRC працює через розширення й налаштовується 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: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну ін’єкцію + model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction + notifyUser: true, // надіслати коротке повідомлення користувачу, коли починається compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1137,18 +1136,18 @@ IRC працює через розширення й налаштовується } ``` -- `mode`: `default` або `safeguard` (підсумовування блоками для довгих історій). Див. [Compaction](/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 доступний лише для читання. +- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типово: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час compaction summarization. +- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які потрібно повторно інжектувати після compaction. Типово `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторну ін’єкцію. Коли значення не задано або явно дорівнює цій типовій парі, старі заголовки `Every Session`/`Safety` також приймаються як застарілий fallback. +- `model`: необов’язкове перевизначення `provider/model-id` лише для compaction summarization. Використовуйте це, якщо основна сесія має лишатися на одній моделі, а підсумки compaction повинні запускатися на іншій; коли не задано, compaction використовує primary model сесії. +- `notifyUser`: коли `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction відбувалася безшумно. +- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження стійких спогадів. Пропускається, коли workspace лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед відправленням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1156,7 +1155,7 @@ IRC працює через розширення й налаштовується 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, @@ -1172,23 +1171,23 @@ IRC працює через розширення й налаштовується -- `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко обрізає надто великі результати інструментів, а потім повністю очищає старіші результати інструментів, якщо це потрібно. +- `mode: "cache-ttl"` вмикає проходи pruning. +- `ttl` керує тим, як часто pruning може виконуватись знову (після останнього звернення до кешу). +- Pruning спочатку м’яко обрізає завеликі результати інструментів, а потім, якщо потрібно, повністю очищає старіші результати інструментів. -**Soft-trim** зберігає початок і кінець та вставляє `...` посередині. +**Soft-trim** зберігає початок + кінець і вставляє `...` посередині. -**Hard-clear** замінює весь результат інструмента заповнювачем. +**Hard-clear** повністю замінює результат інструмента на placeholder. Примітки: -- Блоки зображень ніколи не обрізаються/не очищаються. -- Співвідношення рахуються за символами (приблизно), а не за точними токенами. -- Якщо є менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. +- Блоки зображень ніколи не обрізаються/очищаються. +- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень assistant, pruning пропускається. -Докладніше див. [Обрізання сесії](/concepts/session-pruning). +Докладніше про поведінку див. [Обрізання сесій](/uk/concepts/session-pruning). ### Block streaming @@ -1200,19 +1199,19 @@ IRC працює через розширення й налаштовується 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`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, потрібен явний `*.blockStreaming: true`, щоб увімкнути блочні відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти на рівні облікового запису). Signal/Slack/Discord/Google Chat типово мають `minChars: 1500`. +- `humanDelay`: рандомізована пауза між блочними відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Див. [Streaming](/concepts/streaming) для подробиць про поведінку та chunking. +Докладніше про поведінку й chunking див. [Streaming](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -1225,16 +1224,16 @@ IRC працює через розширення й налаштовується } ``` -- Типові значення: `instant` для особистих чатів/згадок, `message` для групових чатів без згадки. +- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. - Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору](/concepts/typing-indicators). +Докладніше див. [Індикатори набору тексту](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкове sandbox-ізолювання для вбудованого агента. Повний посібник див. в [Sandboxing](/gateway/sandboxing). +Необов’язковий sandboxing для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1280,7 +1279,7 @@ IRC працює через розширення й налаштовується identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // Також підтримуються SecretRef / inline contents: // 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" }, @@ -1329,54 +1328,54 @@ IRC працює через розширення й налаштовується } ``` - + -**Бекенд:** +**Backend:** -- `docker`: локальний Docker runtime (типово) -- `ssh`: універсальний віддалений runtime на базі SSH +- `docker`: локальне runtime Docker (типово) +- `ssh`: універсальне віддалене runtime через SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до `plugins.entries.openshell.config`. -**Конфігурація бекенда SSH:** +**Конфігурація SSH backend:** -- `target`: ціль SSH у формі `user@host[:port]` -- `command`: команда клієнта SSH (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь для workspace за кожною областю +- `target`: SSH target у форматі `user@host[:port]` +- `command`: команда SSH-клієнта (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за scope - `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час runtime -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики host key OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: inline contents або SecretRef, які OpenClaw materialize-ить у тимчасові файли під час runtime +- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет автентифікації SSH:** +**Пріоритет SSH auth:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на базі SecretRef визначаються з активного snapshot runtime секретів перед запуском sandbox-сесії +- Значення `*Data`, підкріплені SecretRef, визначаються з активного runtime snapshot секретів до початку sandbox session -**Поведінка бекенда SSH:** +**Поведінка SSH backend:** -- один раз ініціалізує віддалений workspace після створення або повторного створення -- далі зберігає віддалений workspace SSH як канонічний -- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH -- не синхронізує віддалені зміни назад на хост автоматично -- не підтримує browser-контейнери sandbox +- один раз seed-ить віддалений workspace після створення або повторного створення +- потім зберігає віддалений SSH workspace канонічним +- маршрутизує `exec`, файлові інструменти та медіашляхи через SSH +- не синхронізує автоматично віддалені зміни назад на хост +- не підтримує sandbox browser containers **Доступ до workspace:** -- `none`: workspace sandbox за областю в `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано лише для читання в `/agent` -- `rw`: workspace агента змонтовано з читанням/записом у `/workspace` +- `none`: sandbox workspace за scope у `~/.openclaw/sandboxes` +- `ro`: sandbox workspace у `/workspace`, workspace агента монтується лише для читання в `/agent` +- `rw`: workspace агента монтується читання/запис у `/workspace` -**Область:** +**Scope:** -- `session`: окремий контейнер + workspace для кожної сесії +- `session`: контейнер + workspace для кожної сесії - `agent`: один контейнер + workspace на агента (типово) - `shared`: спільний контейнер і workspace (без ізоляції між сесіями) -**Конфігурація плагіна OpenShell:** +**Конфігурація plugin OpenShell:** ```json5 { @@ -1389,10 +1388,10 @@ IRC працює через розширення й налаштовується 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", // необов’язковий policy id OpenShell + providers: ["openai"], // необов’язково autoProviders: true, timeoutSeconds: 120, }, @@ -1404,29 +1403,29 @@ IRC працює через розширення й налаштовується **Режим OpenShell:** -- `mirror`: засіває віддалений workspace з локального перед exec, синхронізує назад після exec; локальний workspace залишається канонічним -- `remote`: один раз засіває віддалений workspace під час створення sandbox, а потім зберігає віддалений workspace канонічним +- `mirror`: seed віддаленого середовища з локального перед exec, синхронізація назад після exec; локальний workspace лишається канонічним +- `remote`: один раз seed віддаленого середовища під час створення sandbox, після чого канонічним лишається віддалений workspace -У режимі `remote` редагування на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після етапу засівання. -Транспортом є SSH у sandbox OpenShell, але плагін керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні правки хоста, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку seed. +Транспорт — SSH у sandbox OpenShell, але plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, кореневої файлової системи з можливістю запису та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує network egress, записуваного root і користувача root. -**Контейнери типово мають `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово також заблоковано, якщо ви явно не задасте +**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або custom bridge network), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Вхідні вкладення** тимчасово розміщуються в `media/inbound/*` в активному workspace. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента зливаються. +**`docker.binds`** монтує додаткові каталоги хоста; global і per-agent binds об’єднуються. -**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний промпт. Не вимагає `browser.enabled` в `openclaw.json`. -Для спостереження через noVNC типово використовується автентифікація VNC, а OpenClaw видає короткоживучий URL із токеном (замість того, щоб розкривати пароль у спільному URL). +**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC інжектується в системний prompt. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача noVNC типово використовує VNC auth, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує націлення sandbox-сесій на browser хоста. -- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли ви свідомо хочете глобальну bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхід до CDP на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser sandbox. Якщо його встановлено (включно з `[]`), він замінює `docker.binds` для контейнера browser. +- `allowHostControl: false` (типово) блокує націлювання sandboxed sessions на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (окрема bridge network). Встановлюйте `bridge` лише тоді, коли вам свідомо потрібна глобальна bridge connectivity. +- `cdpSourceRange` необов’язково обмежує CDP ingress на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox browser. Якщо задано (включно з `[]`), це замінює `docker.binds` для browser container. - Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1446,26 +1445,26 @@ IRC працює через розширення й налаштовується - `--metrics-recording-only` - `--disable-extensions` (типово увімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - увімкнені типово й можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо робочому процесу потрібен WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + типово увімкнені та можуть бути вимкнені за допомогою + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш workflow залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; задайте `0`, щоб використати + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типовий ліміт процесів Chromium. - - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. - - Типові значення — це базова конфігурація образу контейнера; щоб змінити типові значення контейнера, використовуйте власний образ browser із власною - entrypoint. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; щоб змінити типові значення контейнера, використовуйте власний + browser image із власною entrypoint. -Sandbox browser і `sandbox.docker.binds` наразі підтримуються лише для Docker. +Browser 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 image +scripts/sandbox-browser-setup.sh # необов’язковий browser image ``` ### `agents.list` (перевизначення для окремого агента) @@ -1480,12 +1479,12 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", 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" }, // перевизначає відповідні defaults.models params по ключу + skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", theme: "helpful sloth", @@ -1516,26 +1515,26 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: стабільний ID агента (обов’язково). -- `default`: якщо встановлено кілька, перший перемагає (у журнал пишеться попередження). Якщо не встановлено жодного, типовим стає перший запис списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron jobs, які перевизначають лише `primary`, все одно успадковують типові fallback, якщо ви явно не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. -- `skills`: необов’язковий allowlist 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. +- `id`: стабільний id агента (обов’язково). +- `default`: якщо задано кілька, перший перемагає (у лог пишеться попередження). Якщо не задано жодного, типовим є перший елемент списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback-и). Cron jobs, які перевизначають лише `primary`, усе одно успадковують типові fallback-и, якщо ви не задасте `fallbacks: []`. +- `params`: параметри потоку для конкретного агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для агент-специфічних перевизначень на кшталт `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий allowlist 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`: allowlist ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія-запитувач виконується в sandbox, `sessions_spawn` відхиляє цілі, які працювали б поза sandbox. -- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, які пропускають `agentId` (вимагає явного вибору профілю; типово: false). +- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія запитувача sandbox-ована, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, що не містять `agentId` (примушує до явного вибору профілю; типово: false). --- -## Маршрутизація кількох агентів +## Маршрутизація між агентами -Запускайте кількох ізольованих агентів в одному Gateway. Див. [Кілька агентів](/concepts/multi-agent). +Запускайте кілька ізольованих агентів всередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1552,29 +1551,29 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля зіставлення прив’язок +### Поля match у bindings -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип пропущено, за замовчуванням це route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній type типово означає route), `acp` для постійних ACP bindings розмов. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) +- `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: "*"` (на рівні всього каналу) +4. `match.accountId` (точний, без peer/guild/team) +5. `match.accountId: "*"` (на весь канал) 6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route binding, наведений вище. -### Профілі доступу для окремого агента +### Профілі доступу для окремих агентів @@ -1594,7 +1593,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1623,7 +1622,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1669,7 +1668,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -Докладніше про пріоритети див. у [Sandbox і Tools для кількох агентів](/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. [Sandbox і інструменти для Multi-Agent](/uk/tools/multi-agent-sandbox-tools). --- @@ -1695,22 +1694,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, // типове auto-unfocus за неактивністю в годинах (`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" } }], @@ -1720,36 +1719,36 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу мають одну спільну сесію (використовуйте лише тоді, коли справді потрібен спільний контекст). + - `global`: усі учасники в контексті каналу ділять одну спільну сесію (використовуйте лише коли спільний контекст справді потрібен). - **`dmScope`**: як групуються DM. - - `main`: усі DM ділять одну основну сесію. - - `per-peer`: ізолювати за ID відправника між каналами. - - `per-channel-peer`: ізолювати за каналом + відправником (рекомендовано для вхідних скриньок із кількома користувачами). - - `per-account-channel-peer`: ізолювати за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: зіставлення канонічних ID з peer-ами з префіксами провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика reset. `daily` виконує reset о `atHour` за локальним часом; `idle` — після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що спливає першим. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім `direct`. -- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, за якої дозволяється створення forked thread session (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову thread-сесію замість успадкування історії транскрипту батьківської сесії. - - Задайте `0`, щоб вимкнути цей захист і завжди дозволяти fork від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для основного контейнера direct-chat. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість reply-back ходів між агентами під час обміну agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny перемагає. -- **`maintenance`**: керування очищенням і зберіганням session-store. + - `main`: усі DM спільно використовують основну сесію. + - `per-peer`: ізоляція за id відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox на кількох користувачів). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості). +- **`identityLinks`**: зіставлення канонічних id з peer-ами з префіксом провайдера для спільного використання сесії між каналами. +- **`reset`**: основна політика reset. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає те, що спливає раніше. +- **`resetByType`**: перевизначення для типів (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. +- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, дозволена при створенні fork-нутої thread session (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову thread session замість успадкування історії transcript-а батька. + - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти fork від батька. +- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для основного bucket прямого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обміну agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny перемагає. +- **`maintenance`**: очищення сховища сесій + керування зберіганням. - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). + - `pruneAfter`: поріг віку для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротація `sessions.json`, коли файл перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; задайте `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише журналює попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. + - `rotateBytes`: ротувати `sessions.json`, коли він перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: строк зберігання архівів transcript-ів `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише пише попередження в лог; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до гілок. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне unfocus через бездіяльність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типовий auto-unfocus за неактивністю в годинах (`0` вимикає; провайдери можуть перевизначати) - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1761,7 +1760,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // або "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1776,7 +1775,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 вимикає byChannel: { whatsapp: 5000, slack: 1500, @@ -1790,34 +1789,34 @@ scripts/sandbox-browser-setup.sh # optional browser image Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. -**Змінні шаблону:** +**Шаблонні змінні:** -| Змінна | Опис | Приклад | -| ----------------- | -------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Ім’я identity агента | (те саме, що `"auto"`) | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}` | Ім’я identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. ### Ack reaction -- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Задайте `""`, щоб вимкнути. +- Типово бере `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. -- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає ack після відповіді в Slack, Discord і Telegram. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → fallback identity. +- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: видаляє ack після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не встановлено, реакції статусу лишаються ввімкненими, коли активні ack reactions. - У Telegram задайте це явно як `true`, щоб увімкнути реакції статусу життєвого циклу. + У Slack і Discord відсутність значення зберігає status reactions увімкненими, коли активні ack reactions. + У Telegram задайте це явно як `true`, щоб увімкнути status reactions. -### Inbound debounce +### Debounce для вхідних повідомлень -Пакетує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення негайно спричиняють flush. Команди керування обходять debounce. +Об’єднує швидкі текстові повідомлення від одного й того ж відправника в один хід агента. Media/вкладення скидаються негайно. Керувальні команди оминають debounce. ### TTS (text-to-speech) @@ -1860,12 +1859,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує auto-TTS. `/tts off|always|inbound|tagged` перевизначає значення для окремої сесії. +- `auto` керує auto-TTS. `/tts off|always|inbound|tagged` перевизначає це для сесії. - `summaryModel` перевизначає `agents.defaults.model.primary` для auto-summary. -- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово `false` (opt-in). -- API keys резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає ендпоїнт OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на не-OpenAI ендпоїнт, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку model/voice. +- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (opt-in). +- API key fallback-и: `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `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. --- @@ -1895,13 +1894,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) сумісні лише для старих конфігурацій і автоматично мігрують у `talk.providers.`. -- ID voice резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає звичайні рядки або об’єкти SecretRef. -- Резервний `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API для Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надсилати транскрипт. Якщо не встановлено, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька Talk providers. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. +- Voice ID fallback-и: `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. +- Fallback `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key для Talk не налаштовано. +- `providers.*.voiceAliases` дозволяє використовувати дружні імена у вказівках Talk. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після мовчання користувача, перш ніж надіслати transcript. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -1911,35 +1910,35 @@ scripts/sandbox-browser-setup.sh # optional browser image `tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: -Локальний onboarding типово встановлює для нових локальних конфігурацій `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` приймається як псевдонім для `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` | Усі вбудовані інструменти (без плагінів провайдерів) | +| Група | Інструменти | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| `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) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (deny перемагає). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть коли Docker sandbox вимкнено. +Глобальна політика allow/deny для інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard-и `*`. Застосовується навіть коли Docker sandbox вимкнено. ```json5 { @@ -1965,7 +1964,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує elevated-доступом exec поза sandbox: +Керує elevated exec access поза sandbox: ```json5 { @@ -1981,9 +1980,9 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати доступ. -- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються лише до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). +- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. +- `/elevated on|off|ask|full` зберігає стан для кожної сесії; inline-директиви застосовуються лише до одного повідомлення. +- Elevated `exec` обходить sandboxing і використовує налаштований шлях escape (`gateway` типово, або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2007,8 +2006,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **типово вимкнені**. Задайте `enabled: true`, щоб увімкнути виявлення. -Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки для циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2029,12 +2028,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `historySize`: максимальний розмір історії викликів інструментів, що зберігається для аналізу циклів. -- `warningThreshold`: поріг повторюваних шаблонів без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: жорсткий поріг повної зупинки для будь-якого запуску без прогресу. -- `detectors.genericRepeat`: попереджати про повторні виклики одного й того самого інструмента з однаковими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). +- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. +- `criticalThreshold`: вищий поріг повторень для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. +- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі polling-інструменти (`process.poll`, `command_status` тощо). - `detectors.pingPong`: попереджати/блокувати чергування пар шаблонів без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. @@ -2046,14 +2045,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, @@ -2070,7 +2069,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.media` -Налаштовує розуміння вхідних медіа (зображення/аудіо/відео): +Налаштовує розуміння вхідного медіа (зображення/аудіо/відео): ```json5 { @@ -2099,18 +2098,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + **Запис провайдера** (`type: "provider"` або пропущено): -- `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення ID моделі +- `provider`: id API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `model`: перевизначення id моделі - `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` -**CLI-запис** (`type: "cli"`): +**Запис CLI** (`type: "cli"`): - `command`: виконуваний файл -- `args`: шаблонізовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: аргументи з шаблонами (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** @@ -2118,7 +2117,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. - У разі помилки використовується наступний запис. -Автентифікація провайдера відбувається у стандартному порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. +Автентифікація провайдера використовує стандартний порядок: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. @@ -2137,9 +2136,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, на які сесії можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можна націлюватися за допомогою session tools (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, створені нею, наприклад subagent). +Типово: `tree` (поточна сесія + сесії, створені нею, наприклад subagents). ```json5 { @@ -2155,25 +2154,25 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `self`: лише поточний ключ сесії. -- `tree`: поточна сесія + сесії, створені поточною сесією (subagent). -- `agent`: будь-яка сесія, що належить поточному ID агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим ID агента). -- `all`: будь-яка сесія. Націлення між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `tree`: поточна сесія + сесії, створені поточною сесією (subagents). +- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви використовуєте сесії per-sender під тим самим id агента). +- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- Обмеження sandbox: коли поточна сесія sandbox-ована і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово зводиться до `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Керує підтримкою вбудованих вкладень для `sessions_spawn`. +Керує підтримкою inline-вкладень для `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, щоб дозволити inline file attachments + 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" }, }, }, @@ -2182,22 +2181,22 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP відхиляє їх. -- Файли матеріалізуються в дочірньому workspace в `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується при збереженні транскрипту. -- Входи Base64 перевіряються суворою перевіркою алфавіту/паддінгу та захистом розміру до декодування. -- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення підпорядковується політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. +- Файли materialize-яться в дочірньому workspace за шляхом `.openclaw/attachments//` із `.manifest.json`. +- Вміст вкладень автоматично редагується з transcript persistence. +- Входи base64 перевіряються з суворою перевіркою алфавіту/падінгу і захистом за розміром до декодування. +- Дозволи на файли: `0700` для каталогів і `0600` для файлів. +- Очищення слідує політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапори експериментальних вбудованих інструментів. Типово вимкнено, якщо немає автоматичного вмикання, специфічного для runtime. +Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило auto-enable, специфічне для runtime. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // увімкнути експериментальний update_plan }, }, } @@ -2206,8 +2205,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типово: `false` для не-OpenAI провайдерів. Запуски OpenAI та OpenAI Codex вмикають його автоматично. -- Коли його увімкнено, системний промпт також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи і тримала максимум один крок у стані `in_progress`. +- Типово: `false` для провайдерів, відмінних від OpenAI. Запуски OpenAI і OpenAI Codex вмикають його автоматично. +- Коли ввімкнено, системний prompt також додає вказівки щодо використання, щоб модель використовувала його лише для суттєвої роботи та тримала максимум один крок у стані `in_progress`. ### `agents.defaults.subagents` @@ -2227,21 +2226,21 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: типова модель для створених sub-agent. Якщо пропущено, sub-agent успадковують модель викликувача. -- `allowAgents`: типовий allowlist ID цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає без тайм-ауту. +- `model`: типова модель для породжених sub-agents. Якщо пропущено, sub-agents успадковують модель виклику. +- `allowAgents`: типовий allowlist цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (секунди) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає без тайм-ауту. - Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Кастомні провайдери та base URLs +## Власні провайдери і 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", @@ -2265,46 +2264,46 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для кастомних потреб автентифікації. -- Перевизначення кореня конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім env). -- Порядок злиття для відповідних ID провайдерів: - - Непорожні значення `baseUrl` в agent `models.json` мають пріоритет. +- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. +- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). +- Пріоритет злиття для однакових id провайдерів: + - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. - Непорожні значення `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, якщо його задано; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + - Для провайдерів `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 cap, якщо він заданий; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів залежить від джерела: маркери записуються з активного snapshot конфігурації джерела (до визначення значень), а не з уже визначених runtime-значень секретів. + - Збереження маркерів є source-authoritative: маркери записуються з активного знімка конфігурації джерела (до resolution), а не з розгорнутих runtime secret values. -### Подробиці полів провайдера +### Деталі полів провайдера -- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: карта кастомних провайдерів із ключем за ID провайдера. +- `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). +- `models.providers`: мапа власних провайдерів, ключована за id провайдера. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (краще через SecretRef/env substitution). +- `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 upstream API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (зливаються з типовими для провайдера). Значення приймають SecretRef. +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` інжектувати `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, якщо це потрібно. +- `models.providers.*.baseUrl`: base URL API upstream. +- `models.providers.*.headers`: додаткові статичні заголовки для proxy/tenant routing. +- `models.providers.*.request`: транспортні перевизначення для HTTP-запитів model-provider. + - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. + - `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. +- `models.providers.*.models.*.contextTokens`: необов’язковий runtime cap контексту. Використовуйте це, якщо вам потрібен менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `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 для 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.refreshInterval`: інтервал polling для оновлення discovery. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервні максимальні вихідні токени для виявлених моделей. ### Приклади провайдерів @@ -2342,7 +2341,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -2376,11 +2375,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Задайте `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Задайте `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як alias-и. Скорочення: `openclaw onboard --auth-choice zai-api-key`. -- Загальний ендпоїнт: `https://api.z.ai/api/paas/v4` -- Coding endpoint (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального ендпоїнта визначте кастомного провайдера з перевизначенням base URL. +- Загальний endpoint: `https://api.z.ai/api/paas/v4` +- Coding endpoint (типово): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте власного провайдера з перевизначенням base URL. @@ -2419,11 +2418,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Для China 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`. -Нативні ендпоїнти Moonshot заявляють сумісність зі streaming usage на спільному -транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями ендпоїнта, -а не лише за ID вбудованого провайдера. +Нативні endpoint-и Moonshot повідомляють про сумісність використання стримінгу на спільному +транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями endpoint-а, +а не лише за id вбудованого провайдера. @@ -2441,11 +2440,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2484,7 +2483,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - + ```json5 { @@ -2523,8 +2522,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й Задайте `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. -Каталог моделей тепер типово містить лише M2.7. -На Anthropic-сумісному шляху streaming OpenClaw типово вимикає thinking MiniMax, +Каталог моделей тепер типово використовує лише M2.7. +На Anthropic-compatible streaming path OpenClaw типово вимикає thinking для MiniMax, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2533,7 +2532,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Локальні моделі](/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте хостовані моделі злитими для fallback. +Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте hosted models об’єднаними для fallback. @@ -2554,7 +2553,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 }, @@ -2564,13 +2563,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills це не зачіпає). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: якщо true, надавати перевагу інсталяторам Homebrew, коли доступний `brew`, перед переходом до інших типів інсталяції. -- `install.nodeManager`: бажаний node-інсталятор для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли true, спочатку надавати перевагу встановленню через Homebrew, якщо + доступний `brew`, а вже потім переходити до інших типів інсталяторів. +- `install.nodeManager`: бажаний менеджер встановлення node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручне поле API key на рівні Skill (коли підтримується Skill). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручне поле API key для Skills, що оголошують основну env var (відкритий рядок або об’єкт SecretRef). --- @@ -2598,34 +2598,34 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також з `plugins.load.paths`. -- Discovery приймає нативні plugins OpenClaw, а також сумісні bundled plugins Codex і Claude, включно з bundles Claude у типовому layout без manifest. -- **Зміни конфігурації вимагають перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише вказані 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`. Це стосується нативних hook-ів plugin і підтримуваних каталогів hook-ів із bundles. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому plugin запитувати перевизначення `provider` і `model` для запусків background subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений plugin (перевіряється нативною схемою plugin OpenClaw, якщо доступна). +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Discovery приймає нативні plugins OpenClaw, а також сумісні bundle-и Codex і Claude, включно з bundle-ами Claude з типовою структурою без manifest. +- **Зміни конфігурації потребують перезапуску шлюзу.** +- `allow`: необов’язковий allowlist (завантажуються лише plugins зі списку). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API key на рівні plugin (коли це підтримується plugin-ом). +- `plugins.entries..env`: мапа env vars у scope plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля legacy `before_agent_start`, що мутують prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Застосовується до нативних hooks plugin-ів і підтримуваних каталогів hooks, наданих bundle-ами. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому plugin-у запитувати перевизначення `provider` і `model` для одного запуску фонових subagent runs. +- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений plugin-ом (перевіряється нативною схемою plugin OpenClaw, якщо вона доступна). - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно використовується `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env var `FIRECRAWL_API_KEY`. - - `baseUrl`: базова URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний контент зі сторінок (типово: `true`). + - `baseUrl`: base URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search). + - `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті (експериментально). Режими й пороги див. у [Dreaming](/concepts/dreaming). - - `mode`: готовий режим періодичності dreaming (`"off"`, `"core"`, `"rem"`, `"deep"`). Типово: `"off"`. +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming (експериментально). Режими та пороги див. у [Dreaming](/uk/concepts/dreaming). + - `mode`: пресет cadence dreaming (`"off"`, `"core"`, `"rem"`, `"deep"`). Типово: `"off"`. - `cron`: необов’язкове перевизначення cron-виразу для розкладу dreaming. - - `timezone`: часовий пояс для оцінки розкладу (резервно береться з `agents.defaults.userTimezone`). - - `limit`: максимальна кількість кандидатів, які підвищуються за один цикл. + - `timezone`: часовий пояс для обчислення розкладу (резервно бере `agents.defaults.userTimezone`). + - `limit`: максимальна кількість кандидатів для підвищення за цикл. - `minScore`: мінімальний поріг зваженої оцінки для підвищення. - - `minRecallCount`: мінімальний поріг кількості пригадувань. - - `minUniqueQueries`: мінімальний поріг кількості унікальних запитів. - - `recencyHalfLifeDays`: кількість днів, за які оцінка давності зменшується вдвічі. Типово: `14`. - - `maxAgeDays`: необов’язковий максимальний вік щоденних нотаток у днях, дозволений для підвищення. - - `verboseLogging`: виводити детальні журнали dreaming для кожного запуску в звичайний потік журналів gateway. -- Увімкнені bundles Claude plugins також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як сані \ No newline at end of file + - `minRecallCount`: мінімальний поріг кількості згадувань. + - `minUniqueQueries`: мінімальна кількість різних запитів. + - `recencyHalfLifeDays`: кількість днів, за яку оцінка недавності зменшується вдвічі. Типово: `14`. + - `maxAgeDays`: необов’язковий максимальний вік daily note в днях, дозволений для підвищення. + - `verboseLogging`: виводити детальні логи dreaming для кожного запуску у звичайний потік логів шлюзу. +- Увімкнені Claude bundle plugins також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не \ No newline at end of file diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index e89c3cfa7..8723da881 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -1,186 +1,182 @@ --- read_when: - - Створення або налагодження нативних плагінів OpenClaw - - Розуміння моделі можливостей плагінів або меж відповідальності - - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація runtime-хуків провайдера або канальних плагінів + - Створення або налагодження нативних plugin OpenClaw + - Розуміння моделі можливостей plugin або меж володіння + - Робота над конвеєром завантаження plugin або реєстром + - Реалізація runtime-хуків провайдера або channel plugins sidebarTitle: Internals -summary: 'Внутрішня будова плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та runtime-хелпери' -title: Внутрішня будова плагінів +summary: 'Внутрішні компоненти plugin: модель можливостей, межі володіння, контракти, конвеєр завантаження та допоміжні засоби runtime' +title: Внутрішні компоненти Plugin x-i18n: - generated_at: "2026-04-05T18:14:57Z" + generated_at: "2026-04-05T18:52:03Z" model: gpt-5.4 provider: openai - source_hash: 1bc9d7261c3c7878d37140be77f210dd262d6c3edee2491ea534aa599e2800c0 + source_hash: 70424e2745e6e289aa2e7ff899d33bea4b04f5c18bd3f73de38287f788bd939b source_path: plugins/architecture.md workflow: 15 --- -# Внутрішня будова плагінів +# Внутрішні компоненти Plugin - Це **поглиблений довідник з архітектури**. Практичні посібники див. тут: - - [Install and use plugins](/tools/plugin) — посібник для користувача - - [Getting Started](/plugins/building-plugins) — перший навчальний посібник зі створення плагіна - - [Channel Plugins](/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Provider Plugins](/plugins/sdk-provider-plugins) — створення провайдера моделей - - [SDK Overview](/plugins/sdk-overview) — карта імпортів і API реєстрації + Це **довідник з глибокої архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання plugin](/uk/tools/plugin) — посібник для користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення plugin + - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями + - [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей + - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації -На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. +Ця сторінка описує внутрішню архітектуру системи plugin OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** в OpenClaw. Кожен -нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: +Можливості — це публічна модель **нативних plugin** всередині OpenClaw. Кожен +нативний plugin OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади плагінів | -| ---------------------- | ----------------------------------------------- | ------------------------------------ | -| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI-бекенд інференсу | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | +| Можливість | Метод реєстрації | Приклади plugin | +| --------------------- | ---------------------------------------------- | ----------------------------------- | +| Текстовий inference | `api.registerProvider(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрипція в realtime | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Голос у realtime | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або -сервіси, є **застарілим плагіном лише з хуками**. Такий шаблон усе ще повністю підтримується. +Plugin, який не реєструє жодної можливості, але надає hooks, tools або +services, є **застарілим plugin лише з hooks**. Цей шаблон і далі повністю підтримується. -### Поточна позиція щодо зовнішньої сумісності +### Позиція щодо зовнішньої сумісності -Модель можливостей уже реалізована в core і використовується вбудованими/нативними плагінами -сьогодні, але сумісність із зовнішніми плагінами все ще потребує жорсткішої -планки, ніж «це експортується, отже воно незмінне». +Модель можливостей уже впроваджена в core і сьогодні використовується +вбудованими/нативними plugins, але сумісність із зовнішніми plugins усе ще +потребує вищої планки, ніж "це експортується, отже це вже зафіксовано." Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте +- **наявні зовнішні plugins:** зберігайте працездатність інтеграцій на основі hooks; вважайте це базовим рівнем сумісності -- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей замість - vendor-specific доступів напряму або нових дизайнів лише з хуками -- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але - вважайте допоміжні поверхні, специфічні для можливостей, такими, що ще розвиваються, якщо в документації - контракт явно не позначено як стабільний +- **нові вбудовані/нативні plugins:** віддавайте перевагу явній реєстрації можливостей, а не + vendor-специфічним прямим зверненням або новим дизайнам лише з hooks +- **зовнішні plugins, що переходять на реєстрацію можливостей:** це дозволено, але + capability-специфічні допоміжні поверхні слід вважати такими, що еволюціонують, якщо в документації контракт явно не позначено як стабільний Практичне правило: - API реєстрації можливостей — це бажаний напрямок -- застарілі хуки залишаються найбезпечнішим шляхом без порушень для зовнішніх плагінів під час +- застарілі hooks залишаються найбезпечнішим шляхом без зламів для зовнішніх plugins під час переходу -- не всі експортовані підшляхи-хелпери однаково стабільні; віддавайте перевагу вузькому - задокументованому контракту, а не випадковим експортам хелперів +- не всі експортовані допоміжні subpaths однакові; віддавайте перевагу вузькому задокументованому + контракту, а не випадковим допоміжним експортам -### Форми плагінів +### Форми plugin -OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки під час реєстрації (а не лише статичних метаданих): +OpenClaw класифікує кожен завантажений plugin за формою на основі його фактичної +поведінки реєстрації (а не лише статичних метаданих): - **plain-capability** -- реєструє рівно один тип можливості (наприклад, - плагін лише з провайдером, як-от `mistral`) + plugin лише для провайдера, як-от `mistral`) - **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовим інференсом, мовленням, розумінням медіа та + `openai` володіє текстовим inference, мовленням, розумінням медіа та генерацією зображень) -- **hook-only** -- реєструє лише хуки (типізовані або кастомні), без можливостей, - інструментів, команд чи сервісів -- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не - можливості +- **hook-only** -- реєструє лише hooks (типізовані або custom), без можливостей, + tools, commands чи services +- **non-capability** -- реєструє tools, commands, services або routes, але не можливості -Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та розподіл -можливостей. Докладніше див. [CLI reference](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму plugin і +розподіл можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). -### Застарілі хуки +### Застарілі hooks -Хук `before_agent_start` залишається підтримуваним як шлях сумісності для -плагінів лише з хуками. Застарілі реальні плагіни все ще залежать від нього. +Hook `before_agent_start` залишається підтримуваним як шлях сумісності для +plugin лише з hooks. Реальні застарілі plugins усе ще залежать від нього. Напрямок: -- зберігати його працездатність +- зберігати його працездатним - документувати його як застарілий -- для роботи з перевизначенням моделі/провайдера віддавати перевагу `before_model_resolve` -- для мутації prompt — `before_prompt_build` -- видаляти лише після падіння реального використання та підтвердження безпечної міграції - покриттям фікстур +- для перевизначення моделі/провайдера віддавати перевагу `before_model_resolve` +- для мутації prompt віддавати перевагу `before_prompt_build` +- видаляти лише після зниження реального використання та після того, як покриття fixture підтвердить безпеку міграції ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити -одну з цих міток: +один із цих маркерів: -| Сигнал | Значення | -| -------------------------- | ------------------------------------------------------------- | -| **config valid** | Конфігурація коректно розбирається, а плагіни успішно визначаються | -| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який застарів | -| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | +| Сигнал | Значення | +| -------------------------- | ----------------------------------------------------------- | +| **config valid** | Конфігурація успішно парситься, і plugins коректно визначаються | +| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | +| **legacy warning** | Plugin використовує `before_agent_start`, який вважається застарілим | +| **hard error** | Конфігурація недійсна або plugin не вдалося завантажити | -Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш плагін -- -`hook-only` є рекомендаційним сигналом, а `before_agent_start` викликає лише попередження. Ці +Ні `hook-only`, ні `before_agent_start` не зламають ваш plugin сьогодні -- +`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури -Система плагінів OpenClaw має чотири шари: +Система plugin OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить кандидатів на плагіни в налаштованих шляхах, коренях робочих просторів, - глобальних коренях розширень і серед вбудованих розширень. Виявлення спочатку читає нативні - маніфести `openclaw.plugin.json` і маніфести підтримуваних пакетів. + OpenClaw знаходить потенційні plugins у налаштованих шляхах, коренях workspace, + глобальних коренях extension і серед вбудованих extension. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json` разом із підтримуваними маніфестами bundle. 2. **Увімкнення + валідація** - Core вирішує, чи виявлений плагін увімкнено, вимкнено, заблоковано або - вибрано для ексклюзивного слота, наприклад memory. -3. **Завантаження runtime** - Нативні плагіни OpenClaw завантажуються в тому ж процесі через jiti і реєструють - можливості в центральному реєстрі. Сумісні пакети нормалізуються до записів - реєстру без імпорту коду runtime. + Core вирішує, чи є знайдений plugin увімкненим, вимкненим, заблокованим або + вибраним для ексклюзивного слота, наприклад memory. +3. **Runtime-завантаження** + Нативні plugins OpenClaw завантажуються in-process через jiti і реєструють + можливості в центральному реєстрі. Сумісні bundles нормалізуються в записи + реєстру без імпорту runtime-коду. 4. **Використання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування - провайдерів, хуки, HTTP-маршрути, команди CLI та сервіси. + Решта OpenClaw читає реєстр, щоб надавати tools, channels, налаштування provider, + hooks, HTTP routes, CLI commands і services. -Зокрема для CLI плагінів виявлення кореневих команд поділено на дві фази: +Для CLI plugin зокрема, виявлення кореневих команд розділено на дві фази: -- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику +- метадані під час парсингу походять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI plugin може залишатися lazy і реєструватися лише під час першого виклику -Це дозволяє зберігати код CLI, який належить плагіну, усередині плагіна, водночас даючи OpenClaw -змогу зарезервувати імена кореневих команд до розбору. +Це дозволяє утримувати код CLI, що належить plugin, всередині plugin, при цьому OpenClaw +може резервувати імена кореневих команд до початку парсингу. -Важлива межа дизайну: +Важлива межа проєктування: -- виявлення + валідація конфігурації мають працювати з **метаданих маніфесту/схеми** - без виконання коду плагіна -- нативна поведінка runtime надходить із шляху `register(api)` у модулі плагіна +- виявлення + валідація config мають працювати на основі **метаданих маніфесту/схеми** + без виконання коду plugin +- нативна runtime-поведінка походить із шляху `register(api)` модуля plugin -Такий поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та -будувати підказки для UI/схеми ще до повної активації runtime. +Такий поділ дозволяє OpenClaw перевіряти config, пояснювати відсутні/вимкнені plugins і +будувати підказки UI/схеми до повної активації runtime. -### Канальні плагіни та спільний інструмент повідомлень +### Channel plugins і спільний tool повідомлень -Канальним плагінам не потрібно реєструвати окремий інструмент send/edit/react для -звичайних дій чату. OpenClaw зберігає один спільний інструмент `message` у core, а -канальні плагіни володіють специфічним для каналу виявленням та виконанням за ним. +Channel plugins не повинні реєструвати окремий tool send/edit/react для +звичайних дій у чаті. OpenClaw підтримує один спільний core tool `message`, а +channel plugins володіють channel-специфічним виявленням і виконанням за ним. Поточна межа така: -- core володіє хостом спільного інструмента `message`, wiring для prompt, - обліком сесій/потоків і диспетчеризацією виконання -- канальні плагіни володіють виявленням scoped-дій, виявленням можливостей і будь-якими - фрагментами схеми, специфічними для каналу -- канальні плагіни володіють граматикою розмов сесії, специфічною для провайдера, наприклад - тим, як conversation id кодують thread id або успадковуються від батьківських розмов -- канальні плагіни виконують фінальну дію через свій action adapter +- core володіє спільним host tool `message`, підключенням prompt, + обліком session/thread і диспетчеризацією виконання +- channel plugins володіють виявленням дій в межах scope, виявленням можливостей + і будь-якими channel-специфічними фрагментами schema +- channel plugins володіють provider-специфічною граматикою conversation session, зокрема + тим, як ідентифікатори conversation кодують ідентифікатори thread або успадковуються від батьківських conversations +- channel plugins виконують фінальну дію через свій action adapter -Для канальних плагінів поверхня SDK — це -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну повертати видимі дії, можливості та внески у схему -разом, щоб ці частини не розходилися. +Для channel plugins поверхнею SDK є +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик +виявлення дозволяє plugin повертати видимі дії, можливості та внески до schema +разом, щоб ці частини не розходилися між собою. -Core передає scope runtime у цей крок виявлення. Важливі поля: +Core передає runtime scope в цей крок виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -191,123 +187,121 @@ Core передає scope runtime у цей крок виявлення. Важ - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати -дії з повідомленнями залежно від активного облікового запису, поточної кімнати/потоку/повідомлення або -ідентичності довіреного запитувача, не жорстко прописуючи специфічні для каналу гілки в -інструменті `message` у core. +Це важливо для context-sensitive plugins. Канал може приховувати або показувати +дії повідомлень залежно від активного облікового запису, поточної кімнати/thread/message або +довіреної ідентичності запитувача без жорсткого channel-специфічного branching у core tool `message`. -Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner -відповідає за передавання поточної ідентичності чату/сесії в межу -виявлення плагіна, щоб спільний інструмент `message` показував правильну поверхню, -яка належить каналу, для поточного ходу. +Саме тому зміни маршрутизації embedded-runner усе ще є роботою plugin: runner +відповідає за передавання поточної ідентичності chat/session до межі +виявлення plugin, щоб спільний tool `message` показував правильну channel-власну +поверхню для поточного кроку. -Для хелперів виконання, що належать каналу, вбудовані плагіни мають зберігати runtime -виконання у власних модулях розширення. Core більше не володіє runtime дій повідомлень -Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані -плагіни мають напряму імпортувати свій локальний runtime-код із -власних модулів розширення. +Для channel-власних допоміжних засобів виконання вбудовані plugins повинні +зберігати runtime виконання всередині своїх власних модулів extension. Core більше не володіє Discord, +Slack, Telegram або WhatsApp runtime дій повідомлень у `src/agents/tools`. +Ми не публікуємо окремі subpaths `plugin-sdk/*-action-runtime`, а вбудовані +plugins повинні імпортувати власний локальний runtime-код безпосередньо зі своїх +модулів extension. -Та сама межа застосовується до SDK-швів із назвами провайдерів загалом: core не -повинен імпортувати зручні channel-specific barrel для Slack, Discord, Signal, -WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, або використовуйте -власний `api.ts` / `runtime-api.ts` barrel вбудованого плагіна, або підніміть потребу -до вузької загальної можливості у спільному SDK. +Та сама межа застосовується до provider-іменованих швів SDK загалом: core не повинен +імпортувати channel-специфічні допоміжні barrels для Slack, Discord, Signal, +WhatsApp або подібних extension. Якщо core потрібна певна поведінка, або +використовуйте власний barrel `api.ts` / `runtime-api.ts` вбудованого plugin, або +підніміть цю потребу до вузької загальної можливості в спільному SDK. -Зокрема для опитувань є два шляхи виконання: +Зокрема для poll існує два шляхи виконання: -- `outbound.sendPoll` — це спільна базова лінія для каналів, що відповідають загальній - моделі опитувань -- `actions.handleAction("poll")` — бажаний шлях для специфічної для каналу - семантики опитувань або додаткових параметрів опитування +- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну модель + poll +- `actions.handleAction("poll")` — бажаний шлях для channel-специфічної семантики + poll або додаткових параметрів poll -Тепер core відкладає спільний розбір опитувань до моменту, коли dispatch опитування плагіна -відхиляє дію, тож обробники опитувань, які належать плагіну, можуть приймати поля -опитування, специфічні для каналу, без блокування з боку загального парсера опитувань. +Тепер core відкладає спільний парсинг poll до моменту, коли plugin-диспетчеризація poll +відхиляє дію, щоб handlers poll, що належать plugin, могли приймати channel-специфічні +поля poll без блокування з боку загального parser poll. -Повну послідовність запуску див. в [Load pipeline](#load-pipeline). +Повну послідовність запуску див. у [Конвеєрі завантаження](#load-pipeline). ## Модель володіння можливостями -OpenClaw розглядає нативний плагін як межу відповідальності для **компанії** або -**функції**, а не як набір не пов’язаних між собою інтеграцій. +OpenClaw розглядає нативний plugin як межу володіння для **компанії** або +**функції**, а не як набір несумісних між собою інтеграцій. Це означає: -- плагін компанії зазвичай має володіти всіма OpenClaw-поверхнями цієї компанії -- функціональний плагін зазвичай має володіти повною поверхнею функції, яку він додає -- канали мають споживати спільні можливості core замість того, щоб реалізовувати - поведінку провайдерів ad hoc +- plugin компанії зазвичай повинен володіти всіма surfaces цієї компанії, орієнтованими на OpenClaw +- plugin функції зазвичай повинен володіти повною surface запроваджуваної ним функції +- channels повинні використовувати спільні можливості core замість випадкового повторного + впровадження provider-поведінки Приклади: -- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI, а також - поведінкою OpenAI для мовлення, голосу в реальному часі, розуміння медіа й генерації зображень -- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs -- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft -- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також - поведінкою Google для розуміння медіа, генерації зображень і веб-пошуку -- вбудований плагін `firecrawl` володіє поведінкою веб-отримання Firecrawl -- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми - бекендами розуміння медіа -- плагін `voice-call` є функціональним плагіном: він володіє транспортом дзвінків, інструментами, - CLI, маршрутами та мостом Twilio media-stream, але споживає спільні можливості - мовлення, транскрипції в реальному часі та голосу в реальному часі, а не імпортує - вендорні плагіни напряму +- вбудований plugin `openai` володіє поведінкою провайдера моделей OpenAI і + поведінкою OpenAI для speech + realtime-voice + media-understanding + image-generation +- вбудований plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs +- вбудований plugin `microsoft` володіє поведінкою мовлення Microsoft +- вбудований plugin `google` володіє поведінкою провайдера моделей Google плюс + поведінкою Google для media-understanding + image-generation + web-search +- вбудований plugin `firecrawl` володіє поведінкою web-fetch Firecrawl +- вбудовані plugins `minimax`, `mistral`, `moonshot` і `zai` володіють своїми + backend для media-understanding +- plugin `voice-call` є plugin функції: він володіє transport дзвінків, tools, + CLI, routes і bridgеing медіапотоків Twilio, але використовує спільні можливості speech + плюс realtime-transcription і realtime-voice замість прямого імпорту vendor plugins Бажаний кінцевий стан: -- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та +- OpenAI живе в одному plugin, навіть якщо охоплює текстові моделі, мовлення, зображення і майбутнє відео -- інший вендор може зробити те саме для своєї поверхні -- каналам байдуже, який плагін вендора володіє провайдером; вони споживають - спільний контракт можливості, який надає core +- інший vendor може робити те саме для своєї власної surface +- channels не зважають на те, який plugin vendor володіє provider; вони використовують + спільний capability-контракт, який надає core -Ось ключове розрізнення: +Ось ключова відмінність: -- **плагін** = межа відповідальності -- **можливість** = контракт core, який можуть реалізувати або споживати кілька плагінів +- **plugin** = межа володіння +- **capability** = контракт core, який кілька plugins можуть реалізовувати або використовувати -Отже, якщо OpenClaw додає нову сферу, наприклад відео, перше запитання — не -«який провайдер має жорстко кодувати обробку відео?». Перше запитання — «який -контракт core для можливості відео?». Коли цей контракт існує, вендорні плагіни -можуть реєструватися для нього, а канальні/функціональні плагіни — споживати його. +Отже, якщо OpenClaw додає новий домен, наприклад відео, перше питання — +не "який provider має жорстко кодувати обробку відео?" Перше питання — +"який core-контракт можливості відео?" Щойно такий контракт з’являється, +plugins vendor можуть реєструватися для нього, а channel/feature plugins можуть його використовувати. -Якщо можливість ще не існує, правильний крок зазвичай такий: +Якщо можливості ще не існує, правильний крок зазвичай такий: 1. визначити відсутню можливість у core -2. відкрити її через API/runtime плагінів у типізований спосіб -3. під’єднати канали/функції до цієї можливості -4. дати вендорним плагінам зареєструвати реалізації +2. відкрити її через API/runtime plugin у типізованому вигляді +3. підключити channels/features до цієї можливості +4. дозволити plugins vendor реєструвати реалізації -Це зберігає явне володіння та водночас уникає поведінки core, яка залежить від -одного вендора або одноразового шляху коду, специфічного для плагіна. +Це зберігає явне володіння і водночас уникає поведінки core, яка залежить від +одного vendor або одноразового plugin-специфічного шляху коду. ### Шарування можливостей -Використовуйте таку ментальну модель, вирішуючи, де має жити код: +Користуйтеся цією ментальною моделлю, коли вирішуєте, де має бути код: -- **шар можливостей core**: спільна оркестрація, політика, резервні сценарії, правила - злиття конфігурації, семантика доставки та типізовані контракти -- **шар вендорного плагіна**: vendor-specific API, автентифікація, каталоги моделей, - синтез мовлення, генерація зображень, майбутні відеобекенди, endpoints використання -- **шар канального/функціонального плагіна**: інтеграції Slack/Discord/voice-call/etc., - які споживають можливості core і показують їх на певній поверхні +- **шар можливостей core**: спільна orchestration, policy, fallback, правила + злиття config, семантика доставки та типізовані контракти +- **шар plugin vendor**: vendor-специфічні API, auth, catalogs моделей, speech + synthesis, image generation, майбутні backend відео, endpoints usage +- **шар channel/feature plugin**: інтеграції Slack/Discord/voice-call тощо, + які використовують можливості core і представляють їх на surface Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком резервних сценаріїв, налаштуваннями та доставкою в канали -- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає runtime-хелпер TTS для телефонії +- core володіє policy TTS під час відповіді, порядком fallback, prefs і доставкою в channels +- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями synthesis +- `voice-call` використовує допоміжний засіб runtime TTS для telephony -Цей самий шаблон слід віддавати перевагу і для майбутніх можливостей. +Той самий шаблон слід віддавати перевагу і для майбутніх можливостей. -### Приклад плагіна компанії з кількома можливостями +### Приклад company plugin з кількома можливостями -Плагін компанії має виглядати цілісним ззовні. Якщо OpenClaw має спільні -контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веб-отримання та веб-пошуку, -вендор може володіти всіма своїми поверхнями в одному місці: +Plugin компанії повинен виглядати цілісно ззовні. Якщо OpenClaw має спільні +контракти для моделей, мовлення, транскрипції в realtime, голосу в realtime, розуміння медіа, +генерації зображень, генерації відео, web fetch і web search, vendor може +володіти всіма своїми surfaces в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -327,7 +321,7 @@ const plugin: OpenClawPluginDefinition = { api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — implement the SpeechProviderPlugin interface directly + // vendor speech config — directly implement the SpeechProviderPlugin interface }); api.registerMediaUnderstandingProvider({ @@ -361,183 +355,181 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви хелперів. Важлива форма: +Важливі не точні назви helpers. Важлива форма: -- один плагін володіє поверхнею вендора -- core усе одно володіє контрактами можливостей -- канали та функціональні плагіни споживають хелпери `api.runtime.*`, а не код вендора -- тести контрактів можуть перевіряти, що плагін зареєстрував можливості, якими - заявляє, що володіє +- один plugin володіє surface vendor +- core усе ще володіє контрактами можливостей +- channels і feature plugins використовують helpers `api.runtime.*`, а не vendor-код +- тести контрактів можуть перевіряти, що plugin зареєстрував можливості, якими + він заявляє, що володіє ### Приклад можливості: розуміння відео -OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. Та сама модель володіння застосовується й тут: +OpenClaw вже розглядає розуміння зображень/аудіо/відео як одну спільну +можливість. Та сама модель володіння застосовується і тут: 1. core визначає контракт media-understanding -2. вендорні плагіни реєструють `describeImage`, `transcribeAudio` і +2. plugins vendor реєструють `describeImage`, `transcribeAudio` і `describeVideo` за потреби -3. канали та функціональні плагіни споживають спільну поведінку core, а не - напряму підключаються до коду вендора +3. channels і feature plugins використовують спільну поведінку core замість + прямого підключення до vendor-коду -Це не дає вбудувати припущення одного провайдера щодо відео в core. Плагін володіє -поверхнею вендора; core володіє контрактом можливості та поведінкою резервних сценаріїв. +Це запобігає вбудовуванню припущень одного провайдера про відео в core. Plugin володіє +surface vendor; core володіє capability-контрактом і поведінкою fallback. Генерація відео вже використовує ту саму послідовність: core володіє типізованим -контрактом можливості та runtime-хелпером, а вендорні плагіни реєструють -реалізації `api.registerVideoGenerationProvider(...)`. +capability-контрактом і runtime helper, а plugins vendor реєструють +реалізації `api.registerVideoGenerationProvider(...)` для нього. -Потрібен конкретний контрольний список для впровадження? Див. -[Capability Cookbook](/tools/capability-cookbook). +Потрібен конкретний контрольний список впровадження? Див. +[Capability Cookbook](/uk/plugins/architecture). -## Контракти та примусове забезпечення +## Контракти та контроль -Поверхня API плагінів навмисно типізована й централізована в +Поверхня API plugin навмисно типізована й централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -runtime-хелпери, на які плагін може покладатися. +runtime helpers, на які plugin може покладатися. Чому це важливо: -- автори плагінів отримують єдиний стабільний внутрішній стандарт -- core може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють один і той самий - provider id -- під час запуску можна показувати діагностику, придатну до дій, для неправильно сформованих реєстрацій -- тести контрактів можуть забезпечувати володіння вбудованих плагінів і запобігати - тихому дрейфу +- автори plugin отримують єдиний стабільний внутрішній стандарт +- core може відхиляти дублювання володіння, наприклад коли два plugins реєструють один і той самий + id provider +- під час запуску можна показувати діагностику, придатну до дій, для хибної реєстрації +- тести контрактів можуть забезпечувати володіння вбудованими plugins і запобігати тихому дрейфу -Є два рівні забезпечення: +Є два шари контролю: -1. **забезпечення під час реєстрації runtime** - Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: - дубльовані provider id, дубльовані speech provider id і неправильно - сформовані реєстрації породжують діагностику плагінів замість невизначеної поведінки. +1. **контроль runtime-реєстрації** + Реєстр plugin перевіряє реєстрації під час завантаження plugins. Приклади: + дубльовані id provider, дубльовані id провайдерів мовлення та хибні + реєстрації породжують діагностику plugin замість невизначеної поведінки. 2. **тести контрактів** - Вбудовані плагіни фіксуються в реєстрах контрактів під час тестових запусків, тож - OpenClaw може явно перевіряти володіння. Сьогодні це використовується для моделей - провайдерів, провайдерів мовлення, провайдерів веб-пошуку та володіння - реєстрацією вбудованих компонентів. + Вбудовані plugins фіксуються в реєстрах контрактів під час запусків тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для model + providers, speech providers, web search providers і володіння реєстрацією вбудованих компонентів. -Практичний ефект у тому, що OpenClaw заздалегідь знає, який плагін чим -володіє. Це дозволяє core і каналам безшовно компонуватися, оскільки володіння -оголошене, типізоване й тестоване, а не неявне. +Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який plugin +володіє якою surface. Це дозволяє core і channels композиційно працювати, бо +володіння оголошене, типізоване й перевіряється тестами, а не є неявним. ### Що має належати контракту -Хороші контракти плагінів: +Хороші контракти plugin є: -- типізовані -- невеликі -- специфічні для можливості -- належать core -- придатні для повторного використання кількома плагінами -- споживані каналами/функціями без знання про вендора +- типізованими +- малими +- capability-специфічними +- такими, що належать core +- повторно використовуваними кількома plugins +- придатними до використання channels/features без знань про vendor -Погані контракти плагінів: +Погані контракти plugin є: -- політика, специфічна для вендора, прихована в core -- одноразові обходи для плагіна, що оминають реєстр -- код каналу, який напряму звертається до реалізації вендора -- ad hoc runtime-об’єкти, які не є частиною `OpenClawPluginApi` або +- vendor-специфічною policy, прихованою в core +- одноразовими лазівками plugin, які обходять реєстр +- кодом channel, що напряму лізе у реалізацію vendor +- ad hoc runtime-об’єктами, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтесь, підніміть рівень абстракції: спочатку визначте можливість, а потім -дозвольте плагінам підключатися до неї. +Якщо сумніваєтеся, піднімайте рівень абстракції: спочатку визначте можливість, а +потім дозвольте plugins підключатися до неї. ## Модель виконання -Нативні плагіни OpenClaw працюють **у тому ж процесі**, що й Gateway. Вони не -ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й -код core. +Нативні plugins OpenClaw працюють **in-process** із Gateway. Вони не +ізольовані. Завантажений нативний plugin має ту саму межу довіри на рівні процесу, +що й код core. Наслідки: -- нативний плагін може реєструвати інструменти, мережеві обробники, хуки й сервіси -- помилка нативного плагіна може аварійно завершити роботу шлюзу або дестабілізувати його -- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині +- нативний plugin може реєструвати tools, network handlers, hooks і services +- помилка в нативному plugin може аварійно завершити роботу gateway або дестабілізувати його +- шкідливий нативний plugin еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні пакети безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх -як пакети метаданих/контенту. У поточних релізах це переважно означає вбудовані +Сумісні bundles безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх +як metadata/content packs. У поточних релізах це здебільшого означає вбудовані Skills. -Для не вбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. -Розглядайте workspace plugins як код для розробки, а не як типові значення для продакшену. +Для невбудованих plugins використовуйте allowlists і явні шляхи install/load. Розглядайте +plugins workspace як код для часу розробки, а не як production-типові значення. -Для назв пакетів вбудованого робочого простору зберігайте plugin id, прив’язаний до npm-імені: -типово `@openclaw/` або затверджений типізований суфікс, як-от +Для назв пакетів у workspace, що містять вбудовані plugins, зберігайте прив’язку plugin id у назві npm: +`@openclaw/` за замовчуванням або затверджений типізований suffix на кшталт `-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли -пакет навмисно відкриває вужчу роль плагіна. +пакет навмисно надає вужчу роль plugin. -Важлива примітка про довіру: +Важлива примітка щодо довіри: -- `plugins.allow` довіряє **plugin id**, а не походженню джерела. -- Workspace plugin з тим самим id, що й у вбудованого плагіна, навмисно затіняє - вбудовану копію, коли такий workspace plugin увімкнено/додано в allowlist. -- Це нормально й корисно для локальної розробки, тестування патчів і hotfix-ів. +- `plugins.allow` довіряє **id plugin**, а не походженню джерела. +- Plugin workspace з тим самим id, що й вбудований plugin, навмисно затіняє + вбудовану копію, коли цей plugin workspace увімкнено/додано в allowlist. +- Це нормально і корисно для локальної розробки, тестування патчів і hotfix. ## Межа експорту -OpenClaw експортує можливості, а не зручності реалізації. +OpenClaw експортує можливості, а не зручні реалізаційні шари. -Зберігайте публічною реєстрацію можливостей. Прибирайте не-контрактні експорти-хелпери: +Реєстрацію можливостей слід залишати публічною. Неекспортовані допоміжні зручності слід обрізати: -- підшляхи, специфічні для хелперів вбудованих плагінів -- підшляхи plumbing runtime, які не призначені як публічний API -- convenience-хелпери, специфічні для вендора -- setup/onboarding-хелпери, які є деталями реалізації +- допоміжні subpaths, специфічні для вбудованих plugins +- subpaths runtime plumbing, які не призначені бути публічним API +- vendor-специфічні convenience helpers +- helpers setup/onboarding, які є деталями реалізації -Деякі підшляхи-хелпери вбудованих плагінів усе ще залишаються в згенерованій карті -експортів SDK для сумісності та підтримки вбудованих плагінів. Поточні приклади: +Деякі допоміжні subpaths вбудованих plugins усе ще присутні в згенерованій карті +експорту SDK з міркувань сумісності та підтримки вбудованих plugins. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для -нових сторонніх плагінів. +зарезервовані implementation-detail exports, а не як рекомендований шаблон SDK для +нових сторонніх plugins. ## Конвеєр завантаження Під час запуску OpenClaw приблизно робить таке: -1. виявляє корені кандидатів на плагіни -2. читає нативні або сумісні маніфести пакетів і метадані package +1. виявляє корені потенційних plugin +2. читає нативні або сумісні маніфести bundle та метадані package 3. відхиляє небезпечних кандидатів -4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, +4. нормалізує config plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. вирішує, чи вмикати кожного кандидата -6. завантажує увімкнені нативні модулі через jiti -7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів -8. відкриває реєстр для команд/поверхонь runtime +5. вирішує стан увімкнення для кожного кандидата +6. завантажує увімкнені нативні modules через jiti +7. викликає нативні hooks `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру plugin +8. відкриває реєстр для surfaces commands/runtime -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, який із них присутній (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugins віддавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання runtime. Кандидатів блокують, -якщо entry виходить за межі кореня плагіна, шлях доступний для запису всім або -власник шляху виглядає підозріло для не вбудованих плагінів. +Перевірки безпеки виконуються **до** виконання runtime. Кандидати блокуються, +коли entry виходить за межі кореня plugin, шлях має права запису для всіх, або +власність шляху виглядає підозріло для невбудованих plugins. -### Поведінка з пріоритетом маніфесту +### Поведінка manifest-first Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: -- ідентифікувати плагін -- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- ідентифікувати plugin +- виявляти оголошені channels/skills/config schema або можливості bundle - перевіряти `plugins.entries..config` -- доповнювати мітки/placeholder-и Control UI -- показувати метадані встановлення/каталогу +- доповнювати labels/placeholders у Control UI +- показувати metadata install/catalog -Для нативних плагінів модуль runtime — це частина data plane. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдерів. +Для нативних plugins модуль runtime є частиною data plane. Він реєструє +фактичну поведінку, таку як hooks, tools, commands або provider flows. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі кеші в процесі для: +OpenClaw зберігає короткі in-process кеші для: - результатів виявлення - даних реєстру маніфестів -- реєстрів завантажених плагінів +- завантажених реєстрів plugin -Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно -розглядати як короткоживучі кеші продуктивності, а не як механізм постійного зберігання. +Ці кеші зменшують пікові витрати під час запуску та повторних викликів commands. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як persistence. Примітка щодо продуктивності: @@ -548,37 +540,36 @@ OpenClaw зберігає короткоживучі кеші в процесі ## Модель реєстру -Завантажені плагіни не змінюють довільні глобальні змінні core напряму. Вони -реєструються в центральному реєстрі плагінів. +Завантажені plugins не змінюють безпосередньо випадкові глобальні стани core. Вони +реєструються в центральному реєстрі plugin. Реєстр відстежує: -- записи плагінів (ідентичність, джерело, походження, статус, діагностика) -- інструменти -- застарілі та типізовані хуки -- канали -- провайдерів -- обробники gateway RPC -- HTTP-маршрути -- реєстратори CLI -- фонові сервіси -- команди, що належать плагінам +- записи plugin (ідентичність, джерело, походження, статус, діагностика) +- tools +- застарілі hooks і типізовані hooks +- channels +- providers +- handlers Gateway RPC +- HTTP routes +- CLI registrars +- background services +- commands, що належать plugin -Потім можливості core читають із цього реєстру замість того, щоб напряму -звертатися до модулів плагінів. Це зберігає одностороннє завантаження: +Потім функції core читають із цього реєстру, а не звертаються до модулів plugin +безпосередньо. Це зберігає односпрямованість завантаження: -- модуль плагіна -> реєстрація в реєстрі -- runtime core -> споживання реєстру +- модуль plugin -> реєстрація в реєстрі +- runtime core -> використання реєстру Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: «читати реєстр», а не «робити special-case для -кожного модуля плагіна». +потрібна лише одна точка інтеграції: "читати реєстр", а не "робити special-case для кожного модуля plugin". -## Callback-и прив’язування розмов +## Callbacks прив’язки conversation -Плагіни, які прив’язують розмову, можуть реагувати, коли затвердження вирішено. +Plugins, які прив’язують conversation, можуть реагувати, коли approval вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на прив’язування буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на bind буде схвалено або відхилено: ```ts export default { @@ -598,26 +589,26 @@ export default { }; ``` -Поля payload callback-а: +Поля payload callback: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: вирішене прив’язування для схвалених запитів -- `request`: підсумок оригінального запиту, підказка від’єднання, sender id і - метадані розмови +- `binding`: визначена прив’язка для схвалених запитів +- `request`: початкове резюме запиту, підказка detach, id відправника та + metadata conversation -Цей callback призначений лише для сповіщення. Він не змінює того, хто має право прив’язувати -розмову, і запускається після завершення обробки затвердження в core. +Цей callback лише сповіщує. Він не змінює того, кому дозволено прив’язувати +conversation, і запускається після завершення обробки approval у core. ## Runtime-хуки провайдера -Тепер плагіни провайдерів мають два шари: +Тепер provider plugins мають два шари: -- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до - завантаження runtime, а також `providerAuthChoices` для дешевих - міток onboarding/auth-choice і метаданих прапорців CLI до завантаження runtime -- хуки під час конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- runtime-хуки: `normalizeModelId`, `normalizeTransport`, +- metadata маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до + завантаження runtime, плюс `providerAuthChoices` для дешевих labels onboarding/auth-choice + і metadata CLI flags до завантаження runtime +- hooks часу config: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- runtime hooks: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -636,83 +627,81 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw усе ще володіє загальним циклом агента, failover, обробкою транскриптів і -політикою інструментів. Ці хуки є поверхнею розширення для provider-specific поведінки без -необхідності створювати повністю кастомний транспорт інференсу. +OpenClaw і далі володіє загальним agent loop, failover, обробкою transcript і +policy tools. Ці hooks — це surface розширення для provider-специфічної поведінки без +потреби в повністю custom inference transport. -Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime -плагіна. Використовуйте маніфест `providerAuthChoices`, коли поверхні -CLI onboarding/auth-choice мають знати про choice id провайдера, мітки груп і просте -підключення auth через один прапорець без завантаження runtime провайдера. Залишайте runtime -`envVars` провайдера для operator-facing підказок, таких як мітки onboarding або -змінні для налаштування OAuth client-id/client-secret. +Використовуйте manifest `providerAuthEnvVars`, коли provider має credentials на основі env, +які загальні шляхи auth/status/model-picker повинні бачити без завантаження runtime plugin. +Використовуйте manifest `providerAuthChoices`, коли surfaces CLI onboarding/auth-choice +мають знати id choice провайдера, labels груп і просту прив’язку auth одним flag без завантаження runtime provider. +Залишайте `envVars` runtime provider для operator-facing підказок, таких як labels onboarding або +OAuth client-id/client-secret setup vars. -### Порядок хуків і їх використання +### Порядок hooks і використання -Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це швидкий орієнтир для вибору. +Для model/provider plugins OpenClaw викликає hooks приблизно в такому порядку. +Стовпець "Коли використовувати" — це короткий орієнтир для вибору. -| # | Хук | Що він робить | Коли використовувати | -| --- | -------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями base URL | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації провайдера під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях registry/catalog | _(не є хуком плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед lookup | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує provider-family `api` / `baseUrl` перед загальним складанням моделі | Провайдер володіє очищенням транспорту для custom provider id у тій самій transport family | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед runtime/provider resolution | Провайдеру потрібне очищення конфігурації, яке має жити в плагіні; вбудовані хелпери Google-family також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до config providers | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від endpoint | -| 7 | `resolveConfigApiKey` | Визначає auth env-marker для config providers до завантаження runtime auth | Провайдер має provider-owned визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований визначник AWS env-marker | -| 8 | `resolveSyntheticAuth` | Показує local/self-hosted або auth на основі конфігурації без збереження plaintext | Провайдер може працювати із synthetic/local маркером облікових даних | -| 9 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених synthetic placeholder profile порівняно з auth на основі env/config | Провайдер зберігає synthetic placeholder profile, які не мають вигравати за пріоритетом | -| 10 | `resolveDynamicModel` | Синхронний резервний сценарій для provider-owned model id, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id | -| 11 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 12 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні транспортні переписування, але він усе ще використовує транспорт core | -| 13 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy transport без повного перебрання ролі провайдера | -| 14 | `capabilities` | Метадані transcript/tooling, що належать провайдеру, використовуються спільною логікою core | Провайдеру потрібні quirks transcript/provider-family | -| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для transport family | -| 16 | `inspectToolSchemas` | Показує provider-owned діагностику схем після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання core provider-specific правилам | -| 17 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native-полів | -| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками stream options | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | -| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | -| 20 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності headers/body/model без кастомного транспорту | -| 21 | `resolveTransportTurnState` | Додає native headers або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали provider-native turn identity | -| 22 | `resolveWebSocketSessionPolicy` | Додає native WebSocket headers або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували session headers або політику резервного сценарію | -| 23 | `formatApiKey` | Форматувач auth-profile: збережений profile стає runtime-рядком `apiKey` | Провайдер зберігає додаткові метадані auth і потребує кастомної форми runtime token | -| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для custom refresh endpoint або політики помилок refresh | Провайдер не підходить до спільних засобів оновлення `pi-ai` | -| 25 | `buildAuthDoctorHint` | Підказка з виправлення, яка додається, коли OAuth refresh не вдається | Провайдеру потрібні власні рекомендації з відновлення auth після невдалого refresh | -| 26 | `matchesContextOverflowError` | Matcher для переповнення context window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальна евристика може пропустити | -| 27 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі API/transport errors із rate-limit/overload тощо | -| 28 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul provider | Провайдеру потрібне proxy-specific обмеження cache TTL | -| 29 | `buildMissingAuthMessage` | Замінник загального повідомлення відновлення при відсутній auth | Провайдеру потрібна provider-specific підказка з відновлення auth | -| 30 | `suppressBuiltInModel` | Приховування застарілих upstream model з необов’язковою підказкою для користувача | Провайдеру потрібно приховувати застарілі upstream rows або замінювати їх підказкою вендора | -| 31 | `augmentModelCatalog` | Додає synthetic/final rows каталогу після виявлення | Провайдеру потрібні synthetic rows для forward-compat у `models list` і засобах вибору | -| 32 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для binary-thinking provider | Провайдер має лише binary thinking увімк./вимк. | -| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 34 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 35 | `isModernModelRef` | Matcher сучасних моделей для live profile filters і smoke selection | Провайдер володіє зіставленням preferred-model для live/smoke | -| 36 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime token/key безпосередньо перед інференсом | Провайдеру потрібен обмін token або короткоживучі облікові дані для запиту | -| 37 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь стану | Провайдеру потрібен кастомний розбір usage/quota token або інші облікові дані usage | -| 38 | `fetchUsageSnapshot` | Отримує та нормалізує provider-specific знімки usage/quota після визначення auth | Провайдеру потрібен provider-specific usage endpoint або парсер payload | -| 39 | `createEmbeddingProvider` | Будує provider-owned adapter embedding для memory/search | Поведінка memory embedding має належати плагіну провайдера | -| 40 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для провайдера | Провайдеру потрібна кастомна політика transcript (наприклад, видалення thinking-block) | -| 41 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні provider-specific переписування replay понад спільні хелпери compaction | -| 42 | `validateReplayTurns` | Фінальна перевірка або переформування replay-turn перед embedded runner | Транспорту провайдера потрібні суворіші перевірки ходу після загальної санітизації | -| 43 | `onModelSelected` | Виконує provider-owned побічні ефекти після вибору моделі | Провайдеру потрібна телеметрія або provider-owned стан, коли модель стає активною | +| # | Hook | Що він робить | Коли використовувати | +| --- | --------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує config provider у `models.providers` під час генерації `models.json` | Провайдер володіє catalog або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує global config defaults, що належать provider, під час materialization config | Типові значення залежать від режиму auth, env або семантики сімейства моделей provider | +| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях registry/catalog | _(це не hook plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview alias model-id до пошуку | Провайдер володіє очищенням alias до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства provider до загального складання моделі | Провайдер володіє очищенням transport для custom id provider у тому ж сімействі transport | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення runtime/provider | Провайдеру потрібне очищення config, яке має жити разом із plugin; вбудовані helpers Google-family також підтримують сумісні записи Google config | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи використання нативного streaming до config providers | Провайдеру потрібні endpoint-керовані виправлення metadata нативного streaming usage | +| 7 | `resolveConfigApiKey` | Визначає env-marker auth для config providers до завантаження runtime auth | Провайдер має власне визначення API key через env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver | +| 8 | `resolveSyntheticAuth` | Показує local/self-hosted або auth на основі config без збереження plaintext | Провайдер може працювати із synthetic/local marker credentials | +| 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic placeholder profiles порівняно з auth через env/config | Провайдер зберігає synthetic placeholder profiles, які не повинні мати вищий пріоритет | +| 10 | `resolveDynamicModel` | Синхронний fallback для model id, що належать provider, але ще відсутні в локальному registry | Провайдер приймає довільні upstream model id | +| 11 | `prepareDynamicModel` | Асинхронний прогрів, після якого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві metadata до визначення невідомих id | +| 12 | `normalizeResolvedModel` | Фінальний перезапис до того, як embedded runner використає визначену модель | Провайдеру потрібні перезаписи transport, але він усе ще використовує core transport | +| 13 | `contributeResolvedModelCompat` | Додає compat-flags для vendor-моделей за сумісним transport іншого типу | Провайдер розпізнає власні моделі на proxy transports без перехоплення всього provider | +| 14 | `capabilities` | Метадані transcript/tooling, що належать provider і використовуються спільною логікою core | Провайдеру потрібні особливості transcript/provider-family | +| 15 | `normalizeToolSchemas` | Нормалізує schema tools до того, як їх побачить embedded runner | Провайдеру потрібне очищення schema для сімейства transport | +| 16 | `inspectToolSchemas` | Показує provider-owned діагностику schema після нормалізації | Провайдер хоче попередження про keywords, не навчаючи core provider-специфічних правил | +| 17 | `resolveReasoningOutputMode` | Вибирає нативний або tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість нативних полів | +| 18 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних wrappers параметрів stream | Провайдеру потрібні типові параметри запиту або очищення параметрів per-provider | +| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream custom transport | Провайдеру потрібен custom wire protocol, а не просто wrapper | +| 20 | `wrapStreamFn` | Wrapper stream після застосування загальних wrappers | Провайдеру потрібні wrappers заголовків/тіла/compat моделі запиту без custom transport | +| 21 | `resolveTransportTurnState` | Додає нативні заголовки або metadata transport для конкретного turn | Провайдер хоче, щоб загальні transports передавали provider-native turn identity | +| 22 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або policy cool-down session | Провайдер хоче, щоб загальні WS transports налаштовували заголовки session або policy fallback | +| 23 | `formatApiKey` | Форматер auth-profile: збережений profile стає runtime-рядком `apiKey` | Провайдер зберігає додаткові metadata auth і потребує custom форми runtime token | +| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для custom endpoints refresh або policy помилок refresh | Провайдер не вписується у спільні refreshers `pi-ai` | +| 25 | `buildAuthDoctorHint` | Підказка для виправлення, що додається при помилці оновлення OAuth | Провайдеру потрібна власна підказка щодо відновлення auth після помилки refresh | +| 26 | `matchesContextOverflowError` | Matcher переповнення context window, що належить provider | Провайдер має сирі помилки overflow, які загальні heuristics пропустять | +| 27 | `classifyFailoverReason` | Класифікація причин failover, що належить provider | Провайдер може зіставити сирі API/transport errors із rate-limit/overload тощо | +| 28 | `isCacheTtlEligible` | Policy prompt-cache для proxy/backhaul providers | Провайдеру потрібне proxy-специфічне керування TTL кешу | +| 29 | `buildMissingAuthMessage` | Заміна загального recovery message для відсутньої auth | Провайдеру потрібна provider-специфічна підказка відновлення при відсутній auth | +| 30 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова user-facing підказка помилки | Провайдеру потрібно приховувати застарілі upstream rows або замінювати їх підказкою vendor | +| 31 | `augmentModelCatalog` | Додає synthetic/final rows catalog після виявлення | Провайдеру потрібні synthetic rows для forward-compat у `models list` і pickers | +| 32 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для binary-thinking providers | Провайдер відкриває лише бінарне thinking on/off | +| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | +| 34 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою policy `/think` для сімейства моделей | +| 35 | `isModernModelRef` | Matcher modern-model для live filters профілів і вибору smoke | Провайдер володіє зіставленням preferred моделей для live/smoke | +| 36 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key перед inference | Провайдеру потрібен обмін token або short-lived credentials для запиту | +| 37 | `resolveUsageAuth` | Визначає credentials usage/billing для `/usage` і пов’язаних surfaces status | Провайдеру потрібен custom парсинг token usage/quota або інші credentials usage | +| 38 | `fetchUsageSnapshot` | Отримує та нормалізує provider-специфічні snapshots usage/quota після визначення auth | Провайдеру потрібен provider-специфічний endpoint usage або parser payload | +| 39 | `createEmbeddingProvider` | Створює embedding adapter, що належить provider, для memory/search | Поведінка embedding memory має належати plugin provider | +| 40 | `buildReplayPolicy` | Повертає policy replay, яка керує обробкою transcript для provider | Провайдеру потрібна custom policy transcript (наприклад, видалення блоків thinking) | +| 41 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні provider-специфічні перезаписи replay понад спільні helpers compact | +| 42 | `validateReplayTurns` | Фінальна валідація або зміна форми turns replay до embedded runner | Transport провайдера потребує суворішої валідації turn після загальної санітизації | +| 43 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать provider | Провайдеру потрібна telemetry або provider-owned стан, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -matched provider plugin, а потім переходять до інших hook-capable provider plugins, +відповідний plugin provider, а потім переходять до інших provider plugins, здатних на hooks, доки один із них справді не змінить model id або transport/config. Це дозволяє -shim-плагінам alias/compat працювати без необхідності для виклику знати, який саме -вбудований плагін володіє переписуванням. Якщо жоден provider hook не переписує -підтримуваний запис конфігурації Google-family, вбудований нормалізатор конфігурації Google -усе одно застосує це compat-очищення. +shim providers для alias/compat працювати без потреби, щоб викликаюча сторона знала, який +вбудований plugin володіє цим перезаписом. Якщо жоден provider hook не переписує +підтримуваний запис Google-family config, все одно застосовується вбудований нормалізатор Google config. -Якщо провайдеру потрібен повністю кастомний wire protocol або власний виконавець запитів, -це інший клас розширення. Ці хуки призначені для поведінки провайдера, -яка все ще працює в межах звичайного циклу інференсу OpenClaw. +Якщо provider потрібен повністю custom wire protocol або custom виконавець запитів, +це вже інший клас extension. Ці hooks призначені для поведінки provider, яка +все ще працює на звичайному inference loop OpenClaw. -### Приклад провайдера +### Приклад provider ```ts api.registerProvider({ @@ -770,116 +759,113 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - і `wrapStreamFn`, тому що володіє forward-compat для Claude 4.6, - підказками provider-family, рекомендаціями з відновлення auth, інтеграцією - endpoint usage, допустимістю prompt-cache, значеннями конфігурації за замовчуванням, що залежать від auth, - політикою thinking за замовчуванням/адаптивного Claude та специфічним для Anthropic формуванням stream для + `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, + і `wrapStreamFn`, оскільки володіє forward-compat для Claude 4.6, + підказками сімейства provider, інструкціями відновлення auth, інтеграцією з endpoint usage, + відповідністю prompt-cache, типовими значеннями config з урахуванням auth, типовою/адаптивною policy thinking Claude, + а також Anthropic-специфічним формуванням stream для beta headers, `/fast` / `serviceTier` і `context1m`. -- Хелпери stream, специфічні для Claude від Anthropic, поки що залишаються у власному - публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета +- Claude-специфічні helpers stream Anthropic поки що залишаються у власному + публічному шві `api.ts` / `contract-api.ts` вбудованого plugin. Ця package surface експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі - конструктори обгорток Anthropic замість розширення загального SDK навколо правил - beta-header одного провайдера. + builders wrappers Anthropic замість розширення загального SDK навколо правил + beta-header одного provider. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і - `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities` плюс `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - тому що володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI + оскільки володіє GPT-5.4 forward-compat, прямою нормалізацією OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приховуванням Spark, synthetic rows списку OpenAI та політикою thinking / - live-model для GPT-5; сімейство stream `openai-responses-defaults` володіє - спільними native OpenAI Responses wrappers для attribution headers, - `/fast`/`serviceTier`, verbosity тексту, native Codex web search, - формуванням payload для сумісності reasoning і керуванням контекстом Responses. -- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, оскільки провайдер є pass-through і може відкривати нові - model id до оновлення статичного каталогу OpenClaw; він також використовує - `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб - provider-specific headers запитів, метадані маршрутизації, патчі reasoning і - політика prompt-cache не потрапляли в core. Його політика replay походить із - сімейства `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` - володіє proxy-ін’єкцією reasoning і пропусками для unsupported-model / `auto`. + приховуванням Spark, synthetic rows списку OpenAI і політикою thinking / live-model GPT-5; + сімейство stream `openai-responses-defaults` володіє + спільними нативними wrappers OpenAI Responses для + attribution headers, `/fast`/`serviceTier`, verbosity тексту, нативного web search Codex, + формуванням payload reasoning-compat і керуванням context у Responses. +- OpenRouter використовує `catalog` плюс `resolveDynamicModel` і + `prepareDynamicModel`, оскільки provider є pass-through і може відкривати нові + model id ще до оновлення статичного catalog OpenClaw; він також використовує + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати + provider-специфічні заголовки запитів, metadata маршрутизації, патчі reasoning і + policy prompt-cache поза core. Його policy replay походить із сімейства + `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` + володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому - потрібні provider-owned device login, поведінка резервних сценаріїв моделей, quirks - transcript для Claude, обмін токена GitHub на токен Copilot і provider-owned endpoint usage. + `capabilities` плюс `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому + потрібні device login, що належать provider, fallback-поведінка моделей, особливості transcript Claude, + обмін токена GitHub на токен Copilot і endpoint usage, що належить provider. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він - усе ще працює на core OpenAI transports, але володіє нормалізацією - transport/base URL, власною політикою fallback для оновлення OAuth, вибором - транспорту за замовчуванням, synthetic rows каталогу Codex та інтеграцією endpoint usage ChatGPT; він + `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog` плюс + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він + усе ще працює на core transports OpenAI, але володіє своєю нормалізацією + transport/base URL, policy fallback оновлення OAuth, типовим вибором transport, + synthetic rows catalog Codex і інтеграцією з endpoint usage ChatGPT; він використовує те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI. - Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що - сімейство replay `google-gemini` володіє резервним сценарієм forward-compat для Gemini 3.1, - native-перевіркою replay Gemini, санітизацією bootstrap replay, режимом - tagged reasoning-output і зіставленням сучасних моделей, тоді як - сімейство stream `google-thinking` володіє нормалізацією payload thinking для Gemini; + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки + сімейство replay `google-gemini` володіє fallback для forward-compat Gemini 3.1, + нативною валідацією replay Gemini, санітизацією replay під час bootstrap, режимом + tagged reasoning-output і зіставленням modern-model, тоді як + сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токенів, розбору токенів і + `fetchUsageSnapshot` для форматування токена, парсингу токена та підключення endpoint quota. - Anthropic Vertex використовує `buildReplayPolicy` через - сімейство replay `anthropic-by-model`, тож очищення replay, специфічне для Claude, залишається - прив’язаним до id Claude, а не до всього транспорту `anthropic-messages`. + сімейство replay `anthropic-by-model`, щоб Claude-специфічне очищення replay + залишалося прив’язаним до id Claude, а не до кожного transport `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє - класифікацією помилок throttle/not-ready/context-overflow, специфічних для Bedrock, - для трафіку Anthropic-on-Bedrock; його політика replay усе ще поділяє той самий - guard `anthropic-by-model`, прив’язаний лише до Claude. + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє + класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, + для трафіку Anthropic-on-Bedrock; його policy replay все ще використовує той самий + захист лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі - Gemini через OpenAI-compatible transports і потребують санітизації - thought-signature Gemini без native-перевірки replay Gemini або bootstrap-переписувань. + через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini + через transports, сумісні з OpenAI, і потребують санітизації + thought-signature Gemini без нативної валідації replay Gemini або bootstrap-перезаписів. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один провайдер володіє і - семантикою Anthropic-message, і OpenAI-compatible; він зберігає видалення - thinking-block, що стосується лише Claude, на стороні Anthropic, водночас - перевизначаючи режим reasoning output назад на native, а сімейство stream `minimax-fast-mode` - володіє переписуванням моделей fast-mode на спільному шляху stream. -- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він усе ще використовує - спільний транспорт OpenAI, але потребує provider-owned нормалізації payload thinking; сімейство - stream `moonshot-thinking` зіставляє конфігурацію плюс стан `/think` зі своїм - native binary thinking payload. + сімейство replay `hybrid-anthropic-openai`, оскільки один provider володіє і + семантикою Anthropic-message, і семантикою OpenAI-compatible; він + зберігає видалення blocks thinking лише для Claude з боку Anthropic, одночасно перевизначаючи + режим reasoning output назад на нативний, а сімейство stream `minimax-fast-mode` + володіє перезаписами моделі fast-mode на спільному шляху stream. +- Moonshot використовує `catalog` плюс `wrapStreamFn`, оскільки все ще використовує + спільний OpenAI transport, але потребує provider-owned нормалізації payload thinking; сімейство + stream `moonshot-thinking` відображає config плюс стан `/think` на + його нативний бінарний payload thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні provider-owned request headers, - нормалізація payload reasoning, підказки transcript Gemini і обмеження - cache-TTL для Anthropic; сімейство stream `kilocode-thinking` зберігає ін’єкцію - thinking Kilo на спільному proxy stream path, пропускаючи `kilo/auto` та - інші proxy model id, які не підтримують явний payload reasoning. + `isCacheTtlEligible`, оскільки потребує provider-owned заголовків запитів, + нормалізації payload reasoning, підказок transcript Gemini та керування + TTL кешу Anthropic; сімейство stream `kilocode-thinking` зберігає ін’єкцію Kilo thinking + на спільному proxy stream, пропускаючи `kilo/auto` та + інші proxy model id, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє резервним сценарієм GLM-5, - типовими значеннями `tool_stream`, UX binary thinking, зіставленням сучасних моделей - і визначенням auth usage та отриманням quota; сімейство stream `tool-stream-default-on` - не дає обгортці `tool_stream`, увімкненій за замовчуванням, потрапити до - рукописного glue-коду окремих провайдерів. + `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє fallback GLM-5, + типовими значеннями `tool_stream`, UX бінарного thinking, зіставленням modern-model, + а також auth для usage + отриманням quota; сімейство stream `tool-stream-default-on` + тримає wrapper `tool_stream`, увімкнений за замовчуванням, поза handwritten glue для кожного provider. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - тому що володіє нормалізацією native transport Responses для xAI, переписуванням - псевдонімів fast-mode для Grok, типовим `tool_stream`, очищенням - strict-tool / reasoning-payload, повторним використанням резервної auth для - інструментів, що належать плагіну, визначенням моделей Grok для forward-compat - і provider-owned compat-патчами, як-от профіль xAI для tool-schema, - непідтримувані ключові слова схеми, native `web_search` і декодування аргументів - виклику інструментів з HTML entities. + оскільки володіє нативною нормалізацією transport Responses xAI, перезаписами alias fast-mode Grok, + типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для tools, що належать plugin, forward-compat + визначенням моделей Grok і compat-патчами, що належать provider, такими як профіль schema tools xAI, + непідтримувані keywords schema, нативний `web_search` і декодування аргументів викликів tools з HTML entities. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - quirks transcript/tooling не потрапляли в core. -- Вбудовані провайдери лише з каталогом, як-от `byteplus`, `cloudflare-ai-gateway`, + тримати особливості transcript/tooling поза core. +- Вбудовані providers лише з catalog, такі як `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` і usage-хуки, оскільки їхня - поведінка `/usage` належить плагіну, хоча інференс усе ще працює через спільні транспорти. +- Qwen використовує `catalog` для свого текстового provider плюс спільні реєстрації + media-understanding і video-generation для своїх мультимодальних surfaces. +- MiniMax і Xiaomi використовують `catalog` плюс hooks usage, оскільки їхня поведінка `/usage` + належить plugin, хоча inference і далі виконується через спільні transports. -## Runtime-хелпери +## Runtime helpers -Плагіни можуть отримувати доступ до вибраних хелперів core через `api.runtime`. Для TTS: +Plugins можуть отримувати доступ до вибраних helpers core через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -900,14 +886,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload TTS core для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію core `messages.tts` і вибір провайдера. -- Повертає буфер аудіо PCM + sample rate. Плагіни мають самі виконувати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору. -- Списки голосів можуть містити багатші метадані, як-от locale, стать і теги personality для засобів вибору з урахуванням провайдера. -- Сьогодні OpenAI і ElevenLabs підтримують телефонію. Microsoft — ні. +- `textToSpeech` повертає звичайний payload виводу TTS core для surfaces файлів/voice-note. +- Використовує core-конфігурацію `messages.tts` і вибір provider. +- Повертає буфер аудіо PCM + sample rate. Plugins повинні виконувати ресемплінг/кодування для provider. +- `listVoices` є необов’язковим для кожного provider. Використовуйте його для voice pickers або setup flows, що належать vendor. +- Списки голосів можуть включати багатші metadata, такі як locale, стать і теги personality для provider-aware pickers. +- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні. -Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugins також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -927,15 +913,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, резервні сценарії та доставку відповідей у core. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. -- Застарілий ввід Microsoft `edge` нормалізується до provider id `microsoft`. -- Бажана модель володіння — орієнтована на компанію: один плагін вендора може володіти - текстом, мовленням, зображенням і майбутніми медіапровайдерами, коли OpenClaw додає ці - контракти можливостей. +- Залишайте policy TTS, fallback і доставку відповідей у core. +- Використовуйте speech providers для поведінки synthesis, що належить vendor. +- Застаріле значення вводу Microsoft `edge` нормалізується до id provider `microsoft`. +- Бажана модель володіння — орієнтована на компанію: один plugin vendor може володіти + text, speech, image і майбутніми media providers у міру того, як OpenClaw додає ці + capability-контракти. -Для розуміння зображень/аудіо/відео плагіни реєструють один типізований -provider media-understanding замість загального key/value-механізму: +Для розуміння зображень/аудіо/відео plugins реєструють один типізований +provider media-understanding замість загального key/value bag: ```ts api.registerMediaUnderstandingProvider({ @@ -949,16 +935,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, резервні сценарії, конфігурацію й підключення каналів у core. -- Зберігайте поведінку вендора в плагіні провайдера. -- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові - поля результату, нові необов’язкові можливості. +- Залишайте orchestration, fallback, config і підключення channels у core. +- Залишайте поведінку vendor у plugin provider. +- Розширення шляхом додавання повинно залишатися типізованим: нові необов’язкові methods, нові необов’язкові + поля result, нові необов’язкові capabilities. - Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та runtime-хелпером - - вендорні плагіни реєструють `api.registerVideoGenerationProvider(...)` - - функціональні/канальні плагіни споживають `api.runtime.videoGeneration.*` + - core володіє capability-контрактом і runtime helper + - plugins vendor реєструють `api.registerVideoGenerationProvider(...)` + - feature/channel plugins використовують `api.runtime.videoGeneration.*` -Для runtime-хелперів media-understanding плагіни можуть викликати: +Для runtime helpers media-understanding plugins можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -973,7 +959,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо плагіни можуть використовувати або runtime media-understanding, +Для транскрипції аудіо plugins можуть використовувати або runtime media-understanding, або старіший псевдонім STT: ```ts @@ -987,13 +973,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для +- `api.runtime.mediaUnderstanding.*` — це бажана спільна surface для розуміння зображень/аудіо/відео. -- Використовує конфігурацію audio для core media-understanding (`tools.media.audio`) і порядок резервних сценаріїв провайдерів. -- Повертає `{ text: undefined }`, якщо результат транскрипції не було створено (наприклад, для пропущеного/непідтримуваного вводу). +- Використовує core-конфігурацію аудіо media-understanding (`tools.media.audio`) і порядок fallback provider. +- Повертає `{ text: undefined }`, коли вихід транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу). - `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. -Плагіни також можуть запускати фонові запуски subagent через `api.runtime.subagent`: +Plugins також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1007,14 +993,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для конкретного запуску, а не постійні зміни сесії. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни session. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для резервних запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Недовірені запуски subagent для плагінів теж працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного сценарію. +- Для fallback-запусків, що належать plugin, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent для недовірених plugins усе ще працюють, але запити на перевизначення відхиляються, а не тихо повертаються до fallback. -Для веб-пошуку плагіни можуть використовувати спільний runtime-хелпер замість -звернення до wiring інструмента агента: +Для web search plugins можуть використовувати спільний runtime helper замість +прямого звернення до підключення tool агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1030,14 +1016,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати провайдерів веб-пошуку через +Plugins також можуть реєструвати providers web-search через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core. -- Використовуйте провайдерів веб-пошуку для transport, специфічного для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для функціональних/канальних плагінів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Залишайте вибір provider, визначення credentials і спільну семантику запитів у core. +- Використовуйте web-search providers для vendor-специфічних transports пошуку. +- `api.runtime.webSearch.*` — це бажана спільна surface для feature/channel plugins, яким потрібна поведінка пошуку без залежності від wrapper tool агента. ### `api.runtime.imageGeneration` @@ -1052,12 +1038,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення з використанням налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: показує доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок providers генерації зображень. +- `listProviders(...)`: перелічити доступних providers генерації зображень і їхні можливості. -## HTTP-маршрути Gateway +## HTTP routes Gateway -Плагіни можуть відкривати HTTP-endpoint через `api.registerHttpRoute(...)`. +Plugins можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1072,36 +1058,36 @@ api.registerHttpRoute({ }); ``` -Поля маршруту: +Поля route: -- `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове поле. Використовуйте `"gateway"` для звичайної автентифікації gateway або `"plugin"` для auth/перевірки webhook, що керується плагіном. -- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове поле. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. -- `handler`: повертайте `true`, якщо маршрут обробив запит. +- `path`: шлях route у межах HTTP server gateway. +- `auth`: обов’язкове. Використовуйте `"gateway"` для вимоги звичайної auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує plugin. +- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію route. +- `handler`: повертає `true`, коли route обробив запит. Примітки: -- `api.registerHttpHandler(...)` видалено, і воно спричинить помилку завантаження плагіна. Використовуйте `api.registerHttpRoute(...)`. -- Маршрути плагінів мають явно оголошувати `auth`. -- Конфлікти точних `path + match` відхиляються, якщо лише не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Зберігайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично scope runtime оператора. Вони призначені для webhook/signature verification, що керується плагіном, а не для привілейованих викликів хелперів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах request runtime scope Gateway, але цей scope навмисно консервативний: - - bearer auth на спільному секреті (`gateway.auth.mode = "token"` / `"password"`) фіксує runtime scope маршрутів плагіна на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з наявною ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей header явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів плагінів із наявною ідентичністю, runtime scope повертається до `operator.write` -- Практичне правило: не вважайте маршрут плагіна з gateway-auth неявною адмін-поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим auth із наявною ідентичністю та документуйте явний контракт header `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` видалено і спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Routes plugin повинні явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити route іншого plugin. +- Routes, що перекриваються, з різними рівнями `auth` відхиляються. Зберігайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. +- Routes `auth: "plugin"` **не** отримують автоматично operator runtime scopes. Вони призначені для webhook/signature verification, якими керує plugin, а не для привілейованих helper-викликів Gateway. +- Routes `auth: "gateway"` працюють усередині runtime scope запиту Gateway, але цей scope навмисно консервативний: + - bearer auth із shared-secret (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scopes route plugin прив’язаними до `operator.write`, навіть якщо викликаюча сторона надсилає `x-openclaw-scopes` + - довірені режими HTTP з ідентичністю (наприклад `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких identity-bearing запитах route plugin, runtime scope повертається до `operator.write` +- Практичне правило: не припускайте, що route plugin з auth gateway є неявною admin-surface. Якщо вашому route потрібна поведінка лише для admin, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час написання плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час створення plugins використовуйте subpaths SDK замість монолітного імпорту `openclaw/plugin-sdk`: -- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. -- `openclaw/plugin-sdk/core` для загального контракту плагінів. -- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` +- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації plugin. +- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на plugin. +- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod schema `openclaw.json` (`OpenClawSchema`). -- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, +- Стабільні channel-примітиви, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1113,17 +1099,17 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного wiring - setup/auth/reply/webhook. `channel-inbound` — це спільний дім для - debounce, зіставлення згадок, форматування envelope і хелперів контексту inbound envelope. - `channel-setup` — це вузький шов setup для optional-install. - `setup-runtime` — це безпечна для runtime поверхня setup, яка використовується `setupEntry` / + `openclaw/plugin-sdk/webhook-ingress` для спільного підключення + setup/auth/reply/webhook. `channel-inbound` — це спільне місце для + debounce, mention matching, форматування envelope і helpers контексту inbound envelope. + `channel-setup` — вузький шов setup для необов’язкового install. + `setup-runtime` — runtime-safe surface setup, яка використовується `setupEntry` / відкладеним запуском, включно з import-safe адаптерами патчів setup. - `setup-adapter-runtime` — це env-aware шов adapter setup облікових записів. - `setup-tools` — це невеликий шов хелперів CLI/archive/docs (`formatCliCommand`, + `setup-adapter-runtime` — це env-aware шов adapter setup облікового запису. + `setup-tools` — це малий шов CLI/archive/docs helper (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Предметні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, +- Domain subpaths, такі як `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1138,191 +1124,187 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних runtime/config-хелперів. - `telegram-command-config` — це вузький публічний шов для нормалізації/валідації - кастомних команд Telegram і він залишається доступним, навіть якщо поверхня контракту - вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний шов text/markdown/logging, зокрема - видалення тексту, видимого асистенту, хелпери render/chunking markdown, хелпери - редагування, хелпери directive-tag і safe-text utilities. -- Для approval-specific каналів слід віддавати перевагу єдиному контракту `approvalCapability` - на плагіні. Потім core читає approval auth, delivery, render і - native-routing-поведінку через цю одну можливість, а не змішує - approval-поведінку в незв’язані поля плагіна. -- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як - compatibility shim для старих плагінів. Новий код має імпортувати натомість вужчі - загальні примітиви, а код репозиторію не має додавати нові імпорти цього shim. -- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Core/тести OpenClaw можуть використовувати - публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` і вузькоспеціалізовані файли на кшталт - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з - іншого розширення. -- Поділ точок входу репозиторію: - `/api.js` — barrel для хелперів/типів, - `/runtime-api.js` — barrel лише для runtime, - `/index.js` — точка входу вбудованого плагіна, - а `/setup-entry.js` — точка входу setup-плагіна. -- Поточні приклади вбудованих провайдерів: - - Anthropic використовує `api.js` / `contract-api.js` для хелперів stream Claude, таких - як `wrapAnthropicProviderStream`, хелпери beta-header і розбір `service_tier`. - - OpenAI використовує `api.js` для конструкторів провайдера, хелперів моделей за замовчуванням і - конструкторів realtime provider. - - OpenRouter використовує `api.js` для свого конструктора провайдера та onboarding/config - хелперів, тоді як `register.runtime.js` усе ще може повторно експортувати загальні - хелпери `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні точки входу, завантажувані через фасад, віддають перевагу активному snapshot конфігурації runtime, - якщо він існує, а інакше повертаються до визначеного файлу конфігурації на диску, коли - OpenClaw ще не обслуговує snapshot runtime. + `openclaw/plugin-sdk/directory-runtime` для спільних helpers runtime/config. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації custom-команд Telegram і він залишається доступним, навіть якщо вбудована contract-surface Telegram тимчасово недоступна. + `text-runtime` — це спільний шов text/markdown/logging, включно з + видаленням assistant-visible-text, helpers render/chunking markdown, helpers редагування, + helpers directive-tag і utilities безпечного тексту. +- Для approval-специфічних швів channel слід віддавати перевагу одному контракту + `approvalCapability` на plugin. Потім core читає auth approval, доставку, render і + native-routing behavior через цю одну capability замість змішування + поведінки approval з не пов’язаними полями plugin. +- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як + compatibility shim для старіших plugins. Новий код повинен імпортувати вужчі + загальні примітиви, а код repo не повинен додавати нові імпорти цього shim. +- Внутрішні компоненти вбудованих extension залишаються приватними. Зовнішні plugins повинні використовувати лише subpaths `openclaw/plugin-sdk/*`. Core/test код OpenClaw може використовувати + публічні точки входу repo під коренем package plugin, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js`, а також вузькі файли, наприклад + `login-qr-api.js`. Ніколи не імпортуйте `src/*` package plugin з core або з + іншого extension. +- Поділ точок входу repo: + `/api.js` — це barrel helpers/types, + `/runtime-api.js` — це barrel лише для runtime, + `/index.js` — це entry вбудованого plugin, + а `/setup-entry.js` — це entry plugin setup. +- Поточні приклади вбудованих providers: + - Anthropic використовує `api.js` / `contract-api.js` для helpers stream Claude, таких + як `wrapAnthropicProviderStream`, helpers beta-header і парсинг `service_tier`. + - OpenAI використовує `api.js` для builders provider, helpers типової моделі та + builders provider realtime. + - OpenRouter використовує `api.js` для свого builder provider плюс helpers + onboarding/config, тоді як `register.runtime.js` усе ще може реекспортувати загальні + helpers `plugin-sdk/provider-stream` для локального використання в repo. +- Публічні точки входу, завантажені через facade, надають перевагу активному snapshot config runtime, + якщо він існує, а потім повертаються до визначеного config-файлу на диску, + коли OpenClaw ще не надає runtime snapshot. - Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований compatibility-набір branded-хелперів для вбудованих каналів усе ще існує. Розглядайте їх як - шви для підтримки вбудованих компонентів/сумісності, а не нові цілі імпорту для - сторонніх плагінів; нові міжканальні контракти й надалі мають з’являтися на - загальних підшляхах `plugin-sdk/*` або в локальних barrel `api.js` / - `runtime-api.js` плагіна. + зарезервований набір branded helper-швів вбудованих channels усе ще існує. Розглядайте їх як + шви підтримки/сумісності вбудованих компонентів, а не нові цілі імпорту для сторонніх рішень; нові міжканальні контракти, як і раніше, мають з’являтися в + загальних subpaths `plugin-sdk/*` або в локальних barrels `api.js` / + `runtime-api.js` plugin. Примітка щодо сумісності: - Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. -- Насамперед віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи +- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші subpaths setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool є бажаним контрактом для нової роботи з - вбудованими та зовнішніми плагінами. - Розбір/зіставлення цілей належить до `openclaw/plugin-sdk/channel-targets`. - Обмеження для message action і хелпери message-id реакцій належать до + allowlist/status/message-tool — це бажаний контракт для нової роботи + із вбудованими та зовнішніми plugins. + Парсинг/зіставлення targets належить до `openclaw/plugin-sdk/channel-targets`. + Gating дій повідомлень і helpers message-id реакцій належать до `openclaw/plugin-sdk/channel-actions`. -- Barrel-хелпери, специфічні для вбудованих розширень, не є стабільними за замовчуванням. Якщо - хелпер потрібен лише вбудованому розширенню, залишайте його за локальним швом - `api.js` або `runtime-api.js` цього розширення замість перенесення до +- Допоміжні barrels, специфічні для вбудованих extension, не є стабільними за замовчуванням. Якщо + helper потрібен лише вбудованому extension, залишайте його за локальним швом `api.js` або `runtime-api.js` цього extension замість просування до `openclaw/plugin-sdk/`. -- Нові спільні шви хелперів мають бути загальними, а не branded під конкретний канал. Спільний розбір - цілей належить до `openclaw/plugin-sdk/channel-targets`; channel-specific - внутрішні механізми залишаються за локальним швом `api.js` або `runtime-api.js` - плагіна-власника. -- Підшляхи, специфічні для можливостей, такі як `image-generation`, - `media-understanding` і `speech`, існують, оскільки вбудовані/нативні плагіни використовують - їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований хелпер є - довгостроковим незмінним зовнішнім контрактом. +- Нові спільні helper-шви мають бути загальними, а не branded за channel. Спільний парсинг + targets належить до `openclaw/plugin-sdk/channel-targets`; channel-специфічні + внутрішні компоненти залишаються за локальним швом `api.js` або `runtime-api.js` plugin-власника. +- Capability-специфічні subpaths, такі як `image-generation`, + `media-understanding` і `speech`, існують, тому що вбудовані/нативні plugins використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є + довгостроковим зафіксованим зовнішнім контрактом. -## Схеми інструмента повідомлень +## Schema tools повідомлень -Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу. -Зберігайте provider-specific поля в плагіні, а не в спільному core. +Plugins повинні володіти channel-специфічними внесками до schema в `describeMessageTool(...)`. +Зберігайте provider-специфічні поля в plugin, а не в спільному core. -Для спільних переносних фрагментів схеми повторно використовуйте загальні хелпери, експортовані через +Для спільних portable fragments schema використовуйте загальні helpers, що експортуються через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованого payload карток +- `createMessageToolButtonsSchema()` для payload у стилі grid кнопок +- `createMessageToolCardSchema()` для структурованих payload карток -Якщо форма схеми має сенс лише для одного провайдера, визначайте її у -власному коді цього плагіна, а не просувайте в спільний SDK. +Якщо форма schema має сенс лише для одного provider, визначайте її у +власному джерелі цього plugin замість просування до спільного SDK. -## Визначення цілей каналу +## Визначення channel target -Канальні плагіни мають володіти channel-specific семантикою цілей. Зберігайте -спільний outbound host загальним і використовуйте поверхню messaging adapter для правил провайдера: +Channel plugins повинні володіти channel-специфічною семантикою target. Зберігайте спільний +outbound host загальним і використовуйте surface messaging adapter для правил provider: -- `messaging.inferTargetChatType({ to })` визначає, чи слід розглядати нормалізовану ціль - як `direct`, `group` чи `channel` до пошуку в каталозі. +- `messaging.inferTargetChatType({ to })` вирішує, чи слід нормалізований target + трактувати як `direct`, `group` або `channel` до lookup у directory. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - потрібно одразу переходити до визначення за id-подібним значенням замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний механізм плагіна, коли - core потрібне фінальне provider-owned визначення після нормалізації або - після промаху каталогу. -- `messaging.resolveOutboundSessionRoute(...)` володіє provider-specific побудовою - маршруту сесії після визначення цілі. + слід пропустити одразу до визначення за id-подібним значенням, а не виконувати пошук у directory. +- `messaging.targetResolver.resolveTarget(...)` — це fallback plugin, коли + core потребує фінального provider-owned визначення після нормалізації або + після невдалого пошуку в directory. +- `messaging.resolveOutboundSessionRoute(...)` володіє provider-специфічною побудовою + route session після того, як target визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають відбуватися до +- Використовуйте `inferTargetChatType` для категорійних рішень, які повинні відбуватися до пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок «сприймати це як явний/native target id». -- Використовуйте `resolveTarget` для provider-specific резервного визначення після нормалізації, а не для - широкого пошуку в каталозі. -- Зберігайте provider-native id, як-от chat id, thread id, JID, handle та room id, - усередині значень `target` або provider-specific параметрів, а не в загальних полях SDK. +- Використовуйте `looksLikeId` для перевірок "сприймати це як явний/нативний id target". +- Використовуйте `resolveTarget` для provider-специфічного fallback нормалізації, а не для + широкого пошуку в directory. +- Зберігайте provider-native ids, як-от ids chat, ids thread, JIDs, handles і ids room, + у значеннях `target` або provider-специфічних params, а не в загальних полях SDK. -## Каталоги, що ґрунтуються на конфігурації +## Directories на основі config -Плагіни, які виводять записи каталогу з конфігурації, мають зберігати цю логіку в -плагіні та повторно використовувати спільні хелпери з +Plugins, які формують entries directory з config, повинні тримати цю логіку в +plugin і повторно використовувати спільні helpers із `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: +Використовуйте це, коли channel потребує peers/groups на основі config, таких як: -- peers для DM, керовані allowlist -- налаштовані мапи каналів/груп -- статичні резервні варіанти каталогу, прив’язані до облікового запису +- DM peers на основі allowlist +- налаштовані карти channels/groups +- статичні fallback-и directory з урахуванням scope облікового запису -Спільні хелпери в `directory-runtime` обробляють лише загальні операції: +Спільні helpers у `directory-runtime` обробляють лише загальні операції: -- фільтрацію запиту -- застосування ліміту -- хелпери dedupe/normalization +- фільтрацію query +- застосування limit +- helpers dedupe/normalization - побудову `ChannelDirectoryEntry[]` -Специфічні для каналу перевірка облікового запису та нормалізація id мають залишатися в -реалізації плагіна. +Channel-специфічна перевірка облікового запису та нормалізація id повинні залишатися в реалізації plugin. -## Каталоги провайдерів +## Catalogs provider -Плагіни провайдерів можуть визначати каталоги моделей для інференсу за допомогою +Provider plugins можуть визначати catalogs моделей для inference через `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в +`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує до `models.providers`: -- `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдера +- `{ provider }` для одного запису provider +- `{ providers }` для кількох записів provider -Використовуйте `catalog`, коли плагін володіє provider-specific model id, значеннями -base URL за замовчуванням або метаданими моделей, що залежать від auth. +Використовуйте `catalog`, коли plugin володіє provider-специфічними model ids, типовими +значеннями base URL або metadata моделей, які залежать від auth. -`catalog.order` визначає, коли каталог плагіна зливається відносно вбудованих неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли catalog plugin зливається відносно вбудованих +неявних providers OpenClaw: -- `simple`: провайдери зі звичайним API-ключем або керовані env -- `profile`: провайдери, що з’являються, коли існують профілі auth -- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів -- `late`: останній прохід, після інших неявних провайдерів +- `simple`: прості providers на основі API key або env +- `profile`: providers, які з’являються, коли існують auth profiles +- `paired`: providers, які синтезують кілька пов’язаних записів provider +- `late`: останній прохід після інших неявних providers -Пізніші провайдери перемагають у конфліктах ключів, тож плагіни можуть навмисно -перевизначати вбудований запис провайдера з тим самим provider id. +Пізніші providers перемагають у разі конфлікту key, тож plugins можуть навмисно +перевизначати вбудований запис provider з тим самим id provider. Сумісність: - `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Режим лише для читання для перевірки каналів +## Канальний огляд лише для читання -Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш plugin реєструє channel, віддавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. -- Команди лише для читання, як-от `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config - repair, не повинні потребувати матеріалізації runtime-облікових даних лише для опису конфігурації. +- `resolveAccount(...)` — це runtime-шлях. Він може припускати, що credentials + повністю materialized, і швидко помилятися, якщо обов’язкових secrets бракує. +- Шляхи commands лише для читання, такі як `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config + repair, не повинні потребувати materialization runtime credentials лише для + опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/стану облікових даних, якщо це доречно, зокрема: +- Включає поля джерела/стану credentials, коли це доречно, такі як: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для звітування про доступність лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). -- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле source) для commands у стилі status. +- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але він недоступний у поточному шляху command. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. +Це дозволяє commands лише для читання повідомляти "налаштовано, але недоступно в цьому шляху command" замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. -## Пакети-паки +## Package packs -Каталог плагіна може містити `package.json` з `openclaw.extensions`: +Directory plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -1334,64 +1316,61 @@ base URL за замовчуванням або метаданими модел } ``` -Кожен запис стає плагіном. Якщо пак містить кілька розширень, plugin id +Кожен entry стає plugin. Якщо pack перелічує кілька extension, id plugin стає `name/`. -Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб -було доступне `node_modules` (`npm install` / `pnpm install`). +Якщо ваш plugin імпортує залежності npm, установіть їх у цій directory, щоб +`node_modules` був доступний (`npm install` / `pnpm install`). -Захист безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна -після визначення symlink. Записи, що виходять за межі каталогу пакета, -відхиляються. +Захисне правило безпеки: кожен entry `openclaw.extensions` повинен залишатися в межах directory plugin +після визначення symlink. Entries, які виходять за межі directory package, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies під час runtime). Зберігайте дерева залежностей плагінів «pure JS/TS» і уникайте пакетів, яким потрібні збирання через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies у runtime). Зберігайте дерева залежностей plugin як "pure JS/TS" і уникайте package, які потребують збірок через `postinstall`. Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потрібні поверхні setup для вимкненого канального плагіна або -коли канальний плагін увімкнено, але ще не налаштовано, він завантажує `setupEntry` -замість повної точки входу плагіна. Це робить запуск і setup легшими, -коли основна точка входу плагіна також підключає інструменти, хуки або інший runtime-only -код. +Коли OpenClaw потребує surfaces setup для вимкненого channel plugin або +коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повного entry plugin. Це робить запуск і setup легшими, +коли ваш основний entry plugin також підключає tools, hooks чи інший код лише для runtime. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести канальний плагін на той самий шлях `setupEntry` під час фази -запуску gateway до початку прослуховування, навіть якщо канал уже налаштований. +може перевести channel plugin на той самий шлях `setupEntry` під час фази +запуску gateway до listen, навіть якщо channel уже налаштовано. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне слухати. На практиці це означає, що setup entry -має реєструвати кожну channel-owned можливість, від якої залежить запуск, наприклад: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup-surface, яка має існувати +до того, як gateway почне слухати. На практиці це означає, що entry setup +повинен реєструвати всі можливості channel-власника, від яких залежить запуск, такі як: -- саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати -- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому самому вікні +- сама реєстрація channel +- будь-які HTTP routes, які мають бути доступні до того, як gateway почне слухати +- будь-які methods, tools або services gateway, які мають існувати в тому ж вікні часу -Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не -вмикайте цей прапорець. Залишайте поведінку плагіна типовою й дозвольте OpenClaw завантажити -повну точку входу під час запуску. +Якщо ваш повний entry усе ще володіє будь-якою обов’язковою startup-можливістю, не вмикайте +цей flag. Залишайте plugin на типовій поведінці й дозвольте OpenClaw завантажити +повний entry під час запуску. -Вбудовані канали також можуть публікувати хелпери поверхні контракту лише для setup, які core -може консультувати до завантаження повного runtime каналу. Поточна поверхня просування setup така: +Вбудовані channels також можуть публікувати helpers contract-surface лише для setup, до яких core +може звертатися до завантаження повного runtime channel. Поточна surface setup promotion така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію -каналу з одним обліковим записом у `channels..accounts.*` без завантаження повної точки входу плагіна. -Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap у -іменований підвищений обліковий запис, коли іменовані облікові записи вже існують, і може -зберегти налаштований non-canonical ключ default-account замість того, щоб завжди створювати +Core використовує цю surface, коли йому потрібно підвищити застарілу +конфігурацію single-account channel до `channels..accounts.*` без завантаження +повного entry plugin. Matrix — поточний вбудований приклад: він переносить лише +keys auth/bootstrap до іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і +може зберігати налаштований неканонічний key default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів setup зберігають лінивим виявлення поверхні контракту вбудованих компонентів. Час -імпорту залишається малим; поверхня просування завантажується лише за першого використання, а не -повторно входить у запуск вбудованого каналу під час імпорту модуля. +Ці adapters патчів setup зберігають lazy-виявлення contract-surface вбудованих компонентів. Час import +залишається малим; surface promotion завантажується лише під час першого використання замість повторного входу у startup вбудованого channel при import module. -Коли ці поверхні запуску містять методи gateway RPC, тримайте їх під -префіксом, специфічним для плагіна. Простори імен адмін-команд core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо плагін запитує вужчий scope. +Коли ці startup surfaces включають methods Gateway RPC, зберігайте їх під +plugin-специфічним prefix. Простори імен admin core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються +як `operator.admin`, навіть якщо plugin запитує вужчий scope. Приклад: @@ -1408,10 +1387,10 @@ Core використовує цю поверхню, коли йому потр } ``` -### Метадані каталогу каналів +### Metadata catalog channel -Канальні плагіни можуть оголошувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє не зберігати дані каталогу в core. +Channel plugins можуть оголошувати metadata setup/discovery через `openclaw.channel` і +підказки install через `openclaw.install`. Це дозволяє залишати data-free у core catalog. Приклад: @@ -1439,38 +1418,38 @@ Core використовує цю поверхню, коли йому потр } ``` -Корисні поля `openclaw.channel` понад мінімальний приклад: +Корисні поля `openclaw.channel` поза мінімальним прикладом: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану -- `docsLabel`: перевизначає текст посилання на документацію -- `preferOver`: plugin/channel id з нижчим пріоритетом, які цей запис каталогу має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом на поверхні вибору -- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування outbound -- `showConfigured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддавати перевагу пошуку сесії під час визначення announce targets +- `detailLabel`: вторинний label для багатших surfaces catalog/status +- `docsLabel`: перевизначення тексту посилання на docs +- `preferOver`: ids plugin/channel нижчого пріоритету, які цей запис catalog має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування copy для surfaces selection +- `markdownCapable`: позначає channel як сумісний із markdown для рішень щодо outbound formatting +- `showConfigured`: приховує channel із surfaces списку налаштованих channels, якщо встановлено `false` +- `quickstartAllowFrom`: включає channel до стандартного потоку quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: віддає перевагу lookup session під час визначення announce targets -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в одне з таких місць: +OpenClaw також може зливати **зовнішні catalogs channels** (наприклад, експорт реєстру 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": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. +один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл повинен +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для key `"entries"`. -## Плагіни рушія контексту +## Plugins context engine -Плагіни рушія контексту володіють оркестрацією контексту сесії для ingest, assembly -і compaction. Реєструйте їх у своєму плагіні через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через +Plugins context engine володіють orchestration контексту session для ingest, assembly +і compaction. Реєструйте їх зі свого plugin через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний engine через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий конвеєр -контексту, а не просто додати memory search чи хуки. +Використовуйте це, коли вашому plugin потрібно замінити або розширити типову +конвеєрну обробку context, а не просто додати memory search або hooks. ```ts export default function (api) { @@ -1489,7 +1468,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом compaction, залишайте `compact()` +Якщо ваш engine **не** володіє алгоритмом compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1517,46 +1496,46 @@ export default function (api) { ## Додавання нової можливості -Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний reach-in. Додайте відсутню можливість. +Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте +систему plugin приватним прямим зверненням. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політикою, резервними сценаріями, злиттям конфігурації, - життєвим циклом, канал-орієнтованою семантикою та формою runtime-хелперів. -2. додайте типізовані поверхні реєстрації/runtime для плагінів +1. визначити контракт core + Вирішіть, якою спільною поведінкою має володіти core: policy, fallback, злиття config, + lifecycle, channel-facing semantics і форма runtime helper. +2. додати типізовані surfaces реєстрації/runtime plugin Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною - типізованою поверхнею можливості. -3. під’єднайте споживачів у core та каналах/функціях - Канали й функціональні плагіни мають споживати нову можливість через core, а - не імпортувати напряму реалізацію вендора. -4. зареєструйте реалізації вендорів - Потім вендорні плагіни реєструють свої бекенди для цієї можливості. -5. додайте покриття контрактів - Додайте тести, щоб володіння й форма реєстрації з часом залишалися явними. + типізованою surface можливості. +3. підключити core + споживачів channels/features + Channels і feature plugins повинні використовувати нову можливість через core, + а не напряму імпортувати реалізацію vendor. +4. зареєструвати реалізації vendor + Потім plugins vendor реєструють свої backend для цієї можливості. +5. додати покриття контракту + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається принциповим, не стаючи жорстко прив’язаним до -світогляду одного провайдера. Див. [Capability Cookbook](/tools/capability-cookbook) -для конкретного переліку файлів і готового прикладу. +Саме так OpenClaw залишається виразним, не стаючи жорстко прив’язаним до +світогляду одного provider. Див. [Capability Cookbook](/uk/plugins/architecture) +для конкретного контрольного списку файлів і пропрацьованого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися цих -поверхонь: +Коли ви додаєте нову можливість, реалізація зазвичай повинна одночасно торкатися +таких surfaces: - типи контрактів core у `src//types.ts` -- runner/runtime-хелпер core у `src//runtime.ts` -- поверхня реєстрації API плагінів у `src/plugins/types.ts` -- wiring реєстру плагінів у `src/plugins/registry.ts` -- відкриття runtime плагінів у `src/plugins/runtime/*`, коли функціональним/канальним - плагінам потрібно це споживати -- хелпери захоплення/тестування в `src/test-utils/plugin-registration.ts` +- runner/runtime helper core у `src//runtime.ts` +- surface реєстрації API plugin у `src/plugins/types.ts` +- підключення реєстру plugin у `src/plugins/registry.ts` +- відкриття runtime plugin у `src/plugins/runtime/*`, коли feature/channel + plugins мають її використовувати +- helpers capture/test у `src/test-utils/plugin-registration.ts` - перевірки володіння/контрактів у `src/plugins/contracts/registry.ts` -- документація для операторів/плагінів у `docs/` +- docs для операторів/plugin у `docs/` -Якщо якоїсь із цих поверхонь бракує, це зазвичай знак того, що можливість ще не -повністю інтегрована. +Якщо якоїсь із цих surfaces бракує, це зазвичай означає, що можливість +ще не повністю інтегрована. ### Шаблон можливості @@ -1592,9 +1571,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає правило простим: +Це зберігає просте правило: -- core володіє контрактом можливості + оркестрацією -- вендорні плагіни володіють реалізаціями вендора -- функціональні/канальні плагіни споживають runtime-хелпери +- core володіє capability-контрактом + orchestration +- plugins vendor володіють vendor-реалізаціями +- feature/channel plugins використовують runtime helpers - тести контрактів зберігають явність володіння diff --git a/docs/uk/plugins/sdk-channel-plugins.md b/docs/uk/plugins/sdk-channel-plugins.md index 1ff77138a..ff2dd5f6d 100644 --- a/docs/uk/plugins/sdk-channel-plugins.md +++ b/docs/uk/plugins/sdk-channel-plugins.md @@ -1,90 +1,96 @@ --- read_when: - - Ви створюєте новий plugin каналу повідомлень + - Ви створюєте новий плагін каналу обміну повідомленнями - Ви хочете підключити OpenClaw до платформи обміну повідомленнями - Вам потрібно зрозуміти поверхню адаптера ChannelPlugin sidebarTitle: Channel Plugins -summary: Покроковий посібник зі створення plugin каналу повідомлень для OpenClaw -title: Створення plugin каналів +summary: Покроковий посібник зі створення плагіна каналу обміну повідомленнями для OpenClaw +title: Створення плагінів каналів x-i18n: - generated_at: "2026-04-05T18:12:37Z" + generated_at: "2026-04-05T18:49:07Z" model: gpt-5.4 provider: openai - source_hash: 68a6ad2c75549db8ce54f7e22ca9850d7ed68c5cd651c9bb41c9f73769f48aba + source_hash: 66b52c10945a8243d803af3bf7e1ea0051869ee92eda2af5718d9bb24fbb8552 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Створення plugin каналів +# Створення плагінів каналів -Цей посібник покроково пояснює створення plugin каналу, який підключає OpenClaw до -платформи обміну повідомленнями. Наприкінці ви матимете робочий канал із безпекою DM, -pairing, гілками відповідей і вихідними повідомленнями. +Цей посібник описує створення плагіна каналу, який підключає OpenClaw до +платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із +захистом DM, паруванням, потоковістю відповідей і вихідними повідомленнями. - Якщо ви ще не створювали жодного plugin для OpenClaw, спочатку прочитайте - [Getting Started](/plugins/building-plugins) про базову структуру пакета + Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте + [Getting Started](/uk/plugins/building-plugins) про базову структуру пакета та налаштування маніфесту. -## Як працюють plugin каналів +## Як працюють плагіни каналів -Plugin каналів не потребують власних інструментів send/edit/react. OpenClaw зберігає один -спільний інструмент `message` у core. Ваш plugin відповідає за: +Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw +зберігає один спільний інструмент `message` у core. Вашому плагіну належать: -- **Config** — визначення облікового запису та майстер налаштування -- **Security** — політику DM і allowlist -- **Pairing** — потік підтвердження DM -- **Граматику сесій** — те, як специфічні для провайдера ідентифікатори розмов зіставляються з базовими чатами, ідентифікаторами гілок і резервними батьківськими значеннями -- **Outbound** — надсилання тексту, медіа та опитувань на платформу -- **Threading** — як упорядковуються відповіді в гілках +- **Конфігурація** — визначення облікового запису та майстер налаштування +- **Безпека** — політика DM та allowlist-и +- **Парування** — процес підтвердження DM +- **Граматика сесій** — як conversation id, специфічні для провайдера, зіставляються з базовими чатами, id потоків і резервними батьківськими значеннями +- **Вихідні повідомлення** — надсилання тексту, медіа та опитувань на платформу +- **Потоковість** — як упорядковуються відповіді -Core відповідає за спільний інструмент message, підключення prompt, зовнішню форму ключа сесії, -загальний облік `:thread:` і диспетчеризацію. +Core належить спільний інструмент message, зв’язування prompt-ів, зовнішня +форма ключа сесії, загальний облік `:thread:` та диспетчеризація. -Якщо ваша платформа зберігає додаткову область в ідентифікаторах розмов, залиште цей розбір -у plugin через `messaging.resolveSessionConversation(...)`. Це -канонічний hook для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим -ідентифікатором гілки, явним `baseConversationId` і будь-якими +Якщо ваша платформа зберігає додаткову область в межах conversation id, +залишайте цей розбір у плагіні через +`messaging.resolveSessionConversation(...)`. Це канонічний хук для +зіставлення `rawId` з базовим conversation id, необов’язковим id потоку, +явним `baseConversationId` і будь-якими `parentConversationCandidates`. -Коли ви повертаєте `parentConversationCandidates`, зберігайте їх порядок -від найвужчого батьківського елемента до найширшої/базової розмови. +Коли ви повертаєте `parentConversationCandidates`, зберігайте їх порядок від +найвужчого батьківського значення до найширшої/базової розмови. -Bundled plugin, яким потрібен той самий розбір до запуску реєстру каналів, -також можуть надавати файл верхнього рівня `session-key-api.ts` із відповідним -експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню -лише тоді, коли реєстр runtime plugin ще недоступний. +Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів, +також можуть експортувати файл верхнього рівня `session-key-api.ts` із +відповідним експортом `resolveSessionConversation(...)`. Core використовує цю +безпечну для bootstrap поверхню лише тоді, коли реєстр runtime-плагінів ще +недоступний. -`messaging.resolveParentConversationCandidates(...)` і далі доступний як -застарілий сумісний резервний механізм, коли plugin потрібні лише -резервні батьківські значення поверх загального/raw id. Якщо існують обидва hooks, core використовує -спочатку `resolveSessionConversation(...).parentConversationCandidates` і лише потім -повертається до `resolveParentConversationCandidates(...)`, якщо канонічний hook +`messaging.resolveParentConversationCandidates(...)` залишається доступним як +застарілий резервний механізм сумісності, коли плагіну потрібні лише резервні +батьківські значення поверх загального/сирого id. Якщо існують обидва хуки, +core спочатку використовує +`resolveSessionConversation(...).parentConversationCandidates` і повертається +до `resolveParentConversationCandidates(...)` лише тоді, коли канонічний хук їх не надає. -## Підтвердження та можливості каналів +## Погодження та можливості каналів -Більшості plugin каналів не потрібен код, специфічний для підтверджень. +Більшості плагінів каналів не потрібен код, специфічний для погоджень. -- Core відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну резервну доставку. -- Надавайте перевагу одному об’єкту `approvalCapability` у plugin каналу, коли каналу потрібна специфічна для підтверджень поведінка. -- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов авторизації підтверджень. -- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дублікатів локальних prompt підтвердження або надсилання індикаторів набору тексту перед доставкою. -- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації підтверджень або придушення резервного механізму. -- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтверджень замість спільного renderer. -- Якщо канал може виводити стабільні DM-ідентичності, подібні до власника, з наявного config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання специфічної для підтверджень логіки в core. -- Якщо каналу потрібна нативна доставка підтверджень, зосередьте код каналу на нормалізації цілей і транспортних hooks. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core відповідав за фільтрацію запитів, маршрутизацію, дедуплікацію, термін дії та підписку gateway. -- Канали з нативними підтвердженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці helper. `accountId` забезпечує прив’язку політики підтверджень для кількох облікових записів до правильного bot account, а `approvalKind` зберігає доступність поведінки exec і plugin для каналу без жорстко закодованих гілок у core. -- Зберігайте тип delivered approval id від початку до кінця. Нативні клієнти не повинні - вгадувати або переписувати маршрутизацію exec чи plugin підтверджень на основі локального стану каналу. -- Різні види підтверджень можуть навмисно відкривати різні нативні поверхні. - Поточні bundled приклади: - - Slack зберігає доступність нативної маршрутизації підтверджень і для exec, і для plugin id. - - Matrix зберігає нативну DM/канальну маршрутизацію лише для exec-підтверджень і залишає - plugin-підтвердження на спільному шляху `/approve` у тому самому чаті. -- `createApproverRestrictedNativeApprovalAdapter` і далі існує як сумісна обгортка, але новий код має віддавати перевагу builder можливостей і надавати `approvalCapability` у plugin. +- Core керує `/approve` у тому самому чаті, спільними payload-ами кнопок погодження та загальною резервною доставкою. +- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, коли каналу потрібна поведінка, специфічна для погоджень. +- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шар авторизації погоджень. +- Якщо ваш канал надає нативні погодження exec, реалізуйте `approvalCapability.getActionAvailabilityState` навіть якщо нативний транспорт повністю живе в `approvalCapability.native`. Core використовує цей хук доступності, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціюючий канал нативні погодження, і включати канал до підказок резервного сценарію для нативного клієнта. +- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload-ів, специфічної для каналу, наприклад приховування дубльованих локальних prompt-ів погодження або надсилання індикаторів набору тексту перед доставкою. +- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації погоджень або придушення резервного сценарію. +- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload-и погодження замість спільного рендерера. +- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь у гілці disabled пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних погоджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають рендерити шляхи, прив’язані до облікового запису, наприклад `channels..accounts..execApprovals.*`, замість значень верхнього рівня за замовчуванням. +- Якщо канал може вивести стабільні DM-ідентичності, подібні до власника, із наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки погоджень, специфічної для core. +- Якщо каналу потрібна нативна доставка погоджень, тримайте код каналу зосередженим на нормалізації цілі та транспортних хуках. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core керував фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії та підпискою gateway. +- Канали з нативними погодженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці хелпери. `accountId` зберігає політику погоджень для кількох облікових записів у межах правильного облікового запису бота, а `approvalKind` зберігає поведінку погоджень exec і плагінів доступною для каналу без жорстко закодованих гілок у core. +- Зберігайте тип id доставленого погодження від початку до кінця. Нативні клієнти не повинні + вгадувати або переписувати маршрутизацію погоджень exec чи плагінів на основі локального стану каналу. +- Різні типи погоджень можуть навмисно відкривати різні нативні поверхні. + Поточні приклади вбудованих плагінів: + - Slack зберігає доступність нативної маршрутизації погоджень як для id exec, так і для id плагінів. + - Matrix зберігає нативну маршрутизацію DM/каналів лише для погоджень exec і залишає + погодження плагінів на спільному шляху `/approve` у тому самому чаті. +- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має віддавати перевагу побудовнику можливостей і надавати `approvalCapability` у плагіні. -Для гарячих точок входу каналів надавайте перевагу вужчим runtime subpath, коли вам потрібна лише одна частина цієї сім’ї: +Для гарячих entrypoint-ів каналів віддавайте перевагу вужчим runtime-підшляхам, +коли вам потрібна лише одна частина цієї групи: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -92,70 +98,74 @@ Bundled plugin, яким потрібен той самий розбір до з - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` -Так само надавайте перевагу `openclaw/plugin-sdk/setup-runtime`, +Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` і -`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша umbrella-поверхня. +`openclaw/plugin-sdk/reply-chunking`, якщо вам не потрібна ширша +узагальнювальна поверхня. -Окремо для setup: +Зокрема для setup: -- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper для setup: - безпечні для import адаптери patched setup (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime хелпери setup: + безпечні для import адаптери патчів setup (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), вивід приміток lookup, - `promptResolvedAllowFrom`, `splitSetupEntries` і delegated - builder setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware adapter - seam для `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` охоплює builder optional-install setup - плюс кілька безпечних для setup примітивів: + `createSetupInputPresenceValidator`), вивід приміток пошуку, + `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані + побудовники proxy для setup +- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шар + адаптера для `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` охоплює побудовники setup для + необов’язкового встановлення, а також кілька безпечних для setup примітивів: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і `splitSetupEntries` -- використовуйте ширший seam `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні - важчі спільні helper для setup/config, такі як +- використовуйте ширший шар `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні + важчі спільні хелпери setup/config, наприклад `moveSingleAccountChannelSectionToDefaultAccount(...)` -Якщо ваш канал хоче лише рекламувати "спочатку встановіть цей plugin" у поверхнях setup, -надавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані -adapter/wizard закриваються безпечно для записів config і фіналізації, а також повторно використовують -одне й те саме повідомлення про обов’язкове встановлення у валідації, finalize і тексті з посиланням на docs. +Якщо ваш канал хоче лише повідомляти "спочатку встановіть цей плагін" на +поверхнях setup, віддавайте перевагу `createOptionalChannelSetupSurface(...)`. +Згенеровані adapter/wizard працюють у режимі fail closed для записів у конфігурацію +та фіналізації й повторно використовують те саме повідомлення про необхідність +встановлення у валідації, finalize та тексті з посиланням на документацію. -Для інших гарячих шляхів каналів надавайте перевагу вузьким helper замість ширших застарілих -поверхонь: +Для інших гарячих шляхів каналу віддавайте перевагу вузьким хелперам замість +ширших застарілих поверхонь: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` і - `openclaw/plugin-sdk/account-helpers` для config із кількома обліковими записами та - резервного механізму account за замовчуванням + `openclaw/plugin-sdk/account-helpers` для конфігурації кількох + облікових записів і резервного повернення до облікового запису за + замовчуванням - `openclaw/plugin-sdk/inbound-envelope` і - `openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта вхідних повідомлень та - підключення запису і диспетчеризації + `openclaw/plugin-sdk/inbound-reply-dispatch` для маршрутизації/конвертів + вхідних повідомлень і зв’язування record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей - `openclaw/plugin-sdk/outbound-media` і - `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс delegate - вихідної ідентичності/надсилання -- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок гілок - і реєстрації adapter + `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа та + делегатів ідентичності/надсилання вихідних повідомлень +- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу + прив’язок потоків і реєстрації адаптерів - `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібна - застаріла схема полів payload агента/медіа -- `openclaw/plugin-sdk/telegram-command-config` для нормалізації власних команд Telegram, - валідації дублікатів/конфліктів і стабільного щодо резервного механізму контракту config команд + застаріла структура полів payload-ів agent/media +- `openclaw/plugin-sdk/telegram-command-config` для нормалізації + користувацьких команд Telegram, валідації дублікатів/конфліктів і + стабільного як резервний варіант контракту конфігурації команд -Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core обробляє підтвердження, а plugin просто надає можливості outbound/auth. Канали з нативними підтвердженнями, як-от Matrix, Slack, Telegram і custom chat transport, повинні використовувати спільні нативні helper замість власної реалізації життєвого циклу підтверджень. +Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core керує погодженнями, а плагін лише надає можливості outbound/auth. Канали з нативними погодженнями, такі як Matrix, Slack, Telegram і власні транспортні рішення для чатів, мають використовувати спільні нативні хелпери замість створення власного життєвого циклу погоджень. -## Покроковий розбір +## Покрокове проходження - Створіть стандартні файли plugin. Поле `channel` у `package.json` - робить цей plugin канальним plugin. Повний опис поверхні метаданих пакета - див. у [Plugin Setup and Config](/plugins/sdk-setup#openclawchannel): + Створіть стандартні файли плагіна. Поле `channel` у `package.json` + визначає, що це плагін каналу. Повну поверхню метаданих пакета див. у + [Plugin Setup and Config](/uk/plugins/sdk-setup#openclawchannel): ```json package.json @@ -204,9 +214,9 @@ adapter/wizard закриваються безпечно для записів c - - Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь adapter. Почніть із - мінімуму — `id` і `setup` — і додавайте adapter за потреби. + + Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть + з мінімуму — `id` і `setup` — і додавайте адаптери за потреби. Створіть `src/channel.ts`: @@ -216,7 +226,7 @@ adapter/wizard закриваються безпечно для записів c createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // ваш клієнт API платформи + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -257,7 +267,7 @@ adapter/wizard закриваються безпечно для записів c }, }), - // Безпека DM: хто може писати боту + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -267,7 +277,7 @@ adapter/wizard закриваються безпечно для записів c }, }, - // Pairing: потік підтвердження для нових контактів у DM + // Pairing: approval flow for new DM contacts pairing: { text: { idLabel: "Acme Chat username", @@ -278,10 +288,10 @@ adapter/wizard закриваються безпечно для записів c }, }, - // Threading: як доставляються відповіді + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // Outbound: надсилання повідомлень на платформу + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -302,23 +312,23 @@ adapter/wizard закриваються безпечно для записів c ``` - Замість ручної реалізації низькорівневих інтерфейсів adapter ви передаєте - декларативні параметри, а builder компонує їх: + Замість ручної реалізації низькорівневих інтерфейсів адаптерів, ви + передаєте декларативні параметри, а побудовник компонує їх: - | Параметр | Що він підключає | + | Option | Що він підключає | | --- | --- | - | `security.dm` | Scoped-резолвер безпеки DM з полів config | - | `pairing.text` | Потік pairing у DM на основі тексту з обміном кодами | - | `threading` | Резолвер режиму reply-to (фіксований, scoped за account або custom) | - | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ідентифікатори повідомлень) | + | `security.dm` | Scoped-резолвер безпеки DM із полів конфігурації | + | `pairing.text` | Текстовий процес парування DM з обміном кодом | + | `threading` | Резолвер режиму reply-to (фіксований, прив’язаний до облікового запису або користувацький) | + | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ID повідомлень) | - Ви також можете передавати сирі об’єкти adapter замість декларативних параметрів, + Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів, якщо вам потрібен повний контроль. - + Створіть `index.ts`: ```typescript index.ts @@ -354,22 +364,22 @@ adapter/wizard закриваються безпечно для записів c }); ``` - Розміщуйте CLI descriptors, якими володіє канал, у `registerCliMetadata(...)`, щоб OpenClaw + Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw міг показувати їх у кореневій довідці без активації повного runtime каналу, - а звичайні повні завантаження все одно підхоплювали ті самі descriptors для реєстрації реальних команд. - Залишайте `registerFull(...)` для роботи лише під час runtime. - Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте - prefix, специфічний для plugin. Простори імен адміністрування core (`config.*`, + тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації + реальних команд. Залишайте `registerFull(...)` для роботи, потрібної лише в runtime. + Якщо `registerFull(...)` реєструє gateway RPC-методи, використовуйте + префікс, специфічний для плагіна. Простори імен адмін-інтерфейсу core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди зіставляються з `operator.admin`. - `defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Див. - [Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) для всіх - параметрів. + `defineChannelPluginEntry` автоматично обробляє цей поділ режимів реєстрації. У + [Entry Points](/uk/plugins/sdk-entrypoints#definechannelpluginentry) див. усі + параметри. - Створіть `setup-entry.ts` для легкого завантаження під час onboarding: + Створіть `setup-entry.ts` для легкого завантаження під час онбордингу: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -378,28 +388,28 @@ adapter/wizard закриваються безпечно для записів c export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw завантажує цей файл замість повної точки входу, коли канал вимкнено - або не налаштовано. Це дозволяє уникнути підтягування важкого runtime-коду під час потоків setup. - Подробиці див. у [Setup and Config](/plugins/sdk-setup#setup-entry). + OpenClaw завантажує це замість повного entry, коли канал вимкнений + або не налаштований. Це дає змогу не підтягувати важкий runtime-код під час процесів setup. + Докладніше див. у [Setup and Config](/uk/plugins/sdk-setup#setup-entry). - Ваш plugin має отримувати повідомлення з платформи та пересилати їх до - OpenClaw. Типовий шаблон — webhook, який перевіряє запит і - диспетчеризує його через inbound handler вашого каналу: + Ваш плагін має отримувати повідомлення з платформи та переспрямовувати їх до + OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і + диспетчеризує його через обробник вхідних повідомлень вашого каналу: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // auth під керуванням plugin (перевіряйте підписи самостійно) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Ваш inbound handler диспетчеризує повідомлення до OpenClaw. - // Точне підключення залежить від SDK вашої платформи — - // див. реальний приклад у пакеті bundled plugin Microsoft Teams або Google Chat. + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -411,16 +421,16 @@ adapter/wizard закриваються безпечно для записів c ``` - Обробка вхідних повідомлень є специфічною для каналу. Кожен plugin каналу - володіє власним inbound-конвеєром. Подивіться на bundled plugin каналів - (наприклад пакет plugin Microsoft Teams або Google Chat), щоб побачити реальні шаблони. + Обробка вхідних повідомлень є специфічною для каналу. Кожен плагін каналу + володіє власним конвеєром вхідних повідомлень. Перегляньте вбудовані плагіни каналів + (наприклад пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони. -Пишіть colocated-тести у `src/channel.test.ts`: +Пишіть колоковані тести у `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -458,7 +468,7 @@ adapter/wizard закриваються безпечно для записів c pnpm test -- /acme-chat/ ``` - Спільні helper для тестування див. у [Testing](/plugins/sdk-testing). + Спільні хелпери для тестування див. у [Testing](/uk/plugins/sdk-testing). @@ -467,8 +477,8 @@ adapter/wizard закриваються безпечно для записів c ``` /acme-chat/ -├── package.json # Метадані openclaw.channel -├── openclaw.plugin.json # Маніфест зі схемою config +├── package.json # metadata openclaw.channel +├── openclaw.plugin.json # Маніфест зі схемою конфігурації ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Публічні експорти (необов’язково) @@ -476,37 +486,37 @@ adapter/wizard закриваються безпечно для записів c └── src/ ├── channel.ts # ChannelPlugin через createChatChannelPlugin ├── channel.test.ts # Тести - ├── client.ts # Клієнт API платформи - └── runtime.ts # Сховище runtime (за потреби) + ├── client.ts # API-клієнт платформи + └── runtime.ts # Runtime-сховище (за потреби) ``` ## Розширені теми - - Фіксовані reply-режими, scoped за account або custom + + Фіксовані, прив’язані до облікового запису або користувацькі режими reply - + describeMessageTool і виявлення дій - + inferTargetChatType, looksLikeId, resolveTarget - - TTS, STT, медіа, subagent через api.runtime + + TTS, STT, media, subagent через api.runtime -Деякі bundled helper seams і далі існують для підтримки bundled plugin і -сумісності. Це не рекомендований шаблон для нових plugin каналів; -надавайте перевагу загальним channel/setup/reply/runtime subpath зі спільної поверхні SDK, -якщо тільки ви безпосередньо не підтримуєте цю сім’ю bundled plugin. +Деякі вбудовані допоміжні шари все ще існують для супроводу вбудованих плагінів +та сумісності. Це не рекомендований шаблон для нових плагінів каналів; +віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної +поверхні SDK, якщо тільки ви не супроводжуєте безпосередньо цю сім’ю вбудованих плагінів. ## Наступні кроки -- [Provider Plugins](/plugins/sdk-provider-plugins) — якщо ваш plugin також надає моделі -- [SDK Overview](/plugins/sdk-overview) — повний довідник import subpath -- [SDK Testing](/plugins/sdk-testing) — утиліти тестування та контрактні тести -- [Plugin Manifest](/plugins/manifest) — повна схема маніфесту +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі +- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпортів підшляхів +- [SDK Testing](/uk/plugins/sdk-testing) — тестові утиліти та контрактні тести +- [Plugin Manifest](/uk/plugins/manifest) — повна схема маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 1099296ed..e3de4f269 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -4,27 +4,27 @@ read_when: - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-05T18:13:38Z" + generated_at: "2026-04-05T18:49:41Z" model: gpt-5.4 provider: openai - source_hash: fb25f3f96ca1f522780f5a52eaedb85a8adf3cfb2934df625db3fe8b5f7e0666 + source_hash: d70ea8cc1343b2dc1b4243b0562d19bebb1fdf7eb5065220b17e87cfd8aecc3e source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка є -довідником для **що імпортувати** і **що ви можете реєструвати**. +Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є +довідником про **що імпортувати** і **що можна реєструвати**. - **Шукаєте практичний посібник?** - - Перший плагін? Почніть із [Початок роботи](/plugins/building-plugins) - - Плагін каналу? Див. [Плагіни каналів](/plugins/sdk-channel-plugins) - - Плагін провайдера? Див. [Плагіни провайдерів](/plugins/sdk-provider-plugins) + **Шукаєте покроковий посібник?** + - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) + - Plugin каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Plugin постачальника? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins) ## Угода щодо імпорту @@ -36,39 +36,41 @@ 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` залишайте для -ширшої umbrella-поверхні та спільних допоміжних функцій, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий +запуск і запобігає проблемам із циклічними залежностями. Для специфічних для +каналів допоміжних засобів entry/build віддавайте перевагу +`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +ширшої узагальненої поверхні та спільних помічників, таких як `buildChannelConfigSchema`. -Не додавайте і не покладайтеся на зручні шви з іменами провайдерів, такі як -`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +Не додавайте й не використовуйте зручні шви, названі на честь постачальників, +такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шви з брендуванням каналу. Пакети вбудованих плагінів мають компонувати загальні -підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core -має або використовувати ці локальні barrel-файли плагіна, або додавати вузький загальний контракт SDK, коли потреба справді є міжканальною. +допоміжні шви з брендуванням каналів. Вбудовані plugins мають компонувати +узагальнені підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, +а ядро має або використовувати ці локальні barrel-файли plugin, або додавати +вузький узагальнений контракт SDK, коли потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір -допоміжних швів для вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Згенерована карта експортів усе ще містить невеликий набір допоміжних швів +вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для супроводу вбудованих плагінів і сумісності; їх -навмисно пропущено в загальній таблиці нижче, і вони не є рекомендованим -шляхом імпорту для нових сторонніх плагінів. +підшляхи існують лише для підтримки та сумісності вбудованих plugins; вони +навмисно не включені до загальної таблиці нижче і не є рекомендованим шляхом +імпорту для нових сторонніх plugins. ## Довідник підшляхів -Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із -понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. +Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список +із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи для вбудованих плагінів усе ще з’являються в цьому згенерованому списку. -Розглядайте їх як поверхні деталей реалізації/сумісності, якщо тільки сторінка документації -явно не просуває один із них як публічний. +Зарезервовані допоміжні підшляхи вбудованих plugins усе ще з’являються в цьому +згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності, +якщо лише сторінка документації явно не просуває одну з них як публічну. -### Entry плагіна +### Entry plugin -| Підшлях | Ключові експорти | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Підшлях | Ключові експорти | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | @@ -81,259 +83,257 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `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` | Спільні помічники майстра налаштування, підказки списку дозволених, побудовники статусу налаштування | | `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` | Допоміжні функції конфігурації/контролю дій для кількох облікових записів, допоміжні функції резервного переходу до типового облікового запису | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису + резервного переходу до типового | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції списку облікових записів/дій з обліковим записом | + | `plugin-sdk/account-core` | Помічники для конфігурації/обмеження дій для кількох облікових записів, помічники резервного переходу на типовий обліковий запис | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, помічники нормалізації id облікового запису | + | `plugin-sdk/account-resolution` | Помічники пошуку облікового запису + резервного переходу до типового | + | `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 із резервним переходом до контракту вбудованого пакета | + | `plugin-sdk/telegram-command-config` | Помічники нормалізації/валідації користувацьких команд Telegram із резервною підтримкою вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршруту вхідних даних + побудовника envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису та диспетчеризації вхідних даних | - | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні функції делегування вихідної ідентичності/надсилання | - | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків та допоміжні функції адаптера | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіапейлоада агента | - | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмови/потоку, парування та налаштованої прив’язки | - | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні функції розв’язання політики груп runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні функції знімка/підсумку стану каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні експорти прелюдії плагіна каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо доступу до груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні функції auth/guard для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/скорочення інтерактивного пейлоада відповіді | - | `plugin-sdk/channel-inbound` | Допоміжні функції debounce, зіставлення згадок, envelope | + | `plugin-sdk/inbound-envelope` | Спільні помічники для маршрутизації вхідних повідомлень + побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні помічники запису й диспетчеризації вхідних повідомлень | + | `plugin-sdk/messaging-targets` | Помічники розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні помічники завантаження вихідних медіа | + | `plugin-sdk/outbound-runtime` | Помічники вихідної ідентичності/делегування надсилання | + | `plugin-sdk/thread-bindings-runtime` | Помічники життєвого циклу та адаптерів прив’язок потоків | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа-пейлоаду агента | + | `plugin-sdk/conversation-runtime` | Помічники прив’язки розмови/потоку, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Помічник знімка конфігурації часу виконання | + | `plugin-sdk/runtime-group-policy` | Помічники визначення group-policy під час виконання | + | `plugin-sdk/channel-status` | Спільні помічники знімка/зведення статусу каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу | + | `plugin-sdk/channel-config-writes` | Помічники авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні прелюд-експорти plugin каналу | + | `plugin-sdk/allowlist-config-edit` | Помічники редагування/читання конфігурації списку дозволених | + | `plugin-sdk/group-access` | Спільні помічники рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні помічники auth/guard для прямих DM | + | `plugin-sdk/interactive-runtime` | Помічники нормалізації/скорочення пейлоаду інтерактивних відповідей | + | `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, помічники envelope | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/channel-targets` | Помічники розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контракту каналу | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `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-sdk/provider-auth-api-key` | Допоміжні функції онбордингу/запису профілю API-ключа | + | `plugin-sdk/provider-setup` | Добірні помічники налаштування локальних/self-hosted постачальників | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані помічники налаштування self-hosted постачальника, сумісного з OpenAI | + | `plugin-sdk/provider-auth-runtime` | Помічники визначення API-ключа під час виконання для plugins постачальників | + | `plugin-sdk/provider-auth-api-key` | Помічники онбордингу/запису профілю для API-ключів | | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для плагінів провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку env var для auth провайдера | + | `plugin-sdk/provider-auth-login` | Спільні помічники інтерактивного входу для plugins постачальників | + | `plugin-sdk/provider-env-vars` | Помічники пошуку env vars auth постачальника | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політики повторення, допоміжні функції endpoint провайдера та допоміжні функції нормалізації 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/можливостей 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`, типи обгорток потоків і спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні функції патчів конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні функції локальних для процесу singleton/map/cache | + | `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`, типи обгорток потоку та спільні помічники обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Помічники виправлення конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Помічники локальних для процесу singleton/map/cache | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, допоміжні функції авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання approver і auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра схвалення native exec | - | `plugin-sdk/approval-delivery-runtime` | Адаптери доставки/можливостей native approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні функції native approval target + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції пейлоада відповіді схвалення exec/plugin | - | `plugin-sdk/command-auth-native` | Допоміжні функції native command auth + native session-target | - | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні функції нормалізації тіла команди та поверхні команд | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, помічники реєстру команд, помічники авторизації відправника | + | `plugin-sdk/approval-auth-runtime` | Помічники визначення approver і auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Помічники профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery | + | `plugin-sdk/approval-native-runtime` | Помічники native approval target + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Помічники пейлоаду відповіді exec/plugin approval | + | `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, зовнішнього вмісту та збору секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF та політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні функції розбору секретного вводу | - | `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла запиту/таймауту | + | `plugin-sdk/security-runtime` | Спільні помічники довіри, DM gating, external-content і збору секретів | + | `plugin-sdk/ssrf-policy` | Помічники allowlist хостів і політики SSRF для приватної мережі | + | `plugin-sdk/ssrf-runtime` | Помічники pinned-dispatcher, fetch із захистом SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Помічники розбору введення секретів | + | `plugin-sdk/webhook-ingress` | Помічники запитів/цілей webhook | + | `plugin-sdk/webhook-request-guards` | Помічники розміру тіла запиту/timeout | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні функції runtime/logging/backup/install плагінів | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env, logger, timeout, retry і backoff для runtime | + | `plugin-sdk/runtime` | Широка поверхня помічників runtime/logging/backup/install plugin | + | `plugin-sdk/runtime-env` | Вузькі помічники env runtime, logger, timeout, retry і backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції команди/hook/http/interactive плагіна | - | `plugin-sdk/hook-runtime` | Спільні допоміжні функції конвеєра webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні функції виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування та версії | - | `plugin-sdk/gateway-runtime` | Клієнт Gateway і допоміжні функції патчів стану каналу | - | `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram і перевірки дублювання/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні функції схвалення exec/plugin, побудовники можливостей approval, auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для вхідних даних/відповідей, chunking, dispatch, heartbeat, planner відповіді | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize відповіді | - | `plugin-sdk/reply-history` | Спільні допоміжні функції коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні помічники команд/hook/http/interactive plugin | + | `plugin-sdk/hook-runtime` | Спільні помічники pipeline webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Помічники лінивого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Помічники виконання процесів | + | `plugin-sdk/cli-runtime` | Помічники форматування CLI, очікування та версії | + | `plugin-sdk/gateway-runtime` | Помічники клієнта gateway і виправлення статусу каналу | + | `plugin-sdk/config-runtime` | Помічники завантаження/запису конфігурації | + | `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Помічники exec/plugin approval, побудовники approval-capability, помічники auth/profile, native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні помічники runtime для вхідних повідомлень/відповідей, chunking, dispatch, heartbeat, planner відповіді | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі помічники dispatch/finalize відповіді | + | `plugin-sdk/reply-history` | Спільні помічники reply-history для коротких вікон, такі як `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/routing` | Допоміжні функції маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні функції підсумку стану каналу/облікового запису, типові стани runtime і допоміжні функції метаданих issue | - | `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` | Загальні рідери параметрів інструментів/CLI | - | `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів для тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні функції logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму таблиць Markdown | - | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного file lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні функції дискового кешу дедуплікації | - | `plugin-sdk/acp-runtime` | Допоміжні функції runtime/сесії ACP і reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Рідер нечіткого boolean-параметра | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні функції початкового налаштування пристрою та токенів парування | - | `plugin-sdk/extension-shared` | Спільні примітиви passive-channel і статусу | - | `plugin-sdk/models-provider-runtime` | Допоміжні функції відповіді провайдера/команди `/models` | - | `plugin-sdk/skill-commands-runtime` | Допоміжні функції списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize native-команд | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Допоміжні функції системних подій/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні функції класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і pinned lookup helpers | - | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації повторів і запуску повторів | - | `plugin-sdk/agent-runtime` | Допоміжні функції каталогу/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/reply-chunking` | Вузькі помічники chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Помічники шляху сховища сесії + updated-at | + | `plugin-sdk/state-paths` | Помічники шляхів до директорій state/OAuth | + | `plugin-sdk/routing` | Помічники маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні помічники зведення статусу каналу/облікового запису, типові значення runtime-state і помічники метаданих проблем | + | `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` | Витягуйте канонічні поля цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні помічники шляхів для тимчасових завантажень | + | `plugin-sdk/logging-core` | Помічники logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Помічники режиму таблиць Markdown | + | `plugin-sdk/json-store` | Невеликі помічники читання/запису стану JSON | + | `plugin-sdk/file-lock` | Помічники повторно вхідного file-lock | + | `plugin-sdk/persistent-dedupe` | Помічники дискового кешу дедуплікації | + | `plugin-sdk/acp-runtime` | Помічники runtime/session ACP і dispatch відповіді | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента | + | `plugin-sdk/boolean-param` | Читач параметрів для нестрогих булевих значень | + | `plugin-sdk/dangerous-name-runtime` | Помічники визначення збігів небезпечних імен | + | `plugin-sdk/device-bootstrap` | Помічники bootstrap пристрою і токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel і статусних помічників | + | `plugin-sdk/models-provider-runtime` | Помічники `/models` command/provider reply | + | `plugin-sdk/skill-commands-runtime` | Помічники переліку команд Skills | + | `plugin-sdk/native-command-registry` | Помічники реєстру/build/serialize native command | + | `plugin-sdk/provider-zai-endpoint` | Помічники визначення endpoint Z.A.I | + | `plugin-sdk/infra-runtime` | Помічники системних подій/heartbeat | + | `plugin-sdk/collection-runtime` | Невеликі помічники обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Помічники діагностичних прапорців і подій | + | `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` | Запит/дедуплікація директорій на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store для медіа, а також побудовники медіапейлоадів | - | `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також експорти допоміжних функцій зображень/аудіо для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/logging, такі як вилучення видимого асистенту тексту, render/chunking/table helpers для markdown, допоміжні функції редагування, directive-tag helpers і safe-text utilities | - | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech-провайдера, а також експорти directive, registry і validation для провайдерів | - | `plugin-sdk/speech-core` | Спільні типи speech-провайдера, registry, directive і normalization helpers | - | `plugin-sdk/realtime-transcription` | Типи провайдера realtime transcription і допоміжні функції registry | - | `plugin-sdk/realtime-voice` | Типи провайдера realtime voice і допоміжні функції registry | - | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції registry | - | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні функції встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху webhook | - | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Реекспортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/media-runtime` | Спільні помічники fetch/transform/store медіа, а також побудовники медіа-пейлоаду | + | `plugin-sdk/media-understanding` | Типи постачальників media understanding, а також експорти помічників зображень/аудіо для постачальників | + | `plugin-sdk/text-runtime` | Спільні помічники тексту/markdown/logging, такі як видалення видимого для асистента тексту, render/chunking/table-помічники markdown, помічники редагування, помічники тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Помічник chunking вихідного тексту | + | `plugin-sdk/speech` | Типи постачальників мовлення, а також помічники директив, реєстру та валідації для постачальників | + | `plugin-sdk/speech-core` | Спільні типи постачальників мовлення, реєстр, директиви та помічники нормалізації | + | `plugin-sdk/realtime-transcription` | Типи постачальників realtime transcription і помічники реєстру | + | `plugin-sdk/realtime-voice` | Типи постачальників realtime voice і помічники реєстру | + | `plugin-sdk/image-generation` | Типи постачальників генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і помічники реєстру | + | `plugin-sdk/video-generation` | Типи постачальників/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, помічники failover, пошук постачальника і розбір model-ref | + | `plugin-sdk/webhook-targets` | Помічники реєстру цілей webhook і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Помічники нормалізації шляху webhook | + | `plugin-sdk/web-media` | Спільні помічники завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторно експортований `zod` для користувачів plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для manager/config/file/CLI helpers | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти engine embeddings хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти engine QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти engine storage хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні функції query хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні функції status хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції file/runtime хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb | + | `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` | Мультимодальні помічники хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Помічники запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Помічники секретів хоста пам’яті | + | `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-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb | - - | Family | Поточні підшляхи | Призначення | + + | Сімейство | Поточні підшляхи | Призначене використання | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | Допоміжні функції підтримки вбудованого browser-плагіна | - | 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 для вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime для вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій для вбудованого 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` | Шви сумісності/допоміжних функцій для вбудованих каналів | - | Допоміжні функції, специфічні для auth/плагінів | `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` | Шви допоміжних функцій для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin | + | 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` | Поверхня helper/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого 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` | Шви сумісності/допоміжні шви вбудованих каналів | + | Специфічні для 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` | Допоміжні шви вбудованих можливостей/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Метод | Що він реєструє | -| ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний CLI backend inference | -| `api.registerChannel(...)` | Канал повідомлень | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription | -| `api.registerRealtimeVoiceProvider(...)` | Двобічні сеанси realtime voice | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| Метод | Що реєструє | +| ------------------------------------------------ | ------------------------------ | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerChannel(...)` | Канал повідомлень | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова transcription realtime | +| `api.registerRealtimeVoiceProvider(...)` | Двобічні сесії realtime voice | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Постачальник web fetch / scrape | | `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти й команди +### Tools і команди -| Метод | Що він реєструє | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| Метод | Що реєструє | +| ------------------------------ | --------------------------------------------- | +| `api.registerTool(tool, opts?)` | Agent tool (обов’язковий або `{ optional: true }`) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура -| Метод | Що він реєструє | -| ---------------------------------------------- | --------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | -| `api.registerGatewayMethod(name, handler)` | Метод RPC Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| Метод | Що реєструє | +| --------------------------------------------- | --------------------- | +| `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)` | Інтерактивний handler | Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити -вужчу область gateway method. Для методів, що належать плагіну, -віддавайте перевагу префіксам, специфічним для плагіна. +`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається +призначити вужчу область gateway method. Для методів, що належать plugin, +віддавайте перевагу префіксам, специфічним для plugin. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, що належать реєстратору -- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, - маршрутизації та lazy-реєстрації CLI плагіна +- `commands`: явні корені команд, що належать registrar +- `descriptors`: дескриптори команд на етапі розбору, що використовуються для + довідки кореневого CLI, маршрутизації та лінивої реєстрації CLI plugin -Якщо ви хочете, щоб команда плагіна залишалася lazy-loaded у звичайному кореневому шляху CLI, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, який відкриває -цей реєстратор. +Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в +звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен +корінь команди верхнього рівня, що надається цим registrar. ```typescript api.registerCli( @@ -353,116 +353,121 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, коли вам не потрібна lazy-реєстрація кореневого CLI. -Цей сумісний eager-шлях і далі підтримується, але він не встановлює -плейсхолдери на основі descriptor для lazy loading на етапі парсингу. +Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива +реєстрація кореневого CLI. Цей сумісний eager-шлях усе ще підтримується, але +він не встановлює placeholders на основі descriptor для лінивого завантаження +на етапі розбору. ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ------------------------------------- | +| Метод | Що реєструє | +| ------------------------------------------ | ------------------------------------ | | `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) | -| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding пам’яті +### Адаптери embeddings пам’яті -| Метод | Що він реєструє | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | +| Метод | Що реєструє | +| ---------------------------------------------- | ------------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embeddings пам’яті для активного plugin | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` є ексклюзивними для плагінів пам’яті. -- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу реєструвати один - або більше ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або користувацький - ідентифікатор, визначений плагіном). + `registerMemoryRuntime` є ексклюзивними для plugins пам’яті. +- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті + зареєструвати один або кілька id адаптерів embeddings (наприклад `openai`, + `gemini` або користувацький id, визначений plugin). - Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, розв’язується відносно зареєстрованих ідентифікаторів - адаптерів. + `agents.defaults.memorySearch.fallback`, визначається відносно зареєстрованих + id цих адаптерів. ### Події та життєвий цикл -| Метод | Що він робить | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | +| Метод | Що робить | +| ------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований 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, ... }` є фінальним. Щойно будь-який обробник бере на себе диспетчеризацію, обробники нижчого пріоритету й типовий шлях диспетчеризації моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є фінальним. Щойно будь-який обробник встановлює його, обробники нижчого пріоритету пропускаються. -- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handlers із нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handlers із нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере диспетчеризацію на себе, handlers із нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handlers із нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. ### Поля об’єкта API -| Поле | Тип | Опис | +| Поле | Тип | Опис | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор плагіна | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні функції runtime](/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) | +| `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` | Поточний знімок конфігурації (активний знімок 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` | Розв’язати шлях відносно кореня плагіна | +| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня plugin | ## Угода щодо внутрішніх модулів -Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх +імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Внутрішні експорти лише для runtime - index.ts # Точка входу плагіна + runtime-api.ts # Лише внутрішні експорти runtime + index.ts # Точка входу plugin setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` + Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або - `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. + `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. -Завантажувані через facade публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу -активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime -ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску. +Публічні поверхні вбудованих plugins, що завантажуються через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають +перевагу активному знімку конфігурації runtime, коли OpenClaw уже запущено. Якщо +знімка runtime ще немає, вони переходять до резервного варіанту з визначеним +файлом конфігурації на диску. -Плагіни провайдерів також можуть відкривати вузький локальний barrel-контракт плагіна, коли -допоміжна функція навмисно є специфічною для провайдера і ще не належить до загального підшляху SDK. -Поточний вбудований приклад: провайдер Anthropic зберігає свої допоміжні функції потоку Claude -у власному публічному шві `api.ts` / `contract-api.ts` замість того, щоб просувати логіку Anthropic beta-header і `service_tier` -до загального контракту `plugin-sdk/*`. +Plugins постачальників також можуть надавати вузький локальний barrel-контракт +plugin, коли помічник навмисно є специфічним для постачальника і ще не належить +до узагальненого підшляху SDK. Поточний вбудований приклад: постачальник +Anthropic зберігає свої помічники потоку Claude у власному публічному шві +`api.ts` / `contract-api.ts` замість того, щоб просувати логіку beta-header і +`service_tier` Anthropic до узагальненого контракту `plugin-sdk/*`. Інші поточні вбудовані приклади: -- `@openclaw/openai-provider`: `api.ts` експортує побудовники провайдера, - допоміжні функції типових моделей і побудовники realtime-провайдера -- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник провайдера плюс - допоміжні функції онбордингу/конфігурації +- `@openclaw/openai-provider`: `api.ts` експортує побудовники постачальника, + помічники типових моделей і побудовники realtime-постачальників +- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник постачальника, а також + помічники онбордингу/конфігурації - Production-код розширення також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжна функція справді є спільною, підніміть її до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість зчеплення двох плагінів між собою. + Production-код extensions також має уникати імпортів + `openclaw/plugin-sdk/`. Якщо помічник справді є спільним, + просуньте його до нейтрального підшляху SDK, такого як + `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливості, замість того щоб жорстко зв’язувати два plugins. ## Пов’язане -- [Точки входу](/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` -- [Допоміжні функції runtime](/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` -- [Налаштування та конфігурація](/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації -- [Тестування](/plugins/sdk-testing) — утиліти тестування та правила lint -- [Міграція SDK](/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Внутрішня будова плагінів](/plugins/architecture) — поглиблена архітектура й модель можливостей +- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` +- [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) — глибока архітектура та модель можливостей diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index 2da1ff342..db0e4fe9c 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,30 +1,30 @@ --- read_when: - - Потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json - - Ви змінюєте поведінку автоущільнення або додаєте підготовчі дії перед ущільненням + - Потрібно налагодити ідентифікатори сесій, JSONL транскрипту або поля в sessions.json + - Ви змінюєте поведінку автоущільнення або додаєте службові дії “перед ущільненням” - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Детальний розбір: сховище сесій + транскрипти, життєвий цикл і внутрішня логіка (авто)ущільнення' -title: Детальний розбір керування сесіями +summary: 'Глибокий розбір: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)ущільнення' +title: Глибокий розбір керування сесіями x-i18n: - generated_at: "2026-04-05T18:17:29Z" + generated_at: "2026-04-05T18:49:16Z" model: gpt-5.4 provider: openai - source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091 + source_hash: e0d8c2d30be773eac0424f7a4419ab055fdd50daac8bc654e7d250c891f2c3b8 source_path: reference/session-management-compaction.md workflow: 15 --- -# Керування сесіями та ущільнення (детальний розбір) +# Керування сесіями та ущільнення (глибокий розбір) -У цьому документі пояснюється, як OpenClaw керує сесіями від початку до кінця: +У цьому документі пояснюється, як OpenClaw керує сесіями наскрізно: - **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`) -- **Сховище сесій** (`sessions.json`) і що в ньому відстежується -- **Збереження транскриптів** (`*.jsonl`) та їхня структура -- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запусками) +- **Сховище сесій** (`sessions.json`) і що воно відстежує +- **Збереження транскрипту** (`*.jsonl`) та його структура +- **Гігієна транскрипту** (виправлення для конкретних провайдерів перед запусками) - **Обмеження контексту** (вікно контексту проти відстежуваних токенів) -- **Ущільнення** (ручне + автоущільнення) і де підключати підготовчі дії перед ущільненням -- **Тихе службове обслуговування** (наприклад, записи в пам’ять, які не повинні створювати видимий для користувача вивід) +- **Ущільнення** (ручне + автоущільнення) і куди підключати роботу перед ущільненням +- **Тихі службові дії** (наприклад, запис пам’яті, який не повинен створювати видимий для користувача вивід) Якщо спочатку потрібен огляд вищого рівня, почніть із: @@ -33,31 +33,31 @@ x-i18n: - [/concepts/memory](/uk/concepts/memory) - [/concepts/memory-search](/uk/concepts/memory-search) - [/concepts/session-pruning](/uk/concepts/session-pruning) -- [/reference/transcript-hygiene](/reference/transcript-hygiene) +- [/reference/transcript-hygiene](/uk/reference/transcript-hygiene) --- ## Джерело істини: Gateway -OpenClaw спроєктований навколо єдиного **процесу Gateway**, який володіє станом сесій. +OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. -- Інтерфейси (macOS app, web Control UI, TUI) мають звертатися до Gateway по списки сесій і кількість токенів. -- У віддаленому режимі файли сесій знаходяться на віддаленому хості; «перевірка локальних файлів на Mac» не відображатиме те, що використовує Gateway. +- Інтерфейси (macOS app, веб-інтерфейс Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів. +- У віддаленому режимі файли сесій розміщені на віддаленому хості; “перевірка локальних файлів на Mac” не покаже те, що використовує Gateway. --- -## Два рівні збереження +## Два шари збереження -OpenClaw зберігає сесії на двох рівнях: +OpenClaw зберігає сесії у двох шарах: 1. **Сховище сесій (`sessions.json`)** - - Карта ключ/значення: `sessionKey -> SessionEntry` - - Невелике, змінюване, безпечне для редагування (або видалення записів) - - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) + - Мапа ключ/значення: `sessionKey -> SessionEntry` + - Маленьке, змінюване, безпечно редагувати (або видаляти записи) + - Відстежує метадані сесії (поточний id сесії, останню активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - - Транскрипт із дозаписом і деревоподібною структурою (записи мають `id` + `parentId`) - - Зберігає фактичну розмову + виклики інструментів + підсумки ущільнення + - Транскрипт лише з додаванням записів із деревоподібною структурою (записи мають `id` + `parentId`) + - Зберігає фактичну розмову + виклики інструментів + зведення ущільнення - Використовується для відновлення контексту моделі для майбутніх ходів --- @@ -74,27 +74,27 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`. --- -## Обслуговування сховища та керування диском +## Обслуговування сховища та контроль диска Збереження сесій має автоматичні механізми обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: - `mode`: `warn` (типово) або `enforce` -- `pruneAfter`: поріг давності для видалення застарілих записів (типово `30d`) +- `pruneAfter`: поріг віку застарілих записів для очищення (типово `30d`) - `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) - `rotateBytes`: ротація `sessions.json`, коли файл стає завеликим (типово `10mb`) -- `resetArchiveRetention`: строк зберігання для архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) -- `maxDiskBytes`: необов’язковий ліміт для каталогу сесій -- `highWaterBytes`: необов’язкове цільове значення після очищення (типово `80%` від `maxDiskBytes`) +- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) +- `maxDiskBytes`: необов’язковий бюджет каталогу sessions на диску +- `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Порядок примусового очищення за бюджетом диска (`mode: "enforce"`): +Порядок примусового очищення для бюджету диска (`mode: "enforce"`): -1. Спочатку видалити найстаріші архівні або осиротілі артефакти транскриптів. -2. Якщо ціль і далі не досягнута, видаляти найстаріші записи сесій і їхні файли транскриптів. -3. Продовжувати, доки використання не стане меншим або рівним `highWaterBytes`. +1. Спочатку видалити найстаріші архівовані або осиротілі артефакти транскриптів. +2. Якщо все ще вище за ціль, витіснити найстаріші записи сесій і їхні файли транскриптів. +3. Продовжувати, доки використання не стане на рівні або нижче `highWaterBytes`. -У режимі `mode: "warn"` OpenClaw повідомляє про потенційні видалення, але не змінює сховище/файли. +У режимі `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,7 +118,7 @@ openclaw sessions cleanup --enforce Поширені шаблони: -- Основний/прямий чат (на агента): `agent::` (типово `main`) +- Основний/приватний чат (на агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` @@ -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,25 +147,25 @@ openclaw sessions cleanup --enforce Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`. -Ключові поля (не вичерпно): +Ключові поля (не вичерпний список): -- `sessionId`: поточний ідентифікатор транскрипту (ім’я файлу походить із нього, якщо не задано `sessionFile`) -- `updatedAt`: час останньої активності -- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту +- `sessionId`: поточний id транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`) +- `updatedAt`: мітка часу останньої активності +- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту - `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення групи/каналу +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (перевизначення для конкретної сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (найкраще наближення / залежать від провайдера): +- Лічильники токенів (best-effort / залежать від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: як часто автоущільнення завершувалося для цього ключа сесії -- `memoryFlushAt`: часовий штамп останнього скидання пам’яті перед ущільненням +- `compactionCount`: скільки разів автоущільнення завершувалося для цього ключа сесії +- `memoryFlushAt`: мітка часу останнього скидання пам’яті перед ущільненням - `memoryFlushCompactionCount`: лічильник ущільнень, коли востаннє виконувався flush -Сховище безпечно редагувати, але джерелом істини є Gateway: під час роботи сесій він може перезаписувати або повторно гідратувати записи. +Сховище безпечно редагувати, але Gateway є джерелом істини: під час виконання сесій він може переписувати або повторно гідратувати записи. --- @@ -181,12 +181,12 @@ openclaw sessions cleanup --enforce Помітні типи записів: - `message`: повідомлення user/assistant/toolResult -- `custom_message`: повідомлення, вставлені розширенням, які _потрапляють_ у контекст моделі (можуть бути прихованими в інтерфейсі) -- `custom`: стан розширення, який _не потрапляє_ в контекст моделі -- `compaction`: збережений підсумок ущільнення з `firstKeptEntryId` і `tokensBefore` -- `branch_summary`: збережений підсумок під час навігації по гілці дерева +- `custom_message`: повідомлення, інжектовані розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI) +- `custom`: стан розширення, який _не потрапляє_ у контекст моделі +- `compaction`: збережене зведення ущільнення з `firstKeptEntryId` і `tokensBefore` +- `branch_summary`: збережене зведення під час навігації гілкою дерева -OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. +OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису. --- @@ -195,39 +195,39 @@ OpenClaw навмисно **не** «виправляє» транскрипти Важливі два різні поняття: 1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сесій**: ковзні статистики, що записуються в `sessions.json` (використовуються для /status і панелей керування) +2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і панелей) -Якщо ви налаштовуєте ліміти: +Якщо ви налаштовуєте обмеження: - Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — це оцінка/значення для звітності під час виконання; не сприймайте його як сувору гарантію. +- `contextTokens` у сховищі — це оцінка/значення звітності під час виконання; не сприймайте його як сувору гарантію. -Докладніше див. у [/token-use](/reference/token-use). +Докладніше див. у [/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 зберігає цей очікувальний блок інструмента і залишає неузагальнений хвіст недоторканим. +- Перервані/помилкові блоки викликів інструментів не утримують відкритим очікувальний поділ. --- @@ -239,7 +239,7 @@ OpenClaw навмисно **не** «виправляє» транскрипти (`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 +249,13 @@ exceeded` та подібні варіанти у стилі конкретно - `contextWindow` — це вікно контексту моделі - `reserveTokens` — це запас токенів, зарезервований для промптів + наступного виводу моделі -Це семантика середовища Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати ущільнення). +Це семантика середовища Pi (OpenClaw споживає події, але коли ущільнювати, вирішує Pi). --- ## Налаштування ущільнення (`reserveTokens`, `keepRecentTokens`) -Налаштування ущільнення Pi знаходяться в параметрах Pi: +Налаштування ущільнення Pi зберігаються в налаштуваннях Pi: ```json5 { @@ -267,14 +267,14 @@ exceeded` та подібні варіанти у стилі конкретно } ``` -OpenClaw також застосовує нижню межу безпеки для вбудованих запусків: +OpenClaw також застосовує мінімальний захисний поріг для вбудованих запусків: -- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення. -- Типове значення нижньої межі — `20000` токенів. -- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути нижню межу. +- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує значення. +- Типовий поріг — `20000` токенів. +- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. - Якщо значення вже вище, OpenClaw залишає його без змін. -Навіщо: залишити достатній запас для багатокрокового «службового обслуговування» (наприклад, записів у пам’ять), перш ніж ущільнення стане неминучим. +Чому: залишити достатньо запасу для багатокрокових “службових” дій (наприклад, записів пам’яті), перш ніж ущільнення стане неминучим. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). @@ -283,46 +283,46 @@ OpenClaw також застосовує нижню межу безпеки дл ## Поверхні, видимі користувачу -Ви можете спостерігати ущільнення та стан сесії через: +Ви можете спостерігати ущільнення і стан сесії через: -- `/status` (у будь-якій сесії чату) +- `/status` (у будь-якому чаті сесії) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Докладний режим: `🧹 Auto-compaction complete` + кількість ущільнень +- Режим verbose: `🧹 Auto-compaction complete` + кількість ущільнень --- -## Тихе службове обслуговування (`NO_REPLY`) +## Тихі службові дії (`NO_REPLY`) -OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. +OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. -Домовленість: +Умова: -- Помічник починає свій вивід із точного тихого токена `NO_REPLY` / - `no_reply`, щоб позначити «не доставляти відповідь користувачу». -- OpenClaw видаляє/пригнічує це на рівні доставки. -- Пригнічення точного тихого токена не залежить від регістру, тож `NO_REPLY` і - `no_reply` зараховуються, коли весь вміст складається лише з тихого токена. -- Це призначено лише для справжніх фонових ходів без доставки; це не скорочення - для звичайних дієвих запитів користувача. +- Асистент починає свій вивід з точного тихого токена `NO_REPLY` / + `no_reply`, щоб позначити “не доставляти відповідь користувачу”. +- OpenClaw прибирає/приглушує це на рівні доставки. +- Приглушення точного тихого токена нечутливе до регістру, тож `NO_REPLY` і + `no_reply` обидва зараховуються, коли весь payload — це лише тихий токен. +- Це лише для справді фонових ходів/ходів без доставки; це не скорочений шлях + для звичайних практичних запитів користувача. -Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокову передачу чернеток/набору**, коли -частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали частковий +Починаючи з `2026.1.10`, OpenClaw також приглушує **чернетковий/набірний стримінг**, коли +частковий чанк починається з `NO_REPLY`, щоб тихі операції не видавали частковий вивід посеред ходу. --- -## «Скидання пам’яті» перед ущільненням (реалізовано) +## "Скидання пам’яті" перед ущільненням (реалізовано) -Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який запише довготривалий +Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який записує стійкий стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб ущільнення не могло стерти критичний контекст. -OpenClaw використовує підхід **скидання перед порогом**: +OpenClaw використовує підхід **flush до порога**: 1. Відстежувати використання контексту сесії. -2. Коли воно перетинає «м’який поріг» (нижче від порога ущільнення Pi), виконати тиху - директиву «запиши пам’ять зараз» для агента. +2. Коли воно перетинає “м’який поріг” (нижчий за поріг ущільнення Pi), виконати тиху + директиву “запиши пам’ять зараз” для агента. 3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач нічого не бачив. @@ -330,29 +330,29 @@ OpenClaw використовує підхід **скидання перед п - `enabled` (типово: `true`) - `softThresholdTokens` (типово: `4000`) -- `prompt` (повідомлення користувача для ходу flush) -- `systemPrompt` (додатковий системний промпт, доданий для ходу flush) +- `prompt` (повідомлення user для ходу flush) +- `systemPrompt` (додатковий системний промпт, який додається для ходу flush) Примітки: -- Типові `prompt`/`systemPrompt` містять підказку `NO_REPLY` для пригнічення +- Типові значення prompt/system prompt містять підказку `NO_REPLY` для приглушення доставки. - Flush виконується один раз за цикл ущільнення (відстежується в `sessions.json`). -- Flush виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають). +- Flush виконується лише для вбудованих сесій Pi. - Flush пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Memory](/uk/concepts/memory), щоб дізнатися про структуру файлів у робочому просторі та шаблони запису. +- Див. [Memory](/uk/concepts/memory) щодо структури файлів робочого простору та шаблонів запису. -Pi також надає хук `session_before_compact` в API розширень, але логіка -flush в OpenClaw сьогодні знаходиться на боці Gateway. +Pi також надає хук `session_before_compact` в API розширень, але логіка flush в OpenClaw +сьогодні живе на боці Gateway. --- -## Контрольний список для усунення несправностей +## Контрольний список усунення несправностей -- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. -- Невідповідність між сховищем і транскриптом? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`. +- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і перевірте `sessionKey` у `/status`. +- Невідповідність між сховищем і транскриптом? Перевірте хост Gateway і шлях до сховища з `openclaw status`. - Спам ущільненням? Перевірте: - вікно контексту моделі (замале) - - налаштування ущільнення (`reserveTokens`, занадто велике для вікна моделі, може спричиняти раніше ущільнення) - - роздування `toolResult`: увімкніть/налаштуйте обрізання сесій -- Тихі ходи «просочуються»? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення для пригнічення потокової передачі. + - налаштування ущільнення (`reserveTokens` завелике для вікна моделі може спричиняти раніше ущільнення) + - роздуття tool-result: увімкніть/налаштуйте очищення сесії +- Тихі ходи протікають? Переконайтеся, що відповідь починається з `NO_REPLY` (нечутливий до регістру точний токен) і що у вас збірка, яка містить виправлення приглушення стримінгу. diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index b3a3b7ec5..08a2b744a 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,230 +1,229 @@ --- read_when: - - Запуск coding harness через ACP - - Налаштування ACP-сесій, прив’язаних до розмов, у каналах обміну повідомленнями - - Прив’язка розмови в каналі повідомлень до постійної ACP-сесії - - Усунення проблем із бекендом ACP і wiring плагінів - - Керування командами /acp із чату -summary: Використовуйте runtime-сесії ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших harness-агентів -title: ACP-агенти + - Запуск harness-оточень для кодування через ACP + - Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями + - Прив’язування розмови в каналі повідомлень до постійного сеансу ACP + - Усунення несправностей бекенду ACP і підключення плагінів + - Керування командами /acp з чату +summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness +title: Агенти ACP x-i18n: - generated_at: "2026-04-05T18:20:13Z" + generated_at: "2026-04-05T18:49:57Z" model: gpt-5.4 provider: openai - source_hash: 99e4d5af60fe89314b53655bbad01494d972b55416cf5a529171c010a0b8547d + source_hash: 302f3fe25b1ffe0576592b6e0ad9e8a5781fa5702b31d508d9ba8908f7df33bd source_path: tools/acp-agents.md workflow: 15 --- -# ACP-агенти +# Агенти 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. +Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають змогу OpenClaw запускати зовнішні harness-оточення для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX-harness-оточення) через плагін бекенду ACP. -Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до runtime ACP (а не до нативного runtime субагента). Кожен запуск ACP-сесії відстежується як [фонове завдання](/uk/automation/tasks). +Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у гілці», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо -до наявних розмов OpenClaw у каналах, використовуйте [`openclaw mcp serve`](/cli/mcp) +до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp) замість ACP. -## Яка сторінка мені потрібна? +## Яку сторінку мені потрібно? -Поруч є три схожі поверхні, які легко переплутати: +Поруч є три поверхні, які легко сплутати: -| Ви хочете... | Використовуйте це | Примітки | -| --------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: ACP-агенти | Сесії, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, runtime-керування | -| Експонувати сесію OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим моста. IDE/клієнт спілкується з OpenClaw через ACP поверх stdio/WebSocket | +| Ви хочете... | Використовуйте це | Примітки | +| --------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Запускати 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 | -## Чи працює це одразу після встановлення? +## Це працює одразу після встановлення? Зазвичай так. -- Нові встановлення тепер постачаються з комплектним runtime-плагіном `acpx`, увімкненим типово. -- Комплектний плагін `acpx` надає перевагу своєму локально закріпленому бінарнику `acpx`. -- Під час запуску OpenClaw перевіряє цей бінарник і за потреби самостійно відновлює його. +- Нові встановлення тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`. +- Вбудований плагін `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 на цьому хості. -## Швидкий операторський сценарій +## Швидкий операторський потік -Використовуйте це, якщо вам потрібен практичний runbook для `/acp`: +Використовуйте це, якщо вам потрібна практична інструкція для `/acp`: -1. Створіть сесію: +1. Запустіть сеанс: - `/acp spawn codex --bind here` - `/acp spawn codex --mode persistent --thread auto` -2. Працюйте в прив’язаній розмові або треді (або явно вкажіть ключ цієї сесії). -3. Перевірте стан runtime: +2. Працюйте в прив’язаній розмові або гілці (або явно вкажіть ключ цього сеансу). +3. Перевірте стан середовища виконання: - `/acp status` -4. За потреби налаштуйте параметри runtime: +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 у треді тут і тримай її сфокусованою.» -- «Запусти це як одноразову ACP-сесію Claude Code і підсумуй результат.» -- «Прив’яжи цей чат iMessage до Codex і зберігай подальші повідомлення в тому самому workspace.» -- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші повідомлення в цьому самому треді.» +- «Прив’яжи цей канал Discord до Codex». +- «Запусти тут постійний сеанс Codex у гілці й тримай його зосередженим». +- «Виконай це як одноразовий сеанс Claude Code ACP і підсумуй результат». +- «Прив’яжи цей чат iMessage до Codex і зберігай наступні повідомлення в тому самому робочому просторі». +- «Використай 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, коли вам потрібен зовнішній harness runtime. Використовуйте субагентів, коли вам потрібні делеговані запуски, нативні для OpenClaw. +Використовуйте ACP, коли потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, коли потрібні делеговані запуски OpenClaw. -| Область | ACP-сесія | Запуск субагента | -| ------------- | ------------------------------------- | ----------------------------------- | -| Runtime | Плагін бекенда ACP (наприклад acpx) | Нативний runtime субагента OpenClaw | -| Ключ сесії | `agent::acp:` | `agent::subagent:` | -| Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типовий runtime) | +| Область | Сеанс ACP | Запуск субагента | +| ------------- | -------------------------------------- | ----------------------------------- | +| Середовище виконання | Плагін бекенду ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw | +| Ключ сеансу | `agent::acp:` | `agent::subagent:` | +| Основні команди | `/acp ...` | `/subagents ...` | +| Інструмент запуску | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | -Див. також [Субагенти](/tools/subagents). +Див. також [Субагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code Для Claude Code через ACP стек такий: -1. Керувальна площина ACP-сесії OpenClaw -2. комплектний runtime-плагін `acpx` +1. Площина керування сеансом OpenClaw ACP +2. вбудований плагін середовища виконання `acpx` 3. адаптер Claude ACP -4. runtime/механізми сесій на боці Claude +4. механізм середовища виконання/сеансу на боці Claude Важлива відмінність: -- ACP Claude — це harness-сесія з ACP-керуванням, відновленням сесій, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треда. +- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки. Для операторів практичне правило таке: -- потрібні `/acp spawn`, сесії з прив’язкою, runtime-керування або постійна робота harness: використовуйте ACP -- потрібен простий локальний текстовий fallback через сирий CLI: використовуйте CLI-бекенди +- якщо потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness — використовуйте ACP -## Прив’язані сесії +## Прив’язані сеанси ### Прив’язки до поточної розмови -Використовуйте `/acp spawn --bind here`, якщо хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда. +Використовуйте `/acp spawn --bind here`, коли хочете, щоб поточна розмова стала довговічним робочим простором ACP без створення дочірньої гілки. Поведінка: -- 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. -- Runtime ACP усе одно може мати власний робочий каталог (`cwd`) або workspace на диску, яким керує бекенд. Цей runtime-workspace відокремлений від поверхні чату і не означає створення нового треда повідомлень. -- Якщо ви створюєте сесію для іншого ACP-агента і не передаєте `--cwd`, OpenClaw типово успадковує workspace **цільового агента**, а не того, хто робить запит. -- Якщо цей успадкований шлях до workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до типового cwd бекенда замість того, щоб непомітно повторно використати неправильне дерево. -- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`. +- `--bind here` все одно може створити новий сеанс ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цей сеанс до поточної розмови. +- `--bind here` сам по собі не створює дочірню гілку Discord або тему Telegram. +- Середовище виконання ACP все одно може мати власну робочу директорію (`cwd`) або робочий простір на диску, яким керує бекенд. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нової гілки повідомлень. +- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не запитувача. +- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево. +- Якщо успадкований робочий простір існує, але доступ до нього неможливий (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`. Ментальна модель: - поверхня чату: де люди продовжують спілкуватися (`канал Discord`, `тема Telegram`, `чат iMessage`) -- ACP-сесія: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw -- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, яка створюється лише через `--thread ...` -- runtime-workspace: розташування у файловій системі, де виконується harness (`cwd`, checkout репозиторію, workspace бекенда) +- сеанс ACP: довговічний стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити +- дочірня гілка/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` +- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенду) Приклади: -- `/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-сесії, а не каналу. Ви можете повторно використати або замінити стан runtime без зміни поточної поверхні чату. +- У Discord `--bind here` прив’язує поточний канал або гілку на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here`. +- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає зрозуміле повідомлення про непідтримку. +- `resume` і питання «нового сеансу» — це питання сеансу ACP, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату. -### Сесії, прив’язані до треда +### Сеанси з прив’язкою до гілки -Коли для адаптера каналу ввімкнено прив’язки тредів, ACP-сесії можна прив’язувати до тредів: +Коли для адаптера каналу ввімкнено прив’язки до гілок, сеанси ACP можна прив’язувати до гілок: -- OpenClaw прив’язує тред до цільової ACP-сесії. -- Подальші повідомлення в цьому треді маршрутизуються до прив’язаної ACP-сесії. -- Вивід ACP доставляється назад у той самий тред. -- Розфокусування/закриття/архівування/тайм-аут бездіяльності або перевищення max-age прибирає прив’язку. +- OpenClaw прив’язує гілку до цільового сеансу ACP. +- Наступні повідомлення в цій гілці спрямовуються до прив’язаного сеансу ACP. +- Вивід ACP доставляється назад у ту саму гілку. +- Розфокусування, закриття, архівування, тайм-аут бездіяльності або завершення max-age прибирає прив’язку. -Підтримка прив’язки тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки тредів, OpenClaw повертає зрозуміле повідомлення про непідтримуваність/недоступність. +Підтримка прив’язки до гілки залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до гілки, OpenClaw повертає зрозуміле повідомлення про непідтримку/недоступність. -Потрібні feature flags для ACP, прив’язаного до тредів: +Необхідні прапорці функцій для ACP із прив’язкою до гілки: - `acp.enabled=true` -- `acp.dispatch.enabled` типово увімкнено (встановіть `false`, щоб призупинити ACP-dispatch) -- Увімкнений прапорець створення ACP-тредів для адаптера каналу (залежить від адаптера) +- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) +- Увімкнено прапорець запуску ACP у гілках адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -### Канали з підтримкою тредів +### Канали з підтримкою гілок -- Будь-який адаптер каналу, який надає можливість прив’язки сесії/треда. +- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/гілки. - Поточна вбудована підтримка: - - треди/канали Discord - - теми Telegram (теми форуму в групах/супергрупах і DM-теми) + - гілки/канали Discord + - теми Telegram (форумні теми в групах/супергрупах і DM-теми) - Канали-плагіни можуть додавати підтримку через той самий інтерфейс прив’язки. ## Налаштування для конкретних каналів -Для неепізодичних сценаріїв налаштовуйте постійні ACP-прив’язки у верхньорівневих записах `bindings[]`. +Для неепізодичних робочих процесів налаштуйте постійні ACP-прив’язки в записах верхнього рівня `bindings[]`. ### Модель прив’язки - `bindings[].type="acp"` позначає постійну ACP-прив’язку розмови. -- `bindings[].match` ідентифікує цільову розмову: - - канал або тред Discord: `match.channel="discord"` + `match.peer.id=""` - - тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. - - DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*`. -- `bindings[].agentId` — це id власника-агента OpenClaw. -- Необов’язкові ACP-перевизначення розміщуються в `bindings[].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:*`. +- `bindings[].agentId` — це id агента OpenClaw-власника. +- Необов’язкові перевизначення 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`) @@ -232,11 +231,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`) Приклад: @@ -320,18 +319,18 @@ x-i18n: Поведінка: -- OpenClaw гарантує існування налаштованої ACP-сесії перед використанням. -- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої ACP-сесії. -- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сесії на місці. -- Тимчасові runtime-прив’язки (наприклад створені потоками фокусування тредів) усе ще застосовуються там, де вони є. -- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента. -- Відсутні успадковані шляхи workspace повертаються до типового cwd бекенда; невідсутні помилки доступу повертаються як помилки запуску. +- OpenClaw гарантує, що налаштований сеанс ACP існує до початку використання. +- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. +- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на гілці) усе ще застосовуються, де вони є. +- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. +- Відсутні успадковані шляхи до робочого простору призводять до повернення до стандартного cwd бекенду; невідсутні помилки доступу повертаються як помилки запуску. -## Запуск ACP-сесій (інтерфейси) +## Запуск сеансів ACP (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"`, щоб запустити ACP-сесію з ходу агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. ```json { @@ -345,29 +344,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` (обов’язково): початковий промпт, надісланий до сеансу ACP. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): id цільового ACP-harness. Якщо не задано, використовується `acp.defaultAgent`. -- `thread` (необов’язково, типово `false`): запросити сценарій прив’язки до треда там, де він підтримується. +- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано. +- `thread` (необов’язково, за замовчуванням `false`): запитати потік прив’язки до гілки там, де це підтримується. - `mode` (необов’язково): `run` (одноразовий) або `session` (постійний). - - типове значення — `run` - - якщо `thread: true` і `mode` не задано, OpenClaw може за runtime-шляхом типово обрати постійну поведінку + - за замовчуванням використовується `run` + - якщо `thread: true` і mode не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитаний робочий каталог runtime (перевіряється політикою бекенда/runtime). Якщо не задано, ACP-запуск успадковує workspace цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенда, тоді як реальні помилки доступу повертаються назовні. -- `label` (необов’язково): операторська мітка, що використовується в тексті сесії/банера. -- `resumeSessionId` (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через `session/load`. Потребує `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` транслює підсумки прогресу початкового ACP-запуску назад до сесії-запитувача як системні події. - - Коли це доступно, прийняті відповіді можуть містити `streamLogPath`, що вказує на JSONL-журнал у межах сесії (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. +- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, під час запуску ACP успадковується робочий простір цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних параметрів бекенду, а реальні помилки доступу повертаються. +- `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера. +- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події. + - За наявності прийнятні відповіді включають `streamLogPath`, який вказує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. -### Відновлення наявної сесії +### Відновлення наявного сеансу -Використовуйте `resumeSessionId`, щоб продовжити попередню ACP-сесію замість нового запуску. Агент відтворює свою історію розмов через `session/load`, тож продовжує з повним контекстом попередніх подій. +Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює свою історію розмов через `session/load`, тому відновлює роботу з повним контекстом попередніх дій. ```json { @@ -378,43 +377,43 @@ x-i18n: } ``` -Поширені сценарії використання: +Типові сценарії використання: -- Передати сесію Codex із ноутбука на телефон — скажіть агенту продовжити звідти, де ви зупинилися -- Продовжити coding-сесію, яку ви почали інтерактивно в CLI, тепер у headless-режимі через агента -- Відновити роботу, перервану перезапуском gateway або тайм-аутом бездіяльності +- Передати сеанс Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися +- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, а тепер хочете виконувати безголово через агента +- Відновити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності Примітки: -- `resumeSessionId` вимагає `runtime: "acp"` — при використанні з runtime субагента повертається помилка. -- `resumeSessionId` відновлює upstream-історію розмов ACP; `thread` і `mode` усе одно застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`. -- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). -- Якщо id сесії не знайдено, запуск завершується зрозумілою помилкою — без тихого fallback до нової сесії. +- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента. +- `resumeSessionId` відновлює історію вхідної ACP-розмови; `thread` і `mode` як і раніше застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`. +- Цільовий агент має підтримувати `session/load` (Codex і Claude Code це підтримують). +- Якщо id сеансу не знайдено, запуск завершиться зрозумілою помилкою — без тихого повернення до нового сеансу. ### Операторський smoke test -Використовуйте це після розгортання gateway, якщо хочете швидко перевірити наживо, що ACP-запуск -справді працює end-to-end, а не лише проходить unit-тести. +Використовуйте це після розгортання gateway, коли потрібна швидка жива перевірка того, що запуск ACP +справді працює наскрізь, а не лише проходить модульні тести. -Рекомендований gate: +Рекомендований бар’єр перевірки: 1. Перевірте версію/коміт розгорнутого gateway на цільовому хості. -2. Підтвердьте, що в розгорнутому source-коді є прийняття lineage ACP у +2. Підтвердьте, що розгорнуте джерело містить прийняття лінійності ACP у `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). -3. Відкрийте тимчасову сесію мосту ACPX до живого агента (наприклад +3. Відкрийте тимчасовий сеанс мосту ACPX до живого агента (наприклад `razor(main)` на `jpclawhq`). 4. Попросіть цього агента викликати `sessions_spawn` із: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - - завданням: `Reply with exactly LIVE-ACP-SPAWN-OK` + - task: `Reply with exactly LIVE-ACP-SPAWN-OK` 5. Переконайтеся, що агент повідомляє: - `accepted=yes` - реальний `childSessionKey` - відсутність помилки валідатора -6. Приберіть тимчасову сесію мосту ACPX. +6. Приберіть тимчасовий сеанс мосту ACPX. -Приклад запиту до живого агента: +Приклад промпту для живого агента: ```text Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run". @@ -424,25 +423,25 @@ Then report only: accepted=; childSessionKey=; error=` - `--label ` -Див. [Слеш-команди](/tools/slash-commands). +Див. [Слеш-команди](/uk/tools/slash-commands). -## Визначення цілі сесії +## Визначення цілі сеансу -Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, `session-id` або `session-label`). +Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`). Порядок визначення: @@ -475,48 +474,48 @@ ACP-сесії наразі виконуються в runtime хоста, а н - спочатку пробує ключ - потім session id у форматі UUID - потім мітку -2. Поточна прив’язка треда (якщо ця розмова/тред прив’язана до ACP-сесії) -3. Fallback до поточної сесії запитувача +2. Прив’язка поточної гілки (якщо ця розмова/гілка прив’язана до сеансу ACP) +3. Резервний варіант: поточний сеанс запитувача -Прив’язки як до поточної розмови, так і до треда, беруть участь у кроці 2. +Прив’язки до поточної розмови та прив’язки до гілки беруть участь у кроці 2. -Якщо ціль не визначено, OpenClaw повертає зрозумілу помилку (`Unable to resolve session target: ...`). +Якщо жодної цілі не вдається визначити, OpenClaw повертає зрозумілу помилку (`Unable to resolve session target: ...`). ## Режими прив’язки під час запуску `/acp spawn` підтримує `--bind here|off`. -| Режим | Поведінка | -| ------ | ----------------------------------------------------------------------- | -| `here` | Прив’язати поточну активну розмову на місці; завершити з помилкою, якщо активної немає. | -| `off` | Не створювати прив’язку до поточної розмови. | +| Режим | Поведінка | +| ------ | ---------------------------------------------------------------------- | +| `here` | Прив’язати поточну активну розмову на місці; помилка, якщо її немає. | +| `off` | Не створювати прив’язку до поточної розмови. | Примітки: -- `--bind here` — найпростіший операторський шлях для сценарію «зробити цей канал або чат підкріпленим Codex». -- `--bind here` не створює дочірній тред. -- `--bind here` доступний лише на каналах, які надають підтримку прив’язки до поточної розмови. +- `--bind here` — найпростіший операторський шлях для «зробити цей канал або чат підкріпленим Codex». +- `--bind here` не створює дочірню гілку. +- `--bind here` доступний лише в каналах, які підтримують прив’язку до поточної розмови. - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`. -## Режими тредів під час запуску +## Режими гілок під час запуску `/acp spawn` підтримує `--thread auto|here|off`. | Режим | Поведінка | | ------ | ---------------------------------------------------------------------------------------------------- | -| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо підтримується. | -| `here` | Вимагати поточний активний тред; завершити з помилкою, якщо ви не в треді. | -| `off` | Без прив’язки. Сесія запускається без прив’язки. | +| `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. | +| `here` | Вимагає поточної активної гілки; помилка, якщо ви не в гілці. | +| `off` | Без прив’язки. Сеанс запускається без прив’язки. | Примітки: -- На поверхнях без прив’язки тредів типова поведінка фактично дорівнює `off`. -- Запуск із прив’язкою треда вимагає підтримки політики каналу: +- На поверхнях без підтримки прив’язки до гілки поведінка за замовчуванням фактично дорівнює `off`. +- Запуск із прив’язкою до гілки вимагає підтримки політики каналу: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірнього треда. +- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірньої гілки. -## Керування ACP +## Елементи керування ACP Доступне сімейство команд: @@ -536,49 +535,49 @@ ACP-сесії наразі виконуються в runtime хоста, а н - `/acp doctor` - `/acp install` -`/acp status` показує ефективні параметри runtime і, коли доступно, ідентифікатори сесії як на рівні runtime, так і на рівні бекенда. +`/acp status` показує ефективні параметри середовища виконання і, за наявності, ідентифікатори сеансів як на рівні середовища виконання, так і на рівні бекенду. -Деякі елементи керування залежать від можливостей бекенда. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає зрозумілу помилку про непідтримуваний елемент керування. +Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає зрозумілу помилку про непідтримуваний елемент керування. -## Кулінарна книга команд ACP +## Книга рецептів для команд ACP -| Команда | Що робить | Приклад | -| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | Створює ACP-сесію; необов’язкова прив’язка тут або до треда. | `/acp spawn codex --bind here --cwd /repo` | -| `/acp cancel` | Скасовує хід у процесі для цільової сесії. | `/acp cancel agent:codex:acp:` | -| `/acp 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` | Встановлює 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 spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до гілки. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасовує поточний хід для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/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` | -`/acp sessions` читає сховище для поточної прив’язаної сесії або сесії запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через пошук сесій gateway, включно з кастомними коренями `session.store` для окремих агентів. +`/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів. -## Відображення параметрів runtime +## Відображення параметрів середовища виконання -`/acp` має зручні команди та універсальний setter. +`/acp` має зручні команди та загальний сеттер. Еквівалентні операції: -- `/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` очищає всі перевизначення runtime для цільової сесії. +- `/acp model ` відповідає ключу конфігурації середовища виконання `model`. +- `/acp permissions ` відповідає ключу конфігурації середовища виконання `approval_policy`. +- `/acp timeout ` відповідає ключу конфігурації середовища виконання `timeout`. +- `/acp cwd ` безпосередньо оновлює перевизначення cwd середовища виконання. +- `/acp set ` — це загальний шлях. + - Особливий випадок: `key=cwd` використовує шлях перевизначення cwd. +- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу. ## Підтримка harness acpx (поточна) -Поточні вбудовані псевдоніми harness в acpx: +Поточні вбудовані псевдоніми harness acpx: - `claude` - `codex` @@ -595,12 +594,12 @@ ACP-сесії наразі виконуються в runtime хоста, а н - `pi` - `qwen` -Коли OpenClaw використовує бекенд acpx, надавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено власні псевдоніми агентів. -Якщо ваша локальна інсталяція Cursor усе ще експонує ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого типового значення. +Коли OpenClaw використовує бекенд acpx, віддавайте перевагу цим значенням для `agentId`, якщо тільки у вашій конфігурації acpx не визначено користувацькі псевдоніми агентів. +Якщо ваш локальний Cursor усе ще показує ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого стандартного значення. -Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw через `agentId`). +Безпосереднє використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей сирий обхідний шлях є функцією CLI acpx (а не звичайним шляхом `agentId` в OpenClaw). -## Обов’язкова конфігурація +## Необхідна конфігурація Базова конфігурація ACP: @@ -608,7 +607,7 @@ ACP-сесії наразі виконуються в runtime хоста, а н { acp: { enabled: true, - // Необов’язково. Типове значення true; встановіть false, щоб призупинити ACP-dispatch, зберігши /acp controls. + // Необов’язково. За замовчуванням true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -640,7 +639,7 @@ ACP-сесії наразі виконуються в runtime хоста, а н } ``` -Конфігурація прив’язки тредів залежить від адаптера каналу. Приклад для Discord: +Конфігурація прив’язки до гілок залежить від адаптера каналу. Приклад для Discord: ```json5 { @@ -662,18 +661,18 @@ ACP-сесії наразі виконуються в runtime хоста, а н } ``` -Якщо запуск ACP із прив’язкою треда не працює, спершу перевірте feature flag адаптера: +Якщо запуск ACP із прив’язкою до гілки не працює, спочатку перевірте прапорець функції адаптера: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` -Прив’язки до поточної розмови не вимагають створення дочірнього треда. Вони вимагають активного контексту розмови й адаптера каналу, який надає прив’язки ACP до розмови. +Прив’язки до поточної розмови не потребують створення дочірньої гілки. Вони потребують активного контексту розмови й адаптера каналу, який надає ACP-прив’язки розмов. Див. [Довідник із конфігурації](/uk/gateway/configuration-reference). -## Налаштування плагіна для бекенда acpx +## Налаштування плагіна для бекенду acpx -Нові встановлення постачаються з комплектним runtime-плагіном `acpx`, увімкненим типово, тож ACP -зазвичай працює без ручного кроку встановлення плагіна. +Нові встановлення постачаються з увімкненим за замовчуванням вбудованим плагіном +середовища виконання `acpx`, тому ACP зазвичай працює без ручного кроку встановлення плагіна. Почніть із: @@ -682,34 +681,34 @@ ACP-сесії наразі виконуються в runtime хоста, а н ``` Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny` або хочете -перемкнутися на локальний checkout для розробки, використовуйте явний шлях плагіна: +перейти на локальний checkout для розробки, скористайтеся явним шляхом плагіна: ```bash openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true ``` -Локальне встановлення workspace під час розробки: +Локальне встановлення робочого простору під час розробки: ```bash openclaw plugins install ./path/to/local/acpx-plugin ``` -Потім перевірте стан бекенда: +Після цього перевірте стан бекенду: ```text /acp doctor ``` -### Конфігурація команди та версії acpx +### Конфігурація команди й версії acpx -Типово комплектний плагін бекенда acpx (`acpx`) використовує локальний у плагіні закріплений бінарник: +За замовчуванням вбудований плагін бекенду acpx (`acpx`) використовує локальний закріплений бінарний файл плагіна: -1. Команда типово вказує на локальний у плагіні `node_modules/.bin/acpx` всередині пакета плагіна ACPX. -2. Очікувана версія типово дорівнює pin розширення. -3. Під час запуску OpenClaw негайно реєструє бекенд ACP як not-ready. -4. Фонове ensure-завдання перевіряє `acpx --version`. -5. Якщо локальний у плагіні бінарник відсутній або не збігається, виконується: +1. За замовчуванням команда вказує на локальний `node_modules/.bin/acpx` усередині пакета плагіна ACPX. +2. Очікувана версія за замовчуванням відповідає закріпленню розширення. +3. Під час запуску реєстрація бекенду ACP одразу позначається як not-ready. +4. Фонове завдання ensure перевіряє `acpx --version`. +5. Якщо локальний бінарний файл плагіна відсутній або не збігається за версією, виконується: `npm install --omit=dev --no-save acpx@` і повторна перевірка. Ви можете перевизначити команду/версію в конфігурації плагіна: @@ -733,27 +732,27 @@ openclaw plugins install ./path/to/local/acpx-plugin Примітки: - `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`). -- Відносні шляхи обчислюються від каталогу workspace OpenClaw. -- `expectedVersion: "any"` вимикає сувору перевірку збігу версії. -- Коли `command` вказує на кастомний бінарник/шлях, автоматичне локальне встановлення в плагіні вимикається. -- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенда. +- Відносні шляхи визначаються від директорії робочого простору OpenClaw. +- `expectedVersion: "any"` вимикає сувору перевірку відповідності версії. +- Коли `command` вказує на користувацький бінарний файл/шлях, автоматичне локальне встановлення плагіна вимикається. +- Запуск OpenClaw залишається неблокувальним, поки триває фонова перевірка стану бекенду. -Див. [Плагіни](/tools/plugin). +Див. [Плагіни](/uk/tools/plugin). ### Автоматичне встановлення залежностей -Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx -(платформозалежні бінарники) встановлюються автоматично -через postinstall-хук. Якщо автоматичне встановлення не вдається, gateway однаково запускається -нормально та повідомляє про відсутню залежність через `openclaw acp doctor`. +Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності +середовища виконання acpx (платформозалежні бінарні файли) встановлюються автоматично +через хук postinstall. Якщо автоматичне встановлення завершується помилкою, gateway все одно запускається +нормально і повідомляє про відсутню залежність через `openclaw acp doctor`. -### MCP-міст для інструментів плагінів +### MCP-міст інструментів плагіна -Типово сесії ACPX **не** експонують зареєстровані в плагінах OpenClaw інструменти до -ACP-harness. +За замовчуванням сеанси ACPX **не** відкривають зареєстровані плагінами OpenClaw інструменти +для ACP-harness-оточення. Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені -інструменти плагінів OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст: +інструменти плагінів OpenClaw, такі як збереження/отримання пам’яті, увімкніть спеціальний міст: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true @@ -761,49 +760,50 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Що це робить: -- Інжектує в bootstrap сесії ACPX вбудований MCP-сервер з іменем `openclaw-plugin-tools`. -- Експонує інструменти плагінів, уже зареєстровані встановленими та увімкненими плагінами OpenClaw. -- Робить функцію явно ввімкненою та типово вимкненою. +- Вбудовує в bootstrap сеансу ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`. +- Відкриває інструменти плагінів, уже зареєстровані встановленими та ввімкненими + плагінами OpenClaw. +- Робить цю функцію явною і вимкненою за замовчуванням. Примітки щодо безпеки й довіри: -- Це розширює поверхню інструментів ACP-harness. -- ACP-агенти отримують доступ лише до інструментів плагінів, уже активних у gateway. +- Це розширює поверхню інструментів ACP-harness-оточення. +- ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway. - Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися - в самому OpenClaw. -- Перегляньте встановлені плагіни перед увімкненням цього. + у самому OpenClaw. +- Перевіряйте встановлені плагіни перед увімкненням цієї функції. -Кастомні `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools — -це додаткова зручність за явною згодою, а не заміна узагальненої конфігурації MCP-серверів. +Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст інструментів плагінів є +додатковою зручною функцією за явним увімкненням, а не заміною загальної конфігурації MCP-сервера. -## Налаштування дозволів +## Конфігурація дозволів -ACP-сесії працюють неінтерактивно — немає TTY, у якому можна схвалювати або відхиляти запити на дозвіл на запис файлів і виконання shell-команд. Плагін acpx надає два ключі конфігурації, які визначають, як обробляються дозволи: +Сеанси ACP працюють неінтерактивно — TTY для схвалення або відхилення запитів дозволів на запис у файли й виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів: -Ці дозволи ACPX-harness відокремлені від схвалень exec в OpenClaw і від окремих прапорців обходу на боці CLI-бекенда, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для ACP-сесій. +Ці дозволи harness ACPX відокремлені від схвалень exec в OpenClaw і відокремлені від прапорців обходу постачальника в бекендах CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP. ### `permissionMode` Керує тим, які операції агент harness може виконувати без запиту. -| Значення | Поведінка | -| --------------- | ---------------------------------------------------------- | -| `approve-all` | Автоматично схвалювати всі записи файлів і shell-команди. | -| `approve-reads` | Автоматично схвалювати лише читання; запис і exec вимагають запитів. | -| `deny-all` | Відхиляти всі запити на дозвіл. | +| Значення | Поведінка | +| --------------- | -------------------------------------------------------- | +| `approve-all` | Автоматично схвалює всі записи у файли та shell-команди. | +| `approve-reads` | Автоматично схвалює лише читання; запис і exec вимагають запитів. | +| `deny-all` | Відхиляє всі запити дозволів. | ### `nonInteractivePermissions` -Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (що для ACP-сесій відбувається завжди). +Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сеансів ACP це завжди так). -| Значення | Поведінка | -| -------- | ----------------------------------------------------------------- | -| `fail` | Перервати сесію з `AcpRuntimeError`. **(типово)** | -| `deny` | Мовчки відхилити дозвіл і продовжити (плавна деградація). | +| Значення | Поведінка | +| -------- | ---------------------------------------------------------------- | +| `fail` | Перервати сеанс з `AcpRuntimeError`. **(за замовчуванням)** | +| `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). | ### Конфігурація -Установлюється через конфігурацію плагіна: +Налаштовується через конфігурацію плагіна: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all @@ -812,27 +812,27 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail Після зміни цих значень перезапустіть 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)` | Dispatch із нормальних повідомлень треда вимкнено. | Установіть `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 ...` | Runtime ACP працює на боці хоста; сесія-запитувач ізольована. | Використовуйте `runtime="subagent"` з ізольованих сесій або запускайте ACP зі сесії без sandbox. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової ізоляції або 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). | -| 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`; вручну завершіть завислі процеси. | +| Симптом | Імовірна причина | Виправлення | +| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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`; вручну завершіть завислі процеси. |