chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
2d6ef795f3
commit
d32062ba16
@ -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 <package-name>`. OpenClaw спершу пробує ClawHub і
|
||||
`openclaw plugins install <package-name>`. 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?
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Плагін каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
<Card title="Plugin каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
</Card>
|
||||
<Card title="Плагін провайдера" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Додайте провайдера моделей (LLM, проксі або власний endpoint)
|
||||
<Card title="Plugin провайдера" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Додайте провайдера моделей (LLM, проксі або власну кінцеву точку)
|
||||
</Card>
|
||||
<Card title="Плагін інструмента / hook" icon="wrench" href="/uk/plugins/hooks">
|
||||
<Card title="Plugin інструменту / hook" icon="wrench" href="/uk/plugins/hooks">
|
||||
Зареєструйте інструменти агента, event hooks або сервіси — продовжуйте нижче
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Для плагіна каналу, який не гарантовано буде встановлено під час запуску 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 каналів
|
||||
і провайдерів є окремі посібники, посилання на які наведено вище.
|
||||
|
||||
<Steps>
|
||||
@ -99,12 +99,12 @@ x-i18n:
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Кожному плагіну потрібен 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/`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -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).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Протестуйте й опублікуйте">
|
||||
|
||||
**Зовнішні плагіни:** перевірте та опублікуйте через 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 -- <bundled-plugin-root>/my-plugin/
|
||||
@ -161,70 +161,70 @@ x-i18n:
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Можливості плагіна
|
||||
## Можливості 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/<bundled-id>` досі існують для
|
||||
супроводу вбудованих plugin, коли для них відстежується використання власником. Вважайте їх
|
||||
зарезервованими поверхнями, а не типовим шаблоном для нових сторонніх plugins.
|
||||
Деякі згенеровані допоміжні seam `openclaw/plugin-sdk/<bundled-id>` досі існують для
|
||||
супроводу вбудованих plugins, коли для них відстежується використання власником. Сприймайте їх як
|
||||
зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins.
|
||||
|
||||
## Контрольний список перед поданням
|
||||
|
||||
<Check>**package.json** має коректні метадані `openclaw`</Check>
|
||||
<Check>**package.json** має правильні метадані `openclaw`</Check>
|
||||
<Check>Маніфест **openclaw.plugin.json** наявний і валідний</Check>
|
||||
<Check>Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry`</Check>
|
||||
<Check>Усі імпорти використовують сфокусовані шляхи `plugin-sdk/<subpath>`</Check>
|
||||
<Check>Внутрішні імпорти використовують локальні модулі, а не самоімпорти SDK</Check>
|
||||
<Check>Тести проходять (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` проходить (для plugins у репозиторії)</Check>
|
||||
<Check>`pnpm check` проходить (plugins усередині репозиторію)</Check>
|
||||
|
||||
## Тестування 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: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на 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: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue як у PR, так і у своїй гілці Discord. Контриб’ютори не можуть ставити мітки на PR, тому назва є сигналом з боку PR для мейнтейнерів і автоматизації. Блокери з PR зливаються; блокери без PR можуть усе одно потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування.
|
||||
6. Мовчання означає зелений статус. Якщо ви пропустите це вікно, ваше виправлення, ймовірно, потрапить у наступний цикл.
|
||||
|
||||
## Наступні кроки
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel Plugins" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Створити plugin каналу повідомлень
|
||||
Створіть plugin каналу повідомлень
|
||||
</Card>
|
||||
<Card title="Provider Plugins" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Створити plugin провайдера моделей
|
||||
Створіть plugin провайдера моделей
|
||||
</Card>
|
||||
<Card title="Огляд SDK" icon="book-open" href="/uk/plugins/sdk-overview">
|
||||
Мапа імпортів і довідник API реєстрації
|
||||
Карта імпортів і довідник API реєстрації
|
||||
</Card>
|
||||
<Card title="Допоміжні засоби середовища виконання" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
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 каналів
|
||||
|
||||
@ -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 під час реєстрації. Використовуйте ці допоміжні засоби замість прямого імпорту внутрішніх модулів хоста.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel plugins" href="/uk/plugins/sdk-channel-plugins">
|
||||
Покроковий посібник, який показує використання цих допоміжних функцій у контексті для channel plugins.
|
||||
Покроковий посібник, який показує використання цих допоміжних засобів у контексті для channel plugins.
|
||||
</Card>
|
||||
<Card title="Provider plugins" href="/uk/plugins/sdk-provider-plugins">
|
||||
Покроковий посібник, який показує використання цих допоміжних функцій у контексті для provider plugins.
|
||||
Покроковий посібник, який показує використання цих допоміжних засобів у контексті для provider plugins.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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-простори імен
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="api.runtime.agent">
|
||||
Ідентичність агента, каталоги та керування сеансами.
|
||||
Ідентичність агента, каталоги та керування сесіями.
|
||||
|
||||
```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 перезаписів.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.agent.defaults">
|
||||
Константи моделі та provider за замовчуванням:
|
||||
Константи моделі та провайдера за замовчуванням:
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
@ -170,14 +165,14 @@ register(api) {
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Перевизначення моделі (`provider`/`model`) потребують згоди оператора через `plugins.entries.<id>.subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються.
|
||||
Перевизначення моделі (`provider`/`model`) потребують opt-in оператора через `plugins.entries.<id>.subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються.
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` може видаляти сеанси, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або операторських сеансів і надалі потребує запиту Gateway з admin-областю.
|
||||
`deleteSession(...)` може видаляти сесії, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або operator sessions усе ще потребує admin-scoped запиту Gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
Перелічуйте підключені вузли та викликайте команду 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tasks.managedFlows">
|
||||
Прив’яжіть 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. Не прив’язуйте з необробленого введення користувача.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
@ -249,7 +244,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
Використовує базову конфігурацію `messages.tts` і вибір provider. Повертає аудіобуфер PCM + частоту дискретизації.
|
||||
Використовує core-конфігурацію `messages.tts` і вибір провайдера. Повертає PCM-аудіобуфер + частоту дискретизації.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.mediaUnderstanding">
|
||||
@ -283,7 +278,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
Повертає `{ text: undefined }`, коли вихідні дані не створено (наприклад, пропущений вхід).
|
||||
Повертає `{ text: undefined }`, коли не створено жодного виводу (наприклад, вхідні дані пропущено).
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` залишається сумісним псевдонімом для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
@ -342,9 +337,9 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.config">
|
||||
Поточний знімок конфігурації 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.
|
||||
|
||||
</Accordion>
|
||||
@ -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) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.state">
|
||||
Розв’язання каталогу стану та сховище ключів на базі 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.
|
||||
|
||||
<Warning>
|
||||
У цьому випуску лише вбудовані plugins.
|
||||
@ -442,7 +442,7 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
Допоміжні засоби 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 }`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Зберігання посилань runtime
|
||||
|
||||
Використовуйте `createPluginRuntimeStore`, щоб зберігати посилання runtime для використання поза callback `register`:
|
||||
Використовуйте `createPluginRuntimeStore`, щоб зберегти посилання runtime для використання поза callback `register`:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть сховище">
|
||||
<Step title="Create the store">
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -501,7 +501,7 @@ register(api) {
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Під’єднайте до точки входу">
|
||||
<Step title="Wire into the entry point">
|
||||
```typescript
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
@ -512,7 +512,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
</Step>
|
||||
<Step title="Доступ з інших файлів">
|
||||
<Step title="Access from other files">
|
||||
```typescript
|
||||
export function getRuntime() {
|
||||
return store.getRuntime(); // throws if not initialized
|
||||
@ -527,7 +527,7 @@ register(api) {
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для нетипових випадків, коли одному plugin навмисно потрібно більше ніж один слот runtime.
|
||||
Надавайте перевагу `pluginId` для ідентичності runtime-store. Низькорівнева форма `key` призначена для рідкісних випадків, коли одному plugin навмисно потрібно більше ніж один слот runtime.
|
||||
</Note>
|
||||
|
||||
## Інші поля верхнього рівня `api`
|
||||
@ -535,29 +535,29 @@ register(api) {
|
||||
Окрім `api.runtime`, об’єкт API також надає:
|
||||
|
||||
<ParamField path="api.id" type="string">
|
||||
Ідентифікатор Plugin.
|
||||
Ідентифікатор plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.name" type="string">
|
||||
Відображувана назва Plugin.
|
||||
Відображуване ім’я plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
Поточний знімок конфігурації (активний знімок runtime в пам’яті, коли доступний).
|
||||
Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний).
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
Конфігурація конкретного Plugin з `plugins.entries.<id>.config`.
|
||||
Конфігурація, специфічна для plugin, з `plugins.entries.<id>.config`.
|
||||
</ParamField>
|
||||
<ParamField path="api.logger" type="PluginLogger">
|
||||
Журналювач з областю дії (`debug`, `info`, `warn`, `error`).
|
||||
Логер із заданою областю (`debug`, `info`, `warn`, `error`).
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом.
|
||||
Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним entry.
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
Розв’язати шлях відносно кореня plugin.
|
||||
Визначити шлях відносно кореня plugin.
|
||||
</ParamField>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Внутрішні механізми Plugin](/uk/plugins/architecture) — модель можливостей і реєстр
|
||||
- [Внутрішня архітектура plugin](/uk/plugins/architecture) — модель можливостей і реєстр
|
||||
- [Точки входу SDK](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry`
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідка щодо підшляхів
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник підшляхів
|
||||
|
||||
@ -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 має три рівні, які працюють разом:
|
||||
<Step title="Інструменти — це те, що викликає агент">
|
||||
Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`,
|
||||
`web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а
|
||||
plugins можуть реєструвати додаткові.
|
||||
плагіни можуть реєструвати додаткові.
|
||||
|
||||
Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Skills навчають агента, коли і як діяти">
|
||||
Skill — це markdown-файл (`SKILL.md`), який вставляється в системний prompt.
|
||||
Skills дають агенту контекст, обмеження та покрокові вказівки для
|
||||
<Step title="Skills навчають агента коли і як діяти">
|
||||
Skill — це markdown-файл (`SKILL.md`), який додається до системного промпта.
|
||||
Skills надають агенту контекст, обмеження та покрокові вказівки для
|
||||
ефективного використання інструментів. Skills зберігаються у вашому робочому просторі, у спільних папках
|
||||
або постачаються всередині plugins.
|
||||
або постачаються всередині плагінів.
|
||||
|
||||
[Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills)
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Plugins пакують усе разом">
|
||||
Plugin — це пакет, який може реєструвати будь-яке поєднання можливостей:
|
||||
канали, провайдерів моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі,
|
||||
<Step title="Плагіни пакують усе разом">
|
||||
Плагін — це пакет, який може реєструвати будь-яке поєднання можливостей:
|
||||
канали, постачальників моделей, інструменти, 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)
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Вбудовані інструменти
|
||||
|
||||
Ці інструменти постачаються з 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` |
|
||||
|
||||
<Note>
|
||||
`tools.profile: "messaging"` навмисно вузький для агентів, зосереджених на каналах.
|
||||
Він не включає ширші інструменти команд/керування, як-от файлова система, runtime,
|
||||
браузер, canvas, nodes, cron і керування gateway. Використовуйте `tools.profile: "full"`
|
||||
як необмежену базову конфігурацію для ширшого доступу до команд/керування, а потім звужуйте
|
||||
Він не включає ширші інструменти команд і керування, як-от файлова система, runtime,
|
||||
браузер, canvas, вузли, cron і керування Gateway. Використовуйте `tools.profile: "full"`
|
||||
як необмежену базову конфігурацію для ширшого доступу до команд і керування, а потім скорочуйте
|
||||
доступ за допомогою `tools.allow` / `tools.deny`, коли потрібно.
|
||||
</Note>
|
||||
|
||||
`coding` включає легкі веб-інструменти (`web_search`, `web_fetch`, `x_search`),
|
||||
`coding` включає легкі вебінструменти (`web_search`, `web_fetch`, `x_search`),
|
||||
але не повний інструмент керування браузером. Автоматизація браузера може керувати реальними
|
||||
сесіями та профілями з входом у систему, тому додайте її явно через
|
||||
сесіями та профілями з виконаним входом, тому додайте її явно за допомогою
|
||||
`tools.alsoAllow: ["browser"]` або для окремого агента
|
||||
`agents.list[].tools.alsoAllow: ["browser"]`.
|
||||
|
||||
<Note>
|
||||
Налаштування `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`.
|
||||
</Note>
|
||||
|
||||
Профілі `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` повертає обмежене, відфільтроване з міркувань безпеки подання згадування. Воно вилучає
|
||||
теги міркувань, службовий каркас `<relevant-memories>`, XML-навантаження викликів інструментів у відкритому тексті
|
||||
`sessions_history` повертає обмежений, відфільтрований з міркувань безпеки вигляд пригадування. Він вилучає
|
||||
теги мислення, каркас `<relevant-memories>`, простотекстові XML-корисні навантаження викликів інструментів
|
||||
(зокрема `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
|
||||
`<function_calls>...</function_calls>` і обрізані блоки викликів інструментів),
|
||||
понижений службовий каркас викликів інструментів, витеклі ASCII-/повноширинні керівні
|
||||
`<function_calls>...</function_calls>` і скорочені блоки викликів інструментів),
|
||||
знижений каркас викликів інструментів, витіклі ASCII/повноширинні керівні
|
||||
токени моделі та некоректний XML викликів інструментів MiniMax із тексту асистента, а потім застосовує
|
||||
редагування/обрізання й можливі заповнювачі для завеликих рядків замість того, щоб діяти
|
||||
редагування/усічення та, за потреби, заповнювачі для надмірно великих рядків замість того, щоб діяти
|
||||
як сирий дамп стенограми.
|
||||
|
||||
### Обмеження, специфічні для провайдера
|
||||
### Обмеження для окремих провайдерів
|
||||
|
||||
Використовуйте `tools.byProvider`, щоб обмежити інструменти для конкретних провайдерів без
|
||||
зміни глобальних стандартних значень:
|
||||
Використовуйте `tools.byProvider`, щоб обмежувати інструменти для окремих провайдерів без
|
||||
зміни глобальних стандартних налаштувань:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user