From 694810bc95e07f0110a6c984bcde90f0abd67b7f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 20:16:54 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/automation/tasks.md | 238 +++--- docs/uk/channels/telegram.md | 420 +++++------ docs/uk/ci.md | 399 +++++----- docs/uk/cli/infer.md | 139 ++-- docs/uk/concepts/agent-loop.md | 205 +++--- docs/uk/concepts/queue.md | 74 +- docs/uk/gateway/protocol.md | 572 +++++++-------- docs/uk/gateway/security/index.md | 938 ++++++++++++------------ docs/uk/plugins/sdk-migration.md | 741 +++++++++---------- docs/uk/plugins/sdk-overview.md | 354 ++++----- docs/uk/plugins/sdk-subpaths.md | 507 ++++++------- docs/uk/reference/transcript-hygiene.md | 202 ++--- docs/uk/start/bootstrapping.md | 43 +- docs/uk/tools/acp-agents.md | 741 +++++++++---------- 14 files changed, 2785 insertions(+), 2788 deletions(-) diff --git a/docs/uk/automation/tasks.md b/docs/uk/automation/tasks.md index fc8bac303..2a70a7ed3 100644 --- a/docs/uk/automation/tasks.md +++ b/docs/uk/automation/tasks.md @@ -1,16 +1,16 @@ --- read_when: - - Перегляд фонової роботи, що триває або нещодавно завершилася - - Налагодження збоїв доставки для відокремлених запусків агентів + - Перегляд фонової роботи, що виконується або нещодавно завершилася + - Налагодження збоїв доставки для від’єднаних запусків агентів - Розуміння того, як фонові запуски пов’язані із сеансами, Cron і Heartbeat sidebarTitle: Background tasks -summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron і операцій CLI +summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron та операцій CLI title: Фонові завдання x-i18n: - generated_at: "2026-04-28T11:04:13Z" + generated_at: "2026-04-28T20:11:28Z" model: gpt-5.5 provider: openai - source_hash: 54843ab3831dceb3df810a17dbe97e2824d99bae2233291a70f52aca168778b4 + source_hash: ff4f22f98148b01c1b044a5213a5946eac8c5d763f0d22c992e6a4a2297bc308 source_path: automation/tasks.md workflow: 16 --- @@ -19,35 +19,35 @@ x-i18n: Шукаєте планування? Див. [Автоматизація та завдання](/uk/automation), щоб вибрати правильний механізм. Ця сторінка є журналом активності для фонової роботи, а не планувальником. -Фонові завдання відстежують роботу, що виконується **поза вашим основним сеансом розмови**: запуски ACP, створення субагентів, ізольовані виконання cron-завдань і операції, ініційовані з CLI. +Фонові завдання відстежують роботу, яка виконується **поза основним сеансом розмови**: запуски ACP, створення субагентів, ізольовані виконання завдань cron і операції, ініційовані CLI. -Завдання **не** замінюють сеанси, cron-завдання чи Heartbeat — вони є **журналом активності**, який записує, яка відокремлена робота відбулася, коли саме та чи завершилася вона успішно. +Завдання **не** замінюють сеанси, завдання cron чи heartbeats — вони є **журналом активності**, який записує, яка відокремлена робота відбулася, коли саме та чи була вона успішною. -Не кожен запуск агента створює завдання. Ходи Heartbeat і звичайний інтерактивний чат не створюють. Усі виконання cron, створення ACP, створення субагентів і агентні команди CLI створюють. +Не кожен запуск агента створює завдання. Heartbeat-ходи та звичайний інтерактивний чат цього не роблять. Усі виконання cron, створення ACP, створення субагентів і команди агента CLI створюють завдання. -## TL;DR +## Коротко -- Завдання — це **записи**, а не планувальники — cron і Heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_. -- ACP, субагенти, усі cron-завдання й операції CLI створюють завдання. Ходи Heartbeat не створюють. +- Завдання — це **записи**, а не планувальники: cron і heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_. +- ACP, субагенти, усі завдання cron і операції CLI створюють завдання. Heartbeat-ходи цього не роблять. - Кожне завдання проходить через `queued → running → terminal` (succeeded, failed, timed_out, cancelled або lost). -- Cron-завдання залишаються активними, доки середовище виконання cron усе ще володіє завданням; якщо - стан середовища виконання в пам’яті зник, супровід завдань спершу перевіряє стійку історію запусків cron, - перш ніж позначити завдання як lost. -- Завершення керується push-механізмом: відокремлена робота може сповістити напряму або пробудити - сеанс запитувача/Heartbeat після завершення, тому цикли опитування статусу +- Завдання Cron залишаються активними, доки середовище виконання cron усе ще володіє завданням; якщо + стан середовища виконання в пам’яті зник, обслуговування завдань спершу перевіряє збережену історію запусків cron, + перш ніж позначити завдання як втрачене. +- Завершення працює через push: відокремлена робота може сповіщати напряму або пробуджувати + сеанс/heartbeat запитувача після завершення, тому цикли опитування статусу зазвичай мають неправильну форму. -- Ізольовані запуски cron і завершення субагентів докладають максимальних зусиль, щоб очистити відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням. -- Ізольована доставка cron пригнічує застарілі проміжні відповіді батьківського сеансу, доки робота нащадкових субагентів ще завершується, і віддає перевагу фінальному виводу нащадка, якщо він надходить до доставки. -- Сповіщення про завершення доставляються напряму в канал або ставляться в чергу для наступного Heartbeat. +- Ізольовані запуски cron і завершення субагентів за можливості очищають відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням. +- Ізольована доставка cron пригнічує застарілі проміжні відповіді батьківського сеансу, поки робота нащадків-субагентів ще завершується, і надає перевагу фінальному виводу нащадка, якщо він надходить до доставки. +- Сповіщення про завершення доставляються напряму в канал або ставляться в чергу до наступного heartbeat. - `openclaw tasks list` показує всі завдання; `openclaw tasks audit` виявляє проблеми. -- Термінальні записи зберігаються 7 днів, а потім автоматично видаляються. +- Термінальні записи зберігаються 7 днів, а потім автоматично очищаються. ## Швидкий старт - + ```bash # List all tasks (newest first) openclaw tasks list @@ -58,13 +58,13 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -74,7 +74,7 @@ x-i18n: ``` - + ```bash # Run a health audit openclaw tasks audit @@ -85,7 +85,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -97,26 +97,26 @@ x-i18n: ## Що створює завдання -| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень | +| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` | +| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` | | Оркестрація субагентів | `subagent` | Створення субагента через `sessions_spawn` | `done_only` | -| Cron-завдання (усі типи) | `cron` | Кожне виконання cron (основний сеанс та ізольоване) | `silent` | -| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через gateway | `silent` | -| Медіазавдання агента | `cli` | Запуски `video_generate`, підтримані сеансом | `silent` | +| Завдання Cron (усі типи) | `cron` | Кожне виконання cron (у головному сеансі та ізольоване) | `silent` | +| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через Gateway | `silent` | +| Медіазавдання агента | `cli` | Запуски `video_generate`, прив’язані до сеансу | `silent` | - - Cron-завдання основного сеансу за замовчуванням використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщень. Ізольовані cron-завдання також за замовчуванням використовують `silent`, але вони помітніші, бо виконуються у власному сеансі. + + Завдання cron у головному сеансі типово використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщень. Ізольовані завдання cron також типово мають `silent`, але є помітнішими, оскільки виконуються у власному сеансі. - Запуски `video_generate`, підтримані сеансом, також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг сам написати подальше повідомлення й прикріпити готове відео. Якщо ви вмикаєте `tools.media.asyncCompletion.directSend`, асинхронні завершення `music_generate` і `video_generate` спершу намагаються виконати пряму доставку в канал, перш ніж повернутися до шляху пробудження сеансу запитувача. + Запуски `video_generate`, прив’язані до сеансу, також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг сам написати наступне повідомлення й прикріпити готове відео. Якщо ввімкнути `tools.media.asyncCompletion.directSend`, асинхронні завершення `music_generate` і `video_generate` спершу намагаються доставити результат напряму в канал, перш ніж перейти до шляху пробудження сеансу запитувача. - - Доки завдання `video_generate`, підтримане сеансом, усе ще активне, інструмент також працює як запобіжник: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другої паралельної генерації. Використовуйте `action: "status"`, коли потрібен явний запит прогресу/статусу з боку агента. + + Поки завдання `video_generate`, прив’язане до сеансу, ще активне, інструмент також діє як запобіжник: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другої паралельної генерації. Використовуйте `action: "status"`, коли потрібен явний запит прогресу/статусу з боку агента. - - - Ходи Heartbeat — основний сеанс; див. [Heartbeat](/uk/gateway/heartbeat) + + - Heartbeat-ходи — у головному сеансі; див. [Heartbeat](/uk/gateway/heartbeat) - Звичайні інтерактивні ходи чату - Прямі відповіді `/command` @@ -137,13 +137,13 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| Статус | Що це означає | +| Статус | Що це означає | | ----------- | -------------------------------------------------------------------------- | | `queued` | Створено, очікує запуску агента | | `running` | Хід агента активно виконується | | `succeeded` | Успішно завершено | | `failed` | Завершено з помилкою | -| `timed_out` | Перевищено налаштований тайм-аут | +| `timed_out` | Перевищено налаштований час очікування | | `cancelled` | Зупинено оператором через `openclaw tasks cancel` | | `lost` | Середовище виконання втратило авторитетний базовий стан після 5-хвилинного пільгового періоду | @@ -151,32 +151,32 @@ stateDiagram-v2 Завершення запуску агента є авторитетним для активних записів завдань. Успішний відокремлений запуск фіналізується як `succeeded`, звичайні помилки запуску фіналізуються як `failed`, а результати тайм-ауту або переривання фіналізуються як `timed_out`. Якщо оператор уже скасував завдання або середовище виконання вже записало сильніший термінальний стан, як-от `failed`, `timed_out` чи `lost`, пізніший сигнал успіху не знижує цей термінальний статус. -`lost` залежить від середовища виконання: +`lost` враховує середовище виконання: - Завдання ACP: зникли метадані базового дочірнього сеансу ACP. - Завдання субагентів: базовий дочірній сеанс зник зі сховища цільового агента. -- Cron-завдання: середовище виконання cron більше не відстежує завдання як активне, а стійка +- Завдання Cron: середовище виконання cron більше не відстежує завдання як активне, а збережена історія запусків cron не показує термінального результату для цього запуску. Офлайн-аудит CLI - не вважає власний порожній внутрішньопроцесний стан середовища виконання cron авторитетним. -- Завдання CLI: ізольовані завдання дочірніх сеансів використовують дочірній сеанс; підтримані чатом - завдання CLI натомість використовують живий контекст запуску, тому залишкові - рядки сеансів каналу/групи/особистого чату не підтримують їх активними. Запуски - `openclaw agent`, підтримані Gateway, також фіналізуються за результатом свого запуску, тому завершені запуски + не вважає власний порожній стан cron у процесі авторитетним. +- Завдання CLI: ізольовані завдання дочірнього сеансу використовують дочірній сеанс; завдання CLI, + прив’язані до чату, натомість використовують живий контекст запуску, тому тривалі рядки + сеансів каналу/групи/приватного чату не підтримують їх активними. Запуски + `openclaw agent`, прив’язані до Gateway, також фіналізуються за результатом запуску, тому завершені запуски не залишаються активними, доки прибиральник не позначить їх як `lost`. ## Доставка та сповіщення Коли завдання досягає термінального стану, OpenClaw сповіщає вас. Є два шляхи доставки: -**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надсилається прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень субагентів OpenClaw також зберігає прив’язану маршрутизацію гілки/теми, коли вона доступна, і може заповнити відсутні `to` / обліковий запис зі збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки. +**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надсилається прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень субагентів OpenClaw також зберігає прив’язану маршрутизацію thread/topic, коли вона доступна, і може заповнити відсутнє `to` / обліковий запис зі збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки. -**Доставка через чергу сеансу** — якщо пряма доставка не вдається або джерело не задане, оновлення ставиться в чергу як системна подія в сеансі запитувача й з’являється під час наступного Heartbeat. +**Доставка через чергу сеансу** — якщо пряма доставка не вдається або origin не задано, оновлення ставиться в чергу як системна подія в сеансі запитувача й з’являється під час наступного heartbeat. -Завершення завдання запускає негайне пробудження Heartbeat, тож ви швидко бачите результат — вам не потрібно чекати наступного запланованого такту Heartbeat. +Завершення завдання запускає негайне пробудження heartbeat, тож ви швидко бачите результат — не потрібно чекати наступного запланованого heartbeat-тику. -Це означає, що звичний робочий процес є push-орієнтованим: запустіть відокремлену роботу один раз, а потім дозвольте середовищу виконання пробудити вас або сповістити після завершення. Опитуйте стан завдання лише тоді, коли потрібні налагодження, втручання або явний аудит. +Це означає, що звичний робочий процес є push-орієнтованим: один раз запустіть відокремлену роботу, а потім дозвольте середовищу виконання пробудити вас або сповістити про завершення. Опитуйте стан завдання лише тоді, коли потрібні налагодження, втручання або явний аудит. ### Політики сповіщень @@ -184,11 +184,11 @@ stateDiagram-v2 | Політика | Що доставляється | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (типово) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** | -| `state_changes` | Кожен перехід стану та оновлення прогресу | -| `silent` | Нічого | +| `done_only` (типово) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** | +| `state_changes` | Кожен перехід стану й оновлення прогресу | +| `silent` | Узагалі нічого | -Змініть політику, доки завдання виконується: +Змініть політику, поки завдання виконується: ```bash openclaw tasks notify state_changes @@ -202,7 +202,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - Стовпці виводу: ID завдання, вид, статус, доставка, ID запуску, дочірній сеанс, зведення. + Стовпці виводу: ID завдання, тип, статус, доставка, ID запуску, дочірній сеанс, підсумок. @@ -210,7 +210,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - Токен пошуку приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, зокрема час, стан доставки, помилку та термінальне зведення. + Токен lookup приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, зокрема час, стан доставки, помилку й термінальний підсумок. @@ -218,7 +218,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - Для завдань ACP і субагентів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дескриптора дочірнього середовища виконання немає). Статус переходить у `cancelled`, а сповіщення про доставку надсилається, коли це застосовно. + Для завдань ACP і субагентів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дескриптора дочірнього середовища виконання немає). Статус переходить у `cancelled`, і за потреби надсилається сповіщення про доставку. @@ -231,64 +231,64 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - Виявляє операційні проблеми. Знахідки також з’являються в `openclaw status`, коли виявлено проблеми. + Виявляє операційні проблеми. Знахідки також з’являються в `openclaw status`, коли проблеми виявлено. - | Знахідка | Серйозність | Тригер | - | ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | - | `stale_queued` | warn | У черзі понад 10 хвилин | - | `stale_running` | error | Виконується понад 30 хвилин | - | `lost` | warn/error | Власність над задачею, підтримана середовищем виконання, зникла; збережені втрачені задачі попереджають до `cleanupAfter`, потім стають помилками | - | `delivery_failed` | warn | Доставка не вдалася, а політика сповіщень не `silent` | - | `missing_cleanup` | warn | Завершальна задача без позначки часу очищення | - | `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершено до початку) | + | Виявлення | Серйозність | Тригер | + | ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | + | `stale_queued` | warn | У черзі понад 10 хвилин | + | `stale_running` | error | Виконується понад 30 хвилин | + | `lost` | warn/error | Власність над завданням із підтримкою runtime зникла; збережені втрачені завдання попереджають до `cleanupAfter`, потім стають помилками | + | `delivery_failed` | warn | Доставка не вдалася, а політика сповіщень не є `silent` | + | `missing_cleanup` | warn | Термінальне завдання без часової позначки очищення | + | `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершилося до початку) | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - Використовуйте це, щоб попередньо переглянути або застосувати узгодження, проставлення позначок очищення та скорочення для задач і стану Task Flow. + Використовуйте це, щоб переглянути або застосувати звірення, проставлення очищення та обрізання для завдань і стану Task Flow. - Узгодження враховує середовище виконання: + Звірення враховує runtime: - - Задачі ACP/субагентів перевіряють свій базовий дочірній сеанс. - - Задачі Cron перевіряють, чи середовище виконання cron досі володіє завданням, а потім відновлюють завершальний статус зі збережених журналів запусків cron/стану завдання, перш ніж повертатися до `lost`. Лише процес Gateway є авторитетним для набору активних завдань cron у пам’яті; офлайн-аудит CLI використовує довговічну історію, але не позначає задачу cron втраченою лише тому, що цей локальний Set порожній. - - Задачі CLI, підтримані чатом, перевіряють живий контекст запуску власника, а не лише рядок сеансу чату. + - Завдання ACP/subagent перевіряють свою дочірню сесію, що їх підтримує. + - Завдання Cron перевіряють, чи cron runtime досі володіє завданням, потім відновлюють термінальний статус зі збережених журналів запусків cron/стану завдання, перш ніж перейти до `lost`. Лише процес Gateway є авторитетним для набору активних завдань cron у пам’яті; офлайн-аудит CLI використовує довговічну історію, але не позначає завдання cron як втрачене лише тому, що цей локальний Set порожній. + - CLI-завдання з підтримкою чату перевіряють власний контекст живого запуску, а не лише рядок сесії чату. - Очищення після завершення також враховує середовище виконання: + Очищення після завершення також враховує runtime: - - Завершення субагента найкращими зусиллями закриває відстежувані вкладки браузера/процеси для дочірнього сеансу перед продовженням оголошеного очищення. - - Завершення ізольованого cron найкращими зусиллями закриває відстежувані вкладки браузера/процеси для сеансу cron перед повним згортанням запуску. - - Доставка ізольованого cron за потреби очікує подальшу дію нащадкового субагента та пригнічує застарілий текст підтвердження батьківської задачі замість його оголошення. - - Доставка завершення субагента віддає перевагу найновішому видимому тексту асистента; якщо він порожній, вона повертається до очищеного найновішого тексту tool/toolResult, а запуски викликів інструментів лише з тайм-аутом можуть згортатися до короткого підсумку часткового прогресу. Завершальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді. - - Помилки очищення не маскують реальний результат задачі. + - Завершення subagent за принципом найкращого зусилля закриває відстежувані вкладки браузера/процеси для дочірньої сесії перед тим, як продовжиться очищення оголошення. + - Завершення ізольованого cron за принципом найкращого зусилля закриває відстежувані вкладки браузера/процеси для сесії cron перед повним завершенням запуску. + - Доставка ізольованого cron за потреби очікує подальшу дію нащадка subagent і пригнічує застарілий текст підтвердження батьківського елемента замість його оголошення. + - Доставка завершення subagent віддає перевагу найновішому видимому тексту асистента; якщо він порожній, вона повертається до очищеного найновішого тексту tool/toolResult, а запуски викликів інструментів лише з тайм-аутом можуть згортатися до короткого підсумку часткового прогресу. Термінальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді. + - Помилки очищення не приховують справжній результат завдання. - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - Використовуйте їх, коли вас цікавить оркеструвальний Task Flow, а не один окремий запис фонової задачі. + Використовуйте ці команди, коли вас цікавить оркеструвальний Task Flow, а не один окремий запис фонового завдання. -## Дошка задач чату (`/tasks`) +## Дошка завдань у чаті (`/tasks`) -Використовуйте `/tasks` у будь-якому сеансі чату, щоб побачити фонові задачі, пов’язані з цим сеансом. Дошка показує активні та нещодавно завершені задачі із середовищем виконання, статусом, часом і прогресом або деталями помилки. +Використовуйте `/tasks` у будь-якій чат-сесії, щоб побачити фонові завдання, пов’язані з цією сесією. Дошка показує активні й нещодавно завершені завдання з runtime, статусом, часом, а також деталями прогресу або помилки. -Коли поточний сеанс не має видимих пов’язаних задач, `/tasks` повертається до локальних для агента лічильників задач, тож ви все одно отримуєте огляд без розкриття деталей інших сеансів. +Коли поточна сесія не має видимих пов’язаних завдань, `/tasks` повертається до локальних для агента лічильників завдань, щоб ви все одно отримали огляд без витоку деталей інших сесій. Для повного операторського журналу використовуйте CLI: `openclaw tasks list`. -## Інтеграція статусу (навантаження задач) +## Інтеграція статусу (навантаження завдань) -`openclaw status` містить короткий підсумок задач: +`openclaw status` містить стислий підсумок завдань: ``` Tasks: 3 queued · 2 running · 1 issues @@ -296,79 +296,81 @@ Tasks: 3 queued · 2 running · 1 issues Підсумок повідомляє: -- **active** — кількість `queued` + `running` -- **failures** — кількість `failed` + `timed_out` + `lost` -- **byRuntime** — розподіл за `acp`, `subagent`, `cron`, `cli` +- **активні** — кількість `queued` + `running` +- **помилки** — кількість `failed` + `timed_out` + `lost` +- **заRuntime** — розбивка за `acp`, `subagent`, `cron`, `cli` -І `/status`, і інструмент `session_status` використовують знімок задач, що враховує очищення: активні задачі мають пріоритет, застарілі завершені рядки приховуються, а нещодавні помилки показуються лише тоді, коли не залишилося активної роботи. Це утримує картку статусу сфокусованою на тому, що важливо зараз. +І `/status`, і інструмент `session_status` використовують знімок завдань із урахуванням очищення: активні завдання мають пріоритет, застарілі завершені рядки приховуються, а нещодавні помилки показуються лише тоді, коли не залишилося активної роботи. Це утримує картку статусу зосередженою на тому, що важливо зараз. -## Зберігання та обслуговування +## Сховище та обслуговування -### Де зберігаються задачі +### Де зберігаються завдання -Записи задач зберігаються в SQLite за адресою: +Записи завдань зберігаються в SQLite за адресою: ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -Реєстр завантажується в пам’ять під час запуску Gateway і синхронізує записи з SQLite для довговічності між перезапусками. -Gateway утримує журнал попереднього запису SQLite обмеженим, використовуючи стандартний поріг -autocheckpoint SQLite, а також періодичні контрольні точки `TRUNCATE` і контрольні точки під час завершення роботи. +Реєстр завантажується в пам’ять під час запуску gateway і синхронізує записи в SQLite для довговічності між перезапусками. +Gateway утримує журнал попереднього запису SQLite в обмежених межах за допомогою стандартного порога autocheckpoint SQLite, а також періодичних і завершальних контрольних точок `TRUNCATE`. ### Автоматичне обслуговування -Очищувач запускається кожні **60 секунд** і виконує три речі: +Очищувач запускається кожні **60 секунд** і виконує чотири дії: - - Перевіряє, чи активні задачі досі мають авторитетну підтримку середовища виконання. Задачі ACP/субагентів використовують стан дочірнього сеансу, задачі cron використовують власність активного завдання, а задачі CLI, підтримані чатом, використовують контекст запуску власника. Якщо цей базовий стан відсутній понад 5 хвилин, задачу позначають як `lost`. + + Перевіряє, чи активні завдання досі мають авторитетну підтримку runtime. Завдання ACP/subagent використовують стан дочірньої сесії, завдання cron використовують власність активного завдання, а CLI-завдання з підтримкою чату використовують власний контекст запуску. Якщо цей стан підтримки відсутній понад 5 хвилин, завдання позначається як `lost`. - - Встановлює позначку часу `cleanupAfter` для завершальних задач (endedAt + 7 днів). Під час утримання втрачені задачі все ще відображаються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони є помилками. + + Закриває термінальні одноразові сесії ACP, якими володіє батьківський елемент, і закриває застарілі термінальні постійні сесії ACP лише тоді, коли не залишається активної прив’язки розмови. - + + Встановлює часову позначку `cleanupAfter` для термінальних завдань (endedAt + 7 днів). Протягом утримання втрачені завдання все ще з’являються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони є помилками. + + Видаляє записи після їхньої дати `cleanupAfter`. -**Утримання:** записи завершальних задач зберігаються **7 днів**, а потім автоматично скорочуються. Налаштування не потрібне. +**Утримання:** записи термінальних завдань зберігаються **7 днів**, а потім автоматично обрізаються. Налаштування не потрібне. -## Як задачі пов’язані з іншими системами +## Як завдання пов’язані з іншими системами - - [Task Flow](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими задачами. Один потік може координувати кілька задач протягом свого життєвого циклу, використовуючи керовані або дзеркальні режими синхронізації. Використовуйте `openclaw tasks`, щоб перевіряти окремі записи задач, і `openclaw tasks flow`, щоб перевіряти оркеструвальний потік. + + [Task Flow](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими завданнями. Один потік може координувати кілька завдань протягом свого життєвого циклу, використовуючи керовані або дзеркальні режими синхронізації. Використовуйте `openclaw tasks`, щоб перевіряти окремі записи завдань, і `openclaw tasks flow`, щоб перевіряти оркеструвальний потік. Докладніше див. у [Task Flow](/uk/automation/taskflow). - - **Визначення** завдання cron зберігається в `~/.openclaw/cron/jobs.json`; стан виконання середовища виконання зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис задачі — і основного сеансу, і ізольований. Задачі cron основного сеансу за замовчуванням мають політику сповіщень `silent`, тож вони відстежуються без створення сповіщень. + + **Визначення** завдання cron зберігається в `~/.openclaw/cron/jobs.json`; стан виконання runtime зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис завдання — як основної сесії, так і ізольованої. Завдання cron основної сесії за замовчуванням використовують політику сповіщень `silent`, тому вони відстежуються без створення сповіщень. Див. [Завдання Cron](/uk/automation/cron-jobs). - - Запуски Heartbeat є ходами основного сеансу — вони не створюють записів задач. Коли задача завершується, вона може спричинити пробудження Heartbeat, щоб ви швидко побачили результат. + + Запуски Heartbeat є ходами основної сесії — вони не створюють записів завдань. Коли завдання завершується, воно може запустити пробудження Heartbeat, щоб ви швидко побачили результат. Див. [Heartbeat](/uk/gateway/heartbeat). - - Задача може посилатися на `childSessionKey` (де виконується робота) і `requesterSessionKey` (хто її запустив). Сеанси — це контекст розмови; задачі — це відстеження активності поверх нього. + + Завдання може посилатися на `childSessionKey` (де виконується робота) і `requesterSessionKey` (хто його запустив). Сесії є контекстом розмови; завдання — це відстеження активності поверх нього. - - `runId` задачі пов’язує її із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус задачі — вам не потрібно керувати життєвим циклом вручну. + + `runId` завдання пов’язує його із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус завдання — вам не потрібно керувати життєвим циклом вручну. ## Пов’язане -- [Автоматизація та задачі](/uk/automation) — усі механізми автоматизації одним поглядом -- [CLI: Задачі](/uk/cli/tasks) — довідник команд CLI -- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основного сеансу -- [Заплановані задачі](/uk/automation/cron-jobs) — планування фонової роботи -- [Task Flow](/uk/automation/taskflow) — оркестрація потоків над задачами +- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації стисло +- [CLI: Завдання](/uk/cli/tasks) — довідник команд CLI +- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії +- [Заплановані завдання](/uk/automation/cron-jobs) — планування фонової роботи +- [Task Flow](/uk/automation/taskflow) — оркестрація потоків над завданнями diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 6a63318e2..edc8246a3 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Стан підтримки, можливості та конфігурація бота Telegram +summary: Стан підтримки бота Telegram, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-04-28T19:31:37Z" + generated_at: "2026-04-28T20:11:05Z" model: gpt-5.5 provider: openai - source_hash: dadd8d0a735b8d8ee75eb44ad0ce018f81c6774aee3bd69f0804e9e731352546 + source_hash: 663fd2eecc7f2ff02622f5fde1a6ae3c97427f7aeda26f89a230529f3284df8b source_path: channels/telegram.md workflow: 16 --- -Готово для продакшну для особистих повідомлень бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook є необов’язковим. +Готовий до production для DM бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий. - Стандартна політика особистих повідомлень для Telegram — сполучення. + Політика DM за замовчуванням для Telegram — сполучення. - - Міжканальна діагностика та сценарії відновлення. + + Міжканальна діагностика та інструкції з відновлення. Повні шаблони та приклади конфігурації каналів. @@ -30,13 +30,13 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я точно `@BotFather`). + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle саме `@BotFather`). - Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. + Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. - + ```json5 { @@ -51,12 +51,12 @@ x-i18n: } ``` - Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації або змінній середовища, потім запустіть gateway. + Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. - + ```bash openclaw gateway @@ -64,77 +64,79 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення спливають через 1 годину. + Коди сполучення діють 1 годину. - Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. -Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервною змінною середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. ## Налаштування на боці Telegram - - Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує те, які групові повідомлення вони отримують. + + Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі повідомлення групи, зробіть одне з такого: + Якщо бот має бачити всі групові повідомлення, або: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожну групу, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. - Статус адміністратора керується в налаштуваннях групи Telegram. + Статус адміністратора контролюється в налаштуваннях групи Telegram. - Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі. + Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. - - `/setjoingroups` для дозволу або заборони додавання до груп + - `/setjoingroups`, щоб дозволити/заборонити додавання до груп - `/setprivacy` для поведінки видимості в групах -## Керування доступом і активація +## Контроль доступу та активація - - `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: + + `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - `pairing` (за замовчуванням) - - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) - - `open` (потрібно, щоб `allowFrom` містив `"*"`) + - `allowlist` (потребує щонайменше одного ID відправника в `allowFrom`) + - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` + `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. - `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється валідацією конфігурації. + `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваша конфігурація містить записи allowlist виду `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (наскільки можливо; потрібен токен бота Telegram). - Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + Якщо ви оновилися і ваша конфігурація містить записи allowlist з `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram). + Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була стабільно збережена в конфігурації (а не залежала від попередніх схвалень сполучення). + Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення). - Поширена плутанина: схвалення сполучення для особистих повідомлень не означає «цей відправник авторизований всюди». - Сполучення надає доступ лише до особистих повідомлень. Авторизація відправників у групах усе ще береться з явних allowlist у конфігурації. - Якщо вам потрібно «мене авторизовано один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`. + Поширене непорозуміння: схвалення сполучення DM не означає «цей відправник авторизований усюди». + Сполучення надає доступ лише до DM. Авторизація відправника в групі все одно береться з явних allowlist у конфігурації. + Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Напишіть своєму боту в особисті повідомлення. + 1. Напишіть своєму боту в DM. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. @@ -149,10 +151,10 @@ curl "https://api.telegram.org/bot/getUpdates" - Разом застосовуються два елементи керування: + Два механізми застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - - конфігурації `groups` немає: + - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) @@ -162,15 +164,15 @@ curl "https://api.telegram.org/bot/getUpdates" - `allowlist` (за замовчуванням) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram повертається до `allowFrom`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправників. - Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень для особистих повідомлень. - Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи чи теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища сполучень. + Нечислові записи ігноруються для авторизації відправника. + Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM. + Сполучення лишається тільки для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до `allowFrom` у конфігурації, а не до сховища сполучень. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо середовища виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням відмовляє безпечно через `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -189,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретних користувачів в одній конкретній групі: + Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи: ```json5 { @@ -209,8 +211,8 @@ curl "https://api.telegram.org/bot/getUpdates" Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. - - Розміщуйте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - - Розміщуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. + - Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. @@ -227,12 +229,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд рівня сесії: + Перемикачі команд на рівні сесії: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для сталості використовуйте конфігурацію. + Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію. Приклад сталої конфігурації: @@ -250,29 +252,29 @@ curl "https://api.telegram.org/bot/getUpdates" Отримання ID групового чату: - - перешліть повідомлення групи до `@userinfobot` / `@getidsbot` - - або прочитайте `chat.id` з `openclaw logs --follow` - - або перегляньте `getUpdates` у Bot API + - переслати групове повідомлення до `@userinfobot` / `@getidsbot` + - або прочитати `chat.id` з `openclaw logs --follow` + - або перевірити `getUpdates` Bot API -## Поведінка середовища виконання +## Поведінка runtime -- Telegram належить процесу Gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб ізолювати теми. -- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують тему, і зберігає ID теми для відповідей. -- Довге опитування використовує runner grammY з послідовністю за чатом і темою. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`. -- Довге опитування захищене всередині кожного процесу Gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший Gateway OpenClaw, скрипт або зовнішній poller. -- Перезапуски сторожового механізму довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). +- Telegram належить процесу gateway. +- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та плейсхолдерами медіа. +- Групові сесії ізольовані за ID групи. Теми форумів додають `:topic:`, щоб ізолювати теми. +- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей. +- Довге опитування використовує grammY runner із послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній poller використовує той самий токен. +- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - прямі чати: повідомлення попереднього перегляду + `editMessageText` @@ -282,10 +284,10 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли потоковий попередній перегляд активний) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний streaming попереднього перегляду) + - застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень планування або підсумків патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram тримає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -302,39 +304,39 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставляти тільки фінальну відповідь: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу пригнічуються замість надсилання як окремі повідомлення «Працюємо...». Запити схвалення, медіавміст і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку лише фінальної відповіді: редагування попереднього перегляду Telegram вимкнені, а загальний шум інструментів/прогресу пригнічується замість надсилання як окремі повідомлення "Working...". Запити схвалення, медіа payloads і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. Для відповідей лише з текстом: - - короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима мітка часу Telegram відображала час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима мітка часу Telegram відображає час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіавмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, media payloads) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі. + Попередній streaming окремий від блокового streaming. Коли блоковий streaming явно ввімкнено для Telegram, OpenClaw пропускає попередній stream, щоб уникнути подвійного streaming. Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. - Потік міркувань лише для Telegram: + Stream reasoning лише для Telegram: - - `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерування - - фінальна відповідь надсилається без тексту міркувань + - `/reasoning stream` надсилає reasoning у живий попередній перегляд під час генерування + - фінальна відповідь надсилається без тексту reasoning - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Текст у стилі Markdown відтворюється як безпечний для Telegram HTML. + - Markdown-подібний текст рендериться у безпечний для Telegram HTML. - Сирий HTML від моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст. + - Якщо Telegram відхиляє розпарсений HTML, OpenClaw повторює надсилання як звичайний текст. - Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. + Попередні перегляди посилань увімкнено за замовчуванням, і їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. + + Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`. Типові значення нативних команд: @@ -360,44 +362,44 @@ curl "https://api.telegram.org/bot/getUpdates" - імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - власні команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються і записуються в журнал + - конфлікти/дублікати пропускаються й логуються Примітки: - власні команди є лише записами меню; вони не реалізують поведінку автоматично - - команди plugin/skill можуть працювати під час введення, навіть якщо їх не показано в меню Telegram + - команди plugin/skill усе ще можуть працювати, якщо їх ввести, навіть якщо вони не показані в меню Telegram - Якщо нативні команди вимкнені, вбудовані команди видаляються. Власні команди або команди Plugin можуть усе ще реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні команди/команди Plugin усе ще можуть реєструватися, якщо налаштовані. - Поширені помилки налаштування: + Типові помилки налаштування: - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд Plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`. - Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було задано як повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як помилка очищення Webhook. - - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані. + - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. - ### Команди сполучення пристрою (`device-pair` plugin) + ### Команди сполучення пристрою (Plugin `device-pair`) - Коли встановлено `device-pair` plugin: + Коли Plugin `device-pair` встановлено: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями дії) + 3. `/pair pending` перелічує запити, що очікують (зокрема role/scopes) 4. схваліть запит: - `/pair approve ` для явного схвалення - - `/pair approve`, коли є лише один очікуваний запит + - `/pair approve`, коли є лише один запит, що очікує - `/pair approve latest` для найновішого - Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області дії під власним префіксом ролі. + Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен primary node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є операторськими, все ще потрібні scopes під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області дії/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. + Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, role/scopes/public key), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Перед схваленням повторно запустіть `/pair pending`. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - - Налаштуйте область дії вбудованої клавіатури: + + Налаштуйте scope inline-клавіатури: ```json5 { @@ -429,7 +431,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Області дії: + Scopes: - `off` - `dm` @@ -437,7 +439,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` мапиться на `inlineButtons: "all"`. Приклад дії повідомлення: @@ -462,14 +464,14 @@ curl "https://api.telegram.org/bot/getUpdates" - - Дії інструмента Telegram включають: + + Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). @@ -480,17 +482,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` зараз увімкнено за замовчуванням, і вони не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги гілкування відповідей у згенерованому виводі: + + Telegram підтримує явні теги reply threading у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що запустило дію + - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -499,29 +501,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли гілкування відповідей увімкнене і вихідний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли reply threading увімкнено й доступний початковий текст або підпис Telegram, OpenClaw автоматично включає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + Примітка: `off` вимикає неявний reply threading. Явні теги `[[reply_to_*]]` усе ще враховуються. - + Форумні супергрупи: - ключі сесій тем додають `:topic:` - - відповіді та індикатор набору спрямовуються в гілку теми + - відповіді й індикація набору тексту спрямовуються в thread теми - шлях конфігурації теми: `channels.telegram.groups..topics.` Спеціальний випадок загальної теми (`threadId=1`): - - під час надсилання повідомлень `message_thread_id` не додається (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії набору тексту все одно містять `message_thread_id` + - надсилання повідомлень не включають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії набору тексту все одно включають `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` належить лише темі й не успадковується з типових налаштувань групи. + Наслідування тем: записи тем наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` застосовується лише до теми й не наслідується з типових значень групи. - **Маршрутизація агента за темами**: Кожну тему можна спрямувати до іншого агента, задавши `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агентів за темами**: кожна тема може спрямовуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад: ```json5 { @@ -541,26 +543,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійна прив’язка тем ACP**: Форумні теми можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із темою, наприклад `-1001234567890:topic:42`). Наразі обмежено форумними темами в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані ACP bindings верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та id з уточненням теми, як-от `-1001234567890:topic:42`). Наразі scoped до форумних тем у групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Створення ACP, прив’язане до гілки, із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; наступні повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Створення thread-bound ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової ACP-сесії; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесій, що враховують thread. - + ### Аудіоповідомлення - Telegram розрізняє голосові нотатки й аудіофайли. + Telegram розрізняє голосові нотатки та аудіофайли. - - типово: поведінка аудіофайлу + - за замовчуванням: поведінка аудіофайла - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований, - ненадійний текст; виявлення згадок усе одно використовує сирий - транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. + - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, + недовірений текст у контексті агента; виявлення згадок усе ще використовує сирий + транскрипт, тому voice-повідомлення з gate за згадкою продовжують працювати. Приклад дії повідомлення: @@ -576,7 +578,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли й відеонотатки. + Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: @@ -596,9 +598,9 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичні WEBP: завантажуються й обробляються (заповнювач ``) - - анімовані TGS: пропускаються - - відео WEBM: пропускаються + - статичний WEBP: завантажується й обробляється (placeholder ``) + - анімований TGS: пропускається + - відео WEBM: пропускається Поля контексту стікера: @@ -612,9 +614,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних vision-викликів. - Увімкнути дії зі стікерами: + Увімкніть дії зі стікерами: ```json5 { @@ -652,8 +654,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Реакції Telegram надходять як оновлення `message_reaction` (окремо від вмісту повідомлень). + + Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень). Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: @@ -661,35 +663,35 @@ curl "https://api.telegram.org/bot/getUpdates" Конфігурація: - - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) Примітки: - - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (наскільки можливо, через кеш надісланих повідомлень). - - Події реакцій усе одно дотримуються засобів контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає ідентифікатори гілок в оновленнях реакцій. - - нефорумні групи спрямовуються до сесії групового чату - - форумні групи спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень). + - Події реакцій усе ще поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ідентифікатори тем у оновленнях реакцій. + - групи без форуму маршрутизуються до сеансу групового чату + - групи-форуми маршрутизуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для polling/webhook автоматично містить `message_reaction`. + `allowed_updates` для polling/webhook автоматично включає `message_reaction`. - - `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. + + `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - запасний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode emoji (наприклад "👀"). - - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Telegram очікує unicode emoji (наприклад, "👀"). + - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. @@ -699,7 +701,7 @@ curl "https://api.telegram.org/bot/getUpdates" Записи, ініційовані Telegram, включають: - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - - `/config set` і `/config unset` (потребує ввімкнення команд) + - `/config set` і `/config unset` (потрібне ввімкнення команд) Вимкнення: @@ -715,29 +717,29 @@ curl "https://api.telegram.org/bot/getUpdates" - - За замовчуванням використовується довге опитування. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов'язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). + + За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив'язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло, перш ніж повернути `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/теми, що й довге опитування, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим Webhook перевіряє захист запитів, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, що й у long polling, тож повільні ходи агента не утримують delivery ACK Telegram. - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується значення grammY за замовчуванням). - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування. + - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується стандартне значення grammY). + - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання polling. - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається так, як отримано. - - allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - - Елементи керування історією DM: + - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. + - allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. + - конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Ціль надсилання CLI може бути числовим ID чату або іменем користувача: @@ -756,55 +758,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Прапорці опитування лише для Telegram: + Прапорці опитувань лише для Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для тем форуму (або використовуйте ціль `:topic:`) + - `--thread-id` для тем форуму (або використайте ціль `:topic:`) Надсилання Telegram також підтримує: - `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media + - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті + - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених завантажень фото або animated-media Обмеження дій: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування - - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим - - Telegram підтримує затвердження exec у DM затверджувачів і може додатково публікувати запити у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує підтвердження exec у DM затверджувачів і може додатково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача) - - `channels.telegram.execApprovals.approvers` (відступає до числових ID власників з `allowFrom` / `defaultTo`) + - `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `allowFrom` / `defaultTo`) - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` - `agentFilter`, `sessionFilter` - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту затвердження та подальшого повідомлення. Затвердження exec за замовчуванням спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту підтвердження та наступного повідомлення. Підтвердження exec за замовчуванням спливають через 30 хвилин. - Inline-кнопки затвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID затверджень із префіксом `plugin:` вирішуються через затвердження plugin; інші спершу вирішуються через затвердження exec. + Кнопки inline-підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` визначаються через підтвердження plugin; інші спочатку визначаються через підтвердження exec. - Див. [Затвердження exec](/uk/tools/exec-approvals). + Див. [Підтвердження exec](/uk/tools/exec-approvals). -## Елементи керування відповідями про помилки +## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації: | Ключ | Значення | За замовчуванням | Опис | | ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | | `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для облікового запису, групи та теми (те саме успадкування, що й для інших ключів конфігурації Telegram). +Підтримуються перевизначення для облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram). ```json5 { @@ -829,31 +831,31 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть і знову додайте бота до групи + - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - - швидкий тест сесії: `/activation always`. + - швидкий тест сеансу: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`) + - коли існує `channels.telegram.groups`, група має бути в списку (або включати `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте ідентичність відправника (pairing та/або числовий `allowFrom`) - - авторизація команд усе одно застосовується, навіть коли політика групи має значення `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menu - - `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми DNS/HTTPS-доступності до `api.telegram.org` + - авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`) + - авторизація команд усе ще застосовується, навіть коли політика групи — `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню + - `setMyCommands failed` із помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота. - Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням. @@ -861,13 +863,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - + - - Node 22+ + власний fetch/proxy може спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються. - - Деякі хости спершу вирішують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної long-poll liveness за замовчуванням. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`. + - Node 22+ + користувацький fetch/proxy може спричинити негайну поведінку abort, якщо типи AbortSignal не збігаються. + - Деякі хости спершу резолвлять `api.telegram.org` в IPv6; зламаний вихід IPv6 може спричиняти переривчасті збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання polling. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або виходу TLS між хостом і `api.telegram.org`. - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml @@ -888,9 +890,9 @@ channels: - Відповіді benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або - прозорий proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете явно - ввімкнути обхід лише для Telegram: + прозорий proxy переписує `api.telegram.org` на іншу + приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете увімкнути + обхід лише для Telegram: ```yaml channels: @@ -899,18 +901,18 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Таке саме явне ввімкнення доступне для кожного облікового запису за адресою + - Такий самий opt-in доступний для кожного облікового запису за адресою `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy вирішує хости медіа Telegram у `198.18.x.x`, спершу залиште - небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяє - benchmark-діапазон RFC 2544. + - Якщо ваш proxy резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон + RFC 2544 за замовчуванням. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram - media SSRF. Використовуйте це лише для довірених proxy-середовищ під контролем оператора, - таких як Clash, Mihomo або Surge fake-IP routing, коли вони - синтезують приватні або спеціального призначення відповіді поза benchmark- - діапазоном RFC 2544. Залишайте вимкненим для звичайного публічного доступу Telegram через інтернет. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram + від SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy + середовищ, як-от маршрутизація fake-IP Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціального призначення відповіді поза benchmark-діапазоном + RFC 2544. Залишайте вимкненим для звичайного публічного інтернет-доступу до Telegram. - Перевизначення середовища (тимчасові): @@ -927,23 +929,23 @@ dig +short api.telegram.org AAAA -Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting). +Додаткова допомога: [Усунення проблем із каналами](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + -- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`) +- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символьні посилання відхиляються) +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) - підтвердження виконання: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` -- потоки/відповіді: `replyToMode` -- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` +- гілки/відповіді: `replyToMode` +- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` @@ -953,7 +955,7 @@ dig +short api.telegram.org AAAA -Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, установіть `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане @@ -969,12 +971,12 @@ dig +short api.telegram.org AAAA Маршрутизуйте вхідні повідомлення до агентів. - Модель загроз і зміцнення захисту. + Модель загроз і посилення захисту. Зіставляйте групи й теми з агентами. - + Міжканальна діагностика. diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 44bf1d5e4..2d5ac01ac 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,131 +1,126 @@ --- read_when: - - Потрібно зрозуміти, чому завдання CI виконалося або не виконалося - - Ви налагоджуєте перевірки GitHub Actions, що не проходять -summary: Граф завдань CI, перевірки за областю дії та локальні еквіваленти команд -title: Конвеєр CI + - Вам потрібно зрозуміти, чому завдання CI виконалося або не виконалося + - Ви налагоджуєте перевірки GitHub Actions, які завершуються помилкою +summary: Граф завдань CI, шлюзи області дії та локальні еквіваленти команд +title: CI-конвеєр x-i18n: - generated_at: "2026-04-28T18:57:01Z" + generated_at: "2026-04-28T20:11:22Z" model: gpt-5.5 provider: openai - source_hash: 336906be783376409b7d36ae038ecb0e6c9cc25707d44d7d9bc19e5be17de2a0 + source_hash: 7f2d0e70d04530bd524e5556b3e2e3349be5f109a61ec5044e907d4ed19379eb source_path: ci.md workflow: 16 --- -CI запускається під час кожного push до `main` і кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли змінилися лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області й розгортають повний звичайний граф CI для реліз-кандидатів або широкої перевірки. +CI запускається для кожного push у `main` і кожного pull request. Вона використовує розумне звуження області, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне звуження області й розгортають повний звичайний граф CI для кандидатів на реліз або широкої валідації. -`Full Release Validation` — це ручний парасольковий workflow для "запустити все -перед релізом." Він приймає гілку, тег або повний SHA коміту, запускає ручний -workflow `CI` з цією ціллю та запускає `OpenClaw Release Checks` -для install smoke, package acceptance, Docker release-path наборів, live/E2E, -OpenWebUI, QA Lab parity, Matrix і Telegram lanes. Він також може запускати -post-publish workflow `NPM Telegram Beta E2E`, коли надано специфікацію -опублікованого пакета. `release_profile=minimum|stable|full` керує широтою -live/provider, що передається до release checks: `minimum` лишає найшвидші -OpenAI/core release-critical lanes, `stable` додає стабільний набір -provider/backend, а `full` запускає широку advisory provider/media matrix. -Парасольковий workflow записує id запущених дочірніх запусків, а фінальне -завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх -запусків і додає таблиці найповільніших завдань для кожного дочірнього запуску. -Якщо дочірній workflow перезапущено і він став зеленим, перезапустіть лише -батьківське завдання verifier, щоб оновити результат парасолькового workflow і -підсумок часу виконання. +`Full Release Validation` — це ручний парасольковий робочий процес для «запустити все +перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає +ручний робочий процес `CI` з цією ціллю та запускає `OpenClaw Release Checks` +для перевірки встановлення, приймання пакета, наборів Docker для релізного шляху, live/E2E, +OpenWebUI, паритету QA Lab, Matrix і напрямів Telegram. Він також може запускати +післяпублікаційний робочий процес `NPM Telegram Beta E2E`, коли надано специфікацію +опублікованого пакета. `release_profile=minimum|stable|full` керує шириною live/provider, +яка передається до перевірок релізу: `minimum` залишає найшвидші критичні для релізу +напрями OpenAI/core, `stable` додає стабільний набір provider/backend, а +`full` запускає широку консультативну матрицю provider/media. Парасольковий процес записує +ідентифікатори запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє +поточні висновки дочірніх запусків і додає таблиці найповільніших завдань для кожного дочірнього +запуску. Якщо дочірній робочий процес перезапущено і він став зеленим, перезапустіть лише батьківське +завдання перевірки, щоб оновити результат парасолькового процесу та підсумок часу. Для відновлення `Full Release Validation` і `OpenClaw Release Checks` обидва -приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для -звичайного повного дочірнього CI, `release-checks` для кожного дочірнього -релізного запуску або вужчу релізну групу: `install-smoke`, `cross-os`, -`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` у -парасольковому workflow. Це утримує повторний запуск невдалого релізного -середовища в межах після цільового виправлення. +приймають `rerun_group`. Використовуйте `all` для кандидата на реліз, `ci` лише для +звичайної повної дочірньої CI, `release-checks` для кожного дочірнього релізного процесу або вужчу +групу релізу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, +`qa-parity`, `qa-live` або `npm-telegram` у парасольковому процесі. Це утримує перезапуск +невдалого релізного середовища в межах після сфокусованого виправлення. -Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але +Дочірній live/E2E релізу зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди (`native-live-src-agents`, `native-live-src-gateway-core`, відфільтровані за provider завдання `native-live-src-gateway-profiles`, `native-live-src-gateway-backends`, `native-live-test`, `native-live-extensions-a-k`, `native-live-extensions-l-n`, `native-live-extensions-openai`, `native-live-extensions-o-z-other`, -`native-live-extensions-xai`, розділені media audio/video шарди та -відфільтровані за provider music шарди) через `scripts/test-live-shard.mjs` -замість одного послідовного завдання. Це зберігає те саме файлове покриття й -водночас спрощує повторний запуск і діагностику повільних відмов live provider. -Агреговані назви шардів `native-live-extensions-o-z`, -`native-live-extensions-media` і `native-live-extensions-media-music` -залишаються чинними для ручних одноразових перезапусків. +`native-live-extensions-xai`, розділені шарди audio/video для media та +відфільтровані за provider шарди music) через `scripts/test-live-shard.mjs` замість +одного послідовного завдання. Це зберігає те саме файлове покриття, водночас полегшуючи перезапуск +і діагностику повільних збоїв live provider. Агреговані назви шардів +`native-live-extensions-o-z`, `native-live-extensions-media` і +`native-live-extensions-media-music` залишаються чинними для ручних +одноразових перезапусків. -`OpenClaw Release Checks` використовує довірений workflow ref, щоб один раз -розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає -цей artifact і до live/E2E release-path Docker workflow, і до package acceptance -shard. Це зберігає сталі байти пакета в усіх релізних середовищах і уникає +`OpenClaw Release Checks` використовує довірене посилання робочого процесу, щоб один раз розв’язати вибране +посилання в tarball `release-package-under-test`, а потім передає цей артефакт +і до Docker-робочого процесу live/E2E релізного шляху, і до шарда приймання пакета. +Це зберігає байти пакета узгодженими між релізними середовищами й уникає повторного пакування того самого кандидата в кількох дочірніх завданнях. -`Package Acceptance` — це side-run workflow для перевірки artifact пакета без -блокування релізного workflow. Він розв’язує одного кандидата з опублікованої -npm spec, довіреного `package_ref`, зібраного вибраним harness `workflow_ref`, -HTTPS URL tarball із SHA-256 або tarball artifact з іншого запуску GitHub -Actions, завантажує його як `package-under-test`, а потім повторно використовує +`Package Acceptance` — це побічний робочий процес для валідації артефакта пакета +без блокування релізного робочого процесу. Він розв’язує одного кандидата з +опублікованої npm-специфікації, довіреного `package_ref`, зібраного вибраним +каркасом `workflow_ref`, HTTPS URL tarball із SHA-256 або артефакта tarball +з іншого запуску GitHub Actions, завантажує його як `package-under-test`, а потім повторно використовує планувальник Docker release/E2E з цим tarball замість повторного пакування -workflow checkout. Профілі охоплюють smoke, package, product, full і custom -вибори Docker lane. Профіль `package` використовує offline plugin coverage, щоб -перевірка опублікованого пакета не залежала від доступності live ClawHub. -Опційний Telegram lane повторно використовує artifact -`package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях до -опублікованої npm spec зберігається для standalone dispatches. +checkout робочого процесу. Профілі покривають smoke, package, product, full і custom +вибори напрямів Docker. Профіль `package` використовує офлайн-покриття Plugin, щоб +валідація опублікованого пакета не залежала від доступності live ClawHub. Опційний +напрям Telegram повторно використовує артефакт +`package-under-test` у робочому процесі `NPM Telegram Beta E2E`, а шлях +опублікованої npm-специфікації збережено для окремих запусків. -## Приймальне тестування пакета +## Приймання пакета -Використовуйте `Package Acceptance`, коли питання звучить як "чи працює цей -встановлюваний пакет OpenClaw як продукт?" Це відрізняється від звичайного CI: -звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance -перевіряє один tarball через той самий Docker E2E harness, який користувачі -застосовують після встановлення або оновлення. +Використовуйте `Package Acceptance`, коли питання таке: «чи працює цей встановлюваний пакет OpenClaw +як продукт?» Це відрізняється від звичайної CI: звичайна CI валідує +дерево вихідного коду, тоді як приймання пакета валідує один tarball через той самий +каркас Docker E2E, який користувачі запускають після встановлення або оновлення. -Workflow має чотири завдання: +Робочий процес має чотири завдання: -1. `resolve_package` робить checkout `workflow_ref`, розв’язує одного кандидата пакета, +1. `resolve_package` виконує checkout `workflow_ref`, розв’язує одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує - `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як - artifact `package-under-test` і друкує source, workflow ref, package - ref, version, SHA-256 і profile у підсумку кроку GitHub. + `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт + `package-under-test` і виводить джерело, посилання робочого процесу, посилання пакета, + версію, SHA-256 і профіль у підсумку кроку GitHub. 2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і - `package_artifact_name=package-under-test`. Reusable workflow завантажує - цей artifact, перевіряє інвентар tarball, готує Docker images package-digest, - коли потрібно, і запускає вибрані Docker lanes проти цього пакета замість - пакування workflow checkout. Коли профіль вибирає кілька цільових - `docker_lanes`, reusable workflow готує пакет і спільні images один раз, а - потім розгортає ці lanes як паралельні цільові Docker jobs з унікальними - artifacts. + `package_artifact_name=package-under-test`. Повторно використовуваний робочий процес завантажує + цей артефакт, валідує інвентар tarball, готує Docker-образи package-digest + за потреби та запускає вибрані напрями Docker проти цього + пакета замість пакування checkout робочого процесу. Коли профіль вибирає + кілька цільових `docker_lanes`, повторно використовуваний робочий процес готує пакет + і спільні образи один раз, а потім розгортає ці напрями як паралельні цільові Docker + завдання з унікальними артефактами. 3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли - `telegram_mode` не `none`, і встановлює той самий artifact `package-under-test`, - коли Package Acceptance розв’язав один; standalone Telegram dispatch усе ще - може встановити опубліковану npm spec. -4. `summary` провалює workflow, якщо розв’язання пакета, Docker acceptance або - опційний Telegram lane завершилися невдало. + `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, + коли Package Acceptance розв’язав його; окремий запуск Telegram усе ще + може встановити опубліковану npm-специфікацію. +4. `summary` завершує робочий процес помилкою, якщо розв’язання пакета, Docker acceptance або + опційний напрям Telegram зазнали збою. Джерела кандидатів: - `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну - версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте - це для приймального тестування опублікованих beta/stable. + версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для + приймання опублікованих beta/stable. - `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. - Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з - історії гілок репозиторію або релізного тегу, встановлює залежності у - detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. + Розв’язувач отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт + досяжний з історії гілок репозиторію або релізного тегу, встановлює залежності у + відокремленому worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. - `source=url`: завантажує HTTPS `.tgz`; `package_sha256` обов’язковий. - `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і - `artifact_name`; `package_sha256` опційний, але його варто надати для - зовнішньо поширених artifacts. + `artifact_name`; `package_sha256` опційний, але його слід надавати для + зовнішньо поширених артефактів. Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений -код workflow/harness, який запускає тест. `package_ref` — це вихідний коміт, -який пакується, коли `source=ref`. Це дає змогу поточному test harness -перевіряти старіші довірені коміти вихідного коду без запуску старої workflow -логіки. +код робочого процесу/каркаса, який виконує тест. `package_ref` — це вихідний коміт, +який пакується, коли `source=ref`. Це дозволяє поточному тестовому каркасу валідувати +старіші довірені коміти вихідного коду без запуску старої логіки робочого процесу. -Профілі відповідають Docker coverage: +Профілі відповідають покриттю Docker: - `smoke`: `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package`: `npm-onboard-channel-agent`, `doctor-switch`, @@ -133,38 +128,36 @@ Workflow має чотири завдання: `plugin-update` - `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full`: повні Docker release-path chunks з OpenWebUI +- `full`: повні фрагменти Docker релізного шляху з OpenWebUI - `custom`: точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Release checks викликає Package Acceptance з `source=ref`, +Перевірки релізу викликають Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і -`telegram_mode=mock-openai`. Docker chunks release-path -покривають перехресні lanes package/update/plugin, тоді як Package Acceptance -зберігає artifact-native докази bundled-channel compat, offline plugin і +`telegram_mode=mock-openai`. Docker-фрагменти релізного шляху +покривають перетин напрямів package/update/plugin, тоді як Package +Acceptance зберігає нативне для артефакта підтвердження bundled-channel compat, офлайн Plugin і Telegram проти того самого розв’язаного package tarball. -Cross-OS release checks усе ще покривають OS-specific onboarding, installer і -platform behavior; package/update product validation має починатися з Package -Acceptance. Windows packaged і installer fresh lanes також перевіряють, що -встановлений пакет може імпортувати browser-control override із raw absolute -Windows path. +Cross-OS перевірки релізу все ще покривають специфічну для ОС поведінку onboarding, installer і +platform; продуктову валідацію package/update слід починати з Package Acceptance. Windows-напрями +packaged і installer fresh також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного +шляху Windows. -Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих -пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть -використовувати шлях сумісності для відомих private QA entries у -`dist/postinstall-inventory.json`, які вказують на файли, пропущені в tarball; +Package Acceptance має обмежені вікна сумісності зі спадковими версіями для вже +опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, +можуть використовувати шлях сумісності для відомих приватних QA-записів у +`dist/postinstall-inventory.json`, які вказують на файли, пропущені в tarball, `doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, -коли пакет не надає цей flag; `update-channel-switch` може вилучити відсутні -`pnpm.patchedDependencies` з fake git fixture, отриманої з tarball, і може -логувати відсутній збережений `update.channel`; plugin smokes можуть читати -legacy install-record locations або приймати відсутність marketplace -install-record persistence; а `plugin-update` може дозволяти migration config -metadata, і водночас усе ще вимагати, щоб install record і no-reinstall behavior -залишалися незмінними. Опублікований пакет `2026.4.26` також може попереджати -про local build metadata stamp files, які вже були випущені. Пізніші пакети -мають відповідати сучасним контрактам; ті самі умови завершуються помилкою -замість попередження або пропуску. +коли пакет не надає цей прапорець, `update-channel-switch` може обрізати +відсутні `pnpm.patchedDependencies` з похідної від tarball фальшивої git-фікстури та +може логувати відсутній збережений `update.channel`, smoke-перевірки Plugin можуть читати спадкові +розташування install-record або приймати відсутність збереження marketplace install-record, +а `plugin-update` може дозволити міграцію метаданих конфігурації, водночас усе ще +вимагаючи, щоб install record і поведінка без перевстановлення залишалися незмінними. Опублікований +пакет `2026.4.26` також може попереджати про файли stamp метаданих локальної збірки, +які вже були поставлені. Пізніші пакети мають відповідати сучасним контрактам; ті самі +умови завершуються помилкою замість попередження або пропуску. Приклади: @@ -207,48 +200,46 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску package acceptance починайте з підсумку -`resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім -перевірте дочірній запуск `docker_acceptance` і його Docker artifacts: -`.artifacts/docker-tests/**/summary.json`, `failures.json`, lane logs, phase -timings і rerun commands. Віддавайте перевагу повторному запуску невдалого -package profile або точних Docker lanes замість повторного запуску повної -релізної перевірки. +Під час налагодження невдалого запуску package acceptance почніть із підсумку `resolve_package`, +щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте +дочірній запуск `docker_acceptance` і його Docker-артефакти: +`.artifacts/docker-tests/**/summary.json`, `failures.json`, логи напрямів, часові показники +фаз і команди перезапуску. Надавайте перевагу перезапуску невдалого профілю пакета або +точних Docker-напрямів замість перезапуску повної валідації релізу. -QA Lab має окремі CI lanes поза головним smart-scoped workflow. Workflow -`Parity gate` запускається на відповідні зміни PR і manual dispatch; він -збирає private QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. -Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual -dispatch; він розгортає mock parity gate, live Matrix lane та live Telegram і -Discord lanes як паралельні jobs. Live jobs використовують environment -`qa-live-shared`, а Telegram/Discord використовують Convex leases. Matrix -використовує `--profile fast` для scheduled і release gates, додаючи -`--fail-fast` лише тоді, коли checked-out CLI це підтримує. Типове значення CLI -і manual workflow input залишаються `all`; manual `matrix_profile=all` -dispatch завжди розбиває повне Matrix coverage на jobs `transport`, `media`, +QA Lab має окремі CI-напрями поза основним робочим процесом із розумним звуженням області. Робочий процес +`Parity gate` запускається для відповідних змін PR і ручного запуску; він +збирає приватний QA runtime і порівнює агентні пакети mock GPT-5.5 та Opus 4.6. +Робочий процес `QA-Lab - All Lanes` запускається щоночі на `main` і під час +ручного запуску; він розгортає mock parity gate, live-напрям Matrix, а також live +напрями Telegram і Discord як паралельні завдання. Live-завдання використовують +середовище `qa-live-shared`, а Telegram/Discord використовують lease Convex. Matrix +використовує `--profile fast` для запланованих і релізних перевірок, додаючи `--fail-fast` лише +коли checked-out CLI це підтримує. Типове значення CLI і ручний ввід робочого процесу +залишаються `all`; ручний запуск `matrix_profile=all` +завжди ділить повне покриття Matrix на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також -запускає release-critical QA Lab lanes перед approval релізу; його QA parity -gate запускає candidate і baseline packs як паралельні lane jobs, а потім -завантажує обидва artifacts у невелике report job для фінального parity -comparison. -Не ставте шлях landing для PR за `Parity gate`, якщо зміна фактично не торкається -QA runtime, model-pack parity або поверхні, якою володіє parity workflow. -Для звичайних виправлень channel, config, docs або unit-test розглядайте це як -опційний сигнал і дотримуйтеся scoped CI/check evidence. +запускає критичні для релізу QA Lab напрями перед схваленням релізу; його QA parity +gate запускає кандидатні та baseline пакети як паралельні завдання напрямів, потім завантажує +обидва артефакти в невелике завдання звіту для фінального порівняння паритету. +Не ставте шлях landing PR за `Parity gate`, якщо зміна фактично не +торкається QA runtime, паритету model-pack або поверхні, якою володіє робочий процес паритету. +Для звичайних виправлень channel, config, docs або unit-test розглядайте це як опційний +сигнал і дотримуйтеся scoped CI/check доказів. -Робочий процес `Duplicate PRs After Merge` — це ручний workflow для супровідників для очищення дублікатів після потрапляння змін. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR злито, і що кожен дублікат має або спільне referenced issue, або перекривні змінені hunks. +Робочий процес `Duplicate PRs After Merge` — це ручний робочий процес для супровідників для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що злитий PR справді об’єднано, а кожен дублікат має або спільну згадану issue, або перетин змінених hunks. -Робочий процес `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним скануванням репозиторію. Щоденні та ручні запуски сканують код workflows Actions, а також найризиковіші поверхні JavaScript/TypeScript для auth, secrets, sandbox, cron і gateway за допомогою високоточних security queries. +Робочий процес `CodeQL` навмисно є вузьким сканером безпеки першого проходу, а не повним обходом репозиторію. Щоденні та ручні запуски сканують код workflow Actions, а також найризикованіші поверхні JavaScript/TypeScript для auth, secrets, sandbox, cron і gateway за допомогою високоточних security-запитів. Завдання channel-runtime-boundary окремо сканує контракти реалізації основних каналів разом із runtime channel plugin, gateway, Plugin SDK, secrets і audit touchpoints у категорії `/codeql-critical-security/channel-runtime-boundary`, щоб сигнал безпеки каналів міг масштабуватися без розширення базової категорії JS/TS. -Робочий процес `CodeQL Android Critical Security` — це запланований Android security shard. Він вручну збирає Android app для CodeQL на найменшій мітці Blacksmith Linux runner, прийнятій workflow sanity, і завантажує результати в категорію `/codeql-critical-security/android`. +Робочий процес `CodeQL Android Critical Security` — це запланований Android-шард безпеки. Він вручну збирає Android-застосунок для CodeQL на найменшій мітці Blacksmith Linux runner, яку приймає workflow sanity, і завантажує результати в категорію `/codeql-critical-security/android`. -Робочий процес `CodeQL macOS Critical Security` — це щотижневий/ручний macOS security shard. Він вручну збирає macOS app для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і завантажує результати в категорію `/codeql-critical-security/macos`. Тримайте його поза щоденним workflow за замовчуванням, бо macOS build домінує за runtime навіть у чистому стані. +Робочий процес `CodeQL macOS Critical Security` — це щотижневий/ручний macOS-шард безпеки. Він вручну збирає macOS-застосунок для CodeQL на Blacksmith macOS, відфільтровує результати збірки залежностей із завантажуваного SARIF і завантажує результати в категорію `/codeql-critical-security/macos`. Тримайте його поза щоденним стандартним workflow, бо збірка macOS домінує за часом виконання навіть у чистому стані. -Робочий процес `CodeQL Critical Quality` — це відповідний non-security shard. Він запускає лише quality queries JavaScript/TypeScript з error-severity і безпеки не стосується, на вузьких high-value поверхнях. Його baseline job сканує ту саму поверхню auth, secrets, sandbox, cron і gateway, що й security workflow. Job config-boundary сканує config schema, migration, normalization і IO contracts в окремій категорії `/codeql-critical-quality/config-boundary`. Job gateway-runtime-boundary сканує gateway protocol schemas і server method contracts в окремій категорії `/codeql-critical-quality/gateway-runtime-boundary`. Job channel-runtime-boundary сканує core channel implementation contracts в окремій категорії `/codeql-critical-quality/channel-runtime-boundary`. Job plugin-boundary сканує loader, registry, public-surface і Plugin SDK entrypoint contracts в окремій категорії `/codeql-critical-quality/plugin-boundary`. Тримайте workflow окремо від security, щоб quality findings можна було планувати, вимірювати, вимикати або розширювати без затемнення security signal. Розширення CodeQL для Swift, Python, UI і bundled-plugin слід додавати назад лише як scoped або sharded follow-up work після того, як вузькі профілі матимуть стабільні runtime і signal. +Робочий процес `CodeQL Critical Quality` — це відповідний небезпековий шард. Він запускає лише JavaScript/TypeScript quality-запити severity error, не пов’язані з безпекою, на вузьких цінних поверхнях. Його базове завдання сканує ту саму поверхню auth, secrets, sandbox, cron і gateway, що й security workflow. Завдання config-boundary сканує схему конфігурації, міграцію, нормалізацію та IO-контракти в окремій категорії `/codeql-critical-quality/config-boundary`. Завдання gateway-runtime-boundary сканує схеми gateway protocol і контракти server methods в окремій категорії `/codeql-critical-quality/gateway-runtime-boundary`. Завдання channel-runtime-boundary сканує контракти реалізації основних каналів в окремій категорії `/codeql-critical-quality/channel-runtime-boundary`. Завдання plugin-boundary сканує контракти loader, registry, public-surface і entrypoint Plugin SDK в окремій категорії `/codeql-critical-quality/plugin-boundary`. Тримайте workflow окремо від security, щоб quality-знахідки можна було планувати, вимірювати, вимикати або розширювати без затемнення security-сигналу. Розширення CodeQL для Swift, Python, UI і bundled-plugin слід додавати назад лише як scoped або sharded подальшу роботу після того, як вузькі профілі матимуть стабільний runtime і сигнал. -Робочий процес `Docs Agent` — це подієво-керована lane супроводу Codex для підтримання наявної документації в узгодженому стані з нещодавно landed змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Workflow-run invocations пропускаються, коли `main` уже просунувся далі або коли інший non-skipped Docs Agent run було створено за останню годину. Коли він запускається, він переглядає commit range від попереднього non-skipped Docs Agent source SHA до поточного `main`, тому один hourly run може охопити всі зміни main, накопичені з моменту останнього docs pass. +Робочий процес `Docs Agent` — це подієво керований Codex maintenance lane для підтримання наявної документації в узгодженому стані з нещодавно злитими змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли інший non-skipped запуск Docs Agent було створено протягом останньої години. Під час запуску він переглядає діапазон комітів від попереднього non-skipped source SHA Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни main, накопичені з останнього проходу документації. -Робочий процес `Test Performance Agent` — це подієво-керована lane супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже запускався або зараз виконується цього UTC day. Manual dispatch обходить цей daily activity gate. Lane створює full-suite grouped Vitest performance report, дозволяє Codex робити лише невеликі coverage-preserving test performance fixes замість широких refactors, потім повторно запускає full-suite report і відхиляє зміни, які зменшують passing baseline test count. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має проходити перед будь-яким commit. Коли `main` просувається до того, як bot push потрапить, lane rebase-ить validated patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні stale patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action міг зберегти ту саму drop-sudo safety posture, що й docs agent. +Робочий процес `Test Performance Agent` — це подієво керований Codex maintenance lane для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже запускався або виконується цього UTC-дня. Manual dispatch обходить цей daily activity gate. Lane формує grouped Vitest performance report для повного набору, дозволяє Codex робити лише невеликі coverage-preserving виправлення продуктивності тестів замість широких рефакторингів, потім повторно запускає full-suite report і відхиляє зміни, які зменшують baseline passing test count. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має пройти перед будь-яким комітом. Коли `main` просувається до того, як bot push буде злитий, lane перебазовує перевірений patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action міг зберігати ту саму drop-sudo safety posture, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -257,33 +248,33 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Огляд jobs +## Огляд завдань -| Job | Призначення | Коли запускається | +| Завдання | Призначення | Коли запускається | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Виявляє docs-only changes, changed scopes, changed plugins і будує CI manifest | Завжди на non-draft pushes і PRs | -| `security-scm-fast` | Виявлення приватних ключів і workflow audit через `zizmor` | Завжди на non-draft pushes і PRs | -| `security-dependency-audit` | Dependency-free production lockfile audit щодо npm advisories | Завжди на non-draft pushes і PRs | -| `security-fast` | Required aggregate для fast security jobs | Завжди на non-draft pushes і PRs | -| `build-artifacts` | Збірка `dist/`, Control UI, built-artifact checks і reusable downstream artifacts | Зміни, що стосуються Node | -| `checks-fast-core` | Fast Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Зміни, що стосуються Node | -| `checks-fast-contracts-channels` | Sharded channel contract checks зі stable aggregate check result | Зміни, що стосуються Node | -| `checks-node-extensions` | Повні bundled-plugin test shards across the plugin suite | Зміни, що стосуються Node | -| `checks-node-core-test` | Core Node test shards, excluding channel, bundled, contract, and plugin lanes | Зміни, що стосуються Node | -| `check` | Sharded main local gate equivalent: prod types, lint, guards, test types, and strict smoke | Зміни, що стосуються Node | -| `check-additional` | Architecture, boundary, plugin-surface guards, package-boundary, and gateway-watch shards | Зміни, що стосуються Node | -| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Зміни, що стосуються Node | -| `checks` | Verifier для built-artifact channel tests | Зміни, що стосуються Node | -| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Manual CI dispatch для releases | -| `check-docs` | Docs formatting, lint і broken-link checks | Docs changed | -| `skills-python` | Ruff + pytest для Python-backed Skills | Зміни, що стосуються Python Skills | -| `checks-windows` | Windows-specific process/path tests plus shared runtime import specifier regressions | Зміни, що стосуються Windows | -| `macos-node` | macOS TypeScript test lane з використанням shared built artifacts | Зміни, що стосуються macOS | -| `macos-swift` | Swift lint, build і tests для macOS app | Зміни, що стосуються macOS | -| `android` | Android unit tests для обох flavors plus one debug APK build | Зміни, що стосуються Android | -| `test-performance-agent` | Daily Codex slow-test optimization after trusted activity | Main CI success або manual dispatch | +| `preflight` | Виявляє docs-only зміни, changed scopes, changed extensions і формує CI manifest | Завжди для non-draft pushes і PRs | +| `security-scm-fast` | Виявлення private key і workflow audit через `zizmor` | Завжди для non-draft pushes і PRs | +| `security-dependency-audit` | Dependency-free audit production lockfile за npm advisories | Завжди для non-draft pushes і PRs | +| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft pushes і PRs | +| `build-artifacts` | Збирає `dist/`, Control UI, built-artifact checks і reusable downstream artifacts | Node-relevant зміни | +| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-relevant зміни | +| `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate check result | Node-relevant зміни | +| `checks-node-extensions` | Повні bundled-plugin test shards для extension suite | Node-relevant зміни | +| `checks-node-core-test` | Core Node test shards, крім channel, bundled, contract і extension lanes | Node-relevant зміни | +| `check` | Sharded еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Node-relevant зміни | +| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Node-relevant зміни | +| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Node-relevant зміни | +| `checks` | Verifier для built-artifact channel tests | Node-relevant зміни | +| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Manual CI dispatch для releases | +| `check-docs` | Docs formatting, lint і broken-link checks | Docs змінено | +| `skills-python` | Ruff + pytest для Skills на базі Python | Python-skill-relevant зміни | +| `checks-windows` | Windows-specific process/path tests плюс shared runtime import specifier regressions | Windows-relevant зміни | +| `macos-node` | macOS TypeScript test lane із використанням shared built artifacts | macOS-relevant зміни | +| `macos-swift` | Swift lint, build і tests для macOS-застосунку | macOS-relevant зміни | +| `android` | Android unit tests для обох flavors плюс одна debug APK build | Android-relevant зміни | +| `test-performance-agent` | Щоденна Codex slow-test optimization після trusted activity | Main CI success або manual dispatch | -Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python Skills, Windows, macOS, Android і Control UI i18n. Manual runs використовують унікальну concurrency group, щоб release-candidate full suite не скасовувалася іншим push або PR run на тому самому ref. Необов’язковий input `target_ref` дозволяє trusted caller запустити цей graph для branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref. +Manual CI dispatches запускають той самий job graph, що й звичайний CI, але примусово вмикають кожен scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python Skills, Windows, macOS, Android і Control UI i18n. Manual runs використовують унікальну concurrency group, щоб повний набір release-candidate не скасовувався іншим push або PR run на тому самому ref. Необов’язковий input `target_ref` дає trusted caller змогу запускати цей graph проти branch, tag або full commit SHA, використовуючи workflow file із вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -293,58 +284,58 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Порядок fail-fast -Jobs упорядковані так, щоб дешеві checks падали до запуску дорогих: +Завдання впорядковано так, щоб дешеві перевірки падали раніше, ніж запускаються дорогі: -1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є steps усередині цього job, а не standalone jobs. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не очікуючи на важчі artifact і platform matrix jobs. -3. `build-artifacts` перекривається з fast Linux lanes, щоб downstream consumers могли стартувати, щойно shared build готовий. -4. Після цього розгалужуються важчі platform і runtime lanes: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи на важчі artifact і platform matrix jobs. +3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream consumers могли стартувати, щойно shared build буде готовий. +4. Важчі platform і runtime lanes розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покрита модульними тестами в `src/scripts/ci-changed-scope.test.ts`. Ручний запуск пропускає виявлення changed-scope і змушує preflight-маніфест -поводитися так, ніби змінилася кожна область з визначеною областю дії. -Зміни CI workflow перевіряють граф Node CI плюс linting workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформні лінії залишаються обмеженими змінами платформного вихідного коду. -Редагування лише маршрутизації CI, вибрані дешеві редагування фікстур core-test і вузькі редагування допоміжних засобів/маршрутизації тестів контрактів плагінів використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає артефактів збірки, сумісності з Node 22, контрактів каналів, повних core-шардів, шардів пакетованих плагінів і додаткових guard-матриць, коли змінені файли обмежені поверхнями маршрутизації або допоміжних засобів, які швидке завдання перевіряє напряму. -Перевірки Windows Node обмежені специфічними для Windows обгортками процесів/шляхів, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями CI workflow, які виконують цю лінію; непов’язані зміни вихідного коду, плагінів, install-smoke і лише тестові зміни залишаються на Linux Node-лініях, щоб вони не резервували 16-vCPU Windows worker для покриття, яке вже виконується звичайними тестовими шардами. -Окремий workflow `install-smoke` повторно використовує той самий scope-скрипт через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request-и запускають швидкий шлях для поверхонь Docker/package, змін package/manifest пакетованих плагінів і core-поверхонь plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише вихідного коду пакетованих плагінів, лише тестові редагування і редагування лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg пакетованого extension і запускає обмежений Docker-профіль пакетованих плагінів під 240-секундним сукупним таймаутом команди, причому Docker run кожного сценарію обмежено окремо. Повний шлях зберігає QR package install і installer Docker/update-покриття для нічних запланованих запусків, ручних запусків, workflow-call release checks і pull request-ів, які справді зачіпають поверхні installer/package/Docker. Push-и в `main`, включно з merge commits, не примушують повний шлях; коли changed-scope-логіка запитувала б повне покриття на push, workflow залишає швидкий Docker smoke і відкладає full install smoke до нічної або release-валидації. Повільний Bun global install image-provider smoke окремо керується `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні dispatch-и `install-smoke` можуть увімкнути його, але pull request-и і push-и в `main` його не запускають. QR і installer Docker-тести зберігають власні Dockerfile-и, орієнтовані на інсталяцію. Локальний `test:docker:all` попередньо збирає один спільний live-test-образ, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: мінімальний Node/Git runner для ліній installer/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних ліній. Визначення Docker-ліній містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної лінії за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає лінії з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типову кількість слотів основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM` і кількість слотів чутливого до провайдера tail-пулу 10 через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження важких ліній за замовчуванням становлять `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб npm install і multi-service-лінії не перевантажували Docker, поки легші лінії все ще заповнюють доступні слоти. Одна лінія, важча за ефективні обмеження, усе ще може стартувати з порожнього пулу, а потім виконується сама, доки не звільнить місткість. Старти ліній за замовчуванням рознесені на 2 секунди, щоб уникнути локальних сплесків створення в Docker daemon; перевизначте це через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегатний запуск попередньо перевіряє Docker, видаляє застарілі OpenClaw E2E-контейнери, виводить статус активних ліній, зберігає таймінги ліній для впорядкування від найдовших і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перевірки планувальника. За замовчуванням він припиняє планувати нові pooled-лінії після першого збою, і кожна лінія має 120-хвилинний резервний таймаут, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail-лінії використовують жорсткіші обмеження на рівні лінії. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні лінії планувальника, включно з release-only-лініями, такими як `install-e2e`, і розділеними лініями bundled update, такими як `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. Повторно використовуваний live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, яке покриття package, image kind, live image, lane і credential потрібне, а потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт package з поточного запуску, або завантажує артефакт package з `package_artifact_run_id`; перевіряє інвентар tarball; збирає і публікує package-digest-tagged bare/functional GHCR Docker E2E-образи через Docker layer cache Blacksmith, коли план потребує ліній із встановленим package; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Workflow `Package Acceptance` є високорівневим package gate: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакту попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна acceptance-логіка могла перевіряти старіші довірені commits без checkout старого workflow-коду. Release checks запускають спеціальну дельту Package Acceptance для цільового ref: bundled-channel compat, offline plugin fixtures і Telegram package QA щодо визначеного tarball. Release-path Docker suite запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому тип образу і виконував кілька ліній через той самий зважений планувальник (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`). OpenWebUI включено в `plugins-runtime-services`, коли повне release-path-покриття запитує його, і він зберігає окремий chunk `openwebui` лише для OpenWebUI-only dispatch-ів. Застарілі назви агрегатних chunk-ів `package-update`, `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` досі працюють для ручних повторних запусків, але release workflow використовує розділені chunk-и, щоб installer E2E і sweeps install/uninstall пакетованих плагінів не домінували над критичним шляхом. Псевдонім лінії `install-e2e` залишається агрегатним псевдонімом ручного повторного запуску для обох provider installer-ліній. Chunk `bundled-channels` запускає розділені лінії `bundled-channel-*` і `bundled-channel-update-*` замість послідовної all-in-one-лінії `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` з журналами ліній, таймінгами, `summary.json`, `failures.json`, фазовими таймінгами, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість chunk jobs, що утримує відлагодження невдалої лінії в межах одного цільового Docker job і готує, завантажує або повторно використовує артефакт package для цього запуску; якщо вибрана лінія є live Docker-лінією, цільовий job локально збирає live-test-образ для цього повторного запуску. Згенеровані команди повторного запуску GitHub для кожної лінії містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала лінія могла повторно використати точний package і образи з невдалого запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти з GitHub run і вивести комбіновані/по-лінійні цільові команди повторного запуску; використовуйте `pnpm test:docker:timings ` для підсумків повільних ліній і критичного шляху фаз. Запланований live/E2E workflow щодня запускає повний release-path Docker suite. Матрицю bundled update розділено за ціллю оновлення, щоб повторювані npm update і doctor repair passes могли шардитися разом з іншими bundled-перевірками. +діяти так, ніби кожна scoped-область змінилася. +Редагування CI-робочих процесів перевіряють граф Node CI та лінтинг робочих процесів, але самі по собі не примушують виконувати нативні збірки Windows, Android або macOS; ці платформні lane залишаються scoped до змін у платформному вихідному коді. +Редагування лише маршрутизації CI, вибрані дешеві редагування фікстур core-тестів і вузькі редагування допоміжних засобів/маршрутизації тестів контрактів plugin використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає артефактів збірки, сумісності з Node 22, контрактів каналів, повних core-шардів, шардів bundled-plugin і додаткових guard-матриць, коли змінені файли обмежені поверхнями маршрутизації або допоміжними поверхнями, які швидке завдання перевіряє безпосередньо. +Перевірки Windows Node scoped до специфічних для Windows обгорток процесів/шляхів, допоміжних засобів npm/pnpm/UI runner, конфігурації менеджера пакетів і поверхонь CI-робочих процесів, які виконують цей lane; непов’язані зміни вихідного коду, plugin, install-smoke і лише тестові зміни залишаються на Linux Node lane, щоб вони не резервували 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними тестовими шардами. +Окремий робочий процес `install-smoke` повторно використовує той самий scope-скрипт через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін пакетів/маніфестів bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише вихідного коду bundled plugin, лише тестові редагування й редагування лише документації не резервують Docker worker. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає CLI smoke видалення agents shared-workspace, запускає container gateway-network e2e, перевіряє аргумент збірки bundled extension і запускає обмежений Docker-профіль bundled-plugin із сукупним timeout команди 240 секунд, причому кожен Docker run сценарію обмежений окремо. Повний шлях зберігає встановлення QR package і Docker/update-покриття інсталятора для нічних запланованих запусків, ручних dispatch, workflow-call перевірок релізу та pull request, які справді торкаються поверхонь installer/package/Docker. Push у `main`, включно з merge commit, не примушують повний шлях; коли логіка changed-scope вимагала б повного покриття під час push, робочий процес зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації. Повільний Bun global install image-provider smoke окремо gated через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з робочого процесу перевірок релізу, а ручні dispatch `install-smoke` можуть увімкнути його, але pull request і push у `main` його не запускають. QR і Docker-тести інсталятора зберігають власні install-focused Dockerfile. Локальний `test:docker:all` попередньо збирає один спільний live-test образ, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: bare Node/Git runner для lane інсталятора/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для lane нормальної функціональності. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожного lane за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lane з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартну кількість слотів main-pool, що дорівнює 10, за допомогою `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів provider-sensitive tail-pool, що дорівнює 10, за допомогою `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження важких lane за замовчуванням становлять `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб lane npm install і multi-service не перевантажували Docker, тоді як легші lane все ще заповнюють доступні слоти. Один lane, важчий за ефективні обмеження, все одно може стартувати з порожнього pool, а потім виконується сам, доки не звільнить місткість. Запуски lane за замовчуванням рознесені на 2 секунди, щоб уникнути локальних штормів створення Docker daemon; перевизначте це за допомогою `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або іншого значення в мілісекундах. Локальний aggregate виконує preflight Docker, видаляє застарілі OpenClaw E2E контейнери, виводить статус активних lane, зберігає таймінги lane для впорядкування longest-first і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для інспекції планувальника. За замовчуванням він припиняє планувати нові pooled lane після першої помилки, і кожен lane має резервний timeout 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lane використовують жорсткіші per-lane обмеження. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні lane планувальника, включно з release-only lane, такими як `install-e2e`, і розділеними lane bundled update, такими як `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб agents могли відтворити один невдалий lane. Повторно використовуваний робочий процес live/E2E запитує в `scripts/test-docker-all.mjs --plan-json`, яке покриття package, kind образу, live image, lane і облікових даних потрібне, а потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт package з поточного run, або завантажує артефакт package з `package_artifact_run_id`; перевіряє inventory tarball; збирає і push bare/functional GHCR Docker E2E образи з тегом package digest через Docker layer cache Blacksmith, коли план потребує lane зі встановленим package; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи package-digest замість повторної збірки. Робочий процес `Package Acceptance` є високорівневим package gate: він визначає candidate з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакта попереднього робочого процесу, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E робочий процес. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старіші довірені commit без checkout старого коду робочого процесу. Перевірки релізу запускають спеціальну дельту Package Acceptance для цільового ref: bundled-channel compat, offline plugin fixtures і Telegram package QA проти визначеного tarball. Docker-набір release-path запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому kind образу та виконував кілька lane через той самий зважений планувальник (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`). OpenWebUI включено до `plugins-runtime-services`, коли повне release-path покриття цього вимагає, і він зберігає окремий chunk `openwebui` лише для dispatch, що стосуються лише OpenWebUI. Застарілі назви aggregate chunk `package-update`, `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` все ще працюють для ручних повторних запусків, але релізний робочий процес використовує розділені chunk, щоб installer E2E і sweep встановлення/видалення bundled plugin не домінували в критичному шляху. Псевдонім lane `install-e2e` залишається aggregate manual rerun alias для обох provider installer lane. Chunk `bundled-channels` запускає розділені lane `bundled-channel-*` і `bundled-channel-update-*`, а не серійний all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` з журналами lane, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями slow-lane і командами per-lane rerun. Input робочого процесу `docker_lanes` запускає вибрані lane проти підготовлених образів замість chunk jobs, що утримує налагодження failed-lane в межах одного targeted Docker job і готує, завантажує або повторно використовує артефакт package для цього run; якщо вибраний lane є live Docker lane, targeted job локально збирає live-test image для цього rerun. Згенеровані per-lane команди GitHub rerun містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб failed lane міг повторно використати точні package і образи з невдалого run. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти з GitHub run і вивести combined/per-lane targeted rerun commands; використовуйте `pnpm test:docker:timings ` для summary slow-lane і phase critical-path. Запланований робочий процес live/E2E щодня запускає повний release-path Docker suite. Bundled update matrix розділена за update target, щоб повторні npm update і doctor repair passes могли shard разом з іншими bundled checks. -Поточні release Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `plugins-runtime-install-c`, `plugins-runtime-install-d`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегатний chunk `bundled-channels` залишається доступним для ручних one-shot повторних запусків, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегатними псевдонімами plugin/runtime, але release workflow використовує розділені chunk-и, щоб channel smokes, update targets, plugin runtime checks і sweeps install/uninstall пакетованих плагінів могли виконуватися паралельно. Цільові dispatch-и `docker_lanes` також розділяють кілька вибраних ліній на паралельні jobs після одного спільного кроку підготовки package/image, а bundled-channel update-лінії повторюють спробу один раз у разі тимчасових мережевих збоїв npm. +Поточні release Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `plugins-runtime-install-c`, `plugins-runtime-install-d`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Aggregate chunk `bundled-channels` залишається доступним для ручних one-shot rerun, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються aggregate plugin/runtime aliases, але релізний робочий процес використовує розділені chunks, щоб channel smokes, update targets, plugin runtime checks і bundled plugin install/uninstall sweeps могли виконуватися паралельно. Targeted dispatch `docker_lanes` також розділяє кілька вибраних lane на паралельні jobs після одного спільного етапу підготовки package/image, а bundled-channel update lane повторюють спробу один раз у разі тимчасових мережевих збоїв npm. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широка область платформ CI: зміни core production запускають core prod і core test typecheck плюс core lint/guards, зміни лише core test запускають тільки core test typecheck плюс core lint, зміни extension production запускають extension prod і extension test typecheck плюс extension lint, а зміни лише extension test запускають extension test typecheck плюс extension lint. Зміни публічного Plugin SDK або plugin-contract розширюються до typecheck extension, бо extensions залежать від цих core-контрактів, але Vitest extension sweeps є явною тестовою роботою. Version bumps лише release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни root/config fail safe до всіх check lanes. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широка platform scope CI: production-зміни core запускають core prod і core test typecheck плюс core lint/guards, зміни лише core test запускають лише core test typecheck плюс core lint, production-зміни extension запускають extension prod і extension test typecheck плюс extension lint, а зміни лише extension test запускають extension test typecheck плюс extension lint. Зміни public Plugin SDK або plugin-contract розширюються до extension typecheck, тому що extensions залежать від цих core-контрактів, але Vitest extension sweeps є явною тестовою роботою. Version bump лише release metadata запускають targeted version/config/root-dependency checks. Невідомі root/config changes fail safe до всіх check lanes. Локальна маршрутизація changed-test міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевша за `check:changed`: прямі редагування тестів запускають самі себе, -редагування вихідного коду віддають перевагу явним мапінгам, потім sibling tests і import-graph -dependents. Спільна конфігурація доставки group-room є одним із явних мапінгів: -зміни group visible-reply config, source reply delivery mode або -message-tool system prompt проходять через core reply tests плюс Discord і -Slack delivery regressions, щоб зміна спільного значення за замовчуванням падала до першого PR +редагування вихідного коду надають перевагу явним mappings, потім sibling tests і import-graph +dependents. Shared group-room delivery config є одним із явних mappings: +зміни у group visible-reply config, source reply delivery mode або +message-tool system prompt route через core reply tests плюс Discord і +Slack delivery regressions, щоб зміна shared default завершувалася помилкою до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна -достатньо широка для harness, що дешевий mapped set не є надійною заміною. +настільки harness-wide, що дешевий mapped set не є надійним proxy. -Для валідації Testbox запускайте з кореня репозиторію й віддавайте перевагу свіжій прогрітій машині для -широкого підтвердження. Перш ніж витрачати повільний gate на машину, яку повторно використали, термін дії якої минув або -яка щойно повідомила про неочікувано велику синхронізацію, спершу запустіть `pnpm testbox:sanity` всередині -цієї машини. Перевірка sanity швидко завершується помилкою, коли зникають обов’язкові кореневі файли, як-от -`pnpm-lock.yaml`, або коли `git status --short` показує щонайменше 200 +Для валідації Testbox запускайте з кореня репозиторію й надавайте перевагу свіжому прогрітому боксу для +широкого підтвердження. Перш ніж витрачати повільний gate на бокс, який було повторно використано, строк дії якого минув або +який щойно повідомив про неочікувано велику синхронізацію, спочатку запустіть `pnpm testbox:sanity` всередині +бокса. Sanity-перевірка швидко завершується з помилкою, коли потрібні кореневі файли, як-от +`pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 відстежуваних видалень. Зазвичай це означає, що стан віддаленої синхронізації не є надійною -копією PR. Зупиніть цю машину й прогрійте нову замість налагодження -помилки продуктового тесту. Для PR із навмисними великими видаленнями встановіть -`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього запуску sanity. +копією PR. Зупиніть цей бокс і прогрійте свіжий, замість того щоб налагоджувати +помилку продуктового тесту. Для PR з навмисними великими видаленнями встановіть +`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity-запуску. -Ручні CI-dispatch запуски виконують `checks-node-compat-node22` як compatibility-покриття для реліз-кандидата. Звичайні pull request і push до `main` пропускають цей lane й утримують матрицю сфокусованою на test/channel lane для Node 24. +Ручні CI-запуски виконують `checks-node-compat-node22` як покриття сумісності release candidate. Звичайні pull request-и та пуші в `main` пропускають цю lane й тримають матрицю зосередженою на тестових/channel lane для Node 24. -Найповільніші сімейства тестів Node розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені shard-и, тести bundled plugin балансуються між шістьма extension worker-ами, малі core unit lane-и об’єднуються в пари, auto-reply запускається як чотири збалансовані worker-и з поділом reply-піддерева на shard-и agent-runner, dispatch і commands/state-routing, а agentic gateway/plugin config-и розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media та miscellaneous plugin tests використовують свої окремі Vitest config-и замість спільного plugin catch-all. Extension shard jobs запускають до двох plugin config group одночасно з одним Vitest worker на group і більшим Node heap, щоб import-heavy plugin batch-и не створювали додаткових CI jobs. Широкий agents lane використовує спільний Vitest file-parallel scheduler, бо він залежить переважно від import/scheduling, а не від одного повільного test file. `runtime-config` запускається з infra core-runtime shard, щоб спільний runtime shard не відповідав за tail. Include-pattern shard-и записують timing entries з використанням імені CI shard, тож `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від відфільтрованого shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі незалежні guards паралельно в одному job. Gateway watch, channel tests і core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` вже зібрано, зберігаючи свої старі check names як легкі verifier jobs і водночас уникаючи двох додаткових Blacksmith worker-ів та другої artifact-consumer queue. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane усе ще компілює цей flavor із BuildConfig flags для SMS/call-log, водночас уникаючи дублювання debug APK packaging job на кожному Android-relevant push. -GitHub може позначати замінені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це CI noise, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тож вони все одно повідомляють нормальні shard failures, але не стають у чергу після того, як увесь workflow уже було замінено. -Автоматичний CI concurrency key версійовано (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг нескінченно блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. +Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожна job залишалася невеликою без надмірного резервування runner-ів: channel-контракти запускаються як три зважені shard-и, тести bundled plugin балансуються між шістьма extension worker-ами, малі core unit lane поєднуються попарно, auto-reply запускається як чотири збалансовані worker-и з розділенням піддерева reply на shard-и agent-runner, dispatch і commands/state-routing, а agentic gateway/plugin config-и розподіляються між наявними source-only agentic Node jobs замість очікування на зібрані артефакти. Широкі browser-, QA-, media- та miscellaneous plugin-тести використовують свої виділені Vitest config-и замість спільного plugin catch-all. Extension shard jobs запускають до двох груп plugin config одночасно з одним Vitest worker на групу й більшим Node heap, щоб import-heavy plugin-пакети не створювали додаткових CI jobs. Широка agents lane використовує спільний файлово-паралельний планувальник Vitest, бо вона обмежена import/scheduling, а не одним повільним тестовим файлом. `runtime-config` запускається з infra core-runtime shard, щоб спільний runtime shard не володів хвостом. Include-pattern shard-и записують timing entries з використанням імені CI shard, тож `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від фільтрованого shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; shard boundary guard запускає свої малі незалежні guard-и паралельно всередині однієї job. Gateway watch, channel-тести та core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі check names як легкі verifier jobs, водночас уникаючи двох додаткових Blacksmith worker-ів і другої artifact-consumer черги. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює цей flavor із BuildConfig-прапорцями SMS/call-log, уникаючи дубльованої job пакування debug APK на кожному Android-релевантному push. +GitHub може позначати замінені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це CI-шумом, якщо найновіший run для того самого ref також не падає. Агрегатні shard-перевірки використовують `!cancelled() && always()`, тож вони все ще повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже був замінений. +Автоматичний CI concurrency key версійовано (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безстроково блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують runs, що вже виконуються. ## Runner-и -| Runner | Завдання | +| Runner | Jobs | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі security jobs і aggregates (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled checks, sharded channel contract checks, shard-и `check`, крім lint, shard-и й aggregates `check-additional`, Node test aggregate verifiers, docs checks, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла стати в чергу раніше | +| `ubuntu-24.04` | `preflight`, швидкі security jobs і агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled перевірки, sharded channel contract checks, `check` shards окрім lint, `check-additional` shards і агрегати, Node test aggregate verifiers, docs checks, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла стати в чергу раніше | | `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node test shards, bundled plugin test shards, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо CPU-sensitive, що 8 vCPU коштували більше, ніж заощадили; install-smoke Docker builds, де час у queue для 32-vCPU коштував більше, ніж заощадив | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо CPU-чутливим, щоб 8 vCPU коштували більше, ніж заощаджували; install-smoke Docker builds, де час очікування в черзі для 32-vCPU коштував більше, ніж заощаджував | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; forks повертаються до `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; forks повертаються до `macos-latest` | @@ -377,5 +368,5 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## Пов’язане -- [Огляд установлення](/uk/install) -- [Канали релізів](/uk/install/development-channels) +- [Огляд встановлення](/uk/install) +- [Канали випусків](/uk/install/development-channels) diff --git a/docs/uk/cli/infer.md b/docs/uk/cli/infer.md index 3ecff166d..e2e012bdc 100644 --- a/docs/uk/cli/infer.md +++ b/docs/uk/cli/infer.md @@ -1,39 +1,39 @@ --- read_when: - - Додавання або змінення `openclaw infer` команд - - Проєктування стабільної автоматизації можливостей без інтерфейсу -summary: CLI, орієнтований насамперед на інференс, для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом та ембедингами на базі провайдерів + - Додавання або змінення команд `openclaw infer` + - Проєктування стабільної безінтерфейсної автоматизації можливостей +summary: CLI з підходом infer-first для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом та ембедингами, що підтримуються провайдерами title: CLI для інференсу x-i18n: - generated_at: "2026-04-28T17:56:08Z" + generated_at: "2026-04-28T20:11:19Z" model: gpt-5.5 provider: openai - source_hash: b284a884605ee7c0095652bf1b947dbc2ce78ef70532a161d97553379f348f6b + source_hash: 8a154cf11a09f6c60117740f42937da3a0e6942931dde6eee6d902fb6e0ba461 source_path: cli/infer.md workflow: 16 --- -`openclaw infer` — це канонічна headless-поверхня для робочих процесів інференсу на базі провайдерів. +`openclaw infer` є канонічною безголовою поверхнею для робочих процесів інференсу на основі провайдерів. -Вона навмисно надає сімейства можливостей, а не сирі назви RPC Gateway і не сирі ідентифікатори інструментів агента. +Вона навмисно відкриває сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента. -## Перетворіть infer на навичку +## Перетворіть infer на skill -Скопіюйте та вставте це в агента: +Скопіюйте й вставте це в агент: ```text Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`. Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings. ``` -Добра навичка на основі infer має: +Якісний skill на основі infer має: -- зіставляти типові наміри користувача з правильной підкомандою infer -- містити кілька канонічних прикладів infer для робочих процесів, які вона охоплює +- зіставляти поширені наміри користувача з правильним підкомандним рядком infer +- містити кілька канонічних прикладів infer для робочих процесів, які він охоплює - надавати перевагу `openclaw infer ...` у прикладах і пропозиціях -- уникати повторного документування всієї поверхні infer в тілі навички +- уникати повторного документування всієї поверхні infer у тілі skill -Типове покриття навички, зосередженої на infer: +Типове покриття skill, зосередженого на infer: - `openclaw infer model run` - `openclaw infer image generate` @@ -44,19 +44,19 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## Навіщо використовувати infer -`openclaw infer` надає один узгоджений CLI для завдань інференсу на базі провайдерів усередині OpenClaw. +`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу на основі провайдерів усередині OpenClaw. Переваги: -- Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда. -- Тримайте робочі процеси для моделей, зображень, транскрибування аудіо, TTS, відео, вебу та embeddings в одному дереві команд. -- Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентом. -- Надавайте перевагу першосторонній поверхні OpenClaw, коли завдання по суті є «запустити інференс». -- Для більшості команд infer використовуйте звичайний локальний шлях без вимоги Gateway. +- Використовуйте провайдери й моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда. +- Тримайте робочі процеси для моделей, зображень, транскрипції аудіо, TTS, відео, вебу та embeddings в одному дереві команд. +- Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентами. +- Надавайте перевагу першосторонній поверхні OpenClaw, коли завдання по суті полягає в «запуску інференсу». +- Для більшості команд infer використовуйте звичайний локальний шлях без потреби в Gateway. Для наскрізних перевірок провайдерів надавайте перевагу `openclaw infer ...`, коли нижчорівневі -тести провайдера вже зелені. Це перевіряє поставлений CLI, завантаження конфігурації, -розв’язання агента за замовчуванням, активацію вбудованого Plugin, відновлення runtime-залежностей +тести провайдерів уже зелені. Це перевіряє відвантажений CLI, завантаження конфігурації, +розв’язання агента за замовчуванням, активацію вбудованого Plugin, відновлення залежностей виконання і спільний runtime можливостей до виконання запиту до провайдера. ## Дерево команд @@ -110,42 +110,43 @@ Focus on model runs, image generation, video generation, audio transcription, TT providers ``` -## Типові завдання +## Поширені завдання -Ця таблиця зіставляє типові завдання інференсу з відповідною командою infer. +Ця таблиця зіставляє поширені завдання інференсу з відповідною командою infer. | Завдання | Команда | Примітки | | ---------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Запустити текстовий/модельний prompt | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях | -| Запустити модельний prompt із зображеннями | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Повторіть `--file` для кількох вхідних зображень | -| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, коли починаєте з наявного файла | -| Описати файл зображення | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` має бути моделлю з підтримкою зображень у формі `` | -| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `` | -| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на Gateway | +| Запустити модельний prompt для зображень | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Повторіть `--file` для кількох вхідних зображень | +| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, коли починаєте з наявного файлу | +| Описати файл зображення | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` має бути моделлю з підтримкою зображень у форматі `` | +| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `` | +| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на Gateway | | Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки провайдера, як-от `--resolution` | -| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `` | +| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `` | | Шукати в інтернеті | `openclaw infer web search --query "..." --json` | | | Отримати вебсторінку | `openclaw infer web fetch --url https://example.com --json` | | | Створити embeddings | `openclaw infer embedding create --text "..." --json` | | ## Поведінка -- `openclaw infer ...` — основна поверхня CLI для цих робочих процесів. +- `openclaw infer ...` є основною CLI-поверхнею для цих робочих процесів. - Використовуйте `--json`, коли вивід споживатиме інша команда або скрипт. - Використовуйте `--provider` або `--model provider/model`, коли потрібен конкретний бекенд. - Для `image describe`, `audio transcribe` і `video describe` `--model` має використовувати форму ``. -- Для `image describe` явний `--model` запускає цей provider/model напряму. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений хід Codex app-server для розуміння зображень; `openai-codex/` використовує шлях OpenAI Codex OAuth provider. -- Команди виконання без стану за замовчуванням локальні. +- Для `image describe` явний `--model` запускає цей provider/model напряму. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений крок розуміння зображення через Codex app-server; `openai-codex/` використовує шлях провайдера OpenAI Codex OAuth. +- Команди виконання без стану за замовчуванням використовують локальний режим. - Команди стану, керованого Gateway, за замовчуванням використовують Gateway. - Звичайний локальний шлях не потребує запущеного Gateway. -- Локальний `model run` — це компактне одноразове завершення провайдера. Він розв’язує налаштовану модель агента й автентифікацію, але не запускає хід chat-agent, не завантажує інструменти й не відкриває вбудовані MCP-сервери. +- Локальний `model run` — це легке одноразове завершення через провайдера. Він розв’язує налаштовану модель агента й авторизацію, але не запускає крок чат-агента, не завантажує інструменти й не відкриває вбудовані MCP-сервери. - `model run --file` приймає файли зображень, визначає їхній MIME-тип і надсилає їх із наданим prompt до вибраної моделі. Повторіть `--file` для кількох зображень. - `model run --file` відхиляє вхідні дані, що не є зображеннями. Використовуйте `infer audio transcribe` для аудіофайлів і `infer video describe` для відеофайлів. -- `model run --gateway` перевіряє маршрутизацію Gateway, збережену автентифікацію, вибір провайдера та вбудований runtime, але все одно працює як сирий модельний probe: він надсилає наданий prompt і будь-які вкладення зображень без попереднього transcript сеансу, bootstrap/AGENTS context, складання context-engine, інструментів або вбудованих MCP-серверів. +- `model run --gateway` перевіряє маршрутизацію Gateway, збережену авторизацію, вибір провайдера й вбудований runtime, але все одно працює як сирий модельний пробник: він надсилає наданий prompt і будь-які вкладення зображень без попереднього transcript сесії, bootstrap/AGENTS-контексту, збирання context-engine, інструментів або вбудованих MCP-серверів. +- `model run --gateway --model ` потребує довіреного операторського облікового запису Gateway, оскільки запит просить Gateway виконати одноразове перевизначення provider/model. ## Модель -Використовуйте `model` для текстового інференсу на базі провайдерів і перевірки моделей/провайдерів. +Використовуйте `model` для текстового інференсу на основі провайдерів і перевірки моделей/провайдерів. ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -155,7 +156,7 @@ openclaw infer model providers --json openclaw infer model inspect --name gpt-5.5 --json ``` -Використовуйте повні посилання ``, щоб виконати smoke-test конкретного провайдера без +Використовуйте повні посилання ``, щоб smoke-тестувати конкретного провайдера без запуску Gateway або завантаження повної поверхні інструментів агента: ```bash @@ -170,18 +171,18 @@ openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe Примітки: -- Локальний `model run` — це найвужчий CLI smoke для перевірки стану provider/model/auth, бо він надсилає лише наданий prompt до вибраної моделі. -- Локальний `model run --file` зберігає цей компактний шлях і додає вміст зображення безпосередньо до одного повідомлення користувача. Поширені файли зображень, як-от PNG, JPEG і WebP, працюють, коли їхній MIME-тип визначено як `image/*`; непідтримувані або нерозпізнані файли завершуються помилкою до виклику провайдера. -- `model run --file` найкраще підходить, коли ви хочете напряму протестувати вибрану мультимодальну текстову модель. Використовуйте `infer image describe`, коли вам потрібні вибір провайдера розуміння зображень OpenClaw і маршрутизація image-model за замовчуванням. -- Вибрана модель має підтримувати вхідні зображення; моделі лише для тексту можуть відхилити запит на рівні провайдера. -- `model run --prompt` має містити текст не лише з пробілів; порожні prompts відхиляються до виклику локальних провайдерів або Gateway. -- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстового виводу, тож недосяжні локальні провайдери й порожні завершення не виглядають як успішні probes. -- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування agent-runtime або стан провайдера, керований Gateway, зберігаючи вхідні дані моделі сирими. Використовуйте `openclaw agent` або chat-поверхні, коли потрібні повний контекст агента, інструменти, пам’ять і transcript сеансу. -- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом автентифікації провайдера. +- Локальний `model run` є найвужчим CLI-smoke для справності provider/model/auth, оскільки він надсилає вибраній моделі лише наданий prompt. +- Локальний `model run --file` зберігає цей легкий шлях і прикріплює вміст зображення напряму до єдиного повідомлення користувача. Поширені файли зображень, як-от PNG, JPEG і WebP, працюють, коли їхній MIME-тип визначено як `image/*`; непідтримувані або нерозпізнані файли зазнають помилки до виклику провайдера. +- `model run --file` найкраще підходить, коли потрібно напряму протестувати вибрану мультимодальну текстову модель. Використовуйте `infer image describe`, коли потрібні вибір провайдера розуміння зображень OpenClaw і маршрутизація до моделі зображень за замовчуванням. +- Вибрана модель має підтримувати вхідні зображення; текстові-only моделі можуть відхилити запит на рівні провайдера. +- `model run --prompt` має містити текст не лише з пробільних символів; порожні prompts відхиляються до виклику локальних провайдерів або Gateway. +- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстового виводу, тому недосяжні локальні провайдери й порожні completions не виглядають як успішні проби. +- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування agent-runtime або стан провайдера, керований Gateway, зберігаючи модельний вхід сирим. Використовуйте `openclaw agent` або чат-поверхні, коли потрібні повний контекст агента, інструменти, пам’ять і transcript сесії. +- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом авторизації провайдера. ## Зображення -Використовуйте `image` для генерації, редагування та опису. +Використовуйте `image` для генерації, редагування й опису. ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json @@ -201,16 +202,16 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p - Використовуйте `image edit`, коли починаєте з наявних вхідних файлів. - Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для - провайдерів/моделей, що підтримують геометричні підказки під час редагування reference-image. + провайдерів/моделей, які підтримують підказки геометрії під час редагування референсних зображень. - Використовуйте `--output-format png --background transparent` з `--model openai/gpt-image-1.5` для PNG-виводу OpenAI з прозорим фоном; - `--openai-background` залишається доступним як специфічний для OpenAI псевдонім. Провайдери, - які не оголошують підтримку фону, повідомляють підказку як проігнороване перевизначення. + `--openai-background` залишається доступним як специфічний для OpenAI alias. Провайдери, + які не оголошують підтримку фону, повідомляють цю підказку як проігнороване перевизначення. - Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень - можна виявити, налаштовано, вибрано, і які можливості генерації/редагування + виявляються, налаштовані, вибрані та які можливості генерації/редагування надає кожен провайдер. - Використовуйте `image generate --model --json` як найвужчий live - CLI smoke для змін генерації зображень. Приклад: + CLI-smoke для змін генерації зображень. Приклад: ```bash openclaw infer image providers --json @@ -221,14 +222,14 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p --json ``` - Відповідь JSON повідомляє `ok`, `provider`, `model`, `attempts` і записані - шляхи виводу. Коли задано `--output`, кінцеве розширення може відповідати - MIME-типу, поверненому постачальником. + JSON-відповідь повідомляє `ok`, `provider`, `model`, `attempts` і шляхи + записаних вихідних файлів. Коли задано `--output`, кінцеве розширення може відповідати + MIME-типу, який повернув провайдер. -- Для `image describe` і `image describe-many` використовуйте `--prompt`, щоб надати візійній моделі інструкцію для конкретного завдання, наприклад OCR, порівняння, перевірку UI або стислий підпис. -- Використовуйте `--timeout-ms` із повільними локальними візійними моделями або холодними запусками Ollama. +- Для `image describe` та `image describe-many` використовуйте `--prompt`, щоб надати моделі комп’ютерного зору інструкцію для конкретного завдання, як-от OCR, порівняння, перевірка UI або стислий підпис. +- Використовуйте `--timeout-ms` з повільними локальними моделями комп’ютерного зору або холодними запусками Ollama. - Для `image describe` `--model` має бути моделлю `` із підтримкою зображень. -- Для локальних візійних моделей Ollama спершу завантажте модель і задайте для `OLLAMA_API_KEY` будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). +- Для локальних моделей комп’ютерного зору Ollama спочатку завантажте модель і задайте для `OLLAMA_API_KEY` будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). ## Аудіо @@ -247,7 +248,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso ## TTS -Використовуйте `tts` для синтезу мовлення та стану постачальника TTS. +Використовуйте `tts` для синтезу мовлення та стану TTS-провайдера. ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -258,12 +259,12 @@ openclaw infer tts status --json Примітки: -- `tts status` за замовчуванням використовує gateway, оскільки відображає стан TTS, керований gateway. -- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб переглядати й налаштовувати поведінку TTS. +- `tts status` за замовчуванням використовує Gateway, оскільки відображає стан TTS, керований Gateway. +- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб переглядати та налаштовувати поведінку TTS. ## Відео -Використовуйте `video` для генерації та опису. +Використовуйте `video` для генерування й опису. ```bash openclaw infer video generate --prompt "cinematic sunset over the ocean" --json @@ -274,7 +275,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js Примітки: -- `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх у середовище виконання генерації відео. +- `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх до середовища виконання генерування відео. - `--model` має бути `` для `video describe`. ## Веб @@ -290,11 +291,11 @@ openclaw infer web providers --json Примітки: -- Використовуйте `web providers`, щоб переглядати доступних, налаштованих і вибраних постачальників. +- Використовуйте `web providers`, щоб переглянути доступних, налаштованих і вибраних провайдерів. -## Embedding +## Вбудовування -Використовуйте `embedding` для створення векторів і перегляду постачальника embeddings. +Використовуйте `embedding` для створення векторів і перевірки провайдера вбудовувань. ```bash openclaw infer embedding create --text "friendly lobster" --json @@ -304,7 +305,7 @@ openclaw infer embedding providers --json ## Вивід JSON -Команди infer нормалізують вивід JSON у спільній обгортці: +Команди infer нормалізують вивід JSON у спільній оболонці: ```json { @@ -329,9 +330,9 @@ openclaw infer embedding providers --json - `outputs` - `error` -Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте -`path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві -для автоматизації замість аналізу stdout, призначеного для читання людиною. +Для команд генерування медіа `outputs` містить файли, записані OpenClaw. Використовуйте +`path`, `mimeType`, `size` і будь-які медіаспецифічні розміри в цьому масиві +для автоматизації замість розбору зрозумілого для людини stdout. ## Поширені помилки diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 7ddae191f..127fb8860 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -1,24 +1,24 @@ --- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу - - Ви змінюєте постановку сесій у чергу, записування транскрипту або поведінку блокування запису сесії + - Ви змінюєте постановку сеансів у чергу, запис транскриптів або поведінку блокування запису сеансу summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-04-27T09:29:56Z" - model: gpt-5.4 + generated_at: "2026-04-28T20:11:20Z" + model: gpt-5.5 provider: openai - source_hash: 7b7cb32238489e213680553d0c5ea13f32fecb6ee748a514b69dbe2d223661b0 + source_hash: 3f870abbd9ce724e04b32dfe6296ef0df10ebd5cc6d37492457dc77dfb868b8f source_path: concepts/agent-loop.md - workflow: 15 + workflow: 16 --- -Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі → -виконання інструментів → потокове надсилання відповідей → збереження. Це авторитетний шлях, який перетворює повідомлення -на дії та фінальну відповідь, зберігаючи узгодженість стану сесії. +Агентний цикл — це повний “реальний” запуск агента: приймання → збирання контексту → інференс моделі → +виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення +на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сеансу. -В OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потокові події, -поки модель думає, викликає інструменти та потоково виводить результат. У цьому документі пояснюється, як цей справжній цикл +В OpenClaw цикл — це один серіалізований запуск на сеанс, який генерує події життєвого циклу та потоку, +поки модель міркує, викликає інструменти й потоково видає результат. У цьому документі пояснено, як цей автентичний цикл з’єднаний наскрізно. ## Точки входу @@ -26,151 +26,152 @@ x-i18n: - Gateway RPC: `agent` і `agent.wait`. - CLI: команда `agent`. -## Як це працює (на високому рівні) +## Як це працює (загальний огляд) -1. RPC `agent` валідує параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`. +1. RPC `agent` перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу, одразу повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає модель + типові значення thinking/verbose/trace + - визначає модель + стандартні значення thinking/verbose/trace - завантажує знімок Skills - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - генерує **lifecycle end/error**, якщо вбудований цикл сам цього не згенерував + - генерує **завершення/помилку життєвого циклу**, якщо вбудований цикл не згенерує їх сам 3. `runEmbeddedPiAgent`: - - серіалізує запуски через черги на рівні сесії та глобальні черги - - визначає модель + профіль автентифікації та будує pi session - - підписується на події pi і потоково передає дельти асистента/інструментів - - застосовує timeout -> перериває запуск, якщо його перевищено - - повертає payload-и та метадані використання -4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`: + - серіалізує запуски через посеансові + глобальні черги + - визначає модель + профіль автентифікації та створює сеанс pi + - підписується на події pi й потоково передає дельти асистента/інструментів + - застосовує тайм-аут -> перериває запуск у разі перевищення + - повертає payload-и + метадані використання +4. `subscribeEmbeddedPiSession` мостить події pi-agent-core до потоку OpenClaw `agent`: - події інструментів => `stream: "tool"` - дельти асистента => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - - очікує на **lifecycle end/error** для `runId` + - чекає **завершення/помилки життєвого циклу** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## Постановка в чергу + конкурентність +## Черги + паралельність -- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) і, за потреби, також через глобальну доріжку. -- Це запобігає змаганням інструментів/сесій і зберігає узгоджену історію сесії. -- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. - Див. [Command Queue](/uk/concepts/queue). -- Записи транскрипту також захищені блокуванням запису сесії на файлі сесії. Це блокування - враховує процеси та базується на файлі, тому виявляє записувачів, які обходять внутрішньопроцесну чергу або походять +- Запуски серіалізуються за ключем сеансу (лінія сеансу) й опціонально через глобальну лінію. +- Це запобігає перегонам інструментів/сеансів і підтримує узгоджену історію сеансу. +- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які передаються до цієї системи ліній. + Див. [Черга команд](/uk/concepts/queue). +- Записи транскрипту також захищені блокуванням запису сеансу на файлі сеансу. Блокування + враховує процеси та базується на файлі, тому воно ловить записувачів, які обходять внутрішньопроцесну чергу або приходять з іншого процесу. -- Блокування запису сесії за замовчуванням не є реентерабельними. Якщо допоміжний код навмисно вкладає отримання +- Блокування запису сеансу за замовчуванням нерекурсивні. Якщо helper навмисно вкладає отримання того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через `allowReentrant: true`. -## Підготовка сесії + робочого простору +## Підготовка сеансу + робочого простору -- Робочий простір визначається та створюється; sandboxed-запуски можуть перенаправлятися до кореня робочого простору sandbox. -- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt. -- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt. -- Отримується блокування запису сесії; `SessionManager` відкривається та готується перед початком потокової передачі. Будь-який - подальший шлях перезапису, Compaction або усічення транскрипту повинен брати те саме блокування перед відкриттям або +- Робочий простір визначається й створюється; sandbox-запуски можуть перенаправлятися до кореня sandbox-робочого простору. +- Skills завантажуються (або повторно використовуються зі знімка) та інжектяться в env і prompt. +- Bootstrap/context-файли визначаються й інжектяться у звіт системного prompt-а. +- Отримується блокування запису сеансу; `SessionManager` відкривається й готується до потокової передачі. Будь-який + подальший шлях переписування транскрипту, Compaction або скорочення має взяти те саме блокування перед відкриттям або зміною файлу транскрипту. -## Збирання prompt + системний prompt +## Збирання prompt-а + системний prompt -- Системний prompt будується з базового prompt OpenClaw, prompt для Skills, bootstrap-контексту та перевизначень для конкретного запуску. -- Застосовуються специфічні для моделі обмеження та резерв токенів для Compaction. -- Див. [System prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель. +- Системний prompt будується з базового prompt-а OpenClaw, prompt-а Skills, bootstrap-контексту та перевизначень для запуску. +- Застосовуються модельно-специфічні ліміти та резерв токенів для Compaction. +- Див. [Системний prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель. -## Точки перехоплення (де можна втрутитися) +## Точки hook-ів (де можна перехоплювати) -OpenClaw має дві системи хуків: +OpenClaw має дві системи hook-ів: -- **Внутрішні хуки** (хуки Gateway): скрипти, що реагують на події команд і події життєвого циклу. -- **Plugin hooks**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. +- **Внутрішні hook-и** (hook-и Gateway): подієві скрипти для команд і подій життєвого циклу. +- **Hook-и Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. -### Внутрішні хуки (хуки Gateway) +### Внутрішні hook-и (hook-и Gateway) -- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt. +- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt-а. Використовуйте це, щоб додавати/видаляти файли bootstrap-контексту. -- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію Hooks). +- **Hook-и команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію про hook-и). -Див. [Hooks](/uk/automation/hooks), щоб переглянути налаштування та приклади. +Див. [Hook-и](/uk/automation/hooks) для налаштування та прикладів. -### Plugin hooks (життєвий цикл агента + gateway) +### Hook-и Plugin (життєвий цикл агента + gateway) -Вони запускаються всередині циклу агента або конвеєра gateway: +Вони виконуються всередині циклу агента або конвеєра gateway: -- **`before_model_resolve`**: виконується до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі. -- **`before_prompt_build`**: виконується після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на поточний хід, а поля системного контексту — для стабільних вказівок, які мають залишатися в просторі системного prompt. -- **`before_agent_start`**: застарілий хук сумісності, який може виконуватися в будь-якій фазі; надавайте перевагу явним хукам вище. -- **`before_agent_reply`**: виконується після вбудованих дій і перед викликом LLM, дозволяючи плагіну перехопити хід і повернути синтетичну відповідь або повністю приглушити хід. -- **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення. -- **`before_compaction` / `after_compaction`**: дають змогу спостерігати або анотувати цикли Compaction. +- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити provider/model перед визначенням моделі. +- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб інжектити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt-а. Використовуйте `prependContext` для динамічного тексту на хід і поля системного контексту для стабільних настанов, які мають бути в просторі системного prompt-а. +- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hook-ам вище. +- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, дозволяючи Plugin забрати хід і повернути синтетичну відповідь або повністю приглушити хід. +- **`agent_end`**: перевіряє фінальний список повідомлень і метадані запуску після завершення. +- **`before_compaction` / `after_compaction`**: спостерігають або анотують цикли Compaction. - **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів. -- **`before_install`**: дає змогу перевірити вбудовані результати сканування та за потреби заблокувати встановлення skill або plugin. -- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані в транскрипт сесії, що належить OpenClaw. -- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних і вихідних повідомлень. -- **`session_start` / `session_end`**: межі життєвого циклу сесії. +- **`before_install`**: перевіряє вбудовані результати сканування та опціонально блокує встановлення skill або Plugin. +- **`tool_result_persist`**: синхронно трансформує результати інструментів перед записом у транскрипт сеансу, який належить OpenClaw. +- **`message_received` / `message_sending` / `message_sent`**: hook-и вхідних + вихідних повідомлень. +- **`session_start` / `session_end`**: межі життєвого циклу сеансу. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила прийняття рішень хуками для захисту вихідних повідомлень/інструментів: +Правила ухвалення рішень hook-ами для outbound/tool-запобіжників: -- `before_tool_call`: `{ block: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. -- `before_install`: `{ block: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. -- `message_sending`: `{ cancel: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. +- `before_tool_call`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` нічого не робить і не знімає попереднє блокування. +- `before_install`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. +- `before_install`: `{ block: false }` нічого не робить і не знімає попереднє блокування. +- `message_sending`: `{ cancel: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` нічого не робить і не знімає попереднє скасування. -Див. [Plugin hooks](/uk/plugins/hooks), щоб переглянути API хуків і подробиці реєстрації. +Див. [Hook-и Plugin](/uk/plugins/hooks) для API hook-ів і деталей реєстрації. -Harness-оточення можуть адаптувати ці хуки по-різному. Harness app-server у Codex зберігає -Plugin hooks OpenClaw як контракт сумісності для документованих дзеркальних -поверхонь, тоді як нативні хуки Codex залишаються окремим низькорівневим механізмом Codex. +Harness-и можуть адаптувати ці hook-и по-різному. Harness app-server Codex зберігає +hook-и Plugin OpenClaw як контракт сумісності для задокументованих дзеркальних +поверхонь, тоді як нативні hook-и Codex залишаються окремим нижчорівневим механізмом Codex. ## Потокова передача + часткові відповіді -- Дельти асистента потоково передаються з pi-agent-core та генеруються як події `assistant`. -- Потокова передача блоків може видавати часткові відповіді або на `text_end`, або на `message_end`. -- Потокову передачу міркувань можна видавати як окремий потік або як відповіді блоками. -- Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про нарізання на фрагменти та поведінку відповідей блоками. +- Дельти асистента потоково надходять із pi-agent-core і генеруються як події `assistant`. +- Блокова потокова передача може генерувати часткові відповіді або на `text_end`, або на `message_end`. +- Потокове міркування може генеруватися як окремий потік або як блокові відповіді. +- Див. [Потокова передача](/uk/concepts/streaming) щодо поведінки chunking і блокових відповідей. -## Виконання інструментів + інструменти обміну повідомленнями +## Виконання інструментів + інструменти повідомлень -- Події початку/оновлення/завершення інструмента генеруються в потоці `tool`. -- Результати інструментів очищуються з урахуванням розміру та зображень перед логуванням/генерацією подій. -- Надсилання інструментами обміну повідомленнями відстежуються, щоб уникати дубльованих підтверджень від асистента. +- Події старту/оновлення/завершення інструменту генеруються в потоці `tool`. +- Результати інструментів очищаються за розміром і payload-ами зображень перед логуванням/генеруванням. +- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дублікати підтверджень асистента. -## Формування відповіді + приглушення +## Формування відповіді + пригнічення - Фінальні payload-и збираються з: - - тексту асистента (і, за потреби, міркувань) - - вбудованих зведень інструментів (коли verbose увімкнено й дозволено) - - тексту помилки асистента, якщо модель повернула помилку -- Точний маркер тиші `NO_REPLY` / `no_reply` відфільтровується з вихідних + - тексту асистента (та опціонального міркування) + - inline-підсумків інструментів (коли verbose + дозволено) + - тексту помилки асистента, коли модель помиляється +- Точний мовчазний токен `NO_REPLY` / `no_reply` фільтрується з вихідних payload-ів. -- Дублікати інструментів обміну повідомленнями видаляються з фінального списку payload-ів. -- Якщо не залишилося жодних payload-ів, які можна відобразити, і інструмент повернув помилку, генерується - резервна відповідь про помилку інструмента (якщо тільки інструмент обміну повідомленнями вже не надіслав видиму для користувача відповідь). +- Дублікати інструментів повідомлень видаляються з фінального списку payload-ів. +- Якщо не лишається придатних до рендерингу payload-ів і інструмент завершився з помилкою, генерується fallback-відповідь про помилку інструменту + (якщо інструмент повідомлень уже не надіслав видиму для користувача відповідь). ## Compaction + повторні спроби -- Автоматичний Compaction генерує події потоку `compaction` і може спричинити повторну спробу. -- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дубльованого виводу. -- Див. [Compaction](/uk/concepts/compaction), щоб переглянути конвеєр Compaction. +- Автоматичний Compaction генерує події потоку `compaction` і може запускати повторну спробу. +- Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу. +- Див. [Compaction](/uk/concepts/compaction) щодо конвеєра Compaction. ## Потоки подій (сьогодні) -- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) +- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як fallback через `agentCommand`) - `assistant`: потокові дельти з pi-agent-core -- `tool`: потокові події інструментів з pi-agent-core +- `tool`: потокові події інструментів із pi-agent-core -## Обробка chat-каналу +## Обробка чат-каналу -- Дельти асистента буферизуються в chat-повідомлення `delta`. -- Chat `final` генерується на **lifecycle end/error**. +- Дельти асистента буферизуються в чат-повідомлення `delta`. +- Чат `final` генерується на **завершення/помилку життєвого циклу**. ## Тайм-аути -- Типове значення `agent.wait`: 30s (лише очікування). Його перевизначає параметр `timeoutMs`. -- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800s (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. -- Тайм-аут бездіяльності моделі: OpenClaw перериває запит моделі, якщо до завершення вікна бездіяльності не надходять фрагменти відповіді. `models.providers..timeoutSeconds` подовжує цей сторож бездіяльності для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, з обмеженням 120s за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі чи агента вимикають сторож бездіяльності й покладаються на зовнішній тайм-аут Cron. -- Тайм-аут HTTP-запиту provider-а: `models.providers..timeoutSeconds` застосовується до HTTP fetch-запитів моделі цього provider-а, зокрема до з’єднання, заголовків, тіла, тайм-ауту запиту SDK, обробки переривання guarded-fetch за загальним тайм-аутом і сторожа бездіяльності потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, таких як Ollama, перш ніж збільшувати тайм-аут усього часу виконання агента. +- Стандартно для `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. +- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedPiAgent`. +- Відновлення завислого сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` виявляє довгі сеанси `processing`. Активні вбудовані запуски, активні операції відповіді та активні задачі лінії сеансу за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сеансу, watchdog звільняє відповідну лінію сеансу, щоб запланована стартова робота могла завершитися. +- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять chunks відповіді. `models.providers..timeoutSeconds` розширює цей idle watchdog для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли налаштовано, з верхньою межею 120 с за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron. +- Тайм-аут HTTP-запиту provider-а: `models.providers..timeoutSeconds` застосовується до HTTP-fetch-ів моделі цього provider-а, включно з connect, headers, body, тайм-аутом запиту SDK, загальною обробкою guarded-fetch abort і idle watchdog потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, як-от Ollama, перед підвищенням тайм-ауту всього середовища виконання агента. ## Де все може завершитися раніше @@ -181,8 +182,8 @@ Plugin hooks OpenClaw як контракт сумісності для доку ## Пов’язане -- [Tools](/uk/tools) — доступні інструменти агента -- [Hooks](/uk/automation/hooks) — скрипти, що реагують на події, які запускаються подіями життєвого циклу агента +- [Інструменти](/uk/tools) — доступні інструменти агента +- [Hook-и](/uk/automation/hooks) — подієві скрипти, що запускаються подіями життєвого циклу агента - [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови -- [Exec Approvals](/uk/tools/exec-approvals) — етапи схвалення для shell-команд -- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/міркувань +- [Схвалення Exec](/uk/tools/exec-approvals) — ворота схвалення для shell-команд +- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning diff --git a/docs/uk/concepts/queue.md b/docs/uk/concepts/queue.md index 932263353..372ce3827 100644 --- a/docs/uk/concepts/queue.md +++ b/docs/uk/concepts/queue.md @@ -1,48 +1,49 @@ --- read_when: - - Зміна виконання або паралелізму автовідповіді -summary: Проєктування черги команд, яка серіалізує вхідні запуски автовідповіді -title: черга команд + - Зміна виконання автоматичних відповідей або паралельності +summary: Проєктування черги команд, що послідовно виконує вхідні запуски автовідповіді +title: Черга команд x-i18n: - generated_at: "2026-04-27T08:45:01Z" - model: gpt-5.4 + generated_at: "2026-04-28T20:11:10Z" + model: gpt-5.5 provider: openai - source_hash: 8fa2d4953ba8a3d9be7080599e550c796ccedf622a9467bf77e50454b6ea4c4a + source_hash: 8ed2bd9fad7f35f124b99c570703ddd075c742391061a977323c28feaf3ab508 source_path: concepts/queue.md - workflow: 15 + workflow: 16 --- -Ми серіалізуємо вхідні запуски автовідповіді (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями. +Ми серіалізуємо вхідні запуски автовідповідей (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями. ## Чому -- Запуски автовідповіді можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. -- Серіалізація дозволяє уникнути конкуренції за спільні ресурси (файли сесії, журнали, CLI stdin) і зменшує ймовірність лімітів з боку зовнішніх сервісів. +- Запуски автовідповідей можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. +- Серіалізація дає змогу уникнути конкуренції за спільні ресурси (файли сесій, журнали, CLI stdin) і зменшує ймовірність лімітів частоти від upstream-сервісів. ## Як це працює -- FIFO-черга з урахуванням смуг обробляє кожну смугу з налаштовуваним обмеженням паралелізму (типово 1 для неналаштованих смуг; для main типово 4, для subagent — 8). -- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (смуга `session:`), щоб гарантувати лише один активний запуск на сесію. -- Потім кожен запуск сесії ставиться в **глобальну смугу** (`main` типово), щоб загальний паралелізм обмежувався через `agents.defaults.maxConcurrent`. -- Коли увімкнено докладне журналювання, запуски в черзі виводять коротке повідомлення, якщо вони чекали понад ~2 с перед стартом. -- Індикатори набору тексту все одно спрацьовують одразу під час додавання в чергу (коли це підтримується каналом), тому користувацький досвід не змінюється, поки ми чекаємо своєї черги. +- FIFO-черга з урахуванням lane обробляє кожну lane з настроюваним лімітом паралельності (типово 1 для неналаштованих lane; main типово 4, subagent — 8). +- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (lane `session:`), щоб гарантувати лише один активний запуск на сесію. +- Потім кожен запуск сесії ставиться в **глобальну lane** (`main` типово), тож загальний паралелізм обмежується `agents.defaults.maxConcurrent`. +- Коли ввімкнено докладне журналювання, запуски в черзі виводять коротке повідомлення, якщо чекали понад ~2 с перед стартом. +- Індикатори набору все одно спрацьовують одразу під час додавання в чергу (коли канал це підтримує), тож користувацький досвід не змінюється, поки ми чекаємо своєї черги. ## Режими черги (для кожного каналу) -Вхідні повідомлення можуть керувати поточним запуском, чекати наступного ходу або робити обидва варіанти: +Вхідні повідомлення можуть спрямовувати поточний запуск, чекати на наступний хід або робити і те, й інше: -- `steer`: негайно інʼєктується в поточний запуск (скасовує відкладені виклики інструментів після наступної межі інструмента). Якщо потокова передача не активна, використовується резервний перехід до followup. -- `followup`: ставиться в чергу на наступний хід агента після завершення поточного запуску. -- `collect`: обʼєднує всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення націлені на різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію. -- `steer-backlog` (також `steer+backlog`): спрямовує зараз **і** зберігає повідомлення для наступного ходу. -- `interrupt` (застаріле): перериває активний запуск для цієї сесії, а потім запускає найновіше повідомлення. +- `steer`: негайно вставити в поточний запуск (скасовує очікувані виклики інструментів після наступної межі інструмента). Якщо streaming не використовується, повертається до followup. +- `followup`: поставити в чергу для наступного ходу агента після завершення поточного запуску. +- `collect`: об’єднати всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення спрямовані в різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію. +- `steer-backlog` (також `steer+backlog`): спрямувати зараз **і** зберегти повідомлення для наступного ходу. +- `interrupt` (застарілий): перервати активний запуск для цієї сесії, потім запустити найновіше повідомлення. - `queue` (застарілий псевдонім): те саме, що `steer`. -Steer-backlog означає, що ви можете отримати наступну відповідь після спрямованого запуску, тому на поверхнях зі стримінгом це може виглядати як дублікати. Віддавайте перевагу `collect`/`steer`, якщо хочете -одну відповідь на одне вхідне повідомлення. -Надішліть `/queue collect` як окрему команду (для конкретної сесії) або встановіть `messages.queue.byChannel.discord: "collect"`. +Steer-backlog означає, що ви можете отримати наступну відповідь після спрямованого запуску, тому +поверхні streaming можуть виглядати як дублікати. Надавайте перевагу `collect`/`steer`, якщо хочете +одну відповідь на кожне вхідне повідомлення. +Надішліть `/queue collect` як окрему команду (для сесії) або задайте `messages.queue.byChannel.discord: "collect"`. -Типові значення (якщо не задані в конфігурації): +Типові значення (коли не задано в конфігурації): - Усі поверхні → `collect` @@ -64,33 +65,34 @@ Steer-backlog означає, що ви можете отримати насту ## Параметри черги -Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він резервно переходить до followup): +Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він повертається до followup): -- `debounceMs`: очікувати тиші перед початком наступного ходу (запобігає “continue, continue”). +- `debounceMs`: чекати тиші перед запуском наступного ходу (запобігає “continue, continue”). - `cap`: максимальна кількість повідомлень у черзі на сесію. - `drop`: політика переповнення (`old`, `new`, `summarize`). -Summarize зберігає короткий маркований список відкинутих повідомлень і інʼєктує його як синтетичний followup-промпт. +Summarize зберігає короткий маркований список відкинутих повідомлень і вставляє його як синтетичний followup prompt. Типові значення: `debounceMs: 1000`, `cap: 20`, `drop: summarize`. ## Перевизначення для сесії - Надішліть `/queue ` як окрему команду, щоб зберегти режим для поточної сесії. - Параметри можна комбінувати: `/queue collect debounce:2s cap:25 drop:summarize` -- `/queue default` або `/queue reset` очищає перевизначення для сесії. +- `/queue default` або `/queue reset` очищає перевизначення сесії. ## Область дії та гарантії -- Застосовується до запусків агента автовідповіді в усіх вхідних каналах, які використовують конвеєр відповіді Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). -- Типова смуга (`main`) є загальнопроцесною для вхідних подій і основних Heartbeat; установіть `agents.defaults.maxConcurrent`, щоб дозволити паралельну обробку кількох сесій. -- Можуть існувати додаткові смуги (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно без блокування вхідних відповідей. Ізольовані ходи Cron-агента утримують слот `cron`, тоді як їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-Cron-потоки `nested` зберігають власну поведінку смуг. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). -- Смуги на рівні сесії гарантують, що лише один запуск агента одночасно працює з певною сесією. -- Жодних зовнішніх залежностей або фонових worker-потоків; лише TypeScript + promises. +- Застосовується до запусків агентів автовідповідей у всіх вхідних каналах, які використовують пайплайн відповідей Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). +- Типова lane (`main`) є процесною для вхідних повідомлень і main Heartbeat; задайте `agents.defaults.maxConcurrent`, щоб дозволити кілька сесій паралельно. +- Можуть існувати додаткові lane (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно, не блокуючи вхідні відповіді. Ізольовані ходи агента cron утримують слот `cron`, поки їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-cron потоки `nested` зберігають власну поведінку lane. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). +- Lane для сесій гарантують, що лише один запуск агента одночасно працює з певною сесією. +- Без зовнішніх залежностей або фонових робочих потоків; чистий TypeScript + promises. ## Усунення несправностей -- Якщо здається, що команди зависли, увімкніть докладні журнали та шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється. -- Якщо вам потрібна глибина черги, увімкніть докладні журнали та відстежуйте рядки з таймінгами черги. +- Якщо команди здаються завислими, увімкніть докладні журнали й шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється. +- Якщо вам потрібна глибина черги, увімкніть докладні журнали й стежте за рядками часу черги. +- Коли діагностику ввімкнено, сесії, що залишаються в `processing` довше за `diagnostics.stuckSessionWarnMs`, записують попередження про завислу сесію. Активні вбудовані запуски, активні операції відповіді та активні завдання lane типово залишаються лише попередженнями; застарілий стартовий облік без активної роботи сесії може звільнити відповідну lane сесії, щоб робота в черзі продовжилася. ## Пов’язане diff --git a/docs/uk/gateway/protocol.md b/docs/uk/gateway/protocol.md index db04bdf5c..17d686844 100644 --- a/docs/uk/gateway/protocol.md +++ b/docs/uk/gateway/protocol.md @@ -1,36 +1,35 @@ --- read_when: - - Впровадження або оновлення WS-клієнтів Gateway + - Реалізація або оновлення WS-клієнтів Gateway - Налагодження невідповідностей протоколу або збоїв підключення - Повторне генерування схеми/моделей протоколу -summary: 'Протокол WebSocket для Gateway: рукостискання, фрейми, версіонування' +summary: 'WebSocket-протокол Gateway: рукостискання, кадри, версіонування' title: Протокол Gateway x-i18n: - generated_at: "2026-04-28T11:13:37Z" + generated_at: "2026-04-28T20:11:25Z" model: gpt-5.5 provider: openai - source_hash: ab961f1ec245e93f5f88a641f558124c36c4c828ba66ff3a2ccd41ba1f12b646 + source_hash: 95845fc2aa56b0a53cf8c62c517b70d2624b15e707d84503c791af572360aff2 source_path: gateway/protocol.md workflow: 16 --- Протокол Gateway WS є **єдиною площиною керування + транспортом вузлів** для -OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android, -безголові вузли) підключаються через WebSocket і оголошують свою **роль** + -**область дії** під час рукостискання. +OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android, безголові +вузли) підключаються через WebSocket і оголошують свою **роль** + **область дії** під час +рукостискання. ## Транспорт - WebSocket, текстові кадри з JSON-навантаженнями. - Перший кадр **має** бути запитом `connect`. -- Кадри до підключення обмежені 64 КіБ. Після успішного рукостискання клієнтам - слід дотримуватися обмежень `hello-ok.policy.maxPayload` і +- Кадри до підключення обмежені 64 KiB. Після успішного рукостискання клієнти + мають дотримуватися лімітів `hello-ok.policy.maxPayload` і `hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено, - надмірно великі вхідні кадри та повільні вихідні буфери генерують події - `payload.large` перед тим, як Gateway закриє або відкине відповідний кадр. - Ці події зберігають розміри, обмеження, поверхні та безпечні коди причин. - Вони не зберігають тіло повідомлення, вміст вкладень, необроблене тіло кадру, - токени, cookie або секретні значення. + завеликі вхідні кадри та повільні вихідні буфери створюють події `payload.large` + до того, як Gateway закриє або відкине відповідний кадр. Ці події зберігають + розміри, ліміти, поверхні та безпечні коди причин. Вони не зберігають тіло + повідомлення, вміст вкладень, сире тіло кадру, токени, cookies або секретні значення. ## Рукостискання (connect) @@ -105,8 +104,8 @@ Gateway → Клієнт: } ``` -`server`, `features`, `snapshot` і `policy` є обов’язковими за схемою -(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і повідомляє +`server`, `features`, `snapshot` і `policy` усі є обов’язковими за схемою +(`src/gateway/protocol/schema/frames.ts`). `auth` також обов’язковий і повідомляє узгоджену роль/області дії. `canvasHostUrl` є необов’язковим. Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені @@ -121,14 +120,13 @@ Gateway → Клієнт: } ``` -Довірені клієнти бекенду в тому самому процесі (`client.id: "gateway-client"`, -`client.mode: "backend"`) можуть опускати `device` для прямих loopback-підключень, -коли автентифікуються спільним токеном/паролем Gateway. Цей шлях зарезервовано -для внутрішніх RPC площини керування, і він запобігає тому, щоб застарілі базові -дані сполучення CLI/пристрою блокували локальну роботу бекенду, як-от оновлення -сеансів субагентів. Віддалені клієнти, клієнти з браузерним origin, клієнти-вузли -та явні клієнти з токеном пристрою/ідентичністю пристрою все ще використовують -звичайні перевірки сполучення й підвищення областей дії. +Довірені клієнти бекенда в тому самому процесі (`client.id: "gateway-client"`, +`client.mode: "backend"`) можуть не вказувати `device` на прямих підключеннях local loopback, коли +вони автентифікуються спільним токеном/паролем Gateway. Цей шлях зарезервований +для внутрішніх RPC площини керування і не дає застарілим базовим станам спарювання CLI/пристрою +блокувати локальну роботу бекенда, як-от оновлення сесій субагентів. Віддалені клієнти, +клієнти з браузерним походженням, вузлові клієнти та явні клієнти токена пристрою/ідентичності пристрою +й надалі використовують звичайні перевірки спарювання та підвищення області дії. Коли токен пристрою видано, `hello-ok` також містить: @@ -163,12 +161,11 @@ Gateway → Клієнт: ``` Для вбудованого потоку bootstrap вузла/оператора основний токен вузла залишається -`scopes: []`, а будь-який переданий токен оператора залишається обмеженим списком -дозволів оператора bootstrap (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). Перевірки областей дії bootstrap -залишаються префіксованими роллю: записи оператора задовольняють лише запити -оператора, а неоператорським ролям і далі потрібні області дії з власним -префіксом ролі. +`scopes: []`, а будь-який переданий токен оператора залишається обмеженим allowlist оператора +bootstrap (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). Перевірки області дії bootstrap залишаються +префіксованими за роллю: записи оператора задовольняють лише запити оператора, а ролі, що не є операторами, +й надалі потребують областей дії під власним префіксом ролі. ### Приклад вузла @@ -205,7 +202,7 @@ Gateway → Клієнт: } ``` -## Фреймінг +## Обрамлення - **Запит**: `{type:"req", id, method, params}` - **Відповідь**: `{type:"res", id, ok, payload|error}` @@ -220,7 +217,7 @@ Gateway → Клієнт: - `operator` = клієнт площини керування (CLI/UI/автоматизація). - `node` = хост можливостей (camera/screen/canvas/system.run). -### Області дії (operator) +### Області дії (оператор) Поширені області дії: @@ -234,46 +231,45 @@ Gateway → Клієнт: `talk.config` з `includeSecrets: true` потребує `operator.talk.secrets` (або `operator.admin`). -Зареєстровані Plugin методи Gateway RPC можуть запитувати власну область дії -оператора, але зарезервовані префікси адміністрування ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) завжди розв’язуються до -`operator.admin`. +RPC-методи Gateway, зареєстровані Plugin, можуть запитувати власну область дії оператора, але +зарезервовані основні адміністративні префікси (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) завжди зіставляються з `operator.admin`. -Область дії методу є лише першою перевіркою. Деякі slash-команди, доступні через -`chat.send`, застосовують суворіші перевірки на рівні команди додатково. Наприклад, -постійні записи `/config set` і `/config unset` потребують `operator.admin`. +Область дії методу є лише першим шлюзом перевірки. Деякі slash-команди, доступні через +`chat.send`, застосовують поверх цього суворіші перевірки на рівні команд. Наприклад, постійні +записи `/config set` і `/config unset` потребують `operator.admin`. -`node.pair.approve` також має додаткову перевірку області дії під час схвалення -поверх базової області дії методу: +`node.pair.approve` також має додаткову перевірку області дії під час схвалення поверх +базової області дії методу: - запити без команд: `operator.pairing` - запити з не-exec командами вузла: `operator.pairing` + `operator.write` - запити, що містять `system.run`, `system.run.prepare` або `system.which`: `operator.pairing` + `operator.admin` -### Можливості/команди/дозволи (node) +### Можливості/команди/дозволи (вузол) Вузли оголошують претензії на можливості під час підключення: -- `caps`: високорівневі категорії можливостей. -- `commands`: список дозволених команд для invoke. -- `permissions`: деталізовані перемикачі (наприклад, `screen.record`, `camera.capture`). +- `caps`: категорії можливостей високого рівня. +- `commands`: allowlist команд для виклику. +- `permissions`: детальні перемикачі (наприклад, `screen.record`, `camera.capture`). -Gateway трактує їх як **претензії** та застосовує серверні списки дозволів. +Gateway розглядає їх як **претензії** і застосовує серверні allowlist. ## Присутність -- `system-presence` повертає записи, ключовані ідентичністю пристрою. -- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб інтерфейси могли показувати один рядок на пристрій - навіть коли він підключається і як **оператор**, і як **вузол**. +- `system-presence` повертає записи, ключовані за ідентичністю пристрою. +- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій + навіть коли він підключається і як **operator**, і як **node**. - `node.list` містить необов’язкові поля `lastSeenAtMs` і `lastSeenReason`. Підключені вузли повідомляють - свій поточний час підключення як `lastSeenAtMs` з причиною `connect`; сполучені вузли також можуть повідомляти - тривку фонову присутність, коли довірена подія вузла оновлює їхні метадані сполучення. + свій поточний час підключення як `lastSeenAtMs` з причиною `connect`; спарені вузли також можуть повідомляти + стійку фонову присутність, коли довірена подія вузла оновлює їхні метадані спарювання. -### Фонова подія життєздатності вузла +### Фонова подія активності вузла -Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що сполучений вузол був -активним під час фонового пробудження, не позначаючи його як підключений. +Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що спарений вузол був +активний під час фонового пробудження, не позначаючи його як підключений. ```json { @@ -283,9 +279,9 @@ Gateway трактує їх як **претензії** та застосову ``` `trigger` є закритим enum: `background`, `silent_push`, `bg_app_refresh`, -`significant_location`, `manual` або `connect`. Невідомі рядки тригерів Gateway нормалізує до -`background` перед збереженням. Подія є тривкою лише для автентифікованих сеансів пристроїв-вузлів; -сеанси без пристрою або без сполучення повертають `handled: false`. +`significant_location`, `manual` або `connect`. Невідомі рядки trigger нормалізуються до +`background` Gateway перед збереженням. Подія є стійкою лише для автентифікованих сесій +пристроїв вузлів; сесії без пристрою або без спарювання повертають `handled: false`. Успішні Gateway повертають структурований результат: @@ -298,71 +294,71 @@ Gateway трактує їх як **претензії** та застосову } ``` -Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнтам слід трактувати це як -підтверджений RPC, а не як тривке збереження присутності. +Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як +підтверджений RPC, а не як стійке збереження присутності. -## Обмеження областей дії широкомовних подій +## Обмеження області дії широкомовних подій -Широкомовні WebSocket-події, які сервер надсилає клієнтам, обмежуються областями дії, щоб сеанси з областю дії сполучення або лише вузлові сеанси пасивно не отримували вміст сеансів. +Серверні широкомовні події WebSocket обмежуються областями дії, щоб сесії, обмежені спарюванням або лише вузлами, пасивно не отримували вміст сесій. -- **Кадри чату, агента та результатів інструментів** (включно зі стримованими подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці кадри. -- **Визначені Plugin широкомовлення `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував. -- **Події стану й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл підключення/відключення тощо) залишаються необмеженими, щоб стан транспорту був видимим для кожного автентифікованого сеансу. -- **Невідомі сімейства широкомовних подій** за замовчуванням обмежуються областями дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх. +- **Кадри чату, агента та результатів інструментів** (зокрема потокові події `agent` і результати викликів інструментів) потребують щонайменше `operator.read`. Сесії без `operator.read` повністю пропускають ці кадри. +- **Визначені Plugin широкомовлення `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin зареєстрував їх. +- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл підключення/відключення тощо) залишаються без обмежень, щоб стан транспорту був видимий кожній автентифікованій сесії. +- **Невідомі родини широкомовних подій** за замовчуванням обмежуються областями дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх. -Кожне клієнтське підключення зберігає власний порядковий номер для кожного клієнта, щоб широкомовлення зберігали монотонний порядок у цьому сокеті, навіть коли різні клієнти бачать різні відфільтровані за областями дії підмножини потоку подій. +Кожне клієнтське підключення зберігає власний порядковий номер на клієнта, тому широкомовлення зберігають монотонне впорядкування на цьому сокеті, навіть коли різні клієнти бачать різні підмножини потоку подій, відфільтровані за областями дії. -## Поширені сімейства методів RPC +## Поширені родини RPC-методів Публічна поверхня WS ширша за наведені вище приклади рукостискання/автентифікації. Це -не згенерований дамп — `hello-ok.features.methods` є консервативним списком -виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажених -експортів методів Plugin/каналів. Трактуйте його як виявлення функцій, а не як повний +не згенерований дамп — `hello-ok.features.methods` є консервативним +списком виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажені +експорти методів plugin/channel. Сприймайте його як виявлення можливостей, а не повний перелік `src/gateway/server-methods/*.ts`. - `health` повертає кешований або щойно перевірений знімок стану Gateway. - - `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/Plugin і ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, необроблені тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область дії читання оператора. - - `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з областю дії admin. - - `gateway.identity.get` повертає ідентичність пристрою Gateway, що використовується потоками relay і сполучення. - - `system-presence` повертає поточний знімок присутності для підключених пристроїв оператора/вузла. - - `system-event` додає системну подію та може оновлювати/широкомовно передавати контекст присутності. - - `last-heartbeat` повертає останню збережену подію heartbeat. - - `set-heartbeats` перемикає обробку heartbeat на Gateway. + - `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/plugin і ідентифікатори сесій. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies або секретні значення. Потрібна область дії читання оператора. + - `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з адміністративною областю дії. + - `gateway.identity.get` повертає ідентичність пристрою Gateway, яку використовують потоки relay і спарювання. + - `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node. + - `system-event` додає системну подію і може оновлювати/транслювати контекст присутності. + - `last-heartbeat` повертає останню збережену подію Heartbeat. + - `set-heartbeats` перемикає обробку Heartbeat на Gateway. - - `models.list` повертає дозволений під час виконання каталог моделей. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спочатку, потім `models.providers.*.models`) або `{ "view": "all" }` для повного каталогу. - - `usage.status` повертає зведення вікон використання провайдера/залишкової квоти. + - `models.list` повертає каталог моделей, дозволених у runtime. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спочатку, потім `models.providers.*.models`), або `{ "view": "all" }` для повного каталогу. + - `usage.status` повертає вікна використання провайдера/зведення залишкової квоти. - `usage.cost` повертає агреговані зведення вартості використання за діапазон дат. - - `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного стандартного робочого простору агента. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче live ping провайдера embedding. - - `sessions.usage` повертає зведення використання за сеансами. - - `sessions.usage.timeseries` повертає часовий ряд використання для одного сеансу. - - `sessions.usage.logs` повертає записи журналу використання для одного сеансу. + - `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живий ping embedding-провайдера. + - `sessions.usage` повертає зведення використання за сесіями. + - `sessions.usage.timeseries` повертає часовий ряд використання для однієї сесії. + - `sessions.usage.logs` повертає записи журналу використання для однієї сесії. - - `channels.status` повертає зведення стану вбудованих + комплектних каналів/Plugin. - - `channels.logout` виходить із певного каналу/облікового запису, якщо канал підтримує вихід. - - `web.login.start` запускає QR/web-потік входу для поточного web-провайдера каналу з підтримкою QR. - - `web.login.wait` очікує завершення цього QR/web-потоку входу та в разі успіху запускає канал. - - `push.test` надсилає тестовий APNs push на зареєстрований вузол iOS. + - `channels.status` повертає зведення стану вбудованих + bundled каналів/Plugin. + - `channels.logout` виконує вихід із певного каналу/облікового запису, якщо канал підтримує вихід. + - `web.login.start` запускає потік QR/web-входу для поточного провайдера web-каналу з підтримкою QR. + - `web.login.wait` очікує завершення цього потоку QR/web-входу та запускає канал у разі успіху. + - `push.test` надсилає тестовий APNs push на зареєстрований iOS-вузол. - `voicewake.get` повертає збережені тригери wake-word. - `voicewake.set` оновлює тригери wake-word і транслює зміну. - - `send` є прямим outbound-delivery RPC для надсилань, націлених на канал/обліковий запис/тред, поза chat runner. - - `logs.tail` повертає налаштований фрагмент файлу журналу Gateway з керуванням cursor/limit і max-byte. + - `send` — це прямий RPC вихідної доставки для надсилань, націлених на канал/обліковий запис/потік, поза chat runner. + - `logs.tail` повертає налаштований фрагмент кінця файлового журналу gateway з керуванням cursor/limit і max-byte. - - - `talk.config` повертає ефективне корисне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`). + + - `talk.config` повертає ефективне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`). - `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI. - `talk.speak` синтезує мовлення через активного провайдера мовлення Talk. - `tts.status` повертає стан увімкнення TTS, активного провайдера, резервних провайдерів і стан конфігурації провайдера. @@ -374,78 +370,78 @@ Gateway трактує їх як **претензії** та застосову - - `secrets.reload` повторно розв'язує активні SecretRefs і замінює runtime-стан секретів лише за повного успіху. - - `secrets.resolve` розв'язує призначення секретів для цільових команд для певного набору команд/цілей. - - `config.get` повертає поточний знімок конфігурації та hash. - - `config.set` записує перевірене корисне навантаження конфігурації. - - `config.patch` зливає часткове оновлення конфігурації. - - `config.apply` перевіряє + замінює повне корисне навантаження конфігурації. - - `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують інструменти Control UI та CLI: schema, `uiHints`, version і метадані generation, включно з метаданими схеми plugin + каналу, коли runtime може їх завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, включно з вкладеними object, wildcard, array-item і гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація полів. - - `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований path, неглибокий вузол schema, matched hint + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля перевірки (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, numeric/string/array/object bounds і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів надають `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також matched `hint` / `hintPath`. - - `update.run` запускає потік оновлення Gateway і планує перезапуск лише тоді, коли саме оновлення завершилося успішно. - - `update.status` повертає останній кешований sentinel перезапуску оновлення, включно з версією, що працює після перезапуску, коли вона доступна. - - `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер onboarding через WS RPC. + - `secrets.reload` повторно розв’язує активні SecretRefs і замінює стан секретів runtime лише в разі повного успіху. + - `secrets.resolve` розв’язує призначення секретів, націлені на команду, для певного набору command/target. + - `config.get` повертає поточний знімок конфігурації та хеш. + - `config.set` записує перевірене навантаження конфігурації. + - `config.patch` об’єднує часткове оновлення конфігурації. + - `config.apply` перевіряє + замінює повне навантаження конфігурації. + - `config.schema` повертає живе навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: schema, `uiHints`, version і метадані генерації, зокрема метадані схем Plugin + каналів, коли runtime може їх завантажити. Схема містить метадані полів `title` / `description`, виведені з тих самих міток і довідкового тексту, які використовує UI, зокрема для вкладених об’єктів, wildcard, array-item і гілок композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля. + - `config.schema.lookup` повертає навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідну підказку + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля перевірки (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, межі numeric/string/array/object і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів містять `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також відповідні `hint` / `hintPath`. + - `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, коли саме оновлення успішне. + - `update.status` повертає останній кешований sentinel перезапуску оновлення, зокрема версію, що працює після перезапуску, коли вона доступна. + - `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` надають onboarding wizard через WS RPC. - `agents.list` повертає налаштовані записи агентів. - - `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив'язкою робочої області. - - `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами bootstrap робочої області, відкритими для агента. - - `agent.identity.get` повертає ефективну ідентичність асистента для агента або сеансу. - - `agent.wait` очікує завершення запуску та повертає кінцевий знімок, коли він доступний. + - `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив’язкою робочої області. + - `agents.files.list`, `agents.files.get` і `agents.files.set` керують bootstrap-файлами робочої області, доступними для агента. + - `agent.identity.get` повертає ефективну ідентичність асистента для агента або сесії. + - `agent.wait` очікує завершення запуску та повертає фінальний знімок, коли він доступний. - - - `sessions.list` повертає поточний індекс сеансів. - - `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події зміни сеансів для поточного клієнта WS. - - `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для одного сеансу. - - `sessions.preview` повертає обмежені попередні перегляди транскриптів для певних ключів сеансів. - - `sessions.resolve` розв'язує або канонізує ціль сеансу. - - `sessions.create` створює новий запис сеансу. - - `sessions.send` надсилає повідомлення в наявний сеанс. - - `sessions.steer` є варіантом interrupt-and-steer для активного сеансу. - - `sessions.abort` перериває активну роботу для сеансу. - - `sessions.patch` оновлює метадані/перевизначення сеансу. - - `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сеансу. - - `sessions.get` повертає повний збережений рядок сеансу. - - Виконання чату й надалі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення клієнтами UI: inline directive tags вилучаються з видимого тексту, plain-text XML-корисні навантаження tool-call (включно з `...`, `...`, `...`, `...` і обрізаними блоками tool-call) та витеклі ASCII/full-width токени керування моделі вилучаються, рядки асистента лише з silent-token, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а надмірно великі рядки можуть замінюватися placeholders. + + - `sessions.list` повертає поточний індекс сесій. + - `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події змін сесій для поточного WS-клієнта. + - `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для однієї сесії. + - `sessions.preview` повертає обмежені попередні перегляди транскриптів для певних ключів сесій. + - `sessions.resolve` розв’язує або канонізує ціль сесії. + - `sessions.create` створює новий запис сесії. + - `sessions.send` надсилає повідомлення в наявну сесію. + - `sessions.steer` — це варіант interrupt-and-steer для активної сесії. + - `sessions.abort` перериває активну роботу для сесії. + - `sessions.patch` оновлює метадані/перевизначення сесії. + - `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесії. + - `sessions.get` повертає повний збережений рядок сесії. + - Виконання чату й надалі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізується для відображення UI-клієнтам: inline directive tags вилучаються з видимого тексту, plain-text XML-навантаження викликів інструментів (зокрема `...`, `...`, `...`, `...` і обрізані блоки викликів інструментів) і leaked ASCII/full-width model control tokens вилучаються, рядки асистента лише з silent-token, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а надмірно великі рядки можуть замінюватися placeholders. - - - `device.pair.list` повертає очікувані та схвалені спарені пристрої. - - `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами спарювання пристроїв. - - `device.token.rotate` ротує токен спареного пристрою в межах його схваленої ролі та меж області дії викликача. - - `device.token.revoke` відкликає токен спареного пристрою в межах його схваленої ролі та меж області дії викликача. + + - `device.pair.list` повертає пристрої зі сполученням, які очікують підтвердження або вже схвалені. + - `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами сполучення пристроїв. + - `device.token.rotate` ротує токен сполученого пристрою в межах його схваленої ролі та області дії викликача. + - `device.token.revoke` відкликає токен сполученого пристрою в межах його схваленої ролі та області дії викликача. - - - `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють спарювання вузлів і bootstrap-перевірку. + + - `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють сполучення вузлів і bootstrap-перевірку. - `node.list` і `node.describe` повертають стан відомих/підключених вузлів. - - `node.rename` оновлює мітку спареного вузла. - - `node.invoke` пересилає команду підключеному вузлу. + - `node.rename` оновлює мітку сполученого вузла. + - `node.invoke` пересилає команду до підключеного вузла. - `node.invoke.result` повертає результат для запиту invoke. - - `node.event` переносить події, що походять від вузла, назад у Gateway. + - `node.event` переносить події, що походять від вузла, назад у gateway. - `node.canvas.capability.refresh` оновлює токени scoped canvas-capability. - - `node.pending.pull` і `node.pending.ack` є API черги підключеного вузла. - - `node.pending.enqueue` і `node.pending.drain` керують довговічною очікуваною роботою для offline/disconnected вузлів. + - `node.pending.pull` і `node.pending.ack` — це API черги підключеного вузла. + - `node.pending.enqueue` і `node.pending.drain` керують надійною відкладеною роботою для offline/disconnected вузлів. - - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук/повтор очікуваних схвалень. + - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук/відтворення очікуваних схвалень. - `exec.approval.waitDecision` очікує одне очікуване схвалення exec і повертає остаточне рішення (або `null` у разі timeout). - - `exec.approvals.get` і `exec.approvals.set` керують знімками політики схвалень exec для Gateway. + - `exec.approvals.get` і `exec.approvals.set` керують знімками політики схвалень exec для gateway. - `exec.approvals.node.get` і `exec.approvals.node.set` керують node-local політикою схвалень exec через relay-команди вузла. - - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють визначені plugin потоки схвалення. + - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють потоки схвалень, визначені Plugin. - - Автоматизація: `wake` планує негайну або next-heartbeat ін'єкцію wake-тексту; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою. + - Автоматизація: `wake` планує негайну або next-heartbeat ін’єкцію wake-тексту; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою. - Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`. @@ -453,98 +449,84 @@ Gateway трактує їх як **претензії** та застосову ### Поширені сімейства подій -- `chat`: оновлення чату UI, як-от `chat.inject` та інші події чату лише для транскрипту. -- `session.message` і `session.tool`: оновлення транскрипту/event-stream для підписаного сеансу. -- `sessions.changed`: індекс сеансів або метадані змінилися. +- `chat`: оновлення UI-чату, як-от `chat.inject`, та інші chat-події лише для транскрипту. +- `session.message` і `session.tool`: оновлення транскрипту/потоку подій для підписаної сесії. +- `sessions.changed`: індекс сесій або метадані змінилися. - `presence`: оновлення знімка присутності системи. -- `tick`: періодична keepalive / liveness подія. -- `health`: оновлення знімка стану Gateway. -- `heartbeat`: оновлення потоку подій Heartbeat. -- `cron`: подія зміни запуску/job Cron. -- `shutdown`: сповіщення про вимкнення Gateway. -- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання вузла. +- `tick`: періодична подія keepalive / liveness. +- `health`: оновлення знімка стану gateway. +- `heartbeat`: оновлення потоку подій heartbeat. +- `cron`: подія зміни запуску/завдання cron. +- `shutdown`: сповіщення про вимкнення gateway. +- `node.pair.requested` / `node.pair.resolved`: життєвий цикл сполучення вузла. - `node.invoke.request`: трансляція запиту invoke вузла. -- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спареного пристрою. +- `device.pair.requested` / `device.pair.resolved`: життєвий цикл сполученого пристрою. - `voicewake.changed`: конфігурація тригерів wake-word змінилася. - `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл схвалення exec. -- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення plugin. +- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення Plugin. -### Допоміжні методи вузлів +### Допоміжні методи Node -- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skill - для перевірок auto-allow. +- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills для перевірок auto-allow. -### Допоміжні методи операторів +### Допоміжні методи оператора -- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime - інвентар команд для агента. - - `agentId` є необов'язковим; опустіть його, щоб читати робочу область агента за замовчуванням. - - `scope` керує тим, на яку поверхню націлюється основний `name`: - - `text` повертає основний токен текстової команди без початкового `/` - - `native` і шлях за замовчуванням `both` повертають provider-aware native назви - коли доступні +- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати інвентар runtime-команд для агента. + - `agentId` необов’язковий; пропустіть його, щоб прочитати робочу область агента за замовчуванням. + - `scope` керує тим, на яку поверхню націлюється основне `name`: + - `text` повертає основний текстовий токен команди без початкового `/` + - `native` і типовий шлях `both` повертають provider-aware native names, коли вони доступні - `textAliases` містить точні slash aliases, як-от `/model` і `/m`. - - `nativeName` містить provider-aware native назву команди, коли така існує. - - `provider` є необов'язковим і впливає лише на native naming та доступність native plugin - команд. - - `includeArgs=false` опускає серіалізовані метадані аргументів із відповіді. -- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime catalog інструментів для - агента. Відповідь містить згруповані інструменти та метадані походження: + - `nativeName` містить provider-aware native command name, коли він існує. + - `provider` необов’язковий і впливає лише на native naming плюс доступність native Plugin-команд. + - `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді. +- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для агента. Відповідь містить згруповані інструменти та метадані походження: - `source`: `core` або `plugin` - - `pluginId`: власник plugin, коли `source="plugin"` - - `optional`: чи є інструмент plugin необов'язковим -- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective - інвентар інструментів для сеансу. - - `sessionKey` є обов'язковим. - - Gateway виводить довірений runtime-контекст із сеансу на боці сервера замість приймати - auth або delivery context, надані викликачем. - - Відповідь обмежена сеансом і відображає те, що активна розмова може використовувати зараз, - включно з core, plugin і channel tools. -- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий - інвентар skill для агента. - - `agentId` є необов'язковим; опустіть його, щоб читати робочу область агента за замовчуванням. - - Відповідь містить eligibility, відсутні вимоги, перевірки конфігурації та - sanitized install options без розкриття raw secret values. -- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для - метаданих discovery ClawHub. + - `pluginId`: власник Plugin, коли `source="plugin"` + - `optional`: чи є інструмент Plugin необов’язковим +- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective інвентар інструментів для сесії. + - `sessionKey` обов’язковий. + - Gateway виводить довірений runtime-контекст із сесії на серверному боці, замість приймати auth або delivery context, наданий викликачем. + - Відповідь обмежена сесією та відображає те, що активна розмова може використовувати просто зараз, зокрема інструменти ядра, Plugin і каналів. +- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар Skills для агента. + - `agentId` необов’язковий; пропустіть його, щоб прочитати робочу область агента за замовчуванням. + - Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та санітизовані варіанти встановлення без розкриття raw secret values. +- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення ClawHub. - Оператори можуть викликати `skills.install` (`operator.admin`) у двох режимах: - - Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює - папку skill у директорію `skills/` робочої області агента за замовчуванням. - - Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - запускає оголошену дію `metadata.openclaw.install` на хості Gateway. + - Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює папку Skills у каталог `skills/` робочої області агента за замовчуванням. + - Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` запускає оголошену дію `metadata.openclaw.install` на gateway host. - Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах: - - Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у - робочій області агента за замовчуванням. - - Режим конфігурації виправляє значення `skills.entries.`, як-от `enabled`, - `apiKey` і `env`. + - Режим ClawHub оновлює один tracked slug або всі tracked ClawHub installs у робочій області агента за замовчуванням. + - Режим конфігурації патчить значення `skills.entries.`, як-от `enabled`, `apiKey` і `env`. ### Представлення `models.list` -`models.list` приймає необов'язковий параметр `view`: +`models.list` приймає необов’язковий параметр `view`: -- Не вказано або `"default"`: поточна поведінка runtime. Якщо налаштовано `agents.defaults.models`, відповіддю є дозволений каталог; інакше відповіддю є повний каталог Gateway. -- `"configured"`: поведінка розміру picker. Якщо налаштовано `agents.defaults.models`, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей. -- `"all"`: повний каталог Gateway, в обхід `agents.defaults.models`. Використовуйте це для діагностики та інтерфейсів виявлення, а не для звичайних picker моделей. +- Пропущено або `"default"`: поточна поведінка середовища виконання. Якщо налаштовано `agents.defaults.models`, відповіддю є дозволений каталог; інакше відповіддю є повний каталог Gateway. +- `"configured"`: поведінка розміру вибирача. Якщо налаштовано `agents.defaults.models`, він все одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей. +- `"all"`: повний каталог Gateway з обходом `agents.defaults.models`. Використовуйте це для діагностики та інтерфейсів виявлення, а не для звичайних вибирачів моделей. -## Затвердження exec +## Затвердження Exec -- Коли запит exec потребує затвердження, gateway транслює `exec.approval.requested`. -- Клієнти оператора вирішують це, викликаючи `exec.approval.resolve` (потрібен scope `operator.approvals`). -- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сесії). Запити без `systemRunPlan` відхиляються. -- Після затвердження переадресовані виклики `node.invoke system.run` повторно використовують цей канонічний - `systemRunPlan` як авторитетний контекст команди/cwd/сесії. +- Коли запит exec потребує затвердження, Gateway транслює `exec.approval.requested`. +- Клієнти оператора виконують вирішення, викликаючи `exec.approval.resolve` (потрібна область `operator.approvals`). +- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сеансу). Запити без `systemRunPlan` відхиляються. +- Після затвердження перенаправлені виклики `node.invoke system.run` повторно використовують цей канонічний + `systemRunPlan` як авторитетний контекст команди/cwd/сеансу. - Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` між підготовкою та фінальною затвердженою переадресацією `system.run`, gateway відхиляє запуск замість того, щоб довіряти зміненому payload. + `sessionKey` між підготовкою та фінальним затвердженим пересиланням `system.run`, Gateway + відхиляє запуск замість того, щоб довіряти зміненому корисному навантаженню. -## Fallback доставки агента +## Резервний варіант доставлення агентом -- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку. -- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв'язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`. -- `bestEffortDeliver=true` дозволяє fallback до виконання лише в сесії, коли не вдається розв'язати жодний зовнішній маршрут доставки (наприклад, внутрішні/webchat-сесії або неоднозначні багатоканальні конфігурації). +- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідне доставлення. +- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставлення повертають `INVALID_REQUEST`. +- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в межах сеансу, коли неможливо визначити зовнішній маршрут доставлення (наприклад, внутрішні/webchat-сеанси або неоднозначні багатоканальні конфігурації). -## Версіонування +## Керування версіями -- `PROTOCOL_VERSION` розміщено в `src/gateway/protocol/schema/protocol-schemas.ts`. +- `PROTOCOL_VERSION` міститься в `src/gateway/protocol/schema/protocol-schemas.ts`. - Клієнти надсилають `minProtocol` + `maxProtocol`; сервер відхиляє невідповідності. - Схеми + моделі генеруються з визначень TypeBox: - `pnpm protocol:gen` @@ -553,145 +535,145 @@ Gateway трактує їх як **претензії** та застосову ### Константи клієнта -Еталонний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Значення є -стабільними в межах protocol v3 і є очікуваною базовою лінією для сторонніх клієнтів. +Еталонний клієнт у `src/gateway/client.ts` використовує ці типові значення. Значення +стабільні в межах protocol v3 і є очікуваною базовою лінією для сторонніх клієнтів. -| Константа | За замовчуванням | Джерело | +| Константа | Типово | Джерело | | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | | Тайм-аут запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| Тайм-аут preauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | -| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| Максимальний backoff повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| Clamp швидкого повтору після закриття device-token | `250` ms | `src/gateway/client.ts` | -| Grace force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| Тайм-аут preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`15_000`) | +| Початкова затримка повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| Макс. затримка повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| Обмеження швидкої повторної спроби після закриття device-token | `250` ms | `src/gateway/client.ts` | +| Пільговий період force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | | Типовий тайм-аут `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | Типовий інтервал tick (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | | Закриття через тайм-аут tick | code `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` | | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | Сервер оголошує ефективні `policy.tickIntervalMs`, `policy.maxPayload` -і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень -замість значень за замовчуванням до handshake. +і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень, +а не типових значень до рукостискання. ## Автентифікація -- Автентифікація gateway зі спільним секретом використовує `connect.params.auth.token` або +- Автентифікація Gateway зі спільним секретом використовує `connect.params.auth.token` або `connect.params.auth.password`, залежно від налаштованого режиму автентифікації. -- Режими з ідентичністю, такі як Tailscale Serve +- Режими, що несуть ідентичність, як-от Tailscale Serve (`gateway.auth.allowTailscale: true`) або не-loopback - `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації connect з + `gateway.auth.mode: "trusted-proxy"` задовольняють перевірку автентифікації підключення з заголовків запиту замість `connect.params.auth.*`. -- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію connect зі спільним секретом; - не відкривайте цей режим у публічному/недовіреному ingress. -- Після pairing Gateway видає **device token** із прив'язкою до ролі підключення - + scopes. Він повертається в `hello-ok.auth.deviceToken`, і клієнт має - зберігати його для майбутніх підключень. +- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення зі спільним секретом; + не відкривайте цей режим для публічного/ненадійного ingress. +- Після сполучення Gateway видає **токен пристрою**, обмежений роллю + + областями підключення. Він повертається в `hello-ok.auth.deviceToken` і має + зберігатися клієнтом для майбутніх підключень. - Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого успішного підключення. -- Повторне підключення з цим **збереженим** device token також має повторно використовувати збережений - затверджений набір scopes для цього token. Це зберігає вже наданий доступ - read/probe/status і уникає тихого звуження повторних підключень до - вужчого неявного scope лише адміністратора. -- Складання автентифікації connect на боці клієнта (`selectConnectAuth` у +- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений + затверджений набір областей для цього токена. Це зберігає доступ для читання/перевірки/статусу, + який уже було надано, і запобігає непомітному звуженню повторних підключень до + вужчої неявної області лише адміністратора. +- Збирання автентифікації підключення на боці клієнта (`selectConnectAuth` у `src/gateway/client.ts`): - `auth.password` є ортогональним і завжди пересилається, коли заданий. - - `auth.token` заповнюється за пріоритетом: спочатку явний спільний token, - потім явний `deviceToken`, потім збережений token для пристрою (ключований за + - `auth.token` заповнюється в порядку пріоритету: спочатку явний спільний токен, + потім явний `deviceToken`, потім збережений токен для пристрою (за ключем `deviceId` + `role`). - - `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не розв'язав - `auth.token`. Спільний token або будь-який розв'язаний device token пригнічує його. - - Автоматичне підвищення збереженого device token під час одноразового - повтору `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoint** — + - `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не визначив + `auth.token`. Спільний токен або будь-який визначений токен пристрою його пригнічує. + - Автоматичне підвищення збереженого токена пристрою під час одноразової + повторної спроби `AUTH_TOKEN_MISMATCH` дозволене **лише для довірених кінцевих точок** — loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://` - без pinning не підходить. -- Додаткові записи `hello-ok.auth.deviceTokens` є bootstrap handoff token. - Зберігайте їх лише тоді, коли connect використовував bootstrap-автентифікацію через довірений transport, - такий як `wss://` або loopback/local pairing. + без закріплення не підходить. +- Додаткові записи `hello-ok.auth.deviceTokens` є токенами передавання bootstrap. + Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті, + такому як `wss://` або loopback/локальне сполучення. - Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей - запитаний викликачем набір scopes залишається авторитетним; кешовані scopes лише - повторно використовуються, коли клієнт повторно використовує збережений token для пристрою. -- Device tokens можна ротувати/відкликати через `device.token.rotate` і - `device.token.revoke` (потрібен scope `operator.pairing`). + запитаний викликачем набір областей залишається авторитетним; кешовані області лише + повторно використовуються, коли клієнт повторно використовує збережений токен для пристрою. +- Токени пристроїв можна ротувати/відкликати через `device.token.rotate` і + `device.token.revoke` (потрібна область `operator.pairing`). - `device.token.rotate` повертає метадані ротації. Він віддзеркалює замінний - bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим - device token, щоб клієнти лише з token могли зберегти заміну перед - повторним підключенням. Ротації shared/admin не віддзеркалюють bearer token. -- Видача, ротація та відкликання token залишаються обмеженими затвердженим набором ролей, - записаним у pairing-записі цього пристрою; мутація token не може розширити або - націлити роль пристрою, яку pairing approval ніколи не надавав. -- Для сесій paired-device token керування пристроями є self-scoped, якщо - викликач також не має `operator.admin`: не-admin викликачі можуть видаляти/відкликати/ротувати + bearer-токен лише для викликів з того самого пристрою, які вже автентифіковані цим + токеном пристрою, щоб клієнти лише з токеном могли зберегти свою заміну перед + повторним підключенням. Ротації спільного/адміністративного доступу не віддзеркалюють bearer-токен. +- Видача, ротація та відкликання токенів залишаються обмеженими затвердженим набором ролей, + записаним у записі сполучення цього пристрою; зміна токена не може розширити або + націлитися на роль пристрою, яку затвердження сполучення ніколи не надавало. +- Для сеансів токенів сполученого пристрою керування пристроями є самообмеженим, якщо + викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/ротувати лише **власний** запис пристрою. -- `device.token.rotate` і `device.token.revoke` також перевіряють цільовий набір scopes operator - token проти поточних scopes сесії викликача. Не-admin викликачі - не можуть ротувати або відкликати ширший operator token, ніж уже мають. -- Помилки автентифікації містять `error.details.code` плюс підказки для відновлення: +- `device.token.rotate` і `device.token.revoke` також перевіряють набір областей цільового операторського + токена відносно поточних областей сеансу викликача. Викликачі без прав адміністратора + не можуть ротувати або відкликати ширший операторський токен, ніж той, який вони вже мають. +- Збої автентифікації містять `error.details.code` плюс підказки для відновлення: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Поведінка клієнта для `AUTH_TOKEN_MISMATCH`: - - Довірені клієнти можуть спробувати один обмежений повтор із кешованим token для пристрою. - - Якщо цей повтор не вдається, клієнти мають зупинити автоматичні цикли повторного підключення та показати оператору настанови щодо дії. + - Довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном для пристрою. + - Якщо ця повторна спроба завершується невдало, клієнти мають зупинити автоматичні цикли повторного підключення та показати оператору вказівки щодо дій. -## Ідентичність пристрою + pairing +## Ідентичність пристрою + сполучення - Nodes мають містити стабільну ідентичність пристрою (`device.id`), отриману з - відбитка keypair. -- Gateways видають tokens на пристрій + роль. -- Pairing approvals потрібні для нових device IDs, якщо не ввімкнено локальне auto-approval. -- Pairing auto-approval зосереджено на прямих підключеннях local loopback. -- OpenClaw також має вузький backend/container-local self-connect шлях для - довірених helper-потоків зі спільним секретом. -- Підключення same-host tailnet або LAN усе ще вважаються віддаленими для pairing і - потребують approval. + відбитка пари ключів. +- Gateways видають токени на пристрій + роль. +- Затвердження сполучення потрібні для нових ідентифікаторів пристроїв, якщо не ввімкнено локальне автоматичне затвердження. +- Автоматичне затвердження сполучення зосереджене на прямих підключеннях local loopback. +- OpenClaw також має вузький backend/container-local шлях самопідключення для + довірених допоміжних потоків зі спільним секретом. +- Підключення з того самого хоста через tailnet або LAN усе одно розглядаються як віддалені для сполучення та + потребують затвердження. - WS-клієнти зазвичай включають ідентичність `device` під час `connect` (operator + - node). Єдині винятки operator без device — явні trust paths: - - `gateway.controlUi.allowInsecureAuth=true` для localhost-only сумісності з insecure HTTP. - - успішна автентифікація operator Control UI через `gateway.auth.mode: "trusted-proxy"`. + node). Єдині винятки операторів без пристрою — явні довірчі шляхи: + - `gateway.controlUi.allowInsecureAuth=true` для localhost-only insecure HTTP compatibility. + - успішна автентифікація operator Control UI `gateway.auth.mode: "trusted-proxy"`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, серйозне зниження безпеки). - - direct-loopback backend RPC `gateway-client`, автентифіковані спільним - gateway token/password. + - direct-loopback backend RPCs `gateway-client`, автентифіковані спільним + токеном/паролем Gateway. - Усі підключення мають підписувати наданий сервером nonce `connect.challenge`. ### Діагностика міграції автентифікації пристрою -Для legacy-клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає -detail-коди `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`. +Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає +коди подробиць `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`. -Поширені помилки міграції: +Поширені збої міграції: -| Повідомлення | details.code | details.reason | Значення | +| Повідомлення | details.code | details.reason | Значення | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт пропустив `device.nonce` (або надіслав порожній). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав зі stale/неправильним nonce. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload підпису не відповідає v2 payload. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана timestamp поза допустимим skew. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку public key. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Не вдалося форматування/канонікалізація public key. | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт пропустив `device.nonce` (або надіслав порожнє значення). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав із застарілим/неправильним nonce. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Корисне навантаження підпису не відповідає корисному навантаженню v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана мітка часу виходить за межі дозволеного зсуву. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку відкритого ключа. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Не вдалося перевірити формат/канонікалізацію відкритого ключа. | Ціль міграції: -- Завжди очікуйте `connect.challenge`. -- Підписуйте payload v2, який містить server nonce. +- Завжди чекайте на `connect.challenge`. +- Підписуйте корисне навантаження v2, яке містить серверний nonce. - Надсилайте той самий nonce у `connect.params.device.nonce`. -- Бажаний payload підпису — `v3`, який прив'язує `platform` і `deviceFamily` +- Бажане корисне навантаження підпису — `v3`, яке прив’язує `platform` і `deviceFamily` на додачу до полів device/client/role/scopes/token/nonce. -- Legacy-підписи `v2` залишаються прийнятими для сумісності, але pinning metadata paired-device - усе ще керує command policy під час повторного підключення. +- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення + метаданих сполученого пристрою все одно керує політикою команд під час повторного підключення. -## TLS + pinning +## TLS + закріплення - TLS підтримується для WS-підключень. -- Клієнти можуть необов'язково закріпити відбиток сертифіката gateway (див. конфігурацію `gateway.tls` +- Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls` плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`). -## Scope +## Область -Цей protocol відкриває **повний gateway API** (status, channels, models, chat, -agent, sessions, nodes, approvals тощо). Точну поверхню визначають -схеми TypeBox у `src/gateway/protocol/schema.ts`. +Цей протокол відкриває **повний API Gateway** (status, channels, models, chat, +agent, sessions, nodes, approvals тощо). Точна поверхня визначена +схемами TypeBox у `src/gateway/protocol/schema.ts`. -## Пов'язане +## Пов’язане -- [Протокол моста](/uk/gateway/bridge-protocol) -- [Операційний довідник Gateway](/uk/gateway) +- [Протокол мосту](/uk/gateway/bridge-protocol) +- [Операційний посібник Gateway](/uk/gateway) diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index b05bdb68e..410c74485 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,34 +1,34 @@ --- read_when: - - Додавання функцій, що розширюють доступ або автоматизацію -summary: Аспекти безпеки та модель загроз для запуску Gateway для ШІ з доступом до оболонки + - Додавання функцій, що розширюють доступ або можливості автоматизації +summary: Міркування щодо безпеки та модель загроз для запуску AI Gateway з доступом до командної оболонки title: Безпека x-i18n: - generated_at: "2026-04-28T11:14:20Z" + generated_at: "2026-04-28T20:11:15Z" model: gpt-5.5 provider: openai - source_hash: b60e4a7924789227fcd8ca648253dcf4a2536dccc4daca5ad54ed3241987a2dd + source_hash: 7a1733675f30b5eb8a45eae671aaa8cf41323e16d2543a02ed7bda558c4ebad1 source_path: gateway/security/index.md workflow: 16 --- **Модель довіри персонального асистента.** Ці настанови припускають одну довірену - межу оператора на Gateway (модель персонального асистента для одного користувача). + операторську межу на Gateway (модель персонального асистента для одного користувача). OpenClaw **не** є ворожою багатокористувацькою межею безпеки для кількох - змагальних користувачів, які спільно використовують одного агента або Gateway. Якщо вам потрібна робота зі змішаною довірою або - змагальними користувачами, розділіть межі довіри (окремий Gateway + + ворожих користувачів, які спільно використовують один агент або Gateway. Якщо вам потрібна робота зі змішаною довірою або + ворожими користувачами, розділіть межі довіри (окремі Gateway + облікові дані, в ідеалі окремі користувачі ОС або хости). -## Спершу область застосування: модель безпеки персонального асистента +## Спочатку область застосування: модель безпеки персонального асистента -Настанови з безпеки OpenClaw припускають розгортання **персонального асистента**: одна довірена межа оператора, потенційно багато агентів. +Настанови з безпеки OpenClaw припускають розгортання **персонального асистента**: одна довірена операторська межа, потенційно багато агентів. - Підтримувана позиція безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). -- Не підтримувана межа безпеки: один спільний Gateway/агент, який використовують взаємно недовірені або змагальні користувачі. -- Якщо потрібна ізоляція змагальних користувачів, розділіть за межею довіри (окремий Gateway + облікові дані, і в ідеалі окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що вони спільно мають ті самі делеговані повноваження інструментів для цього агента. +- Не підтримувана межа безпеки: один спільний Gateway/агент, який використовують взаємно недовірені або ворожі користувачі. +- Якщо потрібна ізоляція ворожих користувачів, розділіть за межею довіри (окремий Gateway + облікові дані, а в ідеалі окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть писати одному агенту з увімкненими інструментами, вважайте, що вони спільно використовують ті самі делеговані повноваження інструментів для цього агента. Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не заявляє про ворожу багатокористувацьку ізоляцію на одному спільному Gateway. @@ -45,121 +45,121 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно лишається вузьким: він перемикає типові відкриті групові +`security audit --fix` навмисно залишається вузьким: він перемикає поширені відкриті групові політики на списки дозволених, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для стану/конфігурації/включених файлів і використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. -Він позначає типові небезпечні помилки (відкриття автентифікації Gateway, відкриття керування браузером, підвищені списки дозволених, дозволи файлової системи, надто permissive схвалення exec і відкриття інструментів у відкритих каналах). +Він позначає поширені небезпечні помилки (відкриття автентифікації Gateway, відкриття керування браузером, підвищені списки дозволених, дозволи файлової системи, надто поблажливі підтвердження exec і відкритий доступ каналів до інструментів). -OpenClaw є і продуктом, і експериментом: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Не існує “ідеально безпечного” налаштування.** Мета — діяти усвідомлено щодо: +OpenClaw є одночасно продуктом і експериментом: ви під’єднуєте поведінку frontier-моделі до реальних поверхонь обміну повідомленнями й реальних інструментів. **«Ідеально безпечного» налаштування не існує.** Мета — свідомо визначити: - хто може говорити з вашим ботом - де боту дозволено діяти -- до чого бот може торкатися +- чого бот може торкатися -Почніть із найменшого доступу, який усе ще працює, а потім розширюйте його в міру зростання впевненості. +Почніть із найменшого доступу, який усе ще працює, а потім розширюйте його, коли зростає впевненість. -### Розгортання та довіра до хоста +### Довіра до розгортання та хоста OpenClaw припускає, що межа хоста й конфігурації є довіреною: -- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте їх довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/змагальних операторів **не є рекомендованим налаштуванням**. +- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, зокрема `openclaw.json`), вважайте цю людину довіреним оператором. +- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованим налаштуванням**. - Для команд зі змішаною довірою розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). -- Рекомендоване значення за замовчуванням: один користувач на машину/хост (або VPS), один Gateway для цього користувача та один або більше агентів у цьому Gateway. -- Усередині одного екземпляра Gateway автентифікований доступ оператора є довіреною роллю площини керування, а не роллю орендаря на користувача. -- Ідентифікатори сеансів (`sessionKey`, ID сеансів, мітки) є селекторами маршрутизації, а не токенами авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може спрямовувати той самий набір дозволів. Ізоляція сеансу/памʼяті на користувача допомагає приватності, але не перетворює спільного агента на авторизацію хоста на користувача. +- Рекомендоване типове налаштування: один користувач на машину/хост (або VPS), один Gateway для цього користувача й один або більше агентів у цьому Gateway. +- Усередині одного екземпляра Gateway автентифікований операторський доступ є довіреною роллю площини керування, а не роллю орендаря для окремого користувача. +- Ідентифікатори сеансів (`sessionKey`, ідентифікатори сеансів, мітки) є селекторами маршрутизації, а не токенами авторизації. +- Якщо кілька людей можуть писати одному агенту з увімкненими інструментами, кожна з них може скеровувати той самий набір дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає з приватністю, але не перетворює спільного агента на авторизацію хоста для кожного користувача. ### Спільний робочий простір Slack: реальний ризик -Якщо "кожен у Slack може писати боту", основний ризик — делеговані повноваження інструментів: +Якщо «кожен у Slack може написати боту», основний ризик — делеговані повноваження інструментів: - будь-який дозволений відправник може спричиняти виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики агента; -- інʼєкція підказок/вмісту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або вихідні дані; -- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може спрямувати ексфільтрацію через використання інструментів. +- ін’єкція підказок/вмісту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або виводи; +- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може керувати ексфільтрацією через використання інструментів. -Використовуйте окремих агентів/Gateway з мінімальними інструментами для командних робочих процесів; агентів із персональними даними тримайте приватними. +Для командних робочих процесів використовуйте окремі агенти/Gateway з мінімальними інструментами; агентів із персональними даними тримайте приватними. -### Агент, спільний для компанії: прийнятний патерн +### Спільний агент компанії: прийнятний шаблон -Це прийнятно, коли всі, хто використовує цього агента, перебувають в одній межі довіри (наприклад, одна команда компанії), а агент має суворо бізнесову область застосування. +Це прийнятно, коли всі, хто використовує цього агента, перебувають в одній межі довіри (наприклад, одна команда компанії), а агент суворо обмежений бізнес-контекстом. - запускайте його на виділеній машині/VM/контейнері; -- використовуйте виділеного користувача ОС + виділений браузер/профіль/облікові записи для цього runtime; -- не входьте з цього runtime у персональні облікові записи Apple/Google або персональні профілі менеджера паролів/браузера. +- використовуйте виділеного користувача ОС + виділений браузер/профіль/акаунти для цього середовища виконання; +- не входьте в цьому середовищі виконання до особистих акаунтів Apple/Google або особистих профілів менеджера паролів/браузера. -Якщо ви змішуєте персональні й корпоративні ідентичності в одному runtime, ви руйнуєте розділення та підвищуєте ризик розкриття персональних даних. +Якщо ви змішуєте особисті й корпоративні ідентичності в одному середовищі виконання, ви руйнуєте розділення й підвищуєте ризик викриття персональних даних. ## Концепція довіри Gateway і Node -Розглядайте Gateway і Node як один домен довіри оператора з різними ролями: +Розглядайте Gateway і Node як один операторський домен довіри з різними ролями: -- **Gateway** — це площина керування та поверхня політики (`gateway.auth`, політика інструментів, маршрутизація). +- **Gateway** — це площина керування та поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). - **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії пристрою, локальні можливості хоста). -- Виклик, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії Node є довіреними діями оператора на цьому Node. -- Прямі backend-клієнти loopback, автентифіковані спільним токеном/паролем gateway, - можуть виконувати внутрішні RPC площини керування без предʼявлення ідентичності користувацького - пристрою. Це не обхід віддаленого або браузерного спарювання: мережеві - клієнти, клієнти Node, клієнти з токенами пристрою та явні ідентичності пристроїв - усе ще проходять спарювання та примусове підвищення scope. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на користувача. -- Схвалення exec (список дозволених + запит) — це запобіжники для наміру оператора, а не ворожа багатокористувацька ізоляція. -- Продуктове значення OpenClaw за замовчуванням для довірених налаштувань одного оператора полягає в тому, що host exec на `gateway`/`node` дозволений без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви це не посилите). Це значення за замовчуванням є навмисним UX-рішенням, а не вразливістю саме по собі. -- Схвалення exec привʼязують точний контекст запиту та, наскільки можливо, прямі локальні файлові операнди; вони не моделюють семантично кожен шлях завантажувача runtime/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- Викликача, автентифікованого в Gateway, вважають довіреним у межах Gateway. Після спарення дії Node вважаються довіреними операторськими діями на цьому Node. +- Прямі loopback-клієнти бекенду, автентифіковані спільним токеном/паролем + Gateway, можуть виконувати внутрішні RPC площини керування без подання ідентичності + пристрою користувача. Це не обхід віддаленого чи браузерного спарення: мережеві + клієнти, клієнти Node, клієнти з токенами пристроїв і явні ідентичності пристроїв + усе ще проходять спарення та примусове підвищення області. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація для кожного користувача. +- Підтвердження exec (список дозволених + запит) — це захисні обмеження для наміру оператора, а не ворожа багатокористувацька ізоляція. +- Типове продуктове налаштування OpenClaw для довірених однооператорських установок полягає в тому, що host exec на `gateway`/`node` дозволений без запитів підтвердження (`security="full"`, `ask="off"`, якщо ви не посилите це). Це типове налаштування є навмисним UX, а не вразливістю саме по собі. +- Підтвердження exec прив’язують точний контекст запиту й найкращі можливі прямі локальні файлові операнди; вони не моделюють семантично кожен шлях завантажувача середовища виконання/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. Якщо вам потрібна ізоляція ворожих користувачів, розділіть межі довіри за користувачем ОС/хостом і запускайте окремі Gateway. ## Матриця меж довіри -Використовуйте це як швидку модель під час triage ризику: +Використовуйте це як швидку модель під час оцінювання ризику: -| Межа або контроль | Що це означає | Типове хибне прочитання | -| --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до API gateway | "Для безпеки потрібні підписи кожного повідомлення в кожному кадрі" | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | "Ключ сеансу є межею автентифікації користувача" | -| Запобіжники підказок/вмісту | Зменшують ризик зловживання моделлю | "Самої інʼєкції підказки достатньо, щоб довести обхід автентифікації" | -| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли ввімкнено | "Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри" | -| Локальна TUI `!` shell | Явне локальне виконання, запущене оператором | "Зручна команда локальної shell є віддаленою інʼєкцією" | -| Спарювання Node і команди Node | Віддалене виконання рівня оператора на спарених пристроях | "Віддалене керування пристроєм слід за замовчуванням вважати доступом недовіреного користувача" | -| `gateway.nodes.pairing.autoApproveCidrs` | Опційна політика реєстрації Node у довіреній мережі | "Вимкнений за замовчуванням список дозволених є автоматичною вразливістю спарювання" | +| Межа або контроль | Що це означає | Поширене хибне тлумачення | +| --------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликачів для API Gateway | "Потрібні підписи для кожного повідомлення в кожному кадрі, щоб бути безпечним" | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | "Ключ сеансу є межею автентифікації користувача" | +| Захисні обмеження підказок/вмісту | Зменшують ризик зловживання моделлю | "Одна лише ін’єкція підказки доводить обхід автентифікації" | +| `canvas.eval` / browser evaluate | Навмисна операторська можливість, коли ввімкнено | "Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри" | +| Локальна TUI `!` shell | Явне локальне виконання, запущене оператором | "Зручна команда локальної оболонки є віддаленою ін’єкцією" | +| Спарення Node і команди Node | Віддалене виконання операторського рівня на спарених пристроях | "Віддалене керування пристроєм слід типово вважати доступом недовіреного користувача" | +| `gateway.nodes.pairing.autoApproveCidrs` | Політика підключення Node у довіреній мережі за явним увімкненням | "Вимкнений за замовчуванням список дозволених є автоматичною вразливістю спарення" | -## Не є вразливостями за дизайном +## Не є вразливостями за задумом - + -Про ці патерни повідомляють часто, і зазвичай їх закривають без дій, якщо -не продемонстровано реального обходу межі: +Ці шаблони часто повідомляють, і зазвичай їх закривають без дій, якщо +не продемонстровано реальний обхід межі: -- Ланцюжки лише з інʼєкцією підказок без обходу політики, автентифікації або sandbox. +- Ланцюжки лише з ін’єкцією підказок без обходу політики, автентифікації або пісочниці. - Твердження, що припускають ворожу багатокористувацьку роботу на одному спільному хості або конфігурації. - Твердження, що класифікують звичайний операторський доступ шляхом читання (наприклад `sessions.list` / `sessions.preview` / `chat.history`) як IDOR у налаштуванні зі спільним Gateway. -- Знахідки розгортання лише на localhost (наприклад HSTS на Gateway, +- Знахідки для розгортань лише на localhost (наприклад HSTS на Gateway, доступному лише через loopback). -- Знахідки підписів вхідних webhook Discord для вхідних шляхів, яких +- Знахідки щодо підписів вхідних webhook Discord для вхідних шляхів, яких не існує в цьому репозиторії. -- Звіти, які трактують метадані спарювання Node як прихований другий шар - схвалення на команду для `system.run`, коли реальною межею виконання все ще є - глобальна політика команд Node у Gateway плюс власні схвалення exec - цього Node. -- Звіти, які трактують налаштований `gateway.nodes.pairing.autoApproveCidrs` як - вразливість сам по собі. Цей параметр вимкнений за замовчуванням, потребує - явних записів CIDR/IP, застосовується лише до першого спарювання `role: node` без - запитаних scope і не автоcхвалює operator/browser/Control UI, - WebChat, підвищення ролі, підвищення scope, зміни метаданих, зміни публічного ключа - або шляхи same-host loopback trusted-proxy header, якщо loopback trusted-proxy auth не було явно ввімкнено. -- Знахідки "браку авторизації на користувача", які трактують `sessionKey` як +- Звіти, що трактують метадані спарення Node як прихований другий шар + підтвердження для кожної команди `system.run`, тоді як реальна межа виконання все ще + є глобальною політикою команд Node Gateway плюс власні підтвердження exec + самого Node. +- Звіти, що трактують налаштований `gateway.nodes.pairing.autoApproveCidrs` як + вразливість сам по собі. Це налаштування вимкнене за замовчуванням, потребує + явних записів CIDR/IP, застосовується лише до першого спарення `role: node` без + запитаних областей і не авто-схвалює operator/browser/Control UI, + WebChat, підвищення ролі, підвищення області, зміни метаданих, зміни публічного ключа + або same-host loopback шляхи заголовка trusted-proxy, якщо автентифікацію loopback trusted-proxy не було явно ввімкнено. +- Знахідки про "відсутню авторизацію для кожного користувача", які трактують `sessionKey` як токен автентифікації. ## Посилений базовий рівень за 60 секунд -Спершу використайте цей базовий рівень, а потім вибірково знову вмикайте інструменти для кожного довіреного агента: +Спочатку використайте цей базовий рівень, а потім вибірково знову вмикайте інструменти для кожного довіреного агента: ```json5 { @@ -184,87 +184,87 @@ OpenClaw припускає, що межа хоста й конфігураці } ``` -Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/runtime. +Це залишає Gateway доступним лише локально, ізолює DM і типово вимикає інструменти площини керування/середовища виконання. ## Швидке правило для спільної скриньки -Якщо більш ніж одна людина може надсилати DM вашому боту: +Якщо більше ніж одна людина може написати вашому боту в DM: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома обліковими записами). +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома акаунтами). - Залишайте `dmPolicy: "pairing"` або суворі списки дозволених. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює кооперативні/спільні скриньки, але не призначено для ворожої ізоляції спільних орендарів, коли користувачі мають спільний доступ на запис до хоста/конфігурації. +- Це посилює кооперативні/спільні скриньки, але не призначене як ворожа ізоляція співорендарів, коли користувачі спільно мають доступ до запису хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація запуску**: хто може запускати агента (`dmPolicy`, `groupPolicy`, списки дозволених, вимоги згадки). -- **Видимість контексту**: який додатковий контекст додається до вхідних даних моделі (тіло відповіді, процитований текст, історія треду, переслані метадані). +- **Авторизація запуску**: хто може запустити агента (`dmPolicy`, `groupPolicy`, списки дозволених, gates за згадкою). +- **Видимість контексту**: який додатковий контекст вставляється у вхід моделі (тіло відповіді, цитований текст, історія треду, переслані метадані). -Списки дозволених обмежують запуски та авторизацію команд. Параметр `contextVisibility` керує тим, як фільтрується додатковий контекст (процитовані відповіді, корені тредів, отримана історія): +Списки дозволених обмежують запуски й авторизацію команд. Налаштування `contextVisibility` контролює, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): -- `contextVisibility: "all"` (за замовчуванням) залишає додатковий контекст таким, як отримано. +- `contextVisibility: "all"` (типово) залишає додатковий контекст у тому вигляді, у якому його отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками списку дозволених. -- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все ще зберігає одну явну процитовану відповідь. +- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все ще зберігає одну явну цитовану відповідь. -Установлюйте `contextVisibility` для кожного каналу або для кожної кімнати/розмови. Докладніші відомості про налаштування див. у [Групових чатах](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` для кожного каналу або кожної кімнати/розмови. Див. [Групові чати](/uk/channels/groups#context-visibility-and-allowlists) для деталей налаштування. -Настанови щодо triage консультативних повідомлень: +Настанови з triage консультативних повідомлень: -- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників не з allowlist», є знахідками посилення захисту, які можна усунути за допомогою `contextVisibility`, а не самостійними обходами меж авторизації чи sandbox. -- Щоб мати безпековий вплив, звіти все одно мають демонструвати обхід межі довіри (авторизації, політики, sandbox, approval або іншої задокументованої межі). +- Твердження, які показують лише, що «модель може бачити процитований або історичний текст від відправників не з allowlist», є знахідками для посилення захисту, які можна усунути за допомогою `contextVisibility`, а не самі по собі обходами меж автентифікації чи sandbox. +- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (автентифікації, політики, sandbox, схвалення або іншої задокументованої межі). -## Що перевіряє аудит (на високому рівні) +## Що перевіряє аудит (загальний рівень) -- **Вхідний доступ** (політики DM, групові політики, allowlists): чи можуть сторонні люди запускати бота? -- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії shell/file/network? -- **Дрейф approval для exec** (`security=full`, `autoAllowSkills`, allowlists інтерпретатора без `strictInlineEval`): чи guardrails для host-exec досі роблять те, що ви від них очікуєте? - - `security="full"` — це широке попередження про позицію безпеки, а не доказ помилки. Це вибране значення за замовчуванням для довірених налаштувань персонального асистента; посилюйте його лише тоді, коли ваша модель загроз потребує approval або guardrails allowlist. -- **Мережевий доступ** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Доступ до керування браузером** (віддалені вузли, relay-порти, віддалені CDP endpoints). -- **Гігієна локального диска** (дозволи, symlinks, config includes, шляхи «синхронізованих папок»). +- **Вхідний доступ** (політики DM, групові політики, allowlists): чи можуть незнайомці запускати бота? +- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії з shell/файлами/мережею? +- **Відхилення схвалення exec** (`security=full`, `autoAllowSkills`, allowlists інтерпретаторів без `strictInlineEval`): чи захисні обмеження host-exec досі працюють так, як ви вважаєте? + - `security="full"` — це широке попередження про стан безпеки, а не доказ помилки. Це вибране типове значення для довірених налаштувань персонального асистента; посилюйте його лише тоді, коли ваша модель загроз потребує схвалення або захисних обмежень allowlist. +- **Мережева експозиція** (прив’язка/автентифікація Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Експозиція керування браузером** (віддалені вузли, relay-порти, віддалені CDP endpoint-и). +- **Гігієна локального диска** (дозволи, symlink-и, config includes, шляхи «синхронізованих папок»). - **Plugins** (plugins завантажуються без явного allowlist). -- **Дрейф політик/помилкова конфігурація** (налаштування sandbox docker сконфігуровані, але режим sandbox вимкнений; неефективні патерни `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не перевіряє текст shell; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначений профілями окремих агентів; інструменти, що належать plugin, доступні за дозвільної політики інструментів). -- **Дрейф runtime-очікувань** (наприклад припущення, що implicit exec досі означає `sandbox`, коли `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"`, коли режим sandbox вимкнений). -- **Гігієна моделі** (попереджати, коли налаштовані моделі виглядають застарілими; це не жорстке блокування). +- **Відхилення політик/неправильна конфігурація** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення відбувається лише за точною назвою команди (наприклад `system.run`) і не перевіряє shell-текст; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями окремих агентів; інструменти, що належать plugin, доступні за поблажливої політики інструментів). +- **Відхилення очікувань runtime** (наприклад, припущення, що неявний exec досі означає `sandbox`, коли `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` за вимкненого режиму sandbox). +- **Гігієна моделей** (попередження, коли налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також намагається виконати best-effort live Gateway probe. +Якщо запустити `--deep`, OpenClaw також виконує best-effort live-зонд Gateway. ## Мапа зберігання облікових даних -Використовуйте це під час аудиту доступу або вибору того, що резервувати: +Використовуйте це під час аудиту доступу або вибору того, що резервно копіювати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Токен бота Telegram**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlinks відхиляються) -- **Токен бота Discord**: config/env або SecretRef (постачальники env/file/exec) +- **Токен Telegram-бота**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink-и відхиляються) +- **Токен Discord-бота**: config/env або SecretRef (провайдери env/file/exec) - **Токени Slack**: config/env (`channels.slack.*`) - **Pairing allowlists**: - - `~/.openclaw/credentials/-allowFrom.json` (обліковий запис за замовчуванням) - - `~/.openclaw/credentials/--allowFrom.json` (облікові записи не за замовчуванням) -- **Профілі автентифікації моделі**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload секретів із файловим backing (необов’язково)**: `~/.openclaw/secrets.json` -- **Імпорт legacy OAuth**: `~/.openclaw/credentials/oauth.json` + - `~/.openclaw/credentials/-allowFrom.json` (типовий обліковий запис) + - `~/.openclaw/credentials/--allowFrom.json` (нетипові облікові записи) +- **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Файловий payload секретів (необов’язково)**: `~/.openclaw/secrets.json` +- **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` -## Чеклист аудиту безпеки +## Контрольний список аудиту безпеки -Коли аудит виводить знахідки, розглядайте це як порядок пріоритетів: +Коли аудит друкує знахідки, розглядайте це як порядок пріоритетів: -1. **Будь-що “open” + увімкнені інструменти**: спочатку обмежте DMs/groups (pairing/allowlists), потім посильте політику інструментів/sandboxing. -2. **Публічний мережевий доступ** (LAN bind, Funnel, відсутня auth): виправте негайно. -3. **Віддалений доступ до керування браузером**: розглядайте його як операторський доступ (лише tailnet, свідомо pairing для вузлів, уникайте публічного доступу). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні для читання group/world. +1. **Будь-що “open” + увімкнені інструменти**: спершу заблокуйте DM/групи (pairing/allowlists), потім посильте політику інструментів/sandboxing. +2. **Публічна мережева експозиція** (LAN-прив’язка, Funnel, відсутня автентифікація): виправте негайно. +3. **Віддалена експозиція керування браузером**: ставтеся до неї як до операторського доступу (лише tailnet, навмисно поєднуйте вузли, уникайте публічної експозиції). +4. **Дозволи**: переконайтеся, що стан/config/облікові дані/auth не доступні для читання групі/всім. 5. **Plugins**: завантажуйте лише те, чому явно довіряєте. -6. **Вибір моделі**: надавайте перевагу сучасним моделям, посиленим щодо інструкцій, для будь-якого бота з інструментами. +6. **Вибір моделі**: віддавайте перевагу сучасним, стійким до інструкцій моделям для будь-якого бота з інструментами. ## Глосарій аудиту безпеки -Кожна знахідка аудиту має ключ у вигляді структурованого `checkId` (наприклад +Кожна аудиторська знахідка має ключ у вигляді структурованого `checkId` (наприклад `gateway.bind_no_auth` або `tools.exec.security_full_configured`). Поширені класи критичної серйозності: -- `fs.*` — дозволи файлової системи для state, config, credentials, auth profiles. -- `gateway.*` — режим bind, auth, Tailscale, Control UI, налаштування trusted-proxy. +- `fs.*` — дозволи файлової системи для стану, config, облікових даних, auth-профілів. +- `gateway.*` — режим прив’язки, автентифікація, Tailscale, Control UI, налаштування trusted-proxy. - `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — посилення захисту для окремих поверхонь. - `plugins.*`, `skills.*` — ланцюг постачання plugin/skill і знахідки сканування. - `security.exposure.*` — наскрізні перевірки, де політика доступу перетинається з радіусом ураження інструментів. @@ -274,30 +274,31 @@ OpenClaw розділяє два поняття: ## Control UI через HTTP -Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: +Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати +ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє auth Control UI без ідентичності пристрою, коли сторінку +- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, коли сторінку завантажено через небезпечний HTTP. - Він не обходить перевірки pairing. -- Він не послаблює вимоги до ідентичності віддаленого (не localhost) пристрою. +- Він не послаблює вимоги до ідентичності віддалених (не localhost) пристроїв. Надавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. -Лише для break-glass сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` -повністю вимикає перевірки ідентичності пристрою. Це серйозне зниження безпеки; -тримайте його вимкненим, якщо ви не виконуєте активне налагодження і не можете швидко відкотити зміни. +Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` +повністю вимикає перевірки ідентичності пристрою. Це суттєве зниження безпеки; +тримайте його вимкненим, якщо ви не виконуєте активне налагодження й не можете швидко відкотити зміну. Окремо від цих небезпечних прапорців, успішний `gateway.auth.mode: "trusted-proxy"` -може допускати **операторські** сесії Control UI без ідентичності пристрою. Це -навмисна поведінка auth-mode, а не shortcut `allowInsecureAuth`, і вона все одно -не поширюється на сесії Control UI з роллю node. +може допускати **операторські** сеанси Control UI без ідентичності пристрою. Це +навмисна поведінка режиму автентифікації, а не shortcut `allowInsecureAuth`, і вона все одно +не поширюється на сеанси Control UI з роллю вузла. -`openclaw security audit` попереджає, коли це налаштування увімкнене. +`openclaw security audit` попереджає, коли це налаштування ввімкнено. -## Підсумок небезпечних або ризикових прапорців +## Підсумок небезпечних або ризикованих прапорців -`openclaw security audit` піднімає `config.insecure_or_dangerous_flags`, коли -увімкнені відомі небезпечні/ризикові debug-перемикачі. Тримайте їх unset у +`openclaw security audit` створює `config.insecure_or_dangerous_flags`, коли +відомі небезпечні/ризиковані debug-перемикачі ввімкнено. Не задавайте їх у production. @@ -312,31 +313,31 @@ production. - + Control UI і браузер: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - Зіставлення назв каналів (bundled і plugin channels; також доступно для кожного + Зіставлення назв каналів (вбудовані та plugin-канали; також доступно для кожного `accounts.` там, де застосовно): - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` - - `channels.synology-chat.dangerouslyAllowNameMatching` (plugin channel) - - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (plugin channel) - - `channels.zalouser.dangerouslyAllowNameMatching` (plugin channel) - - `channels.irc.dangerouslyAllowNameMatching` (plugin channel) - - `channels.mattermost.dangerouslyAllowNameMatching` (plugin channel) + - `channels.synology-chat.dangerouslyAllowNameMatching` (plugin-канал) + - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (plugin-канал) + - `channels.zalouser.dangerouslyAllowNameMatching` (plugin-канал) + - `channels.irc.dangerouslyAllowNameMatching` (plugin-канал) + - `channels.mattermost.dangerouslyAllowNameMatching` (plugin-канал) - Мережевий доступ: + Мережева експозиція: - `channels.telegram.network.dangerouslyAllowPrivateNetwork` (також для кожного облікового запису) - Sandbox Docker (defaults + для кожного агента): + Sandbox Docker (типові значення + для кожного агента): - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -348,15 +349,15 @@ production. ## Конфігурація reverse proxy Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки IP forwarded-client. +`gateway.trustedProxies` для коректної обробки forwarded-client IP. -Коли Gateway виявляє proxy headers з адреси, якої **немає** у `trustedProxies`, він **не** розглядатиме з’єднання як локальних клієнтів. Якщо gateway auth вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше виглядали б як такі, що надходять із localhost, і отримували б автоматичну довіру. +Коли Gateway виявляє proxy-заголовки з адреси, якої **немає** в `trustedProxies`, він **не** вважатиме підключення локальними клієнтами. Якщо автентифікацію gateway вимкнено, такі підключення відхиляються. Це запобігає обходу автентифікації, коли proxied-підключення інакше виглядали б як такі, що надходять із localhost, і отримували б автоматичну довіру. -`gateway.trustedProxies` також живить `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: +`gateway.trustedProxies` також живить `gateway.auth.mode: "trusted-proxy"`, але цей режим автентифікації суворіший: -- trusted-proxy auth **за замовчуванням fail closed для loopback-source proxies** -- same-host loopback reverse proxies можуть використовувати `gateway.trustedProxies` для local-client detection і обробки forwarded IP -- same-host loopback reverse proxies можуть задовольнити `gateway.auth.mode: "trusted-proxy"` лише коли `gateway.auth.trustedProxy.allowLoopback = true`; інакше використовуйте token/password auth +- trusted-proxy auth **типово fail closed для проксі з loopback-джерелом** +- same-host loopback reverse proxies можуть використовувати `gateway.trustedProxies` для виявлення local-client і обробки forwarded IP +- same-host loopback reverse proxies можуть задовольняти `gateway.auth.mode: "trusted-proxy"` лише коли `gateway.auth.trustedProxy.allowLoopback = true`; інакше використовуйте автентифікацію token/password ```yaml gateway: @@ -370,86 +371,86 @@ gateway: password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -Коли `trustedProxies` сконфігуровано, Gateway використовує `X-Forwarded-For`, щоб визначити IP клієнта. `X-Real-IP` ігнорується за замовчуванням, якщо `gateway.allowRealIpFallback: true` не встановлено явно. +Коли `trustedProxies` налаштовано, Gateway використовує `X-Forwarded-For`, щоб визначити IP клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. -Trusted proxy headers не роблять node device pairing автоматично довіреним. -`gateway.nodes.pairing.autoApproveCidrs` — це окрема operator policy, вимкнена за замовчуванням. -Навіть коли її ввімкнено, loopback-source trusted-proxy header paths -виключаються з node auto-approval, бо локальні callers можуть підробляти ці -headers, зокрема коли loopback trusted-proxy auth явно ввімкнено. +Заголовки trusted proxy не роблять pairing пристрою вузла автоматично довіреним. +`gateway.nodes.pairing.autoApproveCidrs` — це окрема, типово вимкнена +операторська політика. Навіть коли її ввімкнено, шляхи заголовків trusted-proxy з loopback-джерелом +виключено з автоматичного схвалення вузлів, бо локальні викликачі можуть підробити ці +заголовки, зокрема коли loopback trusted-proxy auth явно ввімкнено. -Правильна поведінка reverse proxy (перезаписувати вхідні forwarding headers): +Добра поведінка reverse proxy (перезаписувати вхідні forwarding-заголовки): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Неправильна поведінка reverse proxy (додавати/зберігати недовірені forwarding headers): +Погана поведінка reverse proxy (додавати/зберігати недовірені forwarding-заголовки): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Примітки щодо HSTS і origin +## Нотатки щодо HSTS і origin -- OpenClaw gateway передусім local/loopback. Якщо ви завершуєте TLS на reverse proxy, установіть HSTS там, на proxy-facing HTTPS domain. -- Якщо gateway сам завершує HTTPS, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб емітувати HSTS header з відповідей OpenClaw. -- Докладні настанови щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Для non-loopback розгортань Control UI `gateway.controlUi.allowedOrigins` потрібен за замовчуванням. -- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика allow-all browser-origin, а не посилене значення за замовчуванням. Уникайте її поза щільно контрольованим локальним тестуванням. -- Browser-origin auth failures на loopback усе одно rate-limited, навіть коли - general loopback exemption увімкнено, але lockout key scoped для кожного +- OpenClaw gateway насамперед локальний/local loopback. Якщо ви завершуєте TLS на reverse proxy, задайте HSTS там, на HTTPS-домені, що звернений до proxy. +- Якщо сам gateway завершує HTTPS, можна встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw відповіді надсилали HSTS-заголовок. +- Детальні настанови з розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). +- Для розгортань Control UI не на loopback `gateway.controlUi.allowedOrigins` типово є обов’язковим. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика дозволу всіх browser-origin, а не посилене типове значення. Уникайте її поза жорстко контрольованим локальним тестуванням. +- Збої автентифікації browser-origin на loopback все одно обмежуються rate limit навіть коли + загальне звільнення для loopback увімкнено, але ключ lockout scoped для кожного нормалізованого значення `Origin`, а не для одного спільного localhost bucket. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим Host-header origin fallback; розглядайте його як небезпечну operator-selected policy. -- Розглядайте DNS rebinding і поведінку proxy-host header як питання посилення захисту розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає fallback-режим origin за Host-заголовком; ставтеся до нього як до небезпечної політики, обраної оператором. +- Розглядайте DNS rebinding і поведінку proxy-host header як питання посилення розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. -## Локальні журнали сесій зберігаються на диску +## Локальні журнали сеансів зберігаються на диску -OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сесій і (необов’язково) індексації пам’яті сесій, але це також означає, що +OpenClaw зберігає transcript-и сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це потрібно для неперервності сеансу й (необов’язково) індексування пам’яті сеансу, але це також означає, що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Розглядайте доступ до диска як межу довіри -і обмежте дозволи на `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +й обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. -## Виконання Node (system.run) +## Виконання на вузлі (system.run) -Якщо macOS node paired, Gateway може викликати `system.run` на цьому node. Це **remote code execution** на Mac: +Якщо macOS-вузол paired, Gateway може викликати `system.run` на цьому вузлі. Це **віддалене виконання коду** на Mac: - Потребує сполучення node (схвалення + токен). -- Сполучення node з Gateway не є поверхнею схвалення для кожної команди. Воно встановлює ідентичність/довіру node та видачу токенів. +- Сполучення node у Gateway не є поверхнею схвалення для кожної команди. Воно встановлює ідентичність/довіру node та видачу токенів. - Gateway застосовує грубу глобальну політику команд node через `gateway.nodes.allowCommands` / `denyCommands`. -- Керується на Mac через **Settings → Exec approvals** (security + ask + allowlist). -- Політика `system.run` для кожного node — це власний файл схвалень виконання node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд Gateway. -- Node, що працює з `security="full"` і `ask="off"`, дотримується стандартної моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо ваше розгортання явно не потребує суворішої позиції щодо схвалень або allowlist. -- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного операнда локального скрипта/файлу. Якщо OpenClaw не може точно визначити один прямий локальний файл для команди інтерпретатора/середовища виконання, виконання на основі схвалення забороняється замість обіцянки повного семантичного покриття. -- Для `host=node` запуски на основі схвалення також зберігають канонічний підготовлений - `systemRunPlan`; подальші схвалені пересилання повторно використовують цей збережений план, а перевірка gateway - відхиляє зміни команд/cwd/контексту сесії від викликача після створення +- Керується на Mac через **Settings → Exec approvals** (безпека + запит + список дозволених). +- Політика `system.run` для кожного node є власним файлом схвалень виконання цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд Gateway. +- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо ваше розгортання явно не потребує суворішої позиції щодо схвалень або списку дозволених. +- Режим схвалення прив’язує точний контекст запиту і, коли можливо, один конкретний операнд локального скрипта/файлу. Якщо OpenClaw не може точно визначити один безпосередній локальний файл для команди інтерпретатора/середовища виконання, виконання на основі схвалення відхиляється замість обіцянки повного семантичного покриття. +- Для `host=node` виконання на основі схвалення також зберігає канонічно підготовлений + `systemRunPlan`; подальші схвалені пересилання повторно використовують цей збережений план, а перевірка Gateway + відхиляє зміни викликачем до контексту команди/cwd/сеансу після створення запиту на схвалення. -- Якщо ви не хочете віддаленого виконання, установіть security на **deny** і видаліть сполучення node для цього Mac. +- Якщо ви не хочете віддаленого виконання, встановіть безпеку на **deny** і видаліть сполучення node для цього Mac. Ця відмінність важлива для тріажу: -- Повторно підключений сполучений node, який рекламує інший список команд, сам по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення виконання node все ще забезпечують фактичну межу виконання. +- Повторно під’єднаний сполучений node, який оголошує інший список команд, сам по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення виконання node все ще забезпечують фактичну межу виконання. - Звіти, які трактують метадані сполучення node як другий прихований рівень схвалення для кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. -## Динамічні Skills (спостерігач / віддалені nodes) +## Динамічні Skills (відстежувач / віддалені nodes) -OpenClaw може оновлювати список Skills посеред сесії: +OpenClaw може оновлювати список Skills посеред сеансу: -- **Спостерігач Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. -- **Віддалені nodes**: підключення macOS node може зробити Skills лише для macOS придатними (на основі зондування bin). +- **Відстежувач Skills**: зміни до `SKILL.md` можуть оновити знімок Skills під час наступного ходу агента. +- **Віддалені nodes**: під’єднання macOS node може зробити доступними Skills лише для macOS (на основі зондування bin). -Вважайте папки Skills **довіреним кодом** і обмежте коло тих, хто може їх змінювати. +Вважайте папки Skills **довіреним кодом** і обмежуйте, хто може їх змінювати. ## Модель загроз Ваш AI-асистент може: -- Виконувати довільні shell-команди +- Виконувати довільні команди оболонки - Читати/записувати файли -- Отримувати доступ до мережевих сервісів +- Доступатися до мережевих служб - Надсилати повідомлення будь-кому (якщо ви надасте йому доступ до WhatsApp) Люди, які надсилають вам повідомлення, можуть: @@ -460,40 +461,40 @@ OpenClaw може оновлювати список Skills посеред сес ## Основна концепція: контроль доступу перед інтелектом -Більшість збоїв тут — не складні експлойти, а ситуація “хтось написав боту, і бот зробив те, що його попросили.” +Більшість збоїв тут не є витонченими експлойтами — це “хтось написав боту, і бот зробив те, про що його попросили.” Позиція OpenClaw: -- **Спершу ідентичність:** вирішіть, хто може спілкуватися з ботом (сполучення DM / allowlists / явне “відкрити”). -- **Далі область дії:** вирішіть, де боту дозволено діяти (allowlists груп + шлюз за згадкою, інструменти, sandboxing, дозволи пристрою). -- **Модель останньою:** припускайте, що моделлю можна маніпулювати; проєктуйте так, щоб маніпуляція мала обмежений радіус ураження. +- **Спершу ідентичність:** вирішіть, хто може спілкуватися з ботом (сполучення DM / списки дозволених / явне “відкрито”). +- **Далі область дії:** вирішіть, де боту дозволено діяти (списки дозволених груп + активація згадкою, інструменти, ізоляція, дозволи пристрою). +- **Модель останньою:** припускайте, що моделлю можна маніпулювати; проектуйте так, щоб маніпуляція мала обмежений радіус ураження. ## Модель авторизації команд -Slash-команди та директиви виконуються лише для **авторизованих відправників**. Авторизація виводиться з -allowlists/сполучення каналів плюс `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) -і [Slash-команди](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, +Команди зі слешем і директиви виконуються лише для **авторизованих відправників**. Авторизація виводиться з +списків дозволених/сполучення каналу плюс `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) +і [Команди зі слешем](/uk/tools/slash-commands)). Якщо список дозволених каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. -`/exec` — це зручність лише в межах сесії для авторизованих операторів. Вона **не** записує конфігурацію і -не змінює інші сесії. +`/exec` — це зручність лише в межах сеансу для авторизованих операторів. Вона **не** записує конфігурацію і +не змінює інші сеанси. ## Ризик інструментів площини керування Два вбудовані інструменти можуть вносити постійні зміни до площини керування: -- `gateway` може перевіряти конфігурацію за допомогою `config.schema.lookup` / `config.get` і може вносити постійні зміни за допомогою `config.apply`, `config.patch` і `update.run`. -- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. +- `gateway` може перевіряти конфігурацію через `config.schema.lookup` / `config.get` і може вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `cron` може створювати заплановані завдання, які продовжують виконуватися після завершення початкового чату/завдання. -Доступний лише власнику runtime-інструмент `gateway` усе ще відмовляється переписувати +Інструмент середовища виконання `gateway`, доступний лише власнику, все ще відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` -нормалізуються до тих самих захищених шляхів exec перед записом. +нормалізуються до тих самих захищених шляхів виконання перед записом. Редагування `gateway config.apply` і `gateway config.patch`, керовані агентом, -за замовчуванням fail-closed: агент може налаштовувати лише вузький набір -шляхів prompt, model і шлюзу за згадкою. Тому нові чутливі дерева конфігурації захищені, -якщо їх навмисно не додано до allowlist. +типово закриті при збої: агент може налаштовувати лише вузький набір шляхів +prompt, моделі та активації згадкою. Тому нові чутливі дерева конфігурації захищені, +якщо їх навмисно не додано до списку дозволених. -Для будь-якого агента/поверхні, що обробляє недовірений вміст, за замовчуванням забороняйте це: +Для будь-якого агента/поверхні, що обробляє недовірений вміст, типово забороняйте це: ```json5 { @@ -503,47 +504,47 @@ allowlists/сполучення каналів плюс `commands.useAccessGroup } ``` -`commands.restart=false` блокує лише дії перезапуску. Це не вимикає дії конфігурації/оновлення `gateway`. +`commands.restart=false` блокує лише дії перезапуску. Це не вимикає дії `gateway` з конфігурацією/оновленням. ## Plugins -Plugins працюють **у процесі** з Gateway. Вважайте їх довіреним кодом: +Plugins працюють **в одному процесі** з Gateway. Вважайте їх довіреним кодом: -- Установлюйте Plugins лише з джерел, яким довіряєте. -- Віддавайте перевагу явним allowlists `plugins.allow`. -- Переглядайте конфігурацію plugin перед увімкненням. -- Перезапускайте Gateway після змін plugin. -- Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - - Шлях установлення — це каталог окремого plugin під активним коренем установлення plugins. - - OpenClaw запускає вбудоване сканування небезпечного коду перед установленням/оновленням. Знахідки `critical` блокуються за замовчуванням. - - OpenClaw використовує `npm pack`, а потім запускає локальний для проєкту `npm install --omit=dev --ignore-scripts` у цьому каталозі. Успадковані глобальні налаштування встановлення npm ігноруються, щоб залежності залишалися під шляхом установлення plugin. - - Віддавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — це аварійний варіант лише для хибнопозитивних спрацювань вбудованого сканування в потоках установлення/оновлення plugin. Він не обходить блокування політики хука `before_install` plugin і не обходить збої сканування. - - Установлення залежностей Skills через Gateway дотримуються того самого розділення небезпечних/підозрілих знахідок: вбудовані знахідки `critical` блокуються, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills з ClawHub. +- Встановлюйте Plugins лише з джерел, яким довіряєте. +- Віддавайте перевагу явним спискам дозволених `plugins.allow`. +- Переглядайте конфігурацію Plugin перед увімкненням. +- Перезапускайте Gateway після змін Plugin. +- Якщо ви встановлюєте або оновлюєте Plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: + - Шлях встановлення — це каталог конкретного Plugin під активним коренем встановлення Plugin. + - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Знахідки `critical` блокують типово. + - OpenClaw використовує `npm pack`, потім запускає локальне для проекту `npm install --omit=dev --ignore-scripts` у цьому каталозі. Успадковані глобальні налаштування встановлення npm ігноруються, щоб залежності залишалися під шляхом встановлення Plugin. + - Віддавайте перевагу закріпленим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` призначений лише для аварійних випадків хибних спрацьовувань вбудованого сканування у потоках встановлення/оновлення Plugin. Він не обходить блокування політики хука `before_install` Plugin і не обходить невдалі результати сканування. + - Встановлення залежностей Skills через Gateway дотримується того самого поділу на небезпечні/підозрілі: вбудовані знахідки `critical` блокують, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки й надалі лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills з ClawHub. -Докладніше: [Plugins](/uk/tools/plugin) +Деталі: [Plugins](/uk/tools/plugin) -## Модель доступу DM: сполучення, allowlist, відкритий, вимкнений +## Модель доступу DM: сполучення, список дозволених, відкрито, вимкнено -Усі поточні канали з підтримкою DM підтримують політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM підтримують політику DM (`dmPolicy` або `*.dm.policy`), яка обмежує вхідні DM **до** обробки повідомлення: -- `pairing` (за замовчуванням): невідомі відправники отримують короткий код сполучення, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Очікувані запити за замовчуванням обмежені **3 на канал**. +- `pairing` (типово): невідомі відправники отримують короткий код сполучення, а бот ігнорує їхнє повідомлення, доки його не схвалять. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Очікувані запити типово обмежені **3 на канал**. - `allowlist`: невідомі відправники блокуються (без рукостискання сполучення). -- `open`: дозволити DM будь-кому (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явне погодження). -- `disabled`: повністю ігнорувати вхідні DM. +- `open`: дозволяє будь-кому надсилати DM (публічно). **Потребує**, щоб список дозволених каналу містив `"*"` (явна згода). +- `disabled`: повністю ігнорує вхідні DM. -Схвалити через CLI: +Схвалення через CLI: ```bash openclaw pairing list openclaw pairing approve ``` -Докладніше + файли на диску: [Сполучення](/uk/channels/pairing) +Деталі + файли на диску: [Сполучення](/uk/channels/pairing) -## Ізоляція DM-сесій (багатокористувацький режим) +## Ізоляція DM-сеансів (багатокористувацький режим) -За замовчуванням OpenClaw маршрутизує **всі DM до головної сесії**, щоб ваш асистент мав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist для кількох людей), розгляньте ізоляцію DM-сесій: +Типово OpenClaw спрямовує **усі DM до головного сеансу**, щоб ваш асистент мав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або багатокористувацький список дозволених), розгляньте ізоляцію DM-сеансів: ```json5 { @@ -553,74 +554,74 @@ openclaw pairing approve Це запобігає витоку контексту між користувачами, зберігаючи ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа host-admin. Якщо користувачі взаємно недовірені й ділять той самий хост/конфігурацію Gateway, натомість запускайте окремі gateways для кожної межі довіри. +Це межа контексту повідомлень, а не межа адміністратора хоста. Якщо користувачі взаємно недовірені й мають спільний хост/конфігурацію Gateway, натомість запускайте окремі gateways для кожної межі довіри. ### Безпечний режим DM (рекомендовано) Вважайте наведений вище фрагмент **безпечним режимом DM**: -- За замовчуванням: `session.dmScope: "main"` (усі DM ділять одну сесію для безперервності). -- Стандарт локального CLI onboarding: записує `session.dmScope: "per-channel-peer"`, коли не задано (зберігає наявні явні значення). +- Типово: `session.dmScope: "main"` (усі DM спільно використовують один сеанс для безперервності). +- Типове значення локального onboarding через CLI: записує `session.dmScope: "per-channel-peer"`, коли значення не задано (зберігає наявні явні значення). - Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Ізоляція peer між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). +- Ізоляція peer між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує один сеанс у всіх каналах одного типу). -Якщо ви запускаєте кілька облікових записів в одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина контактує з вами через кілька каналів, використовуйте `session.identityLinks`, щоб звести ці DM-сесії до однієї канонічної ідентичності. Див. [Керування сесіями](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). +Якщо ви запускаєте кілька облікових записів на одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб звести ці DM-сеанси до однієї канонічної ідентичності. Див. [Керування сеансами](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). -## Allowlists для DM і груп +## Списки дозволених для DM і груп OpenClaw має два окремі рівні “хто може мене активувати?”: -- **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): кому дозволено спілкуватися з ботом у прямих повідомленнях. - - Коли `dmPolicy="pairing"`, схвалення записуються до сховища allowlist сполучень, прив’язаного до облікового запису, під `~/.openclaw/credentials/` (`-allowFrom.json` для стандартного облікового запису, `--allowFrom.json` для нестандартних облікових записів), об’єднуючись з allowlists конфігурації. -- **Allowlist груп** (специфічний для каналу): з яких груп/каналів/guilds бот узагалі прийматиме повідомлення. +- **Список дозволених DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): кому дозволено говорити з ботом у прямих повідомленнях. + - Коли `dmPolicy="pairing"`, схвалення записуються до сховища списку дозволених сполучення, прив’язаного до облікового запису, у `~/.openclaw/credentials/` (`-allowFrom.json` для типового облікового запису, `--allowFrom.json` для нетипових облікових записів), об’єднаного зі списками дозволених із конфігурації. +- **Список дозволених груп** (залежить від каналу): з яких груп/каналів/гільдій бот взагалі прийматиме повідомлення. - Поширені шаблони: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: налаштування за замовчуванням для кожної групи, як-от `requireMention`; коли задано, це також діє як allowlist груп (додайте `"*"`, щоб зберегти поведінку дозволу всіх). - - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежити, хто може активувати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlists для кожної поверхні + стандартні значення згадок. - - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/allowlists груп, потім активація згадкою/відповіддю. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlists відправників, як-от `groupAllowFrom`. - - **Примітка з безпеки:** ставтеся до `dmPolicy="open"` і `groupPolicy="open"` як до налаштувань останньої надії. Їх слід використовувати вкрай рідко; віддавайте перевагу сполученню + allowlists, якщо ви не повністю довіряєте кожному учаснику кімнати. + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові значення для кожної групи, як-от `requireMention`; коли задано, це також працює як список дозволених груп (додайте `"*"`, щоб зберегти поведінку “дозволити всім”). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може активувати бота _всередині_ групового сеансу (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: списки дозволених для кожної поверхні + типові значення згадок. + - Перевірки груп виконуються в такому порядку: спершу `groupPolicy`/списки дозволених груп, потім активація згадкою/відповіддю. + - Відповідь на повідомлення бота (неявна згадка) **не** обходить списки дозволених відправників, як-от `groupAllowFrom`. + - **Примітка щодо безпеки:** вважайте `dmPolicy="open"` і `groupPolicy="open"` налаштуваннями останньої інстанції. Їх слід використовувати вкрай рідко; віддавайте перевагу сполученню + спискам дозволених, якщо ви повністю не довіряєте кожному учаснику кімнати. -Докладніше: [Конфігурація](/uk/gateway/configuration) і [Групи](/uk/channels/groups) +Деталі: [Конфігурація](/uk/gateway/configuration) і [Групи](/uk/channels/groups) ## Prompt injection (що це таке і чому це важливо) -Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю, щоб вона зробила щось небезпечне (“ігноруй свої інструкції”, “скинь свою файлову систему”, “перейди за цим посиланням і виконай команди” тощо). +Prompt injection — це коли атакувальник створює повідомлення, яке маніпулює моделлю, щоб вона зробила щось небезпечне (“ігноруй свої інструкції”, “виведи мою файлову систему”, “перейди за цим посиланням і запусти команди” тощо). -Навіть із сильними системними prompt, **prompt injection не розв’язано**. Запобіжники системного prompt — це лише м’які настанови; жорстке забезпечення походить від політики інструментів, схвалень exec, sandboxing і allowlists каналів (і оператори можуть вимкнути їх за задумом). Що допомагає на практиці: +Навіть із сильними системними prompts **prompt injection не вирішено**. Запобіжники системного prompt — це лише м’які вказівки; жорстке забезпечення надходить від політики інструментів, схвалень виконання, ізоляції та списків дозволених каналів (і оператори можуть вимкнути їх за задумом). Що допомагає на практиці: - Тримайте вхідні приватні повідомлення заблокованими (сполучення/списки дозволених). -- У групах надавайте перевагу обмеженню через згадування; уникайте ботів, що «завжди ввімкнені», у публічних кімнатах. +- У групах віддавайте перевагу обмеженню за згадкою; уникайте ботів, що “завжди ввімкнені”, у публічних кімнатах. - За замовчуванням вважайте посилання, вкладення та вставлені інструкції ворожими. -- Запускайте виконання чутливих інструментів у пісочниці; тримайте секрети поза файловою системою, доступною агенту. -- Примітка: пісочниця вмикається явно. Якщо режим пісочниці вимкнено, неявний `host=auto` розв’язується в хост Gateway. Явний `host=sandbox` все одно завершується безпечною відмовою, бо середовище виконання пісочниці недоступне. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явною в конфігурації. -- Обмежте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними списками дозволених. -- Якщо ви додаєте інтерпретатори до списку дозволених (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно потребували явного схвалення. -- Аналіз схвалення shell також відхиляє форми розгортання параметрів POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) всередині **heredoc без лапок**, тож тіло heredoc зі списку дозволених не зможе непомітно протягнути shell-розгортання повз перевірку списку дозволених як звичайний текст. Візьміть термінатор heredoc у лапки (наприклад `<<'EOF'`), щоб явно вибрати семантику буквального тіла; heredoc без лапок, які розгортали б змінні, відхиляються. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і неправильного використання інструментів. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, загартовану інструкціями. +- Виконуйте чутливі інструменти в пісочниці; тримайте секрети поза файловою системою, доступною агенту. +- Примітка: пісочниця вмикається явно. Якщо режим пісочниці вимкнено, неявне `host=auto` розв’язується в хост Gateway. Явне `host=sandbox` усе одно завершується безпечною відмовою, бо середовище виконання пісочниці недоступне. Установіть `host=gateway`, якщо хочете зробити таку поведінку явною в конфігурації. +- Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними списками дозволених. +- Якщо ви додаєте інтерпретатори до списку дозволених (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми все одно потребували явного схвалення. +- Аналіз схвалення оболонки також відхиляє форми POSIX-розкриття параметрів (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) усередині **неекранованих heredoc**, тож тіло heredoc зі списку дозволених не зможе непомітно провести розкриття оболонки повз перевірку списку дозволених як звичайний текст. Візьміть термінатор heredoc у лапки (наприклад `<<'EOF'`), щоб явно вибрати семантику буквального тіла; неекрановані heredoc, які розкривали б змінні, відхиляються. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до ін’єкції промпта та неправильного використання інструментів. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, зміцнену інструкціями. Червоні прапорці, які слід вважати недовіреними: -- «Прочитай цей файл/URL і зроби точно те, що там написано». -- «Ігноруй свій системний prompt або правила безпеки». -- «Розкрий свої приховані інструкції або виводи інструментів». -- «Встав повний вміст ~/.openclaw або свої журнали». +- “Прочитай цей файл/URL і зроби саме те, що там сказано.” +- “Ігноруй свій системний промпт або правила безпеки.” +- “Розкрий свої приховані інструкції або виводи інструментів.” +- “Встав повний вміст ~/.openclaw або своїх журналів.” ## Санітизація спеціальних токенів зовнішнього вмісту -OpenClaw видаляє поширені літерали спеціальних токенів chat-template для self-hosted LLM із загорнутого зовнішнього вмісту та метаданих до того, як вони потрапляють до моделі. Охоплені сімейства маркерів включають токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi та GPT-OSS. +OpenClaw видаляє поширені літерали спеціальних токенів шаблонів чату LLM із self-hosted середовищ із обгорнутого зовнішнього вмісту та метаданих до того, як вони потрапляють до моделі. Охоплені сімейства маркерів включають рольові/покрокові токени Qwen/ChatML, Llama, Gemma, Mistral, Phi та GPT-OSS. Чому: -- OpenAI-сумісні бекенди, що стоять перед self-hosted моделями, іноді зберігають спеціальні токени, які з’являються в користувацькому тексті, замість маскувати їх. Зловмисник, який може записувати у вхідний зовнішній вміст (отримана сторінка, тіло електронного листа, вивід інструмента з вмістом файлу), інакше міг би ін’єктувати синтетичну межу ролі `assistant` або `system` і обійти захисні обмеження загорнутого вмісту. -- Санітизація відбувається на шарі загортання зовнішнього вмісту, тому застосовується однаково до інструментів fetch/read і вхідного вмісту каналів, а не окремо для кожного провайдера. -- Вихідні відповіді моделі вже мають окремий санітизатор, який видаляє витоки ``, `` і подібної службової структури з видимих користувачу відповідей. Санітизатор зовнішнього вмісту є вхідним відповідником. +- OpenAI-сумісні бекенди, що працюють перед self-hosted моделями, іноді зберігають спеціальні токени, які з’являються в тексті користувача, замість того щоб маскувати їх. Інакше зловмисник, який може записати щось у вхідний зовнішній вміст (отриману сторінку, тіло електронного листа, вивід інструмента з вмістом файла), міг би вставити синтетичну межу ролі `assistant` або `system` і обійти захисні обмеження обгорнутого вмісту. +- Санітизація відбувається на шарі обгортання зовнішнього вмісту, тому застосовується однаково до інструментів fetch/read і вхідного вмісту каналів, а не окремо для кожного провайдера. +- Вихідні відповіді моделі вже мають окремий санітизатор, який видаляє витоки ``, ``, ``, `` та подібного внутрішнього каркаса середовища виконання з відповідей, видимих користувачу, на фінальній межі доставки каналу. Санітизатор зовнішнього вмісту є вхідним відповідником. -Це не замінює інші засоби посилення захисту на цій сторінці — `dmPolicy`, списки дозволених, схвалення exec, пісочниця та `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на шарі токенізатора проти self-hosted стеків, які передають користувацький текст зі спеціальними токенами без змін. +Це не замінює інші заходи зміцнення на цій сторінці — `dmPolicy`, списки дозволених, схвалення exec, пісочниця та `contextVisibility` усе ще виконують основну роботу. Воно закриває один конкретний обхід на рівні токенізатора проти self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. ## Небезпечні прапорці обходу зовнішнього вмісту -OpenClaw містить явні прапорці обходу, які вимикають безпечне загортання зовнішнього вмісту: +OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього вмісту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -628,99 +629,99 @@ OpenClaw містить явні прапорці обходу, які вими Рекомендації: -- Тримайте їх невстановленими/false у production. -- Вмикайте лише тимчасово для вузько обмеженого налагодження. +- У production залишайте їх невстановленими/false. +- Вмикайте лише тимчасово для чітко обмеженого налагодження. - Якщо ввімкнено, ізолюйте цього агента (пісочниця + мінімум інструментів + окремий простір імен сесії). -Примітка про ризик hooks: +Примітка щодо ризиків hooks: -- Payload hooks є недовіреним вмістом, навіть коли доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть нести prompt injection). -- Слабкі рівні моделей підвищують цей ризик. Для автоматизації, керованої hooks, надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте пісочницю, де це можливо. +- Payload hooks є недовіреним вмістом, навіть коли доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити ін’єкцію промпта). +- Слабкі рівні моделей підвищують цей ризик. Для автоматизації, керованої hooks, віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте пісочницю, де можливо. -### Prompt injection не потребує публічних приватних повідомлень +### Ін’єкція промпта не потребує публічних приватних повідомлень -Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може статися через +Навіть якщо **лише ви** можете писати боту, ін’єкція промпта все одно може статися через будь-який **недовірений вміст**, який бот читає (результати web search/fetch, сторінки browser, -електронні листи, документи, вкладення, вставлені журнали/код). Іншими словами: відправник не є -єдиною поверхнею загрози; **сам вміст** може нести ворожі інструкції. +електронні листи, документи, вкладення, вставлені журнали/код). Інакше кажучи: відправник не є +єдиною поверхнею загрози; **сам вміст** може містити ворожі інструкції. Коли інструменти ввімкнені, типовий ризик — ексфільтрація контексту або запуск викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте read-only або з вимкненими інструментами **агента-читача**, щоб підсумовувати недовірений вміст, +- Використовуйте **агента-читача** лише для читання або без інструментів, щоб підсумовувати недовірений вміст, а потім передавайте підсумок основному агенту. - Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами, якщо вони не потрібні. -- Для URL-входів OpenResponses (`input_file` / `input_image`) установіть суворі +- Для URL-входів OpenResponses (`input_file` / `input_image`) задавайте суворі `gateway.http.endpoints.responses.files.urlAllowlist` і `gateway.http.endpoints.responses.images.urlAllowlist`, а `maxUrlParts` тримайте низьким. Порожні списки дозволених трактуються як невстановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, якщо хочете повністю вимкнути отримання URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно ін’єктується як - **недовірений зовнішній вміст**. Не вважайте текст файлу довіреним лише тому, що - Gateway декодував його локально. Ін’єктований блок усе ще містить явні - граничні маркери `<<>>` плюс метадані `Source: External`, - навіть якщо цей шлях пропускає довший банер `SECURITY NOTICE:`. -- Те саме загортання на основі маркерів застосовується, коли media-understanding витягує текст - із прикріплених документів перед додаванням цього тексту до media prompt. -- Вмикайте пісочницю та суворі списки дозволених інструментів для будь-якого агента, що торкається недовіреного введення. -- Тримайте секрети поза prompts; передавайте їх через env/config на хості Gateway натомість. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно вставляється як + **недовірений зовнішній вміст**. Не покладайтеся на те, що текст файла є довіреним лише тому, що + Gateway декодував його локально. Вставлений блок усе одно містить явні + межові маркери `<<>>` і метадані `Source: External`, + хоча цей шлях пропускає довший банер `SECURITY NOTICE:`. +- Таке саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст + із вкладених документів перед додаванням цього тексту до медіапромпта. +- Вмикайте пісочницю та суворі списки дозволених інструментів для будь-якого агента, який працює з недовіреним входом. +- Тримайте секрети поза промптами; натомість передавайте їх через env/config на хості Gateway. ### Self-hosted бекенди LLM -OpenAI-сумісні self-hosted бекенди, такі як vLLM, SGLang, TGI, LM Studio, -або власні стеки токенізаторів Hugging Face можуть відрізнятися від hosted providers тим, як -обробляються спеціальні токени chat-template. Якщо бекенд токенізує буквальні рядки +OpenAI-сумісні self-hosted бекенди, як-от vLLM, SGLang, TGI, LM Studio, +або власні стеки токенізаторів Hugging Face, можуть відрізнятися від hosted провайдерів тим, як +обробляються спеціальні токени шаблонів чату. Якщо бекенд токенізує буквальні рядки на кшталт `<|im_start|>`, `<|start_header_id|>` або `` як -структурні токени chat-template всередині користувацького вмісту, недовірений текст може спробувати -підробити межі ролей на шарі токенізатора. +структурні токени шаблону чату всередині користувацького вмісту, недовірений текст може спробувати +підробити межі ролей на рівні токенізатора. -OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей із загорнутого -зовнішнього вмісту перед відправленням його до моделі. Тримайте загортання зовнішнього вмісту -ввімкненим і, коли доступно, надавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні -токени у вмісті, наданому користувачем. Hosted providers, такі як OpenAI +OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей із обгорнутого +зовнішнього вмісту перед відправленням його до моделі. Тримайте обгортання зовнішнього вмісту +увімкненим і, коли доступно, віддавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні +токени в наданому користувачем вмісті. Hosted провайдери, такі як OpenAI і Anthropic, уже застосовують власну санітизацію на боці запиту. -### Сила моделі (примітка з безпеки) +### Сила моделі (примітка щодо безпеки) -Стійкість до prompt injection **не** є однаковою для різних рівнів моделей. Менші/дешевші моделі загалом більш схильні до неправильного використання інструментів і захоплення інструкцій, особливо під ворожими prompts. +Стійкість до ін’єкції промпта **не** є однаковою на всіх рівнях моделей. Менші/дешевші моделі загалом більш схильні до неправильного використання інструментів і перехоплення інструкцій, особливо під ворожими промптами. -Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt-injection зі старішими/меншими моделями часто занадто високий. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик ін’єкції промпта зі старішими/меншими моделями часто занадто високий. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або торкатися файлів/мереж. -- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених inboxes; ризик prompt-injection занадто високий. -- Якщо ви мусите використовувати меншу модель, **зменште радіус ураження** (read-only інструменти, сильна пісочниця, мінімальний доступ до файлової системи, суворі списки дозволених). -- Під час запуску малих моделей **увімкніть пісочницю для всіх сесій** і **вимкніть web_search/web_fetch/browser**, якщо входи не перебувають під суворим контролем. -- Для chat-only персональних асистентів із довіреним введенням і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених скриньок вхідних; ризик ін’єкції промпта занадто високий. +- Якщо ви мусите використовувати меншу модель, **зменште радіус ураження** (інструменти лише для читання, сильна пісочниця, мінімальний доступ до файлової системи, суворі списки дозволених). +- Під час запуску малих моделей **вмикайте пісочницю для всіх сесій** і **вимикайте web_search/web_fetch/browser**, якщо входи не контролюються жорстко. +- Для персональних помічників лише для чату з довіреним входом і без інструментів менші моделі зазвичай підходять. ## Reasoning і докладний вивід у групах -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє міркування, вивід інструментів -або діагностику Plugin, яка -не призначалася для публічного каналу. У групових налаштуваннях вважайте їх **лише налагодженням** -і тримайте вимкненими, якщо вони не потрібні явно. +`/reasoning`, `/verbose` і `/trace` можуть розкрити внутрішнє reasoning, вивід інструментів +або діагностику Plugin, які +не призначалися для публічного каналу. У групових налаштуваннях вважайте їх **лише налагоджувальними** +і тримайте вимкненими, якщо вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. -- Якщо ви їх вмикаєте, робіть це лише в довірених приватних повідомленнях або суворо контрольованих кімнатах. -- Пам’ятайте: докладний і trace-вивід можуть містити args інструментів, URL, діагностику Plugin і дані, які бачила модель. +- Якщо ви їх вмикаєте, робіть це лише в довірених приватних повідомленнях або жорстко контрольованих кімнатах. +- Пам’ятайте: докладний і trace-вивід може містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. -## Приклади посилення конфігурації +## Приклади зміцнення конфігурації ### Дозволи файлів -Тримайте config + state приватними на хості Gateway: +Тримайте конфігурацію та стан приватними на хості Gateway: -- `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) +- `~/.openclaw/openclaw.json`: `600` (лише читання/запис користувача) - `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити та запропонувати посилити ці дозволи. +`openclaw doctor` може попередити й запропонувати посилити ці дозволи. -### Мережевий доступ (bind, порт, firewall) +### Мережева експозиція (bind, порт, firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: @@ -735,28 +736,28 @@ Gateway мультиплексує **WebSocket + HTTP** на одному пор Якщо ви завантажуєте canvas-вміст у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: - Не відкривайте canvas host для недовірених мереж/користувачів. -- Не дозволяйте canvas-вмісту мати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. +- Не робіть так, щоб canvas-вміст мав той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. Режим bind керує тим, де Gateway слухає: - `gateway.bind: "loopback"` (за замовчуванням): підключатися можуть лише локальні клієнти. -- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширюють поверхню атаки. Використовуйте їх лише з auth Gateway (спільний token/password або правильно налаштований довірений proxy) і справжнім firewall. +- Не-loopback bind (`"lan"`, `"tailnet"`, `"custom"`) розширюють поверхню атаки. Використовуйте їх лише з gateway auth (спільний токен/пароль або правильно налаштований довірений proxy) і справжнім firewall. Практичні правила: -- Надавайте перевагу Tailscale Serve над LAN bind (Serve тримає Gateway на loopback, а Tailscale керує доступом). -- Якщо ви мусите bind до LAN, обмежте порт firewall до вузького списку дозволених IP-джерел; не налаштовуйте широке port-forward. +- Віддавайте перевагу Tailscale Serve замість LAN bind (Serve тримає Gateway на loopback, а Tailscale обробляє доступ). +- Якщо ви мусите прив’язати до LAN, обмежте порт firewall до вузького списку дозволених IP-джерел; не робіть широке port-forwarding. - Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. ### Публікація портів Docker з UFW -Якщо ви запускаєте OpenClaw із Docker на VPS, пам’ятайте, що опубліковані порти контейнера -(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через forwarding-ланцюги Docker, -а не лише правила host `INPUT`. +Якщо ви запускаєте OpenClaw із Docker на VPS, пам’ятайте, що опубліковані порти контейнерів +(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги forwarding Docker, +а не лише правила `INPUT` хоста. Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг оцінюється до власних allow-правил Docker). -На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` +`DOCKER-USER` (цей ланцюг оцінюється перед власними accept-правилами Docker). +У багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` і все одно застосовують ці правила до backend nftables. Мінімальний приклад списку дозволених (IPv4): @@ -782,10 +783,10 @@ IPv6 має окремі таблиці. Додайте відповідну п Docker IPv6 увімкнено. Уникайте жорстко прописаних назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів -різняться між образами VPS (`ens3`, `enp*` тощо), і невідповідності можуть випадково -пропустити ваше правило deny. +відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково +пропустити ваше deny-правило. -Швидка перевірка після перезавантаження: +Швидка перевірка після reload: ```bash ufw reload @@ -799,17 +800,17 @@ nmap -sT -p 1-65535 --open ### Виявлення mDNS/Bonjour -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для виявлення локальними пристроями. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: -- `cliPath`: повний шлях файлової системи до binary CLI (розкриває ім’я користувача та місце встановлення) -- `sshPort`: оголошує доступність SSH на хості -- `displayName`, `lanHost`: інформація про hostname +- `cliPath`: повний шлях файлової системи до бінарного файлу CLI (розкриває ім’я користувача та місце встановлення) +- `sshPort`: повідомляє про доступність SSH на хості +- `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування щодо операційної безпеки:** Трансляція деталей інфраструктури полегшує розвідку для будь-кого в локальній мережі. Навіть "нешкідлива" інформація, як-от шляхи файлової системи й доступність SSH, допомагає зловмисникам мапувати ваше середовище. +**Міркування щодо операційної безпеки:** трансляція деталей інфраструктури спрощує розвідку для будь-кого в локальній мережі. Навіть "нешкідлива" інформація, як-от шляхи файлової системи та доступність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Мінімальний режим** (типово, рекомендовано для відкритих Gateway): пропускайте чутливі поля в трансляціях mDNS: +1. **Мінімальний режим** (типовий, рекомендовано для відкритих Gateway): вилучайте чутливі поля з трансляцій mDNS: ```json5 { @@ -819,7 +820,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Вимкніть повністю**, якщо вам не потрібне локальне виявлення пристроїв: +2. **Повністю вимкнути**, якщо вам не потрібне виявлення локальних пристроїв: ```json5 { @@ -829,7 +830,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (явне ввімкнення): додайте `cliPath` + `sshPort` у записи TXT: +3. **Повний режим** (за явною згодою): включайте `cliPath` + `sshPort` у записи TXT: ```json5 { @@ -839,19 +840,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): встановіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. -У мінімальному режимі Gateway все одно транслює достатньо для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але пропускає `cliPath` і `sshPort`. Застосунки, яким потрібна інформація про шлях CLI, можуть натомість отримати її через автентифіковане WebSocket-з’єднання. +У мінімальному режимі Gateway все ще транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але вилучає `cliPath` і `sshPort`. Застосунки, яким потрібна інформація про шлях CLI, можуть натомість отримати її через автентифіковане з’єднання WebSocket. ### Заблокуйте WebSocket Gateway (локальна автентифікація) -Автентифікація Gateway **обов’язкова за замовчуванням**. Якщо не налаштовано дійсний шлях автентифікації gateway, -Gateway відхиляє WebSocket-з’єднання (fail‑closed). +Автентифікація Gateway **типово обов’язкова**. Якщо не налаштовано чинний шлях автентифікації gateway, +Gateway відхиляє з’єднання WebSocket (закритий режим у разі помилки). -Під час онбордингу типово генерується токен (навіть для loopback), тому +Onboarding типово генерує токен (навіть для loopback), тому локальні клієнти мають автентифікуватися. -Установіть токен, щоб **усі** WS-клієнти мали автентифікуватися: +Задайте токен, щоб **усі** клієнти WS мали автентифікуватися: ```json5 { @@ -864,152 +865,153 @@ Gateway відхиляє WebSocket-з’єднання (fail‑closed). Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. -`gateway.remote.token` і `gateway.remote.password` є джерелами клієнтських облікових даних. Вони самі собою **не** захищають локальний WS-доступ. Локальні шляхи викликів можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. Якщо `gateway.auth.token` або `gateway.auth.password` явно налаштовано через SecretRef і не вдалося розв’язати, розв’язання завершується fail closed (без маскування резервним remote). +`gateway.remote.token` і `gateway.remote.password` — це джерела облікових даних клієнта. Вони **не** захищають локальний доступ WS самі по собі. Локальні шляхи викликів можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. Якщо `gateway.auth.token` або `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закритим режимом (без маскування віддаленим резервним варіантом). Необов’язково: закріпіть віддалений TLS за допомогою `gateway.remote.tlsFingerprint` під час використання `wss://`. Відкритий текст `ws://` типово дозволений лише для loopback. Для довірених шляхів -приватної мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у клієнтському процесі як -break-glass. Це навмисно лише середовище процесу, а не ключ конфігурації +приватної мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як +аварійний виняток. Це навмисно лише середовище процесу, а не ключ конфігурації `openclaw.json`. -Мобільне сполучення та Android-маршрути gateway, задані вручну або скануванням, суворіші: -cleartext приймається для loopback, але приватні LAN, link-local, `.local` і -імена хостів без крапок мають використовувати TLS, якщо ви явно не погодилися на довірений -cleartext-шлях приватної мережі. +Мобільне сполучення та ручні або скановані маршрути gateway Android суворіші: +відкритий текст приймається для loopback, але private-LAN, link-local, `.local` і +імена хостів без крапок мають використовувати TLS, якщо ви явно не погодитеся на довірений +шлях відкритого тексту в приватній мережі. Локальне сполучення пристроїв: - Сполучення пристроїв автоматично схвалюється для прямих підключень local loopback, щоб клієнти на тому самому хості працювали плавно. -- OpenClaw також має вузький backend/container-local шлях самопідключення для +- OpenClaw також має вузький шлях самопідключення backend/container-local для довірених допоміжних потоків зі спільним секретом. -- Підключення через tailnet і LAN, зокрема same-host tailnet bind, вважаються - віддаленими для сполучення й усе ще потребують схвалення. -- Докази forwarded-header у loopback-запиті дискваліфікують - loopback-локальність. Автосхвалення metadata-upgrade має вузьку область дії. Див. - [Сполучення Gateway](/uk/gateway/pairing) для обох правил. +- Підключення tailnet і LAN, включно з прив’язками tailnet на тому самому хості, вважаються + віддаленими для сполучення й усе одно потребують схвалення. +- Докази з forwarded-header у запиті loopback дискваліфікують локальність loopback. + Автоматичне схвалення metadata-upgrade має вузьку область дії. Див. + [сполучення Gateway](/uk/gateway/pairing) для обох правил. Режими автентифікації: - `gateway.auth.mode: "token"`: спільний bearer-токен (рекомендовано для більшості налаштувань). - `gateway.auth.mode: "password"`: автентифікація паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: довіра identity-aware reverse proxy для автентифікації користувачів і передавання ідентичності через заголовки (див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "trusted-proxy"`: довірте автентифікацію користувачів identity-aware reverse proxy і передавання ідентичності через заголовки (див. [автентифікацію довіреного проксі](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (токен/пароль): 1. Згенеруйте/задайте новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). 2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він наглядає за Gateway). -3. Оновіть усіх віддалених клієнтів (`gateway.remote.token` / `.password` на машинах, що звертаються до Gateway). -4. Переконайтеся, що ви більше не можете підключитися зі старими обліковими даними. +3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які викликають Gateway). +4. Переконайтеся, що зі старими обліковими даними підключитися більше неможливо. ### Заголовки ідентичності Tailscale Serve -Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw +Коли `gateway.auth.allowTailscale` дорівнює `true` (типово для Serve), OpenClaw приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації Control UI/WebSocket. OpenClaw перевіряє ідентичність, розв’язуючи адресу -`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) -і зіставляючи її із заголовком. Це спрацьовує лише для запитів, що потрапляють на loopback +`x-forwarded-for` через локальний daemon Tailscale (`tailscale whois`) +і зіставляючи її із заголовком. Це спрацьовує лише для запитів, які потрапляють у loopback і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як їх вставляє Tailscale. Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` -серіалізуються до того, як обмежувач зафіксує помилку. Тому одночасні помилкові повтори -від одного клієнта Serve можуть негайно заблокувати другу спробу -замість того, щоб пройти наввипередки як дві звичайні невідповідності. +серіалізуються до того, як обмежувач зафіксує невдачу. Тому одночасні невдалі повтори +від одного клієнта Serve можуть негайно заблокувати другу спробу, +а не пройти в гонці як дві звичайні невідповідності. Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують автентифікацію через заголовки ідентичності Tailscale. Вони й далі дотримуються +**не** використовують автентифікацію через заголовки ідентичності Tailscale. Вони все одно дотримуються налаштованого режиму HTTP-автентифікації gateway. -Важлива примітка щодо межі: +Важлива примітка про межі: -- HTTP bearer-автентифікація Gateway фактично надає доступ оператора за принципом "усе або нічого". -- Розглядайте облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як операторські секрети з повним доступом для цього gateway. -- На OpenAI-сумісній HTTP-поверхні bearer-автентифікація зі спільним секретом відновлює повні типові операторські області (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не обмежують цей шлях зі спільним секретом. -- Семантика областей на рівні запиту в HTTP застосовується лише тоді, коли запит надходить із режиму з ідентичністю, як-от автентифікація через довірений проксі або `gateway.auth.mode="none"` на приватному ingress. -- У таких режимах з ідентичністю пропуск `x-openclaw-scopes` повертає до звичайного типового набору операторських областей; надсилайте заголовок явно, коли потрібен вужчий набір областей. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer-автентифікація токеном/паролем також вважається там повним операторським доступом, тоді як режими з ідентичністю все ще поважають оголошені області. -- Не діліться цими обліковими даними з недовіреними викликачами; надавайте перевагу окремим gateway для кожної межі довіри. +- Bearer-автентифікація HTTP Gateway фактично є доступом оператора за принципом "усе або нічого". +- Вважайте облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, операторськими секретами з повним доступом для цього gateway. +- На HTTP-поверхні, сумісній з OpenAI, bearer-автентифікація зі спільним секретом відновлює повні типові області оператора (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. +- Семантика областей для кожного запиту в HTTP застосовується лише тоді, коли запит надходить із режиму з ідентичністю, як-от автентифікація довіреного проксі або `gateway.auth.mode="none"` на приватному ingress. +- У цих режимах з ідентичністю відсутність `x-openclaw-scopes` повертається до звичайного типового набору областей оператора; надсилайте заголовок явно, коли потрібен вужчий набір областей. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer-автентифікація токеном/паролем також трактується там як повний операторський доступ, тоді як режими з ідентичністю все ще враховують оголошені області. +- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим gateway для кожної межі довіри. -**Припущення довіри:** безтокенова автентифікація Serve припускає, що хост gateway є довіреним. -Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо недовірений -локальний код може запускатися на хості gateway, вимкніть `gateway.auth.allowTailscale` +**Припущення довіри:** автентифікація Serve без токена припускає, що хост gateway є довіреним. +Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо недовірений +локальний код може виконуватися на хості gateway, вимкніть `gateway.auth.allowTailscale` і вимагайте явної автентифікації зі спільним секретом через `gateway.auth.mode: "token"` або `"password"`. -**Правило безпеки:** не пересилайте ці заголовки з вашого власного reverse proxy. Якщо +**Правило безпеки:** не пересилайте ці заголовки зі свого власного reverse proxy. Якщо ви завершуєте TLS або проксіюєте перед gateway, вимкніть -`gateway.auth.allowTailscale` і натомість використовуйте автентифікацію зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) або [Автентифікацію через довірений проксі](/uk/gateway/trusted-proxy-auth). +`gateway.auth.allowTailscale` і використовуйте автентифікацію зі спільним секретом (`gateway.auth.mode: +"token"` або `"password"`) або [автентифікацію довіреного проксі](/uk/gateway/trusted-proxy-auth) +натомість. Довірені проксі: -- Якщо ви завершуєте TLS перед Gateway, задайте `gateway.trustedProxies` на IP-адреси вашого проксі. -- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) з цих IP-адрес, щоб визначати IP клієнта для локальних перевірок сполучення й HTTP auth/local перевірок. +- Якщо ви завершуєте TLS перед Gateway, задайте `gateway.trustedProxies` як IP-адреси вашого проксі. +- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) з цих IP-адрес, щоб визначати IP клієнта для перевірок локального сполучення та перевірок HTTP-автентифікації/локальності. - Переконайтеся, що ваш проксі **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Огляд вебу](/uk/web). +Див. [Tailscale](/uk/gateway/tailscale) і [огляд Web](/uk/web). ### Керування браузером через хост Node (рекомендовано) -Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост Node** -на машині з браузером і дозвольте Gateway проксіювати дії браузера (див. [Інструмент браузера](/uk/tools/browser)). -Ставтеся до сполучення Node як до адміністративного доступу. +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост node** +на машині браузера й дозвольте Gateway проксіювати дії браузера (див. [інструмент браузера](/uk/tools/browser)). +Ставтеся до сполучення node як до адміністративного доступу. Рекомендований шаблон: -- Тримайте Gateway і хост Node в одному tailnet (Tailscale). -- Сполучайте Node навмисно; вимкніть маршрутизацію браузерного проксі, якщо вона вам не потрібна. +- Тримайте Gateway і хост node в одному tailnet (Tailscale). +- Сполучайте node навмисно; вимкніть маршрутизацію проксі браузера, якщо вона вам не потрібна. Уникайте: -- Відкриття relay/control портів через LAN або публічний Інтернет. +- Виставлення портів ретрансляції/керування через LAN або публічний Інтернет. - Tailscale Funnel для кінцевих точок керування браузером (публічне відкриття). ### Секрети на диску -Припускайте, що все під `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети чи приватні дані: +Припускайте, що будь-що в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і списки дозволів. -- `credentials/**`: облікові дані каналів (приклад: облікові дані WhatsApp), списки дозволів для сполучення, застарілі OAuth-імпорти. -- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): файлове секретне навантаження, яке використовують `file` SecretRef-провайдери (`secrets.providers`). -- `agents//agent/auth.json`: файл застарілої сумісності. Статичні записи `api_key` очищуються, коли їх виявлено. -- `agents//sessions/**`: стенограми сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення й вивід інструментів. -- пакети bundled plugin: встановлені plugins (разом з їхніми `node_modules/`). -- `sandboxes/**`: робочі простори пісочниць інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині пісочниці. +- `openclaw.json`: конфігурація може містити токени (gateway, віддалений gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані каналів (приклад: облікові дані WhatsApp), allowlist сполучення, застарілі імпорти OAuth. +- `agents//agent/auth-profiles.json`: ключі API, профілі токенів, токени OAuth і необов’язкові `keyRef`/`tokenRef`. +- `secrets.json` (необов’язково): файлове секретне навантаження, яке використовують провайдери SecretRef `file` (`secrets.providers`). +- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються, коли їх виявлено. +- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. +- пакетні Plugin: встановлені plugins (плюс їхні `node_modules/`). +- `sandboxes/**`: робочі простори sandbox інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині sandbox. Поради з посилення захисту: - Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). -- Використовуйте повне шифрування диска на хості gateway. -- Надавайте перевагу окремому обліковому запису користувача ОС для Gateway, якщо хост спільний. +- Використовуйте повнодискове шифрування на хості gateway. +- Віддавайте перевагу окремому обліковому запису користувача ОС для Gateway, якщо хост спільний. -### Файли `.env` у робочому просторі +### Файли `.env` робочого простору OpenClaw завантажує локальні для робочого простору файли `.env` для агентів та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати runtime-керування gateway. - Будь-який ключ, що починається з `OPENCLAW_*`, блокується з недовірених файлів `.env` робочого простору. -- Налаштування кінцевих точок каналів для Matrix, Mattermost, IRC і Synology Chat також блокуються від перевизначень із `.env` робочого простору, тому клоновані робочі простори не можуть перенаправляти трафік bundled connector через локальну конфігурацію кінцевих точок. Env-ключі кінцевих точок (як-от `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) мають надходити із середовища процесу gateway або `env.shellEnv`, а не з завантаженого з робочого простору `.env`. -- Блок працює fail-closed: нова змінна runtime-керування, додана в майбутньому релізі, не може бути успадкована з доданого в репозиторій або наданого зловмисником `.env`; ключ ігнорується, а gateway зберігає власне значення. +- Налаштування кінцевих точок каналів для Matrix, Mattermost, IRC і Synology Chat також блокуються від перевизначень у `.env` робочого простору, тому клоновані робочі простори не можуть переспрямувати трафік пакетних конекторів через локальну конфігурацію кінцевих точок. Env-ключі кінцевих точок (такі як `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) мають походити із середовища процесу gateway або `env.shellEnv`, а не з `.env`, завантаженого з робочого простору. +- Блокування працює в закритому режимі: нова runtime-control змінна, додана в майбутньому випуску, не може бути успадкована з закоміченого або наданого зловмисником `.env`; ключ ігнорується, а gateway зберігає власне значення. - Довірені змінні середовища процесу/ОС (власна оболонка gateway, launchd/systemd unit, app bundle) усе ще застосовуються — це обмежує лише завантаження файлів `.env`. -Причина: файли `.env` робочого простору часто лежать поруч із кодом агента, випадково комітяться або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` пізніше ніколи не спричинить регресію до тихого успадкування зі стану робочого простору. +Чому: файли `.env` робочого простору часто лежать поруч із кодом агента, випадково комітяться або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` пізніше ніколи не призведе до регресії в непомітне успадкування зі стану робочого простору. -### Журнали й стенограми (редагування та зберігання) +### Журнали й транскрипти (редагування та зберігання) -Журнали й стенограми можуть розкривати чутливу інформацію, навіть коли контроль доступу правильний: +Журнали й транскрипти можуть витікати чутливою інформацією, навіть коли контроль доступу правильний: -- Журнали Gateway можуть містити підсумки інструментів, помилки й URL-адреси. -- Стенограми сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. +- Журнали Gateway можуть містити підсумки інструментів, помилки та URL. +- Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. Рекомендації: -- Залишайте редагування журналів і стенограм увімкненим (`logging.redactSensitive: "tools"`; типово). -- Додайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL-адреси). -- Під час надання діагностики надавайте перевагу `openclaw status --all` (зручно вставляти, секрети відредаговано) замість сирих журналів. -- Очищайте старі стенограми сесій і файли журналів, якщо вам не потрібне тривале зберігання. +- Залишайте редагування журналів і транскриптів увімкненим (`logging.redactSensitive: "tools"`; типово). +- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Під час надсилання діагностики віддавайте перевагу `openclaw status --all` (можна вставляти, секрети відредаговано) замість сирих журналів. +- Очищайте старі транскрипти сесій і файли журналів, якщо вам не потрібне довге зберігання. -Деталі: [Журналювання](/uk/gateway/logging) +Докладно: [журналювання](/uk/gateway/logging) -### DM: сполучення за замовчуванням +### DM: типово сполучення ```json5 { @@ -1017,7 +1019,7 @@ OpenClaw завантажує локальні для робочого прос } ``` -### Групи: вимагати згадку всюди +### Групи: вимагайте згадку всюди ```json { @@ -1043,27 +1045,27 @@ OpenClaw завантажує локальні для робочого прос ### Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі телефонних номерів розгляньте запуск вашого ШІ на окремому телефонному номері, відмінному від особистого: +Для каналів на основі телефонних номерів розгляньте запуск вашого AI на окремому телефонному номері, відмінному від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: ШІ обробляє їх із відповідними межами +- Номер бота: ШІ обробляє їх із належними межами ### Режим лише для читання (через пісочницю та інструменти) Ви можете створити профіль лише для читання, поєднавши: - `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` без доступу до робочої області) -- списки дозволу/заборони інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. +- списки дозволених/заборонених інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. Додаткові варіанти посилення захисту: -- `tools.exec.applyPatch.workspaceOnly: true` (стандартно): гарантує, що `apply_patch` не може записувати/видаляти поза каталогом робочої області, навіть коли пісочницю вимкнено. Установлюйте `false` лише якщо ви навмисно хочете, щоб `apply_patch` змінював файли поза робочою областю. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автоматичного завантаження зображень нативного промпта каталогом робочої області (корисно, якщо сьогодні ви дозволяєте абсолютні шляхи й хочете один захисний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от домашній каталог, для робочих областей агентів/робочих областей пісочниці. Широкі корені можуть відкрити інструментам файлової системи доступ до чутливих локальних файлів (наприклад, стану/конфігурації під `~/.openclaw`). +- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти поза каталогом робочої області, навіть коли пісочницю вимкнено. Установлюйте `false` лише якщо ви навмисно хочете, щоб `apply_patch` змінював файли поза робочою областю. +- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автоматичного завантаження зображень нативного prompt каталогом робочої області (корисно, якщо сьогодні ви дозволяєте абсолютні шляхи й хочете єдиний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для робочих областей агентів/робочих областей пісочниці. Широкі корені можуть відкрити файловим інструментам доступ до чутливих локальних файлів (наприклад, стану/конфігурації під `~/.openclaw`). ### Безпечна базова конфігурація (скопіювати/вставити) -Одна конфігурація з «безпечними стандартними налаштуваннями», яка тримає Gateway приватним, вимагає сполучення через DM та уникає постійно активних групових ботів: +Одна конфігурація “безпечна за замовчуванням”, яка залишає Gateway приватним, вимагає парування через DM і уникає постійно ввімкнених групових ботів: ```json5 { @@ -1082,9 +1084,9 @@ OpenClaw завантажує локальні для робочого прос } ``` -Якщо ви також хочете виконання інструментів, «безпечніше за замовчуванням», додайте пісочницю + забороніть небезпечні інструменти для будь-якого агента, що не є власником (приклад нижче в розділі «Профілі доступу для окремих агентів»). +Якщо ви також хочете виконання інструментів “безпечніше за замовчуванням”, додайте пісочницю + забороніть небезпечні інструменти для будь-якого агента, який не є власником (приклад нижче в розділі “Профілі доступу для окремих агентів”). -Вбудована базова конфігурація для ходів агента, керованих чатом: відправники, що не є власниками, не можуть використовувати інструменти `cron` або `gateway`. +Вбудована базова конфігурація для керованих чатом ходів агента: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. ## Пісочниця (рекомендовано) @@ -1092,61 +1094,61 @@ OpenClaw завантажує локальні для робочого прос Два взаємодоповнювальні підходи: -- **Запускати весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) -- **Пісочниця інструментів** (`agents.defaults.sandbox`, Gateway на хості + інструменти, ізольовані пісочницею; Docker є стандартним бекендом): [Пісочниця](/uk/gateway/sandboxing) +- **Запуск повного Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) +- **Пісочниця інструментів** (`agents.defaults.sandbox`, хостовий gateway + інструменти, ізольовані пісочницею; Docker є типовим бекендом): [Пісочниця](/uk/gateway/sandboxing) -Щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` як `"agent"` (стандартно) або `"session"` для суворішої ізоляції за сесіями. `scope: "shared"` використовує один контейнер або робочу область. +Щоб запобігти міжагентському доступу, залишайте `agents.defaults.sandbox.scope` як `"agent"` (типово) або `"session"` для суворішої ізоляції за сесіями. `scope: "shared"` використовує один контейнер або одну робочу область. -Також врахуйте доступ до робочої області агента всередині пісочниці: +Також врахуйте доступ агента до робочої області всередині пісочниці: -- `agents.defaults.sandbox.workspaceAccess: "none"` (стандартно) лишає робочу область агента недоступною; інструменти працюють із робочою областю пісочниці під `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) залишає робочу область агента недоступною; інструменти працюють із робочою областю пісочниці під `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` монтує робочу область агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує робочу область агента для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонікалізованими вихідними шляхами. Трюки з батьківськими симлінками й канонічні псевдоніми домашнього каталогу все одно завершуються закритою відмовою, якщо вони розв’язуються в заблоковані корені, як-от `/etc`, `/var/run`, або каталоги облікових даних під домашнім каталогом ОС. +- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонікалізованими вихідними шляхами. Трюки з батьківськими символьними посиланнями та канонічні псевдоніми домашнього каталогу все одно завершуються закрито, якщо вони розв’язуються в заблоковані корені, як-от `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. -`tools.elevated` — це глобальний базовий аварійний вихід, який запускає exec поза пісочницею. Ефективний хост стандартно `gateway`, або `node`, коли ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для незнайомців. Ви можете додатково обмежити elevated для окремого агента через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). +`tools.elevated` — це глобальний базовий аварійний вихід, який запускає exec поза пісочницею. Ефективний хост типово `gateway`, або `node`, коли ціль exec налаштована на `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для незнайомців. Ви можете додатково обмежити підвищений режим для окремого агента через `agents.list[].tools.elevated`. Див. [Підвищений режим](/uk/tools/elevated). -### Захисний запобіжник делегування субагентам +### Запобіжник делегування субагентам -Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як ще одне рішення щодо межі доступу: +Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як ще одне рішення про межі: - Забороніть `sessions_spawn`, якщо агенту справді не потрібне делегування. - Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` для окремих агентів обмеженими відомо безпечними цільовими агентами. -- Для будь-якого робочого процесу, який має залишатися в пісочниці, викликайте `sessions_spawn` із `sandbox: "require"` (стандартно `inherit`). -- `sandbox: "require"` швидко завершується помилкою, коли цільове дочірнє середовище виконання не ізольоване пісочницею. +- Для будь-якого workflow, який має залишатися в пісочниці, викликайте `sessions_spawn` із `sandbox: "require"` (типово `inherit`). +- `sandbox: "require"` швидко завершується помилкою, коли цільове дочірнє runtime-середовище не перебуває в пісочниці. ## Ризики керування браузером -Увімкнення керування браузером дає моделі здатність керувати реальним браузером. -Якщо цей профіль браузера вже містить активні сесії входу, модель може -отримати доступ до цих акаунтів і даних. Ставтеся до профілів браузера як до **чутливого стану**: +Увімкнення керування браузером дає моделі змогу керувати справжнім браузером. +Якщо цей профіль браузера вже містить сесії з виконаним входом, модель може +отримати доступ до цих облікових записів і даних. Розглядайте профілі браузера як **чутливий стан**: -- Надавайте перевагу окремому профілю для агента (стандартний профіль `openclaw`). +- Надавайте перевагу виділеному профілю для агента (типовий профіль `openclaw`). - Уникайте спрямування агента на ваш особистий щоденний профіль. -- Тримайте керування браузером хоста вимкненим для агентів у пісочниці, якщо ви їм не довіряєте. -- Автономний API керування браузером через local loopback приймає лише автентифікацію спільним секретом - (bearer-автентифікацію токеном Gateway або пароль Gateway). Він не використовує - заголовки ідентичності trusted-proxy або Tailscale Serve. -- Ставтеся до завантажень браузера як до недовіреного вводу; надавайте перевагу ізольованому каталогу завантажень. -- Якщо можливо, вимкніть синхронізацію браузера/менеджери паролів у профілі агента (зменшує радіус ураження). -- Для віддалених Gateway припускайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого може дістатися цей профіль. -- Тримайте хости Gateway і node доступними лише в tailnet; уникайте відкриття портів керування браузером у LAN або публічний Інтернет. +- Тримайте керування браузером на хості вимкненим для агентів у пісочниці, якщо ви їм не довіряєте. +- Окремий API керування браузером через local loopback враховує лише автентифікацію спільним секретом + (bearer-автентифікацію токеном gateway або пароль gateway). Він не використовує + trusted-proxy чи заголовки ідентичності Tailscale Serve. +- Вважайте завантаження браузера недовіреним введенням; надавайте перевагу ізольованому каталогу завантажень. +- За можливості вимкніть синхронізацію браузера/менеджери паролів у профілі агента (зменшує радіус ураження). +- Для віддалених gateway припускайте, що “керування браузером” еквівалентне “доступу оператора” до всього, до чого може дістатися цей профіль. +- Тримайте Gateway і хости node доступними лише через tailnet; уникайте відкриття портів керування браузером у LAN або публічний Інтернет. - Вимикайте маршрутизацію через проксі браузера, коли вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим наявної сесії Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені в усьому, до чого може дістатися той профіль Chrome на хості. +- Режим наявної сесії Chrome MCP **не** є “безпечнішим”; він може діяти від вашого імені в усьому, до чого може дістатися цей профіль Chrome на хості. ### Політика SSRF браузера (сувора за замовчуванням) Політика навігації браузера OpenClaw сувора за замовчуванням: приватні/внутрішні призначення залишаються заблокованими, якщо ви явно не погодитеся. -- Стандартно: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація браузера тримає приватні/внутрішні/спеціального використання призначення заблокованими. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація браузера тримає приватні/внутрішні/спеціального використання призначення заблокованими. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. - Режим явної згоди: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціального використання призначення. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, зокрема заблоковані імена на кшталт `localhost`) для явних винятків. -- Навігацію перевіряють перед запитом і, наскільки можливо, повторно перевіряють на фінальному `http(s)` URL після навігації, щоб зменшити перенаправлення на основі редиректів. +- У суворому режимі використовуйте `hostnameAllowlist` (патерни на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, включно із заблокованими іменами на кшталт `localhost`) для явних винятків. +- Навігація перевіряється перед запитом і, у режимі best-effort, повторно перевіряється на фінальному `http(s)` URL після навігації, щоб зменшити pivot через перенаправлення. Приклад суворої політики: @@ -1165,15 +1167,15 @@ OpenClaw завантажує локальні для робочого прос ## Профілі доступу для окремих агентів (кілька агентів) З маршрутизацією кількох агентів кожен агент може мати власну пісочницю + політику інструментів: -використовуйте це, щоб надати **повний доступ**, **лише читання** або **без доступу** для кожного агента. +використовуйте це, щоб надати **повний доступ**, **лише читання** або **без доступу** для окремого агента. Див. [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) для повних подробиць і правил пріоритету. -Поширені сценарії: +Типові випадки використання: - Особистий агент: повний доступ, без пісочниці -- Сімейний/робочий агент: пісочниця + інструменти лише для читання -- Публічний агент: пісочниця + без інструментів файлової системи/оболонки +- Сімейний/робочий агент: у пісочниці + інструменти лише для читання +- Публічний агент: у пісочниці + без інструментів файлової системи/shell ### Приклад: повний доступ (без пісочниці) @@ -1215,7 +1217,7 @@ OpenClaw завантажує локальні для робочого прос } ``` -### Приклад: без доступу до файлової системи/оболонки (обмін повідомленнями провайдера дозволено) +### Приклад: без доступу до файлової системи/shell (обмін повідомленнями провайдера дозволено) ```json5 { @@ -1274,34 +1276,34 @@ OpenClaw завантажує локальні для робочого прос 1. **Зупиніть його:** зупиніть застосунок macOS (якщо він наглядає за Gateway) або завершіть ваш процес `openclaw gateway`. 2. **Закрийте експозицію:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** переведіть ризиковані DM/групи на `dmPolicy: "disabled"` / вимагайте згадки та видаліть записи allow-all `"*"`, якщо вони у вас були. +3. **Заморозьте доступ:** перемкніть ризиковані DM/групи на `dmPolicy: "disabled"` / вимагайте згадок і видаліть записи дозволу для всіх `"*"`, якщо вони були. ### Ротація (припускайте компрометацію, якщо секрети витекли) -1. Ротуйте автентифікацію Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. -2. Ротуйте секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на будь-якій машині, яка може викликати Gateway. -3. Ротуйте облікові дані провайдерів/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення зашифрованих payload секретів, коли вони використовуються). +1. Змініть автентифікацію Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. +2. Змініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на будь-якій машині, яка може викликати Gateway. +3. Змініть облікові дані провайдера/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделі/API в `auth-profiles.json` і значення зашифрованих payload секретів, якщо вони використовуються). ### Аудит 1. Перевірте журнали Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). 2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. 3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни Plugin). -4. Повторно запустіть `openclaw security audit --deep` і підтвердьте, що критичні знахідки усунено. +4. Повторно запустіть `openclaw security audit --deep` і підтвердьте, що критичні знахідки виправлено. -### Збір даних для звіту +### Зібрати для звіту -- Позначка часу, ОС хоста Gateway + версія OpenClaw -- Транскрипти сесій + короткий хвіст журналу (після редагування чутливого) +- Часова мітка, ОС хоста gateway + версія OpenClaw +- Транскрипти сесій + короткий хвіст журналу (після редагування) - Що надіслав атакувальник + що зробив агент -- Чи був Gateway відкритий поза loopback (LAN/Tailscale Funnel/Serve) +- Чи був Gateway відкритий за межами loopback (LAN/Tailscale Funnel/Serve) ## Сканування секретів за допомогою detect-secrets -CI запускає pre-commit hook `detect-secrets` у завданні `secrets`. -Push у `main` завжди запускають сканування всіх файлів. Pull request використовують -швидкий шлях за зміненими файлами, коли базовий коміт доступний, і повертаються до сканування всіх файлів -в іншому разі. Якщо це не проходить, є нові кандидати, яких ще немає в baseline. +CI запускає pre-commit hook `detect-secrets` у job `secrets`. +Push у `main` завжди запускають сканування всіх файлів. Pull requests використовують швидкий шлях +для змінених файлів, коли доступний базовий commit, і повертаються до сканування всіх файлів +в іншому разі. Якщо перевірка не проходить, є нові кандидати, яких ще немає в baseline. ### Якщо CI не проходить @@ -1312,27 +1314,27 @@ Push у `main` завжди запускають сканування всіх ``` 2. Зрозумійте інструменти: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із baseline - репозиторію та виключеннями. + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з baseline + і виключеннями репозиторію. - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline як справжній або хибнопозитивний. -3. Для справжніх секретів: ротуйте/видаліть їх, потім повторно запустіть сканування, щоб оновити baseline. +3. Для справжніх секретів: змініть/видаліть їх, потім повторно запустіть сканування, щоб оновити baseline. 4. Для хибнопозитивних: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові виключення, додайте їх до `.detect-secrets.cfg` і згенеруйте заново +5. Якщо вам потрібні нові виключення, додайте їх до `.detect-secrets.cfg` і повторно згенеруйте baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл конфігурації лише довідковий; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме потрібний стан. +Зафіксуйте оновлений `.secrets.baseline`, щойно він відображатиме потрібний стан. ## Повідомлення про проблеми безпеки Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте відкрито, доки це не виправлено -3. Ми зазначимо ваш внесок (якщо ви не віддаєте перевагу анонімності) +2. Не публікуйте відкрито, доки не буде виправлено +3. Ми зазначимо вас (якщо ви не віддаєте перевагу анонімності) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index fd113398e..d4add606f 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -4,58 +4,58 @@ read_when: - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - Ви використовували api.registerEmbeddedExtensionFactory до OpenClaw 2026.4.25 - Ви оновлюєте Plugin до сучасної архітектури Plugin - - Ви підтримуєте зовнішній Plugin для OpenClaw + - Ви супроводжуєте зовнішній Plugin OpenClaw sidebarTitle: Migrate to SDK summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-28T11:20:14Z" + generated_at: "2026-04-28T20:12:30Z" model: gpt-5.5 provider: openai - source_hash: 3f102c3632f6b51fcc007a53a3e3c4d47dbbee8e86a8d49b758cff38925fbbf1 + source_hash: efaf0f397e7b06a67fd324f1710ac62529dd2c039d483b381a8df5495716cd51 source_path: plugins/sdk-migration.md workflow: 16 --- OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури Plugin -із точковими, задокументованими імпортами. Якщо ваш Plugin був створений до +із сфокусованими, задокументованими імпортами. Якщо ваш Plugin було створено до нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система Plugin надавала дві надто відкриті поверхні, які дозволяли Plugin імпортувати +Стара система Plugin надавала дві широко відкриті поверхні, які дозволяли Plugins імпортувати усе потрібне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки - допоміжних функцій. Його було введено, щоб підтримувати роботу старіших Plugin на основі хуків, - поки будувалася нова архітектура Plugin. -- **`openclaw/plugin-sdk/infra-runtime`** — широкий набір runtime-допоміжних функцій, - який змішував системні події, стан Heartbeat, черги доставлення, допоміжні функції fetch/proxy, - файлові допоміжні функції, типи підтверджень і непов’язані утиліти. -- **`openclaw/plugin-sdk/config-runtime`** — широкий набір для сумісності конфігурації, - який досі містить застарілі прямі допоміжні функції load/write під час - міграційного вікна. -- **`openclaw/extension-api`** — міст, який давав Plugin прямий доступ до - host-side допоміжних функцій, як-от вбудований runner агента. -- **`api.registerEmbeddedExtensionFactory(...)`** — видалений bundled hook лише для Pi, - який міг спостерігати події embedded-runner, як-от +- **`openclaw/plugin-sdk/compat`** — один імпорт, який реекспортував десятки + допоміжних функцій. Його було запроваджено, щоб старі Plugins на основі хуків продовжували працювати, поки + створювалася нова архітектура Plugin. +- **`openclaw/plugin-sdk/infra-runtime`** — широкий barrel із runtime-допоміжними функціями, який + змішував системні події, стан Heartbeat, черги доставки, допоміжні функції fetch/proxy, + файлові допоміжні функції, типи погоджень і непов’язані утиліти. +- **`openclaw/plugin-sdk/config-runtime`** — широкий barrel сумісності конфігурації, + який досі містить застарілі прямі допоміжні функції завантаження/запису протягом міграційного + вікна. +- **`openclaw/extension-api`** — міст, який надавав Plugins прямий доступ до + допоміжних функцій на боці хоста, як-от вбудований агентний runner. +- **`api.registerEmbeddedExtensionFactory(...)`** — видалений bundled + extension hook лише для Pi, який міг спостерігати події embedded-runner, такі як `tool_result`. Широкі поверхні імпорту тепер **застарілі**. Вони досі працюють під час виконання, -але нові Plugin не повинні їх використовувати, а наявні Plugin мають мігрувати до того, -як наступний major-реліз їх видалить. API реєстрації embedded extension factory -лише для Pi було видалено; натомість використовуйте middleware результатів інструментів. +але нові Plugins не повинні їх використовувати, а наявні Plugins мають виконати міграцію до того, +як наступний major release їх видалить. API реєстрації фабрики вбудованих extensions лише для Pi +було видалено; натомість використовуйте middleware для tool-result. -OpenClaw не видаляє й не переінтерпретовує задокументовану поведінку Plugin у тій самій -зміні, яка вводить заміну. Зміни контракту, що ламають сумісність, мають спочатку пройти -через адаптер сумісності, діагностику, документацію та вікно застарівання. +OpenClaw не видаляє і не переінтерпретовує задокументовану поведінку Plugin у тій самій +зміні, яка запроваджує заміну. Критичні зміни контракту мають спочатку пройти +через адаптер сумісності, діагностику, документацію і вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки -runtime-реєстрації. +реєстрації під час виконання. - Шар зворотної сумісності буде видалено в майбутньому major-релізі. - Plugin, які досі імпортують із цих поверхонь, зламаються, коли це станеться. - Реєстрації embedded extension factory лише для Pi вже більше не завантажуються. + Шар зворотної сумісності буде видалено в майбутньому major release. + Plugins, які досі імпортують із цих поверхонь, зламаються, коли це станеться. + Реєстрації фабрик вбудованих extensions лише для Pi вже більше не завантажуються. ## Чому це змінилося @@ -63,22 +63,22 @@ runtime-реєстрації. Старий підхід спричиняв проблеми: - **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки непов’язаних модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту +- **Циклічні залежності** — широкі реекспорти спрощували створення циклів імпорту - **Нечітка поверхня API** — не було способу визначити, які експорти стабільні, а які внутрішні -Сучасний SDK Plugin виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим самодостатнім модулем із чітким призначенням і задокументованим контрактом. +Сучасний SDK для Plugin це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. Legacy provider convenience seams для bundled channels також видалено. -Channel-branded допоміжні seams були приватними скороченнями mono-repo, а не стабільними -контрактами Plugin. Використовуйте натомість вузькі generic subpaths SDK. Усередині bundled -робочого простору Plugin тримайте provider-owned допоміжні функції у власному `api.ts` або +Допоміжні seams із брендингом каналів були приватними скороченнями mono-repo, а не стабільними +контрактами Plugin. Використовуйте натомість вузькі generic SDK subpaths. Усередині workspace +bundled Plugin тримайте provider-owned helpers у власному `api.ts` або `runtime-api.ts` цього Plugin. -Поточні bundled provider приклади: +Поточні приклади bundled provider: -- Anthropic тримає Claude-specific stream helpers у власному `api.ts` / - `contract-api.ts` seam +- Anthropic тримає Claude-specific stream helpers у власному seam `api.ts` / + `contract-api.ts` - OpenAI тримає provider builders, default-model helpers і realtime provider builders у власному `api.ts` - OpenRouter тримає provider builder і onboarding/config helpers у власному @@ -86,46 +86,47 @@ Channel-branded допоміжні seams були приватними скор ## Політика сумісності -Для зовнішніх Plugin робота із сумісністю відбувається в такому порядку: +Для зовнішніх Plugins робота із сумісністю відбувається в такому порядку: -1. додайте новий контракт -2. збережіть стару поведінку, під’єднану через адаптер сумісності -3. виведіть діагностичне повідомлення або попередження, яке називає старий шлях і заміну -4. покрийте обидва шляхи тестами -5. задокументуйте застарівання та шлях міграції -6. видаляйте лише після оголошеного міграційного вікна, зазвичай у major-релізі +1. додати новий контракт +2. зберегти стару поведінку, підключену через адаптер сумісності +3. вивести діагностику або попередження, що називає старий шлях і заміну +4. покрити обидва шляхи тестами +5. задокументувати застарівання і шлях міграції +6. видаляти лише після оголошеного міграційного вікна, зазвичай у major release -Maintainers можуть перевіряти поточну чергу міграції за допомогою +Maintainers можуть перевірити поточну чергу міграції за допомогою `pnpm plugins:boundary-report`. Використовуйте `pnpm plugins:boundary-report:summary` для -стислих лічильників, `--owner ` для одного Plugin або власника сумісності, і +компактних підрахунків, `--owner ` для одного Plugin або власника сумісності, і `pnpm plugins:boundary-report:ci`, коли CI gate має падати через прострочені записи сумісності, cross-owner reserved SDK imports або unused reserved SDK subpaths. Звіт групує застарілі -записи сумісності за датою видалення, рахує локальні посилання в коді/документації, -показує cross-owner reserved SDK imports і підсумовує приватний +записи сумісності за датою видалення, підраховує локальні посилання в коді/документації, +виявляє cross-owner reserved SDK imports і підсумовує приватний memory-host SDK bridge, щоб очищення сумісності залишалося явним, а не -покладалося на ad hoc пошуки. Reserved SDK subpaths повинні мати відстежене використання власником; -unused reserved helper exports слід видалити з публічного SDK. +спиралося на ad hoc пошуки. Reserved SDK subpaths повинні мати відстежене використання власником; +невикористані reserved helper exports слід видалити з public SDK. -Якщо поле маніфесту досі приймається, автори Plugin можуть продовжувати ним користуватися, доки -документація й діагностика не скажуть інше. Новий код має віддавати перевагу задокументованій -заміні, але наявні Plugin не повинні ламатися під час звичайних minor-релізів. +Якщо поле маніфесту досі приймається, автори Plugin можуть продовжувати його використовувати, доки +документація й діагностика не скажуть інше. Новий код має надавати перевагу задокументованій +заміні, але наявні Plugins не повинні ламатися під час звичайних minor +releases. -## Як мігрувати +## Як виконати міграцію - Bundled Plugin повинні припинити прямі виклики + Bundled Plugins мають припинити прямі виклики `api.runtime.config.loadConfig()` і - `api.runtime.config.writeConfigFile(...)`. Віддавайте перевагу конфігурації, яку - вже передано в активний шлях виклику. Довгоживучі handlers, яким потрібен - поточний snapshot процесу, можуть використовувати `api.runtime.config.current()`. Довгоживучі - agent tools мають використовувати `ctx.getRuntimeConfig()` з контексту інструмента всередині - `execute`, щоб інструмент, створений до запису конфігурації, усе одно бачив оновлену + `api.runtime.config.writeConfigFile(...)`. Надавайте перевагу конфігурації, яку + вже було передано в активний шлях виклику. Long-lived handlers, яким потрібен + поточний snapshot процесу, можуть використовувати `api.runtime.config.current()`. Long-lived + agent tools мають використовувати `ctx.getRuntimeConfig()` з tool context усередині + `execute`, щоб tool, створений до запису конфігурації, все одно бачив оновлену runtime config. - Записи конфігурації мають проходити через транзакційні допоміжні функції та вибирати - політику після запису: + Записи конфігурації мають проходити через transactional helpers і вибирати + after-write policy: ```typescript await api.runtime.config.mutateConfigFile({ @@ -139,45 +140,45 @@ unused reserved helper exports слід видалити з публічного Використовуйте `afterWrite: { mode: "restart", reason: "..." }`, коли caller знає, що зміна потребує clean gateway restart, і `afterWrite: { mode: "none", reason: "..." }` лише тоді, коли caller володіє - follow-up і свідомо хоче приглушити reload planner. - Результати мутації містять типізований summary `followUp` для тестів і логування; - Gateway залишається відповідальним за застосування або планування перезапуску. - `loadConfig` і `writeConfigFile` залишаються застарілими compatibility - helpers для зовнішніх Plugin під час міграційного вікна й один раз попереджають із - compatibility code `runtime-config-load-write`. Bundled Plugin і runtime-код репозиторію - захищені scanner guardrails у + подальшою дією і свідомо хоче придушити reload planner. + Результати мутації містять typed `followUp` summary для тестів і logging; + Gateway залишається відповідальним за застосування або планування restart. + `loadConfig` і `writeConfigFile` залишаються застарілими допоміжними функціями сумісності + для зовнішніх Plugins протягом міграційного вікна і попереджають один раз із + compatibility code `runtime-config-load-write`. Bundled Plugins і repo + runtime code захищені scanner guardrails у `pnpm check:deprecated-internal-config-api` і - `pnpm check:no-runtime-action-load-config`: нове production-використання в Plugin - одразу падає, прямі записи конфігурації падають, методи gateway server мають використовувати + `pnpm check:no-runtime-action-load-config`: нове production використання Plugin + завершується помилкою відразу, direct config writes завершуються помилкою, методи gateway server мають використовувати request runtime snapshot, runtime channel send/action/client helpers - мають отримувати конфігурацію зі своєї межі, а довгоживучі runtime modules мають + мають отримувати config зі своєї межі, а long-lived runtime modules мають нуль дозволених ambient викликів `loadConfig()`. Новий код Plugin також має уникати імпорту широкого - compatibility barrel `openclaw/plugin-sdk/config-runtime`. Використовуйте вузький - subpath SDK, що відповідає задачі: + barrel сумісності `openclaw/plugin-sdk/config-runtime`. Використовуйте вузький + SDK subpath, який відповідає задачі: | Потреба | Імпорт | | --- | --- | - | Типи конфігурації, як-от `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | - | Assertions для вже завантаженої конфігурації та lookup конфігурації plugin-entry | `openclaw/plugin-sdk/plugin-config-runtime` | - | Читання поточного runtime snapshot | `openclaw/plugin-sdk/runtime-config-snapshot` | - | Записи конфігурації | `openclaw/plugin-sdk/config-mutation` | + | Типи config, такі як `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | + | Уже завантажені config assertions і plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime` | + | Читання current runtime snapshot | `openclaw/plugin-sdk/runtime-config-snapshot` | + | Записи config | `openclaw/plugin-sdk/config-mutation` | | Допоміжні функції session store | `openclaw/plugin-sdk/session-store-runtime` | | Markdown table config | `openclaw/plugin-sdk/markdown-table-runtime` | - | Group policy runtime helpers | `openclaw/plugin-sdk/runtime-group-policy` | + | Допоміжні функції group policy runtime | `openclaw/plugin-sdk/runtime-group-policy` | | Secret input resolution | `openclaw/plugin-sdk/secret-input-runtime` | | Model/session overrides | `openclaw/plugin-sdk/model-session-runtime` | - Bundled Plugin та їхні тести scanner-guarded проти широкого - barrel, щоб імпорти й mocks залишалися локальними до потрібної їм поведінки. Широкий + Bundled Plugins і їхні тести захищені scanner-guard від широкого + barrel, щоб imports і mocks залишалися локальними до потрібної їм поведінки. Широкий barrel досі існує для зовнішньої сумісності, але новий код не повинен від нього залежати. - Bundled Plugin мають замінити tool-result handlers + Bundled Plugins мають замінити tool-result handlers `api.registerEmbeddedExtensionFactory(...)` лише для Pi на runtime-neutral middleware. @@ -200,39 +201,40 @@ unused reserved helper exports слід видалити з публічного } ``` - Зовнішні Plugin не можуть реєструвати tool-result middleware, бо воно може + Зовнішні Plugins не можуть реєструвати tool-result middleware, бо воно може переписувати high-trust tool output до того, як модель його побачить. - Approval-capable channel Plugin тепер відкривають native approval behavior через + Approval-capable channel Plugins тепер expose native approval behavior через `approvalCapability.nativeRuntime` плюс спільний runtime-context registry. Ключові зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть approval-specific auth/delivery із legacy wiring `plugin.auth` / + - Перенесіть approval-specific auth/delivery зі старого wiring `plugin.auth` / `plugin.approvals` на `approvalCapability` - - `ChannelPlugin.approvals` видалено з публічного контракту channel-plugin; - перенесіть delivery/native/render fields на `approvalCapability` + - `ChannelPlugin.approvals` видалено з public channel-plugin + contract; перенесіть delivery/native/render fields на `approvalCapability` - `plugin.auth` залишається лише для channel login/logout flows; approval auth - hooks там core більше не читає + hooks там більше не читаються core - Реєструйте channel-owned runtime objects, як-от clients, tokens або Bolt apps, через `openclaw/plugin-sdk/channel-runtime-context` - Не надсилайте plugin-owned reroute notices із native approval handlers; core тепер володіє routed-elsewhere notices з actual delivery results - Передаючи `channelRuntime` у `createChannelManager(...)`, надайте - справжню поверхню `createPluginRuntime().channel`. Partial stubs відхиляються. + справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. - Див. `/plugins/sdk-channel-plugins` для поточного layout approval capability. + Див. `/plugins/sdk-channel-plugins` для поточного approval capability + layout. Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, unresolved Windows - `.cmd`/`.bat` wrappers тепер fail closed, якщо ви явно не передасте + wrappers `.cmd`/`.bat` тепер fail closed, якщо ви явно не передасте `allowShellFallback: true`. ```typescript @@ -248,13 +250,13 @@ unused reserved helper exports слід видалити з публічного }); ``` - Якщо ваш caller навмисно не покладається на shell fallback, не встановлюйте + Якщо ваш caller не покладається навмисно на shell fallback, не задавайте `allowShellFallback` і натомість обробіть thrown error. - Пошукайте у своєму Plugin імпорти з будь-якої застарілої поверхні: + Знайдіть у своєму Plugin імпорти з будь-якої застарілої поверхні: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -265,8 +267,8 @@ unused reserved helper exports слід видалити з публічного - - Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні зіставляється з конкретним сучасним шляхом імпорту: ```typescript // Before (deprecated backwards-compatibility layer) @@ -282,7 +284,8 @@ unused reserved helper exports слід видалити з публічного import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для host-side допоміжних функцій використовуйте injected plugin runtime замість прямого імпорту: + Для допоміжних функцій на боці хоста використовуйте injected plugin runtime замість прямого + імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -293,7 +296,7 @@ unused reserved helper exports слід видалити з публічного const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується до інших застарілих допоміжних функцій мосту: + Той самий шаблон застосовується до інших застарілих допоміжних засобів bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -303,48 +306,48 @@ unused reserved helper exports слід видалити з публічного | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні функції сховища сеансів | `api.runtime.agent.session.*` | + | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | `openclaw/plugin-sdk/infra-runtime` досі існує для зовнішньої - сумісності, але новий код має імпортувати сфокусовану поверхню допоміжних - функцій, яка йому фактично потрібна: + сумісності, але новий код має імпортувати сфокусовану поверхню допоміжних засобів, яка + йому фактично потрібна: | Потреба | Імпорт | | --- | --- | - | Допоміжні функції черги системних подій | `openclaw/plugin-sdk/system-event-runtime` | - | Допоміжні функції подій Heartbeat і видимості | `openclaw/plugin-sdk/heartbeat-runtime` | - | Очищення черги очікуваного доставлення | `openclaw/plugin-sdk/delivery-queue-runtime` | + | Допоміжні засоби черги системних подій | `openclaw/plugin-sdk/system-event-runtime` | + | Допоміжні засоби подій Heartbeat і видимості | `openclaw/plugin-sdk/heartbeat-runtime` | + | Спорожнення черги очікуваної доставки | `openclaw/plugin-sdk/delivery-queue-runtime` | | Телеметрія активності каналу | `openclaw/plugin-sdk/channel-activity-runtime` | - | Кеші дедуплікації в пам’яті | `openclaw/plugin-sdk/dedupe-runtime` | - | Допоміжні функції безпечних шляхів до локальних файлів і медіа | `openclaw/plugin-sdk/file-access-runtime` | + | In-memory кеші дедуплікації | `openclaw/plugin-sdk/dedupe-runtime` | + | Безпечні допоміжні засоби шляхів локальних файлів/медіа | `openclaw/plugin-sdk/file-access-runtime` | | Fetch з урахуванням диспетчера | `openclaw/plugin-sdk/runtime-fetch` | - | Допоміжні функції проксі та захищеного fetch | `openclaw/plugin-sdk/fetch-runtime` | - | Типи політики SSRF-диспетчера | `openclaw/plugin-sdk/ssrf-dispatcher` | - | Типи запиту й вирішення схвалення | `openclaw/plugin-sdk/approval-runtime` | - | Допоміжні функції payload відповіді на схвалення та команд | `openclaw/plugin-sdk/approval-reply-runtime` | - | Допоміжні функції форматування помилок | `openclaw/plugin-sdk/error-runtime` | + | Допоміжні засоби проксі та захищеного fetch | `openclaw/plugin-sdk/fetch-runtime` | + | Типи політики диспетчера SSRF | `openclaw/plugin-sdk/ssrf-dispatcher` | + | Типи запиту/розв’язання затвердження | `openclaw/plugin-sdk/approval-runtime` | + | Допоміжні засоби payload відповіді на затвердження та команд | `openclaw/plugin-sdk/approval-reply-runtime` | + | Допоміжні засоби форматування помилок | `openclaw/plugin-sdk/error-runtime` | | Очікування готовності транспорту | `openclaw/plugin-sdk/transport-ready-runtime` | - | Допоміжні функції безпечних токенів | `openclaw/plugin-sdk/secure-random-runtime` | - | Обмежена конкурентність асинхронних завдань | `openclaw/plugin-sdk/concurrency-runtime` | + | Допоміжні засоби безпечних токенів | `openclaw/plugin-sdk/secure-random-runtime` | + | Обмежена конкурентність асинхронних задач | `openclaw/plugin-sdk/concurrency-runtime` | | Числове приведення | `openclaw/plugin-sdk/number-runtime` | - | Локальне для процесу асинхронне блокування | `openclaw/plugin-sdk/async-lock-runtime` | - | Файлові блокування | `openclaw/plugin-sdk/file-lock` | + | Локальний для процесу асинхронний lock | `openclaw/plugin-sdk/async-lock-runtime` | + | Файлові lock | `openclaw/plugin-sdk/file-lock` | - Вбудовані plugins захищені сканером від `infra-runtime`, тому код репозиторію - не може повернутися до широкого barrel. + Вбудовані plugins захищені сканером від `infra-runtime`, тож код репозиторію + не може регресувати до широкого barrel. - + Новий код маршрутів каналів має використовувати `openclaw/plugin-sdk/channel-route`. - Старі назви route-key і comparable-target залишаються псевдонімами для - сумісності протягом вікна міграції, але нові plugins мають використовувати - назви маршрутів, які прямо описують поведінку: + Старі назви route-key і comparable-target залишаються псевдонімами + сумісності на час міграційного вікна, але нові plugins мають використовувати назви маршрутів, + які прямо описують поведінку: - | Стара допоміжна функція | Сучасна допоміжна функція | + | Старий допоміжний засіб | Сучасний допоміжний засіб | | --- | --- | | `channelRouteIdentityKey(...)` | `channelRouteDedupeKey(...)` | | `channelRouteKey(...)` | `channelRouteCompactKey(...)` | @@ -354,11 +357,11 @@ unused reserved helper exports слід видалити з публічного | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | - Сучасні допоміжні функції маршрутів узгоджено нормалізують `{ channel, to, accountId, threadId }` - для нативних схвалень, пригнічення відповідей, дедуплікації вхідних повідомлень, - доставлення Cron і маршрутизації сеансів. Якщо ваш plugin має власну граматику - цілей, використовуйте `resolveChannelRouteTargetWithParser(...)`, щоб адаптувати цей - parser до того самого контракту цілі маршруту. + Сучасні допоміжні засоби маршрутів узгоджено нормалізують `{ channel, to, accountId, threadId }` + для нативних затверджень, приглушення відповідей, вхідної дедуплікації, + cron-доставки та маршрутизації сесій. Якщо ваш plugin має власну граматику цілей, + використовуйте `resolveChannelRouteTargetWithParser(...)`, щоб адаптувати цей + парсер до того самого контракту route target. @@ -373,206 +376,208 @@ unused reserved helper exports слід видалити з публічного ## Довідник шляхів імпорту - | Шлях імпорту | Призначення | Основні експорти | + | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний модуль входу Plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий узагальнений реекспорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічний помічник точки входу plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий об'єднувальний реекспорт для визначень/будівників точок входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний модуль входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Спеціалізовані визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити списку дозволених, конструктори стану налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби нотаток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `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/provider-entry` | Помічник точки входу для одного провайдера | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Сфокусовані визначення й будівники точок входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні помічники майстра налаштування | Запити списку дозволених, будівники стану налаштування | + | `plugin-sdk/setup-runtime` | Runtime-помічники часу налаштування | Імпортобезпечні адаптери патчів налаштування, помічники приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `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` | Помічники account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Помічники пошуку облікового запису | Помічники пошуку облікового запису й резервного значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі помічники облікових записів | Помічники списку облікових записів/дій облікового запису | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви парування DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді, індикація набору та зв’язування доставлення джерела | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | + | `plugin-sdk/channel-pairing` | Примітиви сполучення DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді, набір тексту та підключення доставки джерела | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Спільні примітиви схеми конфігурації каналу й лише універсальний конструктор | - | `plugin-sdk/bundled-channel-config-schema` | Пакетні схеми конфігурації | Лише підтримувані OpenClaw пакетні plugins; нові plugins мають визначати локальні для plugin схеми | - | `plugin-sdk/channel-config-schema-legacy` | Застарілі пакетні схеми конфігурації | Лише псевдонім сумісності; для підтримуваних пакетних plugins використовуйте `plugin-sdk/bundled-channel-config-schema` | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Допоміжні засоби стану облікового запису та життєвого циклу потоку чернеток | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного конверта | Спільні допоміжні засоби маршруту й конструктора конверта | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідної відповіді | Спільні допоміжні засоби запису та диспетчеризації | - | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні засоби вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Допоміжні засоби залежностей вихідного надсилання | Легкий пошук `resolveOutboundSendDep` без імпорту повного вихідного runtime | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідного доставлення, делегата ідентичності/надсилання, сесії, форматування та планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби payload медіа | Конструктор payload медіа агента для застарілих схем полів | - | `plugin-sdk/channel-runtime` | Застаріла прокладка сумісності | Лише застарілі утиліти runtime каналу | + | `plugin-sdk/channel-config-schema` | Будівники схеми конфігурації | Лише спільні примітиви схеми конфігурації каналу й універсальний будівник | + | `plugin-sdk/bundled-channel-config-schema` | Вбудовані схеми конфігурації | Лише вбудовані plugins, підтримувані OpenClaw; нові plugins мають визначати локальні для plugin схеми | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі вбудовані схеми конфігурації | Лише псевдонім сумісності; використовуйте `plugin-sdk/bundled-channel-config-schema` для підтримуваних вбудованих plugins | + | `plugin-sdk/telegram-command-config` | Помічники конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Розв'язання політики груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Помічники стану облікового запису й життєвого циклу потоку чернеток | `createAccountStatusSink`, помічники фіналізації попереднього перегляду чернетки | + | `plugin-sdk/inbound-envelope` | Помічники вхідного конверта | Спільні помічники маршруту й будівника конверта | + | `plugin-sdk/inbound-reply-dispatch` | Помічники вхідної відповіді | Спільні помічники запису й диспетчеризації | + | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Помічники розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Помічники вихідних медіа | Спільне завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Помічники залежностей вихідного надсилання | Легкий пошук `resolveOutboundSendDep` без імпорту повного вихідного runtime | + | `plugin-sdk/outbound-runtime` | Помічники вихідного runtime | Помічники вихідної доставки, делегата ідентичності/надсилання, сесії, форматування та планування payload | + | `plugin-sdk/thread-bindings-runtime` | Помічники прив'язок потоків | Помічники життєвого циклу прив'язок потоків і адаптера | + | `plugin-sdk/agent-media-payload` | Помічники застарілого media payload | Будівник agent media payload для застарілих компонувань полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | | `plugin-sdk/channel-send-result` | Типи результату надсилання | Типи результату відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/журналювання/резервного копіювання/інсталяції plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Середовище журналера/runtime, тайм-аут, повторні спроби та backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime plugin | Допоміжні засоби команд/hooks/http/інтерактивності plugin | - | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра hooks | Спільні допоміжні засоби Webhook/внутрішнього конвеєра hooks | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби runtime CLI | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway і патчів стану каналу | - | `plugin-sdk/config-runtime` | Застаріла прокладка сумісності конфігурації | Надавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Стабільні щодо резервного варіанта допоміжні засоби перевірки команд Telegram, коли пакетна контрактна поверхня Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів схвалення | Payload схвалення exec/plugin, допоміжні засоби capability/profile схвалення, маршрутизація/runtime нативного схвалення та форматування шляху структурованого відображення схвалення | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби автентифікації схвалення | Визначення схвалювача, авторизація дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта схвалення | Допоміжні засоби нативного профілю/фільтра схвалення exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставлення схвалення | Адаптери capability/доставлення нативного схвалення | - | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway схвалення | Спільний допоміжний засіб визначення Gateway схвалення | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера схвалення | Легкі допоміжні засоби завантаження адаптера нативного схвалення для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника схвалення | Ширші допоміжні засоби runtime обробника схвалення; надавайте перевагу вужчим адаптерним/Gateway seams, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілі схвалення | Допоміжні засоби прив’язки нативної цілі схвалення/облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді схвалення | Допоміжні засоби payload відповіді схвалення exec/plugin | - | `plugin-sdk/channel-runtime-context` | Допоміжні засоби runtime-контексту каналу | Універсальні допоміжні засоби реєстрації/отримання/спостереження runtime-контексту каналу | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби списку дозволених хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби runtime SSRF | Закріплений диспетчер, захищений fetch, допоміжні засоби політики SSRF | - | `plugin-sdk/system-event-runtime` | Допоміжні засоби системних подій | `enqueueSystemEvent`, `peekSystemEventEntries` | - | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби Heartbeat | Допоміжні засоби подій Heartbeat і видимості | - | `plugin-sdk/delivery-queue-runtime` | Допоміжні засоби черги доставлення | `drainPendingDeliveries` | - | `plugin-sdk/channel-activity-runtime` | Допоміжні засоби активності каналу | `recordChannelActivity` | - | `plugin-sdk/dedupe-runtime` | Допоміжні засоби дедуплікації | In-memory кеші дедуплікації | - | `plugin-sdk/file-access-runtime` | Допоміжні засоби доступу до файлів | Допоміжні засоби безпечних шляхів до локальних файлів/медіа | - | `plugin-sdk/transport-ready-runtime` | Допоміжні засоби готовності транспорту | `waitForTransportReady` | - | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичного шлюзування | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Обгорнуті допоміжні засоби fetch/proxy | `resolveFetch`, допоміжні засоби proxy | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні засоби повторних спроб | `RetryConfig`, `retryAsync`, виконавці політик | + | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі runtime-помічники | Помічники runtime/журналювання/резервного копіювання/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі помічники runtime env | Помічники logger/runtime env, timeout, retry та backoff | + | `plugin-sdk/plugin-runtime` | Спільні помічники runtime plugin | Помічники команд/хуків/http/інтерактивних можливостей plugin | + | `plugin-sdk/hook-runtime` | Помічники конвеєра хуків | Спільні помічники Webhook/внутрішнього конвеєра хуків | + | `plugin-sdk/lazy-runtime` | Помічники lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Помічники процесів | Спільні помічники exec | + | `plugin-sdk/cli-runtime` | Runtime-помічники CLI | Форматування команд, очікування, помічники версій | + | `plugin-sdk/gateway-runtime` | Помічники Gateway | Клієнт Gateway і помічники патчів стану каналу | + | `plugin-sdk/config-runtime` | Застарілий shim сумісності конфігурації | Надавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` | + | `plugin-sdk/telegram-command-config` | Помічники команд Telegram | Резервно-стабільні помічники перевірки команд Telegram, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Помічники запитів схвалення | Payload схвалення exec/plugin, помічники можливостей/профілів схвалення, нативна маршрутизація/ runtime схвалення та форматування структурованого шляху відображення схвалення | + | `plugin-sdk/approval-auth-runtime` | Помічники автентифікації схвалення | Розв'язання approver, авторизація дії в тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Помічники клієнта схвалення | Помічники профілю/фільтра нативного схвалення exec | + | `plugin-sdk/approval-delivery-runtime` | Помічники доставки схвалення | Нативні адаптери можливостей/доставки схвалення | + | `plugin-sdk/approval-gateway-runtime` | Помічники Gateway схвалення | Спільний помічник розв'язання Gateway для схвалення | + | `plugin-sdk/approval-handler-adapter-runtime` | Помічники адаптера схвалення | Легкі помічники завантаження нативного адаптера схвалення для гарячих entrypoints каналу | + | `plugin-sdk/approval-handler-runtime` | Помічники обробника схвалення | Ширші runtime-помічники обробника схвалення; надавайте перевагу вужчим адаптерним/Gateway швам, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Помічники цілі схвалення | Помічники прив'язки нативної цілі/облікового запису схвалення | + | `plugin-sdk/approval-reply-runtime` | Помічники відповіді схвалення | Помічники payload відповіді схвалення exec/plugin | + | `plugin-sdk/channel-runtime-context` | Помічники runtime-контексту каналу | Універсальні помічники register/get/watch runtime-контексту каналу | + | `plugin-sdk/security-runtime` | Помічники безпеки | Спільні помічники довіри, шлюзування DM, зовнішнього вмісту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Помічники політики SSRF | Помічники списку дозволених хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Runtime-помічники SSRF | Помічники закріпленого dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/system-event-runtime` | Помічники системних подій | `enqueueSystemEvent`, `peekSystemEventEntries` | + | `plugin-sdk/heartbeat-runtime` | Помічники Heartbeat | Помічники подій Heartbeat і видимості | + | `plugin-sdk/delivery-queue-runtime` | Помічники черги доставки | `drainPendingDeliveries` | + | `plugin-sdk/channel-activity-runtime` | Помічники активності каналу | `recordChannelActivity` | + | `plugin-sdk/dedupe-runtime` | Помічники дедуплікації | In-memory кеші дедуплікації | + | `plugin-sdk/file-access-runtime` | Помічники доступу до файлів | Помічники безпечних шляхів локальних файлів/медіа | + | `plugin-sdk/transport-ready-runtime` | Помічники готовності транспорту | `waitForTransportReady` | + | `plugin-sdk/collection-runtime` | Помічники обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Помічники шлюзування діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Помічники форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, помічники графа помилок | + | `plugin-sdk/fetch-runtime` | Обгорнуті помічники fetch/proxy | `resolveFetch`, помічники proxy | + | `plugin-sdk/host-runtime` | Помічники нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Помічники retry | `RetryConfig`, `retryAsync`, виконавці політик | | `plugin-sdk/allow-from` | Форматування списку дозволених | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних списку дозволених | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Шлюзування команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів | + | `plugin-sdk/allowlist-resolution` | Зіставлення входів списку дозволених | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Шлюзування команд і помічники командної поверхні | `resolveControlCommandGate`, помічники авторизації відправника, помічники реєстру команд, зокрема форматування меню динамічних аргументів | | `plugin-sdk/command-status` | Рендерери стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Розбір введення секретів | Допоміжні засоби введення секретів | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби захисту тіла Webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідна диспетчеризація, heartbeat, планувальник відповіді, поділ на фрагменти | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповіді | Фіналізація, диспетчеризація провайдера та допоміжні засоби міток розмов | - | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби фрагментів відповіді | Допоміжні засоби поділу тексту/markdown на фрагменти | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища й updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогу стану та 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 запиту | Виділення рядкових URL з подібних до запиту вхідних даних | - | `plugin-sdk/run-command` | Допоміжні засоби команд із таймером | Виконавець команд із таймером і нормалізованими stdout/stderr | + | `plugin-sdk/secret-input` | Розбір введення секретів | Помічники введення секретів | + | `plugin-sdk/webhook-ingress` | Помічники запитів Webhook | Утиліти цілей Webhook | + | `plugin-sdk/webhook-request-guards` | Помічники guard для тіла Webhook | Помічники читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідна диспетчеризація, heartbeat, планувальник відповіді, розбиття на chunks | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі помічники диспетчеризації відповіді | Фіналізація, диспетчеризація провайдера та помічники міток розмов | + | `plugin-sdk/reply-history` | Помічники історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилання на відповідь | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Помічники chunks відповіді | Помічники розбиття тексту/markdown на chunks | + | `plugin-sdk/session-store-runtime` | Помічники сховища сесій | Помічники шляху сховища й updated-at | + | `plugin-sdk/state-paths` | Помічники шляхів стану | Помічники каталогів стану та OAuth | + | `plugin-sdk/routing` | Помічники routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, помічники нормалізації session-key | + | `plugin-sdk/status-helpers` | Помічники стану каналу | Будівники підсумку стану каналу/облікового запису, стандартні значення runtime-state, помічники метаданих issue | + | `plugin-sdk/target-resolver-runtime` | Помічники розв'язувача цілей | Спільні помічники розв'язувача цілей | + | `plugin-sdk/string-normalization-runtime` | Помічники нормалізації рядків | Помічники нормалізації slug/рядків | + | `plugin-sdk/request-url` | Помічники URL запиту | Витягування рядкових URL із request-like входів | + | `plugin-sdk/run-command` | Помічники команд із таймером | Виконавець команд із таймером і нормалізованими stdout/stderr | | `plugin-sdk/param-readers` | Зчитувачі параметрів | Спільні зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Виділення payload tool | Виділення нормалізованих payload з об’єктів результату tool | - | `plugin-sdk/tool-send` | Виділення надсилання tool | Виділення канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/tool-payload` | Витягування payload tool | Витягування нормалізованих payload з об'єктів результату tool | + | `plugin-sdk/tool-send` | Витягування send tool | Витягування канонічних полів цілі надсилання з args tool | | `plugin-sdk/temp-path` | Допоміжні засоби для тимчасових шляхів | Спільні допоміжні засоби для шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби для журналювання | Допоміжні засоби для журналера підсистеми та редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби для Markdown-таблиць | Допоміжні засоби для режиму Markdown-таблиць | + | `plugin-sdk/logging-core` | Допоміжні засоби журналювання | Допоміжні засоби для журналювача підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби для Markdown-таблиць | Допоміжні засоби режиму Markdown-таблиць | | `plugin-sdk/reply-payload` | Типи відповідей на повідомлення | Типи корисного навантаження відповіді | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби для налаштування локальних/самостійно розміщених провайдерів | Допоміжні засоби для виявлення/налаштування самостійно розміщених провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби для налаштування OpenAI-сумісних самостійно розміщених провайдерів | Ті самі допоміжні засоби для виявлення/налаштування самостійно розміщених провайдерів | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime-автентифікації провайдера | Допоміжні засоби runtime API для визначення API-ключа | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби для налаштування API-ключа провайдера | Допоміжні засоби для онбордингу API-ключа/запису профілю | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби для результату автентифікації провайдера | Стандартний побудовник результату OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби для інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору провайдера | Вибір налаштованого або автоматичного провайдера та злиття сирої конфігурації провайдера | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/саморозміщеного провайдера | Допоміжні засоби виявлення/налаштування саморозміщеного провайдера | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування саморозміщеного провайдера, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/налаштування саморозміщеного провайдера | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби автентифікації виконання провайдера | Допоміжні засоби визначення API-ключа під час виконання | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу API-ключа/запису профілю | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату автентифікації провайдера | Стандартний побудовник результату автентифікації OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору провайдера | Вибір налаштованого або автоматичного провайдера та об’єднання сирої конфігурації провайдера | | `plugin-sdk/provider-env-vars` | Допоміжні засоби env-var провайдера | Допоміжні засоби пошуку env-var автентифікації провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби для моделей/відтворення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик відтворення, допоміжні засоби для кінцевих точок провайдера та допоміжні засоби нормалізації model-id | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повторного відтворення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повторного відтворення, допоміжні засоби кінцевих точок провайдера та допоміжні засоби нормалізації model-id | | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Загальні допоміжні засоби можливостей HTTP/кінцевих точок провайдера, включно з допоміжними засобами multipart-форми для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу web-fetch провайдера | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search провайдера | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped сетери/гетери облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/runtime web-search провайдера | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Загальні допоміжні засоби можливостей HTTP/кінцевих точок провайдера, зокрема допоміжні засоби multipart-форми для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search провайдера | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення ввімкнення plugin | + | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і локалізовані сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/виконання провайдера web-search | + | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдера | | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Нативні допоміжні засоби транспорту провайдера, як-от захищений fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Власні допоміжні засоби транспорту провайдера, як-от захищений fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | | `plugin-sdk/keyed-async-queue` | Впорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби для медіа | Допоміжні засоби отримання/перетворення/зберігання медіа плюс побудовники медіа-навантаження | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибір кандидатів і повідомлення про відсутні моделі для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби розуміння медіа | Типи провайдерів розуміння медіа плюс експорти допоміжних засобів для зображень/аудіо, орієнтовані на провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту | Вилучення видимого для асистента тексту, допоміжні засоби рендерингу/розбиття на фрагменти/таблиць Markdown, допоміжні засоби редагування чутливих даних, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби для тексту/журналювання | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби завантаження/перетворення/зберігання медіа, а також побудовники корисного навантаження медіа | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби перемикання в разі збою, вибору кандидатів і повідомлень про відсутні моделі для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні засоби розуміння медіа | Типи провайдерів розуміння медіа, а також експорти допоміжних засобів зображень/аудіо для провайдерів | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого асистенту тексту, допоміжні засоби рендерингу/розбиття на фрагменти/таблиць Markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/журналювання | | `plugin-sdk/text-chunking` | Допоміжні засоби розбиття тексту на фрагменти | Допоміжний засіб розбиття вихідного тексту на фрагменти | - | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи провайдерів мовлення плюс орієнтовані на провайдерів допоміжні засоби директив, реєстру, валідації та OpenAI-сумісний побудовник TTS | + | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи провайдерів мовлення, а також допоміжні засоби директив, реєстру, перевірки для провайдерів і побудовник TTS, сумісний з OpenAI | | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдерів мовлення, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в реальному часі | Типи провайдерів, допоміжні засоби реєстру та спільний допоміжний засіб WebSocket-сесії | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрибування в реальному часі | Типи провайдерів, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи провайдерів, допоміжні засоби реєстру/визначення та допоміжні засоби bridge-сесій | - | `plugin-sdk/image-generation` | Допоміжні засоби генерації зображень | Типи провайдерів генерації зображень плюс допоміжні засоби для ресурсів зображень/data URL і OpenAI-сумісний побудовник провайдера зображень | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, автентифікація та допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Допоміжні засоби генерації зображень | Типи провайдерів генерації зображень, а також допоміжні засоби ресурсів зображень/data URL і побудовник провайдера зображень, сумісний з OpenAI | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, перемикання в разі збою, автентифікація та допоміжні засоби реєстру | | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби перемикання в разі збою, пошук провайдера та розбір model-ref | | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивної відповіді | Нормалізація/згортання корисного навантаження інтерактивної відповіді | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби перемикання в разі збою, пошук провайдера та розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивної відповіді | Нормалізація/скорочення корисного навантаження інтерактивної відповіді | | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви схеми конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули Plugin каналу | - | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/зведення статусу каналу | + | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Спільні експорти преамбули plugin каналу | + | `plugin-sdk/channel-status` | Допоміжні засоби стану каналу | Спільні допоміжні засоби знімка/підсумку стану каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби групового доступу | Спільні допоміжні засоби рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Допоміжні засоби прямих DM | Спільні допоміжні засоби автентифікації/захисту прямих DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status і ambient proxy | + | `plugin-sdk/group-access` | Допоміжні засоби доступу групи | Спільні допоміжні засоби рішень доступу групи | + | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби автентифікації/захисту direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби розширення | Примітиви допоміжних засобів пасивного каналу/стану та ambient proxy | | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Реєстр цілей Webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби веб-медіа | Допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Реекспорт Zod | Реекспортований `zod` для споживачів plugin SDK | - | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів менеджера/конфігурації/файлів/CLI пам’яті | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад рушія пам’яті | Runtime-фасад індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти базового рушія хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings хоста пам’яті | Контракти embeddings пам’яті, доступ до реєстру, локальний провайдер і загальні допоміжні засоби batch/remote; конкретні віддалені провайдери живуть у своїх власних plugins | + | `plugin-sdk/webhook-path` | Допоміжні засоби шляху Webhook | Допоміжні засоби нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів SDK plugin | + | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів менеджера пам’яті/конфігурації/файлів/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад виконання рушія пам’яті | Фасад виконання індексу/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Експорти рушія foundation хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний провайдер і загальні допоміжні засоби пакетної/віддаленої обробки; конкретні віддалені провайдери живуть у власних plugins | | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Експорти рушія сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | Допоміжні засоби multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | Мультимодальні допоміжні засоби хоста пам’яті | | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | Допоміжні засоби secret хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI хоста пам’яті | Runtime-допоміжні засоби CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Core runtime-допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Vendor-neutral псевдонім для core runtime-допоміжних засобів хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста пам’яті | Допоміжні засоби стану хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Виконання CLI хоста пам’яті | Допоміжні засоби виконання CLI хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Основне виконання хоста пам’яті | Допоміжні засоби основного виконання хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/виконання хоста пам’яті | Допоміжні засоби файлів/виконання хоста пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім основного виконання хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів основного виконання хоста пам’яті | | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/виконання хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів файлів/виконання хоста пам’яті | | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого Markdown | Спільні допоміжні засоби керованого Markdown для plugins, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад пошуку активної пам’яті | Лінивий runtime-фасад search-manager активної пам’яті | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/testing` | Тестові утиліти | Застарілий широкий barrel сумісності; віддавайте перевагу сфокусованим тестовим підшляхам, як-от `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env` і `plugin-sdk/test-fixtures` | + | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад виконання менеджера пошуку active-memory | + | `plugin-sdk/memory-host-status` | Псевдонім стану хоста пам’яті | Vendor-neutral псевдонім для допоміжних засобів стану хоста пам’яті | + | `plugin-sdk/testing` | Тестові утиліти | Застарілий широкий barrel сумісності; надавайте перевагу сфокусованим тестовим підшляхам, як-от `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env` і `plugin-sdk/test-fixtures` | -Ця таблиця навмисно містить спільну підмножину для міграції, а не повну -поверхню SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно є спільною підмножиною для міграції, а не повною +поверхнею SDK. Повний список із 200+ точок входу міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні seams для вбудованих Plugin вилучено з публічної мапи -експортів SDK. Допоміжні засоби, специфічні для власника, містяться всередині -пакета Plugin-власника; спільна поведінка хоста має проходити через загальні -контракти SDK, як-от `plugin-sdk/gateway-runtime`, `plugin-sdk/security-runtime` і -`plugin-sdk/plugin-config-runtime`. +Зарезервовані допоміжні seams для bundled-plugin було вилучено з публічної +карти експорту SDK, за винятком явно задокументованих фасадів сумісності, як-от +застарілий shim `plugin-sdk/discord`, збережений для опублікованого пакета +`@openclaw/discord@2026.3.13`. Допоміжні засоби, специфічні для власника, +розміщуються всередині пакета Plugin-власника; спільна поведінка хоста має +переходити через загальні контракти SDK, як-от `plugin-sdk/gateway-runtime`, +`plugin-sdk/security-runtime` і `plugin-sdk/plugin-config-runtime`. -Використовуйте найвужчий імпорт, який відповідає завданню. Якщо не можете -знайти експорт, перевірте джерело в `src/plugin-sdk/` або запитайте -супровідників, якому загальному контракту він має належати. +Використовуйте найвужчий import, що відповідає завданню. Якщо не можете знайти +export, перевірте джерело в `src/plugin-sdk/` або запитайте maintainer-ів, який +загальний контракт має ним володіти. -## Активні застарілі API +## Активні застаріння -Вужчі застарілі API, що застосовуються до SDK Plugin, контракту провайдера, -runtime-поверхні та manifest. Кожен із них досі працює сьогодні, але буде -вилучений у майбутньому major-релізі. Запис під кожним пунктом зіставляє старий +Вужчі застаріння, що застосовуються в SDK Plugin, контракті провайдера, +runtime-поверхні та manifest. Кожне з них усе ще працює сьогодні, але буде +видалене в майбутньому major release. Запис під кожним пунктом зіставляє старий API з його канонічною заміною. - + **Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`. - **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі - експорти — просто імпортовані з вужчого subpath. `command-auth` - повторно експортує їх як compat stubs. + **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі signatures, ті самі + exports — лише імпорт із вужчого subpath. `command-auth` + re-export-ить їх як compat stubs. ```typescript // Before @@ -584,97 +589,99 @@ API з його канонічною заміною. - + **Старе**: `resolveInboundMentionRequirement({ facts, policy })` і `shouldDropInboundForMention(...)` з `openclaw/plugin-sdk/channel-inbound` або `openclaw/plugin-sdk/channel-mention-gating`. **Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає - єдиний об'єкт рішення замість двох окремих викликів. + єдиний об’єкт рішення замість двох окремих викликів. - Низхідні канальні Plugin-и (Slack, Discord, Matrix, MS Teams) уже - перемкнулися. + Низхідні channel plugins (Slack, Discord, Matrix, MS Teams) уже + перейшли. - - `openclaw/plugin-sdk/channel-runtime` — це compatibility shim для старіших - канальних Plugin-ів. Не імпортуйте його з нового коду; використовуйте - `openclaw/plugin-sdk/channel-runtime-context` для реєстрації runtime-об'єктів. + + `openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших + channel plugins. Не імпортуйте його з нового коду; використовуйте + `openclaw/plugin-sdk/channel-runtime-context` для реєстрації runtime + objects. - Помічники `channelActions*` у `openclaw/plugin-sdk/channel-actions` - застаріли разом із сирими експортами канальних "actions". Натомість - відкривайте capabilities через семантичну поверхню `presentation` — - канальні Plugin-и оголошують, що вони рендерять (картки, кнопки, select-и), - а не які сирі назви дій вони приймають. + Допоміжні засоби `channelActions*` у `openclaw/plugin-sdk/channel-actions` + застаріли разом із сирими exports каналів "actions". Натомість expose-те + capabilities через семантичну поверхню `presentation` — channel plugins + оголошують, що вони render-ять (cards, buttons, selects), а не які сирі + назви action вони приймають. - - **Старе**: фабрика `tool()` з `openclaw/plugin-sdk/provider-web-search`. + + **Старе**: factory `tool()` з `openclaw/plugin-sdk/provider-web-search`. - **Нове**: реалізуйте `createTool(...)` безпосередньо в провайдерному Plugin. - OpenClaw більше не потребує помічника SDK для реєстрації обгортки tool. + **Нове**: реалізуйте `createTool(...)` безпосередньо в provider plugin. + OpenClaw більше не потребує допоміжного засобу SDK для реєстрації обгортки + tool. - + **Старе**: `formatInboundEnvelope(...)` (і - `ChannelMessageForAgent.channelEnvelope`) для побудови плоского plaintext - prompt envelope з вхідних повідомлень каналу. + `ChannelMessageForAgent.channelEnvelope`) для побудови flat plaintext prompt + envelope з вхідних повідомлень каналу. - **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. - Канальні Plugin-и додають routing metadata (thread, topic, reply-to, - reactions) як типізовані поля замість конкатенації їх у рядок prompt. Помічник - `formatAgentEnvelope(...)` досі підтримується для синтезованих - assistant-facing envelopes, але вхідні plaintext envelopes поступово - вилучаються. + **Нове**: `BodyForAgent` плюс structured user-context blocks. Channel + plugins додають routing metadata (thread, topic, reply-to, reactions) як + typed fields замість конкатенації їх у prompt string. Допоміжний засіб + `formatAgentEnvelope(...)` усе ще підтримується для synthesized + assistant-facing envelopes, але inbound plaintext envelopes поступово + виводяться. - Зачеплені області: `inbound_claim`, `message_received` і будь-який - користувацький канальний Plugin, який постобробляв текст `channelEnvelope`. + Зачеплені області: `inbound_claim`, `message_received` і будь-який custom + channel plugin, що post-processed текст `channelEnvelope`. - - Чотири псевдоніми типів discovery тепер є тонкими обгортками над типами + + Чотири aliases типів discovery тепер є тонкими обгортками над типами епохи catalog: - | Старий псевдонім | Новий тип | + | Старий alias | Новий тип | | ------------------------- | ------------------------- | | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | | `ProviderDiscoveryContext`| `ProviderCatalogContext` | | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - Плюс застарілий статичний набір `ProviderCapabilities` — провайдерні - Plugin-и мають додавати capability facts через runtime-контракт провайдера, - а не через статичний об'єкт. + Плюс legacy static bag `ProviderCapabilities` — provider plugins мають + додавати capability facts через контракт provider runtime, а не через + static object. - + **Старе** (три окремі hooks у `ProviderThinkingPolicy`): `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і `resolveDefaultThinkingLevel(ctx)`. - **Нове**: один `resolveThinkingProfile(ctx)`, який повертає - `ProviderThinkingProfile` з канонічним `id`, необов'язковим `label` і - ранжованим списком рівнів. OpenClaw автоматично понижує застарілі збережені - значення за рангом profile. + **Нове**: один `resolveThinkingProfile(ctx)`, що повертає + `ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і + ranked list рівнів. OpenClaw автоматично downgrade-ить застарілі збережені + значення за rank профілю. - Реалізуйте один hook замість трьох. Застарілі hooks продовжують працювати - протягом вікна застарівання, але не компонуються з результатом profile. + Реалізуйте один hook замість трьох. Legacy hooks працюють протягом + deprecation window, але не compose-яться з profile result. - + **Старе**: реалізація `resolveExternalOAuthProfiles(...)` без оголошення провайдера в manifest Plugin. **Нове**: оголосіть `contracts.externalAuthProviders` у manifest Plugin **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях "auth - fallback" виводить попередження під час runtime і буде вилучений. + fallback" видає попередження під час runtime і буде видалений. ```json { @@ -686,35 +693,35 @@ API з його канонічною заміною. - + **Старе** поле manifest: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. **Нове**: віддзеркальте той самий пошук env-var у `setup.providers[].envVars` - у manifest. Це об'єднує metadata env для налаштування/статусу в одному місці - й уникає запуску runtime Plugin лише для відповіді на пошуки env-var. + у manifest. Це консолідує setup/status env metadata в одному місці та + уникає запуску plugin runtime лише для відповіді на env-var lookups. - `providerAuthEnvVars` залишається підтримуваним через compatibility adapter, - доки не закриється вікно застарівання. + `providerAuthEnvVars` залишається підтримуваним через adapter сумісності, + доки deprecation window не закриється. - + **Старе**: три окремі виклики — `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`. - **Нове**: один виклик у memory-state API — + **Нове**: один виклик в API memory-state — `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. - Ті самі слоти, один виклик реєстрації. Адитивні помічники пам'яті + Ті самі slots, один виклик реєстрації. Additive memory helpers (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, `registerMemoryEmbeddingProvider`) не зачеплені. - - Два застарілі псевдоніми типів досі експортуються з `src/plugins/runtime/types.ts`: + + Два legacy type aliases усе ще export-яться з `src/plugins/runtime/types.ts`: | Старе | Нове | | ----------------------------- | ------------------------------- | @@ -722,17 +729,17 @@ API з його канонічною заміною. | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | Runtime-метод `readSession` застарів на користь `getSessionMessages`. - Сигнатура та сама; старий метод делегує виклик новому. + Та сама signature; старий метод викликає новий. - **Старе**: `runtime.tasks.flow` (в однині) повертав live accessor task-flow. + **Старе**: `runtime.tasks.flow` (singular) повертав live task-flow accessor. - **Нове**: `runtime.tasks.managedFlows` зберігає runtime мутації керованого - TaskFlow для Plugin-ів, які створюють, оновлюють, скасовують або запускають - дочірні завдання з flow. Використовуйте `runtime.tasks.flows`, коли Plugin - потребує лише DTO-based читань. + **Нове**: `runtime.tasks.managedFlows` зберігає managed TaskFlow mutation + runtime для plugins, які створюють, оновлюють, cancel-ять або запускають + child tasks із flow. Використовуйте `runtime.tasks.flows`, коли Plugin + потребує лише DTO-based reads. ```typescript // Before @@ -743,18 +750,17 @@ API з його канонічною заміною. - - Описано вище в розділі "Як мігрувати → Міграція extensions результатів tool - Pi до middleware". Додано тут для повноти: вилучений шлях лише для Pi + + Описано вище в "Як мігрувати → Міграція Pi tool-result extensions на + middleware". Додано тут для повноти: видалений шлях лише для Pi `api.registerEmbeddedExtensionFactory(...)` замінено на - `api.registerAgentToolResultMiddleware(...)` з явним списком runtime у + `api.registerAgentToolResultMiddleware(...)` з явним runtime list у `contracts.agentToolResultMiddleware`. - - `OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є - однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу - канонічній назві. + + `OpenClawSchemaType`, re-export-нутий з `openclaw/plugin-sdk`, тепер є + однорядковим alias для `OpenClawConfig`. Надавайте перевагу канонічній назві. ```typescript // Before @@ -767,40 +773,39 @@ API з його канонічною заміною. -Застарілі API рівня extension (усередині вбудованих канальних/провайдерних -Plugin-ів у `extensions/`) відстежуються у власних barrels `api.ts` і -`runtime-api.ts`. Вони не впливають на контракти сторонніх Plugin-ів і не -перелічені тут. Якщо ви споживаєте локальний barrel вбудованого Plugin -безпосередньо, перед оновленням прочитайте коментарі про застарівання в цьому -barrel. +Застаріння на рівні extension (всередині bundled channel/provider plugins у +`extensions/`) відстежуються в їхніх власних barrels `api.ts` і `runtime-api.ts`. +Вони не впливають на контракти third-party plugin і не перелічені тут. Якщо ви +споживаєте local barrel bundled plugin безпосередньо, прочитайте коментарі про +застаріння в цьому barrel перед upgrading. -## Графік вилучення +## Графік видалення | Коли | Що відбувається | | ---------------------- | -------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні виводять runtime-попередження | -| **Наступний major-реліз** | Застарілі поверхні буде вилучено; Plugin-и, які досі їх використовують, не працюватимуть | +| **Зараз** | Застарілі поверхні видають runtime warnings | +| **Наступний major release** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, завершаться з помилкою | -Усі core Plugin-и вже мігровано. Зовнішні Plugin-и мають мігрувати до -наступного major-релізу. +Усі core plugins уже мігровано. External plugins мають мігрувати до наступного +major release. ## Тимчасове приглушення попереджень -Установіть ці змінні середовища під час роботи над міграцією: +Встановіть ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий аварійний обхід, а не постійне рішення. +Це тимчасовий аварійний вихід, а не постійне рішення. -## Пов'язане +## Пов’язане - [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повна довідка імпортів subpath -- [Канальні Plugin-и](/uk/plugins/sdk-channel-plugins) — створення канальних Plugin-ів -- [Провайдерні Plugin-и](/uk/plugins/sdk-provider-plugins) — створення провайдерних Plugin-ів -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — поглиблений огляд архітектури -- [Manifest Plugin](/uk/plugins/manifest) — довідка зі схеми manifest +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник imports за subpath +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins +- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — глибокий огляд архітектури +- [Manifest Plugin](/uk/plugins/manifest) — довідник schema manifest diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 2d3770d16..d9e78e3fd 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -4,19 +4,19 @@ read_when: - Вам потрібен довідник усіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-28T12:00:02Z" + generated_at: "2026-04-28T20:12:31Z" model: gpt-5.5 provider: openai - source_hash: 0c3bd7ae2ca2fbf351442bfd073450b72368e1ab833dbbdccfbe569db5346ce9 + source_hash: 83f554cf3653cdae5027eac2048280a9200828c5ed256d975cd745a77ba1e796 source_path: plugins/sdk-overview.md workflow: 16 --- -SDK плагінів є типізованим контрактом між плагінами та ядром. Ця сторінка є -довідником про **що імпортувати** та **що можна реєструвати**. +SDK плагінів — це типізований контракт між плагінами та ядром. Ця сторінка є +довідником щодо **того, що імпортувати** і **що можна реєструвати**. Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу. @@ -31,134 +31,137 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях є невеликим самодостатнім модулем. Це зберігає швидкий запуск і +Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу помічників входу/збирання віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої загальної поверхні та спільних помічників, як-от +ширшої поверхні-парасольки та спільних помічників, таких як `buildChannelConfigSchema`. Для конфігурації каналу публікуйте JSON Schema, якою володіє канал, через `openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema` -призначений для спільних примітивів схем і універсального збирача. Вбудовані +призначений для спільних примітивів схеми та універсального конструктора. Вбудовані плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених схем вбудованих каналів. Застарілі експорти сумісності залишаються в -`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не є -шаблоном для нових плагінів. +`plugin-sdk/channel-config-schema-legacy`; жоден підшлях вбудованих схем не є +зразком для нових плагінів. - Не імпортуйте провайдеро- або канально-брендовані зручні шви (наприклад + Не імпортуйте зручні шви з брендуванням провайдера або каналу (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни компонують універсальні підшляхи SDK усередині власних барелів `api.ts` / - `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для плагіна - барели, або додати вузький універсальний контракт SDK, коли потреба справді є - міжканальною. + Вбудовані плагіни компонують універсальні підшляхи SDK у власних барелях `api.ts` / + `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для плагіна + барелі, або додати вузький універсальний контракт SDK, коли потреба справді + є міжканальною. -Невеликий набір допоміжних швів для вбудованих плагінів усе ще з’являється в згенерованій мапі експортів, -коли для них відстежено використання власником. Вони існують лише для супроводу вбудованих плагінів -і не рекомендовані як шляхи імпорту для нових сторонніх +Невеликий набір допоміжних швів вбудованих плагінів досі з’являється у згенерованій карті експортів, +коли для них відстежується використання власником. Вони існують лише для супроводу +вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх плагінів. + +`openclaw/plugin-sdk/discord` також збережено як застарілий фасад сумісності +для опублікованого пакета `@openclaw/discord@2026.3.13`. Не копіюйте цей шлях імпорту +в нові плагіни; натомість використовуйте універсальні підшляхи SDK каналів. ## Довідник підшляхів -SDK плагінів експонується як набір вузьких підшляхів, згрупованих за областями (вхід -плагіна, канал, провайдер, автентифікація, runtime, можливість, пам’ять і зарезервовані +SDK плагінів надається як набір вузьких підшляхів, згрупованих за областями (вхід +плагіна, канал, провайдер, автентифікація, runtime, можливості, пам’ять і зарезервовані помічники вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див. -[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). +у [Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths). Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Метод | Що він реєструє | +| Метод | Що він реєструє | | ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | +| `api.registerProvider(...)` | Текстове виведення (LLM) | | `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний CLI-бекенд виведення | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Text-to-speech / STT-синтез | +| `api.registerCliBackend(...)` | Локальний бекенд виведення CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Text-to-speech / STT синтез | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | | `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер веб-отримання / скрейпінгу | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер веботримання / скрейпінгу | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що він реєструє | -| ------------------------------- | --------------------------------------------- | +| Метод | Що він реєструє | +| ----------------------------- | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | -Команди плагінів можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка, -керована командою підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте -політику, специфічну для провайдера або плагіна, до збирачів промптів ядра. +Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка +підказка маршрутизації, якою володіє команда. Тримайте цей текст про саму команду; не додавайте +політику, специфічну для провайдера або плагіна, до побудовників промптів ядра. ### Інфраструктура | Метод | Що він реєструє | -| ---------------------------------------------- | --------------------------------------- | +| ---------------------------------------------- | -------------------------------------- | | `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway | +| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | | `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | | `api.registerGatewayDiscoveryService(service)` | Локальний рекламодавець виявлення Gateway | | `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фоновий сервіс | +| `api.registerService(service)` | Фонова служба | | `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | | `api.registerAgentToolResultMiddleware(...)` | Runtime middleware результатів інструментів | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий суміжний із пам’яттю розділ промпта | +| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ промпта, суміжний із пам’яттю | | `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | -### Хостові хуки для плагінів workflow +### Хост-хуки для плагінів робочих процесів -Хостові хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста, +Хост-хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста, а не лише додавати провайдера, канал або інструмент. Це -універсальні контракти; Plan Mode може їх використовувати, але так само можуть workflow затвердження, -гейти політик робочого простору, фонові монітори, майстри налаштування та супровідні UI-плагіни. +універсальні контракти; їх може використовувати Plan Mode, але також можуть процеси схвалення, +шлюзи політик робочої області, фонові монітори, майстри налаштування та супровідні UI-плагіни. -| Метод | Контракт, яким він володіє | -| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| Метод | Контракт, яким він володіє | +| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `api.registerSessionExtension(...)` | Стан сесії, яким володіє плагін і який сумісний із JSON, проєктований через сесії Gateway | -| `api.enqueueNextTurnInjection(...)` | Стійкий контекст exactly-once, вставлений у наступний хід агента для однієї сесії | -| `api.registerTrustedToolPolicy(...)` | Вбудована/довірена політика інструментів до плагінів, що може блокувати або переписувати параметри інструмента | -| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | -| `api.registerCommand(...)` | Обмежені за областю команди плагіна; результати команди можуть задавати `continueAgent: true` | -| `api.registerControlUiDescriptor(...)` | Дескриптори внесків Control UI для поверхонь сесії, інструмента, запуску або налаштувань | -| `api.registerRuntimeLifecycle(...)` | Колбеки очищення для runtime-ресурсів, якими володіє плагін, на шляхах reset/delete/reload | -| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна на один запуск, очищений у кінцевому життєвому циклі запуску | +| `api.enqueueNextTurnInjection(...)` | Стійкий контекст рівно один раз, інжектований у наступний хід агента для однієї сесії | +| `api.registerTrustedToolPolicy(...)` | Політика інструментів довіреного передплагінного етапу, яка може блокувати або переписувати параметри інструментів | +| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | +| `api.registerCommand(...)` | Обмежені за областю команди плагіна; результати команд можуть задавати `continueAgent: true` | +| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сесії, інструмента, запуску або налаштувань | +| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для runtime-ресурсів, якими володіє плагін, на шляхах reset/delete/reload | +| `api.registerAgentEventSubscription(...)` | Очищені підписки на події для стану робочого процесу та моніторів | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна для окремого запуску, очищений під час завершального життєвого циклу запуску | | `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сесій, якими володіє плагін, із детермінованим очищенням | Контракти навмисно розділяють повноваження: -- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними хуками. -- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і є лише вбудованими, бо беруть участь у політиці безпеки хоста. -- Зарезервоване володіння командами є лише вбудованим. Зовнішні плагіни мають використовувати - власні назви команд або псевдоніми. +- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, інжекціями в наступний хід і звичайними хуками. +- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише вбудованим плагінам, бо вони беруть участь у політиці безпеки хоста. +- Зарезервоване володіння командами доступне лише вбудованим плагінам. Зовнішні плагіни мають використовувати власні імена команд або псевдоніми. - `allowPromptInjection=false` вимикає хуки, що змінюють промпт, зокрема `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, - поля промпта зі спадкового `before_agent_start` і + поля промпта зі спадкового `before_agent_start` та `enqueueNextTurnInjection`. -Приклади споживачів, що не належать до Plan: +Приклади споживачів не з Plan: -| Архетип плагіна | Використані хуки | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| Workflow затвердження | Розширення сесії, продовження команди, ін’єкція наступного ходу, UI-дескриптор | -| Гейт політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії | -| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок до промпта Heartbeat, UI-дескриптор | -| Майстер налаштування або онбордингу | Розширення сесії, обмежені за областю команди, дескриптор Control UI | +| Архетип плагіна | Використані хуки | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Процес схвалення | Розширення сесії, продовження команди, інжекція в наступний хід, UI-дескриптор | +| Шлюз політик бюджету/робочої області | Довірена політика інструментів, метадані інструментів, проєкція сесії | +| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок промпта Heartbeat, UI-дескриптор | +| Майстер налаштування або onboarding | Розширення сесії, команди з областю дії, дескриптор Control UI | - Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + Зарезервовані адміністративні простори імен ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити вужчу область методу gateway. Віддавайте перевагу специфічним для плагіна префіксам для методів, якими володіє плагін. @@ -166,24 +169,24 @@ SDK плагінів експонується як набір вузьких п Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли - їм потрібно переписати результат інструмента після виконання й до того, як runtime - передасть цей результат назад у модель. Це довірений runtime-нейтральний + їм потрібно переписати результат інструмента після виконання і до того, як runtime + передасть цей результат назад у модель. Це довірений нейтральний до runtime шов для асинхронних редукторів виводу, таких як tokenjuice. Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни не можуть реєструвати це middleware; залишайте звичайні хуки плагінів OpenClaw для роботи, -яка не потребує таймінгу результатів інструментів перед моделлю. Старий лише Pi-вбудований -шлях реєстрації фабрики розширення було видалено. +яка не потребує таймінгу результату інструмента перед моделлю. Старий вбудований +шлях реєстрації фабрики розширення лише для Pi було видалено. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає змогу плагіну рекламувати активний +`api.registerGatewayDiscoveryService(...)` дає плагіну змогу рекламувати активний Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає -сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає -поточні порти Gateway і несекретні дані підказок TXT, а також викликає повернений -обробник `stop` під час вимкнення Gateway. +службу під час запуску Gateway, коли локальне виявлення ввімкнено, передає +поточні порти Gateway і несекретні TXT-підказки, а також викликає повернений +обробник `stop` під час завершення роботи Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -200,20 +203,19 @@ api.registerGatewayDiscoveryService({ ``` Плагіни виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або -автентифікацію. Виявлення є підказкою маршрутизації; довірою все ще володіють -автентифікація Gateway і TLS pinning. +автентифікацію. Виявлення — це підказка маршрутизації; довірою все ще керують автентифікація Gateway і TLS-пінінг. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд часу парсингу, що використовуються для кореневої довідки CLI, - маршрутизації та лінивої реєстрації CLI плагіна +- `commands`: явні корені команд, якими володіє реєстратор +- `descriptors`: дескриптори команд часу розбору, які використовуються для довідки кореневого CLI, + маршрутизації та лінивої реєстрації CLI Plugin -Якщо ви хочете, щоб команда Plugin залишалася lazy-loaded у звичайному кореневому шляху CLI, -надайте `descriptors`, які охоплюють кожен кореневий top-level command, що його відкриває цей -реєстратор. +Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному шляху кореневого CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається цим +реєстратором. ```typescript api.registerCli( @@ -233,97 +235,97 @@ api.registerCli( ); ``` -Використовуйте лише `commands` тільки тоді, коли вам не потрібна lazy root CLI registration. -Цей eager compatibility path залишається підтримуваним, але він не встановлює -descriptor-backed placeholders для lazy loading під час parsing. +Використовуйте `commands` самостійно лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI. +Цей енергійний шлях сумісності залишається підтримуваним, але він не встановлює +заповнювачі на основі дескрипторів для лінивого завантаження під час розбору. -### Реєстрація бекенду CLI +### Реєстрація бекенда CLI -`api.registerCliBackend(...)` дає змогу Plugin володіти типовою конфігурацією для локального -AI CLI backend, такого як `codex-cli`. +`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією для локального +AI CLI бекенда, такого як `codex-cli`. -- Backend `id` стає provider prefix у model refs на кшталт `codex-cli/gpt-5`. +- Backend `id` стає префіксом постачальника в посиланнях на модель, як-от `codex-cli/gpt-5`. - Backend `config` використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх +- Конфігурація користувача все одно має пріоритет. OpenClaw об'єднує `agents.defaults.cliBackends.` поверх типового значення Plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує compatibility rewrites після merge +- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після об'єднання (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (один активний одночасно). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. | -| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Builder секції prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті | -| `api.registerMemoryRuntime(runtime)` | Runtime adapter пам’яті | +| Метод | Що він реєструє | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до prompt. | +| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам'яті | +| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам'яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану очищення пам'яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам'яті | -### Адаптери embedding пам’яті +### Адаптери embedding пам'яті | Метод | Що він реєструє | | ---------------------------------------------- | ------------------------------------------------ | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного Plugin | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам'яті для активного Plugin | -- `registerMemoryCapability` є пріоритетним ексклюзивним API для memory-plugin. -- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, - щоб супровідні plugins могли споживати експортовані artifacts пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість доступу до приватної структури конкретного - memory plugin. +- `registerMemoryCapability` є рекомендованим ексклюзивним API Plugin пам'яті. +- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, + щоб супутні plugins могли споживати експортовані артефакти пам'яті через + `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури конкретного + Plugin пам'яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` є legacy-compatible ексклюзивними API для memory-plugin. -- `MemoryFlushPlan.model` може прив’язати flush turn до точного посилання `provider/model`, - такого як `ollama/qwen3:8b`, без успадкування активного fallback chain. -- `registerMemoryEmbeddingProvider` дає активному memory plugin змогу зареєструвати один - або більше id адаптерів embedding (наприклад, `openai`, `gemini` або custom - plugin-defined id). -- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, resolve проти цих зареєстрованих + `registerMemoryRuntime` є застаріло-сумісними ексклюзивними API Plugin пам'яті. +- `MemoryFlushPlan.model` може прив'язати turn очищення до точного посилання `provider/model`, + наприклад `ollama/qwen3:8b`, без успадкування активного ланцюжка fallback. +- `registerMemoryEmbeddingProvider` дає активному Plugin пам'яті змогу зареєструвати один + або більше id адаптерів embedding (наприклад `openai`, `gemini` або власний + id, визначений Plugin). +- Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, розв'язується відносно цих зареєстрованих id адаптерів. ### Події та життєвий цикл | Метод | Що він робить | | -------------------------------------------- | -------------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | -| `api.onConversationBindingResolved(handler)` | Callback прив’язки розмови | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Callback прив'язки розмови | -Див. [хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв hook і семантики guard. +Див. [Хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики guard. -### Семантика рішень hook +### Семантика рішень хуків -- `before_tool_call`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override. -- `before_install`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override. -- `reply_dispatch`: повернення `{ handled: true, ... }` є terminal. Щойно будь-який handler claims dispatch, handlers із нижчим пріоритетом і default model dispatch path пропускаються. -- `message_sending`: повернення `{ cancel: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як omission `cancel`), а не як override. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для channel-specific extras. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId` перед fallback до channel-specific `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для startup state, яким володіє Gateway, замість покладання на внутрішні hooks `gateway:startup`. -- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх wake schedulers, і залишайте OpenClaw джерелом істини для due checks та виконання. +- `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 бере dispatch на себе, handlers із нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. +- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для специфічних для каналу додаткових даних. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє gateway, замість покладання на внутрішні хуки `gateway:startup`. +- `cron_changed`: спостерігайте за змінами життєвого циклу Cron, яким володіє gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, і зберігайте OpenClaw джерелом істини для перевірок строків і виконання. -### Поля об’єкта API +### Поля об'єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Id Plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія Plugin (опційно) | -| `api.description` | `string?` | Опис Plugin (опційно) | -| `api.source` | `string` | Шлях джерела Plugin | -| `api.rootDir` | `string?` | Кореневий каталог Plugin (опційно) | -| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний in-memory runtime snapshot, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для Plugin, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` є lightweight pre-full-entry startup/setup window | -| `api.resolvePath(input)` | `(string) => string` | Resolve path відносно кореня Plugin | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------- | +| `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"` — легке вікно startup/setup перед повним entry | +| `api.resolvePath(input)` | `(string) => string` | Розв'язати шлях відносно кореня Plugin | -## Внутрішня домовленість щодо модулів +## Угода щодо внутрішніх модулів -У межах вашого Plugin використовуйте local barrel files для внутрішніх imports: +Усередині вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ @@ -335,55 +337,55 @@ my-plugin/ Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` - з production code. Спрямовуйте внутрішні imports через `./api.ts` або - `./runtime-api.ts`. Шлях SDK є лише зовнішнім contract. + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. -Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні public entry files) надають перевагу -активному runtime config snapshot, коли OpenClaw уже запущений. Якщо runtime -snapshot ще не існує, вони fallback до resolved config file на диску. -Packaged bundled plugin facades слід завантажувати через facade loaders OpenClaw SDK; -прямі imports з `dist/extensions/...` обходять staged runtime dependency mirrors, -які packaged installs використовують для plugin-owned dependencies. +Публічні поверхні bundled Plugin, завантажені через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` і подібні публічні entry-файли), віддають перевагу +активному runtime-знімку конфігурації, коли OpenClaw уже працює. Якщо runtime-знімка +ще немає, вони повертаються до розв'язаної конфігурації з файлу на диску. +Упаковані bundled facade Plugin слід завантажувати через facade loaders OpenClaw SDK; +прямі імпорти з `dist/extensions/...` обходять staged runtime mirrors залежностей, +які packaged installs використовують для залежностей, що належать Plugin. -Provider plugins можуть відкривати вузький plugin-local contract barrel, коли -helper навмисно provider-specific і ще не належить до generic SDK -subpath. Bundled examples: +Provider plugins можуть надавати вузький локальний barrel контракту Plugin, коли +helper навмисно специфічний для provider і ще не належить до generic SDK +subpath. Bundled приклади: - **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude beta-header і stream helpers `service_tier`. - **`@openclaw/openai-provider`**: `api.ts` експортує provider builders, - default-model helpers і realtime provider builders. + helpers типової моделі та realtime provider builders. - **`@openclaw/openrouter-provider`**: `api.ts` експортує provider builder - плюс onboarding/config helpers. + плюс helpers onboarding/config. - Production code розширення також має уникати imports `openclaw/plugin-sdk/`. - Якщо helper справді спільний, підвищте його до нейтрального SDK subpath, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - capability-oriented surface замість coupling двох plugins разом. + Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. + Якщо helper справді спільний, підніміть його до нейтрального SDK subpath, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша + поверхня, орієнтована на можливості, замість того щоб зв'язувати два plugins між собою. -## Пов’язане +## Пов'язане Параметри `definePluginEntry` і `defineChannelPluginEntry`. - - Повний довідник namespace `api.runtime`. + + Повна довідка простору імен `api.runtime`. - - Packaging, manifests і config schemas. + + Пакування, manifests і config schemas. - Test utilities і lint rules. + Тестові утиліти та правила lint. - Міграція з deprecated surfaces. + Міграція із застарілих поверхонь. - Глибока архітектура та capability model. + Поглиблена архітектура та модель можливостей. diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 139dc3a53..fd40859c6 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -5,26 +5,26 @@ read_when: summary: 'Каталог підшляхів Plugin SDK: які імпорти де розташовані, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-28T11:21:35Z" + generated_at: "2026-04-28T20:12:45Z" model: gpt-5.5 provider: openai - source_hash: 8f9939a84decc6d5ff34662044af97b8c9da838b0d2791b2cd0cfa15d181fdd7 + source_hash: f66fa1c9f9398ae2124dc4b92d3b11a07800616f452409d12e851a6fb0bcd675 source_path: plugins/sdk-subpaths.md workflow: 16 --- - SDK Plugin доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці наведено часто використовувані підшляхи, згруповані за призначенням. Згенерований + SDK Plugin надається як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці наведено поширені підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; зарезервовані допоміжні підшляхи bundled-plugin також є там, але вони є деталлю - реалізації, якщо сторінка документації явно не просуває їх. Супровідники можуть перевіряти активні + реалізації, якщо сторінка документації явно не виносить їх на рівень публічного API. Супровідники можуть перевіряти активні зарезервовані допоміжні підшляхи за допомогою `pnpm plugins:boundary-report:summary`; невикористані - зарезервовані допоміжні експорти провалюють звіт CI, а не залишаються в публічному SDK + зарезервовані допоміжні експорти призводять до помилки у звіті CI, а не залишаються в публічному SDK як неактивний борг сумісності. - Посібник з авторства Plugin див. у [Огляд SDK Plugin](/uk/plugins/sdk-overview). + Посібник з розробки Plugin див. у [огляді SDK Plugin](/uk/plugins/sdk-overview). - ## Вхідна точка Plugin + ## Точка входу Plugin | Підшлях | Ключові експорти | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -32,297 +32,298 @@ x-i18n: | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin; для нових тестів розширень віддавайте перевагу сфокусованим тестовим підшляхам | - | `plugin-sdk/plugin-test-api` | Мінімальний побудовник mock `OpenClawPluginApi` для прямих unit-тестів реєстрації Plugin | - | `plugin-sdk/agent-runtime-test-contracts` | Фікстури контрактів адаптера нативного agent-runtime для профілів автентифікації, приглушення доставки, класифікації fallback, хуків інструментів, накладок prompt, схем і відновлення transcript | - | `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестування життєвого циклу облікового запису каналу, каталогу, send-config, mock runtime, хуків, вхідної точки bundled каналу, timestamp конверта, відповіді pairing та загального контракту каналу | - | `plugin-sdk/channel-target-testing` | Спільний набір тестів випадків помилок розв’язання цілі каналу | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів реєстрації Plugin, маніфесту пакета, публічного artifact, API runtime, побічних ефектів імпорту та прямого імпорту | - | `plugin-sdk/plugin-test-runtime` | Фікстури runtime Plugin, registry, реєстрації provider, setup-wizard і runtime task-flow для тестів | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime provider, автентифікації, discovery, onboard, catalog, media capability, replay policy, realtime STT live-audio, web-search/fetch і wizard | - | `plugin-sdk/provider-http-test-mocks` | Opt-in Vitest HTTP/auth mocks для тестів provider, що перевіряють `plugin-sdk/provider-http` | - | `plugin-sdk/test-env` | Фікстури тестового середовища, fetch/network, одноразового HTTP-сервера, вхідного запиту, live-test, тимчасової файлової системи та керування часом | - | `plugin-sdk/test-fixtures` | Загальні фікстури тестів CLI, sandbox, skill, agent-message, system-event, перезавантаження модуля, шляху bundled Plugin, terminal, chunking, auth-token і typed-case | - | `plugin-sdk/test-node-mocks` | Сфокусовані допоміжні засоби mock для вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` | - | `plugin-sdk/migration` | Допоміжні засоби елементів provider міграції, як-от `createMigrationItem`, константи причин, маркери стану елементів, допоміжні засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби міграції runtime, як-от `copyMigrationFileItem` і `writeMigrationReport` | + | `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin; для нових тестів розширень надавайте перевагу сфокусованим тестовим підшляхам | + | `plugin-sdk/plugin-test-api` | Мінімальний builder моків `OpenClawPluginApi` для модульних тестів прямої реєстрації Plugin | + | `plugin-sdk/agent-runtime-test-contracts` | Нативні fixtures контрактів адаптера agent-runtime для профілів автентифікації, пригнічення доставки, класифікації fallback, хуків інструментів, накладень промптів, схем і відновлення transcript | + | `plugin-sdk/channel-test-helpers` | Помічники тестів життєвого циклу облікового запису каналу, каталогу, send-config, runtime-мока, хуків, точки входу bundled channel, timestamp envelope, pairing reply і generic channel contract | + | `plugin-sdk/channel-target-testing` | Спільний набір тестів випадків помилок target-resolution каналу | + | `plugin-sdk/plugin-test-contracts` | Помічники контрактів реєстрації Plugin, маніфесту пакета, публічного артефакту, runtime API, side-effect імпорту та прямого імпорту | + | `plugin-sdk/plugin-test-runtime` | Fixtures для тестів runtime Plugin, registry, provider-registration, setup-wizard і runtime task-flow | + | `plugin-sdk/provider-test-contracts` | Помічники контрактів provider runtime, auth, discovery, onboard, catalog, media capability, replay policy, realtime STT live-audio, web-search/fetch і wizard | + | `plugin-sdk/provider-http-test-mocks` | Opt-in HTTP/auth моки Vitest для тестів провайдера, що перевіряють `plugin-sdk/provider-http` | + | `plugin-sdk/test-env` | Fixtures тестового середовища, fetch/network, disposable HTTP server, incoming request, live-test, temporary filesystem і time-control | + | `plugin-sdk/test-fixtures` | Generic fixtures для CLI, sandbox, skill, agent-message, system-event, module reload, bundled plugin path, terminal, chunking, auth-token і typed-case | + | `plugin-sdk/test-node-mocks` | Сфокусовані помічники моків вбудованих модулів Node для використання у factory Vitest `vi.mock("node:*")` | + | `plugin-sdk/migration` | Помічники елементів migration provider, як-от `createMigrationItem`, константи причин, маркери стану елементів, помічники редагування та `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Runtime-помічники міграції, як-от `copyMigrationFileItem` і `writeMigrationReport` | | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Експорт схеми Zod кореневого `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Експорт Zod-схеми кореневого `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби setup wizard, prompt allowlist, побудовники стану setup | + | `plugin-sdk/setup` | Спільні помічники setup wizard, allowlist prompts, builder-и стану 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` | Допоміжні засоби multi-account config/action-gate, допоміжні засоби default-account fallback | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби lookup облікового запису та default-fallback | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби account-list/account-action | + | `plugin-sdk/account-core` | Помічники multi-account config/action-gate, помічники fallback облікового запису за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, помічники нормалізації account-id | + | `plugin-sdk/account-resolution` | Помічники пошуку облікового запису та default-fallback | + | `plugin-sdk/account-helpers` | Вузькі помічники account-list/account-action | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та загальний побудовник | - | `plugin-sdk/bundled-channel-config-schema` | Схеми конфігурації bundled каналів OpenClaw лише для підтримуваних bundled Plugin | - | `plugin-sdk/channel-config-schema-legacy` | Застарілий alias сумісності для схем конфігурації bundled-channel | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із fallback bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби gate авторизації команд | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та generic builder | + | `plugin-sdk/bundled-channel-config-schema` | Bundled схеми конфігурації каналів OpenClaw лише для підтримуваних bundled plugins | + | `plugin-sdk/channel-config-schema-legacy` | Застарілий псевдонім сумісності для bundled-channel config schemas | + | `plugin-sdk/telegram-command-config` | Помічники нормалізації/валідації користувацьких команд Telegram із bundled-contract fallback | + | `plugin-sdk/command-gating` | Вузькі помічники gate авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації draft stream | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби inbound route та побудовника envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й dispatch inbound | - | `plugin-sdk/messaging-targets` | Допоміжні засоби parsing/matching цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження outbound media | - | `plugin-sdk/outbound-send-deps` | Легкий lookup залежностей outbound send для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound delivery, identity, send delegate, session, formatting і payload planning | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптера | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби розв’язання group-policy runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary стану каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації config-write каналу | - | `plugin-sdk/channel-plugin-common` | Спільні експорти prelude Plugin каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання config allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень group-access | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel сумісності для inbound debounce, matching mention, допоміжних засобів mention-policy та envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби inbound debounce | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy, маркерів mention і тексту mention без ширшої поверхні inbound runtime | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування inbound envelope | - | `plugin-sdk/channel-location` | Контекст розташування каналу та допоміжні засоби форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для inbound drops і помилок typing/ack | - | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби message-action каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin | - | `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації route, розв’язання цілі на основі parser, перетворення thread-id у рядок, дедуплікації/компактизації ключів route, типи parsed-target і порівняння route/target | - | `plugin-sdk/channel-targets` | Допоміжні засоби parsing цілей; викликачі порівняння route мають використовувати `plugin-sdk/channel-route` | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, помічники життєвого циклу/finalization draft stream | + | `plugin-sdk/inbound-envelope` | Спільні помічники inbound route та builder envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні помічники record-and-dispatch для inbound | + | `plugin-sdk/messaging-targets` | Помічники parsing/matching цілей | + | `plugin-sdk/outbound-media` | Спільні помічники завантаження outbound media | + | `plugin-sdk/outbound-send-deps` | Легкий пошук залежностей outbound send для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Помічники outbound delivery, identity, send delegate, session, formatting і payload planning | + | `plugin-sdk/poll-runtime` | Вузькі помічники нормалізації poll | + | `plugin-sdk/thread-bindings-runtime` | Помічники життєвого циклу thread-binding і адаптера | + | `plugin-sdk/agent-media-payload` | Застарілий builder agent media payload | + | `plugin-sdk/conversation-runtime` | Помічники conversation/thread binding, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Помічник snapshot runtime-конфігурації | + | `plugin-sdk/runtime-group-policy` | Помічники вирішення runtime group-policy | + | `plugin-sdk/channel-status` | Спільні помічники snapshot/summary стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви channel config-schema | + | `plugin-sdk/channel-config-writes` | Помічники авторизації channel config-write | + | `plugin-sdk/channel-plugin-common` | Спільні експорти прелюдії channel plugin | + | `plugin-sdk/allowlist-config-edit` | Помічники редагування/читання allowlist config | + | `plugin-sdk/group-access` | Спільні помічники рішень group-access | + | `plugin-sdk/direct-dm` | Спільні помічники direct-DM auth/guard | + | `plugin-sdk/discord` | Застарілий фасад сумісності Discord для опублікованого `@openclaw/discord@2026.3.13`; нові plugins мають використовувати generic підшляхи SDK каналу | + | `plugin-sdk/interactive-runtime` | Помічники semantic message presentation, delivery і застарілих interactive reply. Див. [подання повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Barrel сумісності для inbound debounce, mention matching, помічників mention-policy і envelope helpers | + | `plugin-sdk/channel-inbound-debounce` | Вузькі помічники inbound debounce | + | `plugin-sdk/channel-mention-gating` | Вузькі помічники mention-policy, mention marker і mention text без ширшої поверхні inbound runtime | + | `plugin-sdk/channel-envelope` | Вузькі помічники форматування inbound envelope | + | `plugin-sdk/channel-location` | Контекст місця каналу та помічники форматування | + | `plugin-sdk/channel-logging` | Помічники логування каналу для inbound drops і typing/ack failures | + | `plugin-sdk/channel-send-result` | Типи результатів reply | + | `plugin-sdk/channel-actions` | Помічники channel message-action, а також застарілі помічники native schema, збережені для сумісності Plugin | + | `plugin-sdk/channel-route` | Спільна нормалізація маршрутів, parser-driven target resolution, stringification thread-id, dedupe/compact route keys, типи parsed-target і помічники порівняння route/target | + | `plugin-sdk/channel-targets` | Помічники parsing цілей; виклики порівняння маршрутів мають використовувати `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | Типи контрактів каналу | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | + | `plugin-sdk/channel-secret-runtime` | Вузькі помічники secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад постачальника LM Studio для налаштування, виявлення каталогу та підготовки моделі під час виконання | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний runtime-фасад LM Studio для типових параметрів локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/самостійно розміщених постачальників | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування самостійно розміщених постачальників, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові параметри backend CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Runtime-допоміжні засоби розв’язання API-ключів для Plugin постачальників | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби onboarding/запису профілю API-ключа, як-от `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний збирач результату автентифікації OAuth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin постачальників | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env-var автентифікації постачальника | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для локальних стандартних параметрів сервера, виявлення моделей, заголовків запитів і допоміжних функцій для завантажених моделей | + | `plugin-sdk/provider-setup` | Добірні допоміжні функції налаштування локальних/самостійно розгорнутих провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Спеціалізовані допоміжні функції налаштування самостійно розгорнутих OpenAI-сумісних провайдерів | + | `plugin-sdk/cli-backend` | Стандартні параметри бекенда CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції розв’язання API-ключів під час виконання для Plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу API-ключів/запису профілю, як-от `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату автентифікації OAuth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для Plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі replay-policy, допоміжні засоби provider-endpoint і допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Runtime-хук доповнення каталогу постачальника та seams реєстру plugin-provider для контрактних тестів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик відтворення, допоміжні функції кінцевих точок провайдерів і допоміжні функції нормалізації ID моделей, як-от `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання для доповнення каталогу провайдера та шви реєстру Plugin-провайдерів для контрактних тестів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Універсальні допоміжні засоби можливостей HTTP/endpoint постачальника, HTTP-помилки постачальника та допоміжні засоби multipart-форми для аудіотранскрипції | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу постачальника web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для постачальників, яким не потрібне підключення plugin-enable | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime постачальника web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібне | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби нативного транспорту постачальника, як-от guarded fetch, перетворення транспортних повідомлень і writable transport event streams | - | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів onboarding-конфігурації | - | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації групи та розбору команд | + | `plugin-sdk/provider-http` | Загальні допоміжні функції можливостей HTTP/кінцевих точок провайдерів, HTTP-помилки провайдерів і допоміжні функції multipart-форм для транскрипції аудіо | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні функції контракту конфігурації/вибору web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні функції конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, а також обмежені за областю сетери/гетери облікових даних | + | `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/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні функції нативного транспорту провайдерів, як-от захищений fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | + | `plugin-sdk/provider-onboard` | Допоміжні функції патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні функції локальних для процесу singleton/map/cache | + | `plugin-sdk/group-activation` | Вузькі допоміжні функції режиму активації груп і парсингу команд | - + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Збирачі повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби розв’язання approver і action-auth у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного підтвердження exec | - | `plugin-sdk/approval-delivery-runtime` | Адаптери нативних можливостей/доставки підтверджень | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб розв’язання approval Gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Легкі допоміжні засоби завантаження нативного approval adapter для гарячих entrypoint каналів | - | `plugin-sdk/approval-handler-runtime` | Ширші runtime-допоміжні засоби approval handler; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби нативної цілі підтвердження + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на підтвердження exec/plugin | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload підтвердження exec/plugin, допоміжні засоби маршрутизації/runtime нативного підтвердження та допоміжні засоби структурованого відображення підтвердження, як-от `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні засоби нативної цілі сеансу | - | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-primitives-runtime` | Легкі предикати тексту команд для гарячих шляхів каналів | - | `plugin-sdk/command-surface` | Нормалізація command-body і допоміжні засоби command-surface | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні функції авторизації відправника | + | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання затверджувача та автентифікації дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра нативного затвердження exec | + | `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки затверджень | + | `plugin-sdk/approval-gateway-runtime` | Спільна допоміжна функція розв’язання Gateway для затверджень | + | `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні функції завантаження нативного адаптера затверджень для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні функції середовища виконання обробника затверджень; надавайте перевагу вужчим швам адаптера/Gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції нативної цілі затвердження + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді затвердження exec/Plugin | + | `plugin-sdk/approval-runtime` | Допоміжні функції payload затвердження exec/Plugin, допоміжні функції маршрутизації/середовища виконання нативних затверджень і допоміжні функції структурованого відображення затверджень, як-от `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні функції скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні функції тестування контрактів каналів без широкого barrel для тестування | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні функції нативної цілі сеансу | + | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | + | `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналів | + | `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні функції поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналу/Plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі `coerceSecretRef` і допоміжні засоби типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, external-content, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватної мережі | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої runtime-поверхні infra | - | `plugin-sdk/ssrf-runtime` | Pinned-dispatcher, SSRF-guarded fetch, SSRF-помилка та допоміжні засоби політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби Webhook-запиту/цілі та приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру/таймауту тіла запиту | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції збирання контрактів секретів для поверхонь секретів каналів/Plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні функції `coerceSecretRef` і типізації SecretRef для парсингу контрактів секретів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, обмеження DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні функції списку дозволених хостів і політики SSRF для приватної мережі | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні функції закріпленого диспетчера без широкої інфраструктурної поверхні середовища виконання | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції закріпленого диспетчера, захищеного від SSRF fetch, помилок SSRF і політик SSRF | + | `plugin-sdk/secret-input` | Допоміжні функції парсингу введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі Webhook і приведення сирого websocket/body | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру/тайм-ауту тіла запиту | - | Підшлях | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі помічники для середовища виконання, журналювання, резервного копіювання та встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі помічники для середовища виконання env, logger, timeout, retry та backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору CDP URL і помічників автентифікації керування браузером | - | `plugin-sdk/channel-runtime-context` | Загальні помічники реєстрації та пошуку контексту середовища виконання каналу | + | `plugin-sdk/runtime` | Широкі допоміжні засоби для середовища виконання, журналювання, резервного копіювання та встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби для env середовища виконання, logger, timeout, retry і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних засобів автентифікації керування браузером | + | `plugin-sdk/channel-runtime-context` | Допоміжні засоби реєстрації та пошуку generic контексту середовища виконання каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні помічники команд, хуків, HTTP та інтерактивної роботи Plugin | - | `plugin-sdk/hook-runtime` | Спільні помічники конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Помічники лінивого імпорту/прив’язки середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Помічники виконання процесів | - | `plugin-sdk/cli-runtime` | Помічники форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд | - | `plugin-sdk/gateway-runtime` | Клієнт Gateway, RPC CLI Gateway, помилки протоколу Gateway та помічники патчів статусу каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише на рівні типів для форм конфігурації Plugin, як-от `OpenClawConfig`, і типів конфігурації каналів/провайдерів | - | `plugin-sdk/plugin-config-runtime` | Помічники пошуку конфігурації Plugin у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Помічники транзакційної зміни конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Помічники знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot`, і сетери тестових знімків | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд Plugin, hook, http та інтерактивної взаємодії | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язування середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд | + | `plugin-sdk/gateway-runtime` | Клієнт Gateway, RPC CLI Gateway, помилки протоколу Gateway і допоміжні засоби patch статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig`, і типів конфігурації каналів/провайдерів | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації Plugin у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної зміни конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot`, і тестові setter знімків | | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли вбудована контрактна поверхня Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel text-runtime | - | `plugin-sdk/approval-runtime` | Помічники затвердження exec/Plugin, конструктори можливостей затвердження, помічники auth/profile, помічники нативної маршрутизації/середовища виконання та форматування структурованого шляху відображення затвердження | - | `plugin-sdk/reply-runtime` | Спільні помічники середовища виконання для вхідних повідомлень/відповідей, поділу на фрагменти, диспетчеризації, Heartbeat, планувальника відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі помічники диспетчеризації/фіналізації відповідей і міток розмов | - | `plugin-sdk/reply-history` | Спільні помічники коротковіконної історії відповідей і маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/text-autolink-runtime` | Виявлення autolink для посилань на файли без широкого barrel text-runtime | + | `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/Plugin, побудовники можливостей схвалення, допоміжні засоби auth/profile, native routing/runtime і форматування структурованого шляху відображення схвалення | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби середовища виконання inbound/reply, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді та міток розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі помічники поділу тексту/markdown на фрагменти | - | `plugin-sdk/session-store-runtime` | Помічники шляху сховища сесій, ключа сесії, updated-at і зміни сховища | - | `plugin-sdk/cron-store-runtime` | Помічники шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Помічники шляхів каталогів стану/OAuth | - | `plugin-sdk/routing` | Помічники маршруту/ключа сесії/прив’язки акаунта, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні помічники зведення статусу каналу/акаунта, типові значення стану середовища виконання та помічники метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні помічники розв’язувача цілей | - | `plugin-sdk/string-normalization-runtime` | Помічники нормалізації slug/рядків | - | `plugin-sdk/request-url` | Видобування рядкових URL з inputs, подібних до fetch/request | - | `plugin-sdk/run-command` | Запускач команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Спільні зчитувачі параметрів інструментів/CLI | - | `plugin-sdk/tool-payload` | Видобування нормалізованих payload з об’єктів результату інструмента | - | `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Спільні помічники шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Помічники logger підсистем і редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Помічники режиму таблиць Markdown і перетворення | - | `plugin-sdk/model-session-runtime` | Помічники перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Помічники розв’язання конфігурації провайдера talk | - | `plugin-sdk/json-store` | Невеликі помічники читання/запису стану JSON | - | `plugin-sdk/file-lock` | Помічники повторно вхідного блокування файлів | - | `plugin-sdk/persistent-dedupe` | Помічники кешу дедуплікації з дисковою підтримкою | - | `plugin-sdk/acp-runtime` | Помічники середовища виконання/сесії ACP і диспетчеризації відповідей | - | `plugin-sdk/acp-runtime-backend` | Легкі помічники реєстрації бекенда ACP і диспетчеризації відповідей для Plugin, завантажених під час запуску | - | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язок ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і зміни сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій стану/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану середовища виконання та допоміжні засоби метаданих 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` | Спільні reader параметрів інструментів/CLI | + | `plugin-sdk/tool-payload` | Витягує нормалізовані payload з об’єктів результату інструмента | + | `plugin-sdk/tool-send` | Витягує канонічні поля цілі надсилання з аргументів інструмента | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування секретних даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму й перетворення Markdown-таблиць | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби розв’язання конфігурації talk-провайдера | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON-стану | + | `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового dedupe-кешу | + | `plugin-sdk/acp-runtime` | Допоміжні засоби середовища виконання/сесії ACP і dispatch відповідей | + | `plugin-sdk/acp-runtime-backend` | Легкі допоміжні засоби реєстрації бекенду ACP і dispatch відповідей для Plugin, завантажених під час запуску | + | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання ACP binding лише для читання без імпортів запуску lifecycle | | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації середовища виконання агента | - | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Помічники розв’язання зіставлення небезпечних імен | - | `plugin-sdk/device-bootstrap` | Помічники bootstrap пристрою і токенів сполучення | - | `plugin-sdk/extension-shared` | Спільні примітиви помічників пасивного каналу, статусу та ambient proxy | - | `plugin-sdk/models-provider-runtime` | Помічники відповідей команди/провайдера `/models` | - | `plugin-sdk/skill-commands-runtime` | Помічники переліку команд Skills | - | `plugin-sdk/native-command-registry` | Помічники реєстру/побудови/серіалізації нативних команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня довірених Plugin для низькорівневих harness агентів: типи harness, помічники керування/скасування активного запуску, помічники мосту інструментів OpenClaw, помічники політик інструментів плану середовища виконання, класифікація результатів термінала, помічники форматування/деталізації прогресу інструментів і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Помічники виявлення endpoint Z.AI | - | `plugin-sdk/async-lock-runtime` | Помічник локального для процесу async lock для малих файлів стану середовища виконання | - | `plugin-sdk/channel-activity-runtime` | Помічник телеметрії активності каналу | - | `plugin-sdk/concurrency-runtime` | Помічник обмеженої конкурентності асинхронних завдань | - | `plugin-sdk/dedupe-runtime` | Помічники кешу дедуплікації в пам’яті | - | `plugin-sdk/delivery-queue-runtime` | Помічник drain очікуваних вихідних доставок | - | `plugin-sdk/file-access-runtime` | Помічники безпечних шляхів до локальних файлів і джерел медіа | - | `plugin-sdk/heartbeat-runtime` | Помічники подій і видимості Heartbeat | - | `plugin-sdk/number-runtime` | Помічник числового приведення | - | `plugin-sdk/secure-random-runtime` | Помічники безпечних токенів/UUID | - | `plugin-sdk/system-event-runtime` | Помічники черги системних подій | - | `plugin-sdk/transport-ready-runtime` | Помічник очікування готовності транспорту | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи середовища виконання | - | `plugin-sdk/collection-runtime` | Невеликі помічники обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Помічники діагностичних прапорців, подій і контексту трасування | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні помічники класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і помічники pinned lookup | + | `plugin-sdk/boolean-param` | Нестрогий reader булевого параметра | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби розв’язання зіставлення небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів пасивного каналу, статусу й ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команди/провайдера `/models` | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби перелічення команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації native команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня довірених Plugin для низькорівневих harness агентів: типи harness, допоміжні засоби steer/abort active-run, допоміжні засоби мосту інструментів OpenClaw, допоміжні засоби політики інструментів runtime-plan, класифікація результатів термінала, допоміжні засоби форматування/деталізації перебігу інструментів і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб локального для процесу async lock для невеликих файлів стану середовища виконання | + | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | + | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої concurrency async-завдань | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби in-memory dedupe-кешу | + | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб drain для outbound pending-delivery | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів local-file і media-source | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | + | `plugin-sdk/number-runtime` | Допоміжний засіб числового приведення | + | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | + | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | + | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | + | `plugin-sdk/infra-runtime` | Застарілий compatibility shim; використовуйте наведені вище спеціалізовані підшляхи середовища виконання | + | `plugin-sdk/collection-runtime` | Допоміжні засоби невеликого обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних flag, event і trace-context | + | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Обмежений зчитувач тіла відповіді без широкої поверхні середовища виконання медіа | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без налаштованої маршрутизації прив’язок або сховищ сполучення | - | `plugin-sdk/session-store-runtime` | Помічники сховища сесій без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту і фільтрування додаткового контексту без широких імпортів конфігурації/безпеки | - | `plugin-sdk/string-coerce-runtime` | Вузькі помічники приведення й нормалізації примітивних записів/рядків без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Помічники нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Помічники конфігурації retry і запуску retry | - | `plugin-sdk/agent-runtime` | Помічники каталогу агента/ідентичності/робочого простору | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/response-limit-runtime` | Обмежений reader response-body без широкої media runtime surface | + | `plugin-sdk/session-binding-runtime` | Поточний стан binding розмови без налаштованого binding routing або pairing stores | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту та фільтрація додаткового контексту без широких імпортів конфігурації/безпеки | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації примітивних записів/рядків без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry та виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/дедуп директорії на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Підшлях | Ключові експорти | + + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби отримання, перетворення й збереження медіа, а також побудовники медіа-навантажень | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, як-от `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби резервного перемикання для генерації медіа, вибору кандидатів і повідомлень про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа, а також експорти допоміжних засобів зображень і аудіо для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту, markdown і журналювання, як-от вилучення тексту, видимого асистенту, допоміжні засоби рендерингу, поділу на фрагменти й таблиць markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб поділу вихідного тексту на фрагменти | - | `plugin-sdk/speech` | Типи мовленнєвого провайдера, а також експорти директив, реєстру, валідації, побудовника TTS, сумісного з OpenAI, і допоміжних засобів мовлення для провайдерів | - | `plugin-sdk/speech-core` | Спільні типи мовленнєвого провайдера, реєстр, директива, нормалізація й експорти допоміжних засобів мовлення | - | `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі, допоміжні засоби реєстру й спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі й допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи провайдера генерації зображень, а також допоміжні засоби URL зображувальних ресурсів/даних і побудовник провайдера зображень, сумісний з OpenAI | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, резервне перемикання, автентифікація й допоміжні засоби реєстру | - | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби резервного перемикання, пошук провайдера й розбір посилань на модель | - | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби резервного перемикання, пошук провайдера й розбір посилань на модель | - | `plugin-sdk/webhook-targets` | Реєстр цілей Webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin. Нові тести розширень мають натомість імпортувати сфокусовані підшляхи SDK, як-от `plugin-sdk/agent-runtime-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для прямих модульних тестів реєстрації Plugin без імпорту мостів тестових допоміжних засобів репозиторію | - | `plugin-sdk/agent-runtime-test-contracts` | Нативні фікстури контрактів адаптера середовища виконання агента для тестів автентифікації, доставки, fallback, hook інструментів, prompt overlay, схеми й проєкції транскрипту | - | `plugin-sdk/channel-test-helpers` | Орієнтовані на канали тестові допоміжні засоби для загальних контрактів дій/налаштування/статусу, перевірок каталогів, життєвого циклу запуску облікового запису, потоків send-config, моків середовища виконання, проблем статусу, вихідної доставки й реєстрації hook | - | `plugin-sdk/channel-target-testing` | Спільний набір випадків помилок розв’язання цілей для тестів каналів | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, API середовища виконання й побічних ефектів імпорту | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів середовища виконання провайдера, автентифікації, виявлення, onboard, каталогу, майстра, медіаможливостей, політики відтворення, живого аудіо realtime STT, вебпошуку/отримання й потоку | - | `plugin-sdk/provider-http-test-mocks` | Опціональні HTTP/auth моки Vitest для тестів провайдерів, які перевіряють `plugin-sdk/provider-http` | - | `plugin-sdk/test-fixtures` | Загальні фікстури захоплення середовища виконання CLI, контексту пісочниці, записувача skill, повідомлення агента, системної події, перезавантаження модуля, шляху до bundled Plugin, термінального тексту, поділу на фрагменти, auth-токена й типізованих cases | - | `plugin-sdk/test-node-mocks` | Сфокусовані допоміжні засоби моків вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` | + | `plugin-sdk/media-runtime` | Спільні помічники отримання/перетворення/зберігання медіа, а також конструктори медіа-навантажень | + | `plugin-sdk/media-store` | Вузькі помічники сховища медіа, як-от `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні помічники резервного перемикання для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти помічників для зображень/аудіо, орієнтовані на провайдерів | + | `plugin-sdk/text-runtime` | Спільні помічники для тексту/markdown/журналювання, як-от вилучення видимого для асистента тексту, помічники рендерингу/розбиття/таблиць markdown, помічники редагування, помічники тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Помічник розбиття вихідного тексту | + | `plugin-sdk/speech` | Типи мовних провайдерів, а також орієнтовані на провайдерів експорти директив, реєстру, валідації, OpenAI-сумісного конструктора TTS і мовних помічників | + | `plugin-sdk/speech-core` | Спільні типи мовних провайдерів, експорти реєстру, директив, нормалізації та мовних помічників | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, помічники реєстру та спільний помічник WebSocket-сеансу | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та помічники реєстру | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень, а також помічники ресурсів зображень/data URL і OpenAI-сумісний конструктор провайдера зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, резервне перемикання, автентифікація та помічники реєстру | + | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, помічники резервного перемикання, пошук провайдера та розбір посилань на модель | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, помічники резервного перемикання, пошук провайдера та розбір посилань на модель | + | `plugin-sdk/webhook-targets` | Реєстр цілей Webhook і помічники встановлення маршрутів | + | `plugin-sdk/webhook-path` | Помічники нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні помічники завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | + | `plugin-sdk/testing` | Широкий compatibility barrel для застарілих тестів plugin. Нові тести розширень натомість мають імпортувати сфокусовані підшляхи SDK, як-от `plugin-sdk/agent-runtime-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | Мінімальний помічник `createTestPluginApi` для unit-тестів прямої реєстрації plugin без імпорту мостів тестових помічників репозиторію | + | `plugin-sdk/agent-runtime-test-contracts` | Нативні фікстури контрактів адаптера agent-runtime для тестів автентифікації, доставки, fallback, tool-hook, prompt-overlay, схеми та проєкції транскрипту | + | `plugin-sdk/channel-test-helpers` | Орієнтовані на канал тестові помічники для загальних контрактів дій/налаштування/статусу, перевірок каталогів, життєвого циклу запуску облікового запису, потоків send-config, runtime-моків, проблем статусу, вихідної доставки та реєстрації хуків | + | `plugin-sdk/channel-target-testing` | Спільний набір випадків помилок визначення цілі для тестів каналів | + | `plugin-sdk/plugin-test-contracts` | Помічники контрактів пакета plugin, реєстрації, публічного артефакту, прямого імпорту, runtime API та побічних ефектів імпорту | + | `plugin-sdk/provider-test-contracts` | Помічники контрактів runtime провайдера, автентифікації, виявлення, onboard, каталогу, майстра, медіа-можливостей, політики replay, live-audio realtime STT, web-search/fetch і потоків | + | `plugin-sdk/provider-http-test-mocks` | Opt-in HTTP/auth моки Vitest для тестів провайдерів, які перевіряють `plugin-sdk/provider-http` | + | `plugin-sdk/test-fixtures` | Загальні фікстури захоплення CLI runtime, контексту sandbox, записувача skill, agent-message, system-event, перезавантаження модуля, шляху bundled plugin, terminal-text, розбиття, auth-token і типізованих випадків | + | `plugin-sdk/test-node-mocks` | Сфокусовані помічники моків вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` | - - | Підшлях | Ключові експорти | + + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня bundled допоміжних засобів memory-core для допоміжних засобів менеджера/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation-рушія хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embeddings хоста пам’яті, доступ до реєстру, локальний провайдер і загальні пакетні/віддалені допоміжні засоби | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD-рушія хоста пам’яті | + | `plugin-sdk/memory-core` | Поверхня bundled memory-core помічників для помічників manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексу/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти рушія foundation хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і загальні batch/remote помічники | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти рушія QMD хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти рушія сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби середовища виконання CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core середовища виконання хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/середовища виконання хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний щодо постачальника псевдонім для допоміжних засобів core середовища виконання хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний щодо постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний щодо постачальника псевдонім для допоміжних засобів файлів/середовища виконання хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для Plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад середовища виконання активної пам’яті для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний щодо постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні помічники хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Помічники запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Помічники секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Помічники журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Помічники статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Помічники CLI runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Помічники core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Помічники файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний щодо постачальника псевдонім для core runtime помічників хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний щодо постачальника псевдонім для помічників журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний щодо постачальника псевдонім для помічників файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні помічники managed-markdown для plugins, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний щодо постачальника псевдонім для помічників статусу хоста пам’яті | - - Наразі немає зарезервованих підшляхів SDK для bundled допоміжних засобів. Допоміжні засоби, специфічні для власника, - розташовані всередині пакета Plugin-власника, а багаторазові контракти хоста + + Наразі немає зарезервованих підшляхів SDK bundled-helper. Власницькі + помічники живуть у пакеті plugin власника, а повторно використовувані контракти хоста використовують загальні підшляхи SDK, як-от `plugin-sdk/gateway-runtime`, `plugin-sdk/security-runtime` і `plugin-sdk/plugin-config-runtime`. @@ -332,4 +333,4 @@ x-i18n: - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/reference/transcript-hygiene.md b/docs/uk/reference/transcript-hygiene.md index 16b283d90..8e36abbe4 100644 --- a/docs/uk/reference/transcript-hygiene.md +++ b/docs/uk/reference/transcript-hygiene.md @@ -1,51 +1,52 @@ --- read_when: - - Ви налагоджуєте відхилення запитів провайдером, пов’язані зі структурою транскрипту - - Ви змінюєте логіку санітизації транскрипту або виправлення викликів інструментів - - Ви досліджуєте невідповідності ідентифікаторів викликів інструментів між провайдерами -summary: 'Довідка: правила очищення та відновлення транскриптів, специфічні для провайдера' -title: Гігієна транскрипту + - Ви діагностуєте відхилення запитів провайдера, пов’язані зі структурою транскрипту. + - Ви змінюєте логіку санітизації транскриптів або виправлення викликів інструментів + - Ви досліджуєте невідповідності ідентифікаторів викликів інструментів у різних провайдерів +summary: 'Довідка: правила очищення та відновлення транскрипту, специфічні для провайдера' +title: Гігієна стенограми x-i18n: - generated_at: "2026-04-28T19:39:03Z" + generated_at: "2026-04-28T20:13:10Z" model: gpt-5.5 provider: openai - source_hash: 51459c719c6314b2980057d7e1e003e1598e8fe4a619c081aa25ce29200645a8 + source_hash: d95f065d87ce58019ff2e6cdd6801879404d3b4fa402d26fc6fed9d51966b0a1 source_path: reference/transcript-hygiene.md workflow: 16 --- -OpenClaw застосовує **специфічні для провайдера виправлення** до транскриптів перед запуском (під час побудови контексту моделі). Більшість із них — це коригування **в пам’яті**, які використовуються для задоволення суворих вимог провайдера. Окремий прохід ремонту файлу сеансу також може переписати збережений JSONL до завантаження сеансу: або відкинувши некоректні рядки JSONL, або виправивши збережені репліки, які синтаксично валідні, але відомо, що їх відхиляє -провайдер під час повторного відтворення. Коли відбувається ремонт, оригінальний файл резервно копіюється поруч із -файлом сеансу. +OpenClaw застосовує **виправлення, специфічні для провайдера**, до транскриптів перед запуском (під час побудови контексту моделі). Більшість із них — це коригування **в пам’яті**, які потрібні для дотримання суворих вимог провайдерів. Окремий прохід відновлення файлу сесії також може переписувати збережений JSONL до завантаження сесії: або видаляючи некоректні рядки JSONL, або відновлюючи збережені ходи, які є синтаксично коректними, але відомо, що їх відхиляє +провайдер під час повторного відтворення. Коли відновлення відбувається, резервна копія оригінального файлу створюється поруч +із файлом сесії. -Область охоплює: +Область охоплення: -- Контекст prompt лише під час виконання, який не потрапляє в видимі користувачу репліки транскрипту +- Контекст підказки лише для часу виконання не потрапляє до видимих користувачу ходів транскрипту - Очищення ідентифікаторів викликів інструментів - Перевірка вхідних даних викликів інструментів -- Ремонт зіставлення результатів інструментів -- Перевірка / упорядкування реплік -- Очищення підписів думок -- Очищення підписів мислення +- Відновлення відповідності результатів інструментів +- Перевірка / впорядкування ходів +- Очищення сигнатур думок +- Очищення сигнатур мислення - Очищення корисного навантаження зображень -- Позначення походження користувацького вводу (для prompt, маршрутизованих між сеансами) -- Ремонт порожніх помилкових реплік асистента для повторного відтворення Bedrock Converse +- Очищення порожніх текстових блоків перед повторним відтворенням у провайдера +- Позначення походження введення користувача (для підказок, маршрутизованих між сесіями) +- Відновлення порожніх помилкових ходів асистента для повторного відтворення Bedrock Converse -Якщо вам потрібні деталі зберігання транскриптів, див.: +Якщо вам потрібні подробиці про зберігання транскриптів, дивіться: -- [Поглиблений огляд керування сеансами](/uk/reference/session-management-compaction) +- [Докладний розбір керування сесіями й Compaction](/uk/reference/session-management-compaction) --- -## Глобальне правило: контекст виконання не є користувацьким транскриптом +## Глобальне правило: контекст часу виконання не є користувацьким транскриптом -Контекст виконання/системи може бути доданий до prompt моделі для репліки, але це -не контент, створений кінцевим користувачем. OpenClaw зберігає окреме тіло -prompt, орієнтоване на транскрипт, для відповідей Gateway, чергових подальших повідомлень, ACP, CLI та вбудованих запусків Pi. -Збережені видимі користувацькі репліки використовують це тіло транскрипту замість -збагаченого під час виконання prompt. +Контекст часу виконання / системний контекст можна додати до підказки моделі для ходу, але це +не вміст, створений кінцевим користувачем. OpenClaw зберігає окреме, орієнтоване на транскрипт +тіло підказки для відповідей Gateway, поставлених у чергу подальших повідомлень, ACP, CLI та вбудованих запусків Pi. +Збережені видимі користувацькі ходи використовують це тіло транскрипту замість +підказки, збагаченої контекстом часу виконання. -Для застарілих сеансів, які вже зберегли обгортки виконання, поверхні історії Gateway +Для застарілих сесій, у яких уже були збережені обгортки часу виконання, поверхні історії Gateway застосовують проєкцію відображення перед поверненням повідомлень клієнтам WebChat, TUI, REST або SSE. @@ -56,11 +57,11 @@ TUI, REST або SSE. Уся гігієна транскриптів централізована у вбудованому runner: - Вибір політики: `src/agents/transcript-policy.ts` -- Застосування очищення/ремонту: `sanitizeSessionHistory` у `src/agents/pi-embedded-runner/replay-history.ts` +- Застосування очищення / відновлення: `sanitizeSessionHistory` у `src/agents/pi-embedded-runner/replay-history.ts` -Політика використовує `provider`, `modelApi` і `modelId`, щоб вирішити, що застосовувати. +Політика використовує `provider`, `modelApi` та `modelId`, щоб вирішити, що застосовувати. -Окремо від гігієни транскриптів файли сеансів ремонтуються (за потреби) перед завантаженням: +Окремо від гігієни транскриптів файли сесій відновлюються (за потреби) перед завантаженням: - `repairSessionFileIfNeeded` у `src/agents/session-file-repair.ts` - Викликається з `run/attempt.ts` і `compact.ts` (вбудований runner) @@ -69,25 +70,28 @@ TUI, REST або SSE. ## Глобальне правило: очищення зображень -Корисне навантаження зображень завжди очищується, щоб запобігти відхиленню на боці провайдера через обмеження -розміру (зменшення масштабу/повторне стиснення надмірно великих зображень base64). +Корисне навантаження зображень завжди очищається, щоб запобігти відхиленню на боці провайдера через обмеження +розміру (зменшення масштабу / повторне стискання надмірно великих base64-зображень). -Це також допомагає контролювати тиск токенів від зображень для моделей із підтримкою зору. -Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталізацію. +Це також допомагає контролювати тиск на токени від зображень для моделей із підтримкою бачення. +Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталі. Реалізація: - `sanitizeSessionMessagesImages` у `src/agents/pi-embedded-helpers/images.ts` - `sanitizeContentBlocksImages` у `src/agents/tool-images.ts` - Максимальна сторона зображення налаштовується через `agents.defaults.imageMaxDimensionPx` (типово: `1200`). +- Порожні текстові блоки видаляються, поки цей прохід обходить вміст для повторного відтворення. Ходи асистента, + які стають порожніми, видаляються з копії для повторного відтворення; користувацькі ходи та ходи результатів інструментів, + які стають порожніми, отримують непорожній заповнювач пропущеного вмісту. --- ## Глобальне правило: некоректні виклики інструментів -Блоки викликів інструментів асистента, у яких відсутні і `input`, і `arguments`, відкидаються -до побудови контексту моделі. Це запобігає відхиленням провайдером через частково -збережені виклики інструментів (наприклад, після збою через ліміт частоти). +Блоки викликів інструментів асистента, у яких відсутні і `input`, і `arguments`, видаляються +до побудови контексту моделі. Це запобігає відхиленням провайдерами через частково +збережені виклики інструментів (наприклад, після помилки обмеження швидкості). Реалізація: @@ -96,22 +100,22 @@ TUI, REST або SSE. --- -## Глобальне правило: походження міжсеансового вводу +## Глобальне правило: походження введення між сесіями -Коли агент надсилає prompt в інший сеанс через `sessions_send` (зокрема -кроки відповіді/оголошення між агентами), OpenClaw зберігає створену користувацьку репліку з: +Коли агент надсилає підказку в іншу сесію через `sessions_send` (зокрема +кроки відповіді / оголошення від агента до агента), OpenClaw зберігає створений користувацький хід із: - `message.provenance.kind = "inter_session"` -OpenClaw також додає на початок тієї самої репліки маркер `[Inter-session message ... isUser=false]` -перед текстом маршрутизованого prompt, щоб активний виклик моделі міг відрізнити -вивід стороннього сеансу від зовнішніх інструкцій кінцевого користувача. Цей маркер містить -вихідний сеанс, канал і інструмент, коли вони доступні. Транскрипт усе ще використовує -`role: "user"` для сумісності з провайдером, але і видимий текст, і метадані -походження позначають репліку як міжсеансові дані. +OpenClaw також додає на початок того самого ходу маркер `[Inter-session message ... isUser=false]` +перед текстом маршрутизованої підказки, щоб активний виклик моделі міг відрізнити +вивід чужої сесії від зовнішніх інструкцій кінцевого користувача. Цей маркер містить +вихідну сесію, канал і інструмент, коли вони доступні. Транскрипт усе ще використовує +`role: "user"` для сумісності з провайдерами, але видимий текст і метадані походження +обидва позначають хід як міжсесійні дані. Під час перебудови контексту OpenClaw застосовує той самий маркер до старіших збережених -міжсеансових користувацьких реплік, які мають лише метадані походження. +міжсесійних користувацьких ходів, які мають лише метадані походження. --- @@ -120,63 +124,65 @@ OpenClaw також додає на початок тієї самої репл **OpenAI / OpenAI Codex** - Лише очищення зображень. -- Відкидати осиротілі підписи reasoning (окремі елементи reasoning без наступного блока контенту) для транскриптів OpenAI Responses/Codex і відкидати повторно відтворюваний OpenAI reasoning після перемикання маршруту моделі. -- Зберігати повторно відтворювані payload елементів reasoning OpenAI Responses, зокрема зашифровані елементи з порожнім підсумком, щоб ручне/WebSocket повторне відтворення зберігало потрібний стан `rs_*`, поєднаний з елементами виводу асистента. -- Без очищення ідентифікаторів викликів інструментів. -- Ремонт зіставлення результатів інструментів може переміщувати реальні зіставлені виводи та синтезувати Codex-стилю виводи `aborted` для відсутніх викликів інструментів. -- Без перевірки чи переупорядкування реплік. -- Відсутні виводи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex. -- Без видалення підписів думок. +- Видаляються осиротілі сигнатури reasoning (окремі елементи reasoning без наступного блоку вмісту) для транскриптів OpenAI Responses/Codex, а також видаляється придатний до повторного відтворення OpenAI reasoning після перемикання маршруту моделі. +- Зберігаються корисні навантаження елементів reasoning OpenAI Responses, придатні до повторного відтворення, включно із зашифрованими елементами з порожнім summary, щоб ручне / WebSocket-повторне відтворення зберігало потрібний стан `rs_*` у парі з елементами виводу асистента. +- Очищення ідентифікаторів викликів інструментів не виконується. +- Відновлення відповідності результатів інструментів може переміщувати справжні зіставлені виходи та синтезувати Codex-стилізовані виходи `aborted` для відсутніх викликів інструментів. +- Перевірка або перевпорядкування ходів не виконується. +- Відсутні виходи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex. +- Сигнатури думок не видаляються. **OpenAI-сумісна Gemma 4** -- Історичні блоки мислення/reasoning асистента видаляються перед повторним відтворенням, щоб локальні - OpenAI-сумісні сервери Gemma 4 не отримували контент reasoning із попередніх реплік. -- Поточні продовження викликів інструментів у межах тієї самої репліки зберігають блок reasoning асистента - приєднаним до виклику інструмента, доки результат інструмента не буде повторно відтворено. +- Історичні блоки thinking/reasoning асистента видаляються перед повторним відтворенням, щоб локальні + OpenAI-сумісні сервери Gemma 4 не отримували вміст reasoning із попередніх ходів. +- Поточні продовження викликів інструментів у тому самому ході зберігають блок reasoning асистента, + прикріплений до виклику інструмента, доки результат інструмента не буде повторно відтворено. **Google (Generative AI / Gemini CLI / Antigravity)** -- Очищення ідентифікаторів викликів інструментів: суворо літерно-цифрові. -- Ремонт зіставлення результатів інструментів і синтетичні результати інструментів. -- Перевірка реплік (чергування реплік у стилі Gemini). -- Виправлення порядку реплік Google (додавання на початок крихітного користувацького bootstrap, якщо історія починається з асистента). -- Antigravity Claude: нормалізувати підписи мислення; відкидати непідписані блоки мислення. +- Очищення ідентифікаторів викликів інструментів: суворо буквено-цифрові. +- Відновлення відповідності результатів інструментів і синтетичні результати інструментів. +- Перевірка ходів (чергування ходів у стилі Gemini). +- Виправлення порядку ходів Google (додає крихітний користувацький bootstrap на початок, якщо історія починається з асистента). +- Antigravity Claude: нормалізуються сигнатури thinking; непідписані блоки thinking видаляються. -**Anthropic / Minimax (Anthropic-сумісні)** +**Anthropic / Minimax (Anthropic-сумісний)** -- Ремонт зіставлення результатів інструментів і синтетичні результати інструментів. -- Перевірка реплік (об’єднання послідовних користувацьких реплік для задоволення суворого чергування). -- Кінцеві репліки попереднього заповнення асистента видаляються з вихідних payload Anthropic Messages, - коли мислення ввімкнено, зокрема для маршрутів Cloudflare AI Gateway. -- Блоки мислення з відсутніми, порожніми або blank підписами повторного відтворення видаляються - перед перетворенням для провайдера. Якщо це спорожнює репліку асистента, OpenClaw зберігає - форму репліки з непорожнім текстом про пропущене reasoning. -- Старіші репліки асистента лише з мисленням, які потрібно видалити, замінюються - непорожнім текстом про пропущене reasoning, щоб адаптери провайдерів не відкидали репліку +- Відновлення відповідності результатів інструментів і синтетичні результати інструментів. +- Перевірка ходів (об’єднання послідовних користувацьких ходів для дотримання суворого чергування). +- Кінцеві ходи попереднього заповнення асистента видаляються з вихідних корисних навантажень Anthropic Messages, + коли thinking увімкнено, включно з маршрутами Cloudflare AI Gateway. +- Блоки thinking з відсутніми, порожніми або blank-сигнатурами повторного відтворення видаляються + перед перетворенням для провайдера. Якщо це робить хід асистента порожнім, OpenClaw зберігає + форму ходу з непорожнім текстом пропущеного reasoning. +- Старіші ходи асистента лише з thinking, які потрібно видалити, замінюються + непорожнім текстом пропущеного reasoning, щоб адаптери провайдерів не видаляли хід повторного відтворення. **Amazon Bedrock (Converse API)** -- Порожні репліки асистента з помилкою stream ремонтуються в непорожній fallback текстовий блок +- Порожні помилкові ходи потоку асистента відновлюються до непорожнього резервного текстового блока перед повторним відтворенням. Bedrock Converse відхиляє повідомлення асистента з `content: []`, тому - збережені репліки асистента з `stopReason: "error"` і порожнім контентом також - ремонтуються на диску перед завантаженням. -- Блоки мислення Claude з відсутніми, порожніми або blank підписами повторного відтворення - видаляються перед повторним відтворенням Converse. Якщо це спорожнює репліку асистента, OpenClaw - зберігає форму репліки з непорожнім текстом про пропущене reasoning. -- Старіші репліки асистента лише з мисленням, які потрібно видалити, замінюються - непорожнім текстом про пропущене reasoning, щоб повторне відтворення Converse зберігало сувору форму реплік. -- Повторне відтворення фільтрує delivery-mirror OpenClaw і вставлені gateway репліки асистента. + збережені ходи асистента з `stopReason: "error"` і порожнім вмістом також + відновлюються на диску перед завантаженням. +- Помилкові ходи потоку асистента, які містять лише порожні текстові блоки, видаляються + з копії повторного відтворення в пам’яті замість повторного відтворення некоректного порожнього блока. +- Блоки thinking Claude з відсутніми, порожніми або blank-сигнатурами повторного відтворення + видаляються перед повторним відтворенням Converse. Якщо це робить хід асистента порожнім, OpenClaw + зберігає форму ходу з непорожнім текстом пропущеного reasoning. +- Старіші ходи асистента лише з thinking, які потрібно видалити, замінюються + непорожнім текстом пропущеного reasoning, щоб повторне відтворення Converse зберігало сувору форму ходу. +- Повторне відтворення фільтрує ходи асистента, які є delivery-mirror OpenClaw і вставлені Gateway. - Очищення зображень застосовується через глобальне правило. -**Mistral (зокрема виявлення на основі ідентифікатора моделі)** +**Mistral (включно з виявленням на основі model-id)** -- Очищення ідентифікаторів викликів інструментів: strict9 (літерно-цифрові довжиною 9). +- Очищення ідентифікаторів викликів інструментів: strict9 (буквено-цифрові, довжина 9). **OpenRouter Gemini** -- Очищення підписів думок: видаляти не-base64 значення `thought_signature` (залишати base64). +- Очищення сигнатур думок: видалення не-base64 значень `thought_signature` (base64 зберігається). **Усе інше** @@ -186,22 +192,22 @@ OpenClaw також додає на початок тієї самої репл ## Історична поведінка (до 2026.1.22) -До випуску 2026.1.22 OpenClaw застосовував кілька шарів гігієни транскриптів: +До випуску 2026.1.22 OpenClaw застосовував кілька рівнів гігієни транскриптів: -- **transcript-sanitize extension** виконувався під час кожної побудови контексту і міг: - - Ремонтувати зіставлення використання/результатів інструментів. - - Очищати ідентифікатори викликів інструментів (зокрема несуворий режим, який зберігав `_`/`-`). -- Runner також виконував специфічне для провайдера очищення, що дублювало роботу. -- Додаткові мутації відбувалися поза політикою провайдера, зокрема: - - Видалення тегів `` із тексту асистента перед збереженням. - - Відкидання порожніх помилкових реплік асистента. - - Обрізання контенту асистента після викликів інструментів. +- **transcript-sanitize extension** виконувався під час кожної побудови контексту й міг: + - Відновлювати відповідність використання інструментів / результатів. + - Очищати ідентифікатори викликів інструментів (включно з несуворим режимом, який зберігав `_`/`-`). +- Runner також виконував очищення, специфічне для провайдера, що дублювало роботу. +- Додаткові мутації відбувалися поза політикою провайдера, включно з: + - Видаленням тегів `` із тексту асистента перед збереженням. + - Видаленням порожніх помилкових ходів асистента. + - Обрізанням вмісту асистента після викликів інструментів. -Ця складність спричиняла регресії між провайдерами (особливо для зіставлення `openai-responses` +Ця складність спричиняла регресії між провайдерами (зокрема відповідність `openai-responses` `call_id|fc_id`). Очищення 2026.1.22 видалило extension, централізувало -логіку в runner і зробило OpenAI **без змін** поза очищенням зображень. +логіку в runner і зробило OpenAI **no-touch** поза очищенням зображень. ## Пов’язане -- [Керування сеансами](/uk/concepts/session) -- [Обрізання сеансів](/uk/concepts/session-pruning) +- [Керування сесіями](/uk/concepts/session) +- [Скорочення сесії](/uk/concepts/session-pruning) diff --git a/docs/uk/start/bootstrapping.md b/docs/uk/start/bootstrapping.md index 8571eac3d..7024364ea 100644 --- a/docs/uk/start/bootstrapping.md +++ b/docs/uk/start/bootstrapping.md @@ -1,50 +1,47 @@ --- read_when: - - Розуміння того, що відбувається під час першого запуску agent - - Пояснення, де розміщуються файли початкового налаштування + - Розуміння того, що відбувається під час першого запуску агента + - Пояснення, де розташовані файли початкової ініціалізації - Налагодження налаштування ідентичності під час онбордингу sidebarTitle: Bootstrapping -summary: Ритуал початкового налаштування agent, що заповнює workspace і файли ідентичності -title: Початкове налаштування agent +summary: Ритуал початкового налаштування агента, який ініціалізує робочий простір і файли ідентичності +title: Ініціалізація агента x-i18n: - generated_at: "2026-04-24T19:53:07Z" - model: gpt-5.4 + generated_at: "2026-04-28T20:13:44Z" + model: gpt-5.5 provider: openai - source_hash: 435eb2a14707623903ab7873774cc8d4489b960719cf6a525d547983f8338027 + source_hash: de829f82016ae1e4dcd7714502ca8d11755556fed18b985a7e2bada4149a2d46 source_path: start/bootstrapping.md - workflow: 15 + workflow: 16 --- -Початкове налгодування — це ритуал **першого запуску**, який готує workspace agent і -збирає відомості про ідентичність. Він відбувається після онбордингу, коли agent -запускається вперше. +Початкове налаштування — це ритуал **першого запуску**, який готує робочий простір агента й збирає дані ідентичності. Воно відбувається після онбордингу, коли агент запускається вперше. ## Що робить початкове налаштування -Під час першого запуску agent OpenClaw ініціалізує workspace (типово +Під час першого запуску агента OpenClaw виконує початкове налаштування робочого простору (типово `~/.openclaw/workspace`): -- Заповнює `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`. +- Створює початкові `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`. - Запускає короткий ритуал запитань і відповідей (по одному запитанню за раз). -- Записує ідентичність і налаштування до `IDENTITY.md`, `USER.md`, `SOUL.md`. -- Видаляє `BOOTSTRAP.md` після завершення, щоб він виконувався лише один раз. +- Записує ідентичність і вподобання до `IDENTITY.md`, `USER.md`, `SOUL.md`. +- Після завершення видаляє `BOOTSTRAP.md`, щоб він запускався лише один раз. + +Для запусків із вбудованими/локальними моделями OpenClaw не включає `BOOTSTRAP.md` до привілейованого системного контексту. Під час основного інтерактивного першого запуску він усе одно передає вміст файла в користувацькому запиті, щоб моделі, які не завжди надійно викликають інструмент `read`, могли завершити ритуал. Якщо поточний запуск не може безпечно отримати доступ до робочого простору, агент отримує обмежену нотатку початкового налаштування замість загального привітання. ## Пропуск початкового налаштування -Щоб пропустити це для попередньо заповненого workspace, виконайте `openclaw onboard --skip-bootstrap`. +Щоб пропустити це для попередньо заповненого робочого простору, виконайте `openclaw onboard --skip-bootstrap`. -## Де це виконується +## Де воно запускається -Початкове налаштування завжди виконується на **хості gateway**. Якщо застосунок macOS підключається до -віддаленого Gateway, workspace і файли початкового налаштування зберігаються на тій віддаленій -машині. +Початкове налаштування завжди запускається на **хості Gateway**. Якщо застосунок macOS підключається до віддаленого Gateway, робочий простір і файли початкового налаштування розташовані на цій віддаленій машині. -Коли Gateway працює на іншій машині, редагуйте файли workspace на хості gateway -(наприклад, `user@gateway-host:~/.openclaw/workspace`). +Коли Gateway працює на іншій машині, редагуйте файли робочого простору на хості Gateway (наприклад, `user@gateway-host:~/.openclaw/workspace`). ## Пов’язана документація - Онбординг застосунку macOS: [Онбординг](/uk/start/onboarding) -- Структура workspace: [Workspace agent](/uk/concepts/agent-workspace) +- Структура робочого простору: [Робочий простір агента](/uk/concepts/agent-workspace) diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index f193d3248..f72cdf7a9 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,34 +1,34 @@ --- read_when: - - Запуск середовищ для програмування через ACP + - Запуск середовищ для кодування через ACP - Налаштування сеансів ACP, прив’язаних до розмови, у каналах обміну повідомленнями - - Прив’язування розмови каналу повідомлень до постійного сеансу ACP - - Усунення несправностей бекенда ACP, підключення Plugin або доставки завершень - - Використання команд /acp із чату + - Прив’язування розмови в каналі повідомлень до постійного сеансу ACP + - Усунення несправностей бекенду ACP, підключення Plugin або доставки завершень + - Виконання команд /acp із чату sidebarTitle: ACP agents -summary: Запускайте зовнішні обв’язки для програмування (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP +summary: Запускайте зовнішні обв’язки кодування (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP title: Агенти ACP x-i18n: - generated_at: "2026-04-28T11:27:10Z" + generated_at: "2026-04-28T20:14:14Z" model: gpt-5.5 provider: openai - source_hash: dd6afc6f17898897ee25c50b3e80ccdbbc3c00a5a2d2a57783ff70408ec16b5a + source_hash: f7e9100cc825f77ce0972e26ecc26be1526922174c727d2024965d62fa86cd70 source_path: tools/acp-agents.md workflow: 16 --- -Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) -дають OpenClaw змогу запускати зовнішні кодингові середовища (наприклад Pi, Claude Code, +[Сеанси Agent Client Protocol (ACP)](https://agentclientprotocol.com/) +дають OpenClaw змогу запускати зовнішні кодингові обв’язки (наприклад Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші -підтримувані середовища ACPX) через бекенд-Plugin ACP. +підтримувані обв’язки ACPX) через бекенд-Plugin ACP. -Кожне створення сеансу ACP відстежується як [фонова задача](/uk/automation/tasks). +Кожен запуск сеансу ACP відстежується як [фонова задача](/uk/automation/tasks). -**ACP — це шлях зовнішнього середовища, а не стандартний шлях Codex.** Нативний -Plugin сервера застосунку Codex володіє елементами керування `/codex ...` і -вбудованим середовищем виконання `agentRuntime.id: "codex"`; ACP володіє -елементами керування `/acp ...` і сеансами `sessions_spawn({ runtime: "acp" })`. +**ACP — це шлях зовнішньої обв’язки, а не стандартний шлях Codex.** Нативний +Plugin сервера застосунку Codex відповідає за керування `/codex ...` і +вбудоване середовище виконання `agentRuntime.id: "codex"`; ACP відповідає за +керування `/acp ...` і сеанси `sessions_spawn({ runtime: "acp" })`. Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо до наявних розмов каналів OpenClaw, використовуйте @@ -37,200 +37,202 @@ Plugin сервера застосунку Codex володіє елемента ## Яка сторінка мені потрібна? -| Ви хочете… | Використовуйте | Примітки | -| ----------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях сервера застосунку Codex, коли Plugin `codex` увімкнено; включає прив’язані відповіді чату, пересилання зображень, модель/швидкий режим/дозволи, зупинку та керування напрямом. ACP — явний резервний варіант | -| Запустити Claude Code, Gemini CLI, явний Codex ACP або інше зовнішнє середовище _через_ OpenClaw | Ця сторінка | Прив’язані до чату сеанси, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові задачі, елементи керування середовищем виконання | -| Надати сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим моста. IDE/клієнт спілкується ACP з OpenClaw через stdio/WebSocket | -| Повторно використати локальний AI CLI як текстову резервну модель | [Бекенди CLI](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без середовища виконання | +| Ви хочете… | Використовуйте | Примітки | +| --------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях сервера застосунку Codex, коли Plugin `codex` увімкнено; включає відповіді прив’язаного чату, пересилання зображень, model/fast/permissions, stop і steer. ACP є явним резервним варіантом | +| Запустити Claude Code, Gemini CLI, явний Codex ACP або іншу зовнішню обв’язку _через_ OpenClaw | Ця сторінка | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові задачі, керування середовищем виконання | +| Надати сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим моста. IDE/клієнт спілкується ACP з OpenClaw через stdio/WebSocket | +| Повторно використати локальний AI CLI як текстову резервну модель | [Бекенди CLI](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без керування ACP, без середовища виконання обв’язки | -## Це працює одразу після встановлення? +## Чи працює це одразу? -Зазвичай так. Свіжі встановлення постачаються з увімкненим за замовчуванням -вбудованим Plugin середовища виконання `acpx` із закріпленим локально для Plugin -бінарним файлом `acpx`, який OpenClaw перевіряє та самостійно відновлює під час -запуску. Запустіть `/acp doctor` для перевірки готовності. +Зазвичай так. Нові інсталяції постачаються з увімкненим за замовчуванням +вбудованим Plugin середовища виконання `acpx` із закріпленим локально для +Plugin бінарним файлом `acpx`, який OpenClaw перевіряє та самостійно +відновлює під час запуску. Виконайте `/acp doctor` для перевірки готовності. -OpenClaw повідомляє агентам про створення ACP лише тоді, коли ACP **справді -придатний до використання**: ACP має бути ввімкнено, диспетчеризацію не має бути -вимкнено, поточний сеанс не має бути заблокований пісочницею, а бекенд +OpenClaw навчає агентів запуску ACP лише тоді, коли ACP **справді +придатний до використання**: ACP має бути увімкнений, dispatch не має бути +вимкнений, поточний сеанс не має бути заблокований пісочницею, а бекенд середовища виконання має бути завантажений. Якщо ці умови не виконано, Skills -Plugin ACP і підказки ACP для `sessions_spawn` залишаються прихованими, щоб агент -не пропонував недоступний бекенд. +Plugin ACP і підказки ACP для `sessions_spawn` залишаються прихованими, щоб +агент не пропонував недоступний бекенд. - - - Якщо `plugins.allow` задано, це обмежувальний інвентар Plugin і він **має** містити `acpx`; інакше вбудований стандартний варіант навмисно блокується, а `/acp doctor` повідомляє про відсутній запис у списку дозволених. - - Вбудований адаптер Codex ACP постачається разом із Plugin `acpx` і запускається локально, коли це можливо. - - Інші адаптери цільових середовищ усе ще можуть завантажуватися на вимогу через `npx` під час першого використання. - - Авторизація постачальника все одно має існувати на хості для цього середовища. - - Якщо на хості немає npm або доступу до мережі, перші завантаження адаптерів не вдаватимуться, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. + + - Якщо задано `plugins.allow`, це обмежувальний інвентар Plugin і він **має** включати `acpx`; інакше вбудований стандартний варіант навмисно блокується, а `/acp doctor` повідомляє про відсутній запис allowlist. + - Вбудований адаптер Codex ACP розгортається разом із Plugin `acpx` і, коли можливо, запускається локально. + - Інші адаптери цільових обв’язок усе ще можуть завантажуватися на вимогу через `npx` під час першого використання. + - Автентифікація постачальника для цієї обв’язки все одно має існувати на хості. + - Якщо хост не має npm або доступу до мережі, перше завантаження адаптерів завершується невдало, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. - ACP запускає реальний процес зовнішнього середовища. OpenClaw володіє маршрутизацією, - станом фонових задач, доставкою, прив’язками та політикою; середовище - володіє своїм входом до постачальника, каталогом моделей, поведінкою файлової системи та - нативними інструментами. + ACP запускає реальний процес зовнішньої обв’язки. OpenClaw відповідає за маршрутизацію, + стан фонових задач, доставку, прив’язки та політику; обв’язка + відповідає за свій вхід до постачальника, каталог моделей, поведінку файлової системи та + нативні інструменти. Перш ніж звинувачувати OpenClaw, перевірте: - - `/acp doctor` повідомляє про ввімкнений, справний бекенд. - - Цільовий id дозволено `acp.allowedAgents`, коли цей список дозволених задано. - - Команда середовища може запуститися на хості Gateway. - - Для цього середовища наявна авторизація постачальника (`claude`, `codex`, `gemini`, `opencode`, `droid` тощо). - - Вибрана модель існує для цього середовища — ідентифікатори моделей не переносяться між середовищами. - - Запитаний `cwd` існує та доступний, або пропустіть `cwd` і дозвольте бекенду використати стандартне значення. - - Режим дозволів відповідає роботі. Неінтерактивні сеанси не можуть натискати нативні запити дозволів, тому запуски кодування з інтенсивним записом/виконанням зазвичай потребують профілю дозволів ACPX, який може працювати без участі користувача. + - `/acp doctor` повідомляє про увімкнений і справний бекенд. + - Цільовий id дозволений `acp.allowedAgents`, коли цей allowlist задано. + - Команда обв’язки може запуститися на хості Gateway. + - Автентифікація постачальника наявна для цієї обв’язки (`claude`, `codex`, `gemini`, `opencode`, `droid` тощо). + - Вибрана модель існує для цієї обв’язки — id моделей не переносяться між обв’язками. + - Запитаний `cwd` існує і доступний, або пропустіть `cwd` і дозвольте бекенду використати його стандартне значення. + - Режим дозволів відповідає роботі. Неінтерактивні сеанси не можуть натискати нативні запити дозволів, тому кодингові запуски з великою кількістю запису/виконання зазвичай потребують профілю дозволів ACPX, який може працювати без участі користувача. Інструменти Plugin OpenClaw і вбудовані інструменти OpenClaw **не** відкриваються -для середовищ ACP за замовчуванням. Увімкніть явні мости MCP у -[Агенти ACP — налаштування](/uk/tools/acp-agents-setup) лише тоді, коли середовище -має викликати ці інструменти напряму. +обв’язкам ACP за замовчуванням. Увімкніть явні MCP-мости в +[Агенти ACP — налаштування](/uk/tools/acp-agents-setup) лише тоді, коли обв’язка +має викликати ці інструменти безпосередньо. -## Підтримувані цілі середовищ +## Підтримувані цільові обв’язки -З вбудованим бекендом `acpx` використовуйте ці id середовищ як цілі -`/acp spawn ` або `sessions_spawn({ runtime: "acp", agentId: "" })`: +З вбудованим бекендом `acpx` використовуйте ці id обв’язок як цілі `/acp spawn ` +або `sessions_spawn({ runtime: "acp", agentId: "" })`: -| Id середовища | Типовий бекенд | Примітки | -| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | -| `claude` | Адаптер Claude Code ACP | Потребує авторизації Claude Code на хості. | -| `codex` | Адаптер Codex ACP | Явний резервний ACP лише тоді, коли нативний `/codex` недоступний або запитано ACP. | -| `copilot` | Адаптер GitHub Copilot ACP | Потребує авторизації Copilot CLI/середовища виконання. | -| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Перевизначте команду acpx, якщо локальне встановлення надає іншу точку входу ACP. | -| `droid` | Factory Droid CLI | Потребує авторизації Factory/Droid або `FACTORY_API_KEY` у середовищі середовища. | -| `gemini` | Адаптер Gemini CLI ACP | Потребує авторизації Gemini CLI або налаштування ключа API. | -| `iflow` | iFlow CLI | Доступність адаптера й керування моделлю залежать від установленого CLI. | -| `kilocode` | Kilo Code CLI | Доступність адаптера й керування моделлю залежать від установленого CLI. | -| `kimi` | Kimi/Moonshot CLI | Потребує авторизації Kimi/Moonshot на хості. | -| `kiro` | Kiro CLI | Доступність адаптера й керування моделлю залежать від установленого CLI. | -| `opencode` | Адаптер OpenCode ACP | Потребує авторизації OpenCode CLI/постачальника. | -| `openclaw` | Міст OpenClaw Gateway через `openclaw acp` | Дає ACP-сумісному середовищу змогу відповідати сеансу OpenClaw Gateway. | -| `pi` | Pi/вбудоване середовище виконання OpenClaw | Використовується для експериментів із нативними для OpenClaw середовищами. | -| `qwen` | Qwen Code / Qwen CLI | Потребує Qwen-сумісної авторизації на хості. | +| Id обв’язки | Типовий бекенд | Примітки | +| ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | +| `claude` | Адаптер Claude Code ACP | Потребує автентифікації Claude Code на хості. | +| `codex` | Адаптер Codex ACP | Лише явний резервний ACP, коли нативний `/codex` недоступний або запитано ACP. | +| `copilot` | Адаптер GitHub Copilot ACP | Потребує автентифікації Copilot CLI/середовища виконання. | +| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Перевизначте команду acpx, якщо локальна інсталяція надає іншу точку входу ACP. | +| `droid` | Factory Droid CLI | Потребує автентифікації Factory/Droid або `FACTORY_API_KEY` у середовищі обв’язки. | +| `gemini` | Адаптер Gemini CLI ACP | Потребує автентифікації Gemini CLI або налаштування API-ключа. | +| `iflow` | iFlow CLI | Доступність адаптера та керування моделлю залежать від установленого CLI. | +| `kilocode` | Kilo Code CLI | Доступність адаптера та керування моделлю залежать від установленого CLI. | +| `kimi` | Kimi/Moonshot CLI | Потребує автентифікації Kimi/Moonshot на хості. | +| `kiro` | Kiro CLI | Доступність адаптера та керування моделлю залежать від установленого CLI. | +| `opencode` | Адаптер OpenCode ACP | Потребує автентифікації OpenCode CLI/постачальника. | +| `openclaw` | Міст OpenClaw Gateway через `openclaw acp` | Дає ACP-сумісній обв’язці змогу звертатися назад до сеансу OpenClaw Gateway. | +| `pi` | Pi/вбудоване середовище виконання OpenClaw | Використовується для експериментів із нативними для OpenClaw обв’язками. | +| `qwen` | Qwen Code / Qwen CLI | Потребує Qwen-сумісної автентифікації на хості. | Власні псевдоніми агентів acpx можна налаштувати в самому acpx, але політика OpenClaw усе одно перевіряє `acp.allowedAgents` і будь-яке зіставлення -`agents.list[].runtime.acp.agent` перед диспетчеризацією. +`agents.list[].runtime.acp.agent` перед dispatch. -## Runbook оператора +## Інструкція оператора Швидкий потік `/acp` із чату: - + `/acp spawn claude --bind here`, - `/acp spawn gemini --mode persistent --thread auto` або явно + `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here`. - - Продовжуйте у прив’язаній розмові або потоці (або явно вкажіть - ключ сеансу). + + Продовжуйте в прив’язаній розмові або гілці (або явно вкажіть ключ + сеансу як ціль). - + `/acp status` - + `/acp model `, `/acp permissions `, `/acp timeout `. - + Без заміни контексту: `/acp steer tighten logging and continue`. - + `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки). - - Створення створює або відновлює сеанс середовища виконання ACP, записує метадані ACP у сховище сеансів OpenClaw і може створити фонову задачу, коли запуск належить батьківському об’єкту. - - Прив’язані подальші повідомлення надходять безпосередньо до сеансу ACP, доки прив’язку не закрито, не знято з фокуса, не скинуто або доки вона не закінчиться. - - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного середовища ACP. + - Запуск створює або відновлює сеанс середовища виконання ACP, записує метадані ACP у сховище сеансів OpenClaw і може створити фонову задачу, коли запуск належить батьківській задачі. + - Сеанси ACP, що належать батьківській задачі, розглядаються як фонова робота, навіть коли сеанс середовища виконання є постійним; завершення та доставка між поверхнями проходять через сповіщувач батьківської задачі, а не поводяться як звичайний чат-сеанс для користувача. + - Обслуговування задач закриває термінальні одноразові сеанси ACP, що належать батьківській задачі. Постійні сеанси ACP зберігаються, доки залишається активна прив’язка розмови; застарілі постійні сеанси без активної прив’язки закриваються, щоб їх не можна було непомітно відновити після завершення задачі-власника. + - Прив’язані наступні повідомлення надходять безпосередньо до сеансу ACP, доки прив’язку не буде закрито, виведено з фокуса, скинуто або доки вона не спливе. + - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаної обв’язки ACP. - `cancel` перериває активний хід, коли бекенд підтримує скасування; він не видаляє прив’язку або метадані сеансу. - - `close` завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Середовище все ще може зберігати власну висхідну історію, якщо підтримує відновлення. - - Неактивні працівники середовища виконання можуть очищатися після `acp.runtime.ttlMinutes`; збережені метадані сеансу залишаються доступними для `/acp sessions`. + - `close` завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Обв’язка все ще може зберігати власну висхідну історію, якщо підтримує відновлення. + - Неактивні працівники середовища виконання можуть бути очищені після `acp.runtime.ttlMinutes`; збережені метадані сеансу залишаються доступними для `/acp sessions`. - + Тригери природною мовою, які мають маршрутизуватися до **нативного Plugin Codex**, - коли його ввімкнено: + коли його увімкнено: - "Прив’яжи цей канал Discord до Codex." - - "Приєднай цей чат до потоку Codex ``." - - "Покажи потоки Codex, а потім прив’яжи цей." + - "Приєднай цей чат до гілки Codex ``." + - "Покажи гілки Codex, потім прив’яжи цю." - Нативна прив’язка розмов Codex є стандартним шляхом керування чатом. + Нативна прив’язка розмови Codex є стандартним шляхом керування чатом. Динамічні інструменти OpenClaw усе ще виконуються через OpenClaw, тоді як - нативні інструменти Codex, такі як shell/apply-patch, виконуються всередині Codex. - Для подій нативних інструментів Codex OpenClaw вставляє нативний ретранслятор + нативні інструменти Codex, як-от shell/apply-patch, виконуються всередині Codex. + Для подій нативних інструментів Codex OpenClaw вставляє ретранслятор нативних hook для кожного ходу, щоб hook Plugin могли блокувати `before_tool_call`, спостерігати `after_tool_call` і маршрутизувати події Codex `PermissionRequest` через схвалення OpenClaw. Hook Codex `Stop` ретранслюються до OpenClaw `before_agent_finalize`, де Plugin можуть запросити ще один прохід моделі перед тим, як Codex фіналізує відповідь. Ретранслятор залишається навмисно консервативним: він не змінює аргументи нативних інструментів Codex - і не переписує записи потоків Codex. Використовуйте явний ACP лише - тоді, коли вам потрібна модель середовища виконання/сеансу ACP. Межу вбудованої підтримки Codex - задокументовано в - [контракті підтримки середовища Codex v1](/uk/plugins/codex-harness#v1-support-contract). + і не переписує записи гілок Codex. Використовуйте явний ACP лише тоді, + коли вам потрібна модель середовища виконання/сеансу ACP. Межа підтримки + вбудованого Codex задокументована в + [контракті підтримки обв’язки Codex v1](/uk/plugins/codex-harness#v1-support-contract). - + - `openai-codex/*` — маршрут PI Codex OAuth/підписки. - - `openai/*` плюс `agentRuntime.id: "codex"` — нативне вбудоване середовище виконання сервера застосунку Codex. - - `/codex ...` — нативне керування розмовою Codex. + - `openai/*` плюс `agentRuntime.id: "codex"` — вбудований runtime нативного сервера застосунку Codex. + - `/codex ...` — керування нативною розмовою Codex. - `/acp ...` або `runtime: "acp"` — явне керування ACP/acpx. - Тригери, які мають маршрутизуватися до середовища виконання ACP: + Тригери, які мають маршрутизуватися до runtime ACP: - "Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат." - - "Використай Gemini CLI для цього завдання в потоці, а потім залиш подальші повідомлення в тому самому потоці." - - "Запусти Codex через ACP у фоновому потоці." + - "Використай Gemini CLI для цього завдання в гілці, а потім тримай подальші відповіді в тій самій гілці." + - "Запусти Codex через ACP у фоновій гілці." OpenClaw вибирає `runtime: "acp"`, визначає harness `agentId`, - прив'язується до поточної розмови або потоку, коли це підтримується, і - маршрутизує подальші звернення до цього сеансу до закриття/завершення строку дії. Codex - йде цим шляхом лише тоді, коли ACP/acpx вказано явно або нативний Codex - plugin недоступний для запитаної операції. + прив’язується до поточної розмови або гілки, коли це підтримується, і + маршрутизує подальші відповіді до цього сеансу до закриття/завершення терміну дії. Codex + використовує цей шлях лише коли ACP/acpx вказано явно або нативний + plugin Codex недоступний для запитаної операції. - Для `sessions_spawn` `runtime: "acp"` оголошується лише тоді, коли ACP - увімкнено, запитувач не перебуває в sandbox, і завантажено backend runtime - ACP. `acp.dispatch.enabled=false` призупиняє автоматичну - диспетчеризацію потоків ACP, але не приховує й не блокує явні - виклики `sessions_spawn({ runtime: "acp" })`. Він націлюється на id harness ACP, як-от `codex`, + Для `sessions_spawn`, `runtime: "acp"` оголошується лише коли ACP + увімкнено, запитувач не ізольований у пісочниці, і backend runtime + ACP завантажено. `acp.dispatch.enabled=false` призупиняє автоматичну + диспетчеризацію гілок ACP, але не приховує і не блокує явні + виклики `sessions_spawn({ runtime: "acp" })`. Він націлюється на ідентифікатори harness ACP, як-от `codex`, `claude`, `droid`, `gemini` або `opencode`. Не передавайте звичайний - id агента конфігурації OpenClaw з `agents_list`, якщо цей запис не - налаштовано явно з `agents.list[].runtime.type="acp"`; - інакше використовуйте runtime субагента за замовчуванням. Коли агент OpenClaw + id агента конфігурації OpenClaw з `agents_list`, якщо цей запис + явно не налаштовано з `agents.list[].runtime.type="acp"`; + інакше використовуйте стандартний runtime підагента. Коли агент OpenClaw налаштований з `runtime.type="acp"`, OpenClaw використовує `runtime.acp.agent` як базовий id harness. -## ACP проти субагентів +## ACP порівняно з підагентами -Використовуйте ACP, коли потрібен зовнішній runtime harness. Використовуйте **нативний Codex -app-server** для прив'язування/керування розмовами Codex, коли `codex` -plugin увімкнено. Використовуйте **субагентів**, коли потрібні нативні для OpenClaw +Використовуйте ACP, коли потрібен зовнішній runtime harness. Використовуйте **нативний сервер застосунку Codex** +для прив’язування/керування розмовою Codex, коли plugin `codex` +увімкнено. Використовуйте **підагентів**, коли потрібні нативні для OpenClaw делеговані запуски. -| Область | Сеанс ACP | Запуск субагента | +| Область | Сеанс ACP | Запуск підагента | | ------------- | ------------------------------------- | ---------------------------------- | -| Runtime | ACP backend plugin (наприклад acpx) | Нативний runtime субагента OpenClaw | +| Runtime | Backend plugin ACP (наприклад acpx) | Нативний runtime підагента OpenClaw | | Ключ сеансу | `agent::acp:` | `agent::subagent:` | | Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) | +| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (стандартний runtime) | -Див. також [Субагенти](/uk/tools/subagents). +Див. також [Підагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code @@ -238,125 +240,125 @@ plugin увімкнено. Використовуйте **субагентів** 1. Площина керування сеансами ACP OpenClaw. 2. Вбудований runtime plugin `acpx`. -3. Адаптер ACP Claude. -4. Механізми runtime/сеансів на стороні Claude. +3. Адаптер Claude ACP. +4. Механізми runtime/сеансу на боці Claude. ACP Claude — це **сеанс harness** з елементами керування ACP, відновленням сеансу, -відстеженням фонових завдань і необов'язковим прив'язуванням розмови/потоку. +відстеженням фонових завдань і необов’язковим прив’язуванням розмови/гілки. -Backend CLI — це окремі текстові локальні резервні runtime — див. -[Backend CLI](/uk/gateway/cli-backends). +Backend-и CLI — це окремі локальні резервні runtime-и лише для тексту — див. +[Backend-и CLI](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- **Потрібні `/acp spawn`, сеанси з прив'язуванням, елементи керування runtime або тривала робота harness?** Використовуйте ACP. -- **Потрібен простий локальний текстовий резервний режим через сирий CLI?** Використовуйте backend CLI. +- **Потрібні `/acp spawn`, прив’язувані сеанси, елементи керування runtime або тривала робота harness?** Використовуйте ACP. +- **Потрібен простий локальний текстовий резерв через сирий CLI?** Використовуйте backend-и CLI. -## Прив'язані сеанси +## Прив’язані сеанси ### Ментальна модель -- **Поверхня чату** — місце, де люди продовжують спілкування (канал Discord, тема Telegram, чат iMessage). -- **Сеанс ACP** — довговічний стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw. -- **Дочірній потік/тема** — необов'язкова додаткова поверхня обміну повідомленнями, створена лише за допомогою `--thread ...`. -- **Робочий простір runtime** — розташування файлової системи (`cwd`, checkout репозиторію, робочий простір backend), де працює harness. Незалежний від поверхні чату. +- **Поверхня чату** — місце, де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage). +- **Сеанс ACP** — стійкий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw. +- **Дочірня гілка/тема** — необов’язкова додаткова поверхня повідомлень, створена лише через `--thread ...`. +- **Робочий простір runtime** — розташування файлової системи (`cwd`, checkout репозиторію, робочий простір backend), де запускається harness. Незалежне від поверхні чату. -### Прив'язування поточної розмови +### Прив’язки поточної розмови `/acp spawn --bind here` закріплює поточну розмову за -створеним сеансом ACP — без дочірнього потоку, та сама поверхня чату. OpenClaw продовжує -керувати транспортом, auth, безпекою та доставкою. Подальші повідомлення в цій +створеним сеансом ACP — без дочірньої гілки, та сама поверхня чату. OpenClaw продовжує +володіти транспортом, автентифікацією, безпекою та доставкою. Подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають -сеанс на місці; `/acp close` видаляє прив'язку. +сеанс на місці; `/acp close` видаляє прив’язку. Приклади: ```text -/codex bind # нативне прив'язування Codex, маршрутизувати майбутні повідомлення сюди -/codex model gpt-5.4 # налаштувати прив'язаний нативний потік Codex +/codex bind # нативна прив’язка Codex, маршрутизувати майбутні повідомлення сюди +/codex model gpt-5.4 # налаштувати прив’язану нативну гілку Codex /codex stop # керувати активним ходом нативного Codex -/acp spawn codex --bind here # явний резервний ACP для Codex -/acp spawn codex --thread auto # може створити дочірній потік/тему й прив'язати там -/acp spawn codex --bind here --cwd /workspace/repo # та сама прив'язка чату, Codex працює в /workspace/repo +/acp spawn codex --bind here # явний резерв ACP для Codex +/acp spawn codex --thread auto # може створити дочірню гілку/тему та прив’язати там +/acp spawn codex --bind here --cwd /workspace/repo # та сама прив’язка чату, Codex запускається в /workspace/repo ``` - + - `--bind here` і `--thread ...` взаємовиключні. - - `--bind here` працює лише на каналах, які оголошують прив'язування поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив'язки зберігаються після перезапусків gateway. - - У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній потік для `--thread auto|here` — не для `--bind here`. - - Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до типового значення backend; інші помилки доступу (наприклад, `EACCES`) відображаються як помилки запуску. - - Команди керування Gateway залишаються локальними у прив'язаних розмовах — команди `/acp ...` обробляються OpenClaw навіть тоді, коли звичайний текст подальших звернень маршрутизується до прив'язаного сеансу ACP; `/status` і `/unfocus` також залишаються локальними щоразу, коли обробку команд увімкнено для цієї поверхні. + - `--bind here` працює лише на каналах, які оголошують прив’язування поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язки зберігаються після перезапусків Gateway. + - У Discord `spawnAcpSessions` потрібен лише коли OpenClaw має створити дочірню гілку для `--thread auto|here` — не для `--bind here`. + - Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw типово успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) відступають до стандартного значення backend; інші помилки доступу (наприклад `EACCES`) показуються як помилки запуску. + - Команди керування Gateway залишаються локальними у прив’язаних розмовах — команди `/acp ...` обробляються OpenClaw навіть коли звичайний текст подальших повідомлень маршрутизується до прив’язаного сеансу ACP; `/status` і `/unfocus` також залишаються локальними, коли для цієї поверхні увімкнено обробку команд. - - Коли прив'язування потоків увімкнено для адаптера каналу: + + Коли прив’язки гілок увімкнено для адаптера каналу: - - OpenClaw прив'язує потік до цільового сеансу ACP. - - Подальші повідомлення в цьому потоці маршрутизуються до прив'язаного сеансу ACP. - - Вивід ACP доставляється назад у той самий потік. - - Unfocus/close/archive/idle-timeout або завершення строку дії max-age видаляє прив'язку. - - `/acp close`, `/acp cancel`, `/acp status`, `/status` і `/unfocus` — це команди Gateway, а не підказки до ACP harness. + - OpenClaw прив’язує гілку до цільового сеансу ACP. + - Подальші повідомлення в цій гілці маршрутизуються до прив’язаного сеансу ACP. + - Вивід ACP доставляється назад у ту саму гілку. + - Зняття фокуса/закриття/архівування/таймаут простою або завершення максимального віку видаляє прив’язку. + - `/acp close`, `/acp cancel`, `/acp status`, `/status` і `/unfocus` є командами Gateway, а не підказками до harness ACP. - Обов'язкові прапорці функцій для ACP, прив'язаного до потоку: + Обов’язкові прапорці функцій для ACP, прив’язаного до гілки: - `acp.enabled=true` - - `acp.dispatch.enabled` увімкнено за замовчуванням (установіть `false`, щоб призупинити автоматичну диспетчеризацію потоків ACP; явні виклики `sessions_spawn({ runtime: "acp" })` і надалі працюють). - - Увімкнений прапорець створення потоків ACP адаптера каналу (залежить від адаптера): + - `acp.dispatch.enabled` типово увімкнено (встановіть `false`, щоб призупинити автоматичну диспетчеризацію гілок ACP; явні виклики `sessions_spawn({ runtime: "acp" })` все ще працюють). + - Увімкнений прапорець запуску гілок ACP адаптера каналу (залежить від адаптера): - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` - Підтримка прив'язування потоків залежить від адаптера. Якщо активний адаптер - каналу не підтримує прив'язування потоків, OpenClaw повертає чітке + Підтримка прив’язування гілок залежить від адаптера. Якщо активний + адаптер каналу не підтримує прив’язки гілок, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. - - - Будь-який адаптер каналу, який надає можливість прив'язування сеансу/потоку. - - Поточна вбудована підтримка: потоки/канали **Discord**, теми **Telegram** (теми форуму в групах/супергрупах і теми DM). - - Канали Plugin можуть додати підтримку через той самий інтерфейс прив'язування. + + - Будь-який адаптер каналу, який надає можливість прив’язування сеансу/гілки. + - Поточна вбудована підтримка: гілки/канали **Discord**, теми **Telegram** (форумні теми в групах/супергрупах і теми DM). + - Plugin-канали можуть додати підтримку через той самий інтерфейс прив’язування. -## Постійні прив'язки каналів +## Постійні прив’язки каналів -Для неефемерних робочих процесів налаштуйте постійні прив'язки ACP у +Для неефемерних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. -### Модель прив'язування +### Модель прив’язування - Позначає постійну прив'язку розмови ACP. + Позначає постійну прив’язку розмови ACP. Ідентифікує цільову розмову. Форми за каналами: -- **Канал/потік 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:*` для стабільних прив'язок груп. +- **Канал/гілка 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:*` для стабільних групових прив’язок. Id агента-власника OpenClaw. - Необов'язкове перевизначення ACP. + Необов’язкове перевизначення ACP. - Необов'язкова мітка для оператора. + Необов’язкова мітка для оператора. - Необов'язковий робочий каталог runtime. + Необов’язковий робочий каталог runtime. - Необов'язкове перевизначення backend. + Необов’язкове перевизначення backend. -### Типові значення runtime для кожного агента +### Стандартні значення runtime для кожного агента -Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента: +Використовуйте `agents.list[].runtime`, щоб один раз визначити стандартні значення ACP для кожного агента: - `agents.list[].runtime.type="acp"` - `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`) @@ -364,11 +366,11 @@ Backend CLI — це окремі текстові локальні резерв - `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`) ### Приклад @@ -452,19 +454,19 @@ Backend CLI — це окремі текстові локальні резерв ### Поведінка -- OpenClaw гарантує, що налаштований сеанс ACP існує перед використанням. +- OpenClaw забезпечує існування налаштованого сеансу ACP перед використанням. - Повідомлення в цьому каналі або темі маршрутизуються до налаштованого сеансу ACP. -- У прив'язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. -- Тимчасові прив'язки runtime (наприклад, створені потоками thread-focus) і надалі застосовуються там, де вони наявні. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. +- Тимчасові прив’язки runtime (наприклад, створені потоками фокуса гілки) все ще застосовуються там, де вони присутні. - Для запусків ACP між агентами без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні успадковані шляхи робочого простору повертаються до типового cwd backend; невідсутні помилки доступу відображаються як помилки запуску. +- Відсутні успадковані шляхи робочого простору відступають до стандартного cwd backend; помилки доступу, не пов’язані з відсутністю, показуються як помилки запуску. ## Запуск сеансів ACP Два способи запустити сеанс ACP: - + Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP з ходу агента або виклику інструмента. @@ -479,10 +481,10 @@ Backend CLI — це окремі текстові локальні резерв ``` - `runtime` за замовчуванням має значення `subagent`, тому явно задайте `runtime: "acp"` - для сеансів ACP. Якщо `agentId` пропущено, OpenClaw використовує - `acp.defaultAgent`, коли його налаштовано. `mode: "session"` вимагає - `thread: true`, щоб зберегти постійну прив'язану розмову. + `runtime` за замовчуванням має значення `subagent`, тому для сеансів ACP явно задавайте + `runtime: "acp"`. Якщо `agentId` не вказано, OpenClaw використовує + `acp.defaultAgent`, якщо його налаштовано. `mode: "session"` потребує + `thread: true`, щоб зберегти постійну прив’язану розмову. @@ -512,167 +514,166 @@ Backend CLI — це окремі текстові локальні резерв ### Параметри `sessions_spawn` - Початковий запит, надісланий до сесії ACP. + Початковий prompt, надісланий до сеансу ACP. - Має бути `"acp"` для сесій ACP. + Має бути `"acp"` для сеансів ACP. - Ідентифікатор цільового середовища ACP. Повертається до `acp.defaultAgent`, якщо задано. + Ідентифікатор цільового ACP harness. Повертається до `acp.defaultAgent`, якщо його задано. - Запитує потік прив’язування до треду, де це підтримується. + Запитує потік прив’язування гілки, де це підтримується. - `"run"` — одноразовий режим; `"session"` — постійний. Якщо `thread: true` і - `mode` опущено, OpenClaw може за замовчуванням використовувати постійну поведінку відповідно до + `"run"` є одноразовим; `"session"` є постійним. Якщо `thread: true` і + `mode` пропущено, OpenClaw може за замовчуванням перейти до постійної поведінки відповідно до шляху runtime. `mode: "session"` потребує `thread: true`. Запитаний робочий каталог runtime (перевіряється політикою backend/runtime). - Якщо опущено, запуск ACP успадковує робочий простір цільового агента, - коли це налаштовано; відсутні успадковані шляхи повертаються до стандартних + Якщо його пропущено, ACP spawn успадковує робочу область цільового агента, + коли її налаштовано; відсутні успадковані шляхи повертаються до стандартних значень backend, тоді як реальні помилки доступу повертаються. - Мітка для оператора, що використовується в тексті сесії/банера. + Мітка для оператора, що використовується в тексті сеансу/банера. - Відновлює наявну сесію ACP замість створення нової. Агент - відтворює історію своєї розмови через `session/load`. Потребує - `runtime: "acp"`. + Відновлює наявний сеанс ACP замість створення нового. Агент відтворює + історію своєї розмови через `session/load`. Потребує `runtime: "acp"`. - `"parent"` транслює початкові підсумки перебігу запуску ACP назад до - сесії-запитувача як системні події. Прийняті відповіді містять - `streamLogPath`, що вказує на JSONL-журнал у межах сесії - (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. + `"parent"` транслює початкові підсумки перебігу ACP run назад до + сеансу-запитувача як системні події. Прийняті відповіді містять + `streamLogPath`, що вказує на scoped для сеансу JSONL-журнал + (`.acp-stream.jsonl`), який можна відстежувати для повної історії relay. - Перериває дочірній хід ACP після N секунд. `0` утримує хід на - шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску - Gateway і runtime ACP, щоб завислі середовища або середовища з вичерпаною квотою не - займали смугу батьківського агента безстроково. + Перериває дочірній хід ACP через N секунд. `0` залишає хід на шляху + Gateway без timeout. Те саме значення застосовується до запуску Gateway + і ACP runtime, щоб harness, які зависли або вичерпали квоту, не + займали lane батьківського агента безкінечно. - Явне перевизначення моделі для дочірньої сесії ACP. Запуски Codex ACP - нормалізують посилання OpenClaw Codex, як-от `openai-codex/gpt-5.4`, у стартову - конфігурацію Codex ACP перед `session/new`; форми зі слешем, як-от - `openai-codex/gpt-5.4/high`, також задають зусилля reasoning Codex ACP. - Інші середовища мають оголошувати ACP `models` і підтримувати + Явне перевизначення моделі для дочірнього сеансу ACP. Codex ACP spawns + нормалізують посилання OpenClaw Codex, як-от `openai-codex/gpt-5.4`, у startup config Codex + ACP перед `session/new`; slash-форми, як-от + `openai-codex/gpt-5.4/high`, також задають reasoning effort Codex ACP. + Інші harness мають оголошувати ACP `models` і підтримувати `session/set_model`; інакше OpenClaw/acpx завершується з чіткою помилкою, а не - непомітно повертається до стандартного цільового агента. + мовчки повертається до стандартного агента цілі. Явне зусилля thinking/reasoning. Для Codex ACP `minimal` відповідає низькому зусиллю, `low`/`medium`/`high`/`xhigh` відповідають напряму, а `off` - пропускає стартове перевизначення reasoning-effort. + пропускає startup-перевизначення reasoning-effort. -## Режими прив’язування запуску й тредів +## Режими spawn bind і thread - | Режим | Поведінка | + | Режим | Поведінка | | ------ | ---------------------------------------------------------------------- | - | `here` | Прив’язати поточну активну розмову на місці; помилка, якщо активної немає. | + | `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної немає. | | `off` | Не створювати прив’язування поточної розмови. | Примітки: - - `--bind here` — найпростіший шлях оператора для «зробити цей канал або чат підтриманим Codex». - - `--bind here` не створює дочірній тред. - - `--bind here` доступний лише на каналах, які надають підтримку прив’язування поточної розмови. + - `--bind here` — найпростіший шлях оператора для "зробити цей канал або чат підтримуваним Codex." + - `--bind here` не створює дочірню гілку. + - `--bind here` доступний лише в каналах, які надають підтримку прив’язування поточної розмови. - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`. - | Режим | Поведінка | + | Режим | Поведінка | | ------ | --------------------------------------------------------------------------------------------------- | - | `auto` | В активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо підтримується. | - | `here` | Вимагати поточний активний тред; помилка, якщо ви не в ньому. | - | `off` | Без прив’язування. Сесія запускається неприв’язаною. | + | `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо підтримується. | + | `here` | Вимагати поточну активну гілку; завершитися помилкою, якщо ви не в ній. | + | `off` | Без прив’язування. Сеанс запускається неприв’язаним. | Примітки: - - На поверхнях без прив’язування тредів стандартна поведінка фактично є `off`. - - Запуск, прив’язаний до треду, потребує підтримки політики каналу: + - На поверхнях без прив’язування гілок стандартна поведінка фактично є `off`. + - Spawn із прив’язуванням до гілки потребує підтримки політики каналу: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` - - Використовуйте `--bind here`, коли потрібно закріпити поточну розмову без створення дочірнього треду. + - Використовуйте `--bind here`, коли потрібно закріпити поточну розмову без створення дочірньої гілки. ## Модель доставки -Сесії ACP можуть бути або інтерактивними робочими просторами, або фоновою -роботою, що належить батьківській сесії. Шлях доставки залежить від цієї форми. +Сеанси ACP можуть бути або інтерактивними робочими областями, або фоновою +роботою, що належить батьківському сеансу. Шлях доставки залежить від цієї форми. - - Інтерактивні сесії призначені для продовження розмови на видимій + + Інтерактивні сеанси призначені для продовження розмови на видимій поверхні чату: - - `/acp spawn ... --bind here` прив’язує поточну розмову до сесії ACP. - - `/acp spawn ... --thread ...` прив’язує тред/тему каналу до сесії ACP. - - Постійні налаштовані `bindings[].type="acp"` спрямовують відповідні розмови до тієї самої сесії ACP. + - `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP. + - `/acp spawn ... --thread ...` прив’язує гілку/тему каналу до сеансу ACP. + - Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP. - Подальші повідомлення у прив’язаній розмові спрямовуються безпосередньо до - сесії ACP, а вивід ACP доставляється назад у той самий - канал/тред/тему. + Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до + сеансу ACP, а вивід ACP доставляється назад у той самий + канал/гілку/тему. - Що OpenClaw надсилає до середовища: + Що OpenClaw надсилає до harness: - - Звичайні прив’язані подальші повідомлення надсилаються як текст запиту, плюс вкладення лише тоді, коли середовище/backend їх підтримує. - - Команди керування `/acp` і локальні команди Gateway перехоплюються перед відправленням до ACP. - - Події завершення, згенеровані runtime, матеріалізуються для кожної цілі. Агенти OpenClaw отримують внутрішній runtime-context-конверт OpenClaw; зовнішні середовища ACP отримують простий запит із дочірнім результатом та інструкцією. Необроблений конверт `<<>>` ніколи не слід надсилати зовнішнім середовищам або зберігати як текст користувацької стенограми ACP. - - Записи стенограми ACP використовують видимий користувачу текст тригера або простий запит завершення. Внутрішні метадані подій, де можливо, залишаються структурованими в OpenClaw і не трактуються як вміст чату, написаний користувачем. + - Звичайні прив’язані подальші повідомлення надсилаються як текст prompt, а вкладення додаються лише тоді, коли harness/backend їх підтримує. + - Керівні команди `/acp` і локальні команди Gateway перехоплюються перед dispatch ACP. + - Події завершення, згенеровані runtime, матеріалізуються для кожної цілі. Агенти OpenClaw отримують внутрішній runtime-context envelope OpenClaw; зовнішні ACP harness отримують звичайний prompt із дочірнім результатом та інструкцією. Сирий envelope `<<>>` ніколи не має надсилатися до зовнішніх harness або зберігатися як текст transcript користувача ACP. + - Записи transcript ACP використовують видимий для користувача текст тригера або звичайний prompt завершення. Внутрішні метадані подій залишаються структурованими в OpenClaw, де це можливо, і не трактуються як вміст чату, написаний користувачем. - - Одноразові сесії ACP, запущені іншим агентом, є фоновими - дочірніми задачами, подібними до під-агентів: + + Одноразові сеанси ACP, породжені іншим запуском агента, є фоновими + дочірніми сеансами, подібними до sub-agents: - - Батьківська сесія запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. - - Дочірня сесія виконується у власній сесії середовища ACP. - - Дочірні ходи виконуються на тій самій фоновій смузі, що використовується нативними запусками під-агентів, тому повільне середовище ACP не блокує непов’язану роботу основної сесії. - - Звіт про завершення повертається через шлях оголошення завершення задачі. OpenClaw перетворює внутрішні метадані завершення на простий запит ACP перед надсиланням його до зовнішнього середовища, щоб середовища не бачили runtime-контекстні маркери, призначені лише для OpenClaw. - - Батьківська сесія переписує дочірній результат звичайним голосом асистента, коли корисна відповідь для користувача. + - Батьківський сеанс запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. + - Дочірній сеанс запускається у власному сеансі ACP harness. + - Дочірні ходи виконуються на тому самому фоновому lane, який використовується нативними sub-agent spawns, тому повільний ACP harness не блокує непов’язану роботу main-session. + - Звіт про завершення повертається через шлях оголошення про завершення завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний ACP prompt перед надсиланням до зовнішнього harness, тому harness не бачать markers runtime context, призначених лише для OpenClaw. + - Батьківський сеанс переписує дочірній результат звичайним голосом assistant, коли корисна відповідь для користувача. - **Не** трактуйте цей шлях як peer-to-peer-чат між батьківською - і дочірньою сесіями. Дочірня сесія вже має канал завершення назад до - батьківської. + **Не** трактуйте цей шлях як peer-to-peer чат між батьківським і + дочірнім сеансами. Дочірній сеанс уже має канал завершення назад до + батьківського. - - `sessions_send` може цілитися в іншу сесію після запуску. Для звичайних - peer-сесій OpenClaw використовує шлях подальших повідомлень agent-to-agent (A2A) - після ін’єкції повідомлення: + + `sessions_send` може націлюватися на інший сеанс після spawn. Для звичайних + peer-сеансів OpenClaw використовує шлях agent-to-agent (A2A) для подальших повідомлень + після вставлення повідомлення: - - Дочекатися відповіді цільової сесії. + - Дочекатися відповіді цільового сеансу. - За потреби дозволити запитувачу й цілі обмінятися обмеженою кількістю подальших ходів. - Попросити ціль створити повідомлення-оголошення. - - Доставити це оголошення у видимий канал або тред. + - Доставити це оголошення у видимий канал або гілку. - Цей шлях A2A є резервним для peer-надсилань, де відправнику потрібне - видиме подальше повідомлення. Він залишається ввімкненим, коли непов’язана сесія може - бачити й писати ACP-цілі, наприклад за широких + Цей шлях A2A є fallback для peer sends, де відправнику потрібне + видиме подальше повідомлення. Він лишається ввімкненим, коли непов’язаний сеанс може + бачити ACP target і надсилати йому повідомлення, наприклад за широких налаштувань `tools.sessions.visibility`. - OpenClaw пропускає подальший хід A2A лише тоді, коли запитувач є - батьківською сесією власної одноразової дочірньої ACP-сесії, що належить їй. У цьому разі - запуск A2A поверх завершення задачі може розбудити батьківську сесію - результатом дочірньої, переслати відповідь батьківської назад до дочірньої та - створити цикл відлуння батьківська/дочірня. Результат `sessions_send` повідомляє - `delivery.status="skipped"` для цього випадку дочірньої сесії, що належить батьківській, оскільки - шлях завершення вже відповідає за результат. + OpenClaw пропускає A2A follow-up лише тоді, коли запитувач є + батьківським сеансом власного одноразового дочірнього ACP, що належить батьківському сеансу. У цьому випадку + запуск A2A поверх task completion може розбудити батьківський сеанс із + результатом дочірнього, переслати відповідь батьківського назад у дочірній і + створити echo loop між батьківським і дочірнім. Результат `sessions_send` повідомляє + `delivery.status="skipped"` для цього випадку owned-child, оскільки + completion path уже відповідає за результат. - - Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість - початку з нуля. Агент відтворює історію своєї розмови через - `session/load`, тож продовжує з повним контекстом того, що було раніше. + + Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість + запуску з нуля. Агент відтворює історію своєї розмови через + `session/load`, тому продовжує з повним контекстом того, що було раніше. ```json { @@ -683,158 +684,160 @@ Backend CLI — це окремі текстові локальні резерв } ``` - Типові випадки використання: + Поширені сценарії використання: - - Передати сесію Codex з ноутбука на телефон — скажіть агенту продовжити з місця, де ви зупинилися. - - Продовжити сесію кодування, яку ви почали інтерактивно в CLI, тепер безголово через свого агента. - - Продовжити роботу, перервану перезапуском gateway або тайм-аутом простою. + - Передайте сеанс Codex із ноутбука на телефон — скажіть агенту продовжити з місця, де ви зупинилися. + - Продовжте сеанс програмування, який ви почали інтерактивно в CLI, тепер headlessly через свого агента. + - Поновіть роботу, перервану перезапуском gateway або idle timeout. Примітки: - - `resumeSessionId` застосовується лише коли `runtime: "acp"`; стандартний runtime під-агента ігнорує це поле, призначене лише для ACP. - - `streamTo` застосовується лише коли `runtime: "acp"`; стандартний runtime під-агента ігнорує це поле, призначене лише для ACP. - - `resumeSessionId` — це локальний для хоста ACP/harness resume id, а не ключ сесії каналу OpenClaw; OpenClaw усе ще перевіряє політику запуску ACP і політику цільового агента перед відправленням, тоді як ACP backend або середовище відповідає за авторизацію завантаження цього upstream id. - - `resumeSessionId` відновлює історію upstream-розмови ACP; `thread` і `mode` усе ще застосовуються звичайно до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` усе ще потребує `thread: true`. + - `resumeSessionId` застосовується лише коли `runtime: "acp"`; стандартний sub-agent runtime ігнорує це ACP-only поле. + - `streamTo` застосовується лише коли `runtime: "acp"`; стандартний sub-agent runtime ігнорує це ACP-only поле. + - `resumeSessionId` — це host-local ACP/harness resume id, а не ключ сеансу каналу OpenClaw; OpenClaw усе ще перевіряє політику ACP spawn і політику цільового агента перед dispatch, тоді як ACP backend або harness відповідає за авторизацію для завантаження цього upstream id. + - `resumeSessionId` відновлює історію upstream ACP conversation; `thread` і `mode` усе ще застосовуються звичайно до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще потребує `thread: true`. - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). - - Якщо ідентифікатор сесії не знайдено, запуск завершується чіткою помилкою — без непомітного повернення до нової сесії. + - Якщо ідентифікатор сеансу не знайдено, spawn завершується чіткою помилкою — без мовчазного fallback до нового сеансу. - - Після розгортання gateway запустіть живу end-to-end-перевірку, а не - покладайтеся на модульні тести: + + Після розгортання gateway запустіть live end-to-end перевірку, а не + покладайтеся на unit tests: - 1. Перевірте розгорнуту версію gateway і коміт на цільовому хості. - 2. Відкрийте тимчасову сесію мосту ACPX до живого агента. - 3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і задачею `Reply with exactly LIVE-ACP-SPAWN-OK`. - 4. Перевірте `accepted=yes`, реальний `childSessionKey` і відсутність помилки валідатора. - 5. Очистьте тимчасову сесію мосту. + 1. Перевірте розгорнуту версію gateway і commit на цільовому host. + 2. Відкрийте тимчасовий сеанс ACPX bridge до live agent. + 3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`. + 4. Перевірте `accepted=yes`, реальний `childSessionKey` і відсутність validator error. + 5. Приберіть тимчасовий сеанс bridge. Тримайте gate на `mode: "run"` і пропустіть `streamTo: "parent"` — - прив’язаний до треду `mode: "session"` і шляхи stream-relay є окремими - багатшими інтеграційними проходами. + thread-bound `mode: "session"` і stream-relay paths є окремими + багатшими integration passes. ## Сумісність із sandbox -Сесії ACP наразі виконуються на runtime хоста, **не** всередині -sandbox OpenClaw. +Сеанси ACP зараз виконуються на host runtime, **не** всередині +OpenClaw sandbox. **Межа безпеки:** -- Зовнішнє середовище може читати/писати відповідно до власних дозволів CLI і вибраного `cwd`. -- Політика sandbox OpenClaw **не** обгортає виконання середовища ACP. -- OpenClaw усе ще застосовує feature gates ACP, дозволених агентів, належність сесій, прив’язування каналів і політику доставки Gateway. -- Використовуйте `runtime: "subagent"` для нативної роботи OpenClaw із примусовим sandbox. +- Зовнішній інструмент виконання може читати/записувати відповідно до власних дозволів CLI і вибраного `cwd`. +- Політика пісочниці OpenClaw **не** обгортає виконання інструмента ACP. +- OpenClaw усе одно застосовує обмеження функцій ACP, дозволених агентів, володіння сеансами, прив’язки каналів і політику доставки Gateway. +- Використовуйте `runtime: "subagent"` для нативної роботи OpenClaw із примусовим застосуванням пісочниці. Поточні обмеження: -- Якщо сесія-запитувач перебуває в sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. +- Якщо сеанс запитувача перебуває в пісочниці, створення ACP заблоковано як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. - `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`. -## Визначення цілі сесії +## Визначення цільового сеансу -Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, +Більшість дій `/acp` приймають необов’язковий цільовий сеанс (`session-key`, `session-id` або `session-label`). **Порядок визначення:** 1. Явний аргумент цілі (або `--session` для `/acp steer`) - - спочатку пробує ключ - - потім UUID-подібний ідентифікатор сесії + - пробує ключ + - потім ідентифікатор сеансу у форматі UUID - потім мітку -2. Прив’язування поточного треду (якщо ця розмова/тред прив’язані до сесії ACP). -3. Резервна сесія поточного запитувача. +2. Прив’язка поточного ланцюжка (якщо ця розмова/ланцюжок прив’язана до сеансу ACP). +3. Резервний варіант із поточним сеансом запитувача. -Поточні прив’язки розмови та прив’язки потоку обидві беруть участь у +Прив’язки поточної розмови й прив’язки ланцюжка обидві беруть участь у кроці 2. -Якщо ціль не вдається визначити, OpenClaw повертає зрозумілу помилку +Якщо ціль не визначено, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`). -## Керування ACP +## Засоби керування ACP -| Команда | Що робить | Приклад | +| Команда | Що робить | Приклад | | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка потоку. | `/acp spawn codex --bind here --cwd /repo` | +| `/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 steer` | Надсилає керівну інструкцію до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Закриває сеанс і відв’язує цілі ланцюжка. | `/acp close` | +| `/acp status` | Показує бекенд, режим, стан, параметри runtime, можливості. | `/acp status` | +| `/acp set-mode` | Задає режим runtime для цільового сеансу. | `/acp set-mode plan` | +| `/acp set` | Записує загальний параметр конфігурації runtime. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Задає перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Задає профіль політики схвалення. | `/acp permissions strict` | +| `/acp timeout` | Задає тайм-аут runtime (секунди). | `/acp timeout 120` | +| `/acp model` | Задає перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Видаляє перевизначення параметрів runtime сеансу. | `/acp reset-options` | | `/acp sessions` | Перелічує нещодавні сеанси ACP зі сховища. | `/acp sessions` | -| `/acp doctor` | Перевіряє справність бекенда, можливості та практичні виправлення. | `/acp doctor` | -| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` | +| `/acp doctor` | Стан бекенду, можливості, практичні виправлення. | `/acp doctor` | +| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` | -`/acp status` показує ефективні параметри середовища виконання, а також ідентифікатори сеансу рівня середовища виконання та рівня бекенда. Помилки непідтримуваного керування відображаються -зрозуміло, коли бекенд не має відповідної можливості. `/acp sessions` читає +`/acp status` показує ефективні параметри runtime, а також ідентифікатори сеансів рівня runtime і +рівня бекенду. Помилки непідтримуваних засобів керування відображаються +чітко, коли бекенд не має відповідної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через -виявлення сеансів Gateway, включно з власними коренями `session.store` для кожного агента. +виявлення сеансів gateway, включно з користувацькими коренями `session.store` +для кожного агента. -### Відповідність параметрів середовища виконання +### Відображення параметрів runtime -`/acp` має зручні команди та загальний сеттер. Еквівалентні +`/acp` має зручні команди й загальний сеттер. Еквівалентні операції: -| Команда | Відповідає | Примітки | -| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/acp model ` | ключ конфігурації середовища виконання `model` | Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора моделі адаптера та відображає суфікси міркування зі слешем, як-от `openai-codex/gpt-5.4/high`, у `reasoning_effort`. | -| `/acp set thinking ` | ключ конфігурації середовища виконання `thinking` | Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер його підтримує. | -| `/acp permissions ` | ключ конфігурації середовища виконання `approval_policy` | — | -| `/acp timeout ` | ключ конфігурації середовища виконання `timeout` | — | -| `/acp cwd ` | перевизначення cwd середовища виконання | Пряме оновлення. | -| `/acp set ` | загальний параметр | `key=cwd` використовує шлях перевизначення cwd. | -| `/acp reset-options` | очищає всі перевизначення середовища виконання | — | +| Команда | Відображається на | Примітки | +| ---------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/acp model ` | ключ конфігурації runtime `model` | Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора моделі адаптера й відображає суфікси reasoning зі скісною рискою, як-от `openai-codex/gpt-5.4/high`, на `reasoning_effort`. | +| `/acp set thinking ` | ключ конфігурації runtime `thinking` | Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер його підтримує. | +| `/acp permissions ` | ключ конфігурації runtime `approval_policy` | — | +| `/acp timeout ` | ключ конфігурації runtime `timeout` | — | +| `/acp cwd ` | перевизначення cwd runtime | Пряме оновлення. | +| `/acp set ` | загальне | `key=cwd` використовує шлях перевизначення cwd. | +| `/acp reset-options` | очищає всі перевизначення runtime | — | -## Тестовий стенд acpx, налаштування Plugin і дозволи +## Інструмент acpx, налаштування Plugin і дозволи -Конфігурацію тестового стенда acpx (псевдоніми Claude Code / Codex / Gemini CLI), MCP-мости plugin-tools і OpenClaw-tools, а також режими дозволів ACP див. у -[агенти ACP — налаштування](/uk/tools/acp-agents-setup). +Для конфігурації інструмента acpx (псевдоніми Claude Code / Codex / Gemini CLI), мостів MCP plugin-tools і OpenClaw-tools, а також режимів дозволів ACP див. +[Агенти ACP — налаштування](/uk/tools/acp-agents-setup). ## Усунення несправностей | Симптом | Ймовірна причина | Виправлення | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ACP runtime backend is not configured` | Backend Plugin відсутній, вимкнений або заблокований через `plugins.allow`. | Установіть і ввімкніть Backend Plugin, додайте `acpx` до `plugins.allow`, якщо цей список дозволів налаштовано, а потім виконайте `/acp doctor`. | +| `ACP runtime backend is not configured` | Backend Plugin відсутній, вимкнений або заблокований `plugins.allow`. | Установіть і ввімкніть backend Plugin, додайте `acpx` до `plugins.allow`, коли цей список дозволів задано, потім виконайте `/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`, щоб відновити автоматичну маршрутизацію гілок; явні виклики `sessions_spawn({ runtime: "acp" })` і далі працюють. | -| `ACP agent "" is not allowed by policy` | Агента немає у списку дозволених. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. | -| `/acp doctor` reports backend not ready right after startup | Перевірка залежностей Plugin або самовідновлення ще виконується. | Трохи зачекайте й повторно виконайте `/acp doctor`; якщо стан лишається несправним, перевірте помилку встановлення бекенда та політику дозволу/заборони Plugin. | -| Команду harness не знайдено | CLI адаптера не встановлено, відсутні підготовлені залежності Plugin або перше завантаження `npx` не вдалося для адаптера не-Codex. | Виконайте `/acp doctor`, відновіть залежності Plugin, установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx. | -| Модель не знайдено від harness | Ідентифікатор моделі дійсний для іншого провайдера/harness, але не для цієї цілі ACP. | Використайте модель зі списку цього harness, налаштуйте модель у harness або пропустіть перевизначення. | -| Помилка автентифікації постачальника від harness | OpenClaw справний, але цільовий CLI/провайдер не авторизований. | Увійдіть або надайте потрібний ключ провайдера в середовищі хоста Gateway. | -| `Unable to resolve session target: ...` | Неправильний ключ/ідентифікатор/токен мітки. | Виконайте `/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 працює на боці хоста; сесію запитувача ізольовано в пісочниці. | Використовуйте `runtime="subagent"` із сесій у пісочниці або запускайте ACP spawn із сесії без пісочниці. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової пісочниці або ACP із `sandbox="inherit"` із сесії без пісочниці. | -| `Cannot apply --model ... did not advertise model support` | Цільовий harness не надає загального перемикання моделей ACP. | Використайте harness, який оголошує ACP `models`/`session/set_model`, використайте посилання моделей Codex ACP або налаштуйте модель безпосередньо в harness, якщо він має власний прапорець запуску. | -| Відсутні метадані ACP для прив’язаної сесії | Застарілі/видалені метадані сесії ACP. | Створіть заново через `/acp spawn`, потім повторно прив’яжіть/сфокусуйте гілку. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує записи/виконання в неінтерактивній сесії ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть Gateway. Див. [Конфігурація дозволів](/uk/tools/acp-agents-setup#permission-configuration). | -| Сесія ACP швидко завершується з малим обсягом виводу | Запити дозволів заблоковано через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали Gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для м’якої деградації встановіть `nonInteractivePermissions=deny`. | -| Сесія ACP зависає на невизначений час після завершення роботи | Процес harness завершився, але сесія ACP не повідомила про завершення. | Стежте за допомогою `ps aux \| grep acpx`; застарілі процеси завершуйте вручну. | -| Harness бачить `<<>>` | Внутрішній конверт подій просочився через межу ACP. | Оновіть OpenClaw і повторно виконайте потік завершення; зовнішні harness мають отримувати лише звичайні запити завершення. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Автоматичне диспетчеризування зі звичайних повідомлень потоку вимкнено. | Установіть `acp.dispatch.enabled=true`, щоб відновити автоматичну маршрутизацію потоків; явні виклики `sessions_spawn({ runtime: "acp" })` і далі працюють. | +| `ACP agent "" is not allowed by policy` | Агента немає у списку дозволів. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. | +| `/acp doctor` reports backend not ready right after startup | Перевірка залежностей Plugin або самовідновлення ще виконується. | Трохи зачекайте й повторно виконайте `/acp doctor`; якщо стан лишається несправним, перевірте помилку встановлення backend і політику дозволу/заборони Plugin. | +| Harness command not found | Adapter CLI не встановлено, залежності проміжного Plugin відсутні або перше завантаження через `npx` не вдалося для адаптера не Codex. | Виконайте `/acp doctor`, відновіть залежності Plugin, установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx. | +| Model-not-found from the harness | Ідентифікатор моделі дійсний для іншого провайдера/harness, але не для цієї цілі ACP. | Використайте модель зі списку цього harness, налаштуйте модель у harness або пропустіть перевизначення. | +| Vendor auth error from the harness | OpenClaw справний, але цільовий CLI/провайдер не авторизований. | Увійдіть або надайте потрібний ключ провайдера в середовищі хоста Gateway. | +| `Unable to resolve session target: ...` | Некоректний токен ключа/ідентифікатора/мітки. | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної прив'язуваної розмови. | Перейдіть до цільового чату/каналу й повторіть спробу або використайте створення без прив'язки. | +| `Conversation bindings are unavailable for .` | Adapter не має можливості 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 .` | Adapter не має можливості прив'язки потоку. | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на боці хоста; сеанс запитувача ізольований у sandbox. | Використайте `runtime="subagent"` із sandbox-сеансів або запустіть створення ACP із неізольованого сеансу. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` запитано для середовища виконання ACP. | Використайте `runtime="subagent"` для обов'язкової ізоляції або використайте ACP з `sandbox="inherit"` із неізольованого сеансу. | +| `Cannot apply --model ... did not advertise model support` | Цільовий harness не надає загального перемикання моделей ACP. | Використайте harness, який оголошує ACP `models`/`session/set_model`, використайте посилання на моделі Codex ACP або налаштуйте модель безпосередньо в harness, якщо він має власний прапорець запуску. | +| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, потім повторно прив'яжіть/сфокусуйте потік. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує записи/виконання в неінтерактивному сеансі ACP. | Установіть `plugins.entries.acpx.config.permissionMode` на `approve-all` і перезапустіть gateway. Див. [Налаштування дозволів](/uk/tools/acp-agents-setup#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`; вручну завершіть застарілі процеси. | +| Harness sees `<<>>` | Внутрішній конверт події просочився через межу ACP. | Оновіть OpenClaw і повторно виконайте потік завершення; зовнішні harness мають отримувати лише звичайні запити завершення. | -## Пов’язане +## Пов'язане - [Агенти ACP — налаштування](/uk/tools/acp-agents-setup) - [Надсилання агенту](/uk/tools/agent-send) -- [CLI бекенди](/uk/gateway/cli-backends) -- [Codex harness](/uk/plugins/codex-harness) -- [Інструменти пісочниці для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- [`openclaw acp` (режим мосту)](/uk/cli/acp) -- [Підагентів](/uk/tools/subagents) +- [Backend CLI](/uk/gateway/cli-backends) +- [Harness Codex](/uk/plugins/codex-harness) +- [Інструменти sandbox для кількох агентів](/uk/tools/multi-agent-sandbox-tools) +- [`openclaw acp` (режим bridge)](/uk/cli/acp) +- [Субагенти](/uk/tools/subagents)