chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
330945deeb
commit
2a8a1f6436
@ -1,65 +1,66 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете створити новий OpenClaw Plugin
|
||||
- Вам потрібен короткий посібник для швидкого старту з розробки Plugin
|
||||
- Ви хочете створити новий Plugin OpenClaw
|
||||
- Вам потрібен посібник зі швидкого старту для розробки Plugin
|
||||
- Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw
|
||||
sidebarTitle: Getting Started
|
||||
summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини
|
||||
title: Створення Pluginів
|
||||
summary: Створіть свій перший Plugin OpenClaw за лічені хвилини
|
||||
title: Створення Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T19:11:07Z"
|
||||
generated_at: "2026-05-03T23:46:11Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1
|
||||
source_hash: 3e6c55c551629da54b3f150ce6299694186fe4434cfd7978a2d43d175d33a5d9
|
||||
source_path: plugins/building-plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Plugins розширюють OpenClaw новими можливостями: каналами, провайдерами моделей,
|
||||
мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень,
|
||||
генерацією відео, web fetch, web search, інструментами агента або будь-якою
|
||||
комбінацією.
|
||||
Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей,
|
||||
мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння
|
||||
медіа, генерація зображень, генерація відео, web fetch, web search, інструменти
|
||||
агента або будь-яке поєднання.
|
||||
|
||||
Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте його в
|
||||
[ClawHub](/uk/tools/clawhub), а користувачі встановлять за допомогою
|
||||
`openclaw plugins install clawhub:<package-name>`. Bare package specs усе ще
|
||||
встановлюються з npm під час launch cutover.
|
||||
[ClawHub](/uk/tools/clawhub), і користувачі встановлять його за допомогою
|
||||
`openclaw plugins install clawhub:<package-name>`. Голі специфікації пакетів усе
|
||||
ще встановлюються з npm під час перехідного запуску.
|
||||
|
||||
## Передумови
|
||||
|
||||
- Node >= 22 і менеджер пакетів (npm або pnpm)
|
||||
- Знайомство з TypeScript (ESM)
|
||||
- Для plugins у репозиторії: репозиторій клоновано і виконано `pnpm install`. Розробка plugin з
|
||||
source checkout підтримується лише з pnpm, бо OpenClaw завантажує bundled
|
||||
plugins з workspace-пакетів `extensions/*`.
|
||||
- Для plugins у репозиторії: репозиторій клоновано й виконано `pnpm install`.
|
||||
Розробка plugins у вихідному checkout підтримує лише pnpm, тому що OpenClaw
|
||||
завантажує вбудовані plugins із workspace-пакетів `extensions/*`.
|
||||
|
||||
## Який тип plugin?
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Channel plugin" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
<Card title="Plugin каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Під’єднайте OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
</Card>
|
||||
<Card title="Provider plugin" 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="Tool / hook plugin" icon="wrench" href="/uk/plugins/hooks">
|
||||
<Card title="Plugin інструментів / hooks" icon="wrench" href="/uk/plugins/hooks">
|
||||
Зареєструйте інструменти агента, event hooks або сервіси — продовжуйте нижче
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Для channel plugin, який не гарантовано буде встановлено під час onboarding/setup,
|
||||
Для plugin каналу, який не гарантовано встановлено під час onboarding/setup,
|
||||
використовуйте `createOptionalChannelSetupSurface(...)` з
|
||||
`openclaw/plugin-sdk/channel-setup`. Він створює пару setup adapter + wizard,
|
||||
яка повідомляє про вимогу встановлення і fail closed для реальних записів конфігурації,
|
||||
доки plugin не встановлено.
|
||||
`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування і
|
||||
майстра, яка повідомляє про вимогу встановлення та закрито завершується з
|
||||
помилкою під час реальних записів конфігурації, доки plugin не буде встановлено.
|
||||
|
||||
## Швидкий старт: tool plugin
|
||||
## Швидкий старт: plugin інструментів
|
||||
|
||||
У цьому покроковому прикладі створюється мінімальний plugin, який реєструє інструмент агента. Channel
|
||||
і provider plugins мають окремі посібники, посилання на які наведено вище.
|
||||
Цей покроковий посібник створює мінімальний plugin, який реєструє інструмент
|
||||
агента. Plugins каналів і провайдерів мають окремі посібники, посилання на які
|
||||
наведено вище.
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть пакет і manifest">
|
||||
<Step title="Створіть пакет і маніфест">
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
{
|
||||
@ -99,16 +100,17 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Кожному plugin потрібен manifest, навіть без конфігурації. Інструменти, зареєстровані під час runtime,
|
||||
мають бути перелічені в `contracts.tools`, щоб OpenClaw міг виявити власника
|
||||
plugin без завантаження runtime кожного plugin. Plugins також мають навмисно оголошувати
|
||||
`activation.onStartup`. У цьому прикладі встановлено `true`. Див.
|
||||
[Manifest](/uk/plugins/manifest) для повної schema. Канонічні фрагменти публікації в ClawHub
|
||||
розміщені в `docs/snippets/plugin-publish/`.
|
||||
Кожному plugin потрібен маніфест, навіть без конфігурації. Інструменти,
|
||||
зареєстровані під час виконання, мають бути перелічені в `contracts.tools`,
|
||||
щоб OpenClaw міг знайти власний plugin без завантаження runtime кожного
|
||||
plugin. Plugins також мають свідомо оголошувати `activation.onStartup`. У
|
||||
цьому прикладі встановлено `true`. Повну схему див. у
|
||||
[Маніфесті](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub
|
||||
містяться в `docs/snippets/plugin-publish/`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Напишіть entry point">
|
||||
<Step title="Напишіть точку входу">
|
||||
|
||||
```typescript
|
||||
// index.ts
|
||||
@ -132,15 +134,16 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
});
|
||||
```
|
||||
|
||||
`definePluginEntry` призначено для не-channel plugins. Для каналів використовуйте
|
||||
`defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins).
|
||||
Повні параметри entry point див. у [Entry Points](/uk/plugins/sdk-entrypoints).
|
||||
`definePluginEntry` призначено для plugins, що не є каналами. Для каналів
|
||||
використовуйте `defineChannelPluginEntry` — див.
|
||||
[Plugins каналів](/uk/plugins/sdk-channel-plugins). Повні параметри точки входу
|
||||
див. у [Точках входу](/uk/plugins/sdk-entrypoints).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Протестуйте й опублікуйте">
|
||||
|
||||
**Зовнішні plugins:** перевірте й опублікуйте через ClawHub, потім встановіть:
|
||||
**Зовнішні plugins:** перевірте й опублікуйте за допомогою ClawHub, потім установіть:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
@ -148,10 +151,11 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
Bare package specs на кшталт `@myorg/openclaw-my-plugin` встановлюються з npm під час
|
||||
launch cutover. Використовуйте `clawhub:`, коли потрібне resolution через ClawHub.
|
||||
Голі специфікації пакетів, як-от `@myorg/openclaw-my-plugin`, встановлюються
|
||||
з npm під час перехідного запуску. Використовуйте `clawhub:`, коли потрібне
|
||||
розв’язання через ClawHub.
|
||||
|
||||
**Plugins у репозиторії:** розмістіть під деревом bundled plugin workspace — їх буде автоматично виявлено.
|
||||
**Plugins у репозиторії:** розмістіть під деревом workspace вбудованих plugins — їх буде виявлено автоматично.
|
||||
|
||||
```bash
|
||||
pnpm test -- <bundled-plugin-root>/my-plugin/
|
||||
@ -160,70 +164,73 @@ Plugins розширюють OpenClaw новими можливостями: к
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Можливості Plugin
|
||||
## Можливості plugin
|
||||
|
||||
Один plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`:
|
||||
|
||||
| Можливість | Метод реєстрації | Докладний посібник |
|
||||
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
|
||||
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
|
||||
| Backend для CLI inference | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) |
|
||||
| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
|
||||
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) |
|
||||
| Інструменти агента | `api.registerTool(...)` | Нижче |
|
||||
| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Hooks Plugin | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) |
|
||||
| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/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) |
|
||||
| Web fetch | `api.registerWebFetchProvider(...)` | [Plugins провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web search | `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(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) |
|
||||
| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) |
|
||||
| Внутрішні event hooks | `api.registerHook(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) |
|
||||
| Підкоманди CLI | `api.registerCli(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) |
|
||||
|
||||
Повний registration API див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api).
|
||||
Повний API реєстрації див. в [Огляді SDK](/uk/plugins/sdk-overview#registration-api).
|
||||
|
||||
Bundled plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм
|
||||
потрібне асинхронне переписування результатів інструментів до того, як модель побачить output. Оголосіть
|
||||
цільові runtimes у `contracts.agentToolResultMiddleware`, наприклад
|
||||
`["pi", "codex"]`. Це довірений seam для bundled-plugin; зовнішнім
|
||||
plugins варто надавати перевагу звичайним hooks OpenClaw plugin, якщо OpenClaw не додасть
|
||||
явну trust policy для цієї можливості.
|
||||
Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм
|
||||
потрібне асинхронне переписування результатів інструментів до того, як модель
|
||||
побачить вивід. Оголосіть цільові runtimes у
|
||||
`contracts.agentToolResultMiddleware`, наприклад `["pi", "codex"]`. Це довірений
|
||||
seam вбудованого plugin; зовнішнім plugins варто надавати перевагу звичайним
|
||||
OpenClaw plugin hooks, доки OpenClaw не отримає явну політику довіри для цієї
|
||||
можливості.
|
||||
|
||||
Якщо ваш plugin реєструє власні Gateway RPC-методи, тримайте їх на
|
||||
префіксі, специфічному для plugin. Core admin namespaces (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) лишаються зарезервованими й завжди resolve до
|
||||
`operator.admin`, навіть якщо plugin просить вужчий scope.
|
||||
Якщо ваш plugin реєструє користувацькі RPC-методи Gateway, тримайте їх на
|
||||
префіксі, специфічному для plugin. Основні admin namespaces (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди
|
||||
розв’язуються до `operator.admin`, навіть якщо plugin запитує вужчу область.
|
||||
|
||||
Семантика hook guard, яку варто пам’ятати:
|
||||
Семантика захисників hooks, про яку варто пам’ятати:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є terminal і зупиняє handlers із нижчим priority.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним і зупиняє handlers із нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` трактується як відсутність рішення.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й просить користувача підтвердити дію через exec approval overlay, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є terminal і зупиняє handlers із нижчим priority.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через overlay схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є термінальним і зупиняє handlers із нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` трактується як відсутність рішення.
|
||||
- `message_sending`: `{ cancel: true }` є terminal і зупиняє handlers із нижчим priority.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним і зупиняє handlers із нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` трактується як відсутність рішення.
|
||||
- `message_received`: надавайте перевагу typed полю `threadId`, коли потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для channel-specific додаткових даних.
|
||||
- `message_sending`: надавайте перевагу typed полям маршрутизації `replyToId` / `threadId` замість channel-specific metadata keys.
|
||||
- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для додаткових даних, специфічних для каналу.
|
||||
- `message_sending`: віддавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId` над ключами metadata, специфічними для каналу.
|
||||
|
||||
Команда `/approve` обробляє як exec, так і plugin approvals з обмеженим fallback: коли exec approval id не знайдено, OpenClaw повторює той самий id через plugin approvals. Пересилання plugin approval можна налаштувати незалежно через `approvals.plugin` у конфігурації.
|
||||
Команда `/approve` обробляє як exec-схвалення, так і схвалення plugin з обмеженим fallback: коли id exec-схвалення не знайдено, OpenClaw повторює той самий id через схвалення plugin. Перенаправлення схвалень plugin можна налаштувати незалежно через `approvals.plugin` у конфігурації.
|
||||
|
||||
Якщо власна approval plumbing має визначати той самий випадок bounded fallback,
|
||||
використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime`
|
||||
замість ручного зіставлення рядків approval-expiry.
|
||||
Якщо користувацькі механізми схвалення мають виявляти той самий випадок
|
||||
обмеженого fallback, віддавайте перевагу `isApprovalNotFoundError` з
|
||||
`openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків про
|
||||
закінчення строку дії схвалення.
|
||||
|
||||
Приклади й довідку hooks див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
Приклади й довідник hooks див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
|
||||
## Реєстрація інструментів агента
|
||||
|
||||
Інструменти — це типізовані функції, які LLM може викликати. Вони можуть бути required (завжди
|
||||
доступні) або optional (користувач вмикає сам):
|
||||
Інструменти — це типізовані функції, які LLM може викликати. Вони можуть бути
|
||||
обов’язковими (завжди доступні) або необов’язковими (користувач підключає їх
|
||||
самостійно):
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -252,23 +259,31 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
Кожен інструмент, зареєстрований через `api.registerTool(...)`, також має бути оголошений у
|
||||
manifest plugin:
|
||||
Кожен інструмент, зареєстрований за допомогою `api.registerTool(...)`, також має
|
||||
бути оголошений у маніфесті plugin:
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"tools": ["my_tool", "workflow_tool"]
|
||||
},
|
||||
"toolMetadata": {
|
||||
"workflow_tool": {
|
||||
"optional": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw фіксує й кешує перевірений descriptor із зареєстрованого інструмента,
|
||||
тож plugins не дублюють `description` або schema data у manifest. Контракт
|
||||
manifest лише оголошує ownership і discovery; виконання все одно викликає
|
||||
живу зареєстровану реалізацію інструмента.
|
||||
OpenClaw захоплює та кешує перевірений дескриптор із зареєстрованого інструмента,
|
||||
тому plugins не дублюють `description` або дані схеми в маніфесті. Контракт
|
||||
маніфесту оголошує лише володіння та виявлення; виконання й надалі викликає
|
||||
актуальну реалізацію зареєстрованого інструмента.
|
||||
Установіть `toolMetadata.<tool>.optional: true` для інструментів, зареєстрованих через
|
||||
`api.registerTool(..., { optional: true })`, щоб OpenClaw міг не завантажувати
|
||||
середовище виконання цього plugin, доки інструмент не буде явно додано до allowlist.
|
||||
|
||||
Користувачі вмикають optional tools у конфігурації:
|
||||
Користувачі вмикають необов’язкові інструменти в конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -276,16 +291,16 @@ manifest лише оголошує ownership і discovery; виконання в
|
||||
}
|
||||
```
|
||||
|
||||
- Назви інструментів не мають конфліктувати з core tools (конфлікти пропускаються)
|
||||
- Інструменти з некоректно сформованими об’єктами реєстрації, зокрема без `parameters`, пропускаються й повідомляються в діагностиці Plugin замість того, щоб ламати запуски агентів
|
||||
- Назви інструментів не повинні конфліктувати з основними інструментами (конфліктні пропускаються)
|
||||
- Інструменти з некоректними об’єктами реєстрації, зокрема без `parameters`, пропускаються та повідомляються в діагностиці plugin замість того, щоб ламати запуски агентів
|
||||
- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів
|
||||
- Користувачі можуть увімкнути всі інструменти з Plugin, додавши ідентифікатор Plugin до `tools.allow`
|
||||
- Користувачі можуть увімкнути всі інструменти з plugin, додавши ідентифікатор plugin до `tools.allow`
|
||||
|
||||
## Реєстрація команд CLI
|
||||
|
||||
Plugin-и можуть додавати кореневі групи команд `openclaw` через `api.registerCli`. Надайте
|
||||
`descriptors` для кожного кореня команди верхнього рівня, щоб OpenClaw міг показувати й маршрутизувати
|
||||
команду без передчасного завантаження кожного середовища виконання Plugin.
|
||||
Plugins можуть додавати кореневі групи команд `openclaw` за допомогою `api.registerCli`. Надайте
|
||||
`descriptors` для кожного кореня команди верхнього рівня, щоб OpenClaw міг показувати та маршрутизувати
|
||||
команду без передчасного завантаження середовища виконання кожного plugin.
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -322,7 +337,7 @@ openclaw plugins inspect demo-plugin --runtime --json
|
||||
openclaw demo-plugin ping
|
||||
```
|
||||
|
||||
## Угоди щодо імпорту
|
||||
## Угоди щодо імпортів
|
||||
|
||||
Завжди імпортуйте зі сфокусованих шляхів `openclaw/plugin-sdk/<subpath>`:
|
||||
|
||||
@ -334,58 +349,58 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { ... } from "openclaw/plugin-sdk";
|
||||
```
|
||||
|
||||
Повний довідник підшляхів див. в [Огляді SDK](/uk/plugins/sdk-overview).
|
||||
Повний довідник підшляхів див. у [огляді SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
Усередині вашого Plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
|
||||
внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK.
|
||||
У межах свого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
|
||||
внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK.
|
||||
|
||||
Для Plugin-ів провайдерів тримайте специфічні для провайдера допоміжні засоби в цих barrel-файлах
|
||||
кореня пакета, якщо межа не є справді загальною. Поточні вбудовані приклади:
|
||||
Для provider plugins тримайте специфічні для провайдера допоміжні функції в цих barrel-файлах
|
||||
кореня пакета, якщо seam не є справді універсальним. Поточні вбудовані приклади:
|
||||
|
||||
- Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta
|
||||
- OpenAI: конструктори провайдерів, допоміжні засоби моделей за замовчуванням, realtime-провайдери
|
||||
- OpenRouter: конструктор провайдера та допоміжні засоби onboarding/конфігурації
|
||||
- Anthropic: обгортки потоків Claude і допоміжні функції `service_tier` / beta
|
||||
- OpenAI: побудовники провайдерів, допоміжні функції моделей за замовчуванням, realtime-провайдери
|
||||
- OpenRouter: побудовник провайдера плюс допоміжні функції onboarding/конфігурації
|
||||
|
||||
Якщо допоміжний засіб корисний лише всередині одного вбудованого пакета провайдера, тримайте його на цій
|
||||
межі кореня пакета замість просування в `openclaw/plugin-sdk/*`.
|
||||
Якщо допоміжна функція корисна лише всередині одного вбудованого пакета провайдера, тримайте її на цьому
|
||||
seam кореня пакета замість просування в `openclaw/plugin-sdk/*`.
|
||||
|
||||
Деякі згенеровані допоміжні межі `openclaw/plugin-sdk/<bundled-id>` усе ще існують для
|
||||
супроводу вбудованих Plugin-ів, коли вони мають відстежене використання власником. Сприймайте їх як
|
||||
зарезервовані поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів.
|
||||
Деякі згенеровані допоміжні seams `openclaw/plugin-sdk/<bundled-id>` досі існують для
|
||||
супроводу вбудованих plugins, коли вони мають відстежуване використання власником. Вважайте їх
|
||||
зарезервованими поверхнями, а не стандартним шаблоном для нових сторонніх plugins.
|
||||
|
||||
## Контрольний список перед поданням
|
||||
|
||||
<Check>**package.json** має коректні метадані `openclaw`</Check>
|
||||
<Check>Маніфест **openclaw.plugin.json** присутній і валідний</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` проходить (для Plugin-ів у репозиторії)</Check>
|
||||
<Check>`pnpm check` проходить (plugins у репозиторії)</Check>
|
||||
|
||||
## Тестування beta-релізів
|
||||
## Тестування 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-гілці. Контриб’ютори не можуть додавати мітки до PR, тому назва є сигналом з боку PR для мейнтейнерів і автоматизації. Блокери з PR зливаються; блокери без PR можуть усе одно потрапити в реліз. Мейнтейнери стежать за цими гілками під час 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 і автоматизації. Blockers із PR зливаються; blockers без PR можуть усе одно потрапити в реліз. Maintainers стежать за цими тредами під час 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 Overview" icon="book-open" href="/uk/plugins/sdk-overview">
|
||||
Довідник карти імпортів і API реєстрації
|
||||
Мапа імпортів і довідник API реєстрації
|
||||
</Card>
|
||||
<Card title="Runtime Helpers" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, пошук, субагент через api.runtime
|
||||
TTS, пошук, subagent через api.runtime
|
||||
</Card>
|
||||
<Card title="Testing" icon="test-tubes" href="/uk/plugins/sdk-testing">
|
||||
Тестові утиліти та шаблони
|
||||
@ -397,8 +412,8 @@ import { ... } from "openclaw/plugin-sdk";
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — глибокий огляд внутрішньої архітектури
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK
|
||||
- [Маніфест](/uk/plugins/manifest) — формат маніфесту Plugin
|
||||
- [Plugin-и каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів
|
||||
- [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — поглиблений огляд внутрішньої архітектури
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK для Plugin
|
||||
- [Маніфест](/uk/plugins/manifest) — формат маніфесту plugin
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins
|
||||
|
||||
Loading…
Reference in New Issue
Block a user