From d32062ba169f31f8bee69546960127b7c13e10f2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 13:58:06 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/building-plugins.md | 237 ++++++++++++++-------------- docs/uk/plugins/sdk-runtime.md | 130 +++++++-------- docs/uk/tools/index.md | 192 +++++++++++----------- 3 files changed, 285 insertions(+), 274 deletions(-) diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index b8e5377ba..c7663be80 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -1,61 +1,61 @@ --- read_when: - Ви хочете створити новий Plugin для OpenClaw - - Вам потрібен короткий посібник із розробки Plugin - - Ви додаєте до OpenClaw новий канал, провайдера, інструмент або іншу можливість + - Вам потрібен швидкий старт для розробки Plugin + - Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw sidebarTitle: Getting Started -summary: Створіть свій перший Plugin для OpenClaw за кілька хвилин -title: Створення плагінів +summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини +title: Створення Plugin x-i18n: - generated_at: "2026-05-02T05:25:37Z" + generated_at: "2026-05-02T13:56:49Z" model: gpt-5.5 provider: openai - source_hash: 2cf85c1c1c1f6ae6752f7fb8d842a420bffac6ebaf4d64803fb8bb8ab9f6f83c + source_hash: f4f810d831db26d1e4efecf691590980b3ba1d958c4b4af3cc6a7ca9ea155a36 source_path: plugins/building-plugins.md workflow: 16 --- -Плагіни розширюють OpenClaw новими можливостями: каналами, провайдерами моделей, -мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, -генерацією відео, вебзавантаженням, вебпошуком, інструментами агента або будь-якою -комбінацією. +Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, +мовлення, транскрибування в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, +генерація відео, отримання вебвмісту, вебпошук, інструменти агента або будь-яка +комбінація. -Вам не потрібно додавати свій плагін до репозиторію OpenClaw. Опублікуйте його в +Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub), і користувачі встановлять його за допомогою -`openclaw plugins install `. OpenClaw спершу пробує ClawHub і +`openclaw plugins install `. OpenClaw спочатку пробує ClawHub і автоматично повертається до npm для пакетів, які все ще використовують розповсюдження через npm. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для плагінів у репозиторії: репозиторій клоновано й виконано `pnpm install`. Розробка плагінів - із checkout вихідного коду підтримує лише pnpm, оскільки OpenClaw завантажує вбудовані - плагіни з workspace-пакетів `extensions/*`. +- Для plugins у репозиторії: репозиторій клоновано і виконано `pnpm install`. Розробка plugin + з checkout вихідного коду підтримує лише pnpm, тому що OpenClaw завантажує вбудовані + plugins із workspace-пакетів `extensions/*`. -## Який тип плагіна? +## Який тип plugin? - + Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - - Додайте провайдера моделей (LLM, проксі або власний endpoint) + + Додайте провайдера моделей (LLM, проксі або власну кінцеву точку) - + Зареєструйте інструменти агента, event hooks або сервіси — продовжуйте нижче -Для плагіна каналу, який не гарантовано буде встановлено під час запуску onboarding/setup, +Для plugin каналу, який не гарантовано буде встановлений під час onboarding/setup, використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару setup adapter + wizard, -яка повідомляє про вимогу встановлення й завершується без змін під час реальних записів конфігурації, -доки плагін не встановлено. +`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптер setup + wizard, +яка повідомляє про вимогу встановлення і відмовляє безпечно під час реальних записів конфігурації, +доки plugin не буде встановлено. -## Швидкий старт: плагін інструмента +## Швидкий старт: plugin інструменту -Цей walkthrough створює мінімальний плагін, який реєструє інструмент агента. Для плагінів каналів +Цей покроковий посібник створює мінімальний plugin, який реєструє інструмент агента. Для plugins каналів і провайдерів є окремі посібники, посилання на які наведено вище. @@ -99,12 +99,12 @@ x-i18n: ``` - Кожному плагіну потрібен manifest, навіть без конфігурації. Інструменти, зареєстровані під час виконання, - мають бути перелічені в `contracts.tools`, щоб OpenClaw міг визначити відповідальний - плагін без завантаження runtime кожного плагіна. Плагіни також мають свідомо оголошувати - `activation.onStartup`. У цьому прикладі встановлено значення `true`. Див. + Кожному plugin потрібен manifest, навіть без конфігурації. Інструменти, зареєстровані під час виконання, + мають бути перелічені в `contracts.tools`, щоб OpenClaw міг знайти власника + plugin без завантаження runtime кожного plugin. Plugins також мають свідомо оголошувати + `activation.onStartup`. У цьому прикладі встановлено `true`. Див. [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні snippets публікації ClawHub - містяться в `docs/snippets/plugin-publish/`. + розміщені в `docs/snippets/plugin-publish/`. @@ -132,15 +132,15 @@ x-i18n: }); ``` - `definePluginEntry` призначений для плагінів, що не є каналами. Для каналів використовуйте - `defineChannelPluginEntry` — див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). - Повні параметри entry point див. у [Entry Points](/uk/plugins/sdk-entrypoints). + `definePluginEntry` призначений для plugins, які не є каналами. Для каналів використовуйте + `defineChannelPluginEntry` — див. [Plugins каналів](/uk/plugins/sdk-channel-plugins). + Повні параметри entry point наведено в [Entry Points](/uk/plugins/sdk-entrypoints). - **Зовнішні плагіни:** перевірте та опублікуйте через ClawHub, потім встановіть: + **Зовнішні plugins:** перевірте й опублікуйте за допомогою ClawHub, а потім установіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -149,10 +149,10 @@ x-i18n: ``` OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів, як-от - `@myorg/openclaw-my-plugin`; npm залишається fallback для пакетів, які ще - не мігрували до ClawHub. + `@myorg/openclaw-my-plugin`; npm залишається fallback для пакетів, які + ще не мігрували до ClawHub. - **Плагіни в репозиторії:** розмістіть у дереві workspace вбудованих плагінів — їх буде автоматично виявлено. + **Plugins у репозиторії:** розмістіть під деревом workspace вбудованих plugins — буде знайдено автоматично. ```bash pnpm test -- /my-plugin/ @@ -161,70 +161,70 @@ x-i18n: -## Можливості плагіна +## Можливості Plugin -Один плагін може зареєструвати будь-яку кількість можливостей через об’єкт `api`: +Один plugin може зареєструвати будь-яку кількість можливостей через об'єкт `api`: -| Можливість | Метод реєстрації | Детальний посібник | +| Можливість | Метод реєстрації | Докладний посібник | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | -| Текстовий inference (LLM) | `api.registerProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) | -| Backend inference для CLI | `api.registerCliBackend(...)` | [Backends CLI](/uk/gateway/cli-backends) | -| Канал / повідомлення | `api.registerChannel(...)` | [Плагіни каналів](/uk/plugins/sdk-channel-plugins) | -| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вебзавантаження | `api.registerWebFetchProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вебпошук | `api.registerWebSearchProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | -| Інструменти агента | `api.registerTool(...)` | Нижче | -| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| Hooks плагіна | `api.on(...)` | [Hooks плагіна](/uk/plugins/hooks) | -| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| HTTP-маршрути | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) | -| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Текстове inference (LLM) | `api.registerProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins) | +| Backend inference для CLI | `api.registerCliBackend(...)` | [Backends CLI](/uk/gateway/cli-backends) | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Plugins каналів](/uk/plugins/sdk-channel-plugins) | +| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Отримання вебвмісту | `api.registerWebFetchProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Вебпошук | `api.registerWebSearchProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | +| Інструменти агента | `api.registerTool(...)` | Нижче | +| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) | +| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| HTTP routes | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -Повний API реєстрації див. в [Огляді SDK](/uk/plugins/sdk-overview#registration-api). +Повний registration API див. в [Огляд SDK](/uk/plugins/sdk-overview#registration-api). -Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм -потрібне асинхронне переписування результату інструмента до того, як модель побачить output. Оголошуйте +Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм +потрібне асинхронне переписування результатів інструментів до того, як модель побачить output. Оголосіть цільові runtimes у `contracts.agentToolResultMiddleware`, наприклад -`["pi", "codex"]`. Це довірений seam для вбудованих плагінів; зовнішнім -плагінам варто надавати перевагу звичайним hooks плагінів OpenClaw, доки OpenClaw не матиме -явної політики довіри для цієї можливості. +`["pi", "codex"]`. Це довірений seam для вбудованих plugins; зовнішнім +plugins варто віддавати перевагу звичайним hooks OpenClaw plugin, якщо OpenClaw не додасть +явної trust policy для цієї можливості. -Якщо ваш плагін реєструє власні RPC-методи Gateway, тримайте їх у -префіксі, специфічному для плагіна. Простори імен core admin (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди resolve до -`operator.admin`, навіть якщо плагін просить вужчий scope. +Якщо ваш plugin реєструє власні RPC-методи gateway, тримайте їх на +префіксі, специфічному для plugin. Core admin namespaces (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв'язуються до +`operator.admin`, навіть якщо plugin просить вужчий scope. -Семантика guard для hooks, яку варто пам’ятати: +Семантика guard для hooks, яку варто пам'ятати: -- `before_tool_call`: `{ block: true }` є terminal і зупиняє handlers із нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує в користувача схвалення через exec approval overlay, кнопки Telegram, Discord interactions або команду `/approve` на будь-якому каналі. -- `before_install`: `{ block: true }` є terminal і зупиняє handlers із нижчим пріоритетом. -- `before_install`: `{ block: false }` розглядається як відсутність рішення. -- `message_sending`: `{ cancel: true }` є terminal і зупиняє handlers із нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення. -- `message_received`: надавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних thread/topic. Залишайте `metadata` для додаткових даних, специфічних для каналу. -- `message_sending`: надавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId` замість ключів metadata, специфічних для каналу. +- `before_tool_call`: `{ block: true }` є terminal і зупиняє handlers з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` трактується як відсутність рішення. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через overlay схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. +- `before_install`: `{ block: true }` є terminal і зупиняє handlers з нижчим пріоритетом. +- `before_install`: `{ block: false }` трактується як відсутність рішення. +- `message_sending`: `{ cancel: true }` є terminal і зупиняє handlers з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` трактується як відсутність рішення. +- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних thread/topic. Залишайте `metadata` для додаткових даних, специфічних для каналу. +- `message_sending`: віддавайте перевагу типізованим routing-полям `replyToId` / `threadId` замість ключів metadata, специфічних для каналу. -Команда `/approve` обробляє як exec approvals, так і approvals плагінів із bounded fallback: коли id exec approval не знайдено, OpenClaw повторює той самий id через approvals плагінів. Forwarding approvals плагінів можна налаштовувати незалежно через `approvals.plugin` у конфігурації. +Команда `/approve` обробляє як exec, так і plugin approvals з обмеженим fallback: коли id exec approval не знайдено, OpenClaw повторює той самий id через plugin approvals. Forwarding plugin approval можна налаштувати незалежно через `approvals.plugin` у конфігурації. -Якщо власний approval plumbing має виявляти той самий bounded fallback-випадок, -надавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` -замість ручного зіставлення рядків про expiry approval. +Якщо власна approval plumbing має виявити той самий випадок обмеженого fallback, +віддавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` +замість ручного зіставлення рядків про expiration approval. -Приклади й довідник hooks див. у [Hooks плагіна](/uk/plugins/hooks). +Приклади та довідник hooks див. у [Plugin hooks](/uk/plugins/hooks). ## Реєстрація інструментів агента -Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди -доступними) або опціональними (користувач вмикає їх сам): +Інструменти — це типізовані функції, які LLM може викликати. Вони можуть бути обов'язковими (завжди +доступні) або необов'язковими (користувач вмикає самостійно): ```typescript register(api) { @@ -254,7 +254,7 @@ register(api) { ``` Кожен інструмент, зареєстрований через `api.registerTool(...)`, також має бути оголошений у -manifest плагіна: +manifest plugin: ```json { @@ -264,7 +264,12 @@ manifest плагіна: } ``` -Користувачі вмикають опціональні інструменти в конфігурації: +OpenClaw захоплює й кешує перевірений descriptor із зареєстрованого інструмента, +тому plugins не дублюють `description` або дані schema в manifest. Контракт +manifest лише оголошує ownership і discovery; виконання все одно викликає +живу зареєстровану реалізацію інструмента. + +Користувачі вмикають необов'язкові інструменти в конфігурації: ```json5 { @@ -272,14 +277,14 @@ manifest плагіна: } ``` -- Назви інструментів не повинні конфліктувати з основними інструментами (конфліктні пропускаються) -- Інструменти з некоректно сформованими об’єктами реєстрації, зокрема без `parameters`, пропускаються й повідомляються в діагностиці plugin замість того, щоб ламати запуски агента +- Назви інструментів не мають конфліктувати з основними інструментами (конфлікти пропускаються) +- Інструменти з некоректними об’єктами реєстрації, зокрема без `parameters`, пропускаються й повідомляються в діагностиці plugin замість того, щоб ламати запуски агента - Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів - Користувачі можуть увімкнути всі інструменти з plugin, додавши ідентифікатор plugin до `tools.allow` ## Реєстрація команд CLI -Plugins можуть додавати кореневі групи команд `openclaw` за допомогою `api.registerCli`. Надавайте +Plugins можуть додавати кореневі групи команд `openclaw` за допомогою `api.registerCli`. Надайте `descriptors` для кожного кореня команди верхнього рівня, щоб OpenClaw міг показувати й маршрутизувати команду без завчасного завантаження кожного середовища виконання plugin. @@ -332,53 +337,53 @@ import { ... } from "openclaw/plugin-sdk"; Повний довідник підшляхів див. у [Огляді SDK](/uk/plugins/sdk-overview). -Усередині свого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для -внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK. +У межах вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для +внутрішніх імпортів — ніколи не імпортуйте власний plugin через його SDK-шлях. -Для provider plugins тримайте специфічні для провайдера допоміжні засоби в цих barrel-файлах кореня пакета, -якщо межа не є справді узагальненою. Поточні вбудовані приклади: +Для provider plugins тримайте специфічні для провайдера допоміжні функції в цих barrel-файлах кореня пакета, +якщо цей seam не є справді універсальним. Поточні вбудовані приклади: -- Anthropic: обгортки потоків Claude та допоміжні засоби `service_tier` / beta -- OpenAI: конструктори провайдера, допоміжні засоби моделей за замовчуванням, realtime-провайдери -- OpenRouter: конструктор провайдера та допоміжні засоби onboarding/конфігурації +- Anthropic: обгортки потоку Claude та допоміжні функції `service_tier` / beta +- OpenAI: побудовники провайдера, допоміжні функції стандартної моделі, realtime-провайдери +- OpenRouter: побудовник провайдера плюс допоміжні функції onboarding/config -Якщо допоміжний засіб корисний лише всередині одного вбудованого пакета провайдера, залишайте його на цій -межі кореня пакета замість просування в `openclaw/plugin-sdk/*`. +Якщо допоміжна функція корисна лише всередині одного вбудованого пакета провайдера, тримайте її на цьому +seam кореня пакета замість просування в `openclaw/plugin-sdk/*`. -Деякі згенеровані допоміжні межі `openclaw/plugin-sdk/` досі існують для -супроводу вбудованих plugin, коли для них відстежується використання власником. Вважайте їх -зарезервованими поверхнями, а не типовим шаблоном для нових сторонніх plugins. +Деякі згенеровані допоміжні seam `openclaw/plugin-sdk/` досі існують для +супроводу вбудованих plugins, коли для них відстежується використання власником. Сприймайте їх як +зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins. ## Контрольний список перед поданням -**package.json** має коректні метадані `openclaw` +**package.json** має правильні метадані `openclaw` Маніфест **openclaw.plugin.json** наявний і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` Усі імпорти використовують сфокусовані шляхи `plugin-sdk/` Внутрішні імпорти використовують локальні модулі, а не самоімпорти SDK Тести проходять (`pnpm test -- /my-plugin/`) -`pnpm check` проходить (для plugins у репозиторії) +`pnpm check` проходить (plugins усередині репозиторію) ## Тестування beta-релізу -1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Також можна ввімкнути сповіщення для офіційного X-акаунта OpenClaw [@openclaw](https://x.com/openclaw), щоб отримувати оголошення про релізи. -2. Тестуйте свій plugin з beta-тегом щойно він з’явиться. Вікно до stable зазвичай становить лише кілька годин. -3. Після тестування напишіть у гілці свого plugin у каналі Discord `plugin-forum` або `all good`, або що саме зламалося. Якщо гілки ще немає, створіть її. -4. Якщо щось зламалося, відкрийте або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. -5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у свою гілку Discord. Contributors не можуть ставити мітки на PR, тому назва є сигналом на боці PR для maintainers та автоматизації. Блокери з PR зливаються; блокери без PR можуть усе одно потрапити в реліз. Maintainers стежать за цими гілками під час beta-тестування. -6. Мовчання означає зелений статус. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить у наступний цикл. +1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного X-акаунта OpenClaw [@openclaw](https://x.com/openclaw), щоб отримувати оголошення про релізи. +2. Протестуйте свій plugin з beta-тегом щойно він з’явиться. Вікно до стабільного релізу зазвичай триває лише кілька годин. +3. Напишіть у гілці свого plugin в Discord-каналі `plugin-forum` після тестування: або `all good`, або що зламалося. Якщо у вас ще немає гілки, створіть її. +4. Якщо щось ламається, відкрийте або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у своїй гілці Discord. Контриб’ютори не можуть ставити мітки на PR, тому назва є сигналом з боку PR для мейнтейнерів і автоматизації. Блокери з PR зливаються; блокери без PR можуть усе одно потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування. +6. Мовчання означає зелений статус. Якщо ви пропустите це вікно, ваше виправлення, ймовірно, потрапить у наступний цикл. ## Наступні кроки - Створити plugin каналу повідомлень + Створіть plugin каналу повідомлень - Створити plugin провайдера моделей + Створіть plugin провайдера моделей - Мапа імпортів і довідник API реєстрації + Карта імпортів і довідник API реєстрації TTS, пошук, субагент через api.runtime @@ -393,7 +398,7 @@ import { ... } from "openclaw/plugin-sdk"; ## Пов’язане -- [Архітектура Plugin](/uk/plugins/architecture) — докладний огляд внутрішньої архітектури +- [Архітектура Plugin](/uk/plugins/architecture) — глибокий огляд внутрішньої архітектури - [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK - [Маніфест](/uk/plugins/manifest) — формат маніфесту plugin - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення plugins каналів diff --git a/docs/uk/plugins/sdk-runtime.md b/docs/uk/plugins/sdk-runtime.md index 87914b46e..ba1bfaac5 100644 --- a/docs/uk/plugins/sdk-runtime.md +++ b/docs/uk/plugins/sdk-runtime.md @@ -2,27 +2,27 @@ read_when: - Потрібно викликати допоміжні функції ядра з Plugin (TTS, STT, генерація зображень, вебпошук, субагент, вузли) - Ви хочете зрозуміти, що надає api.runtime - - Ви звертаєтеся до допоміжних засобів конфігурації, агента або медіа з коду Plugin + - Ви отримуєте доступ до допоміжних функцій конфігурації, агента або медіа з коду Plugin sidebarTitle: Runtime helpers -summary: api.runtime -- впроваджені допоміжні засоби середовища виконання, доступні для Plugin +summary: api.runtime -- інжектовані допоміжні засоби часу виконання, доступні плагінам title: Допоміжні засоби середовища виконання Plugin x-i18n: - generated_at: "2026-05-02T12:15:45Z" + generated_at: "2026-05-02T13:56:46Z" model: gpt-5.5 provider: openai - source_hash: 02c0dc6522e80d4a02b1d3c248fa5ac934888035d435df8b1967861f9dcceb6a + source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c source_path: plugins/sdk-runtime.md workflow: 16 --- -Довідник для об’єкта `api.runtime`, який впроваджується в кожен plugin під час реєстрації. Використовуйте ці допоміжні функції замість прямого імпорту внутрішніх компонентів хоста. +Довідник для об’єкта `api.runtime`, що впроваджується в кожен plugin під час реєстрації. Використовуйте ці допоміжні засоби замість прямого імпорту внутрішніх модулів хоста. - Покроковий посібник, який показує використання цих допоміжних функцій у контексті для channel plugins. + Покроковий посібник, який показує використання цих допоміжних засобів у контексті для channel plugins. - Покроковий посібник, який показує використання цих допоміжних функцій у контексті для provider plugins. + Покроковий посібник, який показує використання цих допоміжних засобів у контексті для provider plugins. @@ -34,38 +34,33 @@ register(api) { ## Завантаження й запис конфігурації -Надавайте перевагу конфігурації, яку вже було передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-функціях каналу чи provider. Це зберігає один знімок процесу протягом роботи замість повторного розбору конфігурації в гарячих шляхах. +Надавайте перевагу конфігурації, яку вже передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-функціях каналу/провайдера. Це забезпечує проходження одного знімка процесу через роботу замість повторного розбору конфігурації на гарячих шляхах. -Використовуйте `api.runtime.config.current()` лише тоді, коли довготривалому обробнику потрібен поточний знімок процесу, а конфігурацію не було передано цій функції. Повернене значення доступне тільки для читання; перед редагуванням створіть копію або скористайтеся допоміжною функцією мутації. +Використовуйте `api.runtime.config.current()` лише тоді, коли довгоживучому обробнику потрібен поточний знімок процесу й жодну конфігурацію не було передано в цю функцію. Повернене значення доступне лише для читання; перед редагуванням клонуйте його або використайте допоміжний засіб мутації. -Фабрики інструментів отримують `ctx.runtimeConfig` разом із `ctx.getRuntimeConfig()`. Використовуйте getter усередині callback-функції `execute` довготривалого інструмента, коли конфігурація може змінитися після створення визначення інструмента. +Фабрики інструментів отримують `ctx.runtimeConfig` плюс `ctx.getRuntimeConfig()`. Використовуйте getter усередині callback-функції `execute` довгоживучого інструмента, коли конфігурація може змінитися після створення визначення інструмента. -Зберігайте зміни через `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибрати явну політику `afterWrite`: +Зберігайте зміни за допомогою `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибрати явну політику `afterWrite`: -- `afterWrite: { mode: "auto" }` дозволяє механізму перезавантаження Gateway ухвалити рішення. -- `afterWrite: { mode: "restart", reason: "..." }` примусово виконує чистий перезапуск, коли автор запису знає, що гаряче перезавантаження небезпечне. -- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження або перезапуск лише тоді, коли викликач сам відповідає за подальші дії. +- `afterWrite: { mode: "auto" }` дозволяє Gateway reload planner ухвалити рішення. +- `afterWrite: { mode: "restart", reason: "..." }` примусово виконує чистий перезапуск, коли writer знає, що гаряче перезавантаження небезпечне. +- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження/перезапуск лише тоді, коли викликач сам відповідає за подальші дії. -Допоміжні функції мутації повертають `afterWrite` разом із типізованим підсумком `followUp`, щоб викликачі могли логувати або тестувати, чи запросили вони перезапуск. Gateway і надалі визначає, коли цей перезапуск фактично відбудеться. +Допоміжні засоби мутації повертають `afterWrite` плюс типізований підсумок `followUp`, щоб викликачі могли журналювати або тестувати, чи запитали вони перезапуск. Gateway все ще відповідає за те, коли цей перезапуск фактично відбудеться. -`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` є застарілими допоміжними функціями сумісності в межах `runtime-config-load-write`. Вони один раз попереджають під час виконання та залишаються доступними для старих зовнішніх plugins протягом вікна міграції. Вбудовані plugins не повинні їх використовувати; захисні перевірки межі конфігурації завершуються помилкою, якщо код plugin викликає їх або імпортує ці допоміжні функції з підшляхів plugin SDK. +`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` є застарілими допоміжними засобами сумісності в межах `runtime-config-load-write`. Вони один раз попереджають під час виконання й залишаються доступними для старих зовнішніх plugins протягом міграційного вікна. Вбудовані plugins не повинні їх використовувати; guards межі конфігурації завершаться помилкою, якщо код plugin викликає їх або імпортує ці допоміжні засоби з підшляхів plugin SDK. -Для прямих імпортів SDK використовуйте цільові підшляхи конфігурації замість широкого сумісного barrel -`openclaw/plugin-sdk/config-runtime`: `config-types` для -типів, `plugin-config-runtime` для перевірок уже завантаженої конфігурації та -пошуку точки входу plugin, `runtime-config-snapshot` для поточних знімків процесу, і -`config-mutation` для записів. Тести вбудованих plugins мають mock-ати ці цільові -підшляхи напряму, а не широкий сумісний barrel. +Для прямих імпортів SDK використовуйте сфокусовані підшляхи конфігурації замість широкого compatibility barrel `openclaw/plugin-sdk/config-runtime`: `config-types` для типів, `plugin-config-runtime` для тверджень щодо вже завантаженої конфігурації та пошуку запису plugin, `runtime-config-snapshot` для поточних знімків процесу і `config-mutation` для записів. Тести вбудованих plugins мають mock-ати ці сфокусовані підшляхи напряму, а не широкий compatibility barrel. -Внутрішній runtime-код OpenClaw рухається в тому самому напрямку: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні записи мутації оновлюють runtime-знімок процесу й просувають його внутрішню ревізію; довготривалі кеші мають спиратися на runtime-власний ключ кешу, а не серіалізувати конфігурацію локально. Довготривалі runtime-модулі мають сканер із нульовою толерантністю до неявних викликів `loadConfig()`; використовуйте переданий `cfg`, `context.getRuntimeConfig()` запиту або `getRuntimeConfig()` на явній межі процесу. +Внутрішній runtime-код OpenClaw має той самий напрям: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні записи мутацій оновлюють runtime-знімок процесу й просувають його внутрішню ревізію; довгоживучі кеші мають спиратися на runtime-owned ключ кешу, а не серіалізувати конфігурацію локально. Для довгоживучих runtime-модулів діє сканер нульової терпимості до ambient-викликів `loadConfig()`; використовуйте переданий `cfg`, request `context.getRuntimeConfig()` або `getRuntimeConfig()` на явній межі процесу. -Шляхи виконання provider і каналу мають використовувати активний знімок runtime-конфігурації, а не файловий знімок, повернений для зворотного читання або редагування конфігурації. Файлові знімки зберігають вихідні значення, зокрема маркери SecretRef для UI та записів; callback-функціям provider потрібен розв’язаний runtime-перегляд. Коли допоміжну функцію можуть викликати як з активним вихідним знімком, так і з активним runtime-знімком, перед читанням облікових даних спрямовуйте через `selectApplicableRuntimeConfig()`. +Шляхи виконання провайдерів і каналів мають використовувати активний runtime-знімок конфігурації, а не файловий знімок, повернений для читання або редагування конфігурації. Файлові знімки зберігають початкові значення, як-от маркери SecretRef, для UI та записів; callback-функціям провайдера потрібне resolved runtime-представлення. Коли допоміжний засіб може бути викликаний або з активним source-знімком, або з активним runtime-знімком, перед читанням облікових даних маршрутизуйте через `selectApplicableRuntimeConfig()`. -## Простори імен runtime +## Runtime-простори імен - Ідентичність агента, каталоги та керування сеансами. + Ідентичність агента, каталоги та керування сесіями. ```typescript // Resolve the agent's working directory @@ -109,15 +104,15 @@ register(api) { }); ``` - `runEmbeddedAgent(...)` — нейтральна допоміжна функція для запуску звичайного ходу агента OpenClaw з коду plugin. Вона використовує те саме розв’язання provider/model і вибір agent-harness, що й відповіді, запущені каналом. + `runEmbeddedAgent(...)` — нейтральний допоміжний засіб для запуску звичайного ходу агента OpenClaw з коду plugin. Він використовує ту саму розв’язку провайдера/моделі й вибір agent-harness, що й відповіді, ініційовані каналом. - `runEmbeddedPiAgent(...)` залишається alias для сумісності. + `runEmbeddedPiAgent(...)` залишається alias сумісності. - `resolveThinkingPolicy(...)` повертає підтримувані рівні мислення provider/model і необов’язкове значення за замовчуванням. Provider plugins володіють профілем, специфічним для моделі, через свої thinking hooks, тому tool plugins мають викликати цю runtime-допоміжну функцію замість імпорту або дублювання списків provider. + `resolveThinkingPolicy(...)` повертає підтримувані рівні thinking для провайдера/моделі та необов’язкове значення за замовчуванням. Provider plugins володіють model-specific профілем через свої thinking hooks, тому tool plugins мають викликати цей runtime helper замість імпорту або дублювання списків провайдерів. - `normalizeThinkingLevel(...)` перетворює користувацький текст, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою щодо розв’язаної політики. + `normalizeThinkingLevel(...)` перетворює користувацький текст, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою щодо resolved policy. - **Допоміжні функції сховища сеансів** розміщені в `api.runtime.agent.session`: + **Допоміжні засоби сховища сесій** розміщені в `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -129,11 +124,11 @@ register(api) { const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId); ``` - Надавайте перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)` для runtime-записів. Вони проходять через writer сховища сеансів, яким володіє Gateway, зберігають паралельні оновлення та повторно використовують гарячий кеш. `saveSessionStore(...)` залишається доступним для сумісності та офлайн-перезаписів у стилі технічного обслуговування. + Надавайте перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)` для runtime-записів. Вони проходять через Gateway-owned writer сховища сесій, зберігають паралельні оновлення та повторно використовують гарячий кеш. `saveSessionStore(...)` залишається доступним для сумісності та offline maintenance-style перезаписів. - Константи моделі та provider за замовчуванням: + Константи моделі та провайдера за замовчуванням: ```typescript const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" @@ -170,14 +165,14 @@ register(api) { ``` - Перевизначення моделі (`provider`/`model`) потребують згоди оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються. + Перевизначення моделі (`provider`/`model`) потребують opt-in оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються. - `deleteSession(...)` може видаляти сеанси, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або операторських сеансів і надалі потребує запиту Gateway з admin-областю. + `deleteSession(...)` може видаляти сесії, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або operator sessions усе ще потребує admin-scoped запиту Gateway. - Перелічуйте підключені вузли та викликайте команду node-host з коду plugin, завантаженого Gateway, або з CLI-команд plugin. Використовуйте це, коли plugin володіє локальною роботою на спареному пристрої, наприклад браузером або аудіомостом на іншому Mac. + Перелічуйте підключені nodes і викликайте node-host command з Gateway-loaded коду plugin або з CLI-команд plugin. Використовуйте це, коли plugin володіє локальною роботою на спареному пристрої, наприклад браузером або audio bridge на іншому Mac. ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -190,13 +185,13 @@ register(api) { }); ``` - Усередині Gateway цей runtime працює в процесі. У CLI-командах plugin він викликає налаштований Gateway через RPC, тож такі команди, як `openclaw googlemeet recover-tab`, можуть перевіряти спарені вузли з термінала. Команди Node і надалі проходять звичайне pairing вузлів Gateway, allowlists команд, політики node-invoke plugin і локальну обробку команд на вузлі. + Усередині Gateway цей runtime є in-process. У CLI-командах plugin він викликає налаштований Gateway через RPC, тож команди на кшталт `openclaw googlemeet recover-tab` можуть перевіряти paired nodes з термінала. Node-команди все ще проходять через звичайне Gateway node pairing, allowlists команд, політики plugin node-invoke та node-local command handling. - Plugins, які відкривають небезпечні команди node-host, мають реєструвати політику node-invoke через `api.registerNodeInvokePolicy(...)`. Політика виконується в Gateway після перевірок allowlist команд і перед пересиланням команди до вузла, тож прямі виклики `node.invoke` і високорівневі інструменти plugin мають спільний шлях застосування правил. + Plugins, що відкривають небезпечні node-host commands, мають реєструвати node-invoke policy за допомогою `api.registerNodeInvokePolicy(...)`. Policy виконується в Gateway після перевірок allowlist команд і перед пересиланням команди до node, тож прямі виклики `node.invoke` і higher-level plugin tools мають той самий шлях enforcement. - Прив’яжіть runtime Task Flow до наявного ключа сеансу OpenClaw або довіреного контексту інструмента, а потім створюйте й керуйте Task Flows без передавання власника в кожному виклику. + Прив’яжіть runtime Task Flow до наявного ключа сесії OpenClaw або довіреного контексту інструмента, а потім створюйте й керуйте Task Flows без передавання owner у кожному виклику. ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -223,7 +218,7 @@ register(api) { }); ``` - Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли вже маєте довірений ключ сеансу OpenClaw з власного шару прив’язки. Не прив’язуйте з необробленого користувацького введення. + Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли у вас уже є довірений ключ сесії OpenClaw з вашого власного binding layer. Не прив’язуйте з необробленого введення користувача. @@ -249,7 +244,7 @@ register(api) { }); ``` - Використовує базову конфігурацію `messages.tts` і вибір provider. Повертає аудіобуфер PCM + частоту дискретизації. + Використовує core-конфігурацію `messages.tts` і вибір провайдера. Повертає PCM-аудіобуфер + частоту дискретизації. @@ -283,7 +278,7 @@ register(api) { }); ``` - Повертає `{ text: undefined }`, коли вихідні дані не створено (наприклад, пропущений вхід). + Повертає `{ text: undefined }`, коли не створено жодного виводу (наприклад, вхідні дані пропущено). `api.runtime.stt.transcribeAudioFile(...)` залишається сумісним псевдонімом для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`. @@ -342,9 +337,9 @@ register(api) { - Поточний знімок конфігурації runtime та транзакційні записи конфігурації. Надавайте перевагу - конфігурації, яку вже було передано в активний шлях виклику; використовуйте - `current()` лише тоді, коли обробнику потрібен безпосередньо знімок процесу. + Поточний знімок конфігурації runtime і транзакційні записи конфігурації. Надавайте перевагу + конфігурації, яку вже передано в активний шлях виклику; використовуйте + `current()` лише тоді, коли обробнику безпосередньо потрібен знімок процесу. ```typescript const cfg = api.runtime.config.current(); @@ -358,7 +353,7 @@ register(api) { `mutateConfigFile(...)` і `replaceConfigFile(...)` повертають значення `followUp`, наприклад `{ mode: "restart", requiresRestart: true, reason }`, - яке фіксує намір записувача, не забираючи керування перезапуском у + яке записує намір записувача, не забираючи керування перезапуском у gateway. @@ -367,7 +362,12 @@ register(api) { ```typescript await api.runtime.system.enqueueSystemEvent(event); - api.runtime.system.requestHeartbeatNow(); + api.runtime.system.requestHeartbeat({ + source: "other", + intent: "event", + reason: "plugin-event", + }); + api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Deprecated compatibility alias. const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts); const hint = api.runtime.system.formatNativeDependencyHint(pkg); ``` @@ -408,7 +408,7 @@ register(api) { - Розв’язання каталогу стану та сховище ключів на базі SQLite. + Визначення каталогу стану та сховище ключів на базі SQLite. ```typescript const stateDir = api.runtime.state.resolveStateDir(process.env); @@ -424,7 +424,7 @@ register(api) { await store.clear(); ``` - Сховища ключів переживають перезапуски й ізольовані за прив’язаним до runtime ідентифікатором Plugin. Обмеження: `maxEntries` на простір імен, 1 000 активних рядків на Plugin, значення JSON до 64 КБ і необов’язкове завершення строку дії за TTL. + Сховища ключів переживають перезапуски та ізольовані ідентифікатором plugin, прив’язаним до runtime. Обмеження: `maxEntries` на простір імен, 1 000 активних рядків на plugin, JSON-значення до 64 КБ і необов’язкове завершення строку дії TTL. У цьому випуску лише вбудовані plugins. @@ -442,7 +442,7 @@ register(api) { - Допоміжні засоби runtime для конкретних каналів (доступні, коли завантажено plugin каналу). + Допоміжні засоби runtime, специфічні для каналу (доступні, коли завантажено plugin каналу). `api.runtime.channel.mentions` — це спільна поверхня політики вхідних згадок для вбудованих plugins каналів, які використовують ін’єкцію runtime: @@ -479,17 +479,17 @@ register(api) { - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` навмисно не надає старі допоміжні засоби сумісності `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. + `api.runtime.channel.mentions` навмисно не надає старі сумісні допоміжні засоби `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. ## Зберігання посилань runtime -Використовуйте `createPluginRuntimeStore`, щоб зберігати посилання runtime для використання поза callback `register`: +Використовуйте `createPluginRuntimeStore`, щоб зберегти посилання runtime для використання поза callback `register`: - + ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; @@ -501,7 +501,7 @@ register(api) { ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -512,7 +512,7 @@ register(api) { }); ``` - + ```typescript export function getRuntime() { return store.getRuntime(); // throws if not initialized @@ -527,7 +527,7 @@ register(api) { -Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для нетипових випадків, коли одному plugin навмисно потрібно більше ніж один слот runtime. +Надавайте перевагу `pluginId` для ідентичності runtime-store. Низькорівнева форма `key` призначена для рідкісних випадків, коли одному plugin навмисно потрібно більше ніж один слот runtime. ## Інші поля верхнього рівня `api` @@ -535,29 +535,29 @@ register(api) { Окрім `api.runtime`, об’єкт API також надає: - Ідентифікатор Plugin. + Ідентифікатор plugin. - Відображувана назва Plugin. + Відображуване ім’я plugin. - Поточний знімок конфігурації (активний знімок runtime в пам’яті, коли доступний). + Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний). - Конфігурація конкретного Plugin з `plugins.entries..config`. + Конфігурація, специфічна для plugin, з `plugins.entries..config`. - Журналювач з областю дії (`debug`, `info`, `warn`, `error`). + Логер із заданою областю (`debug`, `info`, `warn`, `error`). - Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом. + Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним entry. - Розв’язати шлях відносно кореня plugin. + Визначити шлях відносно кореня plugin. ## Пов’язане -- [Внутрішні механізми Plugin](/uk/plugins/architecture) — модель можливостей і реєстр +- [Внутрішня архітектура plugin](/uk/plugins/architecture) — модель можливостей і реєстр - [Точки входу SDK](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` -- [Огляд SDK](/uk/plugins/sdk-overview) — довідка щодо підшляхів +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник підшляхів diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md index 2777f49bd..0c911ae91 100644 --- a/docs/uk/tools/index.md +++ b/docs/uk/tools/index.md @@ -1,24 +1,24 @@ --- read_when: - Ви хочете зрозуміти, які інструменти надає OpenClaw - - Потрібно налаштувати, дозволити або заборонити інструменти - - Ви обираєте між вбудованими інструментами, Skills і Plugin -summary: 'Огляд інструментів і Plugin OpenClaw: що може робити агент і як його розширювати' + - Вам потрібно налаштувати, дозволити або заборонити інструменти + - Ви обираєте між вбудованими інструментами, Skills і plugins +summary: 'Огляд інструментів і плагінів OpenClaw: що агент може робити та як його розширити' title: Інструменти та плагіни x-i18n: - generated_at: "2026-04-30T13:04:18Z" + generated_at: "2026-05-02T13:56:43Z" model: gpt-5.5 provider: openai - source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb + source_hash: 892eb520c14c13e4f55c80aa17ccd2578cc803796844c15cd71674cb2a0a8adf source_path: tools/index.md workflow: 16 --- -Усе, що агент робить поза генеруванням тексту, відбувається через **інструменти**. +Усе, що агент робить окрім генерування тексту, відбувається через **інструменти**. Інструменти — це спосіб, у який агент читає файли, виконує команди, переглядає веб, надсилає повідомлення та взаємодіє з пристроями. -## Інструменти, Skills і plugins +## Інструменти, Skills і плагіни OpenClaw має три рівні, які працюють разом: @@ -26,103 +26,109 @@ OpenClaw має три рівні, які працюють разом: Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`, `web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а - plugins можуть реєструвати додаткові. + плагіни можуть реєструвати додаткові. Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі. - - Skill — це markdown-файл (`SKILL.md`), який вставляється в системний prompt. - Skills дають агенту контекст, обмеження та покрокові вказівки для + + Skill — це markdown-файл (`SKILL.md`), який додається до системного промпта. + Skills надають агенту контекст, обмеження та покрокові вказівки для ефективного використання інструментів. Skills зберігаються у вашому робочому просторі, у спільних папках - або постачаються всередині plugins. + або постачаються всередині плагінів. [Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) - - Plugin — це пакет, який може реєструвати будь-яке поєднання можливостей: - канали, провайдерів моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, + + Плагін — це пакет, який може реєструвати будь-яке поєднання можливостей: + канали, постачальників моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео, - web fetch, web search та інше. Деякі plugins є **core** (постачаються з - OpenClaw), інші є **зовнішніми** (опубліковані спільнотою в npm). + отримання вебвмісту, вебпошук тощо. Деякі плагіни є **core** (постачаються з + OpenClaw), інші — **зовнішніми** (публікуються спільнотою в npm). - [Встановлення та налаштування plugins](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) + [Установлення та налаштування плагінів](/uk/tools/plugin) | [Створення власного](/uk/plugins/building-plugins) ## Вбудовані інструменти -Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких plugins: +Ці інструменти постачаються з OpenClaw і доступні без установлення будь-яких плагінів: -| Інструмент | Що він робить | Сторінка | -| ------------------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------- | -| `exec` / `process` | Виконання shell-команд, керування фоновими процесами | [Exec](/uk/tools/exec), [Схвалення Exec](/uk/tools/exec-approvals) | -| `code_execution` | Запуск ізольованого віддаленого аналізу Python | [Виконання коду](/uk/tools/code-execution) | -| `browser` | Керування браузером Chromium (перехід, клік, знімок екрана) | [Браузер](/uk/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Пошук у вебі, пошук дописів X, отримання вмісту сторінки | [Веб](/uk/tools/web), [Web Fetch](/uk/tools/web-fetch) | -| `read` / `write` / `edit` | Файлове введення/виведення в робочому просторі | | -| `apply_patch` | Багатофрагментні патчі файлів | [Apply Patch](/uk/tools/apply-patch) | -| `message` | Надсилання повідомлень у всіх каналах | [Надсилання агентом](/uk/tools/agent-send) | -| `canvas` | Керування node Canvas (present, eval, snapshot) | | -| `nodes` | Виявлення й вибір спарених пристроїв | | -| `cron` / `gateway` | Керування запланованими завданнями; перевірка, патчинг, перезапуск або оновлення gateway | | -| `image` / `image_generate` | Аналіз або генерація зображень | [Генерація зображень](/uk/tools/image-generation) | -| `music_generate` | Генерація музичних треків | [Генерація музики](/uk/tools/music-generation) | -| `video_generate` | Генерація відео | [Генерація відео](/uk/tools/video-generation) | -| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація під-агентів | [Під-агенти](/uk/tools/subagents) | -| `session_status` | Легке зчитування у стилі `/status` і перевизначення моделі сесії | [Інструменти сесій](/uk/concepts/session-tool) | +| Інструмент | Що він робить | Сторінка | +| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ | +| `exec` / `process` | Виконує shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Схвалення Exec](/uk/tools/exec-approvals) | +| `code_execution` | Виконує ізольований віддалений аналіз Python | [Виконання коду](/uk/tools/code-execution) | +| `browser` | Керує браузером Chromium (навігація, клацання, знімок екрана) | [Браузер](/uk/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Шукає в інтернеті, шукає дописи X, отримує вміст сторінок | [Веб](/uk/tools/web), [Отримання вебвмісту](/uk/tools/web-fetch) | +| `read` / `write` / `edit` | Файлове введення/виведення в робочому просторі | | +| `apply_patch` | Багатофрагментні патчі файлів | [Застосування патча](/uk/tools/apply-patch) | +| `message` | Надсилає повідомлення в усіх каналах | [Надсилання агентом](/uk/tools/agent-send) | +| `canvas` | Керує node Canvas (презентація, обчислення, знімок) | | +| `nodes` | Виявляє спарені пристрої та націлюється на них | | +| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює gateway | | +| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | +| `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) | +| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | +| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Керування сеансами, статус і оркестрація підагентів | [Підагенти](/uk/tools/subagents) | +| `session_status` | Легке зчитування у стилі `/status` і перевизначення моделі сеансу | [Інструменти сеансу](/uk/concepts/session-tool) | -Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого нестандартного провайдера зображень, спочатку налаштуйте auth/API key цього провайдера. +Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого нестандартного постачальника зображень, спершу налаштуйте автентифікацію/API-ключ цього постачальника. -Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого нестандартного провайдера музики, спочатку налаштуйте auth/API key цього провайдера. +Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого нестандартного постачальника музики, спершу налаштуйте автентифікацію/API-ключ цього постачальника. -Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нестандартного провайдера відео, спочатку налаштуйте auth/API key цього провайдера. +Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нестандартного постачальника відео, спершу налаштуйте автентифікацію/API-ключ цього постачальника. -Для workflow-керованої генерації аудіо використовуйте `music_generate`, коли plugin, наприклад -ComfyUI, реєструє його. Це окремо від `tts`, який є перетворенням тексту на мовлення. +Для генерації аудіо, керованої workflow, використовуйте `music_generate`, коли плагін, наприклад +ComfyUI, реєструє його. Це окремо від `tts`, який перетворює текст на мовлення. -`session_status` — це легкий інструмент статусу/зчитування у групі сесій. -Він відповідає на запитання у стилі `/status` про поточну сесію та може -за бажанням встановити перевизначення моделі для окремої сесії; `model=default` очищає це -перевизначення. Як і `/status`, він може дозаповнювати розріджені лічильники токенів/cache і +`session_status` — це легкий інструмент статусу/зчитування в групі сеансів. +Він відповідає на запитання у стилі `/status` про поточний сеанс і може +за потреби встановити перевизначення моделі для окремого сеансу; `model=default` очищає це +перевизначення. Як і `/status`, він може доповнювати розріджені лічильники токенів/кешу та мітку активної runtime-моделі з останнього запису використання в транскрипті. -`gateway` — це runtime-інструмент лише для власника для операцій gateway: +`gateway` — це runtime-інструмент лише для власника для операцій із gateway: -- `config.schema.lookup` для одного path-scoped піддерева конфігурації перед редагуванням -- `config.get` для поточного знімка конфігурації + hash +- `config.schema.lookup` для одного обмеженого шляхом піддерева конфігурації перед редагуванням +- `config.get` для поточного знімка конфігурації + хешу - `config.patch` для часткових оновлень конфігурації з перезапуском -- `config.apply` лише для повної заміни конфігурації -- `update.run` для явного самостійного оновлення + перезапуску +- `config.apply` лише для заміни повної конфігурації +- `update.run` для явного самооновлення + перезапуску -Для часткових змін віддавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте +Для часткових змін надавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте `config.apply` лише тоді, коли ви навмисно замінюєте всю конфігурацію. -Для ширшої документації конфігурації прочитайте [Конфігурація](/uk/gateway/configuration) і +Докладнішу документацію з конфігурації див. у [Конфігурація](/uk/gateway/configuration) та [Довідник конфігурації](/uk/gateway/configuration-reference). Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec. -### Інструменти, надані plugins +### Інструменти, надані Plugin -Plugins можуть реєструвати додаткові інструменти. Деякі приклади: +Plugins можуть реєструвати додаткові інструменти. Кілька прикладів: -- [Diffs](/uk/tools/diffs) — переглядач і рендерер diff -- [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу -- [Lobster](/uk/tools/lobster) — типізований runtime workflow з відновлюваними схваленнями -- [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` із workflow-backed провайдерами -- [OpenProse](/uk/prose) — markdown-first оркестрація workflow -- [Tokenjuice](/uk/tools/tokenjuice) — ущільнення шумних результатів інструментів `exec` і `bash` +- [Відмінності](/uk/tools/diffs) — переглядач і рендерер відмінностей +- [Завдання LLM](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу +- [Lobster](/uk/tools/lobster) — типізоване середовище виконання робочих процесів із відновлюваними затвердженнями +- [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` з провайдерами на основі робочих процесів +- [OpenProse](/uk/prose) — оркестрація робочих процесів із пріоритетом markdown +- [Tokenjuice](/uk/tools/tokenjuice) — стискає шумні результати інструментів `exec` і `bash` -## Налаштування інструментів +Інструменти Plugin все ще створюються за допомогою `api.registerTool(...)` і оголошуються в +списку `contracts.tools` маніфесту Plugin. OpenClaw фіксує перевірений +дескриптор інструмента під час виявлення та кешує його за джерелом Plugin і контрактом, тому +подальше планування інструментів може пропускати завантаження runtime Plugin. Виконання інструмента все ще завантажує +власний Plugin і викликає живу зареєстровану реалізацію. -### Списки дозволів і заборон +## Конфігурація інструментів -Керуйте тим, які інструменти агент може викликати, через `tools.allow` / `tools.deny` у +### Списки дозволу й заборони + +Керуйте тим, які інструменти агент може викликати через `tools.allow` / `tools.deny` у конфігурації. Заборона завжди має перевагу над дозволом. ```json5 @@ -134,46 +140,46 @@ Plugins можуть реєструвати додаткові інструме } ``` -OpenClaw зупиняється без доступу, коли явний allowlist не знаходить жодного викликаного інструмента. -Наприклад, `tools.allow: ["query_db"]` працює лише якщо завантажений plugin фактично -реєструє `query_db`. Якщо жоден вбудований, plugin або bundled MCP інструмент не відповідає -allowlist, виконання зупиняється до виклику моделі, замість того щоб продовжувати як -text-only виконання, яке могло б вигадати результати інструментів. +OpenClaw завершує роботу без доступу, коли явний список дозволів не відповідає жодним викликаним інструментам. +Наприклад, `tools.allow: ["query_db"]` працює лише якщо завантажений Plugin справді +реєструє `query_db`. Якщо жоден вбудований інструмент, Plugin або вбудований у пакет MCP-інструмент не відповідає +списку дозволів, запуск зупиняється до виклику моделі, замість того щоб продовжуватися як +текстовий запуск, який міг би вигадати результати інструментів. ### Профілі інструментів -`tools.profile` встановлює базовий allowlist перед застосуванням `allow`/`deny`. +`tools.profile` задає базовий список дозволів до застосування `allow`/`deny`. Перевизначення для окремого агента: `agents.list[].tools.profile`. -| Профіль | Що він містить | +| Профіль | Що він включає | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `full` | Необмежена базова конфігурація для ширшого доступу до команд/керування; те саме, що залишити `tools.profile` невстановленим | +| `full` | Необмежена базова конфігурація для ширшого доступу до команд і керування; те саме, що залишити `tools.profile` незаданим | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `minimal` | Лише `session_status` | `tools.profile: "messaging"` навмисно вузький для агентів, зосереджених на каналах. -Він не включає ширші інструменти команд/керування, як-от файлова система, runtime, -браузер, canvas, nodes, cron і керування gateway. Використовуйте `tools.profile: "full"` -як необмежену базову конфігурацію для ширшого доступу до команд/керування, а потім звужуйте +Він не включає ширші інструменти команд і керування, як-от файлова система, runtime, +браузер, canvas, вузли, cron і керування Gateway. Використовуйте `tools.profile: "full"` +як необмежену базову конфігурацію для ширшого доступу до команд і керування, а потім скорочуйте доступ за допомогою `tools.allow` / `tools.deny`, коли потрібно. -`coding` включає легкі веб-інструменти (`web_search`, `web_fetch`, `x_search`), +`coding` включає легкі вебінструменти (`web_search`, `web_fetch`, `x_search`), але не повний інструмент керування браузером. Автоматизація браузера може керувати реальними -сесіями та профілями з входом у систему, тому додайте її явно через +сесіями та профілями з виконаним входом, тому додайте її явно за допомогою `tools.alsoAllow: ["browser"]` або для окремого агента `agents.list[].tools.alsoAllow: ["browser"]`. -Налаштування `tools.exec` або `tools.fs` під обмежувальним профілем (`messaging`, `minimal`) не розширює allowlist профілю неявно. Додавайте явні записи `tools.alsoAllow` (наприклад, `["exec", "process"]` для exec або `["read", "write", "edit"]` для fs), коли хочете, щоб обмежувальний профіль використовував ці налаштовані секції. OpenClaw записує startup-попередження, коли секція конфігурації наявна без відповідного дозволу `alsoAllow`. +Налаштування `tools.exec` або `tools.fs` під обмежувальним профілем (`messaging`, `minimal`) не розширює неявно список дозволів профілю. Додайте явні записи `tools.alsoAllow` (наприклад, `["exec", "process"]` для exec або `["read", "write", "edit"]` для fs), коли хочете, щоб обмежувальний профіль використовував ці налаштовані розділи. OpenClaw реєструє попередження під час запуску, коли розділ конфігурації присутній без відповідного дозволу `alsoAllow`. -Профілі `coding` і `messaging` також дозволяють налаштовані bundle MCP інструменти -під ключем plugin `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли -хочете, щоб профіль зберігав свої звичайні вбудовані інструменти, але приховував усі налаштовані MCP інструменти. -Профіль `minimal` не включає bundle MCP інструменти. +Профілі `coding` і `messaging` також дозволяють налаштовані пакетні MCP-інструменти +під ключем Plugin `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли +хочете, щоб профіль зберігав свої звичайні вбудовані інструменти, але приховував усі налаштовані MCP-інструменти. +Профіль `minimal` не включає пакетні MCP-інструменти. Приклад (найширша поверхня інструментів за замовчуванням): @@ -187,9 +193,9 @@ text-only виконання, яке могло б вигадати резуль ### Групи інструментів -Використовуйте скорочення `group:*` у списках allow/deny: +Використовуйте скорочення `group:*` у списках дозволу/заборони: -| Група | Інструменти | +| Група | Інструменти | | ------------------ | --------------------------------------------------------------------------------------------------------- | | `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | | `group:fs` | read, write, edit, apply_patch | @@ -202,22 +208,22 @@ text-only виконання, яке могло б вигадати резуль | `group:nodes` | nodes | | `group:agents` | agents_list | | `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Усі вбудовані інструменти OpenClaw (без інструментів Plugin) | +| `group:openclaw` | Усі вбудовані інструменти OpenClaw (за винятком інструментів Plugin) | -`sessions_history` повертає обмежене, відфільтроване з міркувань безпеки подання згадування. Воно вилучає -теги міркувань, службовий каркас ``, XML-навантаження викликів інструментів у відкритому тексті +`sessions_history` повертає обмежений, відфільтрований з міркувань безпеки вигляд пригадування. Він вилучає +теги мислення, каркас ``, простотекстові XML-корисні навантаження викликів інструментів (зокрема `...`, `...`, `...`, -`...` і обрізані блоки викликів інструментів), -понижений службовий каркас викликів інструментів, витеклі ASCII-/повноширинні керівні +`...` і скорочені блоки викликів інструментів), +знижений каркас викликів інструментів, витіклі ASCII/повноширинні керівні токени моделі та некоректний XML викликів інструментів MiniMax із тексту асистента, а потім застосовує -редагування/обрізання й можливі заповнювачі для завеликих рядків замість того, щоб діяти +редагування/усічення та, за потреби, заповнювачі для надмірно великих рядків замість того, щоб діяти як сирий дамп стенограми. -### Обмеження, специфічні для провайдера +### Обмеження для окремих провайдерів -Використовуйте `tools.byProvider`, щоб обмежити інструменти для конкретних провайдерів без -зміни глобальних стандартних значень: +Використовуйте `tools.byProvider`, щоб обмежувати інструменти для окремих провайдерів без +зміни глобальних стандартних налаштувань: ```json5 {