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

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 23:36:59 +00:00
parent a319837e6b
commit fff4e6a66c
12 changed files with 2817 additions and 2728 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1548
docs/uk/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

1042
docs/uk/help/testing.md
View File

File diff suppressed because it is too large Load Diff

584
docs/uk/plugins/sdk-overview.md
View File

@ -1,389 +1,140 @@
---
read_when:
- Вам потрібно знати, з якого subpath SDK імпортувати】【”】【analysis to=final code_block=None ақәascii_fix_REASONING
- Потрібно знати, з якого підшляху SDK імпортувати
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
- Ви шукаєте конкретний export SDK
- Ви шукаєте конкретний експорт SDK
sidebarTitle: SDK overview
summary: Import map, довідник API реєстрації та архітектура SDK
summary: Карта імпорту, довідник з API реєстрації та архітектура SDK
title: Огляд Plugin SDK
x-i18n:
generated_at: "2026-04-23T21:03:18Z"
generated_at: "2026-04-23T23:27:51Z"
model: gpt-5.4
provider: openai
source_hash: efe676e4907428459ed3e30dd2e1df891eae0f0f1e87b0a850eb45140572a348
source_hash: 7090e13508382a68988f3d345bf12d6f3822c499e01a3affb1fa7a277b22f276
source_path: plugins/sdk-overview.md
workflow: 15
---
Plugin SDK — це типізований контракт між Plugins і core. Ця сторінка є
довідником для **що імпортувати** і **що можна реєструвати**.
Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка —
довідник про **що імпортувати** і **що можна реєструвати**.
<Tip>
Шукаєте натомість практичний посібник?
- Перший Plugin? Почніть з [Створення Plugins](/uk/plugins/building-plugins).
- Plugin каналу? Див. [Plugins каналів](/uk/plugins/sdk-channel-plugins).
- Plugin провайдера? Див. [Plugins провайдерів](/uk/plugins/sdk-provider-plugins).
- Перший plugin? Почніть із [Створення plugins](/uk/plugins/building-plugins).
- Channel plugin? Див. [Channel plugins](/uk/plugins/sdk-channel-plugins).
- Provider plugin? Див. [Provider plugins](/uk/plugins/sdk-provider-plugins).
</Tip>
## Угода щодо імпорту
Завжди імпортуйте з конкретного subpath:
Завжди імпортуйте з конкретного підшляху:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Кожен subpath — це невеликий самодостатній модуль. Це пришвидшує запуск і
запобігає проблемам із циклічними залежностями. Для entry/build helper-ів, специфічних для каналів,
віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для
ширшої umbrella-поверхні та спільних helper-ів, як-от
Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і
запобігає проблемам із циклічними залежностями. Для специфічних для channel
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для
ширшої узагальненої поверхні та спільних допоміжних засобів, таких як
`buildChannelConfigSchema`.
<Warning>
Не імпортуйте provider- або channel-брендовані convenience-seam-и (наприклад
Не імпортуйте branded convenience seams для provider або channel (наприклад
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Вбудовані Plugins композують універсальні subpath-и SDK у власних barrel-файлах `api.ts` /
`runtime-api.ts`; споживачам core слід або використовувати ці plugin-local
barrel-и, або додавати вузький універсальний контракт SDK, коли потреба справді є
Вбудовані plugins компонують загальні підшляхи SDK у власних barrel-файлах `api.ts` /
`runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для plugin
barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді є
міжканальною.
Невеликий набір helper-seam-ів для bundled Plugin (`plugin-sdk/feishu`,
`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється у
згенерованій export map. Вони існують лише для супроводу bundled Plugin і
не рекомендуються як шляхи імпорту для нових сторонніх Plugins.
Невеликий набір допоміжних seams для вбудованих plugins (`plugin-sdk/feishu`,
`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в
згенерованій карті експортів. Вони існують лише для підтримки вбудованих plugins і
не рекомендовані як шляхи імпорту для нових сторонніх plugins.
</Warning>
## Довідник subpath-ів
## Довідник підшляхів
Найуживаніші subpath-и, згруповані за призначенням. Згенерований повний список із
200+ subpath-ів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; зарезервовані
helper-subpath-и bundled Plugin там теж присутні, але є деталлю реалізації,
якщо тільки якась сторінка документації явно не рекомендує їх.
Plugin SDK надається як набір вузьких підшляхів, згрупованих за областями (plugin
entry, channel, provider, auth, runtime, capability, memory і зарезервовані
допоміжні засоби для вбудованих plugins). Повний каталог — згрупований і з посиланнями — див. у
[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
### Entry Plugin
| Subpath | Key exports |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Subpath-и каналів">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Root Zod-схема `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Спільні helper-и setup wizard, prompts allowlist, builders статусу 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` | Helper-и multi-account config/action-gate, helper-и fallback для default-account |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper-и нормалізації account-id |
| `plugin-sdk/account-resolution` | Lookup account + helper-и fallback до default |
| `plugin-sdk/account-helpers` | Вузькі helper-и list/action для account |
| `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` | Helper-и нормалізації/валідації кастомних команд Telegram з fallback до bundled-contract |
| `plugin-sdk/command-gating` | Вузькі helper-и authorization gate для команд |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper-и життєвого циклу/фіналізації draft stream |
| `plugin-sdk/inbound-envelope` | Спільні helper-и для побудови inbound route + envelope |
| `plugin-sdk/inbound-reply-dispatch` | Спільні helper-и для inbound record-and-dispatch |
| `plugin-sdk/messaging-targets` | Helper-и парсингу/зіставлення target |
| `plugin-sdk/outbound-media` | Спільні helper-и завантаження outbound media |
| `plugin-sdk/outbound-runtime` | Helper-и outbound identity, send delegate і планування payload |
| `plugin-sdk/poll-runtime` | Вузькі helper-и нормалізації poll |
| `plugin-sdk/thread-bindings-runtime` | Helper-и життєвого циклу та adapter для thread-binding |
| `plugin-sdk/agent-media-payload` | Застарілий builder media payload агента |
| `plugin-sdk/conversation-runtime` | Helper-и conversation/thread binding, pairing і configured-binding |
| `plugin-sdk/runtime-config-snapshot` | Helper runtime config snapshot |
| `plugin-sdk/runtime-group-policy` | Helper-и розв’язання runtime group-policy |
| `plugin-sdk/channel-status` | Спільні helper-и snapshot/summary статусу каналу |
| `plugin-sdk/channel-config-primitives` | Вузькі primitives схеми конфігурації каналу |
| `plugin-sdk/channel-config-writes` | Helper-и authorization для config-write каналу |
| `plugin-sdk/channel-plugin-common` | Спільні prelude-export-и Plugin каналу |
| `plugin-sdk/allowlist-config-edit` | Helper-и редагування/читання конфігурації allowlist |
| `plugin-sdk/group-access` | Спільні helper-и рішень щодо group-access |
| `plugin-sdk/direct-dm` | Спільні helper-и auth/guard для direct-DM |
| `plugin-sdk/interactive-runtime` | Semantic presentation повідомлень, доставка та helper-и застарілої interactive reply. Див. [Представлення повідомлень](/uk/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Compatibility barrel для inbound debounce, mention matching, helper-ів mention-policy та envelope |
| `plugin-sdk/channel-mention-gating` | Вузькі helper-и mention-policy без ширшої inbound runtime-поверхні |
| `plugin-sdk/channel-location` | Helper-и контексту й форматування location каналу |
| `plugin-sdk/channel-logging` | Helper-и логування каналу для inbound drop і збоїв typing/ack |
| `plugin-sdk/channel-send-result` | Типи результатів reply |
| `plugin-sdk/channel-actions` | Helper-и дій повідомлень каналу, а також застарілі helper-и native schema, збережені для сумісності Plugin |
| `plugin-sdk/channel-targets` | Helper-и парсингу/зіставлення target |
| `plugin-sdk/channel-contract` | Типи контракту каналу |
| `plugin-sdk/channel-feedback` | Wiring feedback/reaction |
| `plugin-sdk/channel-secret-runtime` | Вузькі helper-и secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target |
</Accordion>
<Accordion title="Subpath-и провайдерів">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Добірні helper-и setup для локальних/self-hosted провайдерів |
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані helper-и setup для self-hosted провайдерів, сумісних з OpenAI |
| `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog |
| `plugin-sdk/provider-auth-runtime` | Helper-и runtime-розв’язання API-ключів для Plugin провайдерів |
| `plugin-sdk/provider-auth-api-key` | Helper-и onboarding/profile-write для API-ключів, такі як `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Стандартний builder результату OAuth auth |
| `plugin-sdk/provider-auth-login` | Спільні helper-и інтерактивного login для Plugin провайдерів |
| `plugin-sdk/provider-env-vars` | Helper-и пошуку env vars для auth провайдера |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, helper-и endpoint провайдерів і helper-и нормалізації model-id, такі як `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Універсальні helper-и HTTP/endpoint capability для провайдерів, зокрема helper-и multipart form для транскрипції аудіо |
| `plugin-sdk/provider-web-fetch-contract` | Вузькі helper-и контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper-и реєстрації/cache/runtime для web-fetch провайдерів |
| `plugin-sdk/provider-web-search-config-contract` | Вузькі helper-и config/credential для web-search провайдерів, яким не потрібне ввімкнення Plugin у wiring |
| `plugin-sdk/provider-web-search-contract` | Вузькі helper-и контракту config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, а також scoped setter/getter-и облікових даних |
| `plugin-sdk/provider-web-search` | Helper-и реєстрації/cache/runtime для web-search провайдерів |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + diagnostics і helper-и compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібні |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні helper-и wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Native helper-и provider transport, такі як guarded fetch, transport message transforms і writable transport event streams |
| `plugin-sdk/provider-onboard` | Helper-и patch конфігурації onboarding |
| `plugin-sdk/global-singleton` | Helper-и process-local singleton/map/cache |
</Accordion>
<Accordion title="Subpath-и auth і security">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper-и registry команд, helper-и авторизації відправника |
| `plugin-sdk/command-status` | Builder-и повідомлень command/help, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Розв’язання approver і helper-и same-chat action-auth |
| `plugin-sdk/approval-client-runtime` | Native helper-и profile/filter для exec approval |
| `plugin-sdk/approval-delivery-runtime` | Native adapter-и capability/delivery для approval |
| `plugin-sdk/approval-gateway-runtime` | Спільний helper розв’язання approval gateway |
| `plugin-sdk/approval-handler-adapter-runtime` | Легкі helper-и завантаження native approval adapter для гарячих channel entrypoint |
| `plugin-sdk/approval-handler-runtime` | Ширші helper-и runtime для approval handler; віддавайте перевагу вужчим adapter/gateway seam-ам, коли їх достатньо |
| `plugin-sdk/approval-native-runtime` | Native helper-и target + account-binding для approval |
| `plugin-sdk/approval-reply-runtime` | Helper-и reply payload для exec/plugin approval |
| `plugin-sdk/command-auth-native` | Native command auth + native helper-и session-target |
| `plugin-sdk/command-detection` | Спільні helper-и виявлення команд |
| `plugin-sdk/command-surface` | Helper-и нормалізації command-body і command-surface |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Вузькі helper-и збирання secret-contract для secret-поверхонь channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Вузькі helper-и `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config |
| `plugin-sdk/security-runtime` | Спільні helper-и trust, DM gating, external-content і збирання секретів |
| `plugin-sdk/ssrf-policy` | Helper-и allowlist хостів і SSRF policy для приватних мереж |
| `plugin-sdk/ssrf-dispatcher` | Вузькі helper-и pinned-dispatcher без широкої infra runtime-поверхні |
| `plugin-sdk/ssrf-runtime` | Helper-и pinned-dispatcher, SSRF-guarded fetch і SSRF policy |
| `plugin-sdk/secret-input` | Helper-и парсингу secret input |
| `plugin-sdk/webhook-ingress` | Helper-и request/target для webhook |
| `plugin-sdk/webhook-request-guards` | Helper-и розміру тіла запиту/timeout |
</Accordion>
<Accordion title="Subpath-и runtime і storage">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/runtime` | Широкі helper-и runtime/logging/backup/plugin-install |
| `plugin-sdk/runtime-env` | Вузькі helper-и runtime env, logger, timeout, retry і backoff |
| `plugin-sdk/channel-runtime-context` | Універсальні helper-и реєстрації та lookup runtime-context каналу |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Спільні helper-и plugin command/hook/http/interactive |
| `plugin-sdk/hook-runtime` | Спільні helper-и pipeline webhook/internal hook |
| `plugin-sdk/lazy-runtime` | Helper-и lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper-и exec процесів |
| `plugin-sdk/cli-runtime` | Helper-и форматування, wait і version для CLI |
| `plugin-sdk/gateway-runtime` | Helper-и клієнта Gateway і patch channel-status |
| `plugin-sdk/config-runtime` | Helper-и load/write конфігурації та helper-и lookup plugin-config |
| `plugin-sdk/telegram-command-config` | Helper-и нормалізації name/description команд Telegram і перевірки duplicate/conflict, навіть коли поверхня bundled Telegram contract недоступна |
| `plugin-sdk/text-autolink-runtime` | Виявлення autolink для file-reference без широкого barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Helper-и exec/plugin approval, builder-и approval-capability, helper-и auth/profile, native routing/runtime |
| `plugin-sdk/reply-runtime` | Спільні inbound/reply runtime helper-и, chunking, dispatch, heartbeat, reply planner |
| `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-и dispatch/finalize для reply |
| `plugin-sdk/reply-history` | Спільні helper-и короткого вікна history для reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Вузькі helper-и chunking для text/markdown |
| `plugin-sdk/session-store-runtime` | Helper-и path + updated-at для session store |
| `plugin-sdk/state-paths` | Helper-и шляхів state/OAuth dir |
| `plugin-sdk/routing` | Helper-и route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Спільні helper-и summary статусу channel/account, типові значення runtime-state і helper-и metadata проблем |
| `plugin-sdk/target-resolver-runtime` | Спільні helper-и target resolver |
| `plugin-sdk/string-normalization-runtime` | Helper-и slug/string normalization |
| `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів |
| `plugin-sdk/run-command` | Runner команд із timeout і нормалізованими результатами stdout/stderr |
| `plugin-sdk/param-readers` | Поширені readers параметрів tool/CLI |
| `plugin-sdk/tool-payload` | Витяг нормалізованих payload-ів із об’єктів результатів tool |
| `plugin-sdk/tool-send` | Витяг канонічних полів send target з аргументів tool |
| `plugin-sdk/temp-path` | Спільні helper-и шляхів тимчасового завантаження |
| `plugin-sdk/logging-core` | Helper-и subsystem logger і redaction |
| `plugin-sdk/markdown-table-runtime` | Helper-и режиму Markdown table |
| `plugin-sdk/json-store` | Невеликі helper-и читання/запису JSON state |
| `plugin-sdk/file-lock` | Re-entrant helper-и file-lock |
| `plugin-sdk/persistent-dedupe` | Helper-и disk-backed dedupe cache |
| `plugin-sdk/acp-runtime` | Helper-и ACP runtime/session і reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Read-only розв’язання ACP binding без import-ів startup lifecycle |
| `plugin-sdk/agent-config-primitives` | Вузькі primitives схеми конфігурації agent runtime |
| `plugin-sdk/boolean-param` | Loose reader boolean-параметрів |
| `plugin-sdk/dangerous-name-runtime` | Helper-и розв’язання dangerous-name matching |
| `plugin-sdk/device-bootstrap` | Helper-и device bootstrap і pairing token |
| `plugin-sdk/extension-shared` | Спільні primitives helper-ів passive-channel, status і ambient proxy |
| `plugin-sdk/models-provider-runtime` | Helper-и відповідей `/models` command/provider |
| `plugin-sdk/skill-commands-runtime` | Helper-и переліку команд Skill |
| `plugin-sdk/native-command-registry` | Helper-и registry/build/serialize для native команд |
| `plugin-sdk/agent-harness` | Експериментальна trusted-plugin-поверхня для низькорівневих harness агента: типи harness, helper-и steer/abort для active-run, helper-и bridge інструментів OpenClaw і утиліти результатів спроб |
| `plugin-sdk/provider-zai-endpoint` | Helper-и виявлення endpoint Z.AI |
| `plugin-sdk/infra-runtime` | Helper-и system event/heartbeat |
| `plugin-sdk/collection-runtime` | Невеликі helper-и bounded cache |
| `plugin-sdk/diagnostic-runtime` | Helper-и діагностичних прапорців і подій |
| `plugin-sdk/error-runtime` | Helper-и graph/formatting/error classification, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper-и wrapped fetch, proxy і pinned lookup |
| `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без import-ів proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Reader обмеженого response-body без широкої media runtime-поверхні |
| `plugin-sdk/session-binding-runtime` | Поточний стан conversation binding без configured binding routing або pairing store |
| `plugin-sdk/session-store-runtime` | Helper-и читання session-store без широких import-ів config writes/maintenance |
| `plugin-sdk/context-visibility-runtime` | Розв’язання context visibility і фільтрація supplemental context без широких import-ів config/security |
| `plugin-sdk/string-coerce-runtime` | Вузькі helper-и coercion і normalization для primitive record/string без import-ів markdown/logging |
| `plugin-sdk/host-runtime` | Helper-и нормалізації hostname і SCP host |
| `plugin-sdk/retry-runtime` | Helper-и конфігурації retry і retry runner |
| `plugin-sdk/agent-runtime` | Helper-и agent dir/identity/workspace |
| `plugin-sdk/directory-runtime` | Query/dedup directory на основі config |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subpath-и capabilities і testing">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/media-runtime` | Спільні helper-и fetch/transform/store для media плюс builder-и media payload |
| `plugin-sdk/media-generation-runtime` | Спільні helper-и failover для media-generation, вибір кандидатів і повідомлення про відсутню модель |
| `plugin-sdk/media-understanding` | Типи провайдерів media understanding плюс provider-facing export-и helper-ів image/audio |
| `plugin-sdk/text-runtime` | Спільні helper-и text/markdown/logging, такі як assistant-visible-text stripping, helper-и render/chunking/table для markdown, helper-и redaction, helper-и directive-tag і safe-text utilities |
| `plugin-sdk/text-chunking` | Helper chunking для outbound text |
| `plugin-sdk/speech` | Типи speech provider плюс provider-facing helper-и directive, registry і validation |
| `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive і helper-и normalization |
| `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription, helper-и registry і спільний helper WebSocket session |
| `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і helper-и registry |
| `plugin-sdk/image-generation` | Типи провайдерів image generation |
| `plugin-sdk/image-generation-core` | Спільні типи image-generation, helper-и failover, auth і registry |
| `plugin-sdk/music-generation` | Типи provider/request/result для music generation |
| `plugin-sdk/music-generation-core` | Спільні типи music-generation, helper-и failover, lookup провайдерів і парсинг model-ref |
| `plugin-sdk/video-generation` | Типи provider/request/result для video generation |
| `plugin-sdk/video-generation-core` | Спільні типи video-generation, helper-и failover, lookup провайдерів і парсинг model-ref |
| `plugin-sdk/webhook-targets` | Реєстр webhook target і helper-и встановлення route |
| `plugin-sdk/webhook-path` | Helper-и нормалізації webhook path |
| `plugin-sdk/web-media` | Спільні helper-и завантаження віддалених/локальних media |
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Subpath-и пам’яті">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/memory-core` | Вбудована helper-поверхня memory-core для helper-ів manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексації/пошуку пам’яті |
| `plugin-sdk/memory-core-host-engine-foundation` | Export-и foundation engine для memory host |
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding для memory host, доступ до registry, локальний provider і універсальні helper-и batch/remote |
| `plugin-sdk/memory-core-host-engine-qmd` | Export-и QMD engine для memory host |
| `plugin-sdk/memory-core-host-engine-storage` | Export-и storage engine для memory host |
| `plugin-sdk/memory-core-host-multimodal` | Multimodal helper-и для memory host |
| `plugin-sdk/memory-core-host-query` | Query helper-и для memory host |
| `plugin-sdk/memory-core-host-secret` | Secret helper-и для memory host |
| `plugin-sdk/memory-core-host-events` | Helper-и journal подій для memory host |
| `plugin-sdk/memory-core-host-status` | Helper-и status для memory host |
| `plugin-sdk/memory-core-host-runtime-cli` | Helper-и CLI runtime для memory host |
| `plugin-sdk/memory-core-host-runtime-core` | Базові helper-и runtime для memory host |
| `plugin-sdk/memory-core-host-runtime-files` | Helper-и file/runtime для memory host |
| `plugin-sdk/memory-host-core` | Vendor-neutral alias для базових helper-ів runtime memory host |
| `plugin-sdk/memory-host-events` | Vendor-neutral alias для helper-ів journal подій memory host |
| `plugin-sdk/memory-host-files` | Vendor-neutral alias для helper-ів file/runtime memory host |
| `plugin-sdk/memory-host-markdown` | Спільні helper-и managed-markdown для plugin-ів, суміжних із пам’яттю |
| `plugin-sdk/memory-host-search` | Active Memory runtime facade для доступу до search-manager |
| `plugin-sdk/memory-host-status` | Vendor-neutral alias для helper-ів status memory host |
| `plugin-sdk/memory-lancedb` | Вбудована helper-поверхня memory-lancedb |
</Accordion>
<Accordion title="Зарезервовані bundled-helper subpath-и">
| Family | Current subpaths | Intended use |
| --- | --- | --- |
| 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` | Helper-и підтримки bundled browser Plugin (`browser-support` залишається compatibility 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-поверхня bundled Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Helper/runtime-поверхня bundled LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Helper-поверхня bundled 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` | Compatibility/helper seam-и bundled channel |
| 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 seam-и bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
## API реєстрації
Callback `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
методами:
### Реєстрація можливостей
| Method | What it registers |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Текстове виведення (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий executor агента |
| `api.registerCliBackend(...)` | Локальний inference backend CLI |
| `api.registerChannel(...)` | Канал обміну повідомленнями |
| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis |
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime-транскрипція |
| `api.registerRealtimeVoiceProvider(...)` | Двосторонні realtime-голосові сесії |
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
| `api.registerWebSearchProvider(...)` | Web search |
| Метод | Що він реєструє |
| ------------------------------------------------ | -------------------------------------- |
| `api.registerProvider(...)` | Текстовий inference (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
| `api.registerCliBackend(...)` | Локальний backend inference для CLI |
| `api.registerChannel(...)` | Канал обміну повідомленнями |
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі |
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
| `api.registerWebFetchProvider(...)` | Provider для отримання / скрапінгу вебданих |
| `api.registerWebSearchProvider(...)` | Вебпошук |
### Інструменти та команди
| Method | What it registers |
| ------------------------------- | --------------------------------------------- |
| Метод | Що він реєструє |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
| `api.registerCommand(def)` | Користувацька команда (оминає LLM) |
### Інфраструктура
| Method | What it registers |
| ----------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Event hook |
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
| `api.registerService(service)` | Фоновий сервіс |
| `api.registerInteractiveHandler(registration)` | Interactive handler |
| `api.registerEmbeddedExtensionFactory(factory)` | Extension factory для embedded-runner Pi |
| `api.registerMemoryPromptSupplement(builder)` | Additive prompt section, суміжна з пам’яттю |
| `api.registerMemoryCorpusSupplement(adapter)` | Additive corpus для пошуку/читання пам’яті |
| Метод | Що він реєструє |
| ----------------------------------------------- | ---------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Хук події |
| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
| `api.registerService(service)` | Фоновий сервіс |
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
| `api.registerEmbeddedExtensionFactory(factory)` | Фабрика extension для вбудованого runner у Pi |
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю |
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
<Note>
Зарезервовані core admin namespace-и (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити
для методу Gateway вужчу scope. Для методів, якими володіє Plugin, віддавайте перевагу префіксам, специфічним для Plugin.
Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
вужчу область для методу Gateway. Для методів, що належать plugin, віддавайте перевагу префіксам, специфічним для plugin.
</Note>
<Accordion title="Коли використовувати registerEmbeddedExtensionFactory">
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли Plugin потребує Pi-native
часової семантики подій під час embedded-запусків OpenClaw — наприклад асинхронних переписувань `tool_result`, які мають відбутися до того, як буде надіслано фінальне повідомлення з результатом інструмента.
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin потребує Pi-native
синхронізації подій під час вбудованих запусків OpenClaw — наприклад, для асинхронних переписувань `tool_result`,
які мають відбутися до того, як буде надіслано фінальне повідомлення з результатом інструмента.
Наразі це seam для bundled Plugin: лише bundled Plugins можуть реєструвати його,
і вони мають оголошувати `contracts.embeddedExtensionFactories: ["pi"]` у
`openclaw.plugin.json`. Для всього, що не потребує цього нижчого рівня seam, залишайте звичайні hooks Plugin OpenClaw.
Сьогодні це seam для вбудованих plugins: лише вбудовані plugins можуть реєструвати такий,
і вони мають оголосити `contracts.embeddedExtensionFactories: ["pi"]` у
`openclaw.plugin.json`. Для всього, що не потребує цього низькорівневого seam, використовуйте звичайні хуки plugin OpenClaw.
</Accordion>
### Metadata реєстрації CLI
### Метадані реєстрації CLI
`api.registerCli(registrar, opts?)` приймає два види top-level metadata:
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
- `commands`: явні корені команд, якими володіє registrar
- `descriptors`: parse-time descriptor-и команд, які використовуються для root CLI help,
routing і lazy-реєстрації CLI Plugin
- `commands`: явні корені команд, що належать реєстратору
- `descriptors`: дескриптори команд на етапі розбору, що використовуються для довідки кореневого CLI,
маршрутизації та лінивої реєстрації CLI plugin
Якщо ви хочете, щоб команда Plugin залишалася lazy-loaded у звичайному root CLI path,
надайте `descriptors`, які покривають кожен top-level command root, відкритий цим
registrar.
Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в звичайному шляху кореневого CLI,
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, доступний через цей
реєстратор.
```typescript
api.registerCli(
@ -395,7 +146,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Manage Matrix accounts, verification, devices, and profile state",
description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю",
hasSubcommands: true,
},
],
@ -403,140 +154,139 @@ api.registerCli(
);
```
Використовуйте лише `commands`, коли вам не потрібна lazy-реєстрація в root CLI.
Цей eager-шлях сумісності все ще підтримується, але він не встановлює
placeholders на основі descriptor-ів для parse-time lazy loading.
Використовуйте лише `commands`, тільки якщо вам не потрібна лінива реєстрація кореневого CLI.
Цей eager-сумісний шлях залишається підтримуваним, але він не встановлює
плейсхолдери на основі descriptor для лінивого завантаження на етапі розбору.
### Реєстрація CLI backend
### Реєстрація backend для CLI
`api.registerCliBackend(...)` дозволяє Plugin володіти типовою конфігурацією для локального
`api.registerCliBackend(...)` дає змогу plugin володіти типовою конфігурацією для локального
backend AI CLI, такого як `codex-cli`.
- `id` backend-а стає префіксом provider у model ref на кшталт `codex-cli/gpt-5`.
- `config` backend-а використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
- Користувацька конфігурація все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
типових значень Plugin перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує суміснісних переписувань після merge
(наприклад нормалізації старих форм flags).
- `id` backend стає префіксом provider у посиланнях на моделі, як-от `codex-cli/gpt-5`.
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
типового значення plugin перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після об’єднання
(наприклад, нормалізації старих форм прапорців).
### Exclusive slots
### Ексклюзивні слоти
| Method | What it registers |
| Метод | Що він реєструє |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine (активним може бути лише один). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. |
| `api.registerMemoryCapability(capability)` | Уніфікована memory capability |
| `api.registerMemoryPromptSection(builder)` | Builder prompt section для пам’яті |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для пам’яті |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime для пам’яті |
| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг налаштовувати додавання до prompt. |
| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті |
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt для пам’яті |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті |
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
### Adapters embedding для пам’яті
### Адаптери embedding для пам’яті
| Method | What it registers |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding для пам’яті активного Plugin |
| Метод | Що він реєструє |
| ---------------------------------------------- | ----------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного plugin |
- `registerMemoryCapability` — це рекомендований exclusive API memory-plugin.
- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
щоб companion Plugins могли споживати експортовані memory artifacts через
`openclaw/plugin-sdk/memory-host-core` замість доступу до приватної розкладки конкретного
Plugin пам’яті.
- `registerMemoryCapability` — це пріоритетний API ексклюзивного plugin пам’яті.
- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
щоб супутні plugins могли споживати експортовані артефакти пам’яті через
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури
конкретного plugin пам’яті.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
`registerMemoryRuntime` — це сумісні з legacy exclusive API memory-plugin.
- `registerMemoryEmbeddingProvider` дозволяє активному Plugin пам’яті реєструвати один
або більше id embedding-adapter-ів (наприклад `openai`, `gemini` або custom
id, визначений Plugin).
- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і
`agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих
id adapter-ів.
`registerMemoryRuntime` — це legacy-сумісні API ексклюзивного plugin пам’яті.
- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті реєструвати один
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або кастомний id, визначений plugin).
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
`agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими
id адаптерів.
### Події та життєвий цикл
| Method | What it does |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook |
| `api.onConversationBindingResolved(handler)` | Callback прив’язки conversation |
| Метод | Що він робить |
| -------------------------------------------- | -------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови |
### Семантика рішень hook
### Семантика рішень хуків
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як override.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як override.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере на себе dispatch, handler-и нижчого пріоритету та типовий шлях model dispatch пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються.
- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як і пропуск `cancel`), а не як override.
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна inbound-маршрутизація thread/topic. `metadata` залишайте для channel-specific extra-даних.
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж використовувати fallback до channel-specific `metadata`.
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для startup-стану, яким володіє Gateway, замість покладання на внутрішні hooks `gateway:startup`.
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення.
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для extras, специфічних для channel.
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до `metadata`, специфічних для channel.
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні хуки `gateway:startup`.
### Поля об’єкта API
| Field | Type | Description |
| Поле | Тип | Опис |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | ID Plugin |
| `api.name` | `string` | Display name |
| `api.version` | `string?` | Версія Plugin (необов’язково) |
| `api.description` | `string?` | Опис Plugin (необов’язково) |
| `api.source` | `string` | Шлях до джерела Plugin |
| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) |
| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний runtime snapshot у пам’яті, коли доступний) |
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація Plugin з `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper-и runtime](/uk/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/setup до повного entry |
| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin |
| `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 |
## Угода щодо внутрішніх модулів
## Внутрішня угода щодо модулів
Усередині вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
```text
```
my-plugin/
api.ts # Public exports for external consumers
runtime-api.ts # Internal-only runtime exports
index.ts # Plugin entry point
setup-entry.ts # Lightweight setup-only entry (optional)
api.ts # Публічні експорти для зовнішніх споживачів
runtime-api.ts # Експорти runtime лише для внутрішнього використання
index.ts # Точка входу plugin
setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково)
```
<Warning>
Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/<your-plugin>`
з production-коду. Маршрутизуйте внутрішні імпорти через `./api.ts` або
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
</Warning>
Facade-loaded публічні поверхні bundled Plugin (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) віддають перевагу
активному runtime snapshot конфігурації, коли OpenClaw уже запущено. Якщо runtime
snapshot ще не існує, вони використовують fallback до розв’язаного файла конфігурації на диску.
Публічні поверхні вбудованих plugins, завантажувані через facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), надають перевагу
активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime
ще не існує, вони повертаються до визначеного файлу конфігурації на диску.
Plugins провайдерів можуть відкривати вузький plugin-local contract barrel, коли
helper навмисно є provider-specific і поки що не належить до універсального SDK
subpath. Приклади вбудованих:
Plugins provider можуть надавати вузький локальний для plugin barrel контракту, коли
певний допоміжний засіб навмисно є специфічним для provider і ще не належить до загального підшляху SDK.
Приклади вбудованих:
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude
beta-header і stream-helper-ів `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдера,
helper-и типових моделей і builder-и realtime provider.
- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера
плюс helper-и onboarding/config.
beta-header і допоміжних засобів потоку `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и provider,
допоміжні засоби для типових моделей і builder-и provider для realtime.
- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder provider
разом із допоміжними засобами для onboarding/конфігурації.
<Warning>
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
Якщо helper справді є спільним, підніміть його до нейтрального SDK subpath,
Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK,
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
capability-орієнтованої поверхні, замість того щоб жорстко зв’язувати два Plugins між собою.
поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins між собою.
</Warning>
## Пов’язане
## Пов’язані матеріали
<CardGroup cols={2}>
<Card title="Точки входу" icon="door-open" href="/uk/plugins/sdk-entrypoints">
Параметри `definePluginEntry` і `defineChannelPluginEntry`.
Опції `definePluginEntry` і `defineChannelPluginEntry`.
</Card>
<Card title="Helper-и runtime" icon="gears" href="/uk/plugins/sdk-runtime">
<Card title="Допоміжні засоби runtime" icon="gears" href="/uk/plugins/sdk-runtime">
Повний довідник простору імен `api.runtime`.
</Card>
<Card title="Setup і конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
<Card title="Налаштування та конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
Пакування, маніфести та схеми конфігурації.
</Card>
<Card title="Тестування" icon="vial" href="/uk/plugins/sdk-testing">
@ -545,7 +295,7 @@ subpath. Приклади вбудованих:
<Card title="Міграція SDK" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
Міграція із застарілих поверхонь.
</Card>
<Card title="Внутрішня будова Plugin" icon="diagram-project" href="/uk/plugins/architecture">
Глибока архітектура та модель можливостей.
<Card title="Внутрішня будова plugin" icon="diagram-project" href="/uk/plugins/architecture">
Поглиблена архітектура та модель можливостей.
</Card>
</CardGroup>

280
docs/uk/plugins/sdk-subpaths.md Normal file
View File

@ -0,0 +1,280 @@
---
read_when:
- Вибір правильного підшляху plugin-sdk для імпорту Plugin
- Аудит підшляхів bundled-plugin і допоміжних поверхонь
summary: 'Каталог підшляхів Plugin SDK: які імпорти де розташовані, згруповано за областями'
title: Підшляхи Plugin SDK
x-i18n:
generated_at: "2026-04-23T23:27:47Z"
model: gpt-5.4
provider: openai
source_hash: b0a1d4c2e2d4af147a21716e5240cb3be35ccde9f1d8dea3fc98ae87d3e6ca40
source_path: plugins/sdk-subpaths.md
workflow: 15
---
SDK Plugin доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`.
На цій сторінці наведено каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований
повний список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`;
зарезервовані допоміжні підшляхи bundled-plugin також наведено там, але вони є деталями
реалізації, якщо лише сторінка документації явно не просуває їх.
Посібник з розробки Plugin див. у [Огляд SDK Plugin](/uk/plugins/sdk-overview).
## Точка входу Plugin
| Підшлях | Ключові експорти |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Підшляхи каналів">
| Підшлях | Ключові експорти |
| --- | --- |
| `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-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` | Допоміжні засоби для багатокористувацької конфігурації/керування шлюзами дій, допоміжні засоби резервного вибору облікового запису за замовчуванням |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації 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 із резервним використанням bundled-contract |
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзування авторизації команд |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації чернеткового потоку |
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови envelope |
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей |
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей |
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа |
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності, делегування надсилання та планування payload |
| `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань |
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптера |
| `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа агента |
| `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairing і налаштованих прив’язок |
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації середовища виконання |
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики середовища виконання |
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу |
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу |
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу |
| `plugin-sdk/channel-plugin-common` | Спільні прелюдні експорти Plugin каналу |
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist |
| `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо групового доступу |
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM |
| `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів envelope |
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок без ширшої поверхні вхідного runtime |
| `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування каналу |
| `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкидання вхідних повідомлень і збоїв typing/ack |
| `plugin-sdk/channel-send-result` | Типи результату відповіді |
| `plugin-sdk/channel-actions` | Допоміжні засоби дій з повідомленнями каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin |
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей |
| `plugin-sdk/channel-contract` | Типи контракту каналу |
| `plugin-sdk/channel-feedback` | Підключення feedback/reaction |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретних контрактів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів |
</Accordion>
<Accordion title="Підшляхи провайдерів">
| Підшлях | Ключові експорти |
| --- | --- |
| `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 провайдерів |
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключів/запису профілів, такі як `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth auth |
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin провайдерів |
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища auth провайдера |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації id моделей, такі як `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера, зокрема допоміжні засоби multipart form для аудіотранскрипції |
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдера web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin |
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `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`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту нативного провайдера, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту, доступні для запису |
| `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу |
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
</Accordion>
<Accordion title="Підшляхи auth і безпеки">
| Підшлях | Ключові експорти |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника |
| `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення схвалювача та auth дій у межах того самого чату |
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного схвалення exec |
| `plugin-sdk/approval-delivery-runtime` | Адаптери нативної можливості/доставки схвалення |
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway схвалення |
| `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження адаптера нативного схвалення для гарячих точок входу каналу |
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника схвалення; віддавайте перевагу вужчим швам adapter/gateway, якщо їх достатньо |
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби нативної цілі схвалення та прив’язки облікового запису |
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для схвалення exec/plugin |
| `plugin-sdk/command-auth-native` | Нативний auth команд і допоміжні засоби нативної цілі сесії |
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команди |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретних контрактів для поверхонь секретів каналу/plugin |
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config |
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту та збирання секретів |
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж |
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime |
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF |
| `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів |
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook |
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів |
</Accordion>
<Accordion title="Підшляхи runtime і сховища">
| Підшлях | Ключові експорти |
| --- | --- |
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/журналювання/резервного копіювання/встановлення plugin |
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff |
| `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-контексту каналу |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hooks/http/interactive для plugin |
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра webhook/внутрішніх hook |
| `plugin-sdk/lazy-runtime` | Допоміжні засоби ледачого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів |
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій |
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і патчів стану каналу |
| `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації та пошуку конфігурації plugin |
| `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled Telegram contract недоступна |
| `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/plugin, конструктори можливостей схвалення, допоміжні засоби auth/профілів, нативної маршрутизації/runtime |
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей |
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей |
| `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window історії відповідей, такі як `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/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків |
| `plugin-sdk/request-url` | Витягування рядкових URL із входів типу fetch/request |
| `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr |
| `plugin-sdk/param-readers` | Типові читачі параметрів tool/CLI |
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool |
| `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 |
| `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного блокування файлів |
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковим зберіганням |
| `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і dispatch відповідей |
| `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу |
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента |
| `plugin-sdk/boolean-param` | Читач слабко типізованих булевих параметрів |
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв |
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing |
| `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy |
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби команд `/models` і відповідей провайдера |
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills |
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд |
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw і утиліти результатів спроб |
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
| `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/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Читач обмеженого тіла відповіді без широкої поверхні media runtime |
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing |
| `plugin-sdk/session-store-runtime` | Допоміжні засоби читання сховища сесій без широких імпортів запису/обслуговування конфігурації |
| `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних записів/рядків без імпортів markdown/logging |
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host |
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry |
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента |
| `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Підшляхи можливостей і тестування">
| Підшлях | Ключові експорти |
| --- | --- |
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори payload медіа |
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель |
| `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо |
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення видимого для помічника тексту, допоміжні засоби рендерингу/chunking/таблиць markdown, редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту |
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту |
| `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів допоміжні засоби директив, реєстру й валідації |
| `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації |
| `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби реєстру й спільний допоміжний засіб WebSocket-сесії |
| `plugin-sdk/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/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів |
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook |
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів SDK Plugin |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Підшляхи Memory">
| Підшлях | Ключові експорти |
| --- | --- |
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled `memory-core` для менеджера/конфігурації/файлів/допоміжних засобів CLI |
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку Memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний провайдер і загальні допоміжні засоби batch/remote |
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory |
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory |
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста Memory |
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста Memory |
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста Memory |
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста Memory |
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста Memory |
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста Memory |
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста Memory |
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста Memory |
| `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста Memory |
| `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста Memory |
| `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста Memory |
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugin, суміжних із memory |
| `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager |
| `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста Memory |
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled `memory-lancedb` |
</Accordion>
<Accordion title="Зарезервовані підшляхи bundled-helper">
| Сімейство | Поточні підшляхи | Призначення |
| --- | --- | --- |
| 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` | Допоміжні засоби підтримки bundled 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` | Поверхня допоміжних засобів/runtime bundled Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled 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` | Шви сумісності/допоміжних засобів bundled каналів |
| Допоміжні засоби для 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` | Шви допоміжних засобів bundled функцій/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## Пов’язане
- [Огляд SDK Plugin](/uk/plugins/sdk-overview)
- [Налаштування SDK Plugin](/uk/plugins/sdk-setup)
- [Створення plugin](/uk/plugins/building-plugins)

94
docs/uk/reference/test.md
View File

@ -1,51 +1,51 @@
---
read_when:
- Запуск або виправлення тестів
summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage
summary: Як запускати тести локально (`vitest`) і коли використовувати режими force/coverage
title: Тести
x-i18n:
generated_at: "2026-04-23T21:58:41Z"
generated_at: "2026-04-23T23:27:46Z"
model: gpt-5.4
provider: openai
source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54
source_hash: 1224c2c0fc4b96a6631ba238e4e9b13ed61e918282db393df7a9db93b3fbf8cf
source_path: reference/test.md
workflow: 15
---
- Повний набір для тестування (сьюти, live, Docker): [Тестування](/uk/help/testing)
- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує порт керування за замовчуванням, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789.
- `pnpm test:coverage`: запускає набір unit-тестів з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття unit-тестів для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення: 70% для рядків/функцій/інструкцій і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit-тестів з покриттям, замість того щоб вважати всі файли вихідного коду з розбитих lane непокритими.
- `pnpm test:coverage:changed`: запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`.
- `pnpm test:changed`: розгортає змінені шляхи git у scoped lane Vitest, коли diff торкається лише routable файлів джерела/тестів. Зміни конфігурації/налаштування, як і раніше, повертаються до нативного запуску root projects, щоб за потреби правки wiring запускали ширший прогін.
- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`.
- `pnpm check:changed`: запускає розумну перевірку changed gate для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lane, роботу над розширеннями — з extension test lane, роботу лише над тестами — лише з typecheck/tests для тестів, розгортає зміни публічного Plugin SDK або plugin-contract до перевірки розширень і залишає version bump лише в release metadata на цільових перевірках version/config/root-dependency.
- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілі використовують фіксовані shard-групи та розгортаються в leaf configs для локального паралельного виконання; група розширень завжди розгортається в shard-конфіги для кожного extension/plugin, а не в один великий процес root-project.
- Повні запуски та запуски shard розширень оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane, які залишають тільки `test/setup.ts`, а ресурсомісткі runtime-кейси лишаються на своїх наявних lane.
- Вибрані файли вихідного коду helper у `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane, щоб невеликі правки helper не перезапускали важкі сьюти, що залежать від runtime.
- `auto-reply` тепер також поділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper.
- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний non-isolated runner увімкнено в усіх конфігураціях репозиторію.
- `pnpm test:force`: завершує будь-який завислий процес Gateway, який утримує типовий порт керування, а потім запускає повну сьюту Vitest з ізольованим портом Gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск Gateway залишив зайнятим порт 18789.
- `pnpm test:coverage`: запускає unit-сьюту з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка unit-покриття для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені unit-сьютою покриття, замість того щоб вважати кожен файл вихідного коду з розділених lane-ів непокритим.
- `pnpm test:coverage:changed`: запускає unit-покриття лише для файлів, змінених відносно `origin/main`.
- `pnpm test:changed`: розгортає змінені git-шляхи у scoped lane-и Vitest, коли diff торкається лише routable-файлів коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску root-проєктів, щоб за потреби зміни wiring перевиконувалися ширше.
- `pnpm changed:lanes`: показує архітектурні lane-и, запущені diff-ом відносно `origin/main`.
- `pnpm check:changed`: запускає розумну перевірку зміненого diff-а відносно `origin/main`. Вона запускає core-роботу разом із core test lane-ами, роботу extension — разом із extension test lane-ами, test-only зміни — лише з test typecheck/tests, розширює зміни в публічному Plugin SDK або plugin-contract до одного проходу перевірки extension, а для version bump-ів лише в release metadata зберігає цільові перевірки version/config/root-dependency.
- `pnpm test`: спрямовує явні цілі файлів/директорій через scoped lane-и Vitest. Запуски без цілі використовують фіксовані групи shard-ів і розгортаються до leaf-конфігів для локального паралельного виконання; група extension завжди розгортається до shard-конфігів для кожного extension окремо, а не до одного великого root-project процесу.
- Повні запуски та запуски shard-ів extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard-ів. Встановіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через спеціальні легкі lane-и, які зберігають лише `test/setup.ts`, залишаючи runtime-важкі кейси на їхніх наявних lane-ах.
- Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane-ах, щоб невеликі зміни helper-ів не перезапускали важкі сьюти, які залежать від runtime.
- `auto-reply` тепер також поділяється на три спеціальні конфіги (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper.
- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в конфігах усього репозиторію.
- `pnpm test:channels` запускає `vitest.channels.config.ts`.
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugin, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin лишаються згрупованими. Використовуйте `pnpm test extensions/<id>` для одного lane bundled plugin.
- `pnpm test:perf:imports`: вмикає звітність Vitest щодо тривалості імпорту та деталізації імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів.
- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` виконує benchmark маршрутизованого changed-режиму проти нативного запуску root-project для того самого закоміченого git diff.
- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту.
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard-и; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/<id>` для одного lane-а bundled plugin.
- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та import-breakdown, водночас і далі використовуючи scoped lane routing для явних цілей файлів/директорій.
- `pnpm test:perf:imports:changed`: той самий профайлінг імпорту, але лише для файлів, змінених відносно `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` бенчмаркує routed changed-mode шлях проти нативного запуску root-project для того самого зафіксованого git diff-а.
- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточний набір змін у worktree без попереднього коміту.
- `pnpm test:perf:profile:main`: записує CPU-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest повного набору та записує дані про тривалість за групами, а також JSON/лог-артефакти для кожної конфігурації. Агент Test Performance використовує це як базову лінію перед спробою виправити повільні тести.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність.
- Інтеграція Gateway: увімкнення за бажанням через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (multi-instance WS/HTTP/node pairing). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю worker у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=<n>`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`.
- `pnpm test:live`: запускає live-тести provider (minimax/zai). Потрібні API-ключі та `LIVE=1` (або provider-специфічний `*_LIVE_TEST=1`) для зняття `skip`.
- `pnpm test:docker:all`: один раз збирає спільний образ для live-тестів і Docker E2E image, а потім запускає Docker smoke lane з `OPENCLAW_SKIP_DOCKER_BUILD=1` і типовим паралелізмом 4. Налаштовується через `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а для кожного lane діє тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до старту або provider, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests/<run-id>/`.
- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксований чат через `/api/chat/completions`. Потрібен робочий live model key (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і цей сценарій не очікується стабільним у CI так, як звичайні unit/e2e сьюти.
- `pnpm test:docker:mcp-channels`: запускає seeded-контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-фрейми напряму, щоб smoke-тест відображав те, що міст фактично надсилає.
- `pnpm test:perf:profile:runner`: записує CPU- і heap-профілі для unit runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf-конфіг Vitest із повної suite і записує згруповані дані тривалості разом із JSON/log-артефактами для кожного конфіга. Агент продуктивності тестів використовує це як базову точку перед спробою виправити повільні тести.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після зміни, зосередженої на продуктивності.
- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
- `pnpm test:e2e`: запускає наскрізні smoke-тести Gateway (multi-instance WS/HTTP/node pairing). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=<n>` і встановіть `OPENCLAW_E2E_VERBOSE=1` для докладних логів.
- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потребує API-ключів і `LIVE=1` (або провайдер-специфічного `*_LIVE_TEST=1`) для зняття пропуску.
- `pnpm test:docker:all`: один раз збирає спільний образ live-тестів і Docker E2E-образ, а потім запускає Docker smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1` із concurrency 4 за замовчуванням. Налаштовуйте через `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. Runner припиняє планувати нові pooled lane-и після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Чутливі до запуску або провайдера lane-и запускаються ексклюзивно після паралельного пулу. Логи для кожного lane-а записуються в `.artifacts/docker-tests/<run-id>/`.
- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не розрахований на CI-стабільність, як звичайні unit/e2e-сьюти.
- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із попереднім наповненням і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення routed conversations, читання transcript-ів, metadata вкладень, поведінку черги live-подій, outbound send routing і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-кадри безпосередньо, щоб smoke відображав те, що міст реально надсилає.
## Локальна PR-перевірка
Для локальних перевірок перед злиттям PR запускайте:
Для локальних перевірок перед злиттям/гейтом PR запустіть:
- `pnpm check:changed`
- `pnpm check`
@ -54,12 +54,12 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
Якщо `pnpm test` нестабільно працює на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте проблему через `pnpm test <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
Якщо `pnpm test` флейкиться на навантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test <path/to/test>`. Для хостів з обмеженнями пам’яті використовуйте:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Benchmark затримки моделі (локальні ключі)
## Бенч затримки моделі (локальні ключі)
Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
@ -67,14 +67,14 @@ x-i18n:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.”
- Типовий prompt: “Відповідай одним словом: ok. Без пунктуації або додаткового тексту.”
Останній запуск (2025-12-31, 20 прогонів):
Останній запуск (2025-12-31, 20 запусків):
- minimax median 1279ms (min 1114, max 2431)
- opus median 2454ms (min 1224, max 3170)
## Benchmark запуску CLI
## Бенч запуску CLI
Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -95,41 +95,41 @@ x-i18n:
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
- `pnpm tsx scripts/bench-cli-startup.ts --json`
Preset:
Пресети:
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: обидва preset
- `all`: обидва пресети
Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного прогону, тож вимірювання часу та захоплення профілю використовують той самий harness.
Вивід включає `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, щоб вимірювання часу й захоплення профілів використовували один і той самий harness.
Умовні позначення для збереженого виводу:
- `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1`
- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1`
- `pnpm test:startup:bench:save` записує артефакт повної suite у `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1`
- `pnpm test:startup:bench:update` оновлює зафіксований у репозиторії baseline-фікстур у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1`
Закомічений fixture:
Фікстур, зафіксований у репозиторії:
- `test/fixtures/cli-startup-bench.json`
- Оновлення: `pnpm test:startup:bench:update`
- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check`
- Оновіть через `pnpm test:startup:bench:update`
- Порівняйте поточні результати з фікстуром через `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів.
Docker необов’язковий; це потрібно лише для контейнеризованих smoke-тестів onboarding.
Повний cold-start сценарій у чистому Linux-контейнері:
Повний cold-start потік у чистому Linux-контейнері:
```bash
scripts/e2e/onboard-docker.sh
```
Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`.
Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає Gateway і виконує `openclaw health`.
## Smoke-тест імпорту QR (Docker)
Переконується, що підтримуваний QR runtime helper завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22):
Гарантує, що підтримуваний helper QR runtime завантажується у підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22):
```bash
pnpm test:docker:qr

274
docs/uk/tools/exec-approvals-advanced.md Normal file
View File

@ -0,0 +1,274 @@
---
read_when:
- Налаштування безпечних бінарних файлів або користувацьких профілів safe-bin
- Переспрямування схвалень до Slack/Discord/Telegram або інших чат-каналів
- Реалізація нативного клієнта схвалення для каналу
summary: 'Розширені дозволи на виконання: безпечні бінарні файли, прив’язка інтерпретатора, переспрямування схвалення, нативна доставка'
title: Дозволи на виконання — розширені
x-i18n:
generated_at: "2026-04-23T23:27:49Z"
model: gpt-5.4
provider: openai
source_hash: 8a24a3539126b0f0fd11696c31efc8a6a9a4262fe4cd89bf456ff92a4f05c36c
source_path: tools/exec-approvals-advanced.md
workflow: 15
---
Розширені теми дозволів на виконання: швидкий шлях `safeBins`, прив’язка
інтерпретатора/середовища виконання та переспрямування схвалень до чат-каналів
(включно з нативною доставкою). Базову політику та потік схвалення див. у [Дозволи на виконання](/uk/tools/exec-approvals).
## Безпечні бінарні файли (лише stdin)
`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів у allowlist. Безпечні бінарні файли відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри.
<Warning>
**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`,
`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код,
виконувати підкоманди або читати файли, надавайте перевагу явним записам у allowlist
і залишайте підказки схвалення ввімкненими. Користувацькі безпечні бінарні файли мають визначати явний
профіль у `tools.exec.safeBinProfiles.<bin>`.
</Warning>
Типові безпечні бінарні файли:
[//]: # "SAFE_BIN_DEFAULTS:START"
`cut`, `uniq`, `head`, `tail`, `tr`, `wc`
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні
записи allowlist для їхніх сценаріїв не через stdin. Для `grep` у режимі safe-bin
передавайте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється,
щоб файлові операнди не можна було приховано передати як неоднозначні позиційні аргументи.
### Перевірка argv і заборонені прапорці
Перевірка є детермінованою лише за формою argv (без перевірок існування у файловій системі хоста),
що запобігає поведінці оракула існування файлів через відмінності allow/deny.
Опції, орієнтовані на файли, заборонені для типових safe-bin; довгі
опції перевіряються за принципом fail-closed (невідомі прапорці та неоднозначні скорочення
відхиляються).
Заборонені прапорці за профілем safe-bin:
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
- `wc`: `--files0-from`
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
Безпечні бінарні файли також примусово обробляють токени argv як **буквальний текст** під час виконання
(без глобінгу та без розгортання `$VARS`) для сегментів лише зі stdin, тож шаблони
на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів.
### Довірені каталоги бінарних файлів
Безпечні бінарні файли мають визначатися з довірених каталогів бінарних файлів (системні типові каталоги плюс
необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються автоматично довіреними.
Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо ваш safe-bin виконуваний файл
розташовано в шляхах менеджера пакетів або користувача (наприклад
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх
явно до `tools.exec.safeBinTrustedDirs`.
### Ланцюжки shell-команд, обгортки та мультиплексори
Ланцюжки shell-команд (`&&`, `||`, `;`) дозволені, якщо кожен сегмент верхнього рівня
відповідає allowlist (включно з safe-bin або авто-дозволом Skills). Перенаправлення
у режимі allowlist, як і раніше, не підтримуються. Підстановка команд (`$()` / зворотні лапки) відхиляється
під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`.
У схваленнях companion app на macOS сирий shell-текст, що містить синтаксис керування оболонкою або розгортання
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом allowlist, якщо сам бінарний файл shell не входить до allowlist.
Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env на рівні запиту
зводяться до невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`,
`NO_COLOR`, `FORCE_COLOR`).
Для рішень `allow-always` у режимі allowlist відомі обгортки диспетчеризації (`env`,
`nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях до внутрішнього виконуваного файла,
а не шлях до обгортки. Shell-мультиплексори (`busybox`, `toybox`) розгортаються для
аплетів shell (`sh`, `ash` тощо) так само. Якщо обгортку або мультиплексор
не можна безпечно розгорнути, жоден запис allowlist автоматично не зберігається.
Якщо ви додаєте до allowlist такі інтерпретатори, як `python3` або `node`, надавайте перевагу
`tools.exec.strictInlineEval=true`, щоб inline eval і надалі вимагав явного
схвалення. У strict mode `allow-always` усе ще може зберігати нешкідливі
виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються.
### Safe bins проти allowlist
| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| Мета | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів |
| Тип відповідності | Ім’я виконуваного файла + політика argv safe-bin | Глоб-шаблон шляху до визначеного виконуваного файла |
| Область аргументів | Обмежена профілем 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>` як `{}` (після цього перегляньте й посильте їх). Для бінарних файлів інтерпретаторів/середовищ виконання автогенерація не виконується.
Приклад користувацького профілю:
__OC_I18N_900000__
Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin,
тому `jq -n env` не зможе вивантажити середовище процесу хоста без явного шляху в allowlist
або підказки схвалення.
## Команди інтерпретатора/середовища виконання
Запуски інтерпретатора/середовища виконання, підкріплені схваленням, навмисно є консервативними:
- Точний контекст argv/cwd/env завжди прив’язується.
- Прямі форми shell-скриптів і прямі форми файлів середовища виконання прив’язуються за можливості до одного конкретного локального знімка файла.
- Поширені форми обгорток менеджерів пакетів, які все ще визначаються в один прямий локальний файл (наприклад
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою.
- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання
(наприклад скрипти пакетів, форми eval, специфічні для середовища виконання ланцюжки завантажувачів або неоднозначні багатофайлові
форми), виконання, підкріплене схваленням, відхиляється замість того, щоб заявляти семантичне покриття,
якого насправді немає.
- Для таких сценаріїв надавайте перевагу sandboxing, окремій межі хоста або явному
довіреному allowlist/повному workflow, де оператор приймає ширшу семантику середовища виконання.
Коли потрібні схвалення, інструмент exec одразу повертає ідентифікатор схвалення. Використовуйте цей id, щоб
співвіднести подальші системні події (`Exec finished` / `Exec denied`). Якщо рішення не надходить до завершення
тайм-ауту, запит вважається тайм-аутом схвалення і відображається як причина відмови.
### Поведінка доставки followup
Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` до тієї самої сесії.
- Якщо існує дійсна зовнішня ціль доставки (канал, придатний до доставки, плюс цільовий `to`), followup-доставка використовує цей канал.
- У потоках лише webchat або internal-session без зовнішньої цілі followup-доставка залишається лише в межах сесії (`deliver: false`).
- Якщо викликач явно вимагає сувору зовнішню доставку, але жоден зовнішній канал не можна визначити, запит завершується помилкою `INVALID_REQUEST`.
- Якщо увімкнено `bestEffortDeliver` і жоден зовнішній канал не можна визначити, доставку буде знижено до лише сесійної замість помилки.
## Переспрямування схвалень до чат-каналів
Ви можете переспрямовувати підказки схвалення exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати
їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки.
Конфігурація:
__OC_I18N_900001__
Відповідь у чаті:
__OC_I18N_900002__
Команда `/approve` обробляє і exec-схвалення, і схвалення Plugin. Якщо ID не відповідає очікуваному exec-схваленню, вона автоматично перевіряє схвалення Plugin.
### Переспрямування схвалень Plugin
Переспрямування схвалень Plugin використовує той самий конвеєр доставки, що й exec-схвалення, але має власну
незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше.
__OC_I18N_900003__
Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`,
`sessionFilter` і `targets` працюють однаково.
Канали, що підтримують спільні інтерактивні відповіді, відображають ті самі кнопки схвалення як для exec, так і для схвалень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`.
### Схвалення в тому самому чаті на будь-якому каналі
Коли запит на exec або схвалення Plugin походить із чат-поверхні, придатної до доставки, цей самий чат
тепер за замовчуванням може схвалити його через `/approve`. Це стосується таких каналів, як Slack, Matrix і
Microsoft Teams, на додачу до вже наявних потоків Web UI і terminal UI.
Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо
чат-джерело вже може надсилати команди й отримувати відповіді, для запитів на схвалення більше не потрібен
окремий адаптер нативної доставки лише для того, щоб залишатися в очікуванні.
Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все ще використовують свій
визначений список approver для авторизації, навіть коли нативну доставку схвалень вимкнено.
Для Telegram та інших нативних клієнтів схвалення, які напряму викликають Gateway,
цей fallback навмисно обмежено збоями типу «схвалення не знайдено». Справжня
відмова/помилка exec-схвалення не повторюється мовчки як схвалення Plugin.
### Нативна доставка схвалень
Деякі канали також можуть працювати як нативні клієнти схвалень. Нативні клієнти додають approver DM, fanout чату-джерела
та специфічний для каналу інтерактивний UX схвалення поверх спільного потоку `/approve` у тому самому чаті.
Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним
шляхом для агента. Агент також не повинен дублювати звичайну чат-команду
`/approve`, якщо тільки результат інструмента не вказує, що чат-схвалення недоступні або
ручне схвалення є єдиним шляхом, що залишився.
Загальна модель:
- політика host exec, як і раніше, визначає, чи потрібне exec-схвалення
- `approvals.exec` керує переспрямуванням підказок схвалення до інших чат-цілей
- `channels.<channel>.execApprovals` керує тим, чи працює цей канал як нативний клієнт схвалень
Нативні клієнти схвалень автоматично вмикають доставку спочатку в DM, коли виконуються всі ці умови:
- канал підтримує нативну доставку схвалень
- approver можна визначити з явних `execApprovals.approvers` або з
документованих fallback-джерел цього каналу
- `channels.<channel>.execApprovals.enabled` не задано або має значення `"auto"`
Установіть `enabled: false`, щоб явно вимкнути нативний клієнт схвалень. Установіть `enabled: true`, щоб примусово
увімкнути його, коли approver визначаються. Публічна доставка до чату-джерела й надалі явно задається через
`channels.<channel>.execApprovals.target`.
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` у тому самому чаті та спільних кнопок схвалення.
Спільна поведінка:
- Slack, Matrix, Microsoft Teams та подібні чати з можливістю доставки використовують звичайну модель автентифікації каналу
для `/approve` у тому самому чаті
- коли нативний клієнт схвалень вмикається автоматично, типовою нативною ціллю доставки є DM для approver
- для Discord і Telegram лише визначені approver можуть схвалювати або відхиляти
- approver у Discord можуть бути явними (`execApprovals.approvers`) або визначатися з `commands.ownerAllowFrom`
- approver у Telegram можуть бути явними (`execApprovals.approvers`) або визначатися з наявної конфігурації owner (`allowFrom`, а також `defaultTo` для direct-message, де це підтримується)
- approver у Slack можуть бути явними (`execApprovals.approvers`) або визначатися з `commands.ownerAllowFrom`
- нативні кнопки Slack зберігають тип id схвалення, тож id `plugin:` можуть визначати схвалення Plugin
без другого локального fallback-рівня Slack
- нативна DM/канальна маршрутизація Matrix і скорочення через реакції обробляють і exec-схвалення, і схвалення Plugin;
авторизація Plugin і надалі походить з `channels.matrix.dm.allowFrom`
- запитувач не зобов’язаний бути approver
- чат-джерело може схвалити запит напряму через `/approve`, якщо цей чат уже підтримує команди та відповіді
- нативні кнопки схвалення Discord маршрутизують за типом id схвалення: id `plugin:` одразу
спрямовуються до схвалень Plugin, усе інше — до exec-схвалень
- нативні кнопки схвалення Telegram використовують той самий обмежений exec-to-plugin fallback, що й `/approve`
- коли нативний `target` вмикає доставку до чату-джерела, підказки схвалення містять текст команди
- exec-схвалення в очікуванні за замовчуванням спливають через 30 хвилин
- якщо жоден UI оператора або налаштований клієнт схвалень не може прийняти запит, підказка повертається до `askFallback`
Telegram за замовчуванням використовує DM для approver (`target: "dm"`). Ви можете переключити на `channel` або `both`, якщо
хочете, щоб підказки схвалення також з’являлися в чаті/темі Telegram, звідки надійшов запит. Для тем форуму Telegram
OpenClaw зберігає тему для підказки схвалення та follow-up після схвалення.
Див. також:
- [Discord](/channels/discord)
- [Telegram](/channels/telegram)
### Потік macOS IPC
__OC_I18N_900004__
Примітки щодо безпеки:
- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`.
- Перевірка peer з тим самим UID.
- Challenge/response (nonce + HMAC token + request hash) + короткий TTL.
## Пов’язане
- [Дозволи на виконання](/uk/tools/exec-approvals) — базова політика та потік схвалення
- [Інструмент exec](/uk/tools/exec)
- [Підвищений режим](/uk/tools/elevated)
- [Skills](/uk/tools/skills) — поведінка автодозволу на основі Skills

486
docs/uk/tools/exec-approvals.md
View File

@ -1,65 +1,67 @@
---
read_when:
- Налаштування підтверджень виконання або списків дозволених елементів
- Реалізація UX для підтвердження виконання в застосунку macOS
- Перегляд запитів на вихід із пісочниці та їхніх наслідків
summary: Підтвердження виконання, списки дозволених елементів і запити на вихід із пісочниці
title: Підтвердження виконання
- Налаштування затверджень виконання або списків дозволеного
- Реалізація UX затвердження виконання у застосунку macOS
- Перевірка підказок щодо виходу з пісочниці та їхніх наслідків
summary: Підказки щодо затвердження виконання, списків дозволеного та виходу з пісочниці
title: Затвердження виконання
x-i18n:
generated_at: "2026-04-23T22:14:40Z"
generated_at: "2026-04-23T23:27:47Z"
model: gpt-5.4
provider: openai
source_hash: a4090e0726d9cee3372a11e6bf8f7899546e68f4fabea42dcb55b87593e9315c
source_hash: 0d7c5cd24e7c1831d5a865da6fa20f4c23280a0ec12b9e8f7f3245170a05a37d
source_path: tools/exec-approvals.md
workflow: 15
---
Підтвердження виконання — це **захисний механізм companion app / хоста Node** для надання змоги агенту в пісочниці виконувати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли політика + список дозволених елементів + (необов’язкове) підтвердження користувача збігаються. Підтвердження виконання накладаються **поверх** політики інструментів і підвищеного рівня доступу (окрім випадку, коли elevated встановлено в `full`, що пропускає підтвердження).
Затвердження виконання — це **запобіжник застосунку-компаньйона / хоста Node**, який дає змогу агенту в пісочниці запускати команди на реальному хості (`gateway` або `node`). Це запобіжне блокування: команди дозволяються лише тоді, коли політика + список дозволеного + (необов’язкове) затвердження користувачем усі це підтверджують. Затвердження виконання накладаються **поверх** політики інструментів і підвищеного шлюзу (окрім випадку, коли elevated встановлено в `full`, що пропускає затвердження).
<Note>
Ефективна політика є **суворішою** з `tools.exec.*` і значень за замовчуванням для підтверджень; якщо поле підтверджень пропущено, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан підтверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжуватиме запитувати підтвердження, навіть якщо параметри сеансу або конфігурації вимагають `ask: "on-miss"`.
Ефективна політика — **суворіша** з `tools.exec.*` та типових значень затверджень; якщо поле затверджень пропущено, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан затверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує показувати запит навіть тоді, коли типові значення сеансу або конфігурації вимагають `ask: "on-miss"`.
</Note>
## Перевірка ефективної політики
- `openclaw approvals get`, `... --gateway`, `... --node <id|name|ip>` — показують запитану політику, джерела політики хоста та ефективний результат.
- `openclaw approvals get`, `... --gateway`, `... --node <id|name|ip>` — показує запитану політику, джерела політики хоста та ефективний результат.
- `openclaw exec-policy show` — об’єднане подання для локальної машини.
- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом підтверджень хоста за один крок.
- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом затверджень хоста за один крок.
Коли локальна область запитує `host=node`, `exec-policy show` повідомляє про цю область як керовану вузлом під час виконання, а не вдає, що локальний файл підтверджень є джерелом істини.
Коли локальна область запитує `host=node`, `exec-policy show` повідомляє про цю область як про керовану Node під час виконання, замість того щоб удавати, ніби локальний файл затверджень є джерелом істини.
Якщо UI companion app **недоступний**, будь-який запит, який зазвичай потребував би підтвердження, обробляється через **резервний режим ask** (типово: deny).
Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, який зазвичай викликав би запит на підтвердження, обробляється через **резервну поведінку ask** (типово: deny).
<Tip>
Нативні клієнти підтвердження в чаті можуть додавати специфічні для каналу зручні елементи до повідомлення про очікуване підтвердження. Наприклад, Matrix додає швидкі реакції (`✅`
дозволити один раз, `❌` відхилити, `♾️` дозволити завжди), водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант.
Нативні клієнти затвердження в чаті можуть додавати специфічні для каналу елементи керування до повідомлення з очікуванням затвердження. Наприклад, Matrix додає швидкі реакції (`✅` дозволити один раз, `❌` заборонити, `♾️` дозволити завжди), водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант.
</Tip>
## Де це застосовується
Підтвердження виконання застосовуються локально на хості виконання:
Затвердження виконання застосовуються локально на хості виконання:
- **gateway host** → процес `openclaw` на машині Gateway
- **node host** → виконавець вузла (companion app macOS або headless-хост вузла)
- **node host** → виконавець Node (застосунок-компаньйон macOS або headless-хост Node)
Примітка щодо моделі довіри:
- Виклики, автентифіковані через Gateway, є довіреними операторами для цього Gateway.
- Спарені вузли поширюють цю можливість довіреного оператора на хост вузла.
- Підтвердження виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні окремого користувача.
- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, якщо застосовно.
- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту.
- Ця прив’язка файлів навмисно є best-effort, а не повною семантичною моделлю для кожного шляху завантаження інтерпретатора/середовища виконання.
- Якщо режим підтвердження не може однозначно визначити рівно один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підтриманий підтвердженням, замість того щоб удавати повне покриття.
- Спарені Node розширюють цю можливість довіреного оператора на хост Node.
- Затвердження виконання знижують ризик випадкового виконання, але не є межею автентифікації на рівні користувача.
- Затверджені запуски на хості Node прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, якщо застосовно.
- Для shell-скриптів і прямих викликів файла інтерпретатора/середовища виконання OpenClaw також намагається прив’язати
один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після затвердження, але до виконання,
запуск забороняється замість виконання зміненого вмісту.
- Ця файлова прив’язка навмисно є best-effort, а не повною семантичною моделлю для кожного
шляху завантаження інтерпретатора/середовища виконання. Якщо режим затвердження не може визначити рівно один конкретний локальний
файл для прив’язки, він відмовляється створювати запуск, підкріплений затвердженням, замість того щоб удавати повне покриття.
Розділення в macOS:
Розподіл у macOS:
- **служба node host** пересилає `system.run` до **застосунку macOS** через локальний IPC.
- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI.
- **служба хоста Node** пересилає `system.run` до **застосунку macOS** через локальний IPC.
- **застосунок macOS** застосовує затвердження + виконує команду в контексті UI.
## Налаштування та зберігання
Підтвердження зберігаються в локальному JSON-файлі на хості виконання:
Затвердження зберігаються в локальному JSON-файлі на хості виконання:
`~/.openclaw/exec-approvals.json`
@ -98,35 +100,35 @@ x-i18n:
}
```
## Режим "YOLO" без підтверджень
## Режим "YOLO" без затвердження
Якщо ви хочете, щоб виконання на хості відбувалося без запитів на підтвердження, потрібно відкрити **обидва** рівні політики:
Якщо ви хочете, щоб виконання на хості працювало без запитів на затвердження, потрібно відкрити **обидва** рівні політики:
- запитана політика виконання в конфігурації OpenClaw (`tools.exec.*`)
- локальна для хоста політика підтверджень у `~/.openclaw/exec-approvals.json`
- запитувана політика виконання в конфігурації OpenClaw (`tools.exec.*`)
- локальна для хоста політика затверджень у `~/.openclaw/exec-approvals.json`
Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою:
- `tools.exec.security`: `full` на `gateway`/`node`
- `tools.exec.ask`: `off`
- хост `askFallback`: `full`
- host `askFallback`: `full`
Важливе розрізнення:
Важлива відмінність:
- `tools.exec.host=auto` визначає, де виконується exec: у пісочниці, якщо вона доступна, інакше на gateway.
- YOLO визначає, як схвалюється виконання на хості: `security=full` плюс `ask=off`.
- Провайдери на базі CLI, які надають власний неінтерактивний режим дозволів, можуть дотримуватися цієї політики.
Claude CLI додає `--permission-mode bypassPermissions`, коли запитана політика виконання OpenClaw — це
YOLO. Ви можете перевизначити цю поведінку бекенда явними аргументами Claude у
- YOLO визначає, як затверджується виконання на хості: `security=full` плюс `ask=off`.
- Провайдери на основі CLI, які мають власний неінтерактивний режим дозволів, можуть дотримуватися цієї політики.
Claude CLI додає `--permission-mode bypassPermissions`, коли запитана OpenClaw політика виконання є
YOLO. Перевизначте цю поведінку бекенда явними аргументами Claude в
`agents.defaults.cliBackends.claude-cli.args` / `resumeArgs`, наприклад
`--permission-mode default`, `acceptEdits` або `bypassPermissions`.
- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд або рівень відхилення скриптів перед виконанням поверх налаштованої політики виконання на хості.
- `auto` не робить маршрутизацію через gateway безкоштовним способом обійти обмеження із сеансу в пісочниці. Запит `host=node` для окремого виклику дозволений з `auto`, а `host=gateway` дозволений з `auto` лише тоді, коли немає активного середовища виконання в пісочниці. Якщо вам потрібне стабільне значення за замовчуванням, відмінне від auto, установіть `tools.exec.host` або використовуйте `/exec host=...` явно.
- У режимі YOLO OpenClaw не додає окремий евристичний шлюз затвердження для обфускації команд або шар відхилення script-preflight поверх налаштованої політики виконання на хості.
- `auto` не перетворює маршрутизацію через gateway на безкоштовне перевизначення із сеансу в пісочниці. Запит на рівні виклику `host=node` дозволений із `auto`, а `host=gateway` дозволений із `auto` лише тоді, коли середовище виконання пісочниці неактивне. Якщо вам потрібне стабільне типове значення без 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 +137,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
Потім узгодьте з цим файл підтверджень хоста:
Потім налаштуйте файл затверджень хоста відповідно:
```bash
openclaw approvals set --stdin <<'EOF'
@ -150,22 +152,22 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
Локальний скорочений спосіб для тієї самої політики gateway host на поточній машині:
Локальне скорочення для тієї самої політики gateway-host на поточній машині:
```bash
openclaw exec-policy preset yolo
```
Цей локальний скорочений спосіб оновлює обидва:
Це локальне скорочення оновлює обидва:
- локальні `tools.exec.host/security/ask`
- локальні значення за замовчуванням у `~/.openclaw/exec-approvals.json`
- локальні типові значення в `~/.openclaw/exec-approvals.json`
Він навмисно працює лише локально. Якщо вам потрібно змінити підтвердження gateway host або node host
Воно навмисно працює лише локально. Якщо вам потрібно змінити затвердження gateway-host або node-host
віддалено, і надалі використовуйте `openclaw approvals set --gateway` або
`openclaw approvals set --node <id|name|ip>`.
Для хоста вузла застосуйте той самий файл підтверджень на цьому вузлі:
Для хоста Node застосуйте той самий файл затверджень на цій Node:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -180,45 +182,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
EOF
```
Важливе обмеження лише для локального використання:
Важливе обмеження лише для локального режиму:
- `openclaw exec-policy` не синхронізує підтвердження вузла
- `openclaw exec-policy` не синхронізує затвердження Node
- `openclaw exec-policy set --host node` відхиляється
- підтвердження виконання вузла отримуються з вузла під час виконання, тому для оновлень, спрямованих на вузол, потрібно використовувати `openclaw approvals --node ...`
- затвердження виконання Node отримуються з Node під час виконання, тому цільові оновлення для Node потрібно робити через `openclaw approvals --node ...`
Скорочений спосіб лише для сеансу:
Скорочення лише для сеансу:
- `/exec security=full ask=off` змінює лише поточний сеанс.
- `/elevated full` — це аварійний скорочений спосіб, який також пропускає підтвердження виконання для цього сеансу.
- `/elevated full` — це аварійне скорочення, яке також пропускає затвердження виконання для цього сеансу.
Якщо файл підтверджень хоста залишається суворішим за конфігурацію, перевагу все одно має суворіша політика хоста.
Якщо файл затверджень хоста залишається суворішим за конфігурацію, усе одно перемагає суворіша політика хоста.
## Параметри політики
### Security (`exec.security`)
- **deny**: блокувати всі запити на виконання на хості.
- **allowlist**: дозволяти лише команди зі списку дозволених елементів.
- **allowlist**: дозволяти лише команди зі списку дозволеного.
- **full**: дозволяти все (еквівалент elevated).
### Ask (`exec.ask`)
- **off**: ніколи не запитувати.
- **on-miss**: запитувати лише тоді, коли список дозволених елементів не збігається.
- **always**: запитувати для кожної команди.
- довірений режим `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always`
- **off**: ніколи не показувати запит.
- **on-miss**: показувати запит лише тоді, коли список дозволеного не збігається.
- **always**: показувати запит для кожної команди.
- довготривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always`
### Ask fallback (`askFallback`)
Якщо потрібне підтвердження, але немає доступного UI, резервний варіант визначає дію:
Якщо потрібен запит, але жоден UI недоступний, резервна поведінка визначає:
- **deny**: блокувати.
- **allowlist**: дозволяти лише за умови збігу зі списком дозволених елементів.
- **allowlist**: дозволяти лише за наявності збігу зі списком дозволеного.
- **full**: дозволяти.
### Посилений режим inline eval для інтерпретаторів (`tools.exec.strictInlineEval`)
### Посилення inline interpreter eval (`tools.exec.strictInlineEval`)
Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують лише явного підтвердження, навіть якщо сам двійковий файл інтерпретатора внесений до списку дозволених елементів.
Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують лише затвердження, навіть якщо сам двійковий файл інтерпретатора є в списку дозволеного.
Приклади:
@ -230,15 +232,18 @@ EOF
- `lua -e`
- `osascript -e`
Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються однозначно з одним стабільним файловим операндом. У строгому режимі:
Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються чисто з одним стабільним файловим операндом. У строгому режимі:
- такі команди все одно потребують явного підтвердження;
- `allow-always` не зберігає для них нові записи списку дозволених елементів автоматично.
- ці команди все одно потребують явного затвердження;
- `allow-always` не зберігає для них нові записи списку дозволеного автоматично.
## Список дозволених елементів (для кожного агента)
## Список дозволеного (для кожного агента)
Списки дозволених елементів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, якого ви редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**. Шаблони мають відповідати **шляхам до двійкових файлів** (записи лише з basename ігноруються). Застарілі записи `agents.default` під час завантаження переносяться до `agents.main`.
Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволених елементів.
Списки дозволеного є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента,
якого ви редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**.
Шаблони мають розв’язуватися до **шляхів двійкових файлів** (записи лише з basename ігноруються).
Застарілі записи `agents.default` під час завантаження мігруються до `agents.main`.
Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволеного.
Приклади:
@ -246,297 +251,65 @@ Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимага
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`
Кожен запис списку дозволених елементів відстежує:
Кожен запис списку дозволеного відстежує:
- **id** — стабільний UUID, що використовується для ідентифікації в UI (необов’язково)
- **last used** — мітка часу останнього використання
- **id** — стабільний UUID, який використовується для ідентичності в UI (необов’язково)
- **last used** — позначка часу останнього використання
- **last used command**
- **last resolved path**
## Автодозвіл для CLI зі Skills
## Автодозвіл для CLI Skills
Коли ввімкнено **Auto-allow skill CLIs**, виконувані файли, на які посилаються відомі Skills,
вважаються внесеними до списку дозволених елементів на вузлах (вузол macOS або headless-хост вузла). Для цього використовується
`skills.bins` через Gateway RPC, щоб отримати список bin-файлів skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволених елементів.
розглядаються як такі, що входять до списку дозволеного на Node (macOS node або headless-хост Node). Для цього використовується
`skills.bins` через Gateway RPC, щоб отримати список bin для skill. Вимкніть це, якщо вам потрібні суворі списки дозволеного, задані вручну.
Важливі примітки щодо довіри:
- Це **неявний зручний список дозволених елементів**, окремий від ручних записів списку дозволених шляхів.
- Він призначений для довірених середовищ операторів, де Gateway і вузол перебувають в одній межі довіри.
- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволених шляхів.
- Це **неявний зручний список дозволеного**, окремий від записів ручного списку дозволеного за шляхами.
- Він призначений для середовищ довірених операторів, де Gateway і Node перебувають в одній межі довіри.
- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволеного за шляхами.
## Безпечні bin-файли (лише stdin)
## Safe bins і пересилання затвердження
`tools.exec.safeBins` визначає невеликий список **bin-файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволених елементів. Безпечні bin-файли відхиляють позиційні аргументи файлів і токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. Сприймайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри.
Щодо safe bins (швидкий шлях лише через stdin), деталей прив’язки інтерпретатора та того,
як пересилати запити на затвердження до Slack/Discord/Telegram (або запускати їх як нативні
клієнти затвердження), див. [Затвердження виконання — додатково](/uk/tools/exec-approvals-advanced).
<Warning>
**Не** додавайте двійкові файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`,
`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код,
виконувати підкоманди або читати файли, віддавайте перевагу явним записам списку дозволених елементів
і залишайте ввімкненими запити на підтвердження. Користувацькі safe bins мають визначати явний
профіль у `tools.exec.safeBinProfiles.<bin>`.
</Warning>
<!-- moved to /tools/exec-approvals-advanced -->
Типові safe bins:
## Редагування в UI керування
[//]: # "SAFE_BIN_DEFAULTS:START"
Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення
для окремих агентів і списки дозволеного. Виберіть область (Defaults або агент), налаштуйте політику,
додайте/видаліть шаблони списку дозволеного, а потім натисніть **Save**. UI показує метадані **last used**
для кожного шаблону, щоб вам було легше підтримувати список в охайному стані.
`cut`, `uniq`, `head`, `tail`, `tr`, `wc`
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` і `sort` не входять до типового списку. Якщо ви вмикаєте їх, зберігайте явні
записи списку дозволених елементів для їхніх сценаріїв, що не обмежуються stdin. Для `grep` у режимі safe-bin
вказуйте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється,
щоб файлові операнди не можна було непомітно передати як неоднозначні позиційні аргументи.
### Перевірка Argv і заборонені прапорці
Перевірка є детермінованою лише за формою argv (без перевірок існування файлової системи хоста), що запобігає поведінці оракула існування файлів через відмінності між allow/deny. Параметри, орієнтовані на файли, заборонені для типових safe bins; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці й неоднозначні скорочення відхиляються).
Заборонені прапорці за профілем safe-bin:
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
- `wc`: `--files0-from`
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
Safe bins також примусово обробляють токени argv як **буквальний текст** під час виконання
(без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони
на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів.
### Довірені каталоги двійкових файлів
Safe bins мають визначатися з довірених каталогів двійкових файлів (системні типові значення плюс необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично. Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо ваш виконуваний файл safe-bin розташовано в шляхах менеджера пакетів або користувача (наприклад, `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до `tools.exec.safeBinTrustedDirs`.
### Ланцюжки shell-команд, обгортки та мультиплексори
Ланцюжки shell-команд (`&&`, `||`, `;`) дозволені, коли кожен сегмент верхнього рівня відповідає списку дозволених елементів (зокрема safe bins або автодозвіл для skill). Переспрямування залишаються непідтримуваними в режимі allowlist. Підстановка команд (`$()` / зворотні лапки) відхиляється під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`.
У підтвердженнях companion app на macOS необроблений текст shell, що містить керівний або розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), розглядається як промах allowlist, якщо сам двійковий файл shell не внесений до списку дозволених елементів.
Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту зводяться до невеликого явного списку дозволених елементів (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішній шлях до виконуваного файла замість шляху обгортки. Shell-мультиплексори (`busybox`, `toybox`) так само розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо обгортку або мультиплексор неможливо безпечно розгорнути, запис allowlist не зберігається автоматично.
Якщо ви додаєте до allowlist інтерпретатори, як-от `python3` або `node`, краще встановити
`tools.exec.strictInlineEval=true`, щоб inline eval усе ще вимагав явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються.
### Safe bins проти allowlist
| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| Призначення | Автодозвіл для вузьких 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>` як `{}` (перегляньте та посильте їх після цього). Для двійкових файлів інтерпретатора/середовища виконання шаблони не створюються автоматично.
Приклад користувацького профілю:
__OC_I18N_900005__
Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє вбудовану команду `env` у режимі safe-bin,
щоб `jq -n env` не міг вивантажити середовище процесу хоста без явного шляху allowlist
або запиту на підтвердження.
## Редагування в Control UI
Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати значення за замовчуванням, перевизначення для конкретного агента та списки дозволених елементів. Виберіть область (Defaults або агент), змініть політику, додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **last used** для кожного шаблону, щоб список залишався впорядкованим.
Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли
мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост вузла).
Якщо вузол ще не оголошує підтвердження виконання, редагуйте його локальний
Перемикач цілі вибирає **Gateway** (локальні затвердження) або **Node**. Node
мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост Node).
Якщо Node ще не оголошує затвердження виконання, редагуйте її локальний
`~/.openclaw/exec-approvals.json` безпосередньо.
CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI підтверджень](/cli/approvals)).
CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI затверджень](/uk/cli/approvals)).
## Потік підтвердження
## Потік затвердження
Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам операторів.
Control UI і застосунок macOS обробляють це через `exec.approval.resolve`, а потім gateway пересилає
схвалений запит до хоста вузла.
Коли потрібен запит, gateway розсилає `exec.approval.requested` клієнтам операторів.
Control UI і застосунок macOS обробляють його через `exec.approval.resolve`, після чого gateway пересилає
затверджений запит на хост Node.
Для `host=node` запити на підтвердження містять канонічний payload `systemRunPlan`. Gateway використовує
цей план як авторитетний контекст command/cwd/session під час пересилання схвалених запитів `system.run`.
Для `host=node` запити на затвердження містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує
цей план як авторитетний контекст команди/cwd/сеансу під час пересилання затверджених запитів `system.run`.
Це важливо для затримки асинхронного підтвердження:
Це важливо для затримки асинхронного затвердження:
- шлях виконання вузла готує один канонічний план наперед
- запис підтвердження зберігає цей план і його метадані прив’язки
- після схвалення остаточний пересланий виклик `system.run` повторно використовує збережений план
замість довіри до пізніших змін з боку викликача
- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
`sessionKey` після створення запиту на підтвердження, gateway відхиляє
пересланий запуск як невідповідність підтвердженню
## Команди інтерпретатора/середовища виконання
Запуски інтерпретатора/середовища виконання, підтримані підтвердженням, навмисно консервативні:
- Точний контекст argv/cwd/env завжди прив’язується.
- Форми прямого shell-скрипта й прямого файла середовища виконання прив’язуються в режимі best-effort до одного конкретного локального знімка файла.
- Поширені форми обгорток менеджерів пакетів, які все ще визначаються як один прямий локальний файл (наприклад
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою.
- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання
(наприклад package scripts, eval-форми, специфічні для середовища виконання ланцюжки завантаження або неоднозначні багатофайлові
форми), виконання, підтримане підтвердженням, відхиляється замість того, щоб заявляти про семантичне покриття,
якого насправді немає.
- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний
довірений робочий процес allowlist/full, де оператор приймає ширшу семантику середовища виконання.
Коли потрібні підтвердження, інструмент exec одразу повертає ідентифікатор підтвердження. Використовуйте цей ідентифікатор, щоб
співвідносити подальші системні події (`Exec finished` / `Exec denied`). Якщо до завершення
тайм-ауту рішення не надійде, запит вважається таким, що перевищив час очікування підтвердження, і відображається як причина відхилення.
### Поведінка доставлення followup
Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` у той самий сеанс.
- Якщо існує коректна зовнішня ціль доставлення (канал із можливістю доставлення плюс ціль `to`), доставлення followup використовує цей канал.
- У потоках лише вебчату або внутрішнього сеансу без зовнішньої цілі доставлення followup залишається лише в межах сеансу (`deliver: false`).
- Якщо викликач явно запитує суворе зовнішнє доставлення без такого зовнішнього каналу, запит завершується помилкою `INVALID_REQUEST`.
- Якщо ввімкнено `bestEffortDeliver` і зовнішній канал не вдається визначити, доставлення знижується до режиму лише для сеансу замість помилки.
Діалог підтвердження містить:
- command + args
- cwd
- id агента
- визначений шлях до виконуваного файла
- метадані host + policy
Дії:
- **Allow once** → виконати зараз
- **Always allow** → додати до allowlist + виконати
- **Deny** → заблокувати
## Пересилання підтверджень до чат-каналів
Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (зокрема каналів Plugin) і схвалювати
їх через `/approve`. Для цього використовується звичайний конвеєр вихідного доставлення.
Конфігурація:
__OC_I18N_900006__
Відповідь у чаті:
__OC_I18N_900007__
Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin. Якщо ID не відповідає очікуваному підтвердженню exec, вона автоматично перевіряє підтвердження Plugin.
### Пересилання підтверджень Plugin
Пересилання підтверджень Plugin використовує той самий конвеєр доставлення, що й підтвердження exec, але має власну
незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше.
__OC_I18N_900008__
Форма конфігурації ідентична до `approvals.exec`: `enabled`, `mode`, `agentFilter`,
`sessionFilter` і `targets` працюють однаково.
Канали, що підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для
підтверджень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`.
### Підтвердження в тому самому чаті на будь-якому каналі
Коли запит на підтвердження exec або Plugin походить із чат-поверхні з можливістю доставлення, той самий чат
тепер може схвалити його через `/approve` за замовчуванням. Це стосується таких каналів, як Slack, Matrix і
Microsoft Teams, на додачу до вже наявних потоків Web UI і terminal UI.
Цей спільний шлях текстових команд використовує звичайну модель автентифікації каналу для цієї розмови. Якщо початковий
чат уже може надсилати команди й отримувати відповіді, запитам на підтвердження більше не потрібен
окремий нативний адаптер доставлення, щоб залишатися в стані очікування.
Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали й далі використовують свій
визначений список схвалювачів для авторизації, навіть коли нативне доставлення підтверджень вимкнено.
Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway напряму,
цей резервний варіант навмисно обмежений помилками типу «підтвердження не знайдено». Реальна
відмова/помилка підтвердження exec не повторюється мовчки як підтвердження Plugin.
### Нативне доставлення підтверджень
Деякі канали також можуть працювати як нативні клієнти підтвердження. Нативні клієнти додають DM схвалювачам, fanout у чаті походження
і специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve`
у тому самому чаті.
Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним
шляхом для агента. Агент не повинен також дублювати звичайну чат-команду
`/approve`, якщо тільки результат інструмента не вказує, що чат-підтвердження недоступні або
єдиним варіантом, що залишився, є ручне підтвердження.
Загальна модель:
- політика виконання на хості все ще визначає, чи потрібне підтвердження exec
- `approvals.exec` керує пересиланням запитів на підтвердження до інших цільових чатів
- `channels.<channel>.execApprovals` визначає, чи діє цей канал як нативний клієнт підтвердження
Нативні клієнти підтвердження автоматично вмикають доставлення спочатку в DM, коли виконуються всі ці умови:
- канал підтримує нативне доставлення підтверджень
- схвалювачів можна визначити з явних `execApprovals.approvers` або з
документованих резервних джерел цього каналу
- `channels.<channel>.execApprovals.enabled` не задано або дорівнює `"auto"`
Установіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Установіть `enabled: true`, щоб примусово
увімкнути його, коли визначаються схвалювачі. Публічне доставлення до чату походження й надалі задається явно через
`channels.<channel>.execApprovals.target`.
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` у тому самому чаті та спільних кнопок підтвердження.
Спільна поведінка:
- Slack, Matrix, Microsoft Teams і подібні чати з можливістю доставлення використовують звичайну модель автентифікації каналу
для `/approve` у тому самому чаті
- коли нативний клієнт підтвердження вмикається автоматично, типовою ціллю нативного доставлення є DM схвалювачам
- для Discord і Telegram лише визначені схвалювачі можуть схвалювати або відхиляти
- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom`
- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виведеними з наявної конфігурації власника (`allowFrom`, а також `defaultTo` для прямих повідомлень, де це підтримується)
- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom`
- нативні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть обробляти підтвердження Plugin
без другого локального резервного рівня Slack
- нативна маршрутизація DM/каналу в Matrix і швидкі реакції обробляють як підтвердження exec, так і Plugin;
авторизація Plugin і надалі походить із `channels.matrix.dm.allowFrom`
- запитувач не зобов’язаний бути схвалювачем
- чат походження може схвалити запит напряму через `/approve`, коли цей чат уже підтримує команди й відповіді
- нативні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять
безпосередньо до підтверджень Plugin, усе інше — до підтверджень exec
- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve`
- коли нативний `target` вмикає доставлення до чату походження, запити на підтвердження містять текст команди
- очікувані підтвердження exec типово спливають через 30 хвилин
- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, для запиту використовується `askFallback`
Для Telegram типово використовуються DM схвалювачам (`target: "dm"`). Ви можете переключитися на `channel` або `both`, якщо
хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram
OpenClaw зберігає тему для запиту на підтвердження та follow-up після підтвердження.
Див. також:
- [Discord](/channels/discord)
- [Telegram](/channels/telegram)
### Потік IPC у macOS
__OC_I18N_900009__
Примітки щодо безпеки:
- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`.
- Перевірка peer з тим самим UID.
- Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL.
- шлях виконання node готує один канонічний план наперед
- запис затвердження зберігає цей план та його метадані прив’язки
- після затвердження остаточний пересланий виклик `system.run` повторно використовує збережений план
замість того, щоб довіряти пізнішим змінам виклику
- якщо виклик змінює `command`, `rawCommand`, `cwd`, `agentId` або
`sessionKey` після створення запиту на затвердження, gateway відхиляє
пересланий запуск як невідповідність затвердженню
## Системні події
@ -546,34 +319,37 @@ __OC_I18N_900009__
- `Exec finished`
- `Exec denied`
Вони публікуються в сеанс агента після того, як вузол повідомляє про подію.
Підтвердження exec на gateway host генерують ті самі події життєвого циклу, коли команда завершується (і необов’язково коли виконується довше за поріг).
Виклики exec, захищені підтвердженням, повторно використовують id підтвердження як `runId` у цих повідомленнях для зручного зіставлення.
Вони публікуються в сеанс агента після того, як Node повідомляє про подію.
Затвердження виконання на gateway-host видають ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли вона виконується довше за поріг).
Виконання з перевіркою через затвердження повторно використовують ідентифікатор затвердження як `runId` у цих повідомленнях для зручної кореляції.
## Поведінка при відхиленому підтвердженні
## Поведінка у разі відхилення затвердження
Коли підтвердження асинхронного exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати
вивід із будь-якого попереднього запуску тієї самої команди в межах сеансу. Причина відхилення
передається з явною вказівкою, що вивід команди недоступний, що не дає
агенту стверджувати, ніби є новий вивід, або повторювати відхилену команду зі
застарілими результатами попереднього успішного запуску.
Коли асинхронне затвердження виконання відхиляється, OpenClaw не дозволяє агенту повторно використовувати
вивід будь-якого попереднього запуску тієї самої команди в цьому сеансі. Причина відхилення
передається разом із явною вказівкою, що вивід команди недоступний, що не дає
агенту стверджувати, що є новий вивід, або повторювати відхилену команду зі
застарілими результатами з попереднього успішного запуску.
## Наслідки
- **full** є потужним режимом; коли можливо, віддавайте перевагу спискам дозволених елементів.
- **ask** тримає вас у контурі, водночас дозволяючи швидкі підтвердження.
- Списки дозволених елементів для кожного агента окремо не дають підтвердженням одного агента «просочуватися» до інших.
- Підтвердження застосовуються лише до запитів exec на хості від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`.
- `/exec security=full` — це зручний параметр рівня сеансу для авторизованих операторів, і він навмисно пропускає підтвердження. Щоб жорстко заблокувати виконання на хості, установіть для security підтверджень значення `deny` або забороніть інструмент `exec` через політику інструментів.
- **full** — потужний режим; коли можливо, надавайте перевагу спискам дозволеного.
- **ask** тримає вас у курсі подій, водночас дозволяючи швидкі затвердження.
- Окремі для кожного агента списки дозволеного не дають затвердженням одного агента поширюватися на інших.
- Затвердження застосовуються лише до запитів на виконання на хості від **авторизованих відправників**. Неавторизовані відправники не можуть видавати `/exec`.
- `/exec security=full` — це зручність на рівні сеансу для авторизованих операторів і за задумом пропускає затвердження. Щоб жорстко заблокувати виконання на хості, установіть для затверджень значення security `deny` або забороніть інструмент `exec` через політику інструментів.
## Пов’язане
<CardGroup cols={2}>
<Card title="Інструмент Exec" href="/uk/tools/exec" icon="terminal">
Інструмент виконання shell-команд.
<Card title="Затвердження виконання — додатково" href="/uk/tools/exec-approvals-advanced" icon="gear">
Safe bins, прив’язка інтерпретатора та пересилання затверджень до чату.
</Card>
<Card title="Інструмент exec" href="/uk/tools/exec" icon="terminal">
Інструмент виконання команд shell.
</Card>
<Card title="Режим elevated" href="/uk/tools/elevated" icon="shield-exclamation">
Аварійний шлях, який також пропускає підтвердження.
Аварійний шлях, який також пропускає затвердження.
</Card>
<Card title="Пісочниця" href="/uk/gateway/sandboxing" icon="box">
Режими пісочниці та доступ до робочого простору.
@ -582,7 +358,7 @@ __OC_I18N_900009__
Модель безпеки та посилення захисту.
</Card>
<Card title="Пісочниця vs політика інструментів vs elevated" href="/uk/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
Коли варто використовувати кожен із цих механізмів.
Коли варто використовувати кожен із цих засобів керування.
</Card>
<Card title="Skills" href="/uk/tools/skills" icon="sparkles">
Поведінка автодозволу на основі Skills.

233
docs/uk/tools/exec.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Використання або змінення інструмента Exec
- Використання або змінення інструмента exec
- Налагодження поведінки stdin або TTY
summary: Використання інструмента Exec, режими stdin і підтримка TTY
title: Інструмент Exec
summary: Використання інструмента exec, режими stdin і підтримка TTY
title: Інструмент exec
x-i18n:
generated_at: "2026-04-23T23:07:45Z"
generated_at: "2026-04-23T23:27:47Z"
model: gpt-5.4
provider: openai
source_hash: 4e2a7fc3b0570d59a6694d0a4ff9def1a5721c8a3d13abf7f947e7ea835535b3
source_hash: 4cad17fecfaf7d6a523282ef4f0090e4ffaab89ab53945b5cd831e426f3fc3ac
source_path: tools/exec.md
workflow: 15
---
Запускає shell-команди у workspace. Підтримує виконання у foreground + background через `process`.
Якщо `process` заборонено, `exec` виконується синхронно й ігнорує `yieldMs`/`background`.
Background-сесії мають область дії в межах агента; `process` бачить лише сесії того самого агента.
Запускає shell-команди в робочому просторі. Підтримує виконання на передньому плані й у фоновому режимі через `process`.
Якщо `process` недоступний, `exec` запускається синхронно та ігнорує `yieldMs`/`background`.
Фонові сесії обмежені межами агента; `process` бачить лише сесії того самого агента.
## Параметри
<ParamField path="command" type="string" required>
Команда shell для запуску.
Shell-команда для запуску.
</ParamField>
<ParamField path="workdir" type="string" default="cwd">
@ -28,27 +28,27 @@ Background-сесії мають область дії в межах агент
</ParamField>
<ParamField path="env" type="object">
Перевизначення середовища у форматі ключ/значення, об’єднані поверх успадкованого середовища.
Перевизначення змінних середовища у форматі ключ/значення, які об’єднуються поверх успадкованого середовища.
</ParamField>
<ParamField path="yieldMs" type="number" default="10000">
Автоматично переводить команду в background після цієї затримки (мс).
Автоматично переводить команду у фоновий режим після цієї затримки (мс).
</ParamField>
<ParamField path="background" type="boolean" default="false">
Негайно переводить команду в background замість очікування `yieldMs`.
Негайно переводить команду у фоновий режим замість очікування `yieldMs`.
</ParamField>
<ParamField path="timeout" type="number" default="1800">
Завершити команду після такої кількості секунд.
Завершує команду після такої кількості секунд.
</ParamField>
<ParamField path="pty" type="boolean" default="false">
Запускати в псевдотерміналі, якщо доступно. Використовуйте для CLI, що працюють лише з TTY, coding-агентів і terminal UI.
Запускає в псевдотерміналі, коли це можливо. Використовуйте для CLI, що потребують TTY, агентів кодування та термінальних UI.
</ParamField>
<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
Де виконувати. `auto` перетворюється на `sandbox`, коли активний runtime sandbox, і на `gateway` в іншому разі.
Де виконувати. `auto` визначається як `sandbox`, коли для середовища виконання активний sandbox, інакше як `gateway`.
</ParamField>
<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
@ -56,63 +56,63 @@ Background-сесії мають область дії в межах агент
</ParamField>
<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
Поведінка запиту погодження для виконання `gateway` / `node`.
Поведінка запиту на схвалення для виконання `gateway` / `node`.
</ParamField>
<ParamField path="node" type="string">
Id/назва Node, коли `host=node`.
Ідентифікатор або назва Node, коли `host=node`.
</ParamField>
<ParamField path="elevated" type="boolean" default="false">
Запитати elevated mode — вийти із sandbox на налаштований шлях хоста. `security=full` примусово застосовується лише тоді, коли elevated перетворюється на `full`.
Запитує підвищений режим — вихід із sandbox на налаштований шлях хоста. `security=full` примусово встановлюється лише тоді, коли elevated визначається як `full`.
</ParamField>
Примітки:
- `host` типово дорівнює `auto`: sandbox, коли runtime sandbox активний для сесії, інакше gateway.
- `auto` — це типова стратегія маршрутизації, а не wildcard. Виклик `host=node` для окремого запиту дозволено з `auto`; виклик `host=gateway` для окремого запиту дозволено лише тоді, коли runtime sandbox неактивний.
- Без додаткового config `host=auto` усе одно «просто працює»: без sandbox він перетворюється на `gateway`; з активним sandbox залишається в sandbox.
- `elevated` виходить із sandbox на налаштований шлях хоста: типово `gateway`, або `node`, коли `tools.exec.host=node` (або типовим значенням сесії є `host=node`). Це доступно лише тоді, коли для поточної сесії/провайдера ввімкнено elevated access.
- Погодження `gateway`/`node` керуються через `~/.openclaw/exec-approvals.json`.
- `node` потребує pairied Node (companion app або headless-хост Node).
- Якщо доступно кілька Node, задайте `exec.node` або `tools.exec.node`, щоб вибрати одну.
- `exec host=node` — це єдиний шлях виконання shell для Node; застарілу обгортку `nodes.run` видалено.
- На хостах не з Windows exec використовує `SHELL`, якщо його задано; якщо `SHELL` — це `fish`, він надає перевагу `bash` (або `sh`)
з `PATH`, щоб уникнути несумісних із fish скриптів, а потім повертається до `SHELL`, якщо жодного з них немає.
- На хостах Windows exec надає перевагу пошуку PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, потім PATH),
- `host` типово має значення `auto`: sandbox, коли для сесії активне середовище виконання sandbox, інакше gateway.
- `auto` — це типова стратегія маршрутизації, а не шаблон. Виклик із `host=node` на рівні окремого запиту дозволений із `auto`; виклик із `host=gateway` на рівні окремого запиту дозволений лише тоді, коли середовище виконання sandbox не активне.
- Без додаткової конфігурації `host=auto` усе одно «просто працює»: без sandbox він визначається як `gateway`; з активним sandbox лишається в sandbox.
- `elevated` виводить із sandbox на налаштований шлях хоста: типово `gateway`, або `node`, коли `tools.exec.host=node` (або типовим для сесії є `host=node`). Доступний лише тоді, коли для поточної сесії/провайдера ввімкнено підвищений доступ.
- Схвалення для `gateway`/`node` керуються через `~/.openclaw/exec-approvals.json`.
- Для `node` потрібен спарений Node (додаток-компаньйон або безголовий вузол-хост).
- Якщо доступно кілька Node, установіть `exec.node` або `tools.exec.node`, щоб вибрати один.
- `exec host=node` — єдиний шлях виконання shell-команд для Node; застарілу обгортку `nodes.run` вилучено.
- На хостах, відмінних від Windows, exec використовує `SHELL`, якщо його задано; якщо `SHELL` має значення `fish`, він віддає перевагу `bash` (або `sh`)
із `PATH`, щоб уникнути скриптів, несумісних із fish, а потім повертається до `SHELL`, якщо жоден із них не існує.
- На хостах Windows exec віддає перевагу пошуку PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, потім PATH),
а потім повертається до Windows PowerShell 5.1.
- Виконання на хості (`gateway`/`node`) відхиляє `env.PATH` і перевизначення loader (`LD_*`/`DYLD_*`), щоб
- Виконання на хості (`gateway`/`node`) відхиляє перевизначення `env.PATH` і завантажувача (`LD_*`/`DYLD_*`), щоб
запобігти підміні бінарних файлів або ін’єкції коду.
- OpenClaw задає `OPENCLAW_SHELL=exec` у середовищі запущеної команди (включно з PTY і виконанням у sandbox), щоб правила shell/profile могли визначати контекст exec-tool.
- Важливо: sandboxing **вимкнений типово**. Якщо sandboxing вимкнено, неявний `host=auto`
перетворюється на `gateway`. Явний `host=sandbox` усе одно завершується в режимі fail-closed замість тихого
виконання на хості gateway. Увімкніть sandboxing або використовуйте `host=gateway` з погодженнями.
- Preflight-перевірки скриптів (для типових помилок синтаксису shell у Python/Node) перевіряють лише файли в межах
ефективної межі `workdir`. Якщо шлях до скрипта перетворюється на такий, що виходить за межі `workdir`, preflight для
цього файла пропускається.
- Для довготривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне
пробудження після завершення, коли воно ввімкнене і команда виводить щось або завершується помилкою.
Використовуйте `process` для журналів, статусу, введення або втручання; не імітуйте
планування через цикли sleep, цикли timeout або повторне polling.
- Для роботи, яка має відбутися пізніше або за розкладом, використовуйте cron замість
шаблонів sleep/delay через `exec`.
- OpenClaw установлює `OPENCLAW_SHELL=exec` у середовищі запущеної команди (зокрема для PTY і виконання в sandbox), щоб правила shell/профілю могли виявити контекст інструмента exec.
- Важливо: sandboxing **типово вимкнений**. Якщо sandboxing вимкнено, неявний `host=auto`
визначається як `gateway`. Явний `host=sandbox` у такому разі все одно завершується закритою відмовою, а не тихо
запускається на хості gateway. Увімкніть sandboxing або використовуйте `host=gateway` зі схваленнями.
- Перевірки preflight для скриптів (для поширених помилок синтаксису shell у Python/Node) перевіряють лише файли в межах
фактичної межі `workdir`. Якщо шлях до скрипта визначається поза `workdir`, preflight для
цього файлу пропускається.
- Для довготривалої роботи, яка починається зараз, запускайте її один раз і покладайтеся на автоматичне
пробудження після завершення, якщо воно ввімкнене і команда виводить результат або завершується з помилкою.
Використовуйте `process` для журналів, стану, введення або втручання; не імітуйте
планування за допомогою циклів sleep, циклів timeout або повторного опитування.
- Для роботи, яка має відбутися пізніше або за розкладом, використовуйте Cron замість
шаблонів sleep/delay з `exec`.
## Config
## Конфігурація
- `tools.exec.notifyOnExit` (типово: true): якщо true, переведені в background exec-сесії ставлять у чергу system event і запитують Heartbeat під час завершення.
- `tools.exec.approvalRunningNoticeMs` (типово: 10000): видає одне сповіщення “running”, коли exec із погодженням виконується довше за цей час (0 вимикає).
- `tools.exec.host` (типово: `auto`; перетворюється на `sandbox`, коли runtime sandbox активний, інакше на `gateway`)
- `tools.exec.security` (типово: `deny` для sandbox, `full` для gateway + node, якщо не задано)
- `tools.exec.notifyOnExit` (типово: true): якщо true, фонові сесії exec ставлять системну подію в чергу та запитують Heartbeat після завершення.
- `tools.exec.approvalRunningNoticeMs` (типово: 10000): надсилає одне сповіщення «виконується», коли exec, що потребує схвалення, працює довше за цей час (0 вимикає).
- `tools.exec.host` (типово: `auto`; визначається як `sandbox`, коли активне середовище виконання sandbox, інакше як `gateway`)
- `tools.exec.security` (типово: `deny` для sandbox, `full` для gateway і node, якщо не задано)
- `tools.exec.ask` (типово: `off`)
- Виконання host exec без погодження є типовим для gateway + node. Якщо вам потрібна поведінка з погодженнями/allowlist, посильте і `tools.exec.*`, і політику хоста `~/.openclaw/exec-approvals.json`; див. [Погодження Exec](/uk/tools/exec-approvals#no-approval-yolo-mode).
- YOLO походить із типових значень політики хоста (`security=full`, `ask=off`), а не з `host=auto`. Якщо хочете примусово використовувати маршрутизацію gateway або node, задайте `tools.exec.host` або використовуйте `/exec host=...`.
- У режимі `security=full` плюс `ask=off` host exec напряму дотримується налаштованої policy; немає додаткового евристичного prefilter заплутування команд або шару відхилення script-preflight.
- Виконання на хості без схвалення є типовим для gateway і node. Якщо потрібна поведінка зі схваленнями/allowlist, посильте як `tools.exec.*`, так і політику хоста в `~/.openclaw/exec-approvals.json`; див. [Схвалення exec](/uk/tools/exec-approvals#no-approval-yolo-mode).
- Режим YOLO походить із типових значень політики хоста (`security=full`, `ask=off`), а не з `host=auto`. Якщо потрібно примусово використовувати gateway або node, установіть `tools.exec.host` або використайте `/exec host=...`.
- У режимі `security=full` разом із `ask=off` виконання на хості напряму дотримується налаштованої політики; немає додаткового евристичного префільтра затемнення команд або шару відхилення script-preflight.
- `tools.exec.node` (типово: не задано)
- `tools.exec.strictInlineEval` (типово: false): якщо true, форми inline eval інтерпретаторів, такі як `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` і `osascript -e`, завжди потребують явного погодження. `allow-always` усе ще може зберігати довіру для безпечних викликів інтерпретатора/скрипта, але форми inline-eval усе одно запитують щоразу.
- `tools.exec.pathPrepend`: список каталогів, які потрібно додати на початок `PATH` для запусків exec (лише gateway + sandbox).
- `tools.exec.safeBins`: безпечні бінарні файли лише для stdin, які можуть працювати без явних записів у allowlist. Докладніше про поведінку див. в [Safe bins](/uk/tools/exec-approvals#safe-bins-stdin-only).
- `tools.exec.safeBinTrustedDirs`: додаткові явні каталоги, яким довіряють для перевірок шляхів виконуваних файлів safeBins. Записи `PATH` ніколи не вважаються надійними автоматично. Вбудовані типові значення — `/bin` і `/usr/bin`.
- `tools.exec.safeBinProfiles`: необов’язкова власна policy argv для кожного safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
- `tools.exec.strictInlineEval` (типово: false): якщо true, вбудовані форми eval в інтерпретаторах, як-от `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` і `osascript -e`, завжди вимагають явного схвалення. `allow-always` усе ще може зберігати довіру до безпечних викликів інтерпретаторів/скриптів, але форми inline-eval все одно щоразу запитують схвалення.
- `tools.exec.pathPrepend`: список каталогів, які потрібно додати на початок `PATH` для запусків exec (лише gateway і sandbox).
- `tools.exec.safeBins`: безпечні бінарні файли лише для stdin, які можуть запускатися без явних записів у allowlist. Подробиці поведінки див. у [Safe bins](/uk/tools/exec-approvals-advanced#safe-bins-stdin-only).
- `tools.exec.safeBinTrustedDirs`: додаткові явні каталоги, яким довіряють для перевірок шляхів виконуваних файлів у `safeBins`. Записи `PATH` ніколи не вважаються довіреними автоматично. Вбудовані типові значення — `/bin` і `/usr/bin`.
- `tools.exec.safeBinProfiles`: необов’язкова спеціальна політика argv для кожного safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`).
Приклад:
@ -128,29 +128,29 @@ Id/назва Node, коли `host=node`.
### Обробка PATH
- `host=gateway`: об’єднує `PATH` вашого login-shell із середовищем exec. Перевизначення `env.PATH`
відхиляються для виконання на хості. Сам daemon усе одно працює з мінімальним `PATH`:
- `host=gateway`: об’єднує `PATH` вашої login-shell у середовище exec. Перевизначення `env.PATH`
відхиляються для виконання на хості. Сам демон і далі працює з мінімальним `PATH`:
- macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
- Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
- `host=sandbox`: запускає `sh -lc` (login shell) всередині контейнера, тому `/etc/profile` може скидати `PATH`.
OpenClaw додає `env.PATH` на початок після завантаження profile через внутрішню env var (без shell-інтерполяції);
- `host=sandbox`: запускає `sh -lc` (login shell) усередині контейнера, тому `/etc/profile` може скидати `PATH`.
OpenClaw додає `env.PATH` на початок після завантаження профілю через внутрішню змінну середовища (без інтерполяції shell);
`tools.exec.pathPrepend` теж застосовується тут.
- `host=node`: на Node надсилаються лише не заблоковані перевизначення env, які ви передаєте. Перевизначення `env.PATH`
відхиляються для виконання на хості й ігноруються Node-хостами. Якщо вам потрібні додаткові записи PATH на Node,
налаштуйте середовище служби хоста Node (systemd/launchd) або встановіть інструменти в стандартні місця.
- `host=node`: лише передані вами перевизначення середовища, які не заблоковано, надсилаються до Node. Перевизначення `env.PATH`
відхиляються для виконання на хості та ігноруються хостами Node. Якщо вам потрібні додаткові записи PATH на Node,
налаштуйте середовище служби хоста Node (systemd/launchd) або встановіть інструменти в стандартні розташування.
Прив’язка Node для окремого агента (використовуйте індекс списку агентів у config):
Прив’язка Node на рівні агента (використовуйте індекс у списку агентів у конфігурації):
```bash
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
```
Control UI: вкладка Nodes містить невелику панель “Exec node binding” для тих самих налаштувань.
Керувальний UI: вкладка Nodes містить невелику панель “Exec node binding” для тих самих налаштувань.
## Перевизначення сесії (`/exec`)
Використовуйте `/exec`, щоб задати **типові значення для поточної сесії** для `host`, `security`, `ask` і `node`.
Використовуйте `/exec`, щоб установити **типові значення для поточної сесії** для `host`, `security`, `ask` і `node`.
Надішліть `/exec` без аргументів, щоб показати поточні значення.
Приклад:
@ -161,71 +161,72 @@ Control UI: вкладка Nodes містить невелику панель
## Модель авторизації
`/exec` обробляється лише для **авторизованих відправників** (allowlist/pairing каналу плюс `commands.useAccessGroups`).
Вона оновлює **лише стан сесії** і не записує config. Щоб жорстко вимкнути exec, забороніть його через tool
policy (`tools.deny: ["exec"]` або для окремого агента). Погодження хоста все одно застосовуються, якщо ви явно не задали
`/exec` враховується лише для **авторизованих відправників** (allowlist каналів/спарювання плюс `commands.useAccessGroups`).
Він оновлює **лише стан сесії** і не записує конфігурацію. Щоб повністю вимкнути exec, забороніть його через
політику інструментів (`tools.deny: ["exec"]` або на рівні агента). Схвалення на хості все одно застосовуються, якщо ви явно не встановите
`security=full` і `ask=off`.
## Погодження Exec (companion app / host Node)
## Схвалення exec (додаток-компаньйон / хост node)
Sandboxed-агенти можуть вимагати погодження для кожного запиту, перш ніж `exec` виконуватиметься на хості gateway або node.
Див. [Погодження Exec](/uk/tools/exec-approvals) для policy, allowlist і потоку UI.
Агенти в sandbox можуть вимагати схвалення для кожного запиту перед тим, як `exec` буде запущено на хості gateway або node.
Опис політики, allowlist і потоку UI див. у [Схвалення exec](/uk/tools/exec-approvals).
Коли потрібні погодження, інструмент exec одразу повертає
`status: "approval-pending"` та id погодження. Після погодження (або відхилення / завершення за тайм-аутом)
Gateway видає system events (`Exec finished` / `Exec denied`). Якщо команда все ще
виконується після `tools.exec.approvalRunningNoticeMs`, видається одне сповіщення `Exec running`.
На каналах із власними картками/кнопками погодження агент має спочатку покладатися
саме на цей native UI й додавати ручну команду `/approve` лише тоді, коли результат
інструмента прямо каже, що погодження в чаті недоступні або ручне погодження є
єдиним шляхом.
Коли потрібні схвалення, інструмент exec негайно повертає
`status: "approval-pending"` та ідентифікатор схвалення. Після схвалення (або відхилення / завершення за часом очікування)
Gateway надсилає системні події (`Exec finished` / `Exec denied`). Якщо команда все ще
виконується після `tools.exec.approvalRunningNoticeMs`, надсилається одне сповіщення `Exec running`.
У каналах із нативними картками/кнопками схвалення агент повинен насамперед покладатися на цей
нативний UI і включати ручну команду `/approve` лише тоді, коли в результаті інструмента
явно зазначено, що схвалення через чат недоступні, або ручне схвалення —
єдиний шлях.
## Allowlist + safe bins
Ручне застосування allowlist зіставляється **лише з перетвореними шляхами до бінарних файлів** (без зіставлення за basename). Коли
`security=allowlist`, shell-команди автоматично дозволяються лише тоді, коли кожен сегмент pipeline є
в allowlist або є safe bin. Ланцюжки (`;`, `&&`, `||`) і редиректи відхиляються в
режимі allowlist, якщо тільки кожен сегмент верхнього рівня не відповідає allowlist (включно з safe bins).
Редиректи все ще не підтримуються.
Довготривала довіра `allow-always` не обходить це правило: ланцюжкова команда все одно потребує, щоб кожен
сегмент верхнього рівня відповідав.
Ручне застосування allowlist зіставляє **лише визначені шляхи до бінарних файлів** (без зіставлення за самими базовими назвами). Коли
`security=allowlist`, shell-команди автоматично дозволяються лише тоді, коли кожен сегмент конвеєра
є в allowlist або є safe bin. Ланцюжки (`;`, `&&`, `||`) і перенаправлення відхиляються в
режимі allowlist, якщо кожен сегмент верхнього рівня не задовольняє allowlist (зокрема safe bins).
Перенаправлення, як і раніше, не підтримуються.
Тривала довіра `allow-always` не обходить це правило: ланцюгова команда все одно вимагає, щоб кожен
сегмент верхнього рівня збігався.
`autoAllowSkills` — це окремий зручний шлях у погодженнях exec. Це не те саме, що
ручні записи шляхів в allowlist. Для суворої явної довіри тримайте `autoAllowSkills` вимкненим.
`autoAllowSkills` — це окремий зручний шлях у схваленнях exec. Це не те саме, що
ручні записи шляху в allowlist. Для суворої явної довіри тримайте
`autoAllowSkills` вимкненим.
Використовуйте ці два механізми для різних завдань:
Використовуйте два елементи керування для різних завдань:
- `tools.exec.safeBins`: малі stream-фільтри лише для stdin.
- `tools.exec.safeBinTrustedDirs`: явні додаткові надійні каталоги для шляхів виконуваних файлів safe bin.
- `tools.exec.safeBinProfiles`: явна policy argv для власних safe bin.
- `tools.exec.safeBins`: невеликі потокові фільтри лише для stdin.
- `tools.exec.safeBinTrustedDirs`: явні додаткові довірені каталоги для шляхів виконуваних файлів safe bin.
- `tools.exec.safeBinProfiles`: явна політика argv для користувацьких safe bin.
- allowlist: явна довіра до шляхів виконуваних файлів.
Не використовуйте `safeBins` як загальний allowlist і не додавайте бінарні файли інтерпретаторів/runtime (наприклад `python3`, `node`, `ruby`, `bash`). Якщо вони вам потрібні, використовуйте явні записи allowlist і залишайте ввімкненими запити погодження.
`openclaw security audit` попереджає, коли записи `safeBins` для інтерпретаторів/runtime не мають явних профілів, а `openclaw doctor --fix` може згенерувати відсутні записи `safeBinProfiles`.
`openclaw security audit` і `openclaw doctor` також попереджають, коли ви явно додаєте назад у `safeBins` бінарні файли з широкою поведінкою, такі як `jq`.
Якщо ви явно додаєте інтерпретатори в allowlist, увімкніть `tools.exec.strictInlineEval`, щоб форми inline code-eval усе одно вимагали нового погодження.
Не розглядайте `safeBins` як загальний allowlist і не додавайте туди бінарні файли інтерпретаторів/середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`). Якщо вони вам потрібні, використовуйте явні записи allowlist і залишайте запити на схвалення ввімкненими.
`openclaw security audit` попереджає, коли для записів інтерпретаторів/середовищ виконання в `safeBins` бракує явних профілів, а `openclaw doctor --fix` може згенерувати відсутні користувацькі записи `safeBinProfiles`.
`openclaw security audit` і `openclaw doctor` також попереджають, коли ви явно додаєте назад у `safeBins` бінарні файли з широкою поведінкою, як-от `jq`.
Якщо ви явно додаєте інтерпретатори в allowlist, увімкніть `tools.exec.strictInlineEval`, щоб форми inline code-eval усе одно щоразу вимагали нового схвалення.
Повні подробиці policy й приклади див. в [Погодженнях Exec](/uk/tools/exec-approvals#safe-bins-stdin-only) і [Safe bins versus allowlist](/uk/tools/exec-approvals#safe-bins-versus-allowlist).
Повні відомості про політику та приклади див. у [Схвалення exec](/uk/tools/exec-approvals-advanced#safe-bins-stdin-only) і [Safe bins versus allowlist](/uk/tools/exec-approvals-advanced#safe-bins-versus-allowlist).
## Приклади
Foreground:
Передній план:
```json
{ "tool": "exec", "command": "ls -la" }
```
Background + poll:
Фоновий режим + опитування:
```json
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
```
Polling призначене для статусу на вимогу, а не для циклів очікування. Якщо автоматичне пробудження
після завершення ввімкнене, команда може пробудити сесію, коли виведе щось або завершиться помилкою.
Опитування призначене для перевірки стану на вимогу, а не для циклів очікування. Якщо автоматичне пробудження
після завершення ввімкнено, команда може пробудити сесію, коли виведе результат або завершиться з помилкою.
Надсилання клавіш (у стилі tmux):
Надсилання натискань клавіш (у стилі tmux):
```json
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
@ -233,23 +234,23 @@ Polling призначене для статусу на вимогу, а не д
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
```
Надіслати (лише CR):
Надсилання (лише CR):
```json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```
Вставити (типово з bracketed paste):
Вставлення (типово в дужках):
```json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```
## `apply_patch`
## apply_patch
`apply_patch` — це підінструмент `exec` для структурованих багатофайлових редагувань.
Він типово ввімкнений для моделей OpenAI і OpenAI Codex. Використовуйте config лише
тоді, коли хочете вимкнути його або обмежити певними моделями:
Він типово ввімкнений для моделей OpenAI і OpenAI Codex. Використовуйте конфігурацію лише
тоді, коли хочете вимкнути його або обмежити конкретними моделями:
```json5
{
@ -264,14 +265,14 @@ Polling призначене для статусу на вимогу, а не д
Примітки:
- Доступний лише для моделей OpenAI/OpenAI Codex.
- Tool policy усе одно застосовується; `allow: ["write"]` неявно дозволяє `apply_patch`.
- Config розташований у `tools.exec.applyPatch`.
- `tools.exec.applyPatch.enabled` типово дорівнює `true`; установіть `false`, щоб вимкнути інструмент для моделей OpenAI.
- `tools.exec.applyPatch.workspaceOnly` типово дорівнює `true` (обмеження workspace). Установлюйте `false` лише тоді, коли ви свідомо хочете, щоб `apply_patch` записував/видаляв файли поза каталогом workspace.
- Політика інструментів усе одно застосовується; `allow: ["write"]` неявно дозволяє `apply_patch`.
- Конфігурація розташована в `tools.exec.applyPatch`.
- `tools.exec.applyPatch.enabled` типово має значення `true`; установіть `false`, щоб вимкнути інструмент для моделей OpenAI.
- `tools.exec.applyPatch.workspaceOnly` типово має значення `true` (обмежено межами робочого простору). Установлюйте `false` лише тоді, коли свідомо хочете, щоб `apply_patch` записував/видаляв файли поза каталогом робочого простору.
## Пов’язане
- [Погодження Exec](/uk/tools/exec-approvals) — бар’єри погодження для shell-команд
- [Sandboxing](/uk/gateway/sandboxing) — запуск команд у sandboxed-середовищах
- [Background Process](/uk/gateway/background-process) — довготривалий exec та інструмент process
- [Безпека](/uk/gateway/security) — tool policy та elevated access
- [Схвалення exec](/uk/tools/exec-approvals) — шлюзи схвалення для shell-команд
- [Sandboxing](/uk/gateway/sandboxing) — запуск команд у середовищах sandbox
- [Фоновий процес](/uk/gateway/background-process) — довготривалий exec та інструмент process
- [Безпека](/uk/gateway/security) — політика інструментів і підвищений доступ

196
docs/uk/tools/image-generation.md
View File

@ -2,14 +2,14 @@
read_when:
- Генерація зображень через агента
- Налаштування провайдерів і моделей для генерації зображень
- Розуміння параметрів інструмента image_generate
summary: Генерація та редагування зображень за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)
- Розуміння параметрів інструмента `image_generate`
summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)
title: Генерація зображень
x-i18n:
generated_at: "2026-04-23T23:07:48Z"
generated_at: "2026-04-23T23:28:27Z"
model: gpt-5.4
provider: openai
source_hash: 820829a009d48ccb23fbd9ee256bae27f6d7d9539fd75c2b0a7cef4b91c5c873
source_hash: 81d06d2be0d347be2aec54b02037c85fa4dcf71ccbc3c1b5d0aacac0b58892da
source_path: tools/image-generation.md
workflow: 15
---
@ -17,13 +17,13 @@ x-i18n:
Інструмент `image_generate` дає агенту змогу створювати й редагувати зображення за допомогою налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
<Note>
Інструмент з’являється лише тоді, коли доступний щонайменше один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API key провайдера або увійдіть через OpenAI Codex OAuth.
Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів свого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth.
</Note>
## Швидкий старт
1. Задайте API key щонайменше для одного провайдера (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth.
2. Необов’язково задайте бажану модель:
1. Задайте API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth.
2. За потреби задайте бажану модель:
```json5
{
@ -37,29 +37,25 @@ x-i18n:
}
```
Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли
налаштовано OAuth-профіль `openai-codex`, OpenClaw маршрутизує запити на зображення
через цей самий OAuth-профіль замість того, щоб спочатку намагатися використати `OPENAI_API_KEY`.
Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API key або
користувацький/Azure base URL, повертає використання прямого маршруту OpenAI Images API.
Codex OAuth використовує той самий ref моделі `openai/gpt-image-2`. Коли налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на зображення через цей самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`. Явна власна конфігурація зображень `models.providers.openai`, наприклад API-ключ або custom/Azure base URL, знову перемикає маршрут на прямий OpenAI Images API.
3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_
3. Попросіть агента: _«Згенеруй зображення дружнього маскота-робота.»_
Агент автоматично викликає `image_generate`. Додавання до allowlist інструментів не потрібне — він типово ввімкнений, коли доступний провайдер.
Агент автоматично викликає `image_generate`. Додавати інструмент до allow-list не потрібно — він увімкнений за замовчуванням, коли доступний провайдер.
## Підтримувані провайдери
| Провайдер | Типова модель | Підтримка редагування | Auth |
| --------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
| MiniMax | `image-01` | Так (reference об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
| ComfyUI | `workflow` | Так (1 зображення, визначене workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud |
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація |
| --------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------ |
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
| MiniMax | `image-01` | Так (reference зображення об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
| ComfyUI | `workflow` | Так (1 зображення, визначається workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари |
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
Використовуйте `action: "list"`, щоб переглянути доступні провайдери й моделі під час runtime:
Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання:
```
/tool image_generate action=list
@ -68,11 +64,11 @@ Codex OAuth використовує те саме посилання на мо
## Параметри інструмента
<ParamField path="prompt" type="string" required>
Prompt для генерації зображення. Обов’язковий для `action: "generate"`.
Prompt генерації зображення. Обов’язковий для `action: "generate"`.
</ParamField>
<ParamField path="action" type="'generate' | 'list'" default="generate">
Використовуйте `"list"`, щоб переглянути доступні провайдери й моделі під час runtime.
Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання.
</ParamField>
<ParamField path="model" type="string">
@ -88,28 +84,44 @@ Prompt для генерації зображення. Обов’язковий
</ParamField>
<ParamField path="size" type="string">
Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
</ParamField>
<ParamField path="aspectRatio" type="string">
Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
</ParamField>
<ParamField path="resolution" type="'1K' | '2K' | '4K'">
Підказка щодо роздільної здатності.
Підказка роздільної здатності.
</ParamField>
<ParamField path="quality" type="'low' | 'medium' | 'high' | 'auto'">
Підказка якості, якщо провайдер це підтримує.
</ParamField>
<ParamField path="outputFormat" type="'png' | 'jpeg' | 'webp'">
Підказка формату виводу, якщо провайдер це підтримує.
</ParamField>
<ParamField path="count" type="number">
Кількість зображень для генерації (1–4).
</ParamField>
<ParamField path="filename" type="string">
Підказка щодо імені вихідного файла.
<ParamField path="timeoutMs" type="number">
Необов’язковий тайм-аут запиту до провайдера в мілісекундах.
</ParamField>
Не всі провайдери підтримують усі параметри. Коли fallback-провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує його на найближчий підтримуваний розмір, aspect ratio або роздільну здатність. Справді непідтримувані перевизначення все одно зазначаються в результаті інструмента.
<ParamField path="filename" type="string">
Підказка імені вихідного файлу.
</ParamField>
Результати інструмента повідомляють про застосовані параметри. Коли OpenClaw виконує переналаштування геометрії під час fallback провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
<ParamField path="openai" type="object">
Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`.
</ParamField>
Не всі провайдери підтримують усі параметри. Коли fallback-провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує запит до найближчого підтримуваного розміру, співвідношення сторін або роздільної здатності. Непідтримувані підказки виводу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не декларують підтримку, і зазначаються в результаті інструмента.
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час fallback провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
## Конфігурація
@ -128,125 +140,121 @@ Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `
}
```
### Порядок вибору провайдера
### Порядок вибору провайдерів
Під час генерації зображення OpenClaw пробує провайдерів у такому порядку:
1. **Параметр `model`** з виклику інструмента (якщо агент його задає)
2. **`imageGenerationModel.primary`** з config
3. **`imageGenerationModel.fallbacks`** за порядком
4. **Автовиявлення** — використовує лише типові значення провайдерів, підкріплені auth:
1. Параметр **`model`** з виклику інструмента (якщо агент його вказує)
2. **`imageGenerationModel.primary`** з конфігурації
3. **`imageGenerationModel.fallbacks`** у заданому порядку
4. **Автовиявлення** — використовуються лише типові значення провайдерів, підкріплені автентифікацією:
- спочатку поточний типовий провайдер
- далі інші зареєстровані провайдери генерації зображень у порядку id провайдера
- далі решта зареєстрованих провайдерів генерації зображень у порядку provider-id
Якщо провайдер завершується помилкою (помилка auth, rate limit тощо), автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, помилка містить подробиці кожної спроби.
Якщо провайдер завершується помилкою (помилка автентифікації, rate limit тощо), автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, помилка містить подробиці кожної спроби.
Примітки:
- Автовиявлення враховує auth. Типове значення провайдера потрапляє до списку кандидатів
лише тоді, коли OpenClaw справді може автентифікувати цей провайдер.
- Автовиявлення типово ввімкнено. Задайте
`agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень
використовувала лише явні записи `model`, `primary` і `fallbacks`.
- Використовуйте `action: "list"`, щоб переглянути поточно зареєстровані провайдери, їхні
типові моделі та підказки щодо env vars для auth.
- Автовиявлення враховує стан автентифікації. Типовий провайдер потрапляє до списку кандидатів лише тоді, коли OpenClaw дійсно може автентифікувати цього провайдера.
- Автовиявлення увімкнене за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`.
- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні типові моделі та підказки щодо env vars для автентифікації.
### Редагування зображень
OpenAI, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування reference-зображень. Передайте шлях або URL reference-зображення:
```
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg"
```
OpenAI, Google і xAI підтримують до 5 reference-зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
### OpenAI `gpt-image-2`
Генерація зображень OpenAI типово використовує `openai/gpt-image-2`. Якщо налаштовано
OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-
профіль, який застосовується для chat-моделей підписки Codex, і надсилає запит на зображення
через backend Codex Responses; він не виконує тихого fallback до
`OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут OpenAI Images API,
явно налаштуйте `models.providers.openai` з API key, користувацьким base URL
або endpoint-ом Azure. Старішу
модель `openai/gpt-image-1` усе ще можна явно вибрати, але для нових запитів на генерацію
і редагування зображень OpenAI слід використовувати `gpt-image-2`.
Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, що й для моделей чату за підпискою Codex, і надсилає запит на зображення через бекенд Codex Responses; він не переходить непомітно на `OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, custom base URL або Azure endpoint. Старішу модель `openai/gpt-image-1` усе ще можна явно вибрати, але для нових запитів генерації та редагування зображень OpenAI слід використовувати `gpt-image-2`.
`gpt-image-2` підтримує як генерацію text-to-image, так і редагування
reference-зображень через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`,
`count`, `size` і reference-зображення. OpenAI не отримує
`aspectRatio` або `resolution` напряму; коли можливо, OpenClaw відображає їх у
підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення.
`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування reference-зображень через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat` і reference-зображення. OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли це можливо, OpenClaw перетворює їх у підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення.
Згенерувати одне 4K-зображення в альбомній орієнтації:
Параметри, специфічні для OpenAI, розміщені в об’єкті `openai`:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
```json
{
"quality": "low",
"outputFormat": "jpeg",
"openai": {
"background": "opaque",
"moderation": "low",
"outputCompression": 60,
"user": "end-user-42"
}
}
```
Згенерувати два квадратні зображення:
`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорий вивід вимагає `outputFormat` `png` або `webp`. `openai.outputCompression` застосовується до виводу JPEG/WebP.
Згенеруйте одне 4K-зображення в альбомній орієнтації:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Чистий редакційний постер для генерації зображень OpenClaw" size=3840x2160 count=1
```
Відредагувати одне локальне reference-зображення:
Згенеруйте два квадратні зображення:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Два візуальні напрями для іконки спокійного застосунку продуктивності" size=1024x1024 count=2
```
Відредагувати з кількома reference:
Відредагуйте одне локальне reference-зображення:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Збережи об’єкт, заміни тло на яскраву студійну сцену" image=/path/to/reference.png size=1024x1536
```
Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість
`api.openai.com`, див. [endpoint-и Azure OpenAI](/uk/providers/openai#azure-openai-endpoints)
у документації провайдера OpenAI.
Редагування з кількома reference-зображеннями:
Генерація зображень MiniMax доступна через обидва вбудовані шляхи auth MiniMax:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Поєднай образ персонажа з першого зображення з кольоровою палітрою другого" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
```
- `minimax/image-01` для конфігурацій з API key
- `minimax-portal/image-01` для конфігурацій з OAuth
Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. [endpoints Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) у документації провайдера OpenAI.
Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax:
- `minimax/image-01` для налаштувань з API-ключем
- `minimax-portal/image-01` для OAuth-налаштувань
## Можливості провайдерів
| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначені workflow виходи) | Так (1) | Так (до 4) |
| Редагування/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, reference об’єкта) | Так (1 зображення, визначене workflow) | Ні | Так (до 5 зображень) |
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виводи визначаються workflow) | Так (1) | Так (до 4) |
| Редагування/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, reference об’єкта) | Так (1 зображення, визначається workflow) | Ні | Так (до 5 зображень) |
| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні |
| Aspect ratio | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так |
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так |
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
### xAI `grok-imagine-image`
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з prompt
і `/v1/images/edits`, коли присутній `image` або `images`.
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`.
- Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
- Count: до 4
- Reference: один `image` або до п’яти `images`
- Aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
- Роздільна здатність: `1K`, `2K`
- Вихідні дані: повертаються як керовані OpenClaw вкладення зображень
- Кількість: до 4
- References: один `image` або до п’яти `images`
- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
- Роздільні здатності: `1K`, `2K`
- Вивід: повертається як вкладення зображень, якими керує OpenClaw
OpenClaw навмисно не відкриває специфічні для xAI `quality`, `mask`, `user` або
додаткові native-only aspect ratio, доки ці елементи керування не з’являться в спільному
міжпровайдерному контракті `image_generate`.
OpenClaw навмисно не відкриває нативні для xAI параметри `quality`, `mask`, `user` або додаткові нативні співвідношення сторін, доки ці елементи керування не з’являться в спільному міжпровайдерному контракті `image_generate`.
## Пов’язане
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
- [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal
- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та workflow Comfy Cloud
- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI і workflow Comfy Cloud
- [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini
- [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax
- [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images
- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду і TTS
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — config `imageGenerationModel`
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS
- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `imageGenerationModel`
- [Моделі](/uk/concepts/models) — конфігурація моделей і failover

236
docs/uk/tools/music-generation.md
View File

@ -1,38 +1,39 @@
---
read_when:
- Генерація музики або аудіо через агента
- Налаштування providers і моделей для генерації музики
- Генерування музики або аудіо через агента
- Налаштування провайдерів і моделей для генерування музики
- Розуміння параметрів інструмента music_generate
summary: Генерувати музику зі спільними providers, включно з plugins на основі workflow
title: Генерація музики
summary: Генерування музики зі спільними провайдерами, зокрема плагінами на основі workflow
title: Генерування музики
x-i18n:
generated_at: "2026-04-23T21:16:22Z"
generated_at: "2026-04-23T23:28:46Z"
model: gpt-5.4
provider: openai
source_hash: 5b03922bf032586f649e677d1d8c08250b1fd5dc95f1cdde050a058562feb3da
source_hash: 6010ee365e4b48b62eb20f3769aae4e409cb651fe7d5946b8c832f0fb120a1e4
source_path: tools/music-generation.md
workflow: 15
---
Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через
спільну можливість генерації музики з налаштованими providers, такими як Google,
спільну можливість генерування музики з налаштованими провайдерами, такими як Google,
MiniMax і ComfyUI, налаштований через workflow.
Для агентних сесій на основі спільних providers OpenClaw запускає генерацію музики як
фонове завдання, відстежує його в task ledger, а потім знову пробуджує агента, коли
трек готовий, щоб агент міг опублікувати готове аудіо назад у вихідний канал.
Для сесій агента на основі спільних провайдерів OpenClaw запускає генерування музики як
фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли
трек готовий, щоб агент міг опублікувати готове аудіо назад в
оригінальний канал.
<Note>
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один provider генерації музики. Якщо ви не бачите `music_generate` серед інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ provider.
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерування музики. Якщо ви не бачите `music_generate` в інструментах свого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ провайдера.
</Note>
## Швидкий старт
### Генерація на основі спільних providers
### Генерування на основі спільного провайдера
1. Задайте API-ключ принаймні для одного provider, наприклад `GEMINI_API_KEY` або
1. Задайте API-ключ щонайменше для одного провайдера, наприклад `GEMINI_API_KEY` або
`MINIMAX_API_KEY`.
2. За бажанням задайте бажану модель:
2. За потреби задайте бажану модель:
```json5
{
@ -46,122 +47,123 @@ MiniMax і ComfyUI, налаштований через workflow.
}
```
3. Попросіть агента: _"Generate an upbeat synthpop track about a night drive
through a neon city."_
3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку
неоновим містом."_
Агент автоматично викличе `music_generate`. Додавання в allow-list інструментів не потрібне.
Агент автоматично викликає `music_generate`. Додавання інструмента до allowlist не потрібне.
Для прямих синхронних контекстів без agent-run на основі сесії вбудований
інструмент усе одно повертається до inline-генерації та повертає фінальний шлях до media в
Для прямих синхронних контекстів без запуску агента з підтримкою сесії вбудований
інструмент усе одно переходить до вбудованого генерування та повертає фінальний шлях до медіафайлу в
результаті інструмента.
Приклади prompt:
Приклади запитів:
```text
Generate a cinematic piano track with soft strings and no vocals.
Згенеруй кінематографічний фортепіанний трек із м’якими струнними без вокалу.
```
```text
Generate an energetic chiptune loop about launching a rocket at sunrise.
Згенеруй енергійний chiptune-луп про запуск ракети на світанку.
```
### Генерація Comfy на основі workflow
### Генерування Comfy на основі workflow
Вбудований plugin `comfy` підключається до спільного інструмента `music_generate` через
registry provider генерації музики.
Вбудований Plugin `comfy` підключається до спільного інструмента `music_generate` через
реєстр провайдерів генерування музики.
1. Налаштуйте `models.providers.comfy.music` із JSON workflow та
вузлами prompt/output.
2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
3. Попросіть агента згенерувати музику або викличте інструмент напряму.
3. Попросіть агента створити музику або викличте інструмент безпосередньо.
Приклад:
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
/tool music_generate prompt="Теплий ambient synth loop із м’якою текстурою плівки"
```
## Підтримка вбудованих shared providers
## Підтримка вбудованих спільних провайдерів
| Provider | Типова модель | Опорні входи | Підтримувані елементи керування | API-ключ |
| -------- | --------------------- | ----------------- | ---------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | До 1 зображення | Музика або аудіо, визначені workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` |
| Провайдер | Типова модель | Еталонні входи | Підтримувані керувальні параметри | API-ключ |
| --------- | --------------------- | ---------------- | -------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | До 1 зображення | Визначені workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` |
### Матриця оголошених можливостей
Це явний контракт режимів, який використовують `music_generate`, contract tests
і shared live sweep.
Це явний контракт режимів, який використовують `music_generate`, контрактні тести
та спільний live sweep.
| Provider | `generate` | `edit` | Ліміт edit | Shared live lanes |
| -------- | ---------- | ------ | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | Так | Так | 1 зображення | Не входить до shared sweep; покривається в `extensions/comfy/comfy.live.test.ts` |
| Google | Так | Так | 10 зображень | `generate`, `edit` |
| MiniMax | Так | Ні | Немає | `generate` |
| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live lanes |
| --------- | ---------- | ------ | ----------------- | ------------------------------------------------------------------------- |
| ComfyUI | Так | Так | 1 зображення | Не входить до спільного sweep; покрито `extensions/comfy/comfy.live.test.ts` |
| Google | Так | Так | 10 зображень | `generate`, `edit` |
| MiniMax | Так | Ні | Немає | `generate` |
Використовуйте `action: "list"`, щоб переглянути доступні shared providers і моделі під час
виконання:
Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі під
час виконання:
```text
/tool music_generate action=list
```
Використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до поточної сесії:
Використовуйте `action: "status"`, щоб перевірити активне завдання генерування музики з підтримкою сесії:
```text
/tool music_generate action=status
```
Приклад прямої генерації:
Приклад прямого генерування:
```text
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true
/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та ніжним дощем" instrumental=true
```
## Параметри вбудованого інструмента
| Параметр | Тип | Опис |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------- |
| `prompt` | string | Prompt для генерації музики (обов’язковий для `action: "generate"`) |
| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії, або `"list"` для перегляду providers |
| `model` | string | Перевизначення provider/model, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` |
| `lyrics` | string | Необов’язковий текст пісні, якщо provider підтримує явний ввід lyrics |
| `instrumental` | boolean | Запросити лише інструментальний вивід, якщо provider це підтримує |
| `image` | string | Шлях або URL одного опорного зображення |
| `images` | string[] | Кілька опорних зображень (до 10) |
| `durationSeconds` | number | Бажана тривалість у секундах, якщо provider підтримує підказки тривалості |
| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо provider це підтримує |
| `filename` | string | Підказка для імені вихідного файла |
| Параметр | Тип | Опис |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt` | string | Запит для генерування музики (обов’язковий для `action: "generate"`) |
| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії або `"list"` для перегляду провайдерів |
| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` |
| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне передавання тексту |
| `instrumental` | boolean | Запитати лише інструментальний результат, якщо провайдер це підтримує |
| `image` | string | Шлях або URL одного еталонного зображення |
| `images` | string[] | Кілька еталонних зображень (до 10) |
| `durationSeconds`| number | Бажана тривалість у секундах, якщо провайдер підтримує підказки тривалості |
| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах |
| `format` | string | Підказка щодо вихідного формату (`mp3` або `wav`), якщо провайдер це підтримує |
| `filename` | string | Підказка щодо назви вихідного файла |
Не всі providers підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження,
такі як кількість входів, до надсилання. Коли provider підтримує тривалість, але
має коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує
Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження,
як-от кількість входів, до надсилання. Коли провайдер підтримує тривалість, але
використовує коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує
його до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки ігноруються
з попередженням, коли вибраний provider або модель не може їх виконати.
з попередженням, коли вибраний провайдер або модель не можуть їх застосувати.
Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw обмежує тривалість під час fallback provider, повернуте `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує перетворення від запитаного до застосованого.
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує тривалість під час fallback між провайдерами, повернене `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує зіставлення між запитаним і застосованим значенням.
## Асинхронна поведінка для шляху на основі shared providers
## Асинхронна поведінка для шляху на основі спільного провайдера
- Agent-run на основі сесії: `music_generate` створює фонове завдання, негайно повертає started/task response, а готовий трек публікує пізніше в follow-up повідомленні агента.
- Запобігання дублюванню: поки фонове завдання в тій самій сесії ще має стан `queued` або `running`, подальші виклики `music_generate` повертають статус завдання замість запуску нової генерації.
- Перевірка статусу: використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до поточної сесії, не запускаючи нову генерацію.
- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб переглядати статус queued, running і terminal для генерації.
- Пробудження після завершення: OpenClaw ін’єктує внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати follow-up для користувача.
- Підказка в prompt: подальші user/manual turns у тій самій сесії отримують невелику runtime-підказку, коли завдання генерації музики вже виконується, щоб модель не викликала `music_generate` повторно всліпу.
- Резервний варіант без сесії: прямі/локальні контексти без реальної agent-сесії все одно виконуються inline і повертають фінальний результат аудіо в тому самому turn.
- Запуски агента з підтримкою сесії: `music_generate` створює фонове завдання, негайно повертає відповідь started/task і пізніше публікує готовий трек у наступному повідомленні агента.
- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають стан завдання замість запуску нового генерування.
- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерування музики з підтримкою сесії без запуску нового.
- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб переглядати стани queued, running і terminal для генерування.
- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати користувацьке наступне повідомлення.
- Підказка в prompt: наступні користувацькі/ручні ходи в тій самій сесії отримують невелику підказку під час виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` повторно всліпу.
- Fallback без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються вбудовано та повертають фінальний результат аудіо в тому самому ході.
### Життєвий цикл завдання
Кожен запит `music_generate` проходить через чотири стани:
1. **queued** -- завдання створено, воно чекає, поки provider прийме його.
2. **running** -- provider обробляє його (зазвичай від 30 секунд до 3 хвилин, залежно від provider і тривалості).
3. **succeeded** -- трек готовий; агент пробуджується і публікує його в розмову.
4. **failed** -- помилка provider або timeout; агент пробуджується з деталями помилки.
1. **queued** -- завдання створено, очікує, поки провайдер його прийме.
2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера та тривалості).
3. **succeeded** -- трек готовий; агент пробуджується та публікує його в розмову.
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки.
Перевірка статусу з CLI:
Перевірка стану з CLI:
```bash
openclaw tasks list
@ -169,7 +171,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
Запобігання дублюванню: якщо для поточної сесії завдання музики вже має стан `queued` або `running`, `music_generate` повертає статус наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити це без запуску нової генерації.
Запобігання дублюванню: якщо для поточної сесії вже є музичне завдання у стані `queued` або `running`, `music_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нового генерування.
## Конфігурація
@ -188,41 +190,41 @@ openclaw tasks cancel <taskId>
}
```
### Порядок вибору provider
### Порядок вибору провайдера
Під час генерації музики OpenClaw пробує providers у такому порядку:
Під час генерування музики OpenClaw намагається використовувати провайдерів у такому порядку:
1. параметр `model` із виклику інструмента, якщо агент його вказує
2. `musicGenerationModel.primary` з config
3. `musicGenerationModel.fallbacks` у заданому порядку
4. Автовизначення, використовуючи лише типові значення providers, підкріплені auth:
- спочатку поточний типовий provider
- далі решта зареєстрованих providers генерації музики в порядку provider-id
1. параметр `model` із виклику інструмента, якщо агент його задає
2. `musicGenerationModel.primary` із конфігурації
3. `musicGenerationModel.fallbacks` по черзі
4. автовизначення з використанням лише типових значень провайдера на основі auth:
- спочатку поточний типовий провайдер
- потім інші зареєстровані провайдери генерування музики в порядку ідентифікаторів провайдерів
Якщо provider не спрацьовує, автоматично пробується наступний кандидат. Якщо не спрацьовують усі, помилка
містить подробиці кожної спроби.
Якщо провайдер завершується з помилкою, автоматично пробується наступний кандидат. Якщо всі завершуються помилкою,
помилка містить деталі кожної спроби.
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете,
щоб генерація музики використовувала лише явні записи `model`, `primary` і `fallbacks`.
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо ви хочете,
щоб генерування музики використовувало лише явні записи `model`, `primary` і `fallbacks`.
## Примітки щодо providers
## Примітки щодо провайдерів
- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
prompt, необов’язковий текст lyrics і необов’язкові опорні зображення.
- MiniMax використовує пакетний ендпоінт `music_generation`. Поточний вбудований потік
підтримує prompt, необов’язкові lyrics, instrumental mode, керування тривалістю і
вивід у mp3.
- Google використовує пакетне генерування Lyria 3. Поточний вбудований потік підтримує
prompt, необов’язковий текст lyrics і необов’язкові еталонні зображення.
- MiniMax використовує пакетний ендпойнт `music_generation`. Поточний вбудований потік
підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та
вихід у форматі mp3.
- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та
зіставлення вузлів для полів prompt/output.
## Режими можливостей provider
## Режими можливостей провайдерів
Спільний контракт генерації музики тепер підтримує явні оголошення режимів:
Контракт спільного генерування музики тепер підтримує явні оголошення режимів:
- `generate` для генерації лише за prompt
- `edit`, коли запит містить одне або кілька опорних зображень
- `generate` для генерування лише за prompt
- `edit`, коли запит містить одне або більше еталонних зображень
Нові реалізації providers повинні надавати перевагу явним блокам режимів:
Нові реалізації провайдерів мають надавати перевагу явним блокам режимів:
```typescript
capabilities: {
@ -240,20 +242,20 @@ capabilities: {
}
```
Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і
`supportsFormat`, недостатньо, щоб оголосити підтримку edit. Providers повинні
явно оголошувати `generate` і `edit`, щоб live tests, contract tests і
Застарілих плоских полів, як-от `maxInputImages`, `supportsLyrics` і
`supportsFormat`, недостатньо, щоб оголосити підтримку редагування. Провайдери повинні
явно оголошувати `generate` і `edit`, щоб live-тести, контрактні тести та
спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів.
## Вибір правильного шляху
- Використовуйте шлях на основі shared providers, коли вам потрібні вибір моделі, failover provider і вбудований асинхронний потік task/status.
- Використовуйте шлях plugin, наприклад ComfyUI, коли вам потрібен власний граф workflow або provider, який не входить до shared bundled capability генерації музики.
- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку shared providers, почніть з [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax).
- Використовуйте шлях на основі спільного провайдера, коли вам потрібні вибір моделі, fallback між провайдерами та вбудований асинхронний потік завдання/стану.
- Використовуйте шлях через Plugin, такий як ComfyUI, коли вам потрібен користувацький граф workflow або провайдер, який не входить до спільної вбудованої можливості генерування музики.
- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax).
## Live tests
## Live-тести
Opt-in live-покриття для shared bundled providers:
Покриття live-тестами за згодою для спільних вбудованих провайдерів:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -265,31 +267,31 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
pnpm test:live:media music
```
Цей live-файл завантажує відсутні env vars provider з `~/.profile`, типово надає
перевагу live/env API-ключам над збереженими auth profiles і запускає покриття
і для `generate`, і для оголошеного `edit`, коли provider вмикає режим edit.
Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово віддає
перевагу live/env API-ключам перед збереженими профілями auth і запускає покриття
і для `generate`, і для оголошеного `edit`, коли провайдер вмикає режим редагування.
Сьогодні це означає:
Наразі це означає:
- `google`: `generate` плюс `edit`
- `minimax`: лише `generate`
- `comfy`: окреме live-покриття Comfy, не shared provider sweep
- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів
Opt-in live-покриття для bundled-шляху музики ComfyUI:
Покриття live-тестами за згодою для вбудованого музичного шляху ComfyUI:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Live-файл Comfy також покриває workflows зображень і відео comfy, коли ці
Файл live-тестів Comfy також охоплює workflow для зображень і відео Comfy, коли ці
розділи налаштовані.
## Пов’язане
- [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate`
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - config `musicGenerationModel`
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - конфігурація `musicGenerationModel`
- [ComfyUI](/uk/providers/comfy)
- [Google (Gemini)](/uk/providers/google)
- [MiniMax](/uk/providers/minimax)
- [Models](/uk/concepts/models) - конфігурація моделей і failover
- [Огляд Tools](/uk/tools)
- [Моделі](/uk/concepts/models) - конфігурація моделей і fallback
- [Огляд інструментів](/uk/tools)

226
docs/uk/tools/tts.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Увімкнення text-to-speech для відповідей
- Налаштування провайдерів або обмежень TTS
- Налаштування provider TTS або обмежень
- Використання команд /tts
summary: Text-to-speech (TTS) для вихідних відповідей
title: Text-to-speech
x-i18n:
generated_at: "2026-04-23T23:08:56Z"
generated_at: "2026-04-23T23:28:55Z"
model: gpt-5.4
provider: openai
source_hash: ba760f48e203a090ddc8f18198439541de8886422fca07edb94a46295684da02
source_hash: 935fec2325a08da6f4ecd8ba5a9b889cd265025c5c7ee43bc4e0da36c1003d8f
source_path: tools/tts.md
workflow: 15
---
@ -19,24 +19,24 @@ OpenClaw може перетворювати вихідні відповіді
## Підтримувані сервіси
- **ElevenLabs** (основний або резервний провайдер)
- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS)
- **Microsoft** (основний або резервний провайдер; поточна bundled-реалізація використовує `node-edge-tts`)
- **MiniMax** (основний або резервний провайдер; використовує T2A v2 API)
- **OpenAI** (основний або резервний провайдер; також використовується для зведень)
- **xAI** (основний або резервний провайдер; використовує xAI TTS API)
- **ElevenLabs** (основний або резервний provider)
- **Google Gemini** (основний або резервний provider; використовує Gemini API TTS)
- **Microsoft** (основний або резервний provider; поточна вбудована реалізація використовує `node-edge-tts`)
- **MiniMax** (основний або резервний provider; використовує API T2A v2)
- **OpenAI** (основний або резервний provider; також використовується для підсумків)
- **xAI** (основний або резервний provider; використовує xAI TTS API)
### Примітки щодо Microsoft speech
Bundled-провайдер Microsoft speech наразі використовує онлайн-сервіс
нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це розміщений сервіс (не
локальний), використовує endpoint Microsoft і не потребує API key.
Поточний вбудований provider Microsoft speech зараз використовує онлайн-сервіс
нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостинговий сервіс (не
локальний), використовує ендпоінти Microsoft і не потребує API-ключа.
`node-edge-tts` надає параметри конфігурації мовлення та формати виводу, але
не всі параметри підтримуються сервісом. Застаріла конфігурація і вхідні директиви,
що використовують `edge`, і далі працюють і нормалізуються до `microsoft`.
сервіс підтримує не всі параметри. Старі конфігурації та вхідні директиви
з використанням `edge` усе ще працюють і нормалізуються до `microsoft`.
Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квоти,
ставтеся до нього як до best-effort. Якщо вам потрібні гарантовані ліміти й підтримка, використовуйте OpenAI
Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квот,
сприймайте його як best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI
або ElevenLabs.
## Необов’язкові ключі
@ -49,15 +49,15 @@ Bundled-провайдер Microsoft speech наразі використову
- `OPENAI_API_KEY`
- `XAI_API_KEY`
Microsoft speech **не** потребує API key.
Microsoft speech **не** потребує API-ключа.
Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші є резервними варіантами.
Автоматичне зведення використовує налаштований `summaryModel` (або `agents.defaults.model.primary`),
тому якщо ви вмикаєте зведення, цей провайдер також має бути автентифікований.
Якщо налаштовано кілька provider, спочатку використовується вибраний provider, а інші стають резервними варіантами.
Автоматичне створення підсумків використовує налаштований `summaryModel` (або `agents.defaults.model.primary`),
тому якщо ви вмикаєте підсумки, цей provider також має бути автентифікований.
## Посилання на сервіси
- [Посібник OpenAI з Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech)
- [Посібник OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech)
- [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio)
- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)
@ -66,20 +66,20 @@ Microsoft speech **не** потребує API key.
- [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
## Чи ввімкнено це за замовчуванням?
## Чи ввімкнено це типово?
Ні. Автоматичний TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через
`messages.tts.auto` або локально через `/tts on`.
Ні. Автоматичний TTS типово **вимкнений**. Увімкніть його в конфігурації через
`messages.tts.auto` або локально за допомогою `/tts on`.
Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований
speech-провайдер у порядку автоматичного вибору реєстру.
speech provider у порядку автоматичного вибору реєстру.
## Конфігурація
Конфігурація TTS розміщується в `messages.tts` у `openclaw.json`.
Конфігурація TTS знаходиться в `messages.tts` у `openclaw.json`.
Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration).
### Мінімальна конфігурація (увімкнення + провайдер)
### Мінімальна конфігурація (увімкнення + provider)
```json5
{
@ -92,7 +92,7 @@ speech-провайдер у порядку автоматичного вибо
}
```
### OpenAI як основний з резервним переходом на ElevenLabs
### Основний OpenAI з резервним ElevenLabs
```json5
{
@ -133,7 +133,7 @@ speech-провайдер у порядку автоматичного вибо
}
```
### Microsoft як основний (без API key)
### Основний Microsoft (без API-ключа)
```json5
{
@ -156,7 +156,7 @@ speech-провайдер у порядку автоматичного вибо
}
```
### MiniMax як основний
### Основний MiniMax
```json5
{
@ -180,7 +180,7 @@ speech-провайдер у порядку автоматичного вибо
}
```
### Google Gemini як основний
### Основний Google Gemini
```json5
{
@ -200,13 +200,13 @@ speech-провайдер у порядку автоматичного вибо
}
```
Google Gemini TTS використовує шлях API key Gemini. Ключ API Google Cloud Console,
обмежений Gemini API, тут є дійсним, і це той самий тип ключа, який використовує
bundled-провайдер генерації зображень Google. Порядок визначення:
Google Gemini TTS використовує шлях API-ключа Gemini. Тут також підходить API-ключ Google Cloud Console,
обмежений лише Gemini API, і це той самий тип ключа, який використовується
вбудованим provider генерації зображень Google. Порядок визначення:
`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` ->
`GEMINI_API_KEY` -> `GOOGLE_API_KEY`.
### xAI як основний
### Основний xAI
```json5
{
@ -228,12 +228,12 @@ bundled-провайдер генерації зображень Google. Пор
}
```
xAI TTS використовує той самий шлях `XAI_API_KEY`, що й bundled-провайдер моделей Grok.
xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований provider моделей Grok.
Порядок визначення: `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`.
Поточні live-голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типовим є `eve`.
Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типово використовується `eve`.
`language` приймає тег BCP-47 або `auto`.
### Вимкнути Microsoft speech
### Вимкнення Microsoft speech
```json5
{
@ -249,7 +249,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що
}
```
### Власні обмеження + шлях prefs
### Користувацькі обмеження + шлях до prefs
```json5
{
@ -276,7 +276,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що
}
```
### Вимкнути автоматичне зведення для довгих відповідей
### Вимкнення автоматичного підсумку для довгих відповідей
```json5
{
@ -299,70 +299,70 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що
- `auto`: режим автоматичного TTS (`off`, `always`, `inbound`, `tagged`).
- `inbound` надсилає аудіо лише після вхідного голосового повідомлення.
- `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:key=value]]` або блок `[[tts:text]]...[[/tts:text]]`.
- `enabled`: застарілий перемикач (doctor мігрує це до `auto`).
- `enabled`: застарілий перемикач (doctor мігрує його в `auto`).
- `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків).
- `provider`: id speech-провайдера, наприклад `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"` або `"openai"` (резервний перехід відбувається автоматично).
- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований speech-провайдер у порядку автоматичного вибору реєстру.
- Застаріле `provider: "edge"` і далі працює і нормалізується до `microsoft`.
- `summaryModel`: необов’язкова недорога модель для автоматичного зведення; типово `agents.defaults.model.primary`.
- `provider`: id speech provider, наприклад `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"` або `"openai"` (резервне перемикання відбувається автоматично).
- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований speech provider у порядку автоматичного вибору реєстру.
- Застаріле `provider: "edge"` усе ще працює і нормалізується до `microsoft`.
- `summaryModel`: необов’язкова недорога модель для автоматичного підсумку; типово використовується `agents.defaults.model.primary`.
- Приймає `provider/model` або налаштований псевдонім моделі.
- `modelOverrides`: дозволяє моделі видавати директиви TTS (типово ввімкнено).
- `allowProvider` типово дорівнює `false` (перемикання провайдера вимагає явного ввімкнення).
- `providers.<id>`: налаштування провайдера-власника, ключовані за id speech-провайдера.
- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються до `messages.tts.providers.<id>` під час завантаження.
- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо ліміт перевищено.
- `modelOverrides`: дозволяє моделі виводити директиви TTS (типово ввімкнено).
- `allowProvider` типово має значення `false` (перемикання provider вмикається явно).
- `providers.<id>`: параметри, що належать provider, з ключем за id speech provider.
- Застарілі прямі блоки provider (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються в `messages.tts.providers.<id>` під час завантаження.
- `maxTextLength`: жорстке обмеження для вхідного TTS-тексту (символи). Якщо його перевищено, `/tts audio` завершується помилкою.
- `timeoutMs`: тайм-аут запиту (мс).
- `prefsPath`: перевизначає шлях до локального JSON prefs (provider/limit/summary).
- Значення `apiKey` переходять до env-змінних (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`).
- `prefsPath`: перевизначає локальний шлях до JSON-файла prefs (provider/limit/summary).
- Значення `apiKey` можуть братися з env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`).
- `providers.elevenlabs.baseUrl`: перевизначає базовий URL API ElevenLabs.
- `providers.openai.baseUrl`: перевизначає endpoint OpenAI TTS.
- `providers.openai.baseUrl`: перевизначає ендпоінт OpenAI TTS.
- Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`
- Нетипові значення обробляються як OpenAI-сумісні TTS endpoint, тому приймаються власні назви моделей і голосів.
- Нестандартні значення розглядаються як OpenAI-сумісні TTS-ендпоінти, тому допускаються користувацькі назви моделей і голосів.
- `providers.elevenlabs.voiceSettings`:
- `stability`, `similarityBoost`, `style`: `0..1`
- `useSpeakerBoost`: `true|false`
- `speed`: `0.5..2.0` (1.0 = нормальна)
- `speed`: `0.5..2.0` (1.0 = звичайна швидкість)
- `providers.elevenlabs.applyTextNormalization`: `auto|on|off`
- `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`)
- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінізм)
- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінованість)
- `providers.minimax.baseUrl`: перевизначає базовий URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`).
- `providers.minimax.model`: TTS-модель (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`).
- `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`).
- `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`).
- `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0).
- `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0).
- `providers.minimax.pitch`: зсув тону `-12..12` (типово 0).
- `providers.google.model`: TTS-модель Gemini (типово `gemini-3.1-flash-tts-preview`).
- `providers.minimax.pitch`: зсув висоти тону `-12..12` (типово 0).
- `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`).
- `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`).
- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Приймається лише `https://generativelanguage.googleapis.com`.
- Якщо `messages.tts.providers.google.apiKey` не вказано, TTS може повторно використати `models.providers.google.apiKey` перед переходом до env.
- `providers.xai.apiKey`: API key xAI TTS (env: `XAI_API_KEY`).
- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Допускається лише `https://generativelanguage.googleapis.com`.
- Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використати `models.providers.google.apiKey` до переходу на env fallback.
- `providers.xai.apiKey`: API-ключ xAI TTS (env: `XAI_API_KEY`).
- `providers.xai.baseUrl`: перевизначає базовий URL xAI TTS (типово `https://api.x.ai/v1`, env: `XAI_BASE_URL`).
- `providers.xai.voiceId`: id голосу xAI (типово `eve`; поточні live-голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`).
- `providers.xai.voiceId`: id голосу xAI (типово `eve`; поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`).
- `providers.xai.language`: код мови BCP-47 або `auto` (типово `en`).
- `providers.xai.responseFormat`: `mp3`, `wav`, `pcm`, `mulaw` або `alaw` (типово `mp3`).
- `providers.xai.speed`: нативне перевизначення швидкості провайдера.
- `providers.microsoft.enabled`: дозволити використання Microsoft speech (типово `true`; без API key).
- `providers.xai.speed`: перевизначення швидкості, специфічне для provider.
- `providers.microsoft.enabled`: дозволити використання Microsoft speech (типово `true`; API-ключ не потрібен).
- `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`).
- `providers.microsoft.lang`: код мови (наприклад, `en-US`).
- `providers.microsoft.outputFormat`: формат виводу Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`).
- Див. формати виводу Microsoft Speech для коректних значень; не всі формати підтримуються bundled-транспортом на основі Edge.
- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки відсотків (наприклад, `+10%`, `-5%`).
- `providers.microsoft.saveSubtitles`: записувати JSON-субтитри поряд з аудіофайлом.
- `providers.microsoft.proxy`: proxy URL для запитів Microsoft speech.
- Допустимі значення див. у форматах виводу Microsoft Speech; не всі формати підтримуються вбудованим transport на основі Edge.
- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки з відсотками (наприклад, `+10%`, `-5%`).
- `providers.microsoft.saveSubtitles`: записувати JSON-субтитри поруч з аудіофайлом.
- `providers.microsoft.proxy`: URL проксі для запитів Microsoft speech.
- `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс).
- `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft.
## Перевизначення, керовані моделлю (типово ввімкнено)
За замовчуванням модель **може** видавати директиви TTS для однієї відповіді.
Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо.
Типово модель **може** виводити директиви TTS для однієї відповіді.
Коли `messages.tts.auto` має значення `tagged`, ці директиви є обов’язковими для запуску аудіо.
Коли це ввімкнено, модель може видавати директиви `[[tts:...]]`, щоб перевизначити голос
для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб
надати експресивні теги (сміх, підказки для співу тощо), які мають з’являтися
Коли це ввімкнено, модель може виводити директиви `[[tts:...]]`, щоб перевизначити голос
для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`,
щоб надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися
лише в аудіо.
Директиви `provider=...` ігноруються, якщо не задано `modelOverrides.allowProvider: true`.
Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`.
Приклад payload відповіді:
@ -375,12 +375,12 @@ Here you go.
Доступні ключі директив (коли ввімкнено):
- `provider` (id зареєстрованого speech-провайдера, наприклад `openai`, `elevenlabs`, `google`, `minimax` або `microsoft`; потребує `allowProvider: true`)
- `provider` (id зареєстрованого speech provider, наприклад `openai`, `elevenlabs`, `google`, `minimax` або `microsoft`; потребує `allowProvider: true`)
- `voice` (голос OpenAI), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / MiniMax / xAI)
- `model` (TTS-модель OpenAI, id моделі ElevenLabs або модель MiniMax) або `google_model` (TTS-модель Google)
- `model` (модель OpenAI TTS, id моделі ElevenLabs або модель MiniMax) або `google_model` (модель Google TTS)
- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
- `vol` / `volume` (гучність MiniMax, 0-10)
- `pitch` (тон MiniMax, від -12 до 12)
- `pitch` (висота тону MiniMax, від -12 до 12)
- `applyTextNormalization` (`auto|on|off`)
- `languageCode` (ISO 639-1)
- `seed`
@ -399,7 +399,7 @@ Here you go.
}
```
Необов’язковий allowlist (увімкнути перемикання провайдера, зберігаючи можливість налаштовувати інші параметри):
Необов’язковий allowlist (увімкнути перемикання provider, залишивши інші параметри налаштовуваними):
```json5
{
@ -417,15 +417,15 @@ Here you go.
## Налаштування для окремого користувача
Слеш-команди записують локальні перевизначення в `prefsPath` (типово:
`~/.openclaw/settings/tts.json`, перевизначається через `OPENCLAW_TTS_PREFS` або
Slash-команди записують локальні перевизначення в `prefsPath` (типово:
`~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або
`messages.tts.prefsPath`).
Поля, що зберігаються:
Збережені поля:
- `enabled`
- `provider`
- `maxLength` (поріг зведення; типово 1500 символів)
- `maxLength` (поріг для підсумку; типово 1500 символів)
- `summarize` (типово `true`)
Вони перевизначають `messages.tts.*` для цього хоста.
@ -433,33 +433,33 @@ Here you go.
## Формати виводу (фіксовані)
- **Feishu / Matrix / Telegram / WhatsApp**: голосове повідомлення Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI).
- 48 кГц / 64 кбіт/с — хороший компроміс для голосового повідомлення.
- **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI).
- 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень.
- **Інші channel**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI).
- 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення.
- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц). Формат голосових нотаток нативно не підтримується; використовуйте OpenAI або ElevenLabs для гарантованих голосових повідомлень Opus.
- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/телефонії. Нативний формат голосових нотаток Opus цим шляхом не підтримується.
- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST TTS endpoint xAI і повертає готове аудіовкладення; потоковий WebSocket TTS xAI цим шляхом провайдера не використовується. Нативний формат голосових нотаток Opus цим шляхом не підтримується.
- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/telephony. Нативний формат голосових нотаток Opus цим шляхом не підтримується.
- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST-ендпоінт xAI TTS і повертає готове аудіовкладення; потоковий TTS WebSocket від xAI цим шляхом provider не використовується. Нативний формат голосових нотаток Opus цим шляхом не підтримується.
- **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`).
- Bundled-транспорт приймає `outputFormat`, але не всі формати доступні в сервісі.
- Значення форматів виводу відповідають форматам виводу Microsoft Speech (зокрема Ogg/WebM Opus).
- Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам
потрібні гарантовані голосові повідомлення Opus.
- Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3.
- Вбудований transport приймає `outputFormat`, але сервіс надає не всі формати.
- Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus).
- Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні
гарантовані голосові повідомлення Opus.
- Якщо налаштований формат виводу Microsoft не спрацьовує, OpenClaw повторює спробу з MP3.
Формати виводу OpenAI/ElevenLabs зафіксовані для кожного каналу (див. вище).
Формати виводу OpenAI/ElevenLabs фіксовані для кожного channel (див. вище).
## Поведінка автоматичного TTS
Коли функцію ввімкнено, OpenClaw:
Коли ввімкнено, OpenClaw:
- пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`.
- пропускає дуже короткі відповіді (< 10 символів).
- робить зведення довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`).
- створює підсумок довгих відповідей, якщо це ввімкнено, за допомогою `agents.defaults.model.primary` (або `summaryModel`).
- додає згенероване аудіо до відповіді.
Якщо відповідь перевищує `maxLength`, а зведення вимкнено (або немає API key для
моделі зведення), аудіо
пропускається й надсилається звичайна текстова відповідь.
Якщо відповідь перевищує `maxLength`, а підсумок вимкнено (або немає API-ключа для
моделі підсумку), аудіо
пропускається, і надсилається звичайна текстова відповідь.
## Схема потоку
@ -476,13 +476,13 @@ Reply -> TTS enabled?
-> TTS -> attach audio
```
## Використання слеш-команд
## Використання Slash-команди
Є одна команда: `/tts`.
Докладно про ввімкнення див. у [Слеш-команди](/uk/tools/slash-commands).
Докладніше про ввімкнення див. у [Slash-команди](/uk/tools/slash-commands).
Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє
`/voice` як нативну команду там. Текстова форма `/tts ...` і далі працює.
там `/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює.
```
/tts off
@ -496,24 +496,26 @@ Reply -> TTS enabled?
Примітки:
- Команди потребують авторизованого відправника (правила allowlist/owner і далі застосовуються).
- Команди вимагають авторизованого відправника (правила allowlist/owner усе ще застосовуються).
- Має бути ввімкнено `commands.text` або реєстрацію нативних команд.
- Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`.
- `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`.
- `/tts on` записує локальне налаштування TTS у `always`; `/tts off` записує його в `off`.
- Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`.
- `limit` і `summary` зберігаються в локальних prefs, а не в основній конфігурації.
- `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS назавжди).
- `/tts status` містить видимість резервного переходу для останньої спроби:
- успішний резервний перехід: `Fallback: <primary> -> <used>` плюс `Attempts: ...`
- збій: `Error: ...` плюс `Attempts: ...`
- `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS).
- `/tts status` включає видимість fallback для останньої спроби:
- успішний fallback: `Fallback: <primary> -> <used>` плюс `Attempts: ...`
- помилка: `Error: ...` плюс `Attempts: ...`
- докладна діагностика: `Attempt details: provider:outcome(reasonCode) latency`
- Збої API OpenAI і ElevenLabs тепер містять розібрані деталі помилки провайдера та id запиту (коли провайдер його повертає), які відображаються в помилках/журналах TTS.
- Збої API OpenAI та ElevenLabs тепер містять розібрані деталі помилки provider і request id (коли його повертає provider), які відображаються в помилках/логах TTS.
## Інструмент агента
Інструмент `tts` перетворює текст на мовлення і повертає аудіовкладення для
доставки у відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp,
аудіо доставляється як голосове повідомлення, а не як файлове вкладення.
Інструмент `tts` перетворює текст на мовлення та повертає аудіовкладення для
доставки у відповіді. Коли channel — це Feishu, Matrix, Telegram або WhatsApp,
аудіо доставляється як голосове повідомлення, а не як вкладення файлу.
Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це
тайм-аут запиту provider для кожного виклику в мілісекундах.
## Gateway RPC
@ -526,7 +528,7 @@ Reply -> TTS enabled?
- `tts.setProvider`
- `tts.providers`
## Пов’язане
## Пов’язані матеріали
- [Огляд медіа](/uk/tools/media-overview)
- [Генерація музики](/uk/tools/music-generation)

346
docs/uk/tools/video-generation.md
View File

@ -3,41 +3,41 @@ read_when:
- Генерація відео через агента
- Налаштування провайдерів і моделей генерації відео
- Розуміння параметрів інструмента `video_generate`
summary: Генеруйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів
summary: Створюйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів
title: Генерація відео
x-i18n:
generated_at: "2026-04-23T21:17:50Z"
generated_at: "2026-04-23T23:28:53Z"
model: gpt-5.4
provider: openai
source_hash: 67b3b0c669489dca7c0903dbd2ddd7b0f3438a3a722c5cb2b78850ecd1906866
source_hash: 4fb4053d417e62d6145f6cd2bc2717ae120ca9a7cff34089ba65d4ba79ec8c75
source_path: tools/video-generation.md
workflow: 15
---
Агенти OpenClaw можуть генерувати відео з текстових запитів, референсних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними параметрами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає правильного провайдера на основі вашої конфігурації та доступних API keys.
Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає потрібного провайдера на основі вашої конфігурації та доступних API-ключів.
<Note>
Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, установіть API key провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
</Note>
OpenClaw розглядає генерацію відео як три режими runtime:
OpenClaw розглядає генерацію відео як три режими виконання:
- `generate` для запитів text-to-video без референсних медіа
- `imageToVideo`, коли запит містить одне або кілька референсних зображень
- `videoToVideo`, коли запит містить одне або кілька референсних відео
- `generate` для запитів text-to-video без еталонних медіа
- `imageToVideo`, коли запит містить одне або кілька еталонних зображень
- `videoToVideo`, коли запит містить одне або кілька еталонних відео
Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний
режим перед надсиланням і повідомляє підтримувані режими в `action=list`.
## Швидкий старт
1. Установіть API key для будь-якого підтримуваного провайдера:
1. Установіть API-ключ для будь-якого підтримуваного провайдера:
```bash
export GEMINI_API_KEY="your-key"
```
2. За бажанням закріпіть типову модель:
2. За потреби зафіксуйте типову модель:
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
@ -45,31 +45,31 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
3. Попросіть агента:
> Generate a 5-second cinematic video of a friendly lobster surfing at sunset.
> Згенеруй 5-секундне кінематографічне відео з доброзичливим лобстером, який катається на серфі на заході сонця.
Агент автоматично викличе `video_generate`. Allowlist для інструментів не потрібен.
Агент автоматично викличе `video_generate`. Дозвіл через список дозволеного для інструмента не потрібен.
## Що відбувається, коли ви генеруєте відео
Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії:
Генерація відео є асинхронною. Коли агент викликає `video_generate` у межах сеансу:
1. OpenClaw надсилає запит провайдеру і одразу повертає ID задачі.
2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності).
3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення.
1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання.
2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності).
3. Коли відео готове, OpenClaw пробуджує той самий сеанс внутрішньою подією завершення.
4. Агент публікує готове відео назад у вихідну розмову.
Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан задачі замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб перевіряти прогрес через CLI.
Поки завдання виконується, повторні виклики `video_generate` у тому самому сеансі повертають поточний стан завдання замість запуску ще однієї генерації. Щоб перевірити поступ через CLI, використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`.
Поза запусками агента, прив’язаними до сесії (наприклад, у разі прямих викликів інструмента), інструмент використовує запасний варіант — inline-генерацію — і повертає фінальний шлях до медіа в тому самому ході.
Поза сеансами, пов’язаними із запуском агента (наприклад, для прямих викликів інструмента), інструмент переходить до inline-генерації й повертає фінальний шлях до медіафайла в тому самому ході.
### Життєвий цикл задачі
### Життєвий цикл завдання
Кожен запит `video_generate` проходить через чотири стани:
1. **queued** -- задачу створено, вона очікує, поки провайдер її прийме.
2. **running** -- провайдер обробляє її (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності).
3. **succeeded** -- відео готове; агент прокидається й публікує його в розмову.
4. **failed** -- помилка провайдера або тайм-аут; агент прокидається з деталями помилки.
1. **queued** -- завдання створено, очікує, доки провайдер його прийме.
2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності).
3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову.
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з відомостями про помилку.
Перевірка стану через CLI:
@ -79,164 +79,166 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
Запобігання дублюванню: якщо для поточної сесії задача відео вже має стан `queued` або `running`, `video_generate` повертає стан наявної задачі замість запуску нової. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації.
Запобігання дублюванню: якщо для поточного сеансу вже є відеозавдання у стані `queued` або `running`, `video_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації.
## Підтримувані провайдери
| Провайдер | Типова модель | Текст | Референсне зображення | Референсне відео | API key |
| --------------------- | ------------------------------ | ----- | ------------------------------------------------------ | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший + останній кадр) | Ні | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший + останній кадр через роль) | Ні | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 референсних зображень | До 3 відео | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview`| Так | 1 зображення | 1 відео | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` |
| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Так | 1 зображення | 1 відео | `XAI_API_KEY` |
| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | API-ключ |
| -------------------- | ------------------------------ | ----- | ---------------------------------------------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший і останній кадр) | Ні | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший і останній кадр через role) | Ні | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` |
| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Так | 1 зображення | 1 відео | `XAI_API_KEY` |
Деякі провайдери приймають додаткові або альтернативні env vars для API key. Подробиці див. на окремих [сторінках провайдерів](#related).
Деякі провайдери приймають додаткові або альтернативні змінні середовища для API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related).
Запустіть `video_generate action=list`, щоб під час runtime переглянути доступних провайдерів, моделі та режими runtime.
Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та
режими виконання.
### Матриця оголошених можливостей
### Матриця заявлених можливостей
Це явний контракт режимів, який використовується `video_generate`, contract tests
і спільною live-перевіркою.
Це явний контракт режимів, який використовують `video_generate`, контрактні тести
та спільний live sweep.
| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Поточні спільні live-lanes |
| --------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` |
| ComfyUI | Так | Так | Ні | Не входить до спільної перевірки; покриття, специфічне для workflow, живе разом із тестами Comfy |
| fal | Так | Так | Ні | `generate`, `imageToVideo` |
| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки поточна buffer-backed Gemini/Veo перевірка не приймає такий ввід |
| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` |
| OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки цей шлях org/input наразі потребує доступу до provider-side inpaint/remix |
| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` |
| Together | Так | Так | Ні | `generate`, `imageToVideo` |
| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропускається, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення |
| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру наразі потрібен віддалений MP4 URL |
| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-lane сьогодні |
| --------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` |
| ComfyUI | Так | Так | Ні | Не входить до спільного sweep; покриття, специфічне для workflow, живе в тестах Comfy |
| fal | Так | Так | Ні | `generate`, `imageToVideo` |
| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний sweep Gemini/Veo на основі буфера не приймає це введення |
| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` |
| OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input зараз потребує доступу до inpaint/remix на боці провайдера |
| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` |
| Together | Так | Так | Ні | `generate`, `imageToVideo` |
| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення |
| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру зараз потрібен віддалений MP4 URL |
## Параметри інструмента
### Обов’язкові
| Параметр | Тип | Опис |
| -------- | ------ | ------------------------------------------------------------------------------- |
| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) |
| Параметр | Тип | Опис |
| -------- | ------ | --------------------------------------------------------------------------- |
| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) |
### Вхідний вміст
### Вхідні дані вмісту
| Параметр | Тип | Опис |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | string | Одне референсне зображення (шлях або URL) |
| `images` | string[] | Кілька референсних зображень (до 9) |
| `imageRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` |
| `video` | string | Одне референсне відео (шлях або URL) |
| `videos` | string[] | Кілька референсних відео (до 4) |
| `videoRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку відео. Канонічне значення: `reference_video` |
| `audioRef` | string | Одне референсне аудіо (шлях або URL). Використовується, наприклад, для фонової музики або голосового референсу, коли провайдер підтримує аудіовходи |
| `audioRefs` | string[] | Кілька референсних аудіо (до 3) |
| `audioRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку аудіо. Канонічне значення: `reference_audio` |
| Параметр | Тип | Опис |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | string | Одне еталонне зображення (шлях або URL) |
| `images` | string[] | Кілька еталонних зображень (до 9) |
| `imageRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` |
| `video` | string | Одне еталонне відео (шлях або URL) |
| `videos` | string[] | Кілька еталонних відео (до 4) |
| `videoRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку відео. Канонічне значення: `reference_video` |
| `audioRef` | string | Один еталонний аудіофайл (шлях або URL). Використовується, наприклад, для фонової музики або еталона голосу, коли провайдер підтримує аудіовхід |
| `audioRefs` | string[] | Кілька еталонних аудіофайлів (до 3) |
| `audioRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку аудіо. Канонічне значення: `reference_audio` |
Role hints пересилаються провайдеру без змін. Канонічні значення походять із
Підказки ролей пересилаються провайдеру як є. Канонічні значення походять із
об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові
рядки ролей. Масиви `*Roles` не можуть містити більше записів, ніж
відповідний список референсів; помилки типу off-by-one завершуються зрозумілою помилкою.
Використовуйте порожній рядок, щоб залишити слот невстановленим.
відповідний список еталонів; помилки на один елемент дають чітке повідомлення.
Використовуйте порожній рядок, щоб залишити позицію незаданою.
### Керування стилем
| Параметр | Тип | Опис |
| ---------------- | ------- | -------------------------------------------------------------------------------------- |
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` |
| `resolution` | string | `480P`, `720P`, `768P` або `1080P` |
| `durationSeconds`| number | Цільова тривалість у секундах (округлюється до найближчого значення, підтримуваного провайдером) |
| `size` | string | Підказка розміру, коли провайдер це підтримує |
| `audio` | boolean | Увімкнути згенероване аудіо у виводі, коли це підтримується. Відрізняється від `audioRef*` (входи) |
| `watermark` | boolean | Увімкнути або вимкнути watermark провайдера, коли це підтримується |
| Параметр | Тип | Опис |
| ----------------- | ------- | ----------------------------------------------------------------------------------------- |
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` |
| `resolution` | string | `480P`, `720P`, `768P` або `1080P` |
| `durationSeconds` | number | Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер) |
| `size` | string | Підказка розміру, якщо провайдер це підтримує |
| `audio` | boolean | Увімкнути згенерований звук у виводі, якщо підтримується. Відрізняється від `audioRef*` (входи) |
| `watermark` | boolean | Перемикає водяні знаки провайдера, якщо підтримується |
`adaptive` — це provider-specific sentinel: він пересилається без змін
провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад BytePlus
Seedance використовує його для автоматичного визначення співвідношення сторін із
розмірів вхідного зображення). Провайдери, які не оголошують цю можливість, показують це значення через
`adaptive` — це специфічний для провайдера sentinel: він пересилається як є
провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus
Seedance використовує його, щоб автоматично визначати співвідношення сторін за розмірами
вхідного зображення). Провайдери, які його не оголошують, відображають це значення через
`details.ignoredOverrides` у результаті інструмента, щоб відкидання було видимим.
### Розширені
### Додатково
| Параметр | Тип | Опис |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | `"generate"` (типово), `"status"` або `"list"` |
| `model` | string | Перевизначення провайдера/моделі (наприклад `runway/gen4.5`) |
| `filename` | string | Підказка для імені вихідного файла |
| `providerOptions`| object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі та типи значень; невідомі ключі або невідповідності призводять до пропуску кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер |
| Параметр | Тип | Опис |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | `"generate"` (типово), `"status"` або `"list"` |
| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) |
| `filename` | string | Підказка для імені вихідного файла |
| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах |
| `providerOptions` | object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі й типи; невідомі ключі або невідповідності змушують пропустити кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер |
Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого значення, яке підтримує провайдер, а також переназначає перекладені геометричні підказки, як-от size-to-aspect-ratio, коли fallback-провайдер надає іншу surface керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто багато референсних входів) призводять до помилки ще до надсилання.
Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого значення, яке підтримує провайдер, а також переназначає перекладені підказки геометрії, як-от size-to-aspect-ratio, коли fallback-провайдер надає іншу поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто велика кількість еталонних входів) спричиняють помилку до надсилання.
Результати інструмента повідомляють про застосовані параметри. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернені значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернуті значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
Референсні входи також визначають режим runtime:
Еталонні входи також визначають режим виконання:
- Без референсних медіа: `generate`
- Будь-яке референсне зображення: `imageToVideo`
- Будь-яке референсне відео: `videoToVideo`
- Референсні аудіовходи не змінюють визначений режим; вони застосовуються поверх режиму, який вибирають референсні зображення/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios`
- Без еталонних медіа: `generate`
- Будь-яке еталонне зображення: `imageToVideo`
- Будь-яке еталонне відео: `videoToVideo`
- Еталонні аудіовходи не змінюють визначений режим; вони застосовуються поверх режиму, який вибрали еталонні зображення/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios`
Змішані референси зображень і відео не є стабільною спільною поверхнею можливостей.
Надавайте перевагу одному типу референсу на запит.
Змішані еталонні зображення та відео не є стабільною спільною поверхнею можливостей.
Краще використовувати один тип еталона на запит.
#### Fallback і типізовані параметри
Деякі перевірки можливостей застосовуються на рівні fallback, а не на
межі інструмента, щоб запит, який перевищує обмеження основного провайдера,
усе ще міг виконатися на fallback-провайдері, який це підтримує:
Деякі перевірки можливостей застосовуються на рівні fallback, а не на межі
інструмента, щоб запит, який перевищує обмеження основного провайдера,
усе ще міг виконатися на придатному fallback:
- Якщо активний кандидат не оголошує `maxInputAudios` (або оголошує його як
`0`), він пропускається, коли запит містить аудіореференси, і
пробується наступний кандидат.
- Якщо `maxDurationSeconds` активного кандидата нижчий за запитане
`0`), його пропускають, коли запит містить еталонні аудіо, і
пробують наступного кандидата.
- Якщо `maxDurationSeconds` активного кандидата менше за запитане
`durationSeconds`, а кандидат не оголошує список
`supportedDurationSeconds`, він пропускається.
`supportedDurationSeconds`, його пропускають.
- Якщо запит містить `providerOptions`, а активний кандидат
явно оголошує типізовану схему `providerOptions`, кандидат
пропускається, коли передані ключі відсутні в схемі або типи значень
явно оголошує типізовану схему `providerOptions`, кандидата
пропускають, якщо надані ключі відсутні в схемі або типи значень
не збігаються. Провайдери, які ще не оголосили схему, отримують
параметри як є (зворотно сумісний pass-through). Провайдер може
явно відмовитися від усіх provider options, оголосивши порожню схему
(`capabilities.providerOptions: {}`), що спричиняє той самий пропуск, що і
невідповідність типу.
параметри як є (зворотно сумісне наскрізне передавання). Провайдер може
явно відмовитися від усіх параметрів провайдера, оголосивши порожню схему
(`capabilities.providerOptions: {}`), що спричиняє те саме пропускання, що й
невідповідність типів.
Перша причина пропуску в запиті логується на рівні `warn`, щоб оператори бачили,
коли основного провайдера було пропущено; наступні пропуски логуются на
рівні `debug`, щоб довгі fallback-ланцюжки не шуміли. Якщо пропущено кожного кандидата,
агрегована помилка включає причину пропуску для кожного.
коли їхнього основного провайдера було пропущено; наступні пропуски логуются на
рівні `debug`, щоб довгі ланцюжки fallback не створювали зайвого шуму. Якщо пропущено кожного кандидата,
агрегована помилка містить причину пропуску для кожного з них.
## Дії
- **generate** (типово) -- створити відео з указаного prompt і необов’язкових референсних входів.
- **status** -- перевірити стан поточної video task для поточної сесії без запуску нової генерації.
- **generate** (типово) -- створити відео з указаного запиту та необов’язкових еталонних входів.
- **status** -- перевірити стан відеозавдання, яке виконується для поточного сеансу, без запуску нової генерації.
- **list** -- показати доступних провайдерів, моделі та їхні можливості.
## Вибір моделі
Під час генерації відео OpenClaw визначає модель у такому порядку:
1. **Параметр інструмента `model`** -- якщо агент указує його у виклику.
2. **`videoGenerationModel.primary`** -- з конфігурації.
3. **`videoGenerationModel.fallbacks`** -- пробуються по порядку.
4. **Автовиявлення** -- використовує провайдерів із дійсною автентифікацією, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку.
1. **параметр інструмента `model`** -- якщо агент указує його у виклику.
2. **`videoGenerationModel.primary`** -- із конфігурації.
3. **`videoGenerationModel.fallbacks`** -- випробовуються по черзі.
4. **Автовизначення** -- використовує провайдерів із валідною автентифікацією, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку.
Якщо провайдер дає збій, автоматично пробується наступний кандидат. Якщо всі кандидати дають збій, помилка включає подробиці кожної спроби.
Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі кандидати завершуються помилкою, помилка містить подробиці кожної спроби.
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо ви хочете,
щоб генерація відео використовувала лише явні записи `model`, `primary` і `fallbacks`.
щоб генерація відео використовувала лише явно задані записи `model`, `primary` і `fallbacks`.
```json5
{
@ -251,29 +253,29 @@ Seedance використовує його для автоматичного в
}
```
## Примітки про провайдерів
## Примітки щодо провайдерів
| Провайдер | Примітки |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | Використовує асинхронний endpoint DashScope/Model Studio. Референсні зображення та відео мають бути віддаленими `http(s)` URL-адресами. |
| BytePlus (1.0) | ID провайдера `byteplus`. Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і загальні моделі `*-pro-*` підтримують одне референсне зображення (перший кадр). Передавайте зображення позиційно або встановлюйте `role: "first_frame"`. ID моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean, примусово задає 480p), `camera_fixed` (boolean). |
| BytePlus Seedance 1.5 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. Використовує уніфікований API `content[]`. Підтримує максимум 2 вхідних зображення (first_frame + last_frame). Усі входи мають бути віддаленими `https://` URL-адресами. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передавайте зображення позиційно. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) пересилається далі. |
| BytePlus Seedance 2.0 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Використовує уніфікований API `content[]`. Підтримує до 9 референсних зображень, 3 референсних відео та 3 референсних аудіо. Усі входи мають бути віддаленими `https://` URL-адресами. Установіть `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) пересилається далі. |
| ComfyUI | Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований graph. |
| fal | Використовує queue-backed flow для довготривалих завдань. Лише одне референсне зображення. |
| Google | Використовує Gemini/Veo. Підтримує одне референсне зображення або одне референсне відео. |
| MiniMax | Лише одне референсне зображення. |
| OpenAI | Пересилається лише перевизначення `size`. Інші стильові перевизначення (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. |
| Qwen | Той самий бекенд DashScope, що й Alibaba. Референсні входи мають бути віддаленими `http(s)` URL-адресами; локальні файли відхиляються одразу. |
| Runway | Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Для запусків лише з текстом доступні співвідношення сторін `16:9` і `9:16`. |
| Together | Лише одне референсне зображення. |
| Vydra | Використовує напряму `https://www.vydra.ai/api/v1`, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано як text-to-video only; `kling` потребує віддаленої URL-адреси зображення. |
| xAI | Підтримує text-to-video, image-to-video і віддалені потоки редагування/розширення відео. |
| Провайдер | Примітки |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Alibaba | Використовує асинхронний endpoint DashScope/Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`. |
| BytePlus (1.0) | Ідентифікатор провайдера `byteplus`. Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`. Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean, примусово встановлює 480p), `camera_fixed` (boolean). |
| BytePlus Seedance 1.5 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. Використовує уніфікований API `content[]`. Підтримує не більш як 2 вхідні зображення (first_frame + last_frame). Усі входи мають бути віддаленими URL `https://`. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передайте зображення позиційно. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін за вхідним зображенням. `audio: true` відображається на `generate_audio`. `providerOptions.seed` (number) пересилається далі. |
| BytePlus Seedance 2.0 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими URL `https://`. Установлюйте `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін за вхідним зображенням. `audio: true` відображається на `generate_audio`. `providerOptions.seed` (number) пересилається далі. |
| ComfyUI | Виконання локально або в хмарі на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. |
| fal | Використовує flow на основі черги для довготривалих завдань. Лише одне еталонне зображення. |
| Google | Використовує Gemini/Veo. Підтримує одне еталонне зображення або одне еталонне відео. |
| MiniMax | Лише одне еталонне зображення. |
| OpenAI | Пересилається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. |
| Qwen | Такий самий бекенд DashScope, як і в Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли відхиляються одразу. |
| Runway | Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. |
| Together | Лише одне еталонне зображення. |
| Vydra | Напряму використовує `https://www.vydra.ai/api/v1`, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує віддаленого URL зображення. |
| xAI | Підтримує text-to-video, image-to-video та потоки віддаленого редагування/розширення відео. |
## Режими можливостей провайдера
## Режими можливостей провайдерів
Спільний контракт генерації відео тепер дозволяє провайдерам оголошувати
можливості, специфічні для режиму, а не лише плоскі агреговані обмеження. Нові
Спільний контракт генерації відео тепер дає провайдерам змогу оголошувати
можливості, специфічні для режиму, замість лише пласких агрегованих обмежень. Нові
реалізації провайдерів мають надавати перевагу явним блокам режимів:
```typescript
@ -298,55 +300,55 @@ capabilities: {
}
```
Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо
для оголошення підтримки transform-режимів. Провайдери мають оголошувати
`generate`, `imageToVideo` і `videoToVideo` явно, щоб live tests,
contract tests і спільний інструмент `video_generate` могли детерміновано
Пласких агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо,
щоб оголосити підтримку режимів перетворення. Провайдери мають оголошувати
`generate`, `imageToVideo` і `videoToVideo` явно, щоб live-тести,
контрактні тести та спільний інструмент `video_generate` могли детерміновано
перевіряти підтримку режимів.
## Live tests
## Live-тести
Opt-in live-покриття для спільних вбудованих провайдерів:
Опціональне live-покриття для спільних вбудованих провайдерів:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
Repo wrapper:
Обгортка репозиторію:
```bash
pnpm test:live:media video
```
Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, типово віддає
перевагу live/env API keys над збереженими профілями автентифікації, і за замовчуванням запускає
безпечний для релізу smoke:
Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово
надає перевагу live/env API-ключам над збереженими профілями автентифікації та запускає
безпечний для релізу smoke-тест за замовчуванням:
- `generate` для кожного провайдера в перевірці, крім FAL
- prompt про лобстера на одну секунду
- обмеження операцій для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
(`180000` типово)
- `generate` для кожного провайдера зі sweep, окрім FAL
- односекундний запит про лобстера
- обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
(`180000` за замовчуванням)
FAL вмикається лише за бажанням, оскільки затримка черги на боці провайдера може домінувати над часом релізу:
FAL є опціональним, оскільки затримка черги на боці провайдера може суттєво збільшувати час релізу:
```bash
pnpm test:live:media video --video-providers fal
```
Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені transform-режими,
які спільна перевірка може безпечно виконувати з локальними медіа:
Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення,
які спільний sweep може безпечно виконувати з локальними медіа:
- `imageToVideo`, коли `capabilities.imageToVideo.enabled`
- `videoToVideo`, коли `capabilities.videoToVideo.enabled` і провайдер/модель
приймає buffer-backed локальний вхід відео у спільній перевірці
приймає локальний відеовхід на основі буфера в межах спільного sweep
Наразі спільний live-lane `videoToVideo` охоплює:
Сьогодні спільна live-lane `videoToVideo` покриває:
- `runway` лише тоді, коли ви вибираєте `runway/gen4_aleph`
- лише `runway`, коли ви вибираєте `runway/gen4_aleph`
## Конфігурація
Установіть типову модель генерації відео у своїй конфігурації OpenClaw:
Установіть типову модель генерації відео у конфігурації OpenClaw:
```json5
{
@ -370,7 +372,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## Пов’язане
- [Огляд інструментів](/uk/tools)
- [Фонові завдання](/uk/automation/tasks) -- відстеження задач для асинхронної генерації відео
- [Фонові завдання](/uk/automation/tasks) -- відстеження завдань для асинхронної генерації відео
- [Alibaba Model Studio](/uk/providers/alibaba)
- [BytePlus](/uk/concepts/model-providers#byteplus-international)
- [ComfyUI](/uk/providers/comfy)