openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 18:41:50 +00:00
parent c41424aff5
commit 39b5d8fa9e
1 changed files with 79 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
docs/uk/plugins/hooks.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу
- Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin
- 'Ви вирішуєте, що вибрати: внутрішні хуки чи хуки Plugin'
summary: 'Хуки Plugin: перехоплення подій життєвого циклу агента, інструмента, повідомлення, сесії та Gateway'
- Ви створюєте Plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу
- Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із Plugin
- 'Ви вирішуєте, що обрати: внутрішні хуки чи хуки Plugin'
summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway'
title: Хуки Plugin
x-i18n:
generated_at: "2026-04-24T18:11:53Z"
generated_at: "2026-04-24T18:41:00Z"
model: gpt-5.4
provider: openai
source_hash: 620f4a4c54c26efbab67b9e466624f8d72789937d7e056b88cdd00022b561943
source_hash: 122060cc36dd0ef0be4dbc6bab629742142543ba718fccd7f5a75885e73d43e1
source_path: plugins/hooks.md
workflow: 15
---
Хуки Plugin — це точки розширення в межах процесу для plugin OpenClaw. Використовуйте їх,
коли plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень,
життєвий цикл сесії, маршрутизацію subagent, встановлення або запуск Gateway.
Хуки Plugin — це внутрішньопроцесні точки розширення для Plugin OpenClaw. Використовуйте їх,
коли Plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень,
життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway.
Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий
встановлюваний оператором скрипт `HOOK.md` для команд і подій Gateway, таких як
скрипт `HOOK.md`, встановлений оператором, для команд і подій Gateway, таких як
`/new`, `/reset`, `/stop`, `agent:bootstrap` або `gateway:startup`.
## Швидкий старт
Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` у точці входу вашого plugin:
Зареєструйте типізовані хуки Plugin за допомогою `api.on(...)` у точці входу вашого Plugin:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -56,58 +56,58 @@ export default definePluginEntry({
});
```
Обробники хуків виконуються послідовно у спадному порядку `priority`. Хуки
Обробники хуків виконуються послідовно у порядку спадання `priority`. Хуки
з однаковим пріоритетом зберігають порядок реєстрації.
## Каталог хуків
Хуки згруповані за поверхнею, яку вони розширюють. Назви **жирним** приймають
результат рішення (блокування, скасування, перевизначення або вимогу схвалення); усі інші
лише для спостереження.
Хуки згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають
результат рішення (block, cancel, override або require approval); усі інші є
лише спостережними.
**Хід агента**
- `before_model_resolve` — перевизначити provider або модель до завантаження повідомлень сесії
- `before_prompt_build` — додати динамічний контекст або текст системного prompt перед викликом моделі
- `before_agent_start` — комбінована фаза лише для сумісності; натомість використовуйте два хуки вище
- **`before_agent_reply`** — замкнути хід моделі на синтетичній відповіді або тиші
- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску
- `before_model_resolve` — перевизначає провайдера або модель до завантаження повідомлень сесії
- `before_prompt_build` — додає динамічний контекст або текст системного промпту перед викликом моделі
- `before_agent_start` — лише сумісний об’єднаний етап; натомість віддавайте перевагу двом хукам вище
- **`before_agent_reply`** — достроково завершує хід моделі синтетичною відповіддю або беззвучним режимом
- `agent_end` — спостерігає фінальні повідомлення, стан успіху та тривалість запуску
**Спостереження за розмовою**
- `llm_input` — спостерігати вхід provider (системний prompt, prompt, історія)
- `llm_output` — спостерігати вихід provider
- `llm_input` — спостерігає вхідні дані провайдера (системний промпт, промпт, історія)
- `llm_output` — спостерігає вихідні дані провайдера
**Інструменти**
- **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення
- `after_tool_call` — спостерігати результати інструмента, помилки та тривалість
- **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента
- **`before_message_write`** — перевірити або заблокувати запис повідомлення в процесі (рідко)
- **`before_tool_call`** — переписує параметри інструмента, блокує виконання або вимагає схвалення
- `after_tool_call` — спостерігає результати інструмента, помилки та тривалість
- **`tool_result_persist`** — переписує повідомлення асистента, створене з результату інструмента
- **`before_message_write`** — перевіряє або блокує запис повідомлення в процесі виконання (рідко)
**Повідомлення та доставка**
- **`inbound_claim`** — взяти вхідне повідомлення до маршрутизації агента (синтетичні відповіді)
- `message_received` — спостерігати вхідний вміст, відправника, гілку та метадані
- **`message_sending`** — переписати вихідний вміст або скасувати доставку
- `message_sent` — спостерігати успіх або збій вихідної доставки
- **`before_dispatch`** — перевірити або переписати вихідне dispatch до передавання каналу
- **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді
- **`inbound_claim`** — перехоплює вхідне повідомлення до маршрутизації агента (синтетичні відповіді)
- `message_received` — спостерігає вхідний вміст, відправника, потік та метадані
- **`message_sending`** — переписує вихідний вміст або скасовує доставку
- `message_sent` — спостерігає успіх або збій вихідної доставки
- **`before_dispatch`** — перевіряє або переписує вихідну диспетчеризацію до передавання каналу
- **`reply_dispatch`** — бере участь у фінальному конвеєрі диспетчеризації відповіді
**Сесії та Compaction**
- `session_start` / `session_end` — відстежувати межі життєвого циклу сесії
- `before_compaction` / `after_compaction` — спостерігати або анотувати цикли Compaction
- `before_reset` — спостерігати події скидання сесії (`/reset`, програмні скидання)
- `session_start` / `session_end` — відстежують межі життєвого циклу сесії
- `before_compaction` / `after_compaction` — спостерігають або анотують цикли Compaction
- `before_reset` — спостерігає події скидання сесії (`/reset`, програмні скидання)
**Subagent**
**Субагенти**
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію subagent і доставку після завершення
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координують маршрутизацію субагентів і доставку завершення
**Життєвий цикл**
- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси plugin, що належать Gateway
- **`before_install`** — перевіряти сканування встановлення skill або plugin і за потреби блокувати
- `gateway_start` / `gateway_stop` — запускають або зупиняють служби Plugin, що належать Gateway
- **`before_install`** — перевіряє сканування встановлення skill або Plugin і за потреби блокує
## Політика викликів інструментів
@ -143,30 +143,33 @@ type BeforeToolCallResult = {
Правила:
- `block: true` є фінальним і пропускає обробники з нижчим пріоритетом.
- `block: true` є термінальним і пропускає обробники з нижчим пріоритетом.
- `block: false` трактується як відсутність рішення.
- `params` переписує параметри інструмента для виконання.
- `requireApproval` призупиняє запуск агента й запитує користувача через
схвалення plugin. Команда `/approve` може схвалювати як exec, так і схвалення plugin.
- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук з вищим пріоритетом
- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення Plugin.
Команда `/approve` може схвалювати як exec, так і схвалення Plugin.
- `block: true` з нижчим пріоритетом усе ще може заблокувати виконання після того, як хук з вищим пріоритетом
запросив схвалення.
- `onResolution` отримує остаточне рішення щодо схвалення — `allow-once`,
`allow-always`, `deny`, `timeout` або `cancelled`.
## Хуки prompt і моделі
## Хуки промптів і моделей
Для нових plugin використовуйте хуки, прив’язані до конкретної фази:
Для нових Plugin використовуйте хуки, специфічні для етапу:
- `before_model_resolve`: отримує лише поточний prompt і метадані
вкладень. Поверніть `providerOverride` або `modelOverride`.
- `before_prompt_build`: отримує поточний prompt і повідомлення сесії.
Поверніть `prependContext`, `systemPrompt`, `prependSystemContext` або
- `before_model_resolve`: отримує лише поточний промпт і метадані вкладень.
Повертає `providerOverride` або `modelOverride`.
- `before_prompt_build`: отримує поточний промпт і повідомлення сесії.
Повертає `prependContext`, `systemPrompt`, `prependSystemContext` або
`appendSystemContext`.
`before_agent_start` залишається для сумісності. Надавайте перевагу явним хукам вище,
щоб ваш plugin не залежав від застарілої комбінованої фази.
`before_agent_start` лишається для сумісності. Віддавайте перевагу явним хукам вище,
щоб ваш Plugin не залежав від застарілого об’єднаного етапу.
Plugin, що не входять до комплекту, і яким потрібні `llm_input`, `llm_output` або `agent_end`, мають задати:
`before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може
визначити активний запуск. Це саме значення також доступне в `ctx.runId`.
Сторонні Plugin, яким потрібні `llm_input`, `llm_output` або `agent_end`, мають установити:
```json
{
@ -182,49 +185,54 @@ Plugin, що не входять до комплекту, і яким потрі
}
```
Хуки, що змінюють prompt, можна вимкнути для окремого plugin через
Хуки, що змінюють промпт, можна вимкнути для окремого Plugin через
`plugins.entries.<id>.hooks.allowPromptInjection=false`.
## Хуки повідомлень
Використовуйте хуки повідомлень для політики маршрутизації та доставки на рівні каналу:
Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки:
- `message_received`: спостерігати вхідний вміст, відправника, `threadId` і метадані.
- `message_sending`: переписати `content` або повернути `{ cancel: true }`.
- `message_sent`: спостерігати фінальний успіх або збій.
- `message_received`: спостерігає вхідний вміст, відправника, `threadId`, `messageId`,
`senderId`, необов’язкову кореляцію запуску/сесії та метадані.
- `message_sending`: переписує `content` або повертає `{ cancel: true }`.
- `message_sent`: спостерігає фінальний успіх або збій.
Надавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати метадані,
специфічні для каналу.
Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні:
`ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`,
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу
цим першокласним полям, перш ніж звертатися до застарілих метаданих.
Віддавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати
метадані, специфічні для каналу.
Правила рішень:
- `message_sending` з `cancel: true` є фінальним.
- `message_sending` з `cancel: false` трактується як відсутність рішення.
- Переписаний `content` передається хукам з нижчим пріоритетом, якщо пізніший хук
не скасує доставку.
- `message_sending` із `cancel: true` є термінальним.
- `message_sending` із `cancel: false` трактується як відсутність рішення.
- Переписаний `content` передається хукам із нижчим пріоритетом, якщо пізніший хук
не скасовує доставку.
## Хуки встановлення
`before_install` запускається після вбудованого сканування встановлень skill і plugin.
`before_install` виконується після вбудованого сканування встановлень skill і Plugin.
Поверніть додаткові результати або `{ block: true, blockReason }`, щоб зупинити
встановлення.
`block: true` є фінальним. `block: false` трактується як відсутність рішення.
`block: true` є термінальним. `block: false` трактується як відсутність рішення.
## Життєвий цикл Gateway
Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст
надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для
Використовуйте `gateway_start` для служб Plugin, яким потрібен стан, що належить Gateway.
Контекст надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для
перевірки та оновлення Cron. Використовуйте `gateway_stop` для очищення довготривалих
ресурсів.
Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання,
що належать plugin.
Не покладайтеся на внутрішній хук `gateway:startup` для служб часу виконання, що належать Plugin.
## Пов’язане
- [Створення plugin](/uk/plugins/building-plugins)
- [Створення Plugin](/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/architecture-internals)