diff --git a/docs/uk/plugins/hooks.md b/docs/uk/plugins/hooks.md index c9773004f..f501e09b7 100644 --- a/docs/uk/plugins/hooks.md +++ b/docs/uk/plugins/hooks.md @@ -1,30 +1,30 @@ --- read_when: - - Ви створюєте Plugin, якому потрібні хуки before_tool_call, before_agent_reply, хуки повідомлень або хуки життєвого циклу + - Ви створюєте Plugin, якому потрібні before_tool_call, before_agent_reply, хуки повідомлень або хуки життєвого циклу - Потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів від Plugin - Ви обираєте між внутрішніми хуками та хуками Plugin summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сеансу та Gateway' title: Хуки Plugin x-i18n: - generated_at: "2026-05-03T19:29:25Z" + generated_at: "2026-05-04T14:09:11Z" model: gpt-5.5 provider: openai - source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591 + source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b source_path: plugins/hooks.md workflow: 16 --- -Plugin-хуки — це внутрішньопроцесні точки розширення для плагінів OpenClaw. Використовуйте їх, +Хуки Plugin — це внутрішньопроцесні точки розширення для плагінів OpenClaw. Використовуйте їх, коли плагіну потрібно перевіряти або змінювати запуски агентів, виклики інструментів, потік повідомлень, -життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway. +життєвий цикл сесій, маршрутизацію субагентів, встановлення або запуск Gateway. -Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли потрібен невеликий -встановлений оператором скрипт `HOOK.md` для подій команд і Gateway, як-от +Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий +встановлений оператором скрипт `HOOK.md` для подій команд і Gateway, таких як `/new`, `/reset`, `/stop`, `agent:bootstrap` або `gateway:startup`. ## Швидкий старт -Зареєструйте типізовані Plugin-хуки за допомогою `api.on(...)` з точки входу вашого плагіна: +Реєструйте типізовані хуки плагіна за допомогою `api.on(...)` з точки входу вашого плагіна: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -56,19 +56,19 @@ export default definePluginEntry({ }); ``` -Обробники хуків виконуються послідовно за спаданням `priority`. Хуки з однаковим пріоритетом +Обробники хуків виконуються послідовно в порядку спадання `priority`. Хуки з однаковим пріоритетом зберігають порядок реєстрації. `api.on(name, handler, opts?)` приймає: - `priority` — порядок обробників (вищий виконується першим). -- `timeoutMs` — необов'язковий бюджет для окремого хука. Якщо задано, runner хуків перериває цей +- `timeoutMs` — необов’язковий бюджет для окремого хука. Якщо його задано, runner хука перериває цей обробник після вичерпання бюджету й переходить до наступного, замість того щоб - дозволити повільному налаштуванню або відновленню з пам'яті споживати налаштований для викликача - тайм-аут моделі. Не вказуйте його, щоб використати стандартний тайм-аут спостереження/рішення, який - runner хуків застосовує загально. + дозволити повільному налаштуванню або recall-роботі витратити налаштований для викликача тайм-аут моделі. + Не вказуйте його, щоб використовувати стандартний тайм-аут спостереження/рішення, який + runner хука застосовує загально. -Оператори також можуть задавати бюджети хуків без змінення коду плагіна: +Оператори також можуть задавати бюджети хуків без виправлення коду плагіна: ```json { @@ -90,27 +90,27 @@ export default definePluginEntry({ `hooks.timeouts.` перевизначає `hooks.timeoutMs`, який перевизначає значення `api.on(..., { timeoutMs })`, задане автором плагіна. Кожне налаштоване значення має -бути додатним цілим числом не більше 600000 мілісекунд. Надавайте перевагу перевизначенням для окремих хуків -для відомо повільних хуків, щоб один плагін не отримував довший бюджет +бути додатним цілим числом не більшим за 600000 мілісекунд. Надавайте перевагу +перевизначенням для окремих хуків для відомих повільних хуків, щоб один плагін не отримував довший бюджет усюди. -Кожен хук отримує `event.context.pluginConfig`, розв'язану конфігурацію для -плагіна, який зареєстрував цей обробник. Використовуйте її для рішень хука, яким потрібні -поточні параметри плагіна; OpenClaw вставляє її для кожного обробника без мутації -спільного об'єкта події, який бачать інші плагіни. +Кожен хук отримує `event.context.pluginConfig`, розв’язану конфігурацію для +плагіна, який зареєстрував цей обробник. Використовуйте її для рішень хуків, яким потрібні +поточні параметри плагіна; OpenClaw впроваджує її для кожного обробника без мутації +спільного об’єкта події, який бачать інші плагіни. ## Каталог хуків Хуки згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають -результат рішення (заблокувати, скасувати, перевизначити або вимагати схвалення); усі інші +результат рішення (блокування, скасування, перевизначення або вимогу схвалення); усі інші призначені лише для спостереження. **Хід агента** - `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії -- `agent_turn_prepare` — спожити поставлені в чергу ін'єкції ходу плагіна й додати контекст того самого ходу перед prompt-хуками -- `before_prompt_build` — додати динамічний контекст або текст системного prompt перед викликом моделі -- `before_agent_start` — лише сумісна об'єднана фаза; надавайте перевагу двом хукам вище +- `agent_turn_prepare` — використати поставлені в чергу ін’єкції ходу плагіна й додати контекст того самого ходу до хуків промпта +- `before_prompt_build` — додати динамічний контекст або текст системного промпта перед викликом моделі +- `before_agent_start` — лише сумісна об’єднана фаза; надавайте перевагу двом хукам вище - **`before_agent_reply`** — достроково завершити хід моделі синтетичною відповіддю або тишею - **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі - `agent_end` — спостерігати фінальні повідомлення, стан успіху й тривалість запуску @@ -118,9 +118,9 @@ export default definePluginEntry({ **Спостереження за розмовою** -- `model_call_started` / `model_call_ended` — спостерігати очищені метадані виклику провайдера/моделі, таймінги, результат і обмежені хеші ідентифікаторів запитів без вмісту prompt або відповіді -- `llm_input` — спостерігати вхід провайдера (системний prompt, prompt, історія) -- `llm_output` — спостерігати вихід провайдера +- `model_call_started` / `model_call_ended` — спостерігати санітизовані метадані виклику провайдера/моделі, час, результат і обмежені хеші ідентифікаторів запитів без вмісту промпта або відповіді +- `llm_input` — спостерігати вхідні дані провайдера (системний промпт, промпт, історія) +- `llm_output` — спостерігати вихідні дані провайдера **Інструменти** @@ -129,14 +129,14 @@ export default definePluginEntry({ - **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента - **`before_message_write`** — перевірити або заблокувати запис повідомлення в процесі виконання (рідко) -**Повідомлення й доставка** +**Повідомлення та доставка** -- **`inbound_claim`** — заявити вхідне повідомлення перед маршрутизацією агента (синтетичні відповіді) -- `message_received` — спостерігати вхідний вміст, відправника, гілку й метадані +- **`inbound_claim`** — захопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді) +- `message_received` — спостерігати вхідний вміст, відправника, тред і метадані - **`message_sending`** — переписати вихідний вміст або скасувати доставку -- `message_sent` — спостерігати успіх або помилку вихідної доставки -- **`before_dispatch`** — перевірити або переписати вихідне відправлення перед передаванням каналу -- **`reply_dispatch`** — брати участь у конвеєрі фінального відправлення відповіді +- `message_sent` — спостерігати успіх або помилку доставки вихідного повідомлення +- **`before_dispatch`** — перевірити або переписати вихідне відправлення перед передачею каналу +- **`reply_dispatch`** — брати участь у фінальному конвеєрі відправлення відповіді **Сесії та Compaction** @@ -150,9 +150,9 @@ export default definePluginEntry({ **Життєвий цикл** -- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси, що належать плагіну, разом із Gateway -- `cron_changed` — спостерігати зміни життєвого циклу Cron, що належать gateway (додано, оновлено, видалено, запущено, завершено, заплановано) -- **`before_install`** — перевіряти сканування встановлення skill або плагіна й за потреби блокувати +- `gateway_start` / `gateway_stop` — запускати або зупиняти служби, якими володіє плагін, разом із Gateway +- `cron_changed` — спостерігати зміни життєвого циклу Cron, яким володіє Gateway (додано, оновлено, видалено, запущено, завершено, заплановано) +- **`before_install`** — перевірити сканування встановлення skill або плагіна та за потреби заблокувати ## Політика викликів інструментів @@ -160,9 +160,9 @@ export default definePluginEntry({ - `event.toolName` - `event.params` -- необов'язковий `event.runId` -- необов'язковий `event.toolCallId` -- поля контексту, як-от `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, +- необов’язковий `event.runId` +- необов’язковий `event.toolCallId` +- поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, `ctx.runId`, `ctx.jobId` (задано для запусків, керованих cron), і діагностичний `ctx.trace` Він може повертати: @@ -188,89 +188,105 @@ type BeforeToolCallResult = { Правила: -- `block: true` є кінцевим і пропускає обробники з нижчим пріоритетом. +- `block: true` є термінальним і пропускає обробники з нижчим пріоритетом. - `block: false` розглядається як відсутність рішення. - `params` переписує параметри інструмента для виконання. -- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення плагінів. - Команда `/approve` може схвалювати як exec, так і схвалення плагінів. -- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом - запросив схвалення. -- `onResolution` отримує розв'язане рішення схвалення — `allow-once`, +- `requireApproval` призупиняє запуск агента й запитує користувача через + схвалення плагінів. Команда `/approve` може схвалювати як exec, так і схвалення плагінів. +- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук + з вищим пріоритетом запросив схвалення. +- `onResolution` отримує розв’язане рішення схвалення — `allow-once`, `allow-always`, `deny`, `timeout` або `cancelled`. Вбудовані плагіни, яким потрібна політика рівня хоста, можуть реєструвати довірені політики інструментів -за допомогою `api.registerTrustedToolPolicy(...)`. Вони виконуються перед звичайними -хуками `before_tool_call` і перед рішеннями зовнішніх плагінів. Використовуйте їх лише -для довірених хостом шлюзів, як-от політика робочої області, контроль бюджету або -безпека зарезервованих workflow. Зовнішнім плагінам слід використовувати звичайні хуки `before_tool_call`. +за допомогою `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних +хуків `before_tool_call` і до рішень зовнішніх плагінів. Використовуйте їх лише +для довірених хостом бар’єрів, таких як політика робочого простору, забезпечення бюджету або +безпека зарезервованих workflow. Зовнішні плагіни мають використовувати звичайні хуки `before_tool_call`. ### Збереження результатів інструментів Результати інструментів можуть містити структуровані `details` для рендерингу UI, діагностики, -маршрутизації медіа або метаданих, що належать плагіну. Вважайте `details` runtime-метаданими, -а не вмістом prompt: +маршрутизації медіа або метаданих, якими володіє плагін. Розглядайте `details` як метадані виконання, +а не як вміст промпта: -- OpenClaw видаляє `toolResult.details` перед повторним відтворенням провайдера та вхідними даними - Compaction, щоб метадані не ставали контекстом моделі. -- Збережені записи сесії зберігають лише обмежені `details`. Завеликі details +- OpenClaw вилучає `toolResult.details` перед повторним відтворенням провайдером і входом Compaction, + щоб метадані не ставали контекстом моделі. +- Збережені записи сесії зберігають лише обмежені `details`. Завеликі деталі замінюються компактним підсумком і `persistedDetailsTruncated: true`. -- `tool_result_persist` і `before_message_write` виконуються перед фінальним - обмеженням збереження. Хукам усе одно слід залишати повернуті `details` малими й уникати - розміщення тексту, релевантного для prompt, лише в `details`; вивід інструмента, видимий моделі, - розміщуйте в `content`. +- `tool_result_persist` і `before_message_write` виконуються до фінального + обмеження збереження. Хуки все одно мають тримати повернуті `details` малими й уникати + розміщення релевантного для промпта тексту лише в `details`; розміщуйте видимий для моделі вивід інструмента + в `content`. -## Хуки prompt і моделі +## Хуки промпта й моделі -Використовуйте фазоспецифічні хуки для нових плагінів: +Для нових плагінів використовуйте хуки конкретних фаз: -- `before_model_resolve`: отримує лише поточний prompt і метадані вкладень. +- `before_model_resolve`: отримує лише поточний промпт і метадані вкладень. Поверніть `providerOverride` або `modelOverride`. -- `agent_turn_prepare`: отримує поточний prompt, підготовлені повідомлення сесії - та всі одноразові поставлені в чергу ін'єкції, злиті для цієї сесії. Поверніть +- `agent_turn_prepare`: отримує поточний промпт, підготовлені повідомлення сесії + й будь-які рівно-один-раз поставлені в чергу ін’єкції, вичерпані для цієї сесії. Поверніть `prependContext` або `appendContext`. -- `before_prompt_build`: отримує поточний prompt і повідомлення сесії. +- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. Поверніть `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`. - `heartbeat_prompt_contribution`: виконується лише для ходів Heartbeat і повертає `prependContext` або `appendContext`. Він призначений для фонових моніторів, - яким потрібно підсумувати поточний стан без змінення ходів, ініційованих користувачем. + яким потрібно підсумовувати поточний стан без зміни ходів, ініційованих користувачем. `before_agent_start` залишається для сумісності. Надавайте перевагу явним хукам вище, -щоб ваш плагін не залежав від застарілої об'єднаної фази. +щоб ваш плагін не залежав від застарілої об’єднаної фази. `before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може -визначити активний запуск. Те саме значення також доступне в `ctx.runId`. -Запуски, керовані Cron, також надають `ctx.jobId` (ідентифікатор початкового cron-завдання), щоб -Plugin-хуки могли обмежувати метрики, побічні ефекти або стан конкретним запланованим -завданням. +ідентифікувати активний запуск. Те саме значення також доступне в `ctx.runId`. +Запуски, керовані Cron, також відкривають `ctx.jobId` (id початкового cron job), щоб +хуки плагінів могли прив’язувати метрики, побічні ефекти або стан до конкретного запланованого +завдання. -Для запусків, що походять із каналу, `ctx.messageProvider` є поверхнею провайдера, як-от +Для запусків, що походять із каналів, `ctx.messageProvider` є поверхнею провайдера, такою як `discord` або `telegram`, тоді як `ctx.channelId` є цільовим ідентифікатором розмови, коли OpenClaw може вивести його з ключа сесії або метаданих доставки. -`agent_end` — це хук спостереження, який виконується за принципом fire-and-forget після ходу. Runner -хуків застосовує тайм-аут 30 секунд, щоб завислий плагін або endpoint embedding -не залишили promise хука в очікуванні назавжди. Тайм-аут записується в журнал, і -OpenClaw продовжує роботу; він не скасовує мережеву роботу, що належить плагіну, якщо -плагін також не використовує власний сигнал переривання. +`agent_end` є хуком спостереження й виконується за принципом fire-and-forget після ходу. Runner +хука застосовує 30-секундний тайм-аут, щоб завислий плагін або embedding endpoint +не залишив promise хука в очікуванні назавжди. Тайм-аут журналюється, і +OpenClaw продовжує роботу; він не скасовує мережеву роботу, якою володіє плагін, якщо +плагін також не використовує власний сигнал abort. Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера, -яка не має отримувати сирі prompts, історію, відповіді, заголовки, тіла запитів -або ідентифікатори запитів провайдера. Ці хуки містять стабільні метадані, як-от -`runId`, `callId`, `provider`, `model`, необов'язкові `api`/`transport`, кінцеві +яка не має отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів +або ідентифікатори запитів провайдера. Ці хуки містять стабільні метадані, такі як +`runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, термінальні `durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може вивести обмежений хеш ідентифікатора запиту провайдера. -`before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну +`before_agent_finalize` виконується лише тоді, коли harness ось-ось прийме природну фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб попросити -harness зробити ще один прохід моделі перед фіналізацією, `{ action: +harness виконати ще один прохід моделі перед фіналізацією, `{ action: "finalize", reason? }`, щоб примусово виконати фіналізацію, або не повертайте результат, щоб продовжити. Нативні хуки Codex `Stop` передаються в цей хук як рішення OpenClaw `before_agent_finalize`. +Повертаючи `action: "revise"`, плагіни можуть додавати метадані `retry`, щоб зробити +додатковий прохід моделі обмеженим і безпечним для повторного відтворення: + +```typescript +type BeforeAgentFinalizeRetry = { + instruction: string; + idempotencyKey?: string; + maxAttempts?: number; +}; +``` + +`instruction` додається до причини ревізії, надісланої до harness. +`idempotencyKey` дає хосту змогу рахувати повтори для того самого запиту плагіна в межах +еквівалентних рішень фіналізації, а `maxAttempts` обмежує кількість додаткових проходів, які +хост дозволить перед продовженням із природною фінальною відповіддю. + Невбудовані плагіни, яким потрібні `llm_input`, `llm_output`, -`before_agent_finalize` або `agent_end`, мають задати: +`before_agent_finalize` або `agent_end`, мають встановити: ```json { @@ -286,108 +302,107 @@ harness зробити ще один прохід моделі перед фін } ``` -Хуки, що змінюють prompt, і довговічні ін'єкції наступного ходу можна вимкнути для окремого плагіна +Хуки, що мутують промпти, і довговічні ін’єкції наступного ходу можна вимкнути для окремого плагіна за допомогою `plugins.entries..hooks.allowPromptInjection=false`. -### Розширення сесій та ін'єкції наступного ходу +### Розширення сесії та ін’єкції наступного ходу -Workflow-плагіни можуть зберігати невеликий JSON-сумісний стан сесії за допомогою +Workflow plugins можуть зберігати невеликий JSON-сумісний стан сесії за допомогою `api.registerSessionExtension(...)` і оновлювати його через метод Gateway `sessions.pluginPatch`. Рядки сесій проєктують зареєстрований стан розширення -через `pluginExtensions`, даючи Control UI та іншим клієнтам змогу відображати -статус, що належить плагіну, без знання внутрішньої реалізації плагіна. +через `pluginExtensions`, даючи змогу Control UI та іншим клієнтам відображати +статус, яким володіє plugin, без знання внутрішньої будови plugin. -Use `api.enqueueNextTurnInjection(...)`, коли plugin потребує надійного контексту, який має -дістатися наступного модельного ходу рівно один раз. OpenClaw обробляє ін’єкції в черзі перед -хуками промпта, відкидає прострочені ін’єкції та дедуплікує за `idempotencyKey` -для кожного plugin. Це правильний шов для поновлення після затверджень, зведень політик, +Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin потребує тривалого контексту, що має +дістатися наступного ходу моделі рівно один раз. OpenClaw обробляє поставлені в чергу ін’єкції перед +prompt hooks, відкидає прострочені ін’єкції та дедуплікує за `idempotencyKey` +для кожного plugin. Це правильний seam для відновлень після схвалення, підсумків політик, дельт фонових моніторів і продовжень команд, які мають бути видимі -моделі на наступному ході, але не мають ставати постійним текстом системного промпта. +моделі на наступному ході, але не повинні ставати постійним текстом системного промпта. -Семантика очищення є частиною контракту. Зворотні виклики очищення розширення сесії та -життєвого циклу runtime отримують `reset`, `delete`, `disable` або -`restart`. Хост видаляє постійний стан розширення сесії, що належить plugin, -і відкладені ін’єкції наступного ходу для reset/delete/disable; restart зберігає -надійний стан сесії, тоді як зворотні виклики очищення дають plugin змогу звільнити завдання -планувальника, контекст виконання та інші позасмугові ресурси для старого покоління -runtime. +Семантика очищення є частиною контракту. Callback-функції очищення розширення сесії та +очищення життєвого циклу runtime отримують `reset`, `delete`, `disable` або +`restart`. Host видаляє стійкий стан розширення сесії належного plugin +і очікувані ін’єкції наступного ходу для reset/delete/disable; restart зберігає +тривалий стан сесії, тоді як callback-функції очищення дають plugins змогу звільнити scheduler +jobs, run context та інші позасмугові ресурси старої генерації runtime. ## Хуки повідомлень -Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки: +Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставлення: - `message_received`: спостерігає вхідний вміст, відправника, `threadId`, `messageId`, - `senderId`, необов’язкову кореляцію запуску/сесії та метадані. + `senderId`, необов’язкову кореляцію run/session і metadata. - `message_sending`: переписує `content` або повертає `{ cancel: true }`. -- `message_sent`: спостерігає фінальний успіх або помилку. +- `message_sent`: спостерігає остаточний успіх або збій. -Для TTS-відповідей лише з аудіо `content` може містити прихований озвучений transcript -навіть тоді, коли payload каналу не має видимого тексту/підпису. Переписування цього -`content` оновлює лише transcript, видимий хуку; він не відображається як -підпис медіа. +Для аудіовідповідей TTS без видимого тексту `content` може містити прихований вимовлений transcript +навіть тоді, коли payload каналу не має видимого тексту/caption. Переписування цього +`content` оновлює лише transcript, видимий для hook; він не рендериться як +media caption. Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, `ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу -цим first-class полям перед читанням застарілих метаданих. +цим first-class полям, перш ніж читати legacy metadata. -Віддавайте перевагу типізованим полям `threadId` і `replyToId` перед використанням -каналоспецифічних метаданих. +Віддавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати специфічні для каналу +metadata. Правила ухвалення рішень: -- `message_sending` із `cancel: true` є термінальним. -- `message_sending` із `cancel: false` вважається відсутністю рішення. -- Переписаний `content` продовжує передаватися хукам із нижчим пріоритетом, якщо пізніший хук - не скасує доставку. +- `message_sending` з `cancel: true` є термінальним. +- `message_sending` з `cancel: false` вважається відсутністю рішення. +- Переписаний `content` продовжує переходити до хуків із нижчим пріоритетом, якщо пізніший hook + не скасує доставлення. ## Хуки встановлення -`before_install` виконується після вбудованого сканування для встановлень Skills і plugin. -Поверніть додаткові знахідки або `{ block: true, blockReason }`, щоб зупинити +`before_install` запускається після вбудованого сканування для встановлення skill і plugin. +Поверніть додаткові findings або `{ block: true, blockReason }`, щоб зупинити встановлення. `block: true` є термінальним. `block: false` вважається відсутністю рішення. ## Життєвий цикл Gateway -Використовуйте `gateway_start` для служб plugin, яким потрібен стан, що належить Gateway. Контекст +Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для -перевірки й оновлень cron. Використовуйте `gateway_stop`, щоб очистити довготривалі +перевірки та оновлень cron. Використовуйте `gateway_stop`, щоб очистити довготривалі ресурси. -Не покладайтеся на внутрішній хук `gateway:startup` для runtime-служб, що належать plugin. +Не покладайтеся на внутрішній hook `gateway:startup` для runtime-сервісів, що належать plugin. `cron_changed` спрацьовує для подій життєвого циклу cron, що належать gateway, з типізованим payload події, який охоплює причини `added`, `updated`, `removed`, `started`, `finished` -і `scheduled`. Подія містить snapshot `PluginHookGatewayCronJob` -(зокрема `state.nextRunAtMs`, `state.lastRunStatus` і -`state.lastError`, якщо наявні), а також `PluginHookGatewayCronDeliveryStatus` -зі значенням `not-requested` | `delivered` | `not-delivered` | `unknown`. Події видалення -все одно містять snapshot видаленого завдання, щоб зовнішні планувальники могли -узгодити стан. Використовуйте `ctx.getCron?.()` і `ctx.config` з runtime-контексту -під час синхронізації зовнішніх планувальників пробудження та залишайте OpenClaw -джерелом істини для перевірок строку виконання й виконання. +і `scheduled`. Подія несе snapshot `PluginHookGatewayCronJob` +(включно з `state.nextRunAtMs`, `state.lastRunStatus` і +`state.lastError`, коли вони присутні) плюс `PluginHookGatewayCronDeliveryStatus` +зі значенням `not-requested` | `delivered` | `not-delivered` | `unknown`. Події removed +усе ще містять snapshot видаленого job, щоб зовнішні schedulers могли +узгодити стан. Використовуйте `ctx.getCron?.()` і `ctx.config` з runtime +context під час синхронізації зовнішніх wake schedulers і залишайте OpenClaw +джерелом істини для перевірок настання строку та виконання. ## Майбутні припинення підтримки -Кілька поверхонь поруч із хуками застарілі, але все ще підтримуються. Мігруйте +Кілька поверхонь, суміжних із hooks, застарілі, але все ще підтримуються. Мігруйте до наступного major release: - **Plaintext channel envelopes** в обробниках `inbound_claim` і `message_received`. Читайте `BodyForAgent` і структуровані блоки user-context - замість парсингу плоского тексту envelope. Див. + замість парсингу плаского тексту envelope. Див. [Plaintext channel envelopes → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). -- **`before_agent_start`** зберігається для сумісності. Нові plugins мають використовувати +- **`before_agent_start`** залишається для сумісності. Нові plugins мають використовувати `before_model_resolve` і `before_prompt_build` замість об’єднаної фази. - **`onResolution` у `before_tool_call`** тепер використовує типізований union `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) замість довільного `string`. -Повний список — реєстрацію можливості пам’яті, профіль thinking provider, -зовнішніх auth providers, типи виявлення provider, accessors runtime завдання -та перейменування `command-auth` → `command-status` — див. у +Повний список — реєстрація memory capability, provider thinking +profile, зовнішні auth providers, типи provider discovery, task runtime +accessors і перейменування `command-auth` → `command-status` — див. [Міграція Plugin SDK → Активні припинення підтримки](/uk/plugins/sdk-migration#active-deprecations). ## Пов’язане @@ -395,6 +410,6 @@ payload події, який охоплює причини `added`, `updated`, ` - [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні припинення підтримки та графік видалення - [Створення plugins](/uk/plugins/building-plugins) - [Огляд Plugin SDK](/uk/plugins/sdk-overview) -- [Точки входу Plugin](/uk/plugins/sdk-entrypoints) -- [Внутрішні хуки](/uk/automation/hooks) -- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals) +- [Точки входу plugin](/uk/plugins/sdk-entrypoints) +- [Внутрішні hooks](/uk/automation/hooks) +- [Внутрішня архітектура plugin](/uk/plugins/architecture-internals)