chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
9096c188cd
commit
015f9e992a
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте новий плагін каналу обміну повідомленнями
|
||||
- Ви створюєте новий плагін каналу повідомлень
|
||||
- Ви хочете підключити OpenClaw до платформи обміну повідомленнями
|
||||
- Вам потрібно зрозуміти поверхню адаптера ChannelPlugin
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: Покроковий посібник зі створення плагіна каналу обміну повідомленнями для OpenClaw
|
||||
summary: Покроковий посібник зі створення плагіна каналу повідомлень для OpenClaw
|
||||
title: Створення плагінів каналів
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T06:53:56Z"
|
||||
generated_at: "2026-04-07T18:43:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09
|
||||
source_hash: b709fda7527fcf437b119c4668172804f2f9c9a46f5e39a2161467a4f5f1e42f
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,8 +18,8 @@ x-i18n:
|
||||
# Створення плагінів каналів
|
||||
|
||||
Цей посібник покроково пояснює створення плагіна каналу, який підключає OpenClaw до
|
||||
платформи обміну повідомленнями. Наприкінці у вас буде працездатний канал із безпекою DM,
|
||||
паруванням, потоками відповідей і вихідними повідомленнями.
|
||||
платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із безпекою DM,
|
||||
паруванням, гілкуванням відповідей і надсиланням вихідних повідомлень.
|
||||
|
||||
<Info>
|
||||
Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
@ -30,164 +30,179 @@ x-i18n:
|
||||
## Як працюють плагіни каналів
|
||||
|
||||
Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw зберігає один
|
||||
спільний інструмент `message` у core. Ваш плагін відповідає за:
|
||||
спільний інструмент `message` у ядрі. Ваш плагін відповідає за:
|
||||
|
||||
- **Config** — визначення облікового запису та майстер налаштування
|
||||
- **Security** — політика DM та списки дозволених
|
||||
- **Pairing** — потік схвалення DM
|
||||
- **Session grammar** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами потоків і резервними батьківськими значеннями
|
||||
- **Outbound** — надсилання тексту, медіа та опитувань на платформу
|
||||
- **Threading** — як організовуються відповіді в потоки
|
||||
- **Security** — політика DM і списки дозволених
|
||||
- **Pairing** — процес підтвердження DM
|
||||
- **Session grammar** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами гілок і запасними батьківськими варіантами
|
||||
- **Outbound** — надсилання тексту, медіа й опитувань на платформу
|
||||
- **Threading** — як організовуються відповіді в гілки
|
||||
|
||||
Core відповідає за спільний інструмент повідомлень, підключення до prompt, зовнішню форму ключа сесії,
|
||||
загальне ведення `:thread:` та диспетчеризацію.
|
||||
Ядро відповідає за спільний інструмент message, зв’язування промптів, зовнішню форму
|
||||
ключа сесії, загальний облік `:thread:` і диспетчеризацію.
|
||||
|
||||
Якщо ваша платформа зберігає додаткову область дії в ідентифікаторах розмов, зберігайте цей розбір
|
||||
у плагіні через `messaging.resolveSessionConversation(...)`. Це
|
||||
канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим ідентифікатором потоку,
|
||||
явним `baseConversationId` та будь-якими `parentConversationCandidates`.
|
||||
Коли ви повертаєте `parentConversationCandidates`, зберігайте їхній порядок
|
||||
від найвужчого батьківського елемента до найширшої/базової розмови.
|
||||
Якщо ваша платформа зберігає додатковий контекст в ідентифікаторах розмов, залишайте цей
|
||||
розбір у плагіні через `messaging.resolveSessionConversation(...)`. Це
|
||||
канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим
|
||||
ідентифікатором гілки, явним `baseConversationId` і будь-якими
|
||||
`parentConversationCandidates`.
|
||||
Коли ви повертаєте `parentConversationCandidates`, зберігайте їх впорядкованими від
|
||||
найвужчого батьківського елемента до найширшої/базової розмови.
|
||||
|
||||
Вбудовані плагіни, яким потрібен такий самий розбір до запуску реєстру каналів,
|
||||
також можуть експортувати файл верхнього рівня `session-key-api.ts` із
|
||||
відповідним експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню
|
||||
лише тоді, коли реєстр плагінів середовища виконання ще недоступний.
|
||||
Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів,
|
||||
також можуть надавати файл верхнього рівня `session-key-api.ts` із відповідним
|
||||
експортом `resolveSessionConversation(...)`. Ядро використовує цю безпечну для
|
||||
завантаження поверхню лише тоді, коли реєстр плагінів під час виконання ще недоступний.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` залишається доступним як
|
||||
застарілий резервний варіант сумісності, коли плагіну потрібні лише батьківські резервні значення поверх
|
||||
загального/raw id. Якщо існують обидва хуки, core спочатку використовує
|
||||
`resolveSessionConversation(...).parentConversationCandidates` і лише потім
|
||||
застарілий запасний варіант для сумісності, коли плагіну потрібні лише
|
||||
резервні батьківські варіанти поверх загального/raw id. Якщо існують обидва хуки, ядро спочатку
|
||||
використовує `resolveSessionConversation(...).parentConversationCandidates` і лише потім
|
||||
переходить до `resolveParentConversationCandidates(...)`, якщо канонічний хук
|
||||
їх не вказує.
|
||||
їх не повертає.
|
||||
|
||||
## Схвалення та можливості каналу
|
||||
## Підтвердження та можливості каналу
|
||||
|
||||
Більшості плагінів каналів не потрібен код, специфічний для схвалень.
|
||||
Більшості плагінів каналів не потрібен код, специфічний для підтверджень.
|
||||
|
||||
- Core відповідає за `/approve` у тому ж чаті, спільні payload кнопок схвалення та загальну резервну доставку.
|
||||
- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для схвалень.
|
||||
- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов автентифікації схвалень.
|
||||
- Якщо ваш канал надає нативні схвалення exec, реалізуйте `approvalCapability.getActionAvailabilityState`, навіть якщо нативний транспорт повністю знаходиться в `approvalCapability.native`. Core використовує цей хук доступності, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує канал-ініціатор нативні схвалення, і включати канал до інструкцій резервного варіанта для нативного клієнта.
|
||||
- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для специфічної для каналу поведінки життєвого циклу payload, наприклад приховування дубльованих локальних запитів на схвалення або надсилання індикаторів набору перед доставкою.
|
||||
- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації схвалень або вимкнення резервного варіанта.
|
||||
- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload схвалення замість спільного рендерера.
|
||||
- Використовуйте `approvalCapability.describeExecApprovalSetup`, якщо канал хоче, щоб відповідь для вимкненого шляху пояснювала точні параметри config, потрібні для ввімкнення нативних схвалень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю дії облікового запису, такі як `channels.<channel>.accounts.<id>.execApprovals.*`, замість дефолтів верхнього рівня.
|
||||
- Якщо канал може вивести стабільні DM-ідентичності, подібні до власника, з наявного config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому ж чаті без додавання логіки core, специфічної для схвалень.
|
||||
- Якщо каналу потрібна нативна доставка схвалень, зосередьте код каналу на нормалізації цілі та хуках транспорту. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core відповідав за фільтрацію запитів, маршрутизацію, усунення дублікатів, строк дії та підписку на gateway.
|
||||
- Канали нативних схвалень мають маршрутизувати і `accountId`, і `approvalKind` через ці helper-и. `accountId` утримує політику схвалень для кількох облікових записів у межах правильного бот-облікового запису, а `approvalKind` зберігає поведінку схвалень exec і plugin доступною для каналу без жорстко закодованих гілок у core.
|
||||
- Ядро відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну запасну доставку.
|
||||
- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для підтверджень.
|
||||
- `ChannelPlugin.approvals` видалено. Виносьте факти про доставку/нативний режим/рендеринг/автентифікацію підтверджень у `approvalCapability`.
|
||||
- `plugin.auth` призначений лише для login/logout; ядро більше не читає хуки автентифікації підтверджень із цього об’єкта.
|
||||
- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов автентифікації підтверджень.
|
||||
- Використовуйте `approvalCapability.getActionAvailabilityState` для доступності автентифікації підтверджень у тому самому чаті.
|
||||
- Якщо ваш канал надає нативні підтвердження exec, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану ініціювальної поверхні/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей специфічний для exec хук, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціювальний канал нативні підтвердження exec, і включати канал у рекомендації щодо запасного сценарію для нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку.
|
||||
- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дубльованих локальних запитів підтвердження або надсилання індикаторів набору перед доставкою.
|
||||
- Використовуйте `approvalCapability.delivery` лише для маршрутизації нативних підтверджень або придушення запасної доставки.
|
||||
- Використовуйте `approvalCapability.nativeRuntime` для фактів нативного підтвердження, що належать каналу. Зберігайте його ледачим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень.
|
||||
- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтвердження замість спільного рендера.
|
||||
- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри config, потрібні для ввімкнення нативних підтверджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю облікового запису, як-от `channels.<channel>.accounts.<id>.execApprovals.*`, замість верхньорівневих типових значень.
|
||||
- Якщо канал може вивести стабільні схожі на власника DM-ідентичності з наявної config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки підтверджень у ядро.
|
||||
- Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі плюс фактах транспорту/представлення. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте факти, специфічні для каналу, за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб ядро могло зібрати обробник і взяти на себе фільтрацію запитів, маршрутизацію, усунення дублікатів, завершення строку дії, підписку шлюзу та сповіщення про перенаправлення. `nativeRuntime` поділено на кілька менших швів:
|
||||
- `availability` — чи налаштовано обліковий запис і чи слід обробляти запит
|
||||
- `presentation` — перетворення спільної view model підтверджень у нативні payload очікування/вирішення/прострочення або фінальні дії
|
||||
- `transport` — підготовка цілей плюс надсилання/оновлення/видалення нативних повідомлень підтвердження
|
||||
- `interactions` — необов’язкові хуки bind/unbind/clear-action для нативних кнопок або реакцій
|
||||
- `observe` — необов’язкові хуки діагностики доставки
|
||||
- Якщо каналу потрібні об’єкти, що належать runtime, як-от client, token, додаток Bolt або приймач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-context дозволяє ядру ініціалізувати обробники на основі можливостей зі стану запуску каналу без додавання обгорток, специфічних для підтверджень.
|
||||
- Звертайтеся до нижчорівневого `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов на основі можливостей ще недостатньо виразний.
|
||||
- Канали з нативними підтвердженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці помічники. `accountId` зберігає область політики підтверджень для багатьох облікових записів прив’язаною до правильного бот-акаунта, а `approvalKind` зберігає для каналу доступною поведінку підтверджень exec чи plugin без жорстко закодованих розгалужень у ядрі.
|
||||
- Ядро тепер також відповідає за сповіщення про перенаправлення підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт «підтвердження надійшло в DM / інший канал» із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні помічники можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в ініціювальний чат.
|
||||
- Зберігайте тип delivered approval id наскрізно. Нативні клієнти не повинні
|
||||
вгадувати або переписувати маршрутизацію схвалень exec чи plugin на основі локального стану каналу.
|
||||
- Різні типи схвалень можуть навмисно надавати різні нативні поверхні.
|
||||
Поточні приклади вбудованих:
|
||||
- Slack зберігає доступність нативної маршрутизації схвалень як для exec, так і для plugin id.
|
||||
- Matrix зберігає нативну DM/канальну маршрутизацію лише для схвалень exec і залишає
|
||||
схвалення plugin на спільному шляху `/approve` у тому ж чаті.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має віддавати перевагу builder-у можливостей і експонувати `approvalCapability` у плагіні.
|
||||
вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу.
|
||||
- Різні типи підтверджень можуть навмисно відкривати різні нативні поверхні.
|
||||
Поточні приклади вбудованих плагінів:
|
||||
- Slack зберігає доступною нативну маршрутизацію підтверджень як для exec, так і для plugin id.
|
||||
- Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec
|
||||
і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка для сумісності, але новий код має надавати перевагу будівнику можливостей і експонувати `approvalCapability` у плагіні.
|
||||
|
||||
Для гарячих точок входу каналу віддавайте перевагу вужчим runtime subpath, коли вам
|
||||
потрібна лише одна частина цієї сім’ї:
|
||||
Для гарячих точок входу каналу віддавайте перевагу вужчим runtime-підшляхам, коли вам потрібна лише
|
||||
одна частина цієї сім’ї:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
- `openclaw/plugin-sdk/approval-delivery-runtime`
|
||||
- `openclaw/plugin-sdk/approval-handler-runtime`
|
||||
- `openclaw/plugin-sdk/approval-native-runtime`
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference` і
|
||||
`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша узагальнена
|
||||
`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша зонтична
|
||||
поверхня.
|
||||
|
||||
Зокрема для налаштування:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper-и налаштування:
|
||||
безпечні для import адаптери патчів налаштування (`createPatchedAccountSetupAdapter`,
|
||||
- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime помічники налаштування:
|
||||
безпечні для імпорту адаптери патчів налаштування (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), вивід lookup-note,
|
||||
`createSetupInputPresenceValidator`), виведення lookup-note,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` і делеговані
|
||||
builder-и setup-proxy
|
||||
будівники setup-proxy
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шов адаптера
|
||||
для `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` охоплює builder-и налаштування з необов’язковим встановленням
|
||||
плюс кілька примітивів, безпечних для setup:
|
||||
- `openclaw/plugin-sdk/channel-setup` охоплює будівники налаштування з необов’язковим встановленням
|
||||
плюс кілька безпечних для налаштування примітивів:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Якщо ваш канал підтримує налаштування або auth на основі env і загальні потоки startup/config
|
||||
мають знати ці назви env до завантаження runtime, оголосіть їх у
|
||||
Якщо ваш канал підтримує налаштування або auth на основі env, і загальні процеси запуску/config
|
||||
мають знати ці назви env до завантаження runtime, оголошуйте їх у
|
||||
маніфесті плагіна через `channelEnvVars`. Зберігайте runtime `envVars` каналу або локальні
|
||||
константи лише для копії, орієнтованої на оператора.
|
||||
константи лише для копірайту, орієнтованого на операторів.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і
|
||||
`splitSetupEntries`
|
||||
|
||||
- використовуйте ширший шов `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні
|
||||
важчі спільні helper-и setup/config, наприклад
|
||||
важчі спільні помічники налаштування/config, такі як
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Якщо ваш канал хоче лише рекламувати «спочатку встановіть цей плагін» у поверхнях setup,
|
||||
віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані
|
||||
адаптер/майстер fail closed під час запису config та завершення, і повторно використовують
|
||||
те саме повідомлення про необхідність встановлення в копії валідації, finalize та docs-link.
|
||||
Якщо ваш канал лише хоче повідомляти «спочатку встановіть цей плагін» на
|
||||
поверхнях налаштування, віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані
|
||||
adapter/wizard працюють за принципом fail closed для записів config і фіналізації, а також
|
||||
повторно використовують те саме повідомлення про обов’язкове встановлення для валідації, фіналізації та тексту
|
||||
з посиланням на документацію.
|
||||
|
||||
Для інших гарячих шляхів каналу віддавайте перевагу вузьким helper-ам замість ширших застарілих
|
||||
поверхонь:
|
||||
Для інших гарячих шляхів каналу віддавайте перевагу вузьким помічникам над ширшими застарілими
|
||||
поверхнями:
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
`openclaw/plugin-sdk/account-id`,
|
||||
`openclaw/plugin-sdk/account-resolution` і
|
||||
`openclaw/plugin-sdk/account-helpers` для config кількох облікових записів та
|
||||
резервного варіанта для облікового запису за замовчуванням
|
||||
`openclaw/plugin-sdk/account-helpers` для config багатьох облікових записів і
|
||||
запасного сценарію облікового запису за замовчуванням
|
||||
- `openclaw/plugin-sdk/inbound-envelope` і
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта inbound та
|
||||
запису й диспетчеризації
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` для вхідного маршруту/конверта та
|
||||
зв’язування record-and-dispatch
|
||||
- `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей
|
||||
- `openclaw/plugin-sdk/outbound-media` і
|
||||
`openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс
|
||||
делегатів ідентичності/надсилання outbound
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок потоків
|
||||
та реєстрації адаптерів
|
||||
- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібне
|
||||
застаріле компонування полів payload agent/media
|
||||
- `openclaw/plugin-sdk/telegram-command-config` для нормалізації користувацьких команд Telegram,
|
||||
перевірки дублікатів/конфліктів і стабільного для резервного варіанта контракту
|
||||
config команд
|
||||
`openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс делегатів
|
||||
ідентичності/надсилання вихідних повідомлень
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок гілок
|
||||
і реєстрації адаптерів
|
||||
- `openclaw/plugin-sdk/agent-media-payload` лише коли все ще потрібна застаріла
|
||||
схема полів payload агента/медіа
|
||||
- `openclaw/plugin-sdk/telegram-command-config` для нормалізації спеціальних команд Telegram,
|
||||
валідації дублікатів/конфліктів і стабільного при запасному сценарії контракту config команд
|
||||
|
||||
Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core обробляє схвалення, а плагін лише надає можливості outbound/auth. Канали нативних схвалень, такі як Matrix, Slack, Telegram і користувацькі chat-транспорти, повинні використовувати спільні нативні helper-и замість власної реалізації життєвого циклу схвалень.
|
||||
Канали лише з auth зазвичай можуть зупинитися на типовому шляху: ядро обробляє підтвердження, а плагін лише надає можливості outbound/auth. Канали з нативними підтвердженнями, як-от Matrix, Slack, Telegram і спеціальні транспортні канали чату, повинні використовувати спільні нативні помічники замість реалізації власного життєвого циклу підтверджень.
|
||||
|
||||
## Політика вхідних згадок
|
||||
|
||||
Розділяйте обробку вхідних згадок на два шари:
|
||||
Розділяйте обробку вхідних згадок на два рівні:
|
||||
|
||||
- збирання доказів, яким володіє плагін
|
||||
- спільне оцінювання політики
|
||||
- збирання доказів, що належить плагіну
|
||||
- оцінювання спільної політики
|
||||
|
||||
Для спільного шару використовуйте `openclaw/plugin-sdk/channel-inbound`.
|
||||
Для спільного рівня використовуйте `openclaw/plugin-sdk/channel-inbound`.
|
||||
|
||||
Добре підходить для локальної логіки плагіна:
|
||||
Підходить для логіки, локальної для плагіна:
|
||||
|
||||
- виявлення reply-to-bot
|
||||
- виявлення quoted-bot
|
||||
- перевірки участі в потоці
|
||||
- виключення службових/системних повідомлень
|
||||
- платформені нативні кеші, потрібні для підтвердження участі бота
|
||||
- виявлення відповіді боту
|
||||
- виявлення цитування бота
|
||||
- перевірки участі в гілці
|
||||
- виключення сервісних/системних повідомлень
|
||||
- платформонативні кеші, потрібні для доведення участі бота
|
||||
|
||||
Добре підходить для спільного helper-а:
|
||||
Підходить для спільного помічника:
|
||||
|
||||
- `requireMention`
|
||||
- явний результат згадки
|
||||
- список дозволених неявних згадок
|
||||
- обхід команди
|
||||
- фінальне рішення про пропуск
|
||||
- обхід для команд
|
||||
- остаточне рішення про пропуск
|
||||
|
||||
Бажаний потік:
|
||||
Рекомендований процес:
|
||||
|
||||
1. Обчисліть локальні факти згадок.
|
||||
1. Обчисліть локальні факти згадки.
|
||||
2. Передайте ці факти в `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у вашому вхідному шлюзі.
|
||||
3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у своїй вхідній перевірці.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -226,8 +241,8 @@ const decision = resolveInboundMentionDecision({
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` надає ті самі спільні helper-и згадок для
|
||||
вбудованих плагінів каналів, які вже залежать від ін’єкції runtime:
|
||||
`api.runtime.channel.mentions` надає ті самі спільні помічники згадок для
|
||||
вбудованих плагінів каналів, які вже залежать від інʼєкції runtime:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -235,8 +250,8 @@ if (decision.shouldSkip) return;
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Старіші helper-и `resolveMentionGating*` залишаються в
|
||||
`openclaw/plugin-sdk/channel-inbound` лише як експорти сумісності. Новий код
|
||||
Старіші помічники `resolveMentionGating*` залишаються в
|
||||
`openclaw/plugin-sdk/channel-inbound` лише як експорти для сумісності. Новий код
|
||||
має використовувати `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## Покроковий розбір
|
||||
@ -244,8 +259,8 @@ if (decision.shouldSkip) return;
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Пакет і маніфест">
|
||||
Створіть стандартні файли плагіна. Поле `channel` у `package.json` —
|
||||
це те, що робить його плагіном каналу. Повну поверхню метаданих пакета
|
||||
Створіть стандартні файли плагіна. Поле `channel` у `package.json`
|
||||
робить це плагіном каналу. Повну поверхню метаданих пакета
|
||||
дивіться в [Налаштування плагіна і Config](/uk/plugins/sdk-setup#openclawchannel):
|
||||
|
||||
<CodeGroup>
|
||||
@ -296,7 +311,7 @@ if (decision.shouldSkip) return;
|
||||
</Step>
|
||||
|
||||
<Step title="Створіть об’єкт плагіна каналу">
|
||||
Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптера. Почніть із
|
||||
Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть із
|
||||
мінімуму — `id` і `setup` — і додавайте адаптери за потреби.
|
||||
|
||||
Створіть `src/channel.ts`:
|
||||
@ -392,18 +407,18 @@ if (decision.shouldSkip) return;
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="Що робить для вас createChatChannelPlugin">
|
||||
Замість ручної реалізації низькорівневих інтерфейсів адаптера ви передаєте
|
||||
декларативні параметри, а builder компонуватиме їх:
|
||||
<Accordion title="Що для вас робить createChatChannelPlugin">
|
||||
Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви передаєте
|
||||
декларативні параметри, а будівник поєднує їх:
|
||||
|
||||
| Параметр | Що він підключає |
|
||||
| --- | --- |
|
||||
| `security.dm` | Визначення scoped DM security з полів config |
|
||||
| `pairing.text` | Потік парування DM на основі тексту з обміном кодом |
|
||||
| `threading` | Визначення режиму reply-to (фіксований, у межах облікового запису або користувацький) |
|
||||
| `outbound.attachedResults` | Функції надсилання, що повертають метадані результату (ідентифікатори повідомлень) |
|
||||
| `security.dm` | Визначення DM-безпеки з областю дії з полів config |
|
||||
| `pairing.text` | Текстовий процес парування DM з обміном кодами |
|
||||
| `threading` | Визначення режиму reply-to (фіксований, з областю облікового запису або власний) |
|
||||
| `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ID повідомлень) |
|
||||
|
||||
Ви також можете передавати сирі об’єкти адаптера замість декларативних параметрів,
|
||||
Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів,
|
||||
якщо вам потрібен повний контроль.
|
||||
</Accordion>
|
||||
|
||||
@ -445,20 +460,20 @@ if (decision.shouldSkip) return;
|
||||
});
|
||||
```
|
||||
|
||||
Розміщуйте CLI-дескриптори, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw
|
||||
Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw
|
||||
міг показувати їх у кореневій довідці без активації повного runtime каналу,
|
||||
тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації
|
||||
реальних команд. Залишайте `registerFull(...)` для роботи лише в runtime.
|
||||
реальних команд. Залишайте `registerFull(...)` для роботи лише під час runtime.
|
||||
Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте
|
||||
префікс, специфічний для плагіна. Простори імен адміністрування core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими та завжди
|
||||
префікс, специфічний для плагіна. Простори імен адміністратора ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди
|
||||
визначаються як `operator.admin`.
|
||||
`defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Усі
|
||||
параметри дивіться в [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте запис налаштування">
|
||||
<Step title="Додайте точку входу налаштування">
|
||||
Створіть `setup-entry.ts` для легкого завантаження під час онбордингу:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
@ -468,16 +483,16 @@ if (decision.shouldSkip) return;
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
OpenClaw завантажує це замість повної точки входу, коли канал вимкнений
|
||||
або не налаштований. Це дає змогу не підтягувати важкий runtime-код під час потоків setup.
|
||||
Подробиці дивіться в [Setup and Config](/uk/plugins/sdk-setup#setup-entry).
|
||||
OpenClaw завантажує це замість повної точки входу, коли канал вимкнено
|
||||
або не налаштовано. Це дає змогу не підтягувати важкий runtime-код під час процесів налаштування.
|
||||
Докладніше дивіться в [Налаштування і Config](/uk/plugins/sdk-setup#setup-entry).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Обробляйте вхідні повідомлення">
|
||||
Вашому плагіну потрібно отримувати повідомлення з платформи та пересилати їх до
|
||||
Ваш плагін має отримувати повідомлення з платформи й переспрямовувати їх до
|
||||
OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і
|
||||
диспетчеризує його через inbound-обробник вашого каналу:
|
||||
диспетчеризує його через вхідний обробник вашого каналу:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
@ -501,16 +516,16 @@ if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
<Note>
|
||||
Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу має
|
||||
власний inbound-конвеєр. Подивіться на вбудовані плагіни каналів
|
||||
(наприклад, пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони.
|
||||
Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу відповідає
|
||||
за власний вхідний конвеєр. Подивіться на вбудовані плагіни каналів
|
||||
(наприклад, пакет плагінів Microsoft Teams або Google Chat), щоб побачити реальні шаблони.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Тестування">
|
||||
Пишіть colocated тести в `src/channel.test.ts`:
|
||||
Пишіть колоковані тести в `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -548,7 +563,7 @@ if (decision.shouldSkip) return;
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Спільні helper-и для тестування дивіться в [Тестування](/uk/plugins/sdk-testing).
|
||||
Спільні помічники тестування дивіться в [Тестування](/uk/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -562,7 +577,7 @@ if (decision.shouldSkip) return;
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Публічні експорти (необов’язково)
|
||||
├── runtime-api.ts # Внутрішні експорти runtime (необов’язково)
|
||||
├── runtime-api.ts # Внутрішні runtime-експорти (необов’язково)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin через createChatChannelPlugin
|
||||
├── channel.test.ts # Тести
|
||||
@ -573,30 +588,30 @@ if (decision.shouldSkip) return;
|
||||
## Розширені теми
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Параметри потоків" icon="git-branch" href="/uk/plugins/sdk-entrypoints#registration-mode">
|
||||
Фіксовані, у межах облікового запису або користувацькі режими reply
|
||||
<Card title="Параметри гілкування" icon="git-branch" href="/uk/plugins/sdk-entrypoints#registration-mode">
|
||||
Фіксовані режими відповіді, режими з областю облікового запису або власні
|
||||
</Card>
|
||||
<Card title="Інтеграція інструмента message" icon="puzzle" href="/uk/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="Інтеграція інструмента повідомлень" icon="puzzle" href="/uk/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool і виявлення дій
|
||||
</Card>
|
||||
<Card title="Визначення цілі" icon="crosshair" href="/uk/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Runtime helper-и" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, STT, media, subagent через api.runtime
|
||||
<Card title="Помічники runtime" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, STT, медіа, subagent через api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Деякі вбудовані helper-шви все ще існують для підтримки вбудованих плагінів і
|
||||
сумісності. Вони не є рекомендованим шаблоном для нових плагінів каналів;
|
||||
віддавайте перевагу загальним channel/setup/reply/runtime subpath зі спільної
|
||||
поверхні SDK, якщо тільки ви безпосередньо не підтримуєте цю сім’ю вбудованих плагінів.
|
||||
Деякі вбудовані допоміжні шви все ще існують для підтримки вбудованих плагінів і
|
||||
сумісності. Це не рекомендований шаблон для нових плагінів каналів;
|
||||
віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної
|
||||
поверхні SDK, якщо тільки ви не підтримуєте безпосередньо це сімейство вбудованих плагінів.
|
||||
</Note>
|
||||
|
||||
## Наступні кроки
|
||||
|
||||
- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з import subpath
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів
|
||||
- [Тестування SDK](/uk/plugins/sdk-testing) — тестові утиліти та контрактні тести
|
||||
- [Маніфест плагіна](/uk/plugins/manifest) — повна схема маніфесту
|
||||
|
||||
@ -5,95 +5,131 @@ read_when:
|
||||
- Ви оновлюєте plugin до сучасної архітектури plugin
|
||||
- Ви підтримуєте зовнішній plugin OpenClaw
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: Перейдіть із застарілого шару зворотної сумісності на сучасний plugin SDK
|
||||
summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний plugin SDK
|
||||
title: Міграція Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T22:33:54Z"
|
||||
generated_at: "2026-04-07T18:43:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c
|
||||
source_hash: 509699c3432191a1b2e4214c66d6d620e8d13a064cb2e7b9b38460c7ea45a20d
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Міграція Plugin SDK
|
||||
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури
|
||||
plugin із цільовими, задокументованими імпортами. Якщо ваш plugin було створено
|
||||
до появи нової архітектури, цей посібник допоможе вам виконати міграцію.
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної
|
||||
архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш plugin
|
||||
було створено до появи нової архітектури, цей посібник допоможе вам
|
||||
перейти на неї.
|
||||
|
||||
## Що змінюється
|
||||
|
||||
Стара система plugin надавала дві дуже широкі поверхні, які дозволяли plugin
|
||||
імпортувати все, що їм потрібно, з однієї точки входу:
|
||||
Стара система plugin надавала дві відкриті поверхні, які дозволяли plugin
|
||||
імпортувати все необхідне з єдиної точки входу:
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував
|
||||
десятки допоміжних засобів. Його було запроваджено, щоб старіші plugin на
|
||||
основі hooks продовжували працювати, поки будувалася нова архітектура plugin.
|
||||
- **`openclaw/extension-api`** — міст, який надавав plugin прямий доступ до
|
||||
допоміжних засобів на боці хоста, таких як вбудований runner агента.
|
||||
десятки допоміжних функцій. Його було запроваджено, щоб зберегти роботу
|
||||
старіших plugin на основі hook, поки створювалася нова архітектура plugin.
|
||||
- **`openclaw/extension-api`** — міст, що надавав plugin прямий доступ до
|
||||
допоміжних функцій на боці хоста, як-от вбудований засіб запуску agent.
|
||||
|
||||
Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання,
|
||||
але нові plugin не повинні їх використовувати, а наявні plugin мають виконати
|
||||
міграцію до того, як наступний мажорний реліз їх видалить.
|
||||
але нові plugin не повинні їх використовувати, а наявним plugin слід
|
||||
перейти до того, як наступний мажорний випуск їх прибере.
|
||||
|
||||
<Warning>
|
||||
Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів.
|
||||
Plugins, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться.
|
||||
Шар зворотної сумісності буде видалено в одному з майбутніх мажорних
|
||||
випусків. Plugins, які все ще імпортують із цих поверхонь, перестануть
|
||||
працювати, коли це станеться.
|
||||
</Warning>
|
||||
|
||||
## Чому це змінилося
|
||||
|
||||
Старий підхід створював проблеми:
|
||||
Старий підхід спричиняв проблеми:
|
||||
|
||||
- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу визначити, які експорти були стабільними, а які внутрішніми
|
||||
- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки
|
||||
не пов’язаних між собою модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення
|
||||
циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу визначити, які експорти є
|
||||
стабільними, а які внутрішніми
|
||||
|
||||
Сучасний plugin SDK виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом.
|
||||
Сучасний plugin SDK вирішує це: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим, самодостатнім модулем із чітким призначенням і задокументованим
|
||||
контрактом.
|
||||
|
||||
Застарілі зручні seams провайдерів для вбудованих каналів також зникли. Імпорти
|
||||
Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти
|
||||
на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
|
||||
допоміжні seams із брендуванням каналів і
|
||||
`openclaw/plugin-sdk/telegram-core` були приватними скороченнями mono-repo, а не
|
||||
стабільними контрактами plugin. Натомість використовуйте вузькі узагальнені SDK subpaths. Усередині
|
||||
робочого простору вбудованих plugin зберігайте допоміжні засоби, що належать провайдеру, у власних
|
||||
`api.ts` або `runtime-api.ts` цього plugin.
|
||||
брендовані допоміжні шви каналів і
|
||||
`openclaw/plugin-sdk/telegram-core` були приватними скороченнями
|
||||
моно-репозиторію, а не стабільними контрактами plugin. Натомість
|
||||
використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору
|
||||
вбудованих plugin зберігайте допоміжні функції, що належать provider, у
|
||||
власному `api.ts` або `runtime-api.ts` цього plugin.
|
||||
|
||||
Поточні приклади вбудованих провайдерів:
|
||||
Поточні приклади вбудованих provider:
|
||||
|
||||
- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному seam `api.ts` /
|
||||
`contract-api.ts`
|
||||
- OpenAI зберігає конструктори провайдерів, допоміжні засоби моделей за замовчуванням і конструктори realtime-провайдерів
|
||||
- Anthropic зберігає допоміжні функції потоку, специфічні для Claude, у
|
||||
власному шві `api.ts` / `contract-api.ts`
|
||||
- OpenAI зберігає builder-и provider, допоміжні функції моделей за
|
||||
замовчуванням і builder-и realtime provider у власному `api.ts`
|
||||
- OpenRouter зберігає builder provider та допоміжні функції онбордингу/конфігурації
|
||||
у власному `api.ts`
|
||||
- OpenRouter зберігає конструктор провайдера та допоміжні засоби онбордингу/конфігурації у власному
|
||||
`api.ts`
|
||||
|
||||
## Як виконати міграцію
|
||||
## Як перейти
|
||||
|
||||
<Steps>
|
||||
<Step title="Перенесіть approval-native handlers на факти можливостей">
|
||||
Plugins каналів із підтримкою approval тепер розкривають нативну поведінку
|
||||
approval через `approvalCapability.nativeRuntime` разом зі спільним
|
||||
реєстром runtime-context.
|
||||
|
||||
Ключові зміни:
|
||||
|
||||
- Замініть `approvalCapability.handler.loadRuntime(...)` на
|
||||
`approvalCapability.nativeRuntime`
|
||||
- Перенесіть автентифікацію/доставку, специфічні для approval, зі
|
||||
застарілого зв’язування `plugin.auth` / `plugin.approvals`
|
||||
на `approvalCapability`
|
||||
- `ChannelPlugin.approvals` видалено з публічного контракту
|
||||
channel-plugin; перенесіть поля delivery/native/render до
|
||||
`approvalCapability`
|
||||
- `plugin.auth` залишається лише для потоків входу/виходу з channel; hook
|
||||
автентифікації approval там більше не читаються ядром
|
||||
- Реєструйте runtime-об’єкти, що належать каналу, як-от clients, tokens або Bolt
|
||||
apps, через `openclaw/plugin-sdk/channel-runtime-context`
|
||||
- Не надсилайте повідомлення про перенаправлення, що належать plugin, з native approval handlers;
|
||||
тепер ядро відповідає за повідомлення routed-elsewhere на основі фактичних результатів доставки
|
||||
- Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте
|
||||
справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються.
|
||||
|
||||
Поточне компонування можливостей approval дивіться в
|
||||
`/plugins/sdk-channel-plugins`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте резервну поведінку Windows wrapper">
|
||||
Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows
|
||||
wrappers `.cmd`/`.bat` тепер аварійно завершуються в закритому режимі, якщо ви явно не передасте
|
||||
Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені Windows
|
||||
wrappers `.cmd`/`.bat` тепер завершуються з закритою відмовою, якщо ви явно не передасте
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
// До
|
||||
const program = applyWindowsSpawnProgramPolicy({ candidate });
|
||||
|
||||
// After
|
||||
// Після
|
||||
const program = applyWindowsSpawnProgramPolicy({
|
||||
candidate,
|
||||
// Only set this for trusted compatibility callers that intentionally
|
||||
// accept shell-mediated fallback.
|
||||
// Установлюйте це лише для довірених викликів сумісності, які свідомо
|
||||
// допускають резервний перехід через shell.
|
||||
allowShellFallback: true,
|
||||
});
|
||||
```
|
||||
|
||||
Якщо ваш виклик не покладається навмисно на резервний shell-механізм, не встановлюйте
|
||||
`allowShellFallback`, а натомість обробляйте викинуту помилку.
|
||||
Якщо ваш виклик не покладається навмисно на резервний перехід через shell,
|
||||
не встановлюйте `allowShellFallback` і натомість обробляйте згенеровану помилку.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -107,36 +143,36 @@ plugin із цільовими, задокументованими імпорт
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Замініть на цільові імпорти">
|
||||
<Step title="Замініть їх цільовими імпортами">
|
||||
Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated backwards-compatibility layer)
|
||||
// До (застарілий шар зворотної сумісності)
|
||||
import {
|
||||
createChannelReplyPipeline,
|
||||
createPluginRuntimeStore,
|
||||
resolveControlCommandGate,
|
||||
} from "openclaw/plugin-sdk/compat";
|
||||
|
||||
// After (modern focused imports)
|
||||
// Після (сучасні цільові імпорти)
|
||||
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
|
||||
```
|
||||
|
||||
Для допоміжних засобів на боці хоста використовуйте введений runtime plugin замість
|
||||
прямого імпорту:
|
||||
Для допоміжних функцій на боці хоста використовуйте впроваджений runtime plugin
|
||||
замість прямого імпорту:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated extension-api bridge)
|
||||
// До (застарілий міст extension-api)
|
||||
import { runEmbeddedPiAgent } from "openclaw/extension-api";
|
||||
const result = await runEmbeddedPiAgent({ sessionId, prompt });
|
||||
|
||||
// After (injected runtime)
|
||||
// Після (впроваджений runtime)
|
||||
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
|
||||
```
|
||||
|
||||
Той самий шаблон застосовується й до інших застарілих допоміжних засобів моста:
|
||||
Такий самий шаблон застосовується й до інших застарілих допоміжних функцій моста:
|
||||
|
||||
| Старий імпорт | Сучасний еквівалент |
|
||||
| --- | --- |
|
||||
@ -146,7 +182,7 @@ plugin із цільовими, задокументованими імпорт
|
||||
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
|
||||
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
|
||||
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
|
||||
| session store helpers | `api.runtime.agent.session.*` |
|
||||
| допоміжні функції сховища session | `api.runtime.agent.session.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
@ -163,174 +199,176 @@ plugin із цільовими, задокументованими імпорт
|
||||
<Accordion title="Таблиця поширених шляхів імпорту">
|
||||
| Шлях імпорту | Призначення | Ключові експорти |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/builders входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Цільові визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Підказки allowlist, конструктори статусу налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для налаштування | Безпечні для імпорту patch-адаптери налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку облікових записів/конфігурації/гейтів дій |
|
||||
| `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback до значення за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікового запису | Допоміжні засоби списку облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного provider | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Цільові визначення та builders входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, builders стану налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні функції runtime на етапі налаштування | Безпечні для імпорту patch-adapters налаштування, допоміжні функції нотаток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Допоміжні функції інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку облікових записів/конфігурації/action-gate |
|
||||
| `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервного значення за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні функції облікових записів | Допоміжні функції списку облікових записів/дій облікового запису |
|
||||
| `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Примітиви DM pairing | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + wiring індикатора набору | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання опису, перевірка дублікатів/конфліктів |
|
||||
| `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Відстеження статусу облікового запису | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби побудови route + envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідної відповіді | Спільні допоміжні засоби record-and-dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound runtime | Допоміжні засоби outbound identity/send delegate |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби thread-binding | Життєвий цикл thread-binding і допоміжні засоби адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор agent media payload для застарілих схем полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime |
|
||||
| `plugin-sdk/channel-config-schema` | Builders схем конфігурації | Типи схем конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів |
|
||||
| `plugin-sdk/channel-policy` | Визначення політики group/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Допоміжні функції вхідних envelope | Спільні допоміжні функції маршрутизації + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції запису та dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Розбір messaging targets | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні функції вихідного runtime | Допоміжні функції outbound identity/send delegate |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу thread-binding та адаптерів |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder agent media payload для застарілих layout полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді |
|
||||
| `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/install plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Logger/runtime env, допоміжні засоби timeout, retry і backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби plugin runtime | Допоміжні засоби команд/hooks/http/interactive для plugin |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні засоби pipeline hooks | Спільні допоміжні засоби pipeline webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби gateway | Gateway client і допоміжні засоби patch статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби prompt для approval | Payload approval exec/plugin, допоміжні засоби можливостей/профілю approval, маршрутизація/runtime native approval |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби approval client | Допоміжні засоби профілю/фільтра native approval exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери можливостей/доставки native approval |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілі/облікового запису native approval |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval exec/plugin |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, DM gating, external-content і збору секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби diagnostic gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці policy |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/встановлення plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Logger/runtime env, timeout, retry та backoff helpers |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime plugin | Допоміжні функції команд/hooks/http/interactive plugin |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра hook | Спільні допоміжні функції конвеєра webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні функції runtime CLI | Форматування команд, очікування, допоміжні функції версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні функції gateway | Client gateway та допоміжні функції patch статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції валідації команд Telegram зі стабільним резервним режимом, коли surface контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції prompt approval | Payload approval exec/plugin, допоміжні функції capability/profile approval, native approval routing/runtime helpers |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції автентифікації approval | Визначення approver, автентифікація дій у тому ж чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції client approval | Допоміжні функції native exec approval profile/filter |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки approval | Адаптери native approval capability/delivery |
|
||||
| `plugin-sdk/approval-handler-runtime` | Допоміжні функції handler approval | Спільні допоміжні функції runtime handler approval, включно із завантаженням native approval на основі capability |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей approval | Допоміжні функції binding native approval target/account |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply approval | Допоміжні функції payload reply approval exec/plugin |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні функції runtime-context каналу | Загальні допоміжні функції register/get/watch для channel runtime-context |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції trust, DM gating, external-content і збирання secret |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції runtime SSRF | Допоміжні функції pinned-dispatcher, guarded fetch, політики SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні функції керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch/proxy | `resolveFetch`, допоміжні функції proxy |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, виконавці політик |
|
||||
| `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Зіставлення вводу allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Допоміжні засоби gating команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд |
|
||||
| `plugin-sdk/secret-input` | Розбір введення секретів | Допоміжні засоби введення секретів |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів webhook | Утиліти цілей webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби guards для тіла webhook-запиту | Допоміжні засоби читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Inbound dispatch, heartbeat, планувальник відповідей, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch відповідей | Допоміжні засоби finalize + provider dispatch |
|
||||
| `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування посилань на відповідь | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні засоби chunks відповіді | Допоміжні засоби chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби session store | Допоміжні засоби шляху сховища + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів state і OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори підсумку статусу каналу/облікового запису, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Допоміжні засоби target resolver | Спільні допоміжні засоби target resolver |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витяг рядкових URL із request-подібних вхідних даних |
|
||||
| `plugin-sdk/run-command` | Допоміжні засоби timed command | Виконавець команд із таймерами та нормалізованими stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Читачі параметрів | Поширені читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Керування командами та допоміжні функції surface команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд |
|
||||
| `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні функції запитів webhook | Утиліти цілей webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції guard тіла webhook | Допоміжні функції читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Inbound dispatch, heartbeat, planner відповідей, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповідей | Допоміжні функції finalize + dispatch provider |
|
||||
| `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування reply reference | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні функції chunk відповіді | Допоміжні функції chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні функції сховища session | Шлях до сховища та допоміжні функції updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції директорій стану та OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні функції маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації session-key |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні функції статусу каналу | Builders зведення стану каналу/облікового запису, типові значення runtime-state, допоміжні функції метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Допоміжні функції target resolver | Спільні допоміжні функції target resolver |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації рядків | Допоміжні функції нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Допоміжні функції URL запиту | Витягування рядкових URL з request-подібних вхідних даних |
|
||||
| `plugin-sdk/run-command` | Допоміжні функції команд із тайм-аутом | Запускач команд із нормалізованими stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Витягування tool send | Витягування канонічних полів цілі надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби тимчасових шляхів для завантажень |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logging | Допоміжні засоби logger підсистеми та редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-table | Допоміжні засоби режимів markdown-таблиць |
|
||||
| `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи reply payload |
|
||||
| `plugin-sdk/provider-setup` | Куровані допоміжні засоби налаштування локального/self-hosted провайдера | Допоміжні засоби виявлення/конфігурації self-hosted провайдера |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдера |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime провайдера | Допоміжні засоби визначення API-ключа під час runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth провайдера | Стандартний конструктор результату OAuth auth |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars auth провайдера |
|
||||
| `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повтору провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та нормалізації model-id |
|
||||
| `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу провайдера web-fetch |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Цільові допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/runtime провайдера web-search |
|
||||
| `plugin-sdk/provider-tools` | Допоміжні засоби сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + diagnostics і допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдерів |
|
||||
| `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби fetch/transform/store медіа плюс конструктори media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибір кандидатів і повідомлення про відсутні моделі для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдера media understanding плюс орієнтовані на провайдера експорти допоміжних засобів для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні текстові допоміжні засоби | Видалення видимого асистенту тексту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, directive-tag, safe-text utilities і пов’язані допоміжні засоби text/logging |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні засоби text chunking | Допоміжний засіб chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні засоби speech | Типи провайдера speech плюс орієнтовані на провайдера допоміжні засоби директив, реєстру та перевірки |
|
||||
| `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдера speech, реєстр, директиви, нормалізація |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи провайдера та допоміжні засоби реєстру |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи провайдера та допоміжні засоби реєстру |
|
||||
| `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Допоміжні засоби типів, failover, auth і реєстру для генерації зображень |
|
||||
| `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату для генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату для генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивної відповіді | Нормалізація/зведення payload інтерактивної відповіді |
|
||||
| `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви schema конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Спільні експорти prelude channel plugin |
|
||||
| `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні засоби доступу груп | Спільні допоміжні засоби рішень group-access |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard direct-DM |
|
||||
| `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви passive-channel/status і ambient proxy helper |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби цілей webhook | Реєстр цілей webhook і допоміжні засоби встановлення route |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби шляху webhook | Допоміжні засоби нормалізації шляху webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддаленого/локального медіа |
|
||||
| `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні функції logging | Logger підсистеми та допоміжні функції редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні функції таблиць Markdown | Допоміжні функції режиму таблиць Markdown |
|
||||
| `plugin-sdk/reply-payload` | Типи відповідей на повідомлення | Типи payload відповіді |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted provider | Допоміжні функції виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted provider, сумісних з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime-автентифікації provider | Допоміжні функції визначення ключа API під час runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування ключа API provider | Допоміжні функції онбордингу/запису профілю для ключів API |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні функції результату автентифікації provider | Стандартний builder результату автентифікації OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу provider | Спільні допоміжні функції інтерактивного входу |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції env vars provider | Допоміжні функції пошуку env var для автентифікації provider |
|
||||
| `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builders політик replay, допоміжні функції endpoint provider та нормалізації model-id |
|
||||
| `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Patches онбордингу provider | Допоміжні функції конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-http` | Допоміжні функції HTTP provider | Загальні допоміжні функції HTTP/можливостей endpoint provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch provider | Допоміжні функції реєстрації/кешу web-fetch provider |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search provider | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter для scoped credentials |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні функції web-search provider | Допоміжні функції реєстрації/кешу/runtime web-search provider |
|
||||
| `plugin-sdk/provider-tools` | Допоміжні функції сумісності tool/schema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Допоміжні функції використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції використання provider |
|
||||
| `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper та спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/keyed-async-queue` | Упорядкована async-черга | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції fetch/transform/store медіа, а також builders media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору candidate та повідомлень про відсутність моделі для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні функції media-understanding | Типи provider media understanding, а також exports допоміжних функцій зображення/аудіо для provider |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Видалення тексту, видимого assistant, допоміжні функції render/chunking/table для markdown, допоміжні функції редагування, directive-tag, safe-text utilities та пов’язані допоміжні функції text/logging |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні функції chunking тексту | Допоміжна функція chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні функції speech | Типи provider speech, а також exports допоміжних функцій directive, registry і validation для provider |
|
||||
| `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider speech, registry, directives, normalization |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні функції realtime transcription | Типи provider та допоміжні функції registry |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні функції realtime voice | Типи provider та допоміжні функції registry |
|
||||
| `plugin-sdk/image-generation-core` | Спільне ядро image-generation | Типи image-generation, failover, auth та допоміжні функції registry |
|
||||
| `plugin-sdk/music-generation` | Допоміжні функції music-generation | Типи provider/request/result для генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільне ядро music-generation | Типи music-generation, допоміжні функції failover, пошуку provider та розбору model-ref |
|
||||
| `plugin-sdk/video-generation` | Допоміжні функції video-generation | Типи provider/request/result для генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільне ядро video-generation | Типи video-generation, допоміжні функції failover, пошуку provider та розбору model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей |
|
||||
| `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Exports спільного prelude channel plugin |
|
||||
| `plugin-sdk/channel-status` | Допоміжні функції статусу каналу | Спільні допоміжні функції snapshot/summary статусу каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні функції доступу до group | Спільні допоміжні функції прийняття рішень щодо доступу до group |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні функції direct-DM | Спільні допоміжні функції автентифікації/guard для direct-DM |
|
||||
| `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви passive-channel/status та ambient proxy helper |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні функції цілей webhook | Реєстр цілей webhook і допоміжні функції встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні функції шляхів webhook | Допоміжні функції нормалізації шляхів webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні функції web media | Допоміжні функції завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів memory manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime для memory engine | Фасад runtime для індексації/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Експорти embedding engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | Мультимодальні допоміжні засоби хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | Допоміжні засоби query хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | Допоміжні засоби secret хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні засоби core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад активного пошуку пам’яті | Лінивий фасад runtime search-manager активної пам’яті |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb |
|
||||
| `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks |
|
||||
| `plugin-sdk/memory-core` | Допоміжні функції вбудованого memory-core | Surface допоміжних функцій memory manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексації/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Exports рушія foundation хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings хоста пам’яті | Exports рушія embeddings хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Exports рушія QMD хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Exports рушія сховища хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | Допоміжні функції multimodal хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | Допоміжні функції запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста пам’яті | Допоміжні функції secret хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | Допоміжні функції журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті | Допоміжні функції статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні функції CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні функції core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | Допоміжні функції файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для plugin, суміжних із memory |
|
||||
| `plugin-sdk/memory-host-search` | Фасад пошуку active memory | Лінивий фасад runtime search-manager active memory |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Допоміжні функції вбудованого memory-lancedb | Surface допоміжних функцій memory-lancedb |
|
||||
| `plugin-sdk/testing` | Тестові утиліти | Допоміжні функції та mocks для тестування |
|
||||
</Accordion>
|
||||
|
||||
Ця таблиця навмисно містить поширену підмножину для міграції, а не повну
|
||||
поверхню SDK. Повний список із понад 200 entrypoints розміщено в
|
||||
Ця таблиця навмисно охоплює поширену підмножину для міграції, а не всю
|
||||
поверхню SDK. Повний список із понад 200 точок входу наведено в
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Цей список усе ще містить деякі допоміжні seams вбудованих plugin, такі як
|
||||
Цей список усе ще містить деякі шви допоміжних функцій вбудованих plugin, як-от
|
||||
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
|
||||
`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для
|
||||
підтримки та сумісності вбудованих plugin, але навмисно
|
||||
не включені до таблиці поширеної міграції та не є рекомендованою ціллю для
|
||||
не включені до таблиці поширеної міграції й не є рекомендованою ціллю для
|
||||
нового коду plugin.
|
||||
|
||||
Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, зокрема:
|
||||
Те саме правило застосовується до інших сімейств вбудованих допоміжних функцій, таких як:
|
||||
|
||||
- допоміжні засоби підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
|
||||
- допоміжні функції підтримки browser: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
|
||||
- Matrix: `plugin-sdk/matrix*`
|
||||
- LINE: `plugin-sdk/line*`
|
||||
- IRC: `plugin-sdk/irc*`
|
||||
- вбудовані допоміжні засоби/поверхні plugin, такі як `plugin-sdk/googlechat`,
|
||||
- surfaces вбудованих helper/plugin, як-от `plugin-sdk/googlechat`,
|
||||
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
|
||||
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
|
||||
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
|
||||
@ -339,39 +377,40 @@ plugin із цільовими, задокументованими імпорт
|
||||
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
|
||||
`plugin-sdk/thread-ownership` і `plugin-sdk/voice-call`
|
||||
|
||||
`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токена:
|
||||
`plugin-sdk/github-copilot-token` наразі розкриває вузьку surface допоміжних функцій токенів:
|
||||
`DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`.
|
||||
|
||||
Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти потрібний експорт,
|
||||
перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord.
|
||||
Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете
|
||||
знайти потрібний експорт, перевірте вихідний код у `src/plugin-sdk/`
|
||||
або запитайте в Discord.
|
||||
|
||||
## Хронологія видалення
|
||||
## Часова шкала видалення
|
||||
|
||||
| Коли | Що відбувається |
|
||||
| ---------------------- | ----------------------------------------------------------------------- |
|
||||
| **Зараз** | Застарілі поверхні надсилають попередження під час runtime |
|
||||
| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати |
|
||||
| **Зараз** | Застарілі поверхні видають попередження під час runtime |
|
||||
| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати |
|
||||
|
||||
Усі core plugins уже мігровано. Зовнішнім plugins слід виконати міграцію
|
||||
до наступного мажорного релізу.
|
||||
Усі core plugins уже перенесено. Зовнішнім plugin слід перейти
|
||||
до наступного мажорного випуску.
|
||||
|
||||
## Тимчасове приглушення попереджень
|
||||
|
||||
Поки ви працюєте над міграцією, встановіть ці змінні середовища:
|
||||
Установіть ці змінні середовища, поки працюєте над міграцією:
|
||||
|
||||
```bash
|
||||
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
|
||||
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
|
||||
```
|
||||
|
||||
Це тимчасовий обхідний механізм, а не постійне рішення.
|
||||
Це тимчасовий обхідний шлях, а не постійне рішення.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins
|
||||
- [Внутрішня будова plugin](/uk/plugins/architecture) — глибокий огляд архітектури
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення plugin каналів
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення plugin provider
|
||||
- [Внутрішня будова plugin](/uk/plugins/architecture) — глибокий розбір архітектури
|
||||
- [Маніфест plugin](/uk/plugins/manifest) — довідник зі схеми маніфесту
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібно знати, з якого підшляху SDK імпортувати
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Вам потрібен довідник щодо всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T08:02:41Z"
|
||||
generated_at: "2026-04-07T18:43:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727
|
||||
source_hash: 68d9b78dab757747cfa0e315376af72040ef79453129c0fa051c4c9dd948060f
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Огляд Plugin SDK
|
||||
|
||||
Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка —
|
||||
довідник про **що імпортувати** і **що можна зареєструвати**.
|
||||
Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є
|
||||
довідником щодо **що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте покроковий посібник?**
|
||||
- Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins)
|
||||
- Плагін каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Плагін провайдера? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
**Шукаєте практичний посібник?**
|
||||
- Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins)
|
||||
- Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## Угода щодо імпорту
|
||||
## Угода про імпорт
|
||||
|
||||
Завжди імпортуйте з конкретного підшляху:
|
||||
|
||||
@ -36,40 +36,40 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і
|
||||
Кожен підшлях — це невеликий, самодостатній модуль. Це пришвидшує запуск і
|
||||
запобігає проблемам із циклічними залежностями. Для специфічних для каналу
|
||||
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте
|
||||
для ширшої узагальненої поверхні та спільних допоміжних засобів, таких як
|
||||
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для
|
||||
ширшої парасолькової поверхні та спільних допоміжних засобів, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Не додавайте і не покладайтеся на зручні шви, названі на честь провайдерів, такі як
|
||||
Не додавайте й не використовуйте зручні шари з назвами провайдерів, як-от
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або
|
||||
допоміжні шви з брендингом каналів. Вбудовані плагіни мають компонувати
|
||||
загальні підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро
|
||||
має або використовувати ці локальні для плагіна barrel-файли, або додати вузький загальний SDK
|
||||
контракт, якщо потреба справді є міжканальною.
|
||||
допоміжні шари з брендуванням каналів. Вбудовані plugins мають компонувати загальні
|
||||
підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро
|
||||
має або використовувати ці локальні для plugin barrel-файли, або додати вузький загальний SDK
|
||||
контракт, коли потреба справді є міжканальною.
|
||||
|
||||
Згенерована карта експорту все ще містить невеликий набір допоміжних
|
||||
швів вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
Згенерована карта експортів усе ще містить невеликий набір допоміжних
|
||||
шарів для вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці
|
||||
підшляхи існують лише для підтримки та сумісності вбудованих плагінів; вони
|
||||
навмисно пропущені в загальній таблиці нижче і не є рекомендованим
|
||||
шляхом імпорту для нових сторонніх плагінів.
|
||||
підшляхи існують лише для підтримки вбудованих plugins і сумісності; вони
|
||||
навмисно не включені до загальної таблиці нижче й не є рекомендованим
|
||||
шляхом імпорту для нових сторонніх plugins.
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із
|
||||
понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в цьому
|
||||
згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності, якщо
|
||||
сторінка документації явно не оголошує якийсь із них публічним.
|
||||
Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому згенерованому списку.
|
||||
Ставтеся до них як до деталей реалізації/поверхонь сумісності, якщо якась сторінка документації
|
||||
явно не позначає один із них як публічний.
|
||||
|
||||
### Entry плагіна
|
||||
### Вхід plugin
|
||||
|
||||
| Підшлях | Ключові експорти |
|
||||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Subpath | Ключові експорти |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
@ -77,155 +77,157 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку allowlist, збирачі статусу налаштування |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку дозволених, конструктори статусу налаштування |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби багатооблікового запису config/action-gate, допоміжні засоби резервного вибору типового облікового запису |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації id облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного вибору типового значення |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби списку облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для мультиакаунтної конфігурації/гейтінгу дій, допоміжні засоби резервного переходу до акаунта за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора акаунта |
|
||||
| `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні засоби резервного переходу до значення за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку акаунтів/дій з акаунтами |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним варіантом для вбудованого контракту |
|
||||
| `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю для вбудованого контракту |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних даних |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідного маршруту та envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби делегування вихідної ідентичності/надсилання |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий збирач медіапейлоаду агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмови/потоку, парування та налаштованих прив’язок |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби для вихідної ідентичності/делегатів надсилання |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий конструктор медіа-пейлоаду агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмови/потоку, pairing і налаштованих прив’язок |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення політик груп у runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімків/зведень статусу каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагінів каналів |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо групового доступу |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту для прямих DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення інтерактивного reply payload |
|
||||
| `plugin-sdk/channel-inbound` | Допоміжні засоби debounce для вхідних повідомлень, зіставлення згадок, політики згадок і допоміжні засоби envelope |
|
||||
| `plugin-sdk/channel-send-result` | Типи результату відповіді |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби читання/редагування конфігурації списку дозволених |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/зведення пейлоадів інтерактивних відповідей |
|
||||
| `plugin-sdk/channel-inbound` | Вхідний debounce, зіставлення згадок, допоміжні засоби політики згадок і допоміжні засоби envelope |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів відповіді |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контракту каналу |
|
||||
| `plugin-sdk/channel-feedback` | Налаштування зворотного зв’язку/реакцій |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів |
|
||||
| `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, а також типи цілей секретів |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для плагінів провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth-автентифікації |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів |
|
||||
| `plugin-sdk/cli-backend` | Значення за замовчуванням бекенда CLI + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для plugins провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю для API-ключів, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth-автентифікації |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugins провайдерів |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдера |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі політик replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу для web-fetch провайдера |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime для web-search провайдера |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення + діагностика схеми Gemini та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime web-search провайдерів |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби внесення патчів до конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper-ів і спільні допоміжні wrapper-и для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи автентифікації та безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення апрувера та авторизації дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-auth-runtime` | Визначення approver-а та допоміжні засоби action-auth у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери доставки/можливостей native approval |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply payload для approval exec/plugin |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери доставлення/можливостей native approval |
|
||||
| `plugin-sdk/approval-handler-runtime` | Спільні допоміжні засоби runtime обробника approval, зокрема capability-driven завантаження native approval |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей native approval + прив’язки акаунтів |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби пейлоаду відповіді для exec/plugin approval |
|
||||
| `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
|
||||
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команд |
|
||||
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команд і командної поверхні |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору секретних контрактів для секретних поверхонь каналу/плагіна |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, external-content і збору секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом від SSRF і політики SSRF |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналів/plugins |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього контенту та збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби host allowlist і політики SSRF для приватних мереж |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, SSRF-захищеного fetch і політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout для запитів |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілей webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру тіла запиту/таймаутів |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервних копій/встановлення plugins |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для плагінів |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для plugins |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби пайплайна webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналу |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналів |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram та перевірки на дублікати/конфлікти, навіть коли поверхня вбудованого контракту Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби approval exec/plugin, збирачі approval-capability, допоміжні засоби auth/profile, native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, heartbeat, планувальник reply |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для reply |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублювання/конфліктів, навіть якщо поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, конструктори approval-capability, допоміжні засоби auth/profile, native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби вхідного/reply runtime, chunking, dispatch, heartbeat, planner відповідей |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповідей |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогу state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби прив’язки маршруту/ключа сесії/облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану runtime та допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до session store + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби прив’язки route/session-key/account, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу каналів/акаунтів, значення runtime-state за замовчуванням і допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби target resolver |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Витягування рядкових URL із введення, подібного до fetch/request |
|
||||
| `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів |
|
||||
| `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляху тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби subsystem logger і редагування чутливих даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму Markdown-таблиць |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Допоміжні засоби повторно-вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового кешу dedupe |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session і reply-dispatch для ACP |
|
||||
| `plugin-sdk/param-readers` | Поширені читачі параметрів tools/CLI |
|
||||
| `plugin-sdk/tool-send` | Витяг канонічних полів цілей надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування конфіденційних даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму markdown-таблиць |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state |
|
||||
| `plugin-sdk/file-lock` | Реентрантні допоміжні засоби file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби disk-backed dedupe cache |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session ACP і reply-dispatch |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Гнучкий читач булевих параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних назв |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів сполучення |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel, статусу та ambient proxy helper |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу, статусу й ambient proxy helper |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби команд `/models` і відповідей провайдерів |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize для native command |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native команд |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy та pinned lookup |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імені хоста та SCP-хоста |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів на основі конфігурації |
|
||||
@ -233,125 +235,125 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також збирачі медіапейлоадів |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа плюс конструктори медіа-пейлоадів |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення видимого для асистента тексту, допоміжні засоби render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і safe-text утиліти |
|
||||
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking для вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів допоміжні засоби для директив, реєстру та валідації |
|
||||
| `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі та допоміжні засоби реєстру |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдерів Media understanding плюс орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/markdown/логування, такі як видалення видимого асистенту тексту, допоміжні засоби render/chunking/table для markdown, редагування конфіденційних даних, допоміжні засоби тегів директив і безпечного тексту |
|
||||
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи speech-провайдерів плюс орієнтовані на провайдерів допоміжні засоби директив, реєстру та валідації |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech-провайдерів, реєстру, директив і допоміжні засоби нормалізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і допоміжні засоби реєстру |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи провайдерів генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref |
|
||||
| `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдерів і розбір model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху webhook |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/zod` | Реекспортований `zod` для користувачів Plugin SDK |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Ключові експорти |
|
||||
| Subpath | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI helper-ів |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний щодо вендора псевдонім для допоміжних засобів core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний щодо вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний щодо вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для плагінів, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Активний фасад runtime пам’яті для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний щодо вендора псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb |
|
||||
| `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних засобів core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для plugins, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад runtime активної пам’яті для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи допоміжних засобів вбудованих плагінів">
|
||||
| Сімейство | Поточні підшляхи | Призначення |
|
||||
<Accordion title="Зарезервовані підшляхи вбудованих helper-ів">
|
||||
| Family | Поточні підшляхи | Призначення |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається barrel-файлом сумісності) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого IRC |
|
||||
| Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів для вбудованих каналів |
|
||||
| Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` лишається barrel-ом сумісності) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper-ів/runtime вбудованого Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper-ів/runtime вбудованого LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper-ів вбудованого IRC |
|
||||
| Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари helper-ів/сумісності для вбудованих каналів |
|
||||
| Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шари helper-ів для вбудованих функцій/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API реєстрації
|
||||
|
||||
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerCliBackend(...)` | Локальний CLI backend для inference |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------------ | ------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerCliBackend(...)` | Локальний inference-бекенд CLI |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двосторонні сесії realtime voice |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
|
||||
### Інструменти та команди
|
||||
### Tools і команди
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------- | -------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
|
||||
### Інфраструктура
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Хук подій |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фонова служба |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| Method | Що реєструє |
|
||||
| ---------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Хук подій |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фоновий сервіс |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
|
||||
|
||||
Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити
|
||||
вужчу область методу gateway. Для
|
||||
методів, що належать плагіну, віддавайте перевагу префіксам, специфічним для плагіна.
|
||||
Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
|
||||
вужчу область методу gateway. Для методів, що належать plugin, віддавайте перевагу префіксам,
|
||||
специфічним для plugin.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, які належать registrar
|
||||
- `descriptors`: дескриптори команд на етапі розбору, які використовуються для довідки кореневого CLI,
|
||||
маршрутизації та ледачої реєстрації CLI плагіна
|
||||
- `commands`: явні корені команд, що належать registrar
|
||||
- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої довідки CLI,
|
||||
маршрутизації та lazy-реєстрації plugin CLI
|
||||
|
||||
Якщо ви хочете, щоб команда плагіна залишалася ледачо завантажуваною в
|
||||
звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що експонується цим
|
||||
Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному шляху кореневого CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим
|
||||
registrar.
|
||||
|
||||
```typescript
|
||||
@ -364,7 +366,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю",
|
||||
description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -372,128 +374,128 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands`, якщо вам не потрібна ледача реєстрація кореневого CLI.
|
||||
Цей сумісний eager-шлях залишається підтримуваним, але він не встановлює
|
||||
placeholders на основі descriptor для ледачого завантаження на етапі розбору.
|
||||
Використовуйте лише `commands`, якщо вам не потрібна lazy-реєстрація кореневого CLI.
|
||||
Цей сумісний eager-шлях і далі підтримується, але він не встановлює
|
||||
placeholder-и на основі descriptor для lazy loading на етапі розбору.
|
||||
|
||||
### Реєстрація CLI backend
|
||||
|
||||
`api.registerCliBackend(...)` дає змогу плагіну володіти типовою конфігурацією для локального
|
||||
AI CLI backend, такого як `codex-cli`.
|
||||
`api.registerCliBackend(...)` дозволяє plugin керувати конфігурацією за замовчуванням для локального
|
||||
CLI backend AI, такого як `codex-cli`.
|
||||
|
||||
- `id` backend стає префіксом провайдера в model ref на кшталт `codex-cli/gpt-5`.
|
||||
- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`.
|
||||
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
|
||||
типового значення плагіна перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття
|
||||
значення за замовчуванням plugin перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує переписування сумісності після злиття
|
||||
(наприклад, нормалізації старих форм прапорців).
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один) |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану очищення пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------ | ------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | Context engine (лише один активний одночасно) |
|
||||
| `api.registerMemoryCapability(capability)` | Єдину можливість пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
|
||||
### Адаптери вбудовування пам’яті
|
||||
### Адаптери embedding для пам’яті
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна |
|
||||
| Method | Що реєструє |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin |
|
||||
|
||||
- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті.
|
||||
- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб супутні плагіни могли споживати експортовані артефакти пам’яті через
|
||||
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватної
|
||||
структури конкретного плагіна пам’яті.
|
||||
- `registerMemoryCapability` — рекомендований API ексклюзивного plugin пам’яті.
|
||||
- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб супровідні plugins могли споживати експортовані артефакти пам’яті через
|
||||
`openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної
|
||||
структури конкретного plugin пам’яті.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивних плагінів пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу зареєструвати один
|
||||
або більше id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький
|
||||
id, визначений плагіном).
|
||||
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
|
||||
`registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивного plugin пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті зареєструвати один
|
||||
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або власний
|
||||
id, визначений plugin).
|
||||
- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих
|
||||
id адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Метод | Що він робить |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови |
|
||||
| Method | Що робить |
|
||||
| -------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови |
|
||||
|
||||
### Семантика рішень хука
|
||||
### Семантика рішень hook
|
||||
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник заявляє про диспетчеризацію, обробники з нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник візьме dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням.
|
||||
|
||||
### Поля об’єкта API
|
||||
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | ID плагіна |
|
||||
| `api.name` | `string` | Назва для відображення |
|
||||
| `api.version` | `string?` | Версія плагіна (необов’язково) |
|
||||
| `api.description` | `string?` | Опис плагіна (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела плагіна |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна |
|
||||
| Field | Type | Опис |
|
||||
| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Ідентифікатор plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія plugin (необов’язково) |
|
||||
| `api.description` | `string?` | Опис plugin (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела plugin |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, якщо доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація plugin з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня plugin |
|
||||
|
||||
## Внутрішня угода щодо модулів
|
||||
## Угода про внутрішні модулі
|
||||
|
||||
Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Публічні експорти для зовнішніх споживачів
|
||||
runtime-api.ts # Лише внутрішні експорти runtime
|
||||
index.ts # Точка входу плагіна
|
||||
runtime-api.ts # Внутрішні runtime-експорти
|
||||
index.ts # Точка входу plugin
|
||||
setup-entry.ts # Полегшений entry лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Для внутрішніх імпортів використовуйте `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Фасадно-завантажувані публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу
|
||||
активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime
|
||||
ще не існує, вони повертаються до визначеного файла конфігурації на диску.
|
||||
Facade-loaded публічні поверхні вбудованих plugins (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` і подібні публічні entry-файли) тепер віддають перевагу
|
||||
активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімка runtime
|
||||
ще не існує, вони повертаються до визначеного файлу конфігурації на диску.
|
||||
|
||||
Плагіни провайдерів також можуть експонувати вузький локальний barrel-файл контракту плагіна, коли
|
||||
певний допоміжний засіб навмисно є специфічним для провайдера і ще не належить до
|
||||
загального підшляху SDK. Поточний вбудований приклад: провайдер Anthropic зберігає свої
|
||||
допоміжні засоби потоків Claude у власному публічному шві `api.ts` / `contract-api.ts`
|
||||
замість просування логіки beta-header Anthropic і `service_tier` у загальний
|
||||
контракт `plugin-sdk/*`.
|
||||
Plugins провайдерів також можуть надавати вузький локальний barrel контракту plugin, якщо
|
||||
helper навмисно є специфічним для провайдера й поки що не належить до загального
|
||||
підшляху SDK. Поточний приклад серед вбудованих: провайдер Anthropic зберігає свої helper-и
|
||||
Claude stream у власному публічному шарі `api.ts` / `contract-api.ts` замість
|
||||
просування логіки Anthropic beta-header і `service_tier` до загального
|
||||
контракту `plugin-sdk/*`.
|
||||
|
||||
Інші поточні вбудовані приклади:
|
||||
Інші поточні приклади серед вбудованих:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує збирачі провайдерів,
|
||||
допоміжні засоби типових моделей і збирачі realtime-провайдерів
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує збирач провайдера, а також
|
||||
допоміжні засоби онбордингу/конфігурації
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує конструктори провайдерів,
|
||||
helper-и моделей за замовчуванням і конструктори realtime-провайдерів
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор провайдера та
|
||||
helper-и онбордингу/конфігурації
|
||||
|
||||
<Warning>
|
||||
Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою.
|
||||
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо helper справді є спільним, перенесіть його до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або до іншої
|
||||
поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
@ -503,4 +505,4 @@ my-plugin/
|
||||
- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації
|
||||
- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint
|
||||
- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь
|
||||
- [Plugin Internals](/uk/plugins/architecture) — глибока архітектура та модель можливостей
|
||||
- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей
|
||||
|
||||
@ -1,65 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштовуєте підтвердження exec або allowlist-и
|
||||
- Реалізуєте UX підтвердження exec у застосунку macOS
|
||||
- Переглядаєте запити на вихід із sandbox та їхні наслідки
|
||||
summary: Підтвердження Exec, allowlist-и та запити на вихід із sandbox
|
||||
title: Підтвердження Exec
|
||||
- Налаштування підтверджень exec або списків дозволів
|
||||
- Реалізація UX підтвердження exec у застосунку macOS
|
||||
- Перегляд запитів на вихід із sandbox і пов’язаних наслідків
|
||||
summary: Підтвердження exec, списки дозволів і запити на вихід із sandbox
|
||||
title: Підтвердження exec
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:21:15Z"
|
||||
generated_at: "2026-04-07T18:43:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22
|
||||
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Підтвердження exec
|
||||
|
||||
Підтвердження exec — це **запобіжний механізм companion app / вузла-хоста** для того, щоб дозволити sandbox-агенту запускати
|
||||
команди на реальному хості (`gateway` або `node`). Думайте про це як про запобіжне блокування:
|
||||
команди дозволяються лише тоді, коли політика + allowlist + (необов’язкове) підтвердження користувача збігаються.
|
||||
Підтвердження exec — це **захисний механізм застосунку-компаньйона / хоста вузла** для дозволу sandbox-агенту запускати
|
||||
команди на реальному хості (`gateway` або `node`). Сприймайте це як запобіжне блокування:
|
||||
команди дозволяються лише тоді, коли політика + список дозволів + (необов’язкове) підтвердження користувача всі погоджуються.
|
||||
Підтвердження exec діють **додатково** до політики інструментів і elevated gating (якщо тільки elevated не встановлено в `full`, що пропускає підтвердження).
|
||||
Ефективна політика — це **суворіше** з `tools.exec.*` і типових значень підтверджень; якщо поле підтверджень пропущено, використовується значення `tools.exec`.
|
||||
Ефективна політика — це **суворіша** з `tools.exec.*` і типових значень підтверджень; якщо поле підтверджень пропущене, використовується значення `tools.exec`.
|
||||
Host exec також використовує локальний стан підтверджень на цій машині. Локальне для хоста
|
||||
`ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує показувати запити, навіть якщо
|
||||
`ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує запитувати навіть якщо
|
||||
типові значення сесії або конфігурації вимагають `ask: "on-miss"`.
|
||||
Використовуйте `openclaw approvals get`, `openclaw approvals get --gateway` або
|
||||
`openclaw approvals get --node <id|name|ip>`, щоб переглянути запитану політику,
|
||||
джерела політики хоста та ефективний результат.
|
||||
|
||||
Якщо UI companion app **недоступний**, будь-який запит, що потребує підтвердження,
|
||||
обробляється через **ask fallback** (типово: deny).
|
||||
Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, що потребує підтвердження,
|
||||
обробляється через **резервну поведінку ask** (типово: deny).
|
||||
|
||||
Нативні клієнти підтвердження в чаті також можуть надавати прив’язаний до каналу інтерфейс у
|
||||
повідомленні з очікуванням підтвердження. Наприклад, Matrix може додати скорочення через реакції до
|
||||
запиту підтвердження (`✅` дозволити один раз, `❌` відхилити та `♾️` дозволити завжди, якщо доступно),
|
||||
при цьому залишаючи команди `/approve ...` у повідомленні як резервний варіант.
|
||||
Власні клієнти підтвердження в чаті також можуть надавати специфічні для каналу елементи інтерфейсу в повідомленні
|
||||
про очікуване підтвердження. Наприклад, Matrix може додавати швидкі реакції до
|
||||
запиту на підтвердження (`✅` дозволити один раз, `❌` відхилити та `♾️` завжди дозволяти, коли доступно),
|
||||
водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант.
|
||||
|
||||
## Де це застосовується
|
||||
|
||||
Підтвердження exec застосовуються локально на хості виконання:
|
||||
|
||||
- **gateway host** → процес `openclaw` на машині gateway
|
||||
- **node host** → runner вузла (companion app macOS або headless node host)
|
||||
- **node host** → раннер вузла (застосунок-компаньйон macOS або headless node host)
|
||||
|
||||
Примітка про модель довіри:
|
||||
Примітка щодо моделі довіри:
|
||||
|
||||
- Виклики, автентифіковані gateway, вважаються довіреними операторами для цього Gateway.
|
||||
- Спарені вузли розширюють цю можливість довіреного оператора на host вузла.
|
||||
- Підтвердження exec знижують ризик випадкового виконання, але не є межею автентифікації на рівні користувача.
|
||||
- Схвалені запуски на host вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env,
|
||||
якщо вона присутня, і зафіксований шлях до виконуваного файла, якщо застосовно.
|
||||
- Викликачі, автентифіковані gateway, є довіреними операторами для цього Gateway.
|
||||
- Спарені вузли розширюють цю можливість довіреного оператора на хост вузла.
|
||||
- Підтвердження exec зменшують ризик випадкового виконання, але не є межею автентифікації на рівні користувача.
|
||||
- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env
|
||||
за наявності та зафіксований шлях до виконуваного файла, де це застосовно.
|
||||
- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати
|
||||
один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання,
|
||||
запуск відхиляється замість виконання зміненого вмісту.
|
||||
- Ця прив’язка файла навмисно є best-effort, а не повною семантичною моделлю для кожного
|
||||
шляху завантажувача інтерпретатора/середовища виконання. Якщо режим підтвердження не може визначити рівно один конкретний локальний
|
||||
файл для прив’язки, він відмовляється створювати запуск на основі підтвердження замість того, щоб удавати повне покриття.
|
||||
- Ця прив’язка файлів навмисно є best-effort, а не повною семантичною моделлю для кожного шляху
|
||||
завантажувача інтерпретатора/середовища виконання. Якщо режим підтвердження не може точно визначити один конкретний локальний
|
||||
файл для прив’язки, він відмовляється створювати запуск із підтвердженням, а не вдає повне покриття.
|
||||
|
||||
Поділ на macOS:
|
||||
Поділ у macOS:
|
||||
|
||||
- **служба node host** пересилає `system.run` до **застосунку macOS** через локальний IPC.
|
||||
- **служба хоста вузла** пересилає `system.run` до **застосунку macOS** через локальний IPC.
|
||||
- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI.
|
||||
|
||||
## Налаштування та зберігання
|
||||
@ -105,10 +105,10 @@ Host exec також використовує локальний стан під
|
||||
|
||||
## Режим "YOLO" без підтверджень
|
||||
|
||||
Якщо ви хочете, щоб host exec працював без запитів на підтвердження, потрібно відкрити **обидва** шари політики:
|
||||
Якщо ви хочете, щоб host exec запускався без запитів на підтвердження, потрібно відкрити **обидва** шари політики:
|
||||
|
||||
- запитана політика exec у конфігурації OpenClaw (`tools.exec.*`)
|
||||
- локальна політика підтверджень хоста в `~/.openclaw/exec-approvals.json`
|
||||
- запитану політику exec у конфігурації OpenClaw (`tools.exec.*`)
|
||||
- локальну для хоста політику підтверджень у `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою:
|
||||
|
||||
@ -116,17 +116,17 @@ Host exec також використовує локальний стан під
|
||||
- `tools.exec.ask`: `off`
|
||||
- host `askFallback`: `full`
|
||||
|
||||
Важлива різниця:
|
||||
Важливе розрізнення:
|
||||
|
||||
- `tools.exec.host=auto` вибирає, де виконується exec: у sandbox, якщо доступно, інакше на gateway.
|
||||
- YOLO визначає, як підтверджується host exec: `security=full` плюс `ask=off`.
|
||||
- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд поверх налаштованої політики host exec.
|
||||
- `auto` не перетворює маршрутизацію на gateway на вільне перевизначення із сесії в sandbox. Запит `host=node` для окремого виклику дозволений із `auto`, а `host=gateway` дозволений із `auto` лише тоді, коли немає активного середовища виконання sandbox. Якщо вам потрібне стабільне типове значення без auto, задайте `tools.exec.host` або використовуйте `/exec host=...` явно.
|
||||
- `tools.exec.host=auto` вибирає, де виконується exec: у sandbox, коли доступно, інакше на gateway.
|
||||
- YOLO вибирає, як схвалюється host exec: `security=full` плюс `ask=off`.
|
||||
- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження обфускації команд поверх налаштованої політики host exec.
|
||||
- `auto` не робить маршрутизацію через gateway вільним обходом із sandbox-сесії. Запит `host=node` на рівні окремого виклику дозволений із `auto`, а `host=gateway` дозволяється з `auto` лише тоді, коли немає активного runtime sandbox. Якщо вам потрібен стабільний типово не-`auto` режим, задайте `tools.exec.host` або використовуйте `/exec host=...` явно.
|
||||
|
||||
Якщо ви хочете більш консервативне налаштування, поверніть будь-який шар до `allowlist` / `on-miss`
|
||||
Якщо вам потрібне більш консервативне налаштування, знову зробіть суворішим будь-який із шарів до `allowlist` / `on-miss`
|
||||
або `deny`.
|
||||
|
||||
Постійне налаштування для gateway host "ніколи не показувати запит":
|
||||
Постійне налаштування gateway host "ніколи не запитувати":
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
@ -135,7 +135,7 @@ openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Потім налаштуйте файл підтверджень хоста відповідно:
|
||||
Потім приведіть файл підтверджень хоста у відповідність:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Для host вузла застосуйте той самий файл підтверджень на цьому вузлі:
|
||||
Для хоста вузла замість цього застосуйте той самий файл підтверджень на цьому вузлі:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -165,39 +165,39 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Скорочення лише для сесії:
|
||||
Ярлик лише для сесії:
|
||||
|
||||
- `/exec security=full ask=off` змінює лише поточну сесію.
|
||||
- `/elevated full` — це break-glass скорочення, яке також пропускає підтвердження exec для цієї сесії.
|
||||
- `/elevated full` — це аварійний shortcut, який також пропускає підтвердження exec для цієї сесії.
|
||||
|
||||
Якщо файл підтверджень хоста залишається суворішим за конфігурацію, суворіша політика хоста все одно має пріоритет.
|
||||
Якщо файл підтверджень хоста залишається суворішим за конфігурацію, усе одно перемагає суворіша політика хоста.
|
||||
|
||||
## Параметри політики
|
||||
|
||||
### Security (`exec.security`)
|
||||
|
||||
- **deny**: блокувати всі запити host exec.
|
||||
- **allowlist**: дозволяти лише команди з allowlist.
|
||||
- **full**: дозволяти все (еквівалент elevated).
|
||||
- **allowlist**: дозволяти лише команди зі списку дозволів.
|
||||
- **full**: дозволяти все (еквівалентно elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off**: ніколи не показувати запит.
|
||||
- **on-miss**: показувати запит лише тоді, коли allowlist не збігається.
|
||||
- **always**: показувати запит для кожної команди.
|
||||
- тривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always`
|
||||
- **off**: ніколи не запитувати.
|
||||
- **on-miss**: запитувати лише коли список дозволів не збігається.
|
||||
- **always**: запитувати для кожної команди.
|
||||
- довіреність `allow-always` не пригнічує запити, коли ефективний режим ask — `always`
|
||||
|
||||
### Ask fallback (`askFallback`)
|
||||
|
||||
Якщо потрібне підтвердження, але жоден UI недоступний, fallback визначає результат:
|
||||
Якщо потрібне підтвердження, але жоден UI недосяжний, резервна поведінка вирішує:
|
||||
|
||||
- **deny**: блокувати.
|
||||
- **allowlist**: дозволяти лише за збігом allowlist.
|
||||
- **allowlist**: дозволяти лише якщо є збіг зі списком дозволів.
|
||||
- **full**: дозволяти.
|
||||
|
||||
### Посилення для inline interpreter eval (`tools.exec.strictInlineEval`)
|
||||
### Посилення для inline eval інтерпретатора (`tools.exec.strictInlineEval`)
|
||||
|
||||
Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає inline форми виконання коду як такі, що потребують лише підтвердження, навіть якщо сам бінарний файл інтерпретатора є в allowlist.
|
||||
Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає inline-форми виконання коду лише як такі, що потребують підтвердження, навіть якщо сам бінарний файл інтерпретатора є в списку дозволів.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -209,18 +209,18 @@ EOF
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
Це захист у глибину для завантажувачів інтерпретаторів, які не можна чисто зіставити з одним стабільним файловим операндом. У строгому режимі:
|
||||
Це defense-in-depth для завантажувачів інтерпретаторів, які не можна чисто відобразити на один стабільний файловий операнд. У strict mode:
|
||||
|
||||
- ці команди все одно потребують явного підтвердження;
|
||||
- `allow-always` не зберігає для них нові записи allowlist автоматично.
|
||||
- `allow-always` не зберігає для них нові записи списку дозволів автоматично.
|
||||
|
||||
## Allowlist (для кожного агента)
|
||||
## Список дозволів (для кожного агента)
|
||||
|
||||
Allowlist-и є **для кожного агента окремо**. Якщо агентів кілька, перемкніть агента,
|
||||
якого редагуєте, у застосунку macOS. Патерни — це **glob-збіги без урахування регістру**.
|
||||
Патерни мають вказувати на **шляхи до бінарних файлів** (записи лише з basename ігноруються).
|
||||
Застарілі записи `agents.default` мігрують у `agents.main` під час завантаження.
|
||||
Shell-ланцюжки на зразок `echo ok && pwd` усе одно вимагають, щоб кожен сегмент верхнього рівня задовольняв правила allowlist.
|
||||
Списки дозволів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть, якого агента ви
|
||||
редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**.
|
||||
Шаблони мають вказувати на **шляхи до бінарних файлів** (записи лише з basename ігноруються).
|
||||
Застарілі записи `agents.default` мігрують до `agents.main` під час завантаження.
|
||||
Shell-ланцюжки на кшталт `echo ok && pwd` усе одно вимагають, щоб кожен верхньорівневий сегмент відповідав правилам списку дозволів.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -228,43 +228,43 @@ Shell-ланцюжки на зразок `echo ok && pwd` усе одно вим
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
Кожен запис allowlist відстежує:
|
||||
Кожен запис списку дозволів відстежує:
|
||||
|
||||
- **id** — стабільний UUID для ідентичності в UI (необов’язково)
|
||||
- **last used** timestamp
|
||||
- **id** стабільний UUID, який використовується для ідентичності в UI (необов’язково)
|
||||
- **last used** мітка часу
|
||||
- **last used command**
|
||||
- **last resolved path**
|
||||
|
||||
## Автодозвіл CLI навичок
|
||||
## Автодозвіл для CLI Skills
|
||||
|
||||
Коли увімкнено **Auto-allow skill CLIs**, виконувані файли, на які посилаються відомі Skills,
|
||||
вважаються такими, що входять в allowlist на вузлах (macOS node або headless node host). Для цього використовується
|
||||
`skills.bins` через Gateway RPC, щоб отримати список бінарних файлів навичок. Вимкніть це, якщо вам потрібні суворі ручні allowlist-и.
|
||||
Коли **Auto-allow skill CLIs** увімкнено, виконувані файли, на які посилаються відомі Skills,
|
||||
вважаються такими, що входять до списку дозволів на вузлах (macOS node або headless node host). Для цього
|
||||
використовується `skills.bins` через Gateway RPC, щоб отримати список бінарних файлів skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволів.
|
||||
|
||||
Важливі примітки щодо довіри:
|
||||
|
||||
- Це **неявний зручний allowlist**, окремий від ручних записів allowlist за шляхами.
|
||||
- Він призначений для середовищ довірених операторів, де Gateway і вузол перебувають у межах однієї моделі довіри.
|
||||
- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи allowlist за шляхами.
|
||||
- Це **неявний зручний список дозволів**, окремий від ручних записів списку дозволів для шляхів.
|
||||
- Він призначений для середовищ із довіреними операторами, де Gateway і вузол перебувають в одній межі довіри.
|
||||
- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволів для шляхів.
|
||||
|
||||
## Safe bins (лише stdin)
|
||||
|
||||
`tools.exec.safeBins` визначає невеликий список бінарних файлів **лише для stdin** (наприклад, `cut`),
|
||||
які можуть виконуватися в режимі allowlist **без** явних записів allowlist. Safe bins відхиляють
|
||||
позиційні файлові аргументи й токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком.
|
||||
Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри.
|
||||
**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) до `safeBins`.
|
||||
Якщо команда може виконувати код, запускати підкоманди або читати файли за своїм задумом, краще використовувати явні записи allowlist і залишити запити підтвердження увімкненими.
|
||||
`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, `cut`),
|
||||
які можуть запускатися в режимі списку дозволів **без** явних записів у списку дозволів. Safe bins відхиляють
|
||||
позиційні файлові аргументи та токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком.
|
||||
Розглядайте це як вузький fast-path для потокових фільтрів, а не як загальний список довіри.
|
||||
**Не** додавайте до `safeBins` бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`).
|
||||
Якщо команда за задумом може обчислювати код, виконувати підкоманди або читати файли, краще використовувати явні записи списку дозволів і залишати ввімкненими запити на підтвердження.
|
||||
Користувацькі safe bins мають визначати явний профіль у `tools.exec.safeBinProfiles.<bin>`.
|
||||
Перевірка детерміновано ґрунтується лише на формі argv (без перевірок існування файлів у файловій системі хоста), що
|
||||
запобігає поведінці oracle за існуванням файлів через різницю allow/deny.
|
||||
Орієнтовані на файли опції відхиляються для типових safe bins (наприклад, `sort -o`, `sort --output`,
|
||||
Перевірка є детермінованою лише за формою argv (без перевірок існування у файловій системі хоста), що
|
||||
запобігає поведінці оракула існування файлів через різницю між allow/deny.
|
||||
Файлоорієнтовані параметри відхиляються для типових safe bins (наприклад, `sort -o`, `sort --output`,
|
||||
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
|
||||
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
|
||||
`grep -f/--file`).
|
||||
Safe bins також застосовують явну політику для прапорців кожного бінарного файла окремо для опцій, які порушують поведінку
|
||||
лише зі stdin (наприклад, `sort -o/--output/--compress-program` і рекурсивні прапорці grep).
|
||||
Довгі опції перевіряються fail-closed у режимі safe-bin: невідомі прапорці й неоднозначні
|
||||
Safe bins також застосовують явну політику для прапорців кожного бінарного файла окремо щодо параметрів, які порушують поведінку
|
||||
лише для stdin (наприклад, `sort -o/--output/--compress-program` і рекурсивні прапорці grep).
|
||||
Довгі параметри перевіряються в режимі safe-bin fail-closed: невідомі прапорці й неоднозначні
|
||||
скорочення відхиляються.
|
||||
Відхилені прапорці за профілем safe-bin:
|
||||
|
||||
@ -278,31 +278,31 @@ Safe bins також застосовують явну політику для
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
Safe bins також примусово обробляють токени argv як **буквальний текст** під час виконання (без globbing
|
||||
і без розгортання `$VARS`) для сегментів лише зі stdin, тож шаблони на кшталт `*` або `$HOME/...` не можуть бути
|
||||
і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони на кшталт `*` або `$HOME/...` не можуть бути
|
||||
використані для прихованого читання файлів.
|
||||
Safe bins також мають розв’язуватися лише з довірених каталогів бінарних файлів (типові системні каталоги плюс необов’язкові
|
||||
`tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично.
|
||||
Safe bins також мають визначатися з довірених каталогів бінарних файлів (системні типові плюс необов’язкові
|
||||
`tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються автоматично довіреними.
|
||||
Типові довірені каталоги safe-bin навмисно мінімальні: `/bin`, `/usr/bin`.
|
||||
Якщо ваш виконуваний файл safe-bin знаходиться у шляхах пакетного менеджера/користувача (наприклад
|
||||
Якщо ваш виконуваний файл safe-bin знаходиться в шляхах пакетного менеджера/користувача (наприклад
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно
|
||||
до `tools.exec.safeBinTrustedDirs`.
|
||||
Shell chaining і redirection не дозволяються автоматично в режимі allowlist.
|
||||
Shell-ланцюжки та перенаправлення не дозволяються автоматично в режимі списку дозволів.
|
||||
|
||||
Shell chaining (`&&`, `||`, `;`) дозволено, коли кожен сегмент верхнього рівня задовольняє allowlist
|
||||
(включно з safe bins або автодозволом навичок). Redirection залишається непідтримуваним у режимі allowlist.
|
||||
Підстановка команд (`$()` / backticks) відхиляється під час розбору allowlist, зокрема й усередині
|
||||
Shell-ланцюжки (`&&`, `||`, `;`) дозволяються, коли кожен верхньорівневий сегмент відповідає списку дозволів
|
||||
(включно із safe bins або автодозволом для skill). Перенаправлення залишаються непідтримуваними в режимі списку дозволів.
|
||||
Підстановка команд (`$()` / зворотні лапки) відхиляється під час розбору списку дозволів, зокрема всередині
|
||||
подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`.
|
||||
У підтвердженнях companion app macOS сирий shell-текст, що містить синтаксис керування shell або розгортання
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом allowlist, якщо
|
||||
сам бінарний файл shell не входить до allowlist.
|
||||
Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env на рівні запиту зводяться до
|
||||
невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Для рішень allow-always у режимі allowlist відомі dispatch-обгортки
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи виконуваних файлів, а не шляхи
|
||||
обгорток. Shell-мультиплексори (`busybox`, `toybox`) також розгортаються для shell-аплетів (`sh`, `ash`,
|
||||
тощо), тож зберігаються внутрішні виконувані файли, а не бінарні файли мультиплексора. Якщо обгортку або
|
||||
мультиплексор не можна безпечно розгорнути, жоден запис allowlist автоматично не зберігається.
|
||||
Якщо ви додаєте інтерпретатори на кшталт `python3` або `node` в allowlist, краще встановити `tools.exec.strictInlineEval=true`, щоб inline eval усе одно потребував явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються.
|
||||
У підтвердженнях застосунку-компаньйона macOS сирий shell-текст, що містить синтаксис керування shell або розгортання
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), розглядається як промах списку дозволів, якщо
|
||||
сам бінарний файл shell не входить до списку дозволів.
|
||||
Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env у межах запиту зводяться до
|
||||
невеликого явного списку дозволів (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Для рішень allow-always у режимі списку дозволів відомі dispatch-обгортки
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи до виконуваних файлів, а не шляхи
|
||||
до самих обгорток. Shell-мультиплексори (`busybox`, `toybox`) також розгортаються для shell-аплетів (`sh`, `ash`,
|
||||
тощо), щоб зберігалися внутрішні виконувані файли, а не бінарні файли мультиплексора. Якщо обгортку або
|
||||
мультиплексор неможливо безпечно розгорнути, запис списку дозволів не зберігається автоматично.
|
||||
Якщо ви вносите до списку дозволів інтерпретатори на кшталт `python3` або `node`, віддавайте перевагу `tools.exec.strictInlineEval=true`, щоб inline eval усе одно вимагав явного підтвердження. У strict mode `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються.
|
||||
|
||||
Типові safe bins:
|
||||
|
||||
@ -312,57 +312,57 @@ Shell chaining (`&&`, `||`, `;`) дозволено, коли кожен сег
|
||||
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` і `sort` не входять до типового списку. Якщо ви явно додаєте їх, залишайте явні записи allowlist для
|
||||
`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні записи списку дозволів для
|
||||
їхніх сценаріїв, не пов’язаних лише зі stdin.
|
||||
Для `grep` у режимі safe-bin задавайте патерн через `-e`/`--regexp`; позиційна форма патерна
|
||||
відхиляється, щоб файлові операнди не можна було приховати як неоднозначні позиційні аргументи.
|
||||
Для `grep` у режимі safe-bin передавайте шаблон через `-e`/`--regexp`; позиційна форма шаблону
|
||||
відхиляється, щоб файлові операнди не могли бути приховано передані як неоднозначні позиційні аргументи.
|
||||
|
||||
### Safe bins проти allowlist
|
||||
### Safe bins проти списку дозволів
|
||||
|
||||
| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| Тема | `tools.exec.safeBins` | Список дозволів (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Мета | Автодозвіл вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів |
|
||||
| Тип збігу | Ім’я виконуваного файла + політика argv safe-bin | Glob-патерн шляху до розв’язаного виконуваного файла |
|
||||
| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи далі відповідаєте ви |
|
||||
| Мета | Автоматично дозволяти вузькі stdin-фільтри | Явно довіряти конкретним виконуваним файлам |
|
||||
| Тип збігу | Назва виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла |
|
||||
| Обсяг аргументів | Обмежений профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи в іншому ви відповідаєте самі |
|
||||
| Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI |
|
||||
| Найкраще використання | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами |
|
||||
| Найкраще використання | Текстові перетворення з низьким ризиком у конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами |
|
||||
|
||||
Розташування конфігурації:
|
||||
|
||||
- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або для агента `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або для агента `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або для агента `agents.list[].tools.exec.safeBinProfiles`). Ключі профілів для агента перевизначають глобальні ключі.
|
||||
- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents.<id>.allowlist` (або через Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів.
|
||||
- `openclaw doctor --fix` може згенерувати відсутні записи `safeBinProfiles.<bin>` як `{}` (після цього перегляньте їх і зробіть суворішими). Для бінарних файлів інтерпретатора/середовища виконання автоматичне створення не виконується.
|
||||
- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або для окремого агента `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або для окремого агента `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або для окремого агента `agents.list[].tools.exec.safeBinProfiles`). Ключі профілів окремого агента мають пріоритет над глобальними ключами.
|
||||
- записи списку дозволів зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents.<id>.allowlist` (або через Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретаторів/середовищ виконання з’являються в `safeBins` без явних профілів.
|
||||
- `openclaw doctor --fix` може створити відсутні записи `safeBinProfiles.<bin>` як `{}` (після цього перегляньте й посильте їх). Бінарні файли інтерпретаторів/середовищ виконання не створюються автоматично.
|
||||
|
||||
Приклад користувацького профілю:
|
||||
__OC_I18N_900004__
|
||||
Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin,
|
||||
щоб `jq -n env` не міг вивантажити env хост-процесу без явного шляху allowlist
|
||||
тому `jq -n env` не може вивести env процесу хоста без явного шляху у списку дозволів
|
||||
або запиту на підтвердження.
|
||||
|
||||
## Редагування в Control UI
|
||||
|
||||
Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення
|
||||
для кожного агента й allowlist-и. Виберіть область (Defaults або агент), змініть політику,
|
||||
додайте/видаліть патерни allowlist, потім натисніть **Save**. UI показує метадані **last used**
|
||||
для кожного патерна, щоб ви могли підтримувати список у порядку.
|
||||
для окремих агентів і списки дозволів. Виберіть область дії (Defaults або агент), налаштуйте політику,
|
||||
додайте/видаліть шаблони списку дозволів, а потім натисніть **Save**. UI показує метадані **last used**
|
||||
для кожного шаблону, щоб вам було легше підтримувати порядок у списку.
|
||||
|
||||
Перемикач цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли
|
||||
мають повідомляти про `system.execApprovals.get/set` (застосунок macOS або headless node host).
|
||||
Якщо вузол ще не повідомляє про підтвердження exec, відредагуйте його локальний
|
||||
`~/.openclaw/exec-approvals.json` напряму.
|
||||
Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли
|
||||
мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless node host).
|
||||
Якщо вузол ще не оголошує exec approvals, відредагуйте його локальний
|
||||
`~/.openclaw/exec-approvals.json` безпосередньо.
|
||||
|
||||
CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI підтверджень](/cli/approvals)).
|
||||
CLI: `openclaw approvals` підтримує редагування gateway або node (див. [Approvals CLI](/cli/approvals)).
|
||||
|
||||
## Потік підтвердження
|
||||
|
||||
Коли потрібен запит на підтвердження, gateway транслює `exec.approval.requested` клієнтам-операторам.
|
||||
Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам операторів.
|
||||
Control UI та застосунок macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає
|
||||
схвалений запит до node host.
|
||||
схвалений запит на хост вузла.
|
||||
|
||||
Для `host=node` запити на підтвердження містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує
|
||||
Для `host=node` запити на підтвердження містять канонічний payload `systemRunPlan`. Gateway використовує
|
||||
цей план як авторитетний контекст команди/cwd/сесії під час пересилання схвалених запитів `system.run`.
|
||||
|
||||
Це важливо для затримки асинхронного підтвердження:
|
||||
@ -370,57 +370,58 @@ Control UI та застосунок macOS обробляють це через
|
||||
- шлях exec вузла готує один канонічний план наперед
|
||||
- запис підтвердження зберігає цей план і його метадані прив’язки
|
||||
- після схвалення фінальний пересланий виклик `system.run` повторно використовує збережений план
|
||||
замість того, щоб довіряти пізнішим змінам виклику
|
||||
- якщо виклик змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
замість довіри до пізніших змін викликача
|
||||
- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
`sessionKey` після створення запиту на підтвердження, gateway відхиляє
|
||||
пересланий запуск через невідповідність підтвердженню
|
||||
пересланий запуск як невідповідність підтвердженню
|
||||
|
||||
## Команди інтерпретатора/середовища виконання
|
||||
|
||||
Запуски інтерпретатора/середовища виконання, що спираються на підтвердження, навмисно консервативні:
|
||||
Запуски інтерпретатора/середовища виконання з підтвердженням навмисно є консервативними:
|
||||
|
||||
- Точний контекст argv/cwd/env завжди прив’язується.
|
||||
- Форми прямого shell-скрипта та прямого runtime-файла прив’язуються до одного конкретного локального
|
||||
знімка файла на основі best-effort.
|
||||
- Поширені форми обгорток пакетних менеджерів, які все ще розв’язуються в один прямий локальний файл (наприклад
|
||||
- Форми прямого shell-скрипта і прямого runtime-файла best-effort прив’язуються до одного конкретного snapshot локального
|
||||
файла.
|
||||
- Поширені форми обгорток пакетних менеджерів, які все ще зводяться до одного прямого локального файла (наприклад
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою.
|
||||
- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання
|
||||
(наприклад, package scripts, eval-форми, ланцюжки завантажувачів, специфічні для runtime, або
|
||||
неоднозначні форми з кількома файлами), виконання на основі підтвердження відхиляється замість того, щоб заявляти семантичне покриття, якого воно не має.
|
||||
- Для таких сценаріїв краще використовувати sandbox, окрему межу host або явний
|
||||
довірений робочий процес allowlist/full, де оператор приймає ширшу семантику runtime.
|
||||
(наприклад package scripts, eval-форми, ланцюжки завантажувачів, специфічні для runtime, або неоднозначні форми
|
||||
з кількома файлами), виконання з підтвердженням відхиляється замість заяв про семантичне покриття, якого
|
||||
насправді немає.
|
||||
- Для таких сценаріїв віддавайте перевагу sandboxing, окремій межі хоста або явному довіреному
|
||||
workflow зі списком дозволів/full, де оператор приймає ширшу семантику runtime.
|
||||
|
||||
Коли потрібні підтвердження, інструмент exec одразу повертає id підтвердження. Використовуйте цей id для
|
||||
співставлення з пізнішими системними подіями (`Exec finished` / `Exec denied`). Якщо рішення не надходить до
|
||||
закінчення тайм-ауту, запит вважається тайм-аутом підтвердження і відображається як причина відхилення.
|
||||
Коли потрібні підтвердження, інструмент exec негайно повертає id підтвердження. Використовуйте цей id, щоб
|
||||
співвідносити подальші системні події (`Exec finished` / `Exec denied`). Якщо жодне рішення не надходить до
|
||||
закінчення часу очікування, запит вважається тайм-аутом підтвердження й відображається як причина відмови.
|
||||
|
||||
### Поведінка доставки followup
|
||||
|
||||
Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` у ту саму сесію.
|
||||
Після завершення схваленого асинхронного exec OpenClaw надсилає followup-turn `agent` у ту саму сесію.
|
||||
|
||||
- Якщо існує дійсна зовнішня ціль доставки (канал доставки плюс ціль `to`), followup доставляється через цей канал.
|
||||
- У потоках лише webchat або внутрішніх сесіях без зовнішньої цілі followup залишається лише в сесії (`deliver: false`).
|
||||
- Якщо виклик явно вимагає суворої зовнішньої доставки, але жоден зовнішній канал не можна розв’язати, запит завершується помилкою `INVALID_REQUEST`.
|
||||
- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не можна розв’язати, доставка знижується до режиму лише сесії замість помилки.
|
||||
- Якщо існує дійсна зовнішня ціль доставки (канал, у який можна доставити, плюс ціль `to`), followup-доставка використовує цей канал.
|
||||
- У потоках лише webchat або внутрішньосесійних потоках без зовнішньої цілі доставка followup залишається лише в межах сесії (`deliver: false`).
|
||||
- Якщо викликач явно запитує сувору зовнішню доставку без зовнішнього каналу, який можна визначити, запит завершується помилкою `INVALID_REQUEST`.
|
||||
- Якщо ввімкнено `bestEffortDeliver` і неможливо визначити зовнішній канал, доставку знижують до режиму лише в сесії замість помилки.
|
||||
|
||||
Діалог підтвердження містить:
|
||||
|
||||
- команду + аргументи
|
||||
- cwd
|
||||
- id агента
|
||||
- розв’язаний шлях до виконуваного файла
|
||||
- метадані host + policy
|
||||
- визначений шлях до виконуваного файла
|
||||
- хост + метадані політики
|
||||
|
||||
Дії:
|
||||
|
||||
- **Allow once** → виконати зараз
|
||||
- **Always allow** → додати до allowlist + виконати
|
||||
- **Allow once** → запустити зараз
|
||||
- **Always allow** → додати до списку дозволів + запустити
|
||||
- **Deny** → заблокувати
|
||||
|
||||
## Пересилання підтверджень у канали чату
|
||||
## Пересилання підтверджень до чат-каналів
|
||||
|
||||
Ви можете пересилати запити підтвердження exec у будь-який канал чату (включно з каналами plugin) і підтверджувати
|
||||
їх через `/approve`. Це використовує звичайний конвеєр вихідної доставки.
|
||||
Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (включно з каналами plugin) і підтверджувати
|
||||
їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки.
|
||||
|
||||
Конфігурація:
|
||||
__OC_I18N_900005__
|
||||
@ -434,102 +435,100 @@ __OC_I18N_900006__
|
||||
незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше.
|
||||
__OC_I18N_900007__
|
||||
Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter` і `targets` працюють так само.
|
||||
`sessionFilter` і `targets` працюють однаково.
|
||||
|
||||
Канали, які підтримують спільні інтерактивні відповіді, показують ті самі кнопки підтвердження як для exec, так і для
|
||||
підтверджень plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями
|
||||
`/approve`.
|
||||
Канали, які підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для
|
||||
підтверджень plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`.
|
||||
|
||||
### Підтвердження в тому самому чаті на будь-якому каналі
|
||||
|
||||
Коли запит підтвердження exec або plugin походить із чату, який підтримує доставку, той самий чат
|
||||
тепер може підтвердити його через `/approve` типово. Це стосується таких каналів, як Slack, Matrix і
|
||||
Microsoft Teams, на додачу до наявних потоків через Web UI і terminal UI.
|
||||
Коли запит на підтвердження exec або plugin походить із чат-поверхні, у яку можна доставити повідомлення, цей самий чат
|
||||
тепер може типово підтвердити його через `/approve`. Це застосовується до таких каналів, як Slack, Matrix і
|
||||
Microsoft Teams, на додачу до наявних потоків Web UI і terminal UI.
|
||||
|
||||
Цей спільний шлях через текстову команду використовує звичайну модель автентифікації каналу для цієї розмови. Якщо
|
||||
початковий чат уже може надсилати команди й отримувати відповіді, запитам підтвердження більше не потрібен
|
||||
окремий нативний адаптер доставки лише для того, щоб залишатися в очікуванні.
|
||||
Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо чат-
|
||||
джерело вже може надсилати команди й отримувати відповіді, запитам на підтвердження більше не потрібен
|
||||
окремий власний адаптер доставки лише для того, щоб залишатися в очікуванні.
|
||||
|
||||
Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все одно використовують
|
||||
свій розв’язаний список схвалювачів для авторизації, навіть коли нативну доставку підтверджень вимкнено.
|
||||
Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все одно використовують свій
|
||||
визначений список схвалювачів для авторизації, навіть коли власну доставку підтверджень вимкнено.
|
||||
|
||||
Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway напряму,
|
||||
цей fallback навмисно обмежений помилками типу "approval not found". Реальне
|
||||
відхилення/помилка підтвердження exec не повторюється мовчки як підтвердження plugin.
|
||||
Для Telegram та інших власних клієнтів підтвердження, які напряму викликають Gateway,
|
||||
цей fallback навмисно обмежений помилками типу "підтвердження не знайдено". Реальна
|
||||
відмова/помилка підтвердження exec не повторюється мовчки як підтвердження plugin.
|
||||
|
||||
### Нативна доставка підтверджень
|
||||
### Власна доставка підтверджень
|
||||
|
||||
Деякі канали також можуть працювати як нативні клієнти підтвердження. Нативні клієнти додають DM схвалювачам, fanout до початкового чату
|
||||
та прив’язаний до каналу інтерактивний UX підтвердження поверх спільного потоку `/approve`
|
||||
в тому самому чаті.
|
||||
Деякі канали також можуть діяти як власні клієнти підтвердження. Власні клієнти додають DM для схвалювачів, fanout у чат-
|
||||
джерело та специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` у тому самому чаті.
|
||||
|
||||
Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним
|
||||
шляхом для агента. Агент не повинен також дублювати звичайну команду чату
|
||||
`/approve`, якщо тільки результат інструмента не вказує, що підтвердження через чат недоступні або
|
||||
ручне підтвердження — єдиний шлях, що залишився.
|
||||
Коли доступні власні картки/кнопки підтвердження, цей власний UI є основним
|
||||
шляхом для агента. Агент не повинен також дублювати звичайну чат-команду
|
||||
`/approve`, якщо тільки результат інструмента не каже, що чат-підтвердження недоступні або
|
||||
ручне підтвердження — це єдиний шлях, що залишився.
|
||||
|
||||
Загальна модель:
|
||||
|
||||
- політика host exec усе ще визначає, чи потрібне підтвердження exec
|
||||
- `approvals.exec` керує пересиланням запитів на підтвердження до інших цілей чату
|
||||
- `channels.<channel>.execApprovals` визначає, чи діє цей канал як нативний клієнт підтвердження
|
||||
- політика host exec, як і раніше, визначає, чи потрібне підтвердження exec
|
||||
- `approvals.exec` керує пересиланням запитів на підтвердження до інших чат-призначень
|
||||
- `channels.<channel>.execApprovals` керує тим, чи діє цей канал як власний клієнт підтвердження
|
||||
|
||||
Нативні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі ці умови істинні:
|
||||
Власні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі ці умови істинні:
|
||||
|
||||
- канал підтримує нативну доставку підтверджень
|
||||
- схвалювачів можна розв’язати з явних `execApprovals.approvers` або з
|
||||
документованих для цього каналу fallback-джерел
|
||||
- `channels.<channel>.execApprovals.enabled` не задано або дорівнює `"auto"`
|
||||
- канал підтримує власну доставку підтверджень
|
||||
- схвалювачів можна визначити з явних `execApprovals.approvers` або з
|
||||
документованих fallback-джерел цього каналу
|
||||
- `channels.<channel>.execApprovals.enabled` не задано або має значення `"auto"`
|
||||
|
||||
Встановіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Встановіть `enabled: true`, щоб примусово
|
||||
увімкнути його, коли схвалювачі розв’язуються. Доставка в публічний початковий чат залишається явною через
|
||||
Установіть `enabled: false`, щоб явно вимкнути власний клієнт підтвердження. Установіть `enabled: true`, щоб примусово
|
||||
ввімкнути його, коли схвалювачів визначено. Публічна доставка в чат-джерело, як і раніше, вмикається явно через
|
||||
`channels.<channel>.execApprovals.target`.
|
||||
|
||||
FAQ: [Чому існують дві конфігурації підтвердження exec для підтверджень у чаті?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
FAQ: [Чому існують дві конфігурації підтверджень exec для чат-підтверджень?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
|
||||
- Discord: `channels.discord.execApprovals.*`
|
||||
- Slack: `channels.slack.execApprovals.*`
|
||||
- Telegram: `channels.telegram.execApprovals.*`
|
||||
|
||||
Ці нативні клієнти підтвердження додають маршрутизацію до DM і необов’язковий fanout по каналу поверх спільного
|
||||
потоку `/approve` в тому самому чаті та спільних кнопок підтвердження.
|
||||
Ці власні клієнти підтвердження додають маршрутизацію в DM і необов’язковий fanout у канал поверх спільного
|
||||
потоку `/approve` у тому самому чаті та спільних кнопок підтвердження.
|
||||
|
||||
Спільна поведінка:
|
||||
|
||||
- Slack, Matrix, Microsoft Teams та подібні чати з доставкою використовують звичайну модель автентифікації каналу
|
||||
для `/approve` у тому самому чаті
|
||||
- коли нативний клієнт підтвердження вмикається автоматично, типовою нативною ціллю доставки є DM схвалювачів
|
||||
- для Discord і Telegram лише розв’язані схвалювачі можуть підтвердити або відхилити
|
||||
- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom`
|
||||
- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виведеними з наявної конфігурації owner (`allowFrom`, плюс `defaultTo` для direct message, де це підтримується)
|
||||
- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom`
|
||||
- нативні кнопки Slack зберігають вид ID підтвердження, тож ID `plugin:` можуть розв’язувати підтвердження plugin
|
||||
- коли власний клієнт підтвердження вмикається автоматично, типовою власною ціллю доставки є DM схвалювачів
|
||||
- для Discord і Telegram лише визначені схвалювачі можуть схвалювати або відхиляти
|
||||
- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom`
|
||||
- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації owner (`allowFrom`, плюс `defaultTo` для direct-message, де це підтримується)
|
||||
- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom`
|
||||
- власні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть визначати підтвердження plugin
|
||||
без другого локального fallback-рівня Slack
|
||||
- нативна маршрутизація Matrix до DM/каналу стосується лише exec; підтвердження plugin у Matrix залишаються на спільному
|
||||
шляху `/approve` у тому самому чаті та необов’язковому пересиланні через `approvals.plugin`
|
||||
- відправник запиту не обов’язково має бути схвалювачем
|
||||
- початковий чат може підтвердити напряму через `/approve`, коли цей чат уже підтримує команди й відповіді
|
||||
- нативні кнопки підтвердження Discord маршрутизуються за видом ID підтвердження: ID `plugin:` переходять
|
||||
- власна маршрутизація Matrix у DM/канал і shortcut-реакції обробляють як підтвердження exec, так і plugin;
|
||||
авторизація plugin, як і раніше, походить із `channels.matrix.dm.allowFrom`
|
||||
- запитувач не обов’язково має бути схвалювачем
|
||||
- чат-джерело може схвалити напряму через `/approve`, коли цей чат уже підтримує команди та відповіді
|
||||
- власні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять
|
||||
безпосередньо до підтверджень plugin, усе інше — до підтверджень exec
|
||||
- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого fallback exec-to-plugin, що й `/approve`
|
||||
- коли нативний `target` вмикає доставку до початкового чату, запити на підтвердження містять текст команди
|
||||
- власні кнопки підтвердження Telegram дотримуються того самого обмеженого fallback exec-to-plugin, що й `/approve`
|
||||
- коли власний `target` вмикає доставку в чат-джерело, запити на підтвердження містять текст команди
|
||||
- очікувані підтвердження exec типово спливають через 30 хвилин
|
||||
- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, запит переходить до `askFallback`
|
||||
|
||||
Типово Telegram використовує DM схвалювачів (`target: "dm"`). Ви можете переключити на `channel` або `both`, коли
|
||||
Telegram типово використовує DM схвалювачів (`target: "dm"`). Ви можете перемкнути на `channel` або `both`, якщо
|
||||
хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram
|
||||
OpenClaw зберігає тему для запиту підтвердження та followup після підтвердження.
|
||||
OpenClaw зберігає тему для запиту на підтвердження й follow-up після підтвердження.
|
||||
|
||||
Див.:
|
||||
Дивіться:
|
||||
|
||||
- [Discord](/channels/discord)
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Потік IPC на macOS
|
||||
### Потік IPC у macOS
|
||||
__OC_I18N_900008__
|
||||
Примітки щодо безпеки:
|
||||
|
||||
- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`.
|
||||
- Режим Unix-сокета `0600`, токен зберігається в `exec-approvals.json`.
|
||||
- Перевірка peer з тим самим UID.
|
||||
- Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL.
|
||||
|
||||
@ -541,36 +540,36 @@ __OC_I18N_900008__
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Вони публікуються в сесію агента після того, як вузол повідомляє про подію.
|
||||
Підтвердження exec на gateway host генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг).
|
||||
Вони публікуються в сесії агента після того, як вузол повідомляє про подію.
|
||||
Підтвердження exec на gateway host надсилають ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг).
|
||||
Exec із підтвердженням повторно використовують id підтвердження як `runId` у цих повідомленнях для зручної кореляції.
|
||||
|
||||
## Поведінка при відхиленому підтвердженні
|
||||
|
||||
Коли асинхронне підтвердження exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати
|
||||
Коли асинхронне підтвердження exec відхиляється, OpenClaw забороняє агенту повторно використовувати
|
||||
вивід будь-якого попереднього запуску тієї самої команди в сесії. Причина відхилення
|
||||
передається з явною вказівкою, що вивід команди недоступний, що не дає
|
||||
агенту стверджувати, ніби є новий вивід, або повторювати відхилену команду зі
|
||||
старими результатами від попереднього успішного запуску.
|
||||
передається разом із явною вказівкою, що жодного виводу команди немає, що заважає
|
||||
агенту стверджувати, що є новий вивід, або повторювати відхилену команду зі
|
||||
застарілими результатами попереднього успішного запуску.
|
||||
|
||||
## Наслідки
|
||||
|
||||
- **full** має великі повноваження; за можливості віддавайте перевагу allowlist-ам.
|
||||
- **ask** тримає вас у циклі, водночас даючи змогу швидко підтверджувати.
|
||||
- Allowlist-и для кожного агента окремо не дають підтвердженням одного агента просочуватися в інших.
|
||||
- **full** — це потужний режим; за можливості віддавайте перевагу спискам дозволів.
|
||||
- **ask** залишає вас у циклі, водночас даючи можливість швидко підтверджувати.
|
||||
- Списки дозволів для окремих агентів не дають підтвердженням одного агента просочуватися до інших.
|
||||
- Підтвердження застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`.
|
||||
- `/exec security=full` — це зручність на рівні сесії для авторизованих операторів, яка за задумом пропускає підтвердження.
|
||||
Щоб жорстко заборонити host exec, встановіть `security` підтверджень у `deny` або забороніть інструмент `exec` через політику інструментів.
|
||||
- `/exec security=full` — це зручність на рівні сесії для авторизованих операторів і за задумом пропускає підтвердження.
|
||||
Щоб жорстко заборонити host exec, установіть безпеку підтверджень у `deny` або забороніть інструмент `exec` через політику інструментів.
|
||||
|
||||
Пов’язане:
|
||||
|
||||
- [Інструмент Exec](/tools/exec)
|
||||
- [Режим Elevated](/tools/elevated)
|
||||
- [Skills](/tools/skills)
|
||||
- [Exec tool](/uk/tools/exec)
|
||||
- [Elevated mode](/uk/tools/elevated)
|
||||
- [Skills](/uk/tools/skills)
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Exec](/tools/exec) — інструмент виконання shell-команд
|
||||
- [Sandboxing](/uk/gateway/sandboxing) — режими sandbox і доступ до робочого простору
|
||||
- [Exec](/uk/tools/exec) — інструмент виконання shell-команд
|
||||
- [Sandboxing](/uk/gateway/sandboxing) — режими sandbox і доступ до workspace
|
||||
- [Security](/uk/gateway/security) — модель безпеки та посилення
|
||||
- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — коли що використовувати
|
||||
- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — коли використовувати кожен варіант
|
||||
|
||||
Loading…
Reference in New Issue
Block a user