diff --git a/docs/uk/cli/message.md b/docs/uk/cli/message.md index 97ee98b87..f19714a91 100644 --- a/docs/uk/cli/message.md +++ b/docs/uk/cli/message.md @@ -2,21 +2,21 @@ read_when: - Додавання або змінення дій CLI для повідомлень - Змінення поведінки вихідного каналу -summary: Довідка CLI для `openclaw message` (надсилання + дії каналу) +summary: Довідник CLI для `openclaw message` (надсилання + дії каналу) title: Повідомлення x-i18n: - generated_at: "2026-04-24T04:12:34Z" + generated_at: "2026-04-27T20:08:58Z" model: gpt-5.4 provider: openai - source_hash: 39932fb54caee37bdf58681da22b30e1b4cc7cc11b654010bf0335b1da3b2b4d + source_hash: 43f14b3815d89c92a7503e620e2424f41a3f6b92e20e089504017305b19bace4 source_path: cli/message.md workflow: 15 --- # `openclaw message` -Єдина вихідна команда для надсилання повідомлень і виконання дій каналу -(Discord/Google Chat/iMessage/Matrix/Mattermost (Plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp). +Єдина вихідна команда для надсилання повідомлень і дій каналу +(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp). ## Використання @@ -26,67 +26,68 @@ openclaw message [flags] Вибір каналу: -- `--channel` обов’язковий, якщо налаштовано більше ніж один канал. +- `--channel` обов’язковий, якщо налаштовано більше одного каналу. - Якщо налаштовано рівно один канал, він стає типовим. -- Значення: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost вимагає Plugin) +- Значення: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost потребує plugin) +- `openclaw message` зіставляє вибраний канал з plugin, якому він належить, коли присутній `--channel` або ціль із префіксом каналу; інакше завантажує налаштовані channel plugins для визначення типового каналу. -Формати цілі (`--target`): +Формати цілей (`--target`): -- WhatsApp: E.164 або group JID -- Telegram: id чату або `@username` -- Discord: `channel:` або `user:` (або згадка `<@id>`; необроблені числові id трактуються як канали) +- WhatsApp: E.164 або груповий JID +- Telegram: ідентифікатор чату або `@username` +- Discord: `channel:` або `user:` (або згадка `<@id>`; необроблені числові ідентифікатори вважаються каналами) - Google Chat: `spaces/` або `users/` -- Slack: `channel:` або `user:` (необроблений id каналу підтримується) -- Mattermost (Plugin): `channel:`, `user:` або `@username` (id без префікса трактуються як канали) +- Slack: `channel:` або `user:` (необроблений ідентифікатор каналу приймається) +- Mattermost (plugin): `channel:`, `user:` або `@username` (ідентифікатори без префікса вважаються каналами) - Signal: `+E.164`, `group:`, `signal:+E.164`, `signal:group:` або `username:`/`u:` - iMessage: handle, `chat_id:`, `chat_guid:` або `chat_identifier:` - Matrix: `@user:server`, `!room:server` або `#alias:server` -- Microsoft Teams: id розмови (`19:...@thread.tacv2`) або `conversation:` або `user:` +- Microsoft Teams: ідентифікатор розмови (`19:...@thread.tacv2`) або `conversation:` чи `user:` Пошук за назвою: -- Для підтримуваних провайдерів (Discord/Slack тощо) назви каналів, як-от `Help` або `#help`, визначаються через кеш каталогу. -- Якщо кеш не містить запису, OpenClaw спробує виконати живий пошук у каталозі, якщо провайдер це підтримує. +- Для підтримуваних провайдерів (Discord/Slack тощо) назви каналів, як-от `Help` або `#help`, зіставляються через кеш каталогу. +- Якщо кеш не містить збігу, OpenClaw спробує виконати живий пошук у каталозі, якщо провайдер це підтримує. ## Загальні прапорці - `--channel ` - `--account ` - `--target ` (цільовий канал або користувач для send/poll/read тощо) -- `--targets ` (повторюється; лише для broadcast) +- `--targets ` (повторюваний; лише для broadcast) - `--json` - `--dry-run` - `--verbose` ## Поведінка SecretRef -- `openclaw message` визначає підтримувані SecretRef каналу перед виконанням вибраної дії. -- Визначення, де можливо, обмежується активною ціллю дії: - - на рівні каналу, коли задано `--channel` (або його виведено з цілей із префіксом, як-от `discord:...`) - - на рівні облікового запису, коли задано `--account` (глобальні поверхні каналу + поверхні вибраного облікового запису) - - якщо `--account` не задано, OpenClaw не примушує до області SecretRef облікового запису `default` -- Невизначені SecretRef в не пов’язаних каналах не блокують цільову дію з повідомленням. -- Якщо SecretRef вибраного каналу/облікового запису не визначено, команда завершується із закритою відмовою для цієї дії. +- `openclaw message` розв’язує підтримувані channel SecretRef перед виконанням вибраної дії. +- Розв’язання, коли можливо, обмежується активною ціллю дії: + - у межах каналу, коли задано `--channel` (або його визначено з цілей із префіксом, як-от `discord:...`) + - у межах облікового запису, коли задано `--account` (глобальні значення каналу + поверхні вибраного облікового запису) + - якщо `--account` не вказано, OpenClaw не примусово застосовує область SecretRef облікового запису `default` +- Нерозв’язані SecretRef в нерелевантних каналах не блокують цільову дію повідомлення. +- Якщо SecretRef вибраного каналу/облікового запису не розв’язано, команда завершується безпечною відмовою для цієї дії. ## Дії -### Основні +### Ядро - `send` - - Канали: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix/Microsoft Teams + - Канали: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams - Обов’язково: `--target`, а також `--message`, `--media` або `--presentation` - Необов’язково: `--media`, `--presentation`, `--delivery`, `--pin`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent` - - Спільні payload presentation: `--presentation` надсилає семантичні блоки (`text`, `context`, `divider`, `buttons`, `select`), які core рендерить через оголошені можливості вибраного каналу. Див. [Message Presentation](/uk/plugins/message-presentation). - - Загальні параметри доставки: `--delivery` приймає підказки доставки, як-от `{ "pin": true }`; `--pin` є скороченням для закріпленої доставки, коли канал це підтримує. - - Лише Telegram: `--force-document` (надсилати зображення та GIF як документи, щоб уникнути стиснення Telegram) - - Лише Telegram: `--thread-id` (id теми форуму) - - Лише Slack: `--thread-id` (timestamp гілки; `--reply-to` використовує те саме поле) + - Спільні presentation payload: `--presentation` надсилає семантичні блоки (`text`, `context`, `divider`, `buttons`, `select`), які ядро рендерить через оголошені можливості вибраного каналу. Див. [Message Presentation](/uk/plugins/message-presentation). + - Загальні параметри доставки: `--delivery` приймає підказки доставки, як-от `{ "pin": true }`; `--pin` — скорочення для закріпленої доставки, якщо канал це підтримує. + - Лише Telegram: `--force-document` (надсилати зображення й GIF як документи, щоб уникнути стиснення Telegram) + - Лише Telegram: `--thread-id` (ідентифікатор теми форуму) + - Лише Slack: `--thread-id` (часова мітка потоку; `--reply-to` використовує те саме поле) - Telegram + Discord: `--silent` - Лише WhatsApp: `--gif-playback` - `poll` - Канали: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams - - Обов’язково: `--target`, `--poll-question`, `--poll-option` (повторюється) + - Обов’язково: `--target`, `--poll-question`, `--poll-option` (повторюваний) - Необов’язково: `--poll-multi` - Лише Discord: `--poll-duration-hours`, `--silent`, `--message` - Лише Telegram: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id` @@ -95,9 +96,9 @@ openclaw message [flags] - Канали: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix - Обов’язково: `--message-id`, `--target` - Необов’язково: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid` - - Примітка: `--remove` вимагає `--emoji` (не вказуйте `--emoji`, щоб очистити власні реакції там, де це підтримується; див. /tools/reactions) + - Примітка: `--remove` потребує `--emoji` (не вказуйте `--emoji`, щоб очистити власні реакції там, де це підтримується; див. /tools/reactions) - Лише WhatsApp: `--participant`, `--from-me` - - Реакції в групах Signal: обов’язково `--target-author` або `--target-author-uuid` + - Реакції в групах Signal: обов’язковий `--target-author` або `--target-author-uuid` - `reactions` - Канали: Discord/Google Chat/Slack/Matrix @@ -134,13 +135,13 @@ openclaw message [flags] - `search` - Канали: Discord - Обов’язково: `--guild-id`, `--query` - - Необов’язково: `--channel-id`, `--channel-ids` (повторюється), `--author-id`, `--author-ids` (повторюється), `--limit` + - Необов’язково: `--channel-id`, `--channel-ids` (повторюваний), `--author-id`, `--author-ids` (повторюваний), `--limit` -### Гілки +### Потоки - `thread create` - Канали: Discord - - Обов’язково: `--thread-name`, `--target` (id каналу) + - Обов’язково: `--thread-name`, `--target` (ідентифікатор каналу) - Необов’язково: `--message-id`, `--message`, `--auto-archive-min` - `thread list` @@ -150,7 +151,7 @@ openclaw message [flags] - `thread reply` - Канали: Discord - - Обов’язково: `--target` (id гілки), `--message` + - Обов’язково: `--target` (ідентифікатор потоку), `--message` - Необов’язково: `--media`, `--reply-to` ### Емодзі @@ -162,13 +163,13 @@ openclaw message [flags] - `emoji upload` - Канали: Discord - Обов’язково: `--guild-id`, `--emoji-name`, `--media` - - Необов’язково: `--role-ids` (повторюється) + - Необов’язково: `--role-ids` (повторюваний) -### Стікери +### Наліпки - `sticker send` - Канали: Discord - - Обов’язково: `--target`, `--sticker-id` (повторюється) + - Обов’язково: `--target`, `--sticker-id` (повторюваний) - Необов’язково: `--message` - `sticker upload` @@ -192,12 +193,12 @@ openclaw message [flags] ### Модерація (Discord) -- `timeout`: `--guild-id`, `--user-id` (необов’язково `--duration-min` або `--until`; не вказуйте обидва, щоб скасувати timeout) +- `timeout`: `--guild-id`, `--user-id` (необов’язково `--duration-min` або `--until`; якщо обидва пропущено, тайм-аут буде скасовано) - `kick`: `--guild-id`, `--user-id` (+ `--reason`) - `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`) - `timeout` також підтримує `--reason` -### Broadcast +### Трансляція - `broadcast` - Канали: будь-який налаштований канал; використовуйте `--channel all`, щоб націлитися на всіх провайдерів @@ -221,9 +222,9 @@ openclaw message send --channel discord \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}' ``` -Core рендерить той самий payload `presentation` у компоненти Discord, блоки Slack, вбудовані кнопки Telegram, props Mattermost або картки Teams/Feishu залежно від можливостей каналу. Див. [Message Presentation](/uk/plugins/message-presentation) для повного контракту та правил резервного відображення. +Ядро рендерить той самий payload `presentation` у компоненти Discord, блоки Slack, inline-кнопки Telegram, props Mattermost або картки Teams/Feishu залежно від можливостей каналу. Див. [Message Presentation](/uk/plugins/message-presentation) для повного контракту та правил резервного відображення. -Надіслати багатший payload presentation: +Надіслати розширений payload presentation: ```bash openclaw message send --channel googlechat --target spaces/AAA... \ @@ -241,7 +242,7 @@ openclaw message poll --channel discord \ --poll-multi --poll-duration-hours 48 ``` -Створити опитування в Telegram (автозакриття через 2 хвилини): +Створити опитування в Telegram (автоматично закрити через 2 хвилини): ``` openclaw message poll --channel telegram \ @@ -267,7 +268,7 @@ openclaw message poll --channel msteams \ --poll-option Pizza --poll-option Sushi ``` -Додати реакцію у Slack: +Додати реакцію в Slack: ``` openclaw message react --channel slack \ @@ -282,14 +283,14 @@ openclaw message react --channel signal \ --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000 ``` -Надіслати вбудовані кнопки Telegram через загальний presentation: +Надіслати inline-кнопки Telegram через узагальнений presentation: ``` openclaw message send --channel telegram --target @mychat --message "Choose:" \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}' ``` -Надіслати картку Teams через загальний presentation: +Надіслати картку Teams через узагальнений presentation: ```bash openclaw message send --channel msteams \ @@ -297,7 +298,7 @@ openclaw message send --channel msteams \ --presentation '{"title":"Status update","blocks":[{"type":"text","text":"Build completed"}]}' ``` -Надіслати зображення Telegram як документ, щоб уникнути стиснення: +Надіслати зображення в Telegram як документ, щоб уникнути стиснення: ```bash openclaw message send --channel telegram --target @mychat \ @@ -306,5 +307,5 @@ openclaw message send --channel telegram --target @mychat \ ## Пов’язане -- [Довідка CLI](/uk/cli) +- [Довідник CLI](/uk/cli) - [Надсилання агента](/uk/tools/agent-send) diff --git a/docs/uk/cli/models.md b/docs/uk/cli/models.md index a04db8420..a1c6ffe86 100644 --- a/docs/uk/cli/models.md +++ b/docs/uk/cli/models.md @@ -1,27 +1,27 @@ --- read_when: - - Ви хочете змінити моделі за замовчуванням або переглянути статус auth провайдера - - Ви хочете просканувати доступні моделі/провайдери та налагодити профілі auth -summary: Довідник CLI для `openclaw models` (status/list/set/scan, псевдоніми, fallback, auth) + - Ви хочете змінити моделі за замовчуванням або переглянути стан автентифікації постачальника + - Ви хочете просканувати доступні моделі/постачальників і налагодити профілі автентифікації +summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація) title: Моделі x-i18n: - generated_at: "2026-04-27T06:24:03Z" + generated_at: "2026-04-27T20:08:44Z" model: gpt-5.4 provider: openai - source_hash: ffafec22fb05909fd06ffc8987f8da87597ef6aa85a69bcadbcfcc1d19f7d7dc + source_hash: 1ff1d5d6b7e2d72ad0ff7480313ca67f7a49ec77ab198b688e7abf2b9de42757 source_path: cli/models.md workflow: 15 --- # `openclaw models` -Виявлення моделей, сканування та конфігурація (модель за замовчуванням, fallback, профілі auth). +Виявлення моделей, сканування та налаштування (модель за замовчуванням, резервні варіанти, профілі автентифікації). -Пов’язане: +Пов’язано: -- Провайдери + моделі: [Моделі](/uk/providers/models) -- Концепції вибору моделі + slash-команда `/models`: [Концепція моделей](/uk/concepts/models) -- Налаштування auth провайдера: [Початок роботи](/uk/start/getting-started) +- Постачальники + моделі: [Моделі](/uk/providers/models) +- Концепції вибору моделей + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models) +- Налаштування автентифікації постачальника: [Початок роботи](/uk/start/getting-started) ## Поширені команди @@ -32,67 +32,67 @@ openclaw models set openclaw models scan ``` -`openclaw models status` показує визначені модель за замовчуванням/fallback, а також огляд auth. -Коли доступні знімки використання провайдера, розділ стану OAuth/API key містить -вікна використання провайдера та знімки квот. -Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI -Codex, MiniMax, Xiaomi і z.ai. Usage auth надходить зі специфічних для провайдера hooks, -коли вони доступні; інакше OpenClaw повертається до зіставлення облікових даних -OAuth/API key з профілів auth, env або конфігурації. -У виводі `--json` `auth.providers` — це огляд провайдерів з урахуванням env/config/store, -тоді як `auth.oauth` — лише стан профілів сховища auth. -Додайте `--probe`, щоб виконати live-перевірки auth для кожного налаштованого профілю провайдера. -Перевірки — це реальні запити (можуть витрачати токени та спричиняти обмеження швидкості). -Використовуйте `--agent `, щоб переглянути стан моделі/auth для налаштованого агента. Якщо його не вказано, -команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо задано, інакше — +`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації. +Коли доступні знімки використання постачальника, розділ стану OAuth/API-ключа включає +вікна використання постачальника та знімки квот. +Поточні постачальники з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI +Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків, специфічних для постачальника, +коли вони доступні; інакше OpenClaw використовує резервний варіант і підбирає облікові дані +OAuth/API-ключа з профілів автентифікації, env або config. +У виводі `--json` `auth.providers` — це огляд постачальників з урахуванням env/config/store, +тоді як `auth.oauth` — це лише стан профілів у сховищі автентифікації. +Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю постачальника. +Перевірки — це реальні запити (можуть витрачати токени та спричиняти обмеження частоти). +Використовуйте `--agent `, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано, +команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше — налаштованого агента за замовчуванням. -Рядки перевірок можуть походити з профілів auth, облікових даних env або `models.json`. +Рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`. Примітки: - `models set ` приймає `provider/model` або псевдонім. -- `models list` працює лише на читання: вона читає конфігурацію, профілі auth, наявний стан каталогу - та рядки каталогу, що належать провайдеру, але не переписує +- `models list` — лише для читання: команда читає config, профілі автентифікації, наявний стан каталогу + та рядки каталогу, що належать постачальнику, але не переписує `models.json`. -- `models list --all --provider ` може включати статичні рядки каталогу, що належать провайдеру, - з маніфестів plugin або метаданих вбудованого каталогу провайдера, навіть якщо ви - ще не автентифікувалися в цього провайдера. Такі рядки все одно показуються як - недоступні, доки не буде налаштовано відповідний auth. -- `models list` зберігає розділення між власними метаданими моделі та runtime-обмеженнями. У табличному - виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне runtime-обмеження - відрізняється від власного контекстного вікна; рядки JSON містять `contextTokens`, - якщо провайдер відкриває це обмеження. -- `models list --provider ` фільтрує за id провайдера, наприклад `moonshot` або - `openai-codex`. Він не приймає мітки відображення з інтерактивних - засобів вибору провайдера, як-от `Moonshot AI`. -- Посилання на моделі розбираються поділом за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). -- Якщо ви пропускаєте провайдера, OpenClaw спочатку визначає введення як псевдонім, потім — - як унікальний збіг точного id моделі серед налаштованих провайдерів, і лише після цього - повертається до налаштованого провайдера за замовчуванням із попередженням про застарілість. - Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw - повертається до першого налаштованого провайдера/моделі замість того, щоб показувати - застаріле типове значення видаленого провайдера. -- `models status` може показувати `marker()` у виводі auth для несекретних заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. +- `models list --all --provider ` може включати статичні рядки каталогу, що належать постачальнику, + із маніфестів Plugin або вбудованих метаданих каталогу постачальника, навіть якщо ви + ще не пройшли автентифікацію в цього постачальника. Такі рядки все одно відображаються як + недоступні, доки не буде налаштовано відповідну автентифікацію. +- `models list` зберігає нативні метадані моделі та ефективні обмеження runtime окремо. У табличному + виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне обмеження runtime + відрізняється від нативного вікна контексту; рядки JSON включають `contextTokens`, + коли постачальник надає це обмеження. +- `models list --provider ` фільтрує за id постачальника, наприклад `moonshot` або + `openai-codex`. Він не приймає мітки відображення з інтерактивних засобів вибору постачальника, + наприклад `Moonshot AI`. +- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс постачальника (приклад: `openrouter/moonshotai/kimi-k2`). +- Якщо ви не вказали постачальника, OpenClaw спочатку визначає введення як псевдонім, потім — + як унікальний збіг exact model id серед налаштованих постачальників, і лише після цього + використовує резервний варіант із налаштованим постачальником за замовчуванням із попередженням про застарілість. + Якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw + використовує резервний варіант із першою налаштованою парою постачальник/модель замість того, щоб показувати + застаріле значення за замовчуванням від видаленого постачальника. +- `models status` може показувати `marker()` у виводі автентифікації для незахищених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. ### Сканування моделей -`models scan` читає публічний каталог `:free` OpenRouter і ранжує кандидатів для -використання як fallback. Сам каталог є публічним, тому для сканувань лише метаданих -ключ OpenRouter не потрібен. +`models scan` читає публічний каталог OpenRouter `:free` і ранжує кандидатів для +використання як резервних варіантів. Сам каталог є публічним, тому сканування лише метаданих не потребує +ключа OpenRouter. -За замовчуванням OpenClaw намагається перевірити підтримку інструментів і зображень за допомогою live-викликів моделей. -Якщо ключ OpenRouter не налаштовано, команда повертається до виводу лише метаданих і пояснює, -що моделі `:free` все одно потребують `OPENROUTER_API_KEY` для -перевірок і інференсу. +За замовчуванням OpenClaw намагається перевірити підтримку інструментів і зображень за допомогою живих викликів моделі. +Якщо ключ OpenRouter не налаштовано, команда використовує резервний варіант із виводом лише метаданих +і пояснює, що моделі `:free` усе одно потребують `OPENROUTER_API_KEY` для +перевірок і висновку. Параметри: -- `--no-probe` (лише метадані; без пошуку конфігурації/секретів) +- `--no-probe` (лише метадані; без пошуку config/секретів) - `--min-params ` - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout ` (тайм-аут запиту каталогу та тайм-аут кожної перевірки) +- `--timeout ` (тайм-аут запиту каталогу та кожної перевірки) - `--concurrency ` - `--yes` - `--no-input` @@ -100,8 +100,8 @@ OAuth/API key з профілів auth, env або конфігурації. - `--set-image` - `--json` -`--set-default` і `--set-image` вимагають live-перевірок; результати сканування -лише метаданих мають інформаційний характер і не застосовуються до конфігурації. +`--set-default` і `--set-image` потребують живих перевірок; результати сканування лише метаданих +є інформаційними та не застосовуються до config. ### Стан моделей @@ -109,15 +109,19 @@ OAuth/API key з профілів auth, env або конфігурації. - `--json` - `--plain` -- `--check` (код виходу 1=прострочено/відсутнє, 2=скоро спливає) -- `--probe` (live-перевірка налаштованих профілів auth) -- `--probe-provider ` (перевірити одного провайдера) -- `--probe-profile ` (повторювані або профілі через кому) +- `--check` (код виходу 1=прострочено/відсутнє, 2=строк дії спливає) +- `--probe` (жива перевірка налаштованих профілів автентифікації) +- `--probe-provider ` (перевірити одного постачальника) +- `--probe-profile ` (повторювані або розділені комами id профілів) - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` - `--agent ` (id налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) +`--json` зберігає stdout виключно для корисного навантаження JSON. Діагностика профілів автентифікації, постачальників +і запуску спрямовується в stderr, щоб скрипти могли напряму передавати stdout +в інструменти на кшталт `jq`. + Категорії стану перевірок: - `ok` @@ -129,24 +133,24 @@ OAuth/API key з профілів auth, env або конфігурації. - `unknown` - `no_model` -Випадки detail/reason-code перевірок, яких слід очікувати: +Варіанти деталей/кодів причин перевірок, на які слід очікувати: - `excluded_by_auth_order`: збережений профіль існує, але явний - `auth.order.` його пропустив, тож перевірка повідомляє про це виключення замість - спроби використати профіль. + `auth.order.` його пропустив, тому перевірка повідомляє про виключення замість + спроби використати його. - `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`: профіль присутній, але не придатний/не може бути визначений. -- `no_model`: auth провайдера існує, але OpenClaw не зміг визначити придатного - кандидата моделі для перевірки для цього провайдера. +- `no_model`: автентифікація постачальника існує, але OpenClaw не зміг визначити + кандидата моделі для перевірки для цього постачальника. -## Псевдоніми + fallback +## Псевдоніми + резервні варіанти ```bash openclaw models aliases list openclaw models fallbacks list ``` -## Профілі auth +## Профілі автентифікації ```bash openclaw models auth add @@ -155,14 +159,14 @@ openclaw models auth setup-token --provider openclaw models auth paste-token ``` -`models auth add` — це інтерактивний помічник auth. Він може запустити потік auth провайдера +`models auth add` — це інтерактивний помічник автентифікації. Він може запустити потік автентифікації постачальника (OAuth/API key) або провести вас через ручне вставлення токена, залежно від -вибраного провайдера. +вибраного постачальника. -`models auth login` запускає потік auth plugin провайдера (OAuth/API key). Використовуйте -`openclaw plugins list`, щоб побачити, які провайдери встановлено. -Використовуйте `openclaw models auth --agent `, щоб записати результати auth у -сховище конкретного налаштованого агента. Батьківський прапорець `--agent` враховується для +`models auth login` запускає потік автентифікації Plugin постачальника (OAuth/API key). Використовуйте +`openclaw plugins list`, щоб побачити, які постачальники встановлено. +Використовуйте `openclaw models auth --agent `, щоб записати результати автентифікації до +сховища конкретного налаштованого агента. Батьківський прапорець `--agent` підтримується в `add`, `login`, `setup-token`, `paste-token` і `login-github-copilot`. Приклади: @@ -173,21 +177,21 @@ openclaw models auth login --provider openai-codex --set-default Примітки: -- `setup-token` і `paste-token` залишаються універсальними командами токенів для провайдерів, - які надають методи auth через токен. -- `setup-token` вимагає інтерактивного TTY і запускає метод token-auth провайдера - (за замовчуванням використовуючи метод `setup-token` цього провайдера, якщо він його надає). -- `paste-token` приймає рядок токена, згенерований деінде або автоматизацією. -- `paste-token` вимагає `--provider`, запитує значення токена і записує - його до типового id профілю `:manual`, якщо ви не передасте +- `setup-token` і `paste-token` залишаються універсальними командами токенів для постачальників, + які надають методи автентифікації за токеном. +- `setup-token` потребує інтерактивного TTY і запускає метод токен-автентифікації постачальника + (типово — метод `setup-token` цього постачальника, якщо він його надає). +- `paste-token` приймає рядок токена, згенерований в іншому місці або автоматизацією. +- `paste-token` потребує `--provider`, запитує значення токена та записує + його до id профілю за замовчуванням `:manual`, якщо ви не передасте `--profile-id`. -- `paste-token --expires-in ` зберігає абсолютний час завершення дії токена на основі +- `paste-token --expires-in ` зберігає абсолютний строк дії токена на основі відносної тривалості, наприклад `365d` або `12h`. -- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI та `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- `setup-token` / `paste-token` для Anthropic залишаються підтримуваним шляхом токенів OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. -## Пов’язане +## Пов’язано -- [Довідник CLI](/uk/cli) +- [Довідка CLI](/uk/cli) - [Вибір моделі](/uk/concepts/model-providers) -- [Перемикання моделі при відмові](/uk/concepts/model-failover) +- [Перемикання між моделями при збоях](/uk/concepts/model-failover) diff --git a/docs/uk/cli/sessions.md b/docs/uk/cli/sessions.md index 4bb292d26..da3571f86 100644 --- a/docs/uk/cli/sessions.md +++ b/docs/uk/cli/sessions.md @@ -1,20 +1,20 @@ --- read_when: - - Ви хочете переглянути список збережених сесій і побачити нещодавню активність -summary: Довідник CLI для `openclaw sessions` (перелік збережених сесій і використання) -title: Сесії + - Ви хочете переглянути список збережених сеансів і недавню активність +summary: Довідка CLI для `openclaw sessions` (перелік збережених сеансів + використання) +title: Сеанси x-i18n: - generated_at: "2026-04-24T03:43:26Z" + generated_at: "2026-04-27T20:08:42Z" model: gpt-5.4 provider: openai - source_hash: 8d9fdc5d4cc968784e6e937a1000e43650345c27765208d46611e1fe85ee9293 + source_hash: 77bf1cdc5cb1688889ec5155241ed98a2c62204c56e727a1174c593a79c78ca8 source_path: cli/sessions.md workflow: 15 --- # `openclaw sessions` -Перегляд списку збережених сесій розмов. +Перелічує збережені сеанси розмов. ```bash openclaw sessions @@ -27,17 +27,18 @@ openclaw sessions --json Вибір області: -- типово: сховище типового налаштованого агента +- за замовчуванням: сховище агента, налаштоване за замовчуванням - `--verbose`: докладне журналювання -- `--agent `: сховище одного налаштованого агента -- `--all-agents`: агрегувати всі сховища налаштованих агентів +- `--agent `: одне налаштоване сховище агента +- `--all-agents`: агрегує всі налаштовані сховища агентів - `--store `: явний шлях до сховища (не можна поєднувати з `--agent` або `--all-agents`) -`openclaw sessions --all-agents` читає сховища налаштованих агентів. Gateway і ACP -мають ширше виявлення сесій: вони також включають сховища, знайдені лише на диску -в типовому корені `agents/` або в шаблонізованому корені `session.store`. Такі -виявлені сховища мають визначатися як звичайні файли `sessions.json` усередині -кореня агента; символьні посилання та шляхи поза коренем пропускаються. +`openclaw sessions --all-agents` читає налаштовані сховища агентів. Виявлення +сеансів Gateway і ACP має ширше охоплення: воно також включає сховища, знайдені +лише на диску, у стандартному корені `agents/` або в корені `session.store`, +заданому шаблоном. Ці виявлені сховища мають відповідати звичайним файлам +`sessions.json` усередині кореня агента; символічні посилання та шляхи поза +коренем пропускаються. Приклади JSON: @@ -73,19 +74,19 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` використовує параметри `session.maintenance` із конфігурації: +`openclaw sessions cleanup` використовує налаштування `session.maintenance` з конфігурації: -- Примітка щодо області: `openclaw sessions cleanup` обслуговує лише сховища сесій/транскрипти. Воно не очищає журнали запусків Cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration) і які пояснено в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). +- Примітка щодо області дії: `openclaw sessions cleanup` обслуговує сховища сеансів, стенограми та побічні файли траєкторій. Воно не обрізає журнали запусків Cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration), а також які описані в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). -- `--dry-run`: попередній перегляд того, скільки записів буде видалено/обмежено без запису. - - У текстовому режимі dry-run друкує таблицю дій для кожної сесії (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб ви могли побачити, що буде збережено, а що видалено. -- `--enforce`: застосувати обслуговування, навіть якщо `session.maintenance.mode` має значення `warn`. -- `--fix-missing`: видалити записи, для яких відсутні файли транскриптів, навіть якщо зазвичай вони ще не підпадали б під обмеження за віком/кількістю. -- `--active-key `: захистити конкретний активний ключ від витіснення через дисковий бюджет. -- `--agent `: запустити очищення для одного сховища налаштованого агента. -- `--all-agents`: запустити очищення для всіх сховищ налаштованих агентів. -- `--store `: запустити для конкретного файлу `sessions.json`. -- `--json`: вивести підсумок у JSON. З `--all-agents` вивід містить по одному підсумку для кожного сховища. +- `--dry-run`: попередньо показує, скільки записів буде вилучено/обмежено без запису. + - У текстовому режимі dry-run виводить таблицю дій по сеансах (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб ви могли побачити, що буде збережено, а що видалено. +- `--enforce`: застосовує обслуговування, навіть коли `session.maintenance.mode` має значення `warn`. +- `--fix-missing`: видаляє записи, у яких відсутні файли стенограм, навіть якщо вони зазвичай ще не підлягали б видаленню за віком/кількістю. +- `--active-key `: захищає конкретний активний ключ від витіснення через обмеження дискового бюджету. +- `--agent `: запускає очищення для одного налаштованого сховища агента. +- `--all-agents`: запускає очищення для всіх налаштованих сховищ агентів. +- `--store `: запускає очищення для конкретного файла `sessions.json`. +- `--json`: виводить підсумок у форматі JSON. Із `--all-agents` вивід містить по одному підсумку для кожного сховища. `openclaw sessions cleanup --all-agents --dry-run --json`: @@ -117,9 +118,9 @@ openclaw sessions cleanup --json Пов’язане: -- Конфігурація сесій: [Довідник конфігурації](/uk/gateway/config-agents#session) +- Конфігурація сеансів: [Довідник із конфігурації](/uk/gateway/config-agents#session) ## Пов’язане -- [Довідник CLI](/uk/cli) -- [Керування сесіями](/uk/concepts/session) +- [Довідка CLI](/uk/cli) +- [Керування сеансами](/uk/concepts/session) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 52bdaac5e..ebbaf91c7 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,126 +1,128 @@ --- read_when: - - Реалізація runtime-хуків провайдера, життєвого циклу каналу або пакунків пакетів + - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - Налагодження порядку завантаження plugin або стану реєстру - Додавання нової можливості plugin або plugin рушія контексту -summary: 'Внутрішні механізми архітектури Plugin: конвеєр завантаження, реєстр, runtime-хуки, HTTP-маршрути та довідкові таблиці' -title: Внутрішні механізми архітектури Plugin +summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' +title: Внутрішня архітектура Plugin x-i18n: - generated_at: "2026-04-27T16:06:47Z" + generated_at: "2026-04-27T20:08:47Z" model: gpt-5.4 provider: openai - source_hash: 72aac4073018a61d3731a8de54782c63c9ab6e3d21b3af95198adadf8be582f1 + source_hash: 2258835c881bf83d090898c0276f81b74d0a1ec471a85ab9d8f96125eb9cba6a source_path: plugins/architecture-internals.md workflow: 15 --- -Для публічної моделі можливостей, форм plugin та контрактів +Щодо публічної моделі можливостей, форм plugin і контрактів володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка — -довідник із внутрішніх механізмів: конвеєра завантаження, реєстру, runtime-хуків, -HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. +довідник щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків +середовища виконання, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження -Під час запуску OpenClaw приблизно робить таке: +Під час запуску OpenClaw приблизно виконує таке: 1. виявляє кандидатні корені plugin -2. зчитує маніфести native або сумісних пакетів і метадані пакетів -3. відхиляє небезпечних кандидатів +2. зчитує маніфести native або сумісних збірок і метадані пакетів +3. відхиляє небезпечні кандидати 4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. визначає, чи вмикати кожного кандидата -6. завантажує ввімкнені native-модулі: зібрані вбудовані модулі використовують native-завантажувач; - незібрані native-plugin використовують jiti -7. викликає native-хуки `register(api)` і збирає реєстрації в реєстр plugin -8. відкриває реєстр для поверхонь команд/runtime +6. завантажує ввімкнені native модулі: зібрані вбудовані модулі використовують native loader; + незібрані native plugin використовують jiti +7. викликає native хуки `register(api)` і збирає реєстрації до реєстру plugin +8. робить реєстр доступним для поверхонь команд/середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugins надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані plugin використовують `register`; для нових plugin надавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються, -коли точка входу виходить за межі кореня plugin, шлях має право запису для всіх, -або власник шляху виглядає підозріло для невбудованих plugins. +Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня plugin, шлях +доступний для запису всім, або право власності на шлях +виглядає підозріло для невбудованих plugin. ### Поведінка з пріоритетом маніфесту -Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для контрольної площини. OpenClaw використовує його, щоб: - ідентифікувати plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки - перевіряти `plugins.entries..config` -- доповнювати мітки/заповнювачі Control UI +- доповнювати підписи/заповнювачі в Control UI - показувати метадані встановлення/каталогу -- зберігати недорогі дескриптори активації та налаштування без завантаження runtime plugin +- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin -Для native-plugins runtime-модуль є частиною data plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. +Для native plugin модуль середовища виконання є частиною площини даних. Він реєструє +фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane. -Це лише метадані-дескриптори для планування активації та виявлення налаштування; -вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, +Необов’язкові блоки маніфесту `activation` і `setup` залишаються в контрольній площині. +Це лише дескриптори метаданих для планування активації та виявлення налаштування; +вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. +Перші споживачі живої активації тепер використовують підказки команд, каналів і провайдерів у маніфесті, щоб звузити завантаження plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugins, які володіють запитаною основною командою -- налаштування каналу/визначення plugin звужується до plugins, які володіють запитаним +- завантаження CLI звужується до plugin, які володіють запитаною основною командою +- налаштування каналу/визначення plugin звужується до plugin, які володіють запитаним id каналу -- явне визначення налаштування/runtime провайдера звужується до plugins, які володіють +- явне визначення налаштування/середовища виконання провайдера звужується до plugin, які володіють запитаним id провайдера -Планувальник активації надає і API лише з id для наявних викликів, і +Планувальник активації надає як API лише з ідентифікаторами для наявних викликачів, так і API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, -відокремлюючи явні підказки планувальника `activation.*` від резервного -володіння з маніфесту, такого як `providers`, `channels`, `commandAliases`, -`setup.providers`, `contracts.tools` і хуки. Це розділення причин є межею сумісності: -наявні метадані plugin і далі працюють, а новий код може виявляти широкі підказки -або резервну поведінку без зміни семантики завантаження runtime. +відокремлюючи явні підказки планувальника `activation.*` від резервного варіанта володіння з маніфесту, +такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Це розділення причин є межею сумісності: +наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки +або резервну поведінку без зміни семантики завантаження середовища виконання. -Виявлення налаштування тепер надає перевагу id, що належать дескриптору, таким як -`setup.providers` і `setup.cliBackends`, щоб звузити кандидатні plugins перед тим, як -повернутися до `setup-api` для plugins, яким і далі потрібні runtime-хуки на етапі налаштування. Списки -налаштування провайдера використовують маніфест `providerAuthChoices`, варіанти налаштування, -похідні від дескриптора, і метадані каталогу встановлення без завантаження runtime провайдера. Явний -`setup.requiresRuntime: false` є межею лише для дескриптора; якщо -`requiresRuntime` пропущено, для сумісності зберігається застарілий резервний шлях `setup-api`. Якщо більше -ніж один виявлений plugin заявляє про той самий нормалізований id провайдера налаштування або CLI-бекенда, +Виявлення налаштування тепер надає перевагу id, що належать дескриптору, таким як `setup.providers` і +`setup.cliBackends`, щоб звузити кандидатні plugin до того, як воно повернеться до +`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Списки налаштування провайдера +використовують маніфест `providerAuthChoices`, варіанти налаштування, похідні від дескриптора, +і метадані каталогу встановлення без завантаження середовища виконання провайдера. Явне +`setup.requiresRuntime: false` є межею лише для дескриптора; пропущене +`requiresRuntime` зберігає застарілий резервний варіант `setup-api` для сумісності. Якщо більше +ніж один виявлений plugin заявляє той самий нормалізований id провайдера налаштування або бекенда CLI, пошук налаштування відхиляє неоднозначного власника замість покладання на -порядок виявлення. Коли runtime налаштування все ж виконується, діагностика реєстру повідомляє -про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або CLI-бекендами, -зареєстрованими через setup-api, не блокуючи застарілі plugins. +порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє +про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або бекендами CLI, +зареєстрованими через setup-api, не блокуючи застарілі plugin. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі внутрішньопроцесні кеші для: +OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів - завантажених реєстрів plugin -Ці кеші зменшують пікове навантаження під час запуску та накладні витрати повторних команд. Їх безпечно -розглядати як короткоживучі кеші продуктивності, а не як постійне зберігання. +Ці кеші зменшують імпульсні витрати під час запуску та накладні витрати повторних команд. Їх безпечно +сприймати як короткочасні кеші продуктивності, а не як сховище стану. -Гарячі шляхи запуску Gateway мають віддавати перевагу поточному `PluginMetadataSnapshot`, -похідному `PluginLookUpTable` або явному реєстру маніфестів, переданому по ланцюжку викликів. Перевірка конфігурації, -автоматичне ввімкнення під час запуску та bootstrap plugin використовують той самий знімок, коли це можливо. -Для викликів, які все ще перебудовують метадані маніфесту зі збереженого індексу встановлених plugin, -OpenClaw також зберігає невеликий обмежений резервний кеш із ключами за встановленим індексом, формою запиту, політикою конфігурації, -runtime-коренями та сигнатурами файлів маніфесту/пакета. Цей кеш є лише -резервом для повторної реконструкції індексу встановлених plugin; це не змінюваний runtime- -реєстр plugin. +Гарячі шляхи запуску Gateway мають надавати перевагу поточному `PluginMetadataSnapshot`, +похідному `PluginLookUpTable` або явному реєстру маніфестів, переданому далі +ланцюжком викликів. Перевірка конфігурації, автоматичне ввімкнення під час запуску та bootstrap plugin використовують +той самий знімок, коли він доступний. Для викликачів, які все ще перебудовують метадані маніфесту +з постійного індексу встановлених plugin, OpenClaw також зберігає невеликий +обмежений резервний кеш, ключами якого є встановлений індекс, форма запиту, +політика конфігурації, корені середовища виконання та сигнатури файлів маніфесту/пакета. Цей кеш є лише +резервним варіантом для повторної реконструкції з установленого індексу; це не змінюваний реєстр +plugin середовища виконання. Примітка щодо продуктивності: -- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Встановіть `OPENCLAW_DISABLE_INSTALLED_PLUGIN_MANIFEST_REGISTRY_CACHE=1`, щоб вимкнути - лише резервний кеш реєстру маніфестів для індексу встановлених plugin. -- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Установіть `OPENCLAW_DISABLE_INSTALLED_PLUGIN_MANIFEST_REGISTRY_CACHE=1`, щоб вимкнути + лише резервний кеш реєстру маніфестів встановленого індексу. +- Налаштуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugins не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в +Завантажені plugin не змінюють безпосередньо довільні глобальні змінні core. Вони реєструються в центральному реєстрі plugin. Реєстр відстежує: @@ -136,21 +138,20 @@ runtime-коренями та сигнатурами файлів маніфес - фонові сервіси - команди, що належать plugin -Функції ядра потім читають із цього реєстру замість прямої взаємодії з модулями plugin. +Потім функції core читають із цього реєстру замість прямої взаємодії з модулями plugin. Це зберігає односпрямованість завантаження: - модуль plugin -> реєстрація в реєстрі -- runtime ядра -> споживання реєстру +- середовище виконання core -> споживання реєстру -Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра -потрібна лише одна точка інтеграції: «читати реєстр», а не «окремо обробляти кожен модуль plugin». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core +потрібна лише одна точка інтеграції: «читати реєстр», а не «робити особливу обробку для кожного модуля plugin». -## Колбеки прив’язки розмови +## Зворотні виклики прив’язування розмови -Plugins, які прив’язують розмову, можуть реагувати, коли погодження завершено. +Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку -схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язування схвалено або відхилено: ```ts export default { @@ -158,128 +159,128 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Для цього plugin + розмови тепер існує прив’язка. + // Тепер для цього plugin + розмови існує прив’язування. console.log(event.binding?.conversationId); return; } - // Запит було відхилено; очистьте будь-який локальний стан очікування. + // Запит було відхилено; очистіть будь-який локальний стан очікування. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля корисного навантаження колбека: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: вирішена прив’язка для схвалених запитів -- `request`: зведення початкового запиту, підказка від’єднання, id відправника та +- `binding`: вирішене прив’язування для схвалених запитів +- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей колбек призначений лише для сповіщення. Він не змінює, хто має право прив’язувати -розмову, і виконується після завершення обробки погодження ядром. +Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати +розмову, і виконується після завершення обробки погодження в core. -## Runtime-хуки провайдера +## Хуки середовища виконання провайдера -Plugins провайдера мають три рівні: +Plugin провайдера мають три шари: -- **Метадані маніфесту** для недорогого передruntime-пошуку: - `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: + `setup.providers[].envVars`, застарілий шар сумісності `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. - **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Runtime-хуки**: понад 40 необов’язкових хуків для auth, визначення моделі, - обгортання потоку, рівнів thinking, політики відтворення та кінцевих точок використання. Див. +- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделі, + обгортання потоку, рівні thinking, політику відтворення та кінцеві точки використання. Див. повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw і далі відповідає за загальний цикл агента, failover, обробку транскриптів і -політику інструментів. Ці хуки — поверхня розширення для специфічної поведінки провайдера -без потреби у повністю власному транспорті інференсу. +OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера +поведінки без потреби в цілком окремому транспорті інференсу. Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, -які мають бути видимі загальним шляхам auth/status/вибору моделі без -завантаження runtime plugin. Застарілий `providerAuthEnvVars` і далі читається адаптером сумісності -під час перехідного періоду, а невбудовані plugins, які його використовують, отримують +які мають бачити загальні шляхи auth/status/model-picker без +завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` усе ще зчитується адаптером сумісності +протягом перехідного вікна, а невбудовані plugin, які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера -має повторно використовувати env vars, профілі auth, auth на основі конфігурації та варіант -онбордингу з API-ключем іншого id провайдера. Використовуйте маніфест -`providerAuthChoices`, коли поверхні CLI онбордингу/вибору auth мають знати -id варіанта провайдера, мітки груп і просту auth-проводку з одним прапорцем без -завантаження runtime провайдера. Залишайте runtime провайдера -`envVars` для операторських підказок, таких як мітки онбордингу або змінні налаштування +має повторно використовувати env vars, профілі auth, auth на основі конфігурації та +варіант онбордингу API-ключа іншого id провайдера. Використовуйте маніфест +`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth мають знати +id варіанта провайдера, підписи груп і просту прив’язку auth через один прапорець без +завантаження середовища виконання провайдера. Зберігайте в середовищі виконання провайдера +`envVars` для підказок, орієнтованих на операторів, як-от підписи онбордингу або змінні налаштування OAuth client-id/client-secret. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, -які загальний резервний шлях shell-env, перевірки config/status або підказки налаштування мають бачити -без завантаження runtime каналу. +Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, керовані env, які +загальний резервний шлях shell-env, перевірки config/status або підказки налаштування мають бачити +без завантаження середовища виконання каналу. ### Порядок і використання хуків -Для plugins моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. +Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. Стовпець «Коли використовувати» — це короткий посібник для вибору. -| # | Хук | Що він робить | Коли використовувати | +| # | Хук | Що він робить | Коли використовувати | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | -| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не є хуком plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в межах того самого сімейства транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані helper-и сімейства Google також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні перезаписи native streaming-usage до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від кінцевої точки | -| 7 | `resolveConfigApiKey` | Визначає auth env-marker для конфігурованих провайдерів перед завантаженням runtime auth | Провайдер має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований AWS-резолвер env-marker | -| 8 | `resolveSyntheticAuth` | Виводить локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать провайдеру; типовим `persistence` є `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token-ів; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені заповнювачі синтетичних профілів нижче за auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають отримувати пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей із зовнішнього джерела | -| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Остаточний перезапис перед тим, як вбудований runner використовує визначену модель | Провайдеру потрібні перезаписи транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | -| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Виводить діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без додавання в ядро специфічних для провайдера правил | -| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт reasoning output | Провайдеру потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту | -| 22 | `resolveTransportTurnState` | Додає native-заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику cooldown сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху | -| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові метадані auth і потребує власну форму runtime-токена | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для власних кінцевих точок refresh або політики помилки refresh | Провайдер не відповідає спільним механізмам refresh `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібна власна підказка відновлення auth після помилки refresh | -| 27 | `matchesContextOverflowError` | Власний зіставник переповнення context window для провайдера | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутності auth | Провайдеру потрібна специфічна для провайдера підказка відновлення при відсутності auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих моделей із зовнішнього джерела плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховувати застарілі рядки з зовнішнього джерела або замінювати їх підказкою вендора | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в `models list` і засобах вибору | -| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей | -| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійкове thinking: увімкнено/вимкнено | -| 35 | `supportsXHighThinking` | Хук сумісності підтримки reasoning `xhigh` | Провайдер хоче підтримку `xhigh` лише для частини моделей | -| 36 | `resolveDefaultThinkingLevel` | Хук сумісності типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 37 | `isModernModelRef` | Зіставник modern-model для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний парсинг токена usage/quota або інші облікові дані для usage | -| 40 | `fetchUsageSnapshot` | Отримує й нормалізує специфічні для провайдера знімки usage/quota після визначення auth | Провайдеру потрібна специфічна для провайдера кінцева точка usage або парсер корисного навантаження | -| 41 | `createEmbeddingProvider` | Створює embedding-адаптер, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту, наприклад видалення блоків thinking | -| 43 | `sanitizeReplayHistory` | Перезаписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера перезаписи replay понад спільні helper-и Compaction | -| 44 | `validateReplayTurns` | Остаточна перевірка або зміна форми ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями `base URL` за замовчуванням | +| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або попередні псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдера в тому самому сімействі транспортів | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від кінцевої точки | +| 7 | `resolveConfigApiKey` | Визначає auth з маркером env для провайдерів конфігурації перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа з маркером env; `amazon-bedrock` також має тут вбудований резолвер маркера AWS env | +| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених заповнювачів синтетичного профілю порівняно з auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований раннер використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт core | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора, що працюють через інший сумісний транспорт | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | +| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою core | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований раннер | Провайдеру потрібне очищення схем для сімейства транспортів | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без додавання до core специфічних для провайдера правил | +| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт виводу reasoning | Провайдеру потрібен tagged reasoning/фінальний вивід замість native полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху | +| 24 | `formatApiKey` | Форматер auth-профілю: збережений профіль перетворюється на рядок `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує користувацької форми токена в середовищі виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилок оновлення | Провайдер не підходить під спільні засоби оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка щодо виправлення, яка додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні рекомендації з виправлення auth після помилки оновлення | +| 27 | `matchesContextOverflowError` | Матчер переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не помітять | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з перевищенням ліміту, перевантаженням тощо | +| 29 | `isCacheTtlEligible` | Політика TTL кешу промптів для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутності auth | Провайдеру потрібна власна підказка відновлення для випадків відсутності auth | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream записи або замінити їх підказкою вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в майбутньому в `models list` і селекторах | +| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, підписи відображення та значення за замовчуванням, специфічні для моделі | Провайдер пропонує користувацьку шкалу thinking або двійковий підпис для вибраних моделей | +| 34 | `isBinaryThinking` | Хук сумісності перемикача reasoning увімкнено/вимкнено | Провайдер підтримує лише двійковий режим thinking увімкнено/вимкнено | +| 35 | `supportsXHighThinking` | Хук сумісності підтримки reasoning `xhigh` | Провайдер хоче підтримку `xhigh` лише для частини моделей | +| 36 | `resolveDefaultThinkingLevel` | Хук сумісності рівня `/think` за замовчуванням | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | +| 37 | `isModernModelRef` | Матчер modern-model для фільтрів live-профілів і вибору для smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту | +| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір токенів usage/quota або інші облікові дані usage | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки usage/quota після визначення auth | Провайдеру потрібна специфічна для провайдера кінцева точка usage або парсер корисного навантаження | +| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка memory embedding має належати plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні допоміжні засоби Compaction | +| 44 | `validateReplayTurns` | Фінальна перевірка або переформування ходів replay перед вбудованим раннером | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -plugin провайдера, що збігся, а потім переходять до інших plugin провайдерів із підтримкою хуків, -доки один із них фактично не змінить id моделі або transport/config. Це дає змогу -shim-прошаркам alias/compat провайдера працювати без вимоги, щоб виклик знав, який -саме вбудований plugin володіє цим перезаписом. Якщо жоден хук провайдера не перезапише -підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google -усе одно застосує це очищення сумісності. +відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, здатних до хуків, +доки один із них справді не змінить id моделі або transport/config. Це зберігає +працездатність shim для alias/compat провайдерів без вимоги, щоб викликач знав, який +вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосовує +це очищення сумісності. -Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, +Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів, це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, -яка все ще працює в межах звичайного циклу inference OpenClaw. +яка все ще працює в межах звичайного циклу інференсу OpenClaw. ### Приклад провайдера @@ -337,45 +338,45 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugins провайдерів поєднують наведені вище хуки, щоб відповідати потребам -кожного вендора щодо каталогу, auth, thinking, replay та usage. Авторитетний набір хуків -живе разом із кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не -дзеркально відтворює список. +Вбудовані plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора +щодо каталогу, auth, thinking, replay і usage. Авторитетний набір хуків живе разом +із кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не +віддзеркалює список. OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із - `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати id моделей - із зовнішнього джерела раніше за статичний каталог OpenClaw. + `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream + model id раніше за статичний каталог OpenClaw. GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`. + `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`. Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають провайдерам змогу - підключати політику транскриптів через `buildReplayPolicy` замість того, щоб кожен plugin + `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам + підключатися до політики транскриптів через `buildReplayPolicy` замість того, щоб кожен plugin повторно реалізовував очищення. `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і використовують спільний цикл inference. + `volcengine` реєструють лише `catalog` і використовують спільний цикл інференсу. - - Бета-заголовки, `/fast` / `serviceTier` і `context1m` розміщено всередині - публічного шва `api.ts` / `contract-api.ts` plugin Anthropic + + Бета-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в + публічному seam `api.ts` / `contract-api.ts` plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. -## Runtime-helper-и +## Допоміжні засоби середовища виконання -Plugins можуть отримувати доступ до вибраних helper-ів ядра через `api.runtime`. Для TTS: +Plugin можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -396,14 +397,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію ядра `messages.tts` і вибір провайдера. -- Повертає PCM-аудіобуфер + частоту дискретизації. Plugins мають виконувати ресемплінг/кодування для провайдерів. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS із core для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію core `messages.tts` і вибір провайдера. +- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin повинні виконувати ресемплінг/кодування для провайдерів. - `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору. -- Списки голосів можуть містити багатші метадані, як-от locale, стать і теги характеру для засобів вибору, обізнаних про провайдера. -- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- Списки голосів можуть містити багатші метадані, наприклад locale, gender і теги personality для засобів вибору, обізнаних про провайдера. +- Сьогодні телефонію підтримують OpenAI та ElevenLabs. Microsoft — ні. -Plugins також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -423,15 +424,15 @@ api.registerSpeechProvider({ Примітки: -- Залишайте політику TTS, резервний шлях і доставлення відповіді в ядрі. -- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить вендору. +- Зберігайте політику TTS, fallback і доставку відповіді в core. +- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. - Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння — орієнтована на компанію: один plugin вендора може володіти +- Бажана модель володіння орієнтована на компанію: один plugin вендора може володіти текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugins реєструють одного типізованого -провайдера розуміння медіа замість узагальненого набору ключ/значення: +Для розуміння зображень/аудіо/відео plugin реєструють один типізований +провайдер media-understanding замість узагальненого сховища ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -445,16 +446,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Залишайте оркестрацію, резервний шлях, конфігурацію та підключення каналів у ядрі. -- Залишайте поведінку вендора в plugin провайдера. -- Розширення шляхом додавання має залишатися типізованим: нові необов’язкові методи, нові необов’язкові +- Зберігайте оркестрацію, fallback, config і прив’язку каналів у core. +- Зберігайте поведінку вендора в plugin провайдера. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже наслідує той самий шаблон: - - ядро володіє контрактом можливості та runtime-helper-ом - - plugins вендорів реєструють `api.registerVideoGenerationProvider(...)` - - plugins функцій/каналів використовують `api.runtime.videoGeneration.*` +- Генерація відео вже дотримується тієї самої схеми: + - core володіє контрактом можливості та допоміжним засобом середовища виконання + - plugin вендора реєструють `api.registerVideoGenerationProvider(...)` + - plugin функцій/каналів споживають `api.runtime.videoGeneration.*` -Для runtime-helper-ів розуміння медіа plugins можуть викликати: +Для допоміжних засобів середовища виконання media-understanding plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -469,14 +470,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugins можуть використовувати або runtime -розуміння медіа, або старіший псевдонім STT: +Для транскрибування аудіо plugin можуть використовувати або середовище виконання media-understanding, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Необов’язково, коли MIME неможливо надійно визначити: + // Необов’язково, коли MIME не вдається надійно визначити: mime: "audio/ogg", }); ``` @@ -485,11 +486,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервних шляхів провайдера. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створюється (наприклад, для пропущеного/непідтримуваного вводу). +- Використовує конфігурацію аудіо media-understanding із core (`tools.media.audio`) та порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, вхід пропущено/не підтримується). - `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. -Plugins також можуть запускати фонові виконання субагентів через `api.runtime.subagent`: +Plugin також можуть запускати фонові запуски субагента через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -503,15 +504,15 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. -- OpenClaw враховує ці поля перевизначення лише для довірених викликів. -- Для резервних запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски субагента з недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу на резервний шлях. -- Сесії субагентів, створені plugin, позначаються id plugin, що їх створив. Резервний шлях `api.runtime.subagent.deleteSession(...)` може видаляти лише ці сесії, що належать plugin; довільне видалення сесій, як і раніше, потребує запиту Gateway з областю дії адміністратора. +- `provider` і `model` є необов’язковими перевизначеннями для окремого запуску, а не постійними змінами сесії. +- OpenClaw враховує ці поля перевизначення лише для довірених викликачів. +- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. +- Запуски субагента з недовірених plugin усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять у fallback. +- Сесії субагента, створені plugin, позначаються id plugin, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише такі сесії, що належать власнику; довільне видалення сесій, як і раніше, потребує запиту Gateway з адміністраторською областю дії. -Для вебпошуку plugins можуть використовувати спільний runtime-helper замість -звернення до підключення інструмента агента: +Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість +занурення у прив’язку інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -527,14 +528,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugins також можуть реєструвати провайдерів вебпошуку через +Plugin також можуть реєструвати провайдерів web-search через `api.registerWebSearchProvider(...)`. Примітки: -- Залишайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. -- Використовуйте провайдерів вебпошуку для специфічних транспортів пошуку вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugins функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core. +- Використовуйте провайдерів web-search для специфічних для вендора пошукових транспортів. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -549,12 +550,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. -- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: показує доступних провайдерів генерації зображень і їхні можливості. ## HTTP-маршрути Gateway -Plugins можуть відкривати HTTP-ендпойнти через `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP-ендпойнти через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -572,140 +573,143 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth, керованої plugin, / перевірки Webhook. +- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/перевірки Webhook, якими керує plugin. - `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. -- `handler`: повертає `true`, коли маршрут обробив запит. +- `replaceExisting`: необов’язкове. Дає змогу тому самому plugin замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і це спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. - Маршрути plugin мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не задано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки передачі керування `exact`/`prefix` мають залишатися лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook-ів / перевірки підписів, керованих plugin, а не для привілейованих helper-викликів Gateway. -- Маршрути `auth: "gateway"` працюють у межах області runtime запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів plugin на рівні `operator.write`, навіть якщо виклик надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів plugin з ідентичністю, область runtime повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут plugin з auth gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю й задокументуйте явний контракт заголовка `x-openclaw-scopes`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише на одному й тому самому рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області дії середовища виконання оператора. Вони призначені для Webhook/перевірки підписів, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` працюють в межах області дії середовища виконання запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області дії середовища виконання маршрутів plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з носієм ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes`, лише коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів plugin із носієм ідентичності, область дії середовища виконання повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут plugin з auth gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з носієм ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення нових plugins використовуйте вузькі підшляхи SDK замість -монолітного кореневого barrel `openclaw/plugin-sdk`. -Основні підшляхи: +Під час розробки нових plugin використовуйте вузькі підшляхи SDK замість монолітного +кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: -| Підшлях | Призначення | -| ---------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | -| `openclaw/plugin-sdk/channel-core` | Helper-и входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні helper-и та umbrella-контракт | -| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) | +| Підшлях | Призначення | +| ----------------------------------- | -------------------------------------------------- | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби для входу/побудови каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | +| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) | -Plugins каналів вибирають із сімейства вузьких швів — `channel-setup`, +Плагіни каналів вибирають із сімейства вузьких seam — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, `channel-targets` і `channel-actions`. Поведінку погодження слід консолідувати -в одному контракті `approvalCapability`, а не змішувати між не пов’язаними -полями plugin. Див. [Plugins каналів](/uk/plugins/sdk-channel-plugins). +навколо одного контракту `approvalCapability`, а не змішувати її між не пов’язаними +полями plugin. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). -Runtime- і config-helper-и розміщені у відповідних підшляхах `*-runtime` -(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, -`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо). +Допоміжні засоби середовища виконання та конфігурації розміщені у відповідних сфокусованих підшляхах `*-runtime` +(`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, +`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`, +`channel-activity-runtime` тощо). Віддавайте перевагу `config-types`, +`plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` замість +широкого barrel сумісності `config-runtime`. -`openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для -старіших plugins. Новий код має імпортувати натомість вужчі загальні примітиви. +`openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime` +і `openclaw/plugin-sdk/infra-runtime` — це застарілі shim сумісності для +старіших plugin. Новий код має імпортувати вужчі загальні примітиви. Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): - `index.js` — точка входу вбудованого plugin -- `api.js` — barrel helper-ів/типів -- `runtime-api.js` — barrel лише для runtime -- `setup-entry.js` — точка входу plugin для setup +- `api.js` — barrel допоміжних засобів/типів +- `runtime-api.js` — barrel лише для середовища виконання +- `setup-entry.js` — точка входу plugin для налаштування -Зовнішні plugins мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета plugin з ядра або з іншого plugin. -Точки входу, завантажені через facade, віддають перевагу активному знімку runtime-конфігурації, якщо він існує, -а потім повертаються до визначеного файлу конфігурації на диску. +Зовнішні plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета plugin із core або з іншого plugin. +Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він +існує, а потім повертаються до визначеного файлу конфігурації на диску. -Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding` -і `speech`, існують, оскільки вбудовані plugins уже використовують їх сьогодні. Вони не є -автоматично зовнішніми контрактами, замороженими на довгий строк — перевіряйте відповідну сторінку -довідки SDK, коли покладаєтесь на них. +Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` +і `speech`, існують, бо вбудовані plugin використовують їх уже сьогодні. Це не +автоматично довгостроково зафіксовані зовнішні контракти — перевіряйте відповідну довідкову +сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugins мають володіти внесками до схеми канально-специфічного `describeMessageTool(...)` -для немеседжевих примітивів, як-от реакції, прочитання та опитування. -Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation` -замість native-полів кнопок, компонентів, блоків або карток конкретного провайдера. -Див. [Message Presentation](/uk/plugins/message-presentation) для контракту, -правил резервного шляху, мапування провайдерів і контрольного списку автора plugin. +Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, +для немеседжних примітивів, таких як реакції, читання та опитування. +Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` +замість native полів кнопок, компонентів, блоків або карток, специфічних для провайдера. +Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, +правилами fallback, зіставленням провайдерів і контрольним списком для авторів plugin. -Plugins із підтримкою надсилання оголошують, що саме вони можуть відобразити, через можливості повідомлень: +Plugin із підтримкою надсилання оголошують, що вони можуть відтворювати, через можливості повідомлень: -- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів закріпленого доставлення +- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів закріпленої доставки -Ядро вирішує, чи відображати представлення native-способом, чи деградувати його до тексту. -Не відкривайте шляхи обходу до native UI провайдера з загального інструмента повідомлень. -Застарілі helper-и SDK для старих native-схем залишаються експортованими для наявних -сторонніх plugins, але нові plugins не мають їх використовувати. +Core вирішує, чи відтворювати подання native способом, чи деградувати його до тексту. +Не відкривайте обхідні шляхи native UI, специфічні для провайдера, із загального інструмента повідомлень. +Застарілі допоміжні засоби SDK для старих native схем залишаються експортованими для наявних +сторонніх plugin, але нові plugin не повинні їх використовувати. -## Визначення цілі каналу +## Визначення цілей каналу -Plugins каналів мають володіти канально-специфічною семантикою цілей. Залишайте спільний -вихідний хост узагальненим і використовуйте поверхню messaging adapter для правил провайдера: +Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +хост вихідного трафіку загальним і використовуйте поверхню messaging adapter для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи слід трактувати нормалізовану ціль - як `direct`, `group` або `channel` до пошуку в директорії. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи має - вхідне значення одразу переходити до визначення id-подібної цілі замість пошуку в директорії. +- `messaging.inferTargetChatType({ to })` вирішує, чи слід нормалізовану ціль + трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи + слід входу одразу перейти до визначення id-подібної цілі замість пошуку в каталозі. - `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли - ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або - після промаху по директорії. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, + core потрібне фінальне визначення, що належить провайдеру, після нормалізації або + після промаху в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічною для провайдера, після того як ціль визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають ухвалюватися до - пошуку peers/groups. +- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають ухвалюватися до + пошуку peer/group. - Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі». -- Використовуйте `resolveTarget` для резервного шляху нормалізації, специфічного для провайдера, а не для - широкого пошуку в директорії. -- Зберігайте native-id провайдера, як-от id чату, id потоку, JID, handles та room id, - всередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. +- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для + широкого пошуку в каталозі. +- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle і room + id, всередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Директорії на основі конфігурації +## Каталоги на основі конфігурації -Plugins, які отримують записи директорії з конфігурації, мають зберігати цю логіку в -plugin і повторно використовувати спільні helper-и з +Plugin, які формують записи каталогу з конфігурації, мають тримати цю логіку в +plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, такі як: -- DM-peers, керовані allowlist +- peer DM, керовані allowlist - налаштовані мапи каналів/груп -- статичні резервні шляхи директорії в межах облікового запису +- статичні резервні варіанти каталогу з областю дії облікового запису -Спільні helper-и в `directory-runtime` обробляють лише загальні операції: +Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: - фільтрацію запитів -- застосування ліміту -- helper-и дедуплікації/нормалізації +- застосування лімітів +- допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися -в реалізації plugin. +Специфічні для каналу перевірка облікового запису та нормалізація id мають залишатися в +реалізації plugin. ## Каталоги провайдерів -Plugins провайдерів можуть визначати каталоги моделей для inference через +Plugin провайдерів можуть визначати каталоги моделей для інференсу через `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -714,58 +718,57 @@ Plugins провайдерів можуть визначати каталоги - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли plugin володіє специфічними для провайдера id моделей, типовими значеннями `base URL` -або метаданими моделей, захищеними auth. +Використовуйте `catalog`, коли plugin володіє специфічними для провайдера model id, значеннями `base URL` +за замовчуванням або метаданими моделей, що залежать від auth. `catalog.order` визначає, коли каталог plugin зливається відносно вбудованих неявних провайдерів OpenClaw: -- `simple`: звичайні провайдери з API-ключем або на основі env -- `profile`: провайдери, що з’являються, коли існують профілі auth -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера +- `simple`: звичайні провайдери на основі API-ключа або env +- `profile`: провайдери, які з’являються, коли існують auth-профілі +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі конфлікту ключів, тож plugins можуть навмисно перевизначати +Пізніші провайдери перемагають у разі колізії ключів, тож plugin можуть навмисно перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` і далі працює як застарілий псевдонім +- `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Лише читання для перевірки каналу +## Інспектування каналу лише для читання -Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. +Якщо ваш plugin реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і може швидко завершуватися з помилкою, коли обов’язкові секрети відсутні. -- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` та потоки - repair doctor/config, не повинні матеріалізовувати runtime-облікові дані лише для того, - щоб описати конфігурацію. +- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані + повністю матеріалізовано, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config + repair, не повинні вимагати матеріалізації облікових даних середовища виконання лише для + опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- За потреби включає поля джерела/статусу облікових даних, як-от: +- Містить поля джерела/статусу облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання. Для команд на кшталт status достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. -## Пакети пакетів +## Пакетні набори -Каталог plugin може містити `package.json` з `openclaw.extensions`: +Каталог plugin може містити `package.json` із `openclaw.extensions`: ```json { @@ -777,68 +780,67 @@ Plugins провайдерів можуть визначати каталоги } ``` -Кожен запис стає plugin. Якщо пакет перелічує кілька extensions, id plugin +Кожен запис стає plugin. Якщо пакет перераховує кілька extensions, id plugin стає `name/`. -Якщо ваш plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб +Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin -після розв’язання symlink. Записи, які виходять за межі каталогу пакета, +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу plugin +після визначення symlink. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` встановлює залежності plugin через -локальний для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, -без dev dependencies у runtime), ігноруючи успадковані глобальні налаштування npm install. -Підтримуйте дерева залежностей plugin «чистими JS/TS» і уникайте пакетів, яким потрібні -збірки через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin за допомогою +локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, +без dev dependencies у середовищі виконання), ігноруючи успадковані глобальні налаштування встановлення npm. +Зберігайте дерева залежностей plugin як "pure JS/TS" і уникайте пакетів, яким потрібні +збирання через `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого channel plugin, або -коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повної точки входу plugin. Це робить запуск і setup легшими, -коли основна точка входу plugin також підключає інструменти, хуки або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або +коли plugin каналу ввімкнено, але його ще не налаштовано, він завантажує `setupEntry` +замість повної точки входу plugin. Це робить запуск і налаштування легшими, +коли ваша основна точка входу plugin також підключає інструменти, хуки або інший код +лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести channel plugin на той самий шлях `setupEntry` під час -передслухової фази запуску gateway, навіть якщо канал уже налаштований. +може перевести plugin каналу на той самий шлях `setupEntry` під час +фази запуску gateway до початку прослуховування, навіть коли канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне слухати. На практиці це означає, що точка входу setup -має реєструвати всі можливості, що належать каналу, від яких залежить запуск, наприклад: +до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування +має реєструвати кожну можливість, що належить каналу й від якої залежить запуск, наприклад: -- саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати -- будь-які методи gateway, інструменти або сервіси, які мають існувати впродовж того самого вікна +- власне реєстрацію каналу +- будь-які HTTP-маршрути, які мають бути доступними до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому самому вікні -Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте -цей прапорець. Залиште plugin на типовій поведінці й дозвольте OpenClaw завантажувати +Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте +цей прапорець. Залиште plugin із типовою поведінкою й дозвольте OpenClaw завантажити повну точку входу під час запуску. -Вбудовані канали також можуть публікувати helper-и поверхні контракту лише для setup, які ядро -може використовувати до завантаження повного runtime каналу. Поточна поверхня -просування setup така: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які core +може використовувати до завантаження повного середовища виконання каналу. Поточна поверхня просування налаштування: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу -конфігурацію однокористувацького каналу в `channels..accounts.*` без -завантаження повної точки входу plugin. Поточний вбудований приклад — Matrix: -він переносить у просунутий іменований обліковий запис лише ключі auth/bootstrap, -коли іменовані облікові записи вже існують, і може зберегти налаштований -неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати +Core використовує цю поверхню, коли йому потрібно підвищити застарілу конфігурацію +каналу з одним обліковим записом до `channels..accounts.*` без завантаження повної точки входу plugin. +Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap до +іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може зберегти +налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. -Ці адаптери patch setup зберігають ліниве виявлення поверхні контракту для вбудованих компонентів. Час -імпорту залишається малим; поверхня просування завантажується лише під час першого використання -замість повторного входу в запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту вбудованих каналів. Час +імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання, а не +повторно входить у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають Gateway RPC-методи, тримайте їх на -префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`, +Коли ці поверхні запуску включають Gateway RPC methods, залишайте їх на +префіксі, специфічному для plugin. Простори назв адміністратора core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо plugin запитує вужчу область. +до `operator.admin`, навіть якщо plugin запитує вужчу область дії. Приклад: @@ -857,8 +859,8 @@ Plugins провайдерів можуть визначати каталоги ### Метадані каталогу каналу -Plugins каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` та -підказки встановлення через `openclaw.install`. Це дозволяє не зберігати дані в каталозі ядра. +Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` та +підказки встановлення через `openclaw.install`. Це дозволяє core не містити даних каталогу. Приклад: @@ -873,7 +875,7 @@ Plugins каналів можуть оголошувати метадані setu "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", + "blurb": "Самостійно розгорнутий чат через webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -886,68 +888,68 @@ Plugins каналів можуть оголошувати метадані setu } ``` -Корисні поля `openclaw.channel` понад мінімальний приклад: +Корисні поля `openclaw.channel` поза мінімальним прикладом: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначення тексту посилання для посилання на документацію -- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати +- `docsLabel`: перевизначає текст посилання для посилання на документацію +- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має перевершувати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору -- `markdownCapable`: позначає канал як сумісний з markdown для рішень щодо форматування вихідних повідомлень -- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних засобів вибору setup/configure, коли встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документацією +- `markdownCapable`: позначає канал як здатний до Markdown для рішень щодо форматування вихідних повідомлень +- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` +- `quickstartAllowFrom`: підключає канал до стандартного потоку швидкого старту `allowFrom` - `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис - `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в одне з таких місць: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). +Додайте JSON-файл до одного з таких шляхів: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комами/крапками з комою/через `PATH`). Кожен файл має -містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. +один або кілька JSON-файлів (розділених комами/крапкою з комою/`PATH`). Кожен файл має +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми ключа `"entries"`. -Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають -нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці -нормалізовані факти визначають, чи є npm-специфікація точною версією або плаваючим селектором, -чи присутні очікувані метадані цілісності та чи доступний також локальний шлях джерела. -Коли відома ідентичність каталогу/пакета, нормалізовані факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. -Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, яке -недоступне, а також коли метадані цілісності npm присутні без дійсного npm- -джерела. Споживачі мають ставитися до `installSource` як до додаткового необов’язкового поля, щоб -вручну створені записи й shim-и каталогів не мусили його синтезувати. +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів показують +нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані +факти визначають, чи є npm spec точною версією чи плаваючим селектором, +чи присутні очікувані метадані цілісності, і чи також доступний локальний шлях до джерела. +Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я +npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний +або вказує на джерело, яке недоступне, і коли метадані цілісності npm присутні без дійсного +джерела npm. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб +записи, створені вручну, і shim каталогу не мусили його синтезувати. Це дає змогу онбордингу та діагностиці пояснювати стан площини джерела без -імпорту runtime plugin. +імпорту середовища виконання plugin. -Офіційні зовнішні npm-записи мають надавати перевагу точному `npmSpec` разом із -`expectedIntegrity`. Голі назви пакетів і dist-tag-и все ще працюють для +Офіційні зовнішні записи npm мають віддавати перевагу точному `npmSpec` разом із +`expectedIntegrity`. Голі назви пакетів і dist-tag усе ще працюють для сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися -до pinned- та integrity-checked-встановлень без порушення роботи наявних plugins. -Коли онбординг встановлює з локального шляху каталогу, він записує керований plugin -у запис індексу plugin із `source: "path"` і workspace-відносним +до закріплених установлень із перевіркою цілісності, не ламаючи наявні plugin. +Коли онбординг установлює з локального шляху каталогу, він записує керований plugin +запис індексу plugin із `source: "path"` і відносним до робочого простору `sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в -`plugins.load.paths`; запис встановлення уникає дублювання шляхів локальної робочої станції -в довготривалій конфігурації. Це зберігає видимість локальних розробницьких встановлень для -діагностики площини джерела без додавання другої поверхні розкриття сирих шляхів файлової системи. -Збережений індекс plugin `plugins/installs.json` є джерелом істини для встановлення й може -оновлюватися без завантаження runtime-модулів plugin. -Його мапа `installRecords` є довговічною, навіть коли маніфест plugin відсутній або -недійсний; його масив `plugins` — це перебудовуваний вигляд маніфесту/кешу. +`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів файлової системи +робочої станції в довготривалій конфігурації. Це зберігає локальні встановлення для розробки видимими для +діагностики площини джерела без додавання другої сирої поверхні розкриття шляхів +файлової системи. Постійний індекс plugin `plugins/installs.json` є джерелом істини для встановлення +і може бути оновлений без завантаження модулів середовища виконання plugin. +Його мапа `installRecords` є довговічною навіть коли маніфест plugin відсутній або +недійсний; його масив `plugins` є перебудовуваним представленням маніфесту/кешу. -## Plugins рушія контексту +## Plugin рушія контексту -Plugins рушія контексту володіють оркестрацією контексту сесії для ingеst, assembly +Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly і Compaction. Реєструйте їх зі свого plugin через `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. +конвеєр контексту, а не просто додати пошук у пам’яті або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1013,45 +1015,45 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потрібна поведінка, яка не вписується в поточний API, не обходьте -систему plugin через приватне пряме звернення. Додайте відсутню можливість. +Коли plugin потребує поведінки, яка не вкладається в поточний API, не обходьте +систему plugin приватним глибоким доступом. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним шляхом, злиттям конфігурації, - життєвим циклом, семантикою для каналів і формою runtime-helper-а. -2. додайте типізовані поверхні реєстрації/runtime для plugin +1. визначте контракт core + Вирішіть, якою спільною поведінкою має володіти core: policy, fallback, злиття config, + lifecycle, семантика, видима для каналу, і форма допоміжного засобу середовища виконання. +2. додайте типізовані поверхні реєстрації plugin/середовища виконання Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть ядро + споживачів каналів/функцій - Канали та plugins функцій мають використовувати нову можливість через ядро, +3. підключіть core + споживачів каналів/функцій + Канали й plugin функцій мають споживати нову можливість через core, а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендорів - Потім plugins вендорів реєструють свої бекенди для цієї можливості. +4. зареєструйте реалізації вендора + Потім plugin вендора реєструють свої бекенди для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб з часом володіння та форма реєстрації залишалися явними. + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається думкоцентричним, не стаючи жорстко прив’язаним до -світогляду одного провайдера. Див. [Кулінарну книгу можливостей](/uk/plugins/architecture), -щоб отримати конкретний перелік файлів і розгорнутий приклад. +Саме так OpenClaw залишається системою з чіткою позицією, не стаючи жорстко прив’язаною до +світогляду одного провайдера. Див. [Кулінарна книга можливостей](/uk/plugins/architecture), +щоб побачити конкретний перелік файлів і готовий приклад. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має разом зачіпати такі -поверхні: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: -- типи контракту ядра в `src//types.ts` -- runner/runtime-helper ядра в `src//runtime.ts` -- поверхню реєстрації API plugin в `src/plugins/types.ts` -- підключення реєстру plugin в `src/plugins/registry.ts` -- відкриття runtime plugin в `src/plugins/runtime/*`, коли plugins функцій/каналів - мають її використовувати -- helper-и capture/test в `src/test-utils/plugin-registration.ts` -- твердження володіння/контракту в `src/plugins/contracts/registry.ts` -- документацію для операторів/plugin у `docs/` +- типів контракту core у `src//types.ts` +- раннера/допоміжного засобу середовища виконання core у `src//runtime.ts` +- поверхні реєстрації API plugin у `src/plugins/types.ts` +- підключення реєстру plugin у `src/plugins/registry.ts` +- експонування середовища виконання plugin у `src/plugins/runtime/*`, коли plugin функцій/каналів + мають це споживати +- допоміжних засобів capture/test у `src/test-utils/plugin-registration.ts` +- перевірок володіння/контракту в `src/plugins/contracts/registry.ts` +- документації для операторів/plugin у `docs/` -Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, це зазвичай означає, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1059,7 +1061,7 @@ export default function (api) { Мінімальний шаблон: ```ts -// контракт ядра +// контракт core export type VideoGenerationProviderPlugin = { id: string; label: string; @@ -1075,7 +1077,7 @@ api.registerVideoGenerationProvider({ }, }); -// спільний runtime-helper для plugins функцій/каналів +// спільний допоміжний засіб середовища виконання для plugin функцій/каналів const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1090,14 +1092,14 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- ядро володіє контрактом можливості + оркестрацією -- plugins вендорів володіють реалізаціями вендорів -- plugins функцій/каналів використовують runtime-helper-и +- core володіє контрактом можливості + оркестрацією +- plugin вендора володіють реалізаціями вендора +- plugin функцій/каналів споживають допоміжні засоби середовища виконання - тести контракту зберігають явність володіння ## Пов’язане -- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель і форми можливостей +- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми - [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugins](/uk/plugins/building-plugins) +- [Створення plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 27fe76b5c..0cdaf7ae9 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -2,113 +2,84 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви використовували api.registerEmbeddedExtensionFactory до OpenClaw 2026.4.25 - - Ви оновлюєте Plugin до сучасної архітектури плагінів - - Ви підтримуєте зовнішній Plugin OpenClaw + - Ви використовували `api.registerEmbeddedExtensionFactory` до OpenClaw 2026.4.25 + - Ви оновлюєте плагін до сучасної архітектури плагінів + - Ви підтримуєте зовнішній плагін OpenClaw sidebarTitle: Migrate to SDK -summary: Перехід із застарілого шару зворотної сумісності на сучасний Plugin SDK -title: Міграція Plugin SDK +summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний SDK плагінів +title: Міграція SDK плагінів x-i18n: - generated_at: "2026-04-27T14:19:28Z" + generated_at: "2026-04-27T20:08:58Z" model: gpt-5.4 provider: openai - source_hash: 0ef7690f48fae9286ae2d994e9e85af63f20eddf0d6cfef7c51be72929afd006 + source_hash: 19e2e5af310234544a3e1ae7a440554f9134f407c6bc896e58b134ed4376b2b3 source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів -зі сфокусованими, документованими імпортами. Якщо ваш Plugin було створено до -нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів зі сфокусованими, задокументованими імпортами. Якщо ваш плагін було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система плагінів надавала дві широкі поверхні, які дозволяли Plugin імпортувати -все необхідне з однієї точки входу: +Стара система плагінів надавала дві дуже широкі поверхні, які дозволяли плагінам імпортувати все необхідне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки - допоміжних функцій. Його було запроваджено, щоб старіші плагіни на основі хуків - продовжували працювати під час розробки нової архітектури плагінів. -- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до - допоміжних функцій на боці хоста, таких як вбудований runner агента. -- **`api.registerEmbeddedExtensionFactory(...)`** — вилучений хук для вбудованих - розширень лише для Pi, який міг спостерігати за подіями embedded-runner, такими як - `tool_result`. +- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував десятки допоміжних функцій. Його було запроваджено, щоб старіші hook-орієнтовані плагіни продовжували працювати, поки будувалася нова архітектура плагінів. +- **`openclaw/plugin-sdk/infra-runtime`** — широкий barrel допоміжних функцій runtime, який поєднував системні події, стан Heartbeat, черги доставки, допоміжні функції fetch/proxy, файлові допоміжні функції, типи approvals і не пов’язані між собою утиліти. +- **`openclaw/plugin-sdk/config-runtime`** — широкий barrel сумісності конфігурації, який під час вікна міграції все ще містить застарілі прямі допоміжні функції load/write. +- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до helper-функцій на боці хоста, таких як вбудований runner агента. +- **`api.registerEmbeddedExtensionFactory(...)`** — вилучений hook для вбудованих розширень лише для Pi, який міг спостерігати за подіями embedded runner, такими як `tool_result`. -Широкі поверхні імпорту тепер **застарілі**. Вони все ще працюють під час виконання, -але нові Plugin не повинні їх використовувати, а наявним Plugin слід виконати міграцію до -того, як у наступному мажорному випуску їх буде вилучено. API реєстрації фабрики -вбудованих розширень лише для Pi було вилучено; натомість використовуйте middleware результатів інструментів. +Широкі поверхні імпорту тепер **застарілі**. Вони все ще працюють під час runtime, але нові плагіни не повинні їх використовувати, а наявним плагінам слід виконати міграцію до того, як наступний мажорний реліз їх вилучить. API реєстрації factory вбудованих розширень лише для Pi було вилучено; натомість використовуйте middleware для результатів інструментів. -OpenClaw не вилучає і не переосмислює документовану поведінку Plugin у тій самій -зміні, яка вводить заміну. Зміни контракту, що порушують сумісність, спочатку -мають пройти через адаптер сумісності, діагностику, документацію та вікно застарівання. -Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки -реєстрації під час виконання. +OpenClaw не вилучає і не переосмислює задокументовану поведінку плагінів у тій самій зміні, яка вводить заміну. Зміни контракту, що ламають сумісність, спочатку мають проходити через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API setup, hooks і поведінки реєстрації runtime. - Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних випусків. - Plugin, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. - Реєстрації фабрики вбудованих розширень лише для Pi уже більше не завантажуються. + Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних релізів. + Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. + Реєстрації factory вбудованих розширень лише для Pi вже більше не завантажуються. ## Чому це змінилося -Старий підхід спричиняв проблеми: +Старий підхід створював проблеми: -- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних модулів +- **Повільний запуск** — імпорт однієї helper-функції завантажував десятки не пов’язаних модулів - **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту -- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які — внутрішніми +- **Неясна поверхня API** — не було способу зрозуміти, які exports були стабільними, а які внутрішніми -Сучасний Plugin SDK виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим самодостатнім модулем із чітким призначенням і документованим контрактом. +Сучасний SDK плагінів виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні шви провайдерів для вбудованих каналів також зникли. -Допоміжні шви з брендуванням каналів були приватними скороченнями mono-repo, а не стабільними -контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині -робочого простору вбудованого Plugin залишайте допоміжні функції, що належать провайдеру, у власному `api.ts` або -`runtime-api.ts` цього Plugin. +Застарілі зручні seams провайдера для вбудованих каналів також прибрано. +Допоміжні seams із брендуванням каналу були приватними скороченнями mono-repo, а не стабільними контрактами плагінів. Натомість використовуйте вузькі загальні subpath SDK. Усередині workspace вбудованого плагіна зберігайте helper-функції, що належать провайдеру, у власному `api.ts` або `runtime-api.ts` цього плагіна. -Поточні приклади вбудованих провайдерів: +Приклади поточних вбудованих провайдерів: -- Anthropic зберігає допоміжні функції потоків, специфічні для Claude, у власному шві `api.ts` / - `contract-api.ts` -- OpenAI зберігає builder-и провайдера, допоміжні функції моделі за замовчуванням і builder-и - провайдера реального часу у власному `api.ts` -- OpenRouter зберігає builder провайдера та допоміжні функції onboarding/config у власному - `api.ts` +- Anthropic зберігає helper-функції потоку, специфічні для Claude, у власному seam `api.ts` / `contract-api.ts` +- OpenAI зберігає builder-и провайдера, helper-функції моделі за замовчуванням і builder-и realtime-провайдера у власному `api.ts` +- OpenRouter зберігає builder провайдера та helper-функції онбордингу/конфігурації у власному `api.ts` ## Політика сумісності -Для зовнішніх Plugin робота із сумісністю виконується в такому порядку: +Для зовнішніх плагінів робота із сумісністю виконується в такому порядку: 1. додати новий контракт -2. залишити стару поведінку підключеною через адаптер сумісності -3. вивести діагностичне повідомлення або попередження з указанням старого шляху та заміни +2. зберегти стару поведінку, підключивши її через адаптер сумісності +3. вивести діагностику або попередження з указанням старого шляху та заміни 4. покрити тестами обидва шляхи 5. задокументувати застарівання та шлях міграції -6. вилучати лише після оголошеного вікна міграції, зазвичай у мажорному випуску +6. вилучати лише після оголошеного вікна міграції, зазвичай у мажорному релізі -Якщо поле маніфесту все ще приймається, автори Plugin можуть і надалі його використовувати, -доки документація й діагностика не повідомлять про інше. Новий код має віддавати перевагу -документованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних -випусків. +Якщо поле маніфесту все ще приймається, автори плагінів можуть і надалі його використовувати, доки документація та діагностика не скажуть інакше. Новий код має надавати перевагу задокументованій заміні, але наявні плагіни не повинні ламатися під час звичайних мінорних релізів. ## Як виконати міграцію - - Вбудовані Plugin повинні припинити прямі виклики + + Вбудовані плагіни мають припинити прямі виклики `api.runtime.config.loadConfig()` і - `api.runtime.config.writeConfigFile(...)`. Надавайте перевагу конфігурації, яку вже - передано в активний шлях виклику. Довгоживучі обробники, яким потрібен - поточний знімок процесу, можуть використовувати `api.runtime.config.current()`. Довгоживучі - інструменти агента повинні використовувати `ctx.getRuntimeConfig()` із контексту інструмента всередині - `execute`, щоб інструмент, створений до запису конфігурації, усе одно бачив - оновлену конфігурацію виконання. + `api.runtime.config.writeConfigFile(...)`. Натомість віддавайте перевагу конфігурації, яку вже передано в активний шлях виклику. Довгоживучі обробники, яким потрібен поточний snapshot процесу, можуть використовувати `api.runtime.config.current()`. Довгоживучі інструменти агента мають використовувати `ctx.getRuntimeConfig()` із контексту інструмента всередині `execute`, щоб інструмент, створений до запису конфігурації, усе одно бачив оновлену конфігурацію runtime. - Запис конфігурації має проходити через транзакційні допоміжні функції з вибором - політики після запису: + Запис конфігурації має відбуватися через транзакційні helper-функції з вибором політики після запису: ```typescript await api.runtime.config.mutateConfigFile({ @@ -119,52 +90,47 @@ OpenClaw не вилучає і не переосмислює документо }); ``` - Використовуйте `afterWrite: { mode: "restart", reason: "..." }`, коли викликач - знає, що зміна потребує чистого перезапуску gateway, і - `afterWrite: { mode: "none", reason: "..." }` лише тоді, коли викликач сам - контролює подальші дії і свідомо хоче вимкнути planner перезавантаження. - Результати мутації містять типізоване зведення `followUp` для тестів і логування; - gateway, як і раніше, відповідає за застосування або планування перезапуску. - `loadConfig` і `writeConfigFile` залишаються застарілими допоміжними - функціями сумісності для зовнішніх Plugin протягом вікна міграції та виводять - однократне попередження з кодом сумісності `runtime-config-load-write`. Вбудовані Plugin і - код runtime у репозиторії захищені guardrail-сканерами в + Використовуйте `afterWrite: { mode: "restart", reason: "..." }`, коли викликач знає, + що зміна потребує чистого перезапуску Gateway, і + `afterWrite: { mode: "none", reason: "..." }` лише тоді, коли викликач сам відповідає + за наступні дії та свідомо хоче вимкнути планувальник перезавантаження. + Результати мутацій містять типізований підсумок `followUp` для тестів і логування; + Gateway як і раніше відповідає за застосування або планування перезапуску. + `loadConfig` і `writeConfigFile` залишаються як застарілі helper-функції сумісності + для зовнішніх плагінів протягом вікна міграції та один раз показують попередження з + кодом сумісності `runtime-config-load-write`. Вбудовані плагіни та код runtime репозиторію + захищені scanner-обмеженнями у `pnpm check:deprecated-internal-config-api` і - `pnpm check:no-runtime-action-load-config`: нове використання у production Plugin - завершується негайною помилкою, прямий запис конфігурації завершується помилкою, серверні методи gateway - мають використовувати знімок runtime запиту, допоміжні функції надсилання/дії/клієнта каналу runtime - мають отримувати конфігурацію зі свого граничного шару, а довгоживучі runtime-модулі - мають нульову дозволену кількість фонових викликів `loadConfig()`. + `pnpm check:no-runtime-action-load-config`: нове використання виробничими плагінами + відразу завершується помилкою, прямі записи конфігурації завершуються помилкою, методи сервера gateway мають використовувати snapshot runtime запиту, helper-функції send/action/client каналу runtime мають отримувати конфігурацію зі своєї межі, а довгоживучі модулі runtime мають нульову допустиму кількість ambient-викликів `loadConfig()`. - Новий код Plugin також повинен уникати імпорту широкого - compat-barrel `openclaw/plugin-sdk/config-runtime`. Використовуйте вузький - підшлях SDK, що відповідає потрібному завданню: + Новий код плагінів також має уникати імпорту широкого barrel сумісності + `openclaw/plugin-sdk/config-runtime`. Використовуйте вузький subpath SDK, який відповідає завданню: | Потреба | Імпорт | | --- | --- | | Типи конфігурації, такі як `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | - | Перевірки вже завантаженої конфігурації та пошук конфігурації точки входу Plugin | `openclaw/plugin-sdk/plugin-config-runtime` | - | Читання поточного знімка runtime | `openclaw/plugin-sdk/runtime-config-snapshot` | - | Запис конфігурації | `openclaw/plugin-sdk/config-mutation` | - | Допоміжні функції сховища сесій | `openclaw/plugin-sdk/session-store-runtime` | - | Конфігурація Markdown-таблиць | `openclaw/plugin-sdk/markdown-table-runtime` | - | Допоміжні функції політики груп runtime | `openclaw/plugin-sdk/runtime-group-policy` | - | Визначення секретного вводу | `openclaw/plugin-sdk/secret-input-runtime` | + | Перевірки вже завантаженої конфігурації та пошук конфігурації запису плагіна | `openclaw/plugin-sdk/plugin-config-runtime` | + | Читання поточного snapshot runtime | `openclaw/plugin-sdk/runtime-config-snapshot` | + | Записи конфігурації | `openclaw/plugin-sdk/config-mutation` | + | Helper-функції сховища сесій | `openclaw/plugin-sdk/session-store-runtime` | + | Конфігурація таблиць Markdown | `openclaw/plugin-sdk/markdown-table-runtime` | + | Helper-функції runtime для політики груп | `openclaw/plugin-sdk/runtime-group-policy` | + | Розв’язання secret input | `openclaw/plugin-sdk/secret-input-runtime` | | Перевизначення моделі/сесії | `openclaw/plugin-sdk/model-session-runtime` | - Вбудовані Plugin і їхні тести захищені сканерами від використання широкого - barrel, тому імпорти й mock-и залишаються локальними до потрібної їм поведінки. Широкий - barrel усе ще існує для зовнішньої сумісності, але новий код не повинен - від нього залежати. + Вбудовані плагіни та їхні тести захищені scanner-перевірками від широкого + barrel, тому імпорти й mocks залишаються локальними для потрібної їм поведінки. Широкий + barrel усе ще існує для зовнішньої сумісності, але новий код не повинен від нього залежати. - Вбудовані Plugin повинні замінити обробники результатів інструментів лише для Pi - `api.registerEmbeddedExtensionFactory(...)` на middleware, нейтральне до runtime. + Вбудовані плагіни мають замінити обробники результатів інструментів лише для Pi через + `api.registerEmbeddedExtensionFactory(...)` на runtime-нейтральне middleware. ```typescript - // Динамічні інструменти runtime Pi і Codex + // Pi and Codex runtime dynamic tools api.registerAgentToolResultMiddleware(async (event) => { return compactToolResult(event); }, { @@ -172,7 +138,7 @@ OpenClaw не вилучає і не переосмислює документо }); ``` - Одночасно оновіть маніфест Plugin: + Одночасно оновіть маніфест плагіна: ```json { @@ -182,100 +148,101 @@ OpenClaw не вилучає і не переосмислює документо } ``` - Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки воно - може переписувати високодовірений вивід інструмента до того, як його побачить модель. + Зовнішні плагіни не можуть реєструвати middleware результатів інструментів, оскільки воно може + переписувати високодовірений вивід інструмента до того, як його побачить модель. - - Plugin каналів із підтримкою approval тепер відкривають нативну поведінку approval через + + Плагіни каналів із підтримкою approval тепер надають нативну поведінку approval через `approvalCapability.nativeRuntime` разом зі спільним реєстром runtime-context. Основні зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть специфічні для approval auth/delivery зі застарілого зв’язування `plugin.auth` / - `plugin.approvals` на `approvalCapability` + - Перенесіть auth/delivery, специфічні для approval, зі старої прив’язки `plugin.auth` / + `plugin.approvals` до `approvalCapability` - `ChannelPlugin.approvals` вилучено з публічного контракту channel-plugin; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу каналу; approval auth + - `plugin.auth` залишається лише для потоків входу/виходу в channel; approval hooks там більше не зчитуються ядром - - Реєструйте об’єкти runtime, що належать каналу, як-от клієнти, токени або Bolt + - Реєструйте об’єкти runtime, що належать каналу, такі як клієнти, токени або Bolt apps, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте повідомлення reroute notice, що належать Plugin, із нативних обробників approval; - ядро тепер саме відповідає за повідомлення routed-elsewhere notice на основі фактичних результатів доставки - - Передаючи `channelRuntime` у `createChannelManager(...)`, надавайте - реальну поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. + - Не надсилайте сповіщення reroute, що належать плагіну, із native approval handlers; + тепер ядро саме відповідає за routed-elsewhere notices на основі фактичних результатів доставки + - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте + реальну поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. - Поточне компонування можливостей approval див. в `/plugins/sdk-channel-plugins`. + Поточну структуру capability approval див. у `/plugins/sdk-channel-plugins`. - Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені Windows - wrapper-и `.cmd`/`.bat` тепер завершуються закрито, якщо ви явно не передасте + Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows + wrapper-и `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. ```typescript - // До + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // Після + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Установлюйте це лише для довірених викликачів сумісності, які свідомо - // допускають резервний перехід через оболонку. + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Якщо ваш викликач не покладається свідомо на резервний перехід через оболонку, не встановлюйте - `allowShellFallback` і натомість обробляйте викинуту помилку. + Якщо ваш викликач навмисно не покладається на shell fallback, не встановлюйте + `allowShellFallback`, а натомість обробляйте викинуту помилку. - Знайдіть у своєму Plugin імпорти з будь-якої із застарілих поверхонь: + Виконайте пошук у своєму плагіні імпортів із будь-якої застарілої поверхні: ```bash grep -r "plugin-sdk/compat" my-plugin/ + grep -r "plugin-sdk/infra-runtime" my-plugin/ grep -r "plugin-sdk/config-runtime" my-plugin/ grep -r "openclaw/extension-api" my-plugin/ ``` - - Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: + + Кожен export зі старої поверхні відповідає певному сучасному шляху імпорту: ```typescript - // До (застарілий шар зворотної сумісності) + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Після (сучасні сфокусовані імпорти) + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних функцій на боці хоста використовуйте впроваджений runtime Plugin замість + Для helper-функцій на боці хоста використовуйте інжектований runtime плагіна замість прямого імпорту: ```typescript - // До (застарілий міст extension-api) + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Після (впроваджений runtime) + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Той самий шаблон застосовується до інших застарілих допоміжних функцій мосту: + Той самий шаблон застосовується й до інших legacy helper-функцій bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -285,7 +252,38 @@ OpenClaw не вилучає і не переосмислює документо | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні функції сховища сесій | `api.runtime.agent.session.*` | + | helper-функції сховища сесій | `api.runtime.agent.session.*` | + + + + + `openclaw/plugin-sdk/infra-runtime` усе ще існує для зовнішньої + сумісності, але новий код має імпортувати сфокусовану поверхню helper-функцій, + яка йому фактично потрібна: + + | Потреба | Імпорт | + | --- | --- | + | Helper-функції черги системних подій | `openclaw/plugin-sdk/system-event-runtime` | + | Helper-функції подій і видимості Heartbeat | `openclaw/plugin-sdk/heartbeat-runtime` | + | Зливання черги відкладеної доставки | `openclaw/plugin-sdk/delivery-queue-runtime` | + | Телеметрія активності каналу | `openclaw/plugin-sdk/channel-activity-runtime` | + | In-memory кеші дедуплікації | `openclaw/plugin-sdk/dedupe-runtime` | + | Безпечні helper-функції шляхів до локальних файлів/медіа | `openclaw/plugin-sdk/file-access-runtime` | + | Fetch з урахуванням dispatcher | `openclaw/plugin-sdk/runtime-fetch` | + | Helper-функції proxy і guarded fetch | `openclaw/plugin-sdk/fetch-runtime` | + | Типи політики SSRF dispatcher | `openclaw/plugin-sdk/ssrf-dispatcher` | + | Типи запиту/розв’язання approval | `openclaw/plugin-sdk/approval-runtime` | + | Payload відповіді approval і helper-функції команд | `openclaw/plugin-sdk/approval-reply-runtime` | + | Helper-функції форматування помилок | `openclaw/plugin-sdk/error-runtime` | + | Очікування готовності транспорту | `openclaw/plugin-sdk/transport-ready-runtime` | + | Helper-функції безпечних токенів | `openclaw/plugin-sdk/secure-random-runtime` | + | Обмежена конкурентність асинхронних завдань | `openclaw/plugin-sdk/concurrency-runtime` | + | Числове приведення | `openclaw/plugin-sdk/number-runtime` | + | Асинхронне блокування локального процесу | `openclaw/plugin-sdk/async-lock-runtime` | + | Блокування файлів | `openclaw/plugin-sdk/file-lock` | + + Вбудовані плагіни захищені scanner-перевірками від `infra-runtime`, тож код репозиторію + не може повернутися до широкого barrel. @@ -300,187 +298,194 @@ OpenClaw не вилучає і не переосмислює документо ## Довідник шляхів імпорту - | Import path | Призначення | Ключові експорти | + | Import path | Призначення | Ключові exports | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу Plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/builder-ів входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Експорт схеми кореневої конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Сфокусовані визначення та builder-и входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Підказки allowlist, builder-и статусу налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні функції runtime під час налаштування | Безпечні для імпорту адаптери patch налаштування, допоміжні функції приміток lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Допоміжні функції інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку/конфігурації облікових записів/контролю дій | - | `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікових записів | Допоміжні функції пошуку облікового запису + резервного вибору за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції облікових записів | Допоміжні функції списку облікових записів/дій з обліковими записами | - | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви DM pairing | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Зв’язування префікса відповіді + typing | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builder-и схем конфігурації | Спільні примітиви схеми конфігурації каналу та лише загальний builder | - | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації вбудованих модулів | Лише для сумісності вбудованих модулів; нові Plugin повинні визначати локальні схеми Plugin | - | `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Допоміжні функції стану облікового запису та життєвого циклу потоку чернеток | `createAccountStatusSink`, допоміжні функції фіналізації попереднього перегляду чернеток | - | `plugin-sdk/inbound-envelope` | Допоміжні функції вхідного envelope | Спільні допоміжні функції маршрутів + builder-а envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції record-and-dispatch | - | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Допоміжні функції залежностей вихідного надсилання | Полегшений пошук `resolveOutboundSendDep` без імпорту повного outbound runtime | - | `plugin-sdk/outbound-runtime` | Допоміжні функції outbound runtime | Допоміжні функції outbound delivery, делегата identity/send, сесії, форматування та планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу thread-binding та адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder media payload агента для застарілих макетів полів | + | `plugin-sdk/plugin-entry` | Канонічний helper для входу плагіна | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий umbrella-реекспорт для визначень/builders входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper для входу одного провайдера | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Сфокусовані визначення та builders входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні helper-функції майстра налаштування | Підказки allowlist, builders статусу налаштування | + | `plugin-sdk/setup-runtime` | Helper-функції runtime під час налаштування | Безпечні для імпорту setup patch adapters, helper-функції lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies | + | `plugin-sdk/setup-adapter-runtime` | Helper-функції setup adapter | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Helper-функції інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Helper-функції для кількох облікових записів | Helper-функції списку/конфігурації/шлюзу дій облікових записів | + | `plugin-sdk/account-id` | Helper-функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Helper-функції пошуку облікового запису | Helper-функції пошуку облікового запису + fallback до значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі helper-функції для облікових записів | Helper-функції списку облікових записів/дій облікових записів | + | `plugin-sdk/channel-setup` | Adapters майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | Примітиви pairing для DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Factory config adapter | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Builders схем конфігурації | Спільні примітиви схеми конфігурації каналу та лише загальний builder | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації вбудованих плагінів | Лише для сумісності вбудованих плагінів; нові плагіни мають визначати локальні схеми плагіна | + | `plugin-sdk/telegram-command-config` | Helper-функції конфігурації команд Telegram | Нормалізація імен команд, обрізання опису, перевірка дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Розв’язання політики груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Helper-функції статусу облікового запису та життєвого циклу draft stream | `createAccountStatusSink`, helper-функції завершення preview чернетки | + | `plugin-sdk/inbound-envelope` | Helper-функції вхідного envelope | Спільні helper-функції маршрутизації + builder envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper-функції вхідної відповіді | Спільні helper-функції запису та dispatch | + | `plugin-sdk/messaging-targets` | Парсинг цілей повідомлень | Helper-функції парсингу/зіставлення цілей | + | `plugin-sdk/outbound-media` | Helper-функції вихідних медіа | Спільне завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Helper-функції залежностей outbound send | Полегшений пошук `resolveOutboundSendDep` без імпорту всього outbound runtime | + | `plugin-sdk/outbound-runtime` | Helper-функції outbound runtime | Helper-функції outbound delivery, delegate identity/send, session, formatting і планування payload | + | `plugin-sdk/thread-bindings-runtime` | Helper-функції thread-binding | Helper-функції життєвого циклу та adapters thread-binding | + | `plugin-sdk/agent-media-payload` | Застарілі helper-функції media payload | Builder media payload агента для застарілих layout полів | | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | - | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/логування/резервного копіювання/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції runtime env | Logger/runtime env, допоміжні функції timeout, retry і backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime Plugin | Допоміжні функції команд/хуків/http/інтерактивності Plugin | - | `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра хуків | Спільні допоміжні функції конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec | - | `plugin-sdk/cli-runtime` | Допоміжні функції CLI runtime | Форматування команд, очікування, допоміжні функції версій | - | `plugin-sdk/gateway-runtime` | Допоміжні функції Gateway | Допоміжні функції клієнта Gateway і patch статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні функції approval prompt | Допоміжні функції payload approval exec/Plugin, approval capability/profile, нативної маршрутизації/runtime approval і форматування шляху відображення структурованого approval | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції approval auth | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції approval client | Допоміжні функції профілю/фільтра нативного approval exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні функції approval delivery | Адаптери нативних approval capability/delivery | - | `plugin-sdk/approval-gateway-runtime` | Допоміжні функції approval gateway | Спільна допоміжна функція визначення approval gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні функції адаптера approval | Полегшені допоміжні функції завантаження адаптера нативного approval для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Допоміжні функції approval handler | Ширші допоміжні функції runtime обробника approval; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей approval | Допоміжні функції прив’язки нативної цілі/облікового запису approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції відповіді approval | Допоміжні функції payload відповіді approval exec/Plugin | - | `plugin-sdk/channel-runtime-context` | Допоміжні функції channel runtime-context | Загальні допоміжні функції register/get/watch для channel runtime-context | - | `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції довіри, DM gating, external-content і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції SSRF runtime | Допоміжні функції pinned-dispatcher, guarded fetch, SSRF policy | - | `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні функції контролю діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch/proxy | `resolveFetch`, допоміжні функції proxy | - | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, виконавці policy | + | `plugin-sdk/channel-send-result` | Типи результату send | Типи результату відповіді | + | `plugin-sdk/runtime-store` | Постійне сховище плагіна | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі helper-функції runtime | Helper-функції runtime/logging/backup/встановлення плагінів | + | `plugin-sdk/runtime-env` | Вузькі helper-функції runtime env | Helper-функції logger/runtime env, timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні helper-функції runtime плагіна | Helper-функції команд/hooks/http/interactive плагіна | + | `plugin-sdk/hook-runtime` | Helper-функції pipeline hooks | Спільні helper-функції pipeline webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Helper-функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper-функції процесу | Спільні helper-функції exec | + | `plugin-sdk/cli-runtime` | Helper-функції CLI runtime | Форматування команд, очікування, helper-функції версій | + | `plugin-sdk/gateway-runtime` | Helper-функції Gateway | Helper-функції клієнта Gateway і patch статусу каналу | + | `plugin-sdk/config-runtime` | Застарілий shim сумісності конфігурації | Надавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` | + | `plugin-sdk/telegram-command-config` | Helper-функції команд Telegram | Стабільні helper-функції перевірки команд Telegram із fallback, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Helper-функції prompts approval | Payload approval exec/plugin, helper-функції capability/profile approval, helper-функції маршрутизації/runtime native approval і форматування шляху структурованого відображення approval | + | `plugin-sdk/approval-auth-runtime` | Helper-функції auth approval | Розв’язання approver, auth дій у тому ж чаті | + | `plugin-sdk/approval-client-runtime` | Helper-функції клієнта approval | Helper-функції profile/filter native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Helper-функції delivery approval | Adapters capability/delivery native approval | + | `plugin-sdk/approval-gateway-runtime` | Helper-функції Gateway approval | Спільна helper-функція gateway-resolution approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper-функції adapters approval | Полегшені helper-функції завантаження adapter native approval для hot entrypoint каналів | + | `plugin-sdk/approval-handler-runtime` | Helper-функції handlers approval | Ширші helper-функції runtime handlers approval; надавайте перевагу вужчим seams adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Helper-функції цілей approval | Helper-функції native approval target/account binding | + | `plugin-sdk/approval-reply-runtime` | Helper-функції відповіді approval | Helper-функції payload відповіді approval exec/plugin | + | `plugin-sdk/channel-runtime-context` | Helper-функції runtime-context каналу | Загальні helper-функції register/get/watch для runtime-context каналу | + | `plugin-sdk/security-runtime` | Helper-функції безпеки | Спільні helper-функції trust, DM gating, external-content і збирання секретів | + | `plugin-sdk/ssrf-policy` | Helper-функції політики SSRF | Helper-функції allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Helper-функції SSRF runtime | Helper-функції pinned-dispatcher, guarded fetch, SSRF policy | + | `plugin-sdk/system-event-runtime` | Helper-функції системних подій | `enqueueSystemEvent`, `peekSystemEventEntries` | + | `plugin-sdk/heartbeat-runtime` | Helper-функції Heartbeat | Helper-функції подій і видимості Heartbeat | + | `plugin-sdk/delivery-queue-runtime` | Helper-функції черги доставки | `drainPendingDeliveries` | + | `plugin-sdk/channel-activity-runtime` | Helper-функції активності каналу | `recordChannelActivity` | + | `plugin-sdk/dedupe-runtime` | Helper-функції дедуплікації | In-memory кеші дедуплікації | + | `plugin-sdk/file-access-runtime` | Helper-функції доступу до файлів | Безпечні helper-функції шляхів до локальних файлів/медіа | + | `plugin-sdk/transport-ready-runtime` | Helper-функції готовності транспорту | `waitForTransportReady` | + | `plugin-sdk/collection-runtime` | Helper-функції обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Helper-функції керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Helper-функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, helper-функції графа помилок | + | `plugin-sdk/fetch-runtime` | Обгорнуті helper-функції fetch/proxy | `resolveFetch`, helper-функції proxy | + | `plugin-sdk/host-runtime` | Helper-функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Helper-функції retry | `RetryConfig`, `retryAsync`, runners політики | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Зіставлення вводу allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні функції контролю команд і поверхні команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд, зокрема форматування меню динамічних аргументів | - | `plugin-sdk/command-status` | Рендерери статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні функції запитів Webhook | Утиліти цілі Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції guard для тіла запиту Webhook | Допоміжні функції читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний reply runtime | Вхідна диспетчеризація, Heartbeat, planner відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції диспетчеризації відповідей | Допоміжні функції finalize, диспетчеризації провайдера та міток розмов | - | `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань відповідей | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні функції фрагментації відповідей | Допоміжні функції фрагментації тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні функції сховища сесій | Допоміжні функції шляху сховища + `updated-at` | - | `plugin-sdk/state-paths` | Допоміжні функції шляхів state | Допоміжні функції каталогів state та OAuth | - | `plugin-sdk/routing` | Допоміжні функції маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні функції статусу каналу | Builder-и зведень статусу каналу/облікового запису, типові значення runtime-state, допоміжні функції метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні функції визначення цілей | Спільні допоміжні функції визначення цілей | - | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації рядків | Допоміжні функції нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні функції URL запиту | Витягування рядкових URL із вхідних даних, схожих на запит | - | `plugin-sdk/run-command` | Допоміжні функції timed command | Виконавець timed command із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Зчитувачі параметрів | Типові зчитувачі параметрів інструментів/CLI | - | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload з об’єктів результатів інструментів | - | `plugin-sdk/tool-send` | Витягування надсилання інструмента | Витягування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції шляху тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні функції логування | Допоміжні функції logger підсистеми та редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції Markdown-таблиць | Допоміжні функції режиму Markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи відповідей повідомлень | Типи payload відповідей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локального/self-hosted провайдера | Допоміжні функції виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдера, сумісного з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/provider-auth-runtime` | Допоміжні функції auth провайдера під час runtime | Допоміжні функції визначення API-key під час runtime | - | `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування API-key провайдера | Допоміжні функції onboarding/запису профілю для API-key | - | `plugin-sdk/provider-auth-result` | Допоміжні функції auth-result провайдера | Стандартний builder OAuth auth-result | - | `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу провайдера | Спільні допоміжні функції інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Допоміжні функції вибору провайдера | Вибір провайдера configured-or-auto і злиття сирої конфігурації провайдера | - | `plugin-sdk/provider-env-vars` | Допоміжні функції env var провайдера | Допоміжні функції пошуку env var автентифікації провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделі/повтору провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, допоміжні функції endpoint провайдера та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні функції конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні функції HTTP провайдера | Загальні допоміжні функції HTTP/можливостей endpoint провайдера, зокрема допоміжні функції multipart form для транскрибування аудіо | - | `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch провайдера | Допоміжні функції реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні функції конфігурації web-search провайдера | Вузькі допоміжні функції конфігурації/облікових даних web-search для провайдерів, яким не потрібне зв’язування ввімкнення Plugin | - | `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search провайдера | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні функції web-search провайдера | Допоміжні функції реєстрації/кешу/runtime провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні функції compat інструментів/схем провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика та допоміжні функції compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні функції використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції використання провайдера | - | `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні функції обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні функції транспорту провайдера | Нативні допоміжні функції транспорту провайдера, такі як guarded fetch, перетворення transport message і writable потоки подій транспорту | + | `plugin-sdk/allowlist-resolution` | Відображення входів allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Helper-функції gating команд і поверхні команд | `resolveControlCommandGate`, helper-функції авторизації відправника, helper-функції реєстру команд, включно з форматуванням меню динамічних аргументів | + | `plugin-sdk/command-status` | Renderers статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Парсинг secret input | Helper-функції secret input | + | `plugin-sdk/webhook-ingress` | Helper-функції запиту Webhook | Утиліти цілі Webhook | + | `plugin-sdk/webhook-request-guards` | Helper-функції guards тіла запиту Webhook | Helper-функції читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний reply runtime | Inbound dispatch, Heartbeat, planner відповіді, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-функції dispatch відповіді | Helper-функції finalize, dispatch провайдера та міток розмов | + | `plugin-sdk/reply-history` | Helper-функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Helper-функції chunk відповіді | Helper-функції chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Helper-функції сховища сесій | Helper-функції шляху сховища + updated-at | + | `plugin-sdk/state-paths` | Helper-функції шляхів стану | Helper-функції каталогів стану та OAuth | + | `plugin-sdk/routing` | Helper-функції маршрутизації/ключів сесії | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper-функції нормалізації ключів сесії | + | `plugin-sdk/status-helpers` | Helper-функції статусу каналу | Builders підсумку статусу каналу/облікового запису, значення за замовчуванням для runtime-state, helper-функції метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Helper-функції розв’язання цілей | Спільні helper-функції target resolver | + | `plugin-sdk/string-normalization-runtime` | Helper-функції нормалізації рядків | Helper-функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Helper-функції URL запиту | Витягування рядкових URL із request-подібних входів | + | `plugin-sdk/run-command` | Helper-функції команд із таймером | Runner команд із таймером і нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Readers параметрів | Загальні readers параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload із об’єктів результатів інструментів | + | `plugin-sdk/tool-send` | Витягування send інструмента | Витягування канонічних полів цілі send з аргументів інструмента | + | `plugin-sdk/temp-path` | Helper-функції тимчасових шляхів | Спільні helper-функції шляхів для тимчасових завантажень | + | `plugin-sdk/logging-core` | Helper-функції логування | Helper-функції logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Helper-функції таблиць Markdown | Helper-функції режиму таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload відповіді | + | `plugin-sdk/provider-setup` | Добірні helper-функції налаштування локальних/self-hosted провайдерів | Helper-функції виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані helper-функції налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі helper-функції виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/provider-auth-runtime` | Helper-функції auth провайдера для runtime | Helper-функції розв’язання API-ключа під час runtime | + | `plugin-sdk/provider-auth-api-key` | Helper-функції налаштування API-ключа провайдера | Helper-функції онбордингу/запису профілю API-ключа | + | `plugin-sdk/provider-auth-result` | Helper-функції auth-result провайдера | Стандартний builder auth-result OAuth | + | `plugin-sdk/provider-auth-login` | Helper-функції інтерактивного входу провайдера | Спільні helper-функції інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Helper-функції вибору провайдера | Вибір налаштованого або автоматичного провайдера та об’єднання сирої конфігурації провайдера | + | `plugin-sdk/provider-env-vars` | Helper-функції env vars провайдера | Helper-функції пошуку env vars auth провайдера | + | `plugin-sdk/provider-model-shared` | Спільні helper-функції моделей/replay провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builders політики replay, helper-функції endpoint провайдера та helper-функції нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні helper-функції каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Helper-функції конфігурації онбордингу | + | `plugin-sdk/provider-http` | HTTP helper-функції провайдера | Загальні helper-функції HTTP/можливостей endpoint провайдера, включно з helper-функціями multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch` | Helper-функції web-fetch провайдера | Helper-функції реєстрації/кешу провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helper-функції конфігурації web-search провайдера | Вузькі helper-функції конфігурації/облікових даних web-search для провайдерів, яким не потрібна прив’язка ввімкнення плагіна | + | `plugin-sdk/provider-web-search-contract` | Helper-функції контракту web-search провайдера | Вузькі helper-функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | + | `plugin-sdk/provider-web-search` | Helper-функції web-search провайдера | Helper-функції реєстрації/кешу/runtime провайдера web-search | + | `plugin-sdk/provider-tools` | Helper-функції сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics і helper-функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Helper-функції usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші helper-функції usage провайдера | + | `plugin-sdk/provider-stream` | Helper-функції wrappers потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи wrappers потоків і спільні helper-функції wrappers для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Helper-функції транспорту провайдера | Нативні helper-функції транспорту провайдера, такі як guarded fetch, перетворення транспортних повідомлень і writable event streams транспорту | | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції fetch/transform/store для медіа, а також builder-и media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні функції розуміння медіа | Типи провайдера розуміння медіа та експорти допоміжних функцій зображення/аудіо для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Видалення тексту, видимого асистенту, допоміжні функції рендерингу/chunking/таблиць markdown, редагування чутливих даних, допоміжні функції directive-tag, утиліти safe-text та пов’язані допоміжні функції тексту/логування | - | `plugin-sdk/text-chunking` | Допоміжні функції фрагментації тексту | Допоміжна функція фрагментації вихідного тексту | - | `plugin-sdk/speech` | Допоміжні функції мовлення | Типи провайдера мовлення та експорти допоміжних функцій directive, registry і validation для провайдерів | - | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдера мовлення, registry, directives, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні функції транскрибування в реальному часі | Типи провайдера, допоміжні функції registry та спільна допоміжна функція сесії WebSocket | - | `plugin-sdk/realtime-voice` | Допоміжні функції голосу в реальному часі | Типи провайдера, допоміжні функції registry/визначення та допоміжні функції bridge session | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, допоміжні функції failover, auth і registry | - | `plugin-sdk/music-generation` | Допоміжні функції генерації музики | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні функції failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/video-generation` | Допоміжні функції генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/редукція payload інтерактивних відповідей | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви schema конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули channel Plugin | - | `plugin-sdk/channel-status` | Допоміжні функції статусу каналу | Спільні допоміжні функції snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні функції доступу до групи | Спільні допоміжні функції рішень щодо group-access | - | `plugin-sdk/direct-dm` | Допоміжні функції direct-DM | Спільні допоміжні функції auth/guard для direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні функції розширень | Примітиви passive-channel/status і ambient proxy helper | - | `plugin-sdk/webhook-targets` | Допоміжні функції цілей Webhook | Допоміжні функції registry цілей Webhook та встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні функції шляху Webhook | Допоміжні функції нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні функції вебмедіа | Допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/memory-core` | Вбудовані допоміжні функції memory-core | Поверхня допоміжних функцій менеджера пам’яті/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти базового рушія хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до registry, локальний провайдер і загальні batch/remote допоміжні функції; конкретні remote-провайдери містяться у Plugin-власниках | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Експорти рушія сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні функції хоста пам’яті | Мультимодальні допоміжні функції хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | Допоміжні функції запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні функції секретів хоста пам’яті | Допоміжні функції секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | Допоміжні функції журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті | Допоміжні функції статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні функції CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Базовий runtime хоста пам’яті | Допоміжні функції базового runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | Допоміжні функції файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім базового runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних функцій базового runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних функцій журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для Plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку Active Memory | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних функцій статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні функції memory-lancedb | Поверхня допоміжних функцій memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні функції тестування та mock-и | + | `plugin-sdk/media-runtime` | Спільні helper-функції медіа | Helper-функції fetch/transform/store медіа та builders payload медіа | + | `plugin-sdk/media-generation-runtime` | Спільні helper-функції генерації медіа | Спільні helper-функції failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Helper-функції розуміння медіа | Типи провайдерів розуміння медіа та provider-facing exports helper-функцій зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні text helper-функції | Видалення видимого для асистента тексту, helper-функції render/chunking/table для markdown, helper-функції редагування, helper-функції тегів директив, утиліти безпечного тексту та пов’язані helper-функції тексту/логування | + | `plugin-sdk/text-chunking` | Helper-функції chunking тексту | Helper-функція chunking вихідного тексту | + | `plugin-sdk/speech` | Helper-функції мовлення | Типи провайдерів мовлення та provider-facing helper-функції directives, registry і validation | + | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдерів мовлення, registry, directives, нормалізація | + | `plugin-sdk/realtime-transcription` | Helper-функції realtime-транскрибування | Типи провайдерів, helper-функції registry і спільна helper-функція сесії WebSocket | + | `plugin-sdk/realtime-voice` | Helper-функції realtime voice | Типи провайдерів, helper-функції registry/resolution і helper-функції bridge session | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, helper-функції failover, auth і registry | + | `plugin-sdk/music-generation` | Helper-функції генерації музики | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, helper-функції failover, пошук провайдера та парсинг model-ref | + | `plugin-sdk/video-generation` | Helper-функції генерації відео | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, helper-функції failover, пошук провайдера та парсинг model-ref | + | `plugin-sdk/interactive-runtime` | Helper-функції інтерактивної відповіді | Нормалізація/зменшення payload інтерактивної відповіді | + | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | + | `plugin-sdk/channel-config-writes` | Helper-функції запису конфігурації каналу | Helper-функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Exports спільного prelude channel plugin | + | `plugin-sdk/channel-status` | Helper-функції статусу каналу | Спільні helper-функції snapshot/summary статусу каналу | + | `plugin-sdk/allowlist-config-edit` | Helper-функції конфігурації allowlist | Helper-функції редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Helper-функції доступу до груп | Спільні helper-функції рішень group-access | + | `plugin-sdk/direct-dm` | Helper-функції direct-DM | Спільні helper-функції auth/guard direct-DM | + | `plugin-sdk/extension-shared` | Спільні helper-функції розширень | Примітиви passive-channel/status і ambient proxy helper | + | `plugin-sdk/webhook-targets` | Helper-функції цілей Webhook | Реєстр цілей Webhook і helper-функції встановлення маршрутів | + | `plugin-sdk/webhook-path` | Helper-функції шляху Webhook | Helper-функції нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні helper-функції web media | Helper-функції завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Реекспорт Zod | Повторно експортований `zod` для споживачів SDK плагінів | + | `plugin-sdk/memory-core` | Вбудовані helper-функції memory-core | Поверхня helper-функцій менеджера memory, конфігурації, файлів і CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія memory | Фасад runtime індексу/пошуку memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста memory | Exports базового рушія хоста memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-рушій хоста memory | Контракти embedding memory, доступ до registry, локальний провайдер і загальні helper-функції batch/remote; конкретні remote-провайдери знаходяться у плагінах, яким вони належать | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD-рушій хоста memory | Exports QMD-рушія хоста memory | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста memory | Exports рушія сховища хоста memory | + | `plugin-sdk/memory-core-host-multimodal` | Багатомодальні helper-функції хоста memory | Багатомодальні helper-функції хоста memory | + | `plugin-sdk/memory-core-host-query` | Query helper-функції хоста memory | Query helper-функції хоста memory | + | `plugin-sdk/memory-core-host-secret` | Secret helper-функції хоста memory | Secret helper-функції хоста memory | + | `plugin-sdk/memory-core-host-events` | Helper-функції журналу подій хоста memory | Helper-функції журналу подій хоста memory | + | `plugin-sdk/memory-core-host-status` | Helper-функції статусу хоста memory | Helper-функції статусу хоста memory | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста memory | CLI runtime helper-функції хоста memory | + | `plugin-sdk/memory-core-host-runtime-core` | Базовий runtime хоста memory | Базові runtime helper-функції хоста memory | + | `plugin-sdk/memory-core-host-runtime-files` | Helper-функції файлів/runtime хоста memory | Helper-функції файлів/runtime хоста memory | + | `plugin-sdk/memory-host-core` | Псевдонім базового runtime хоста memory | Нейтральний до вендора псевдонім для базових runtime helper-функцій хоста memory | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста memory | Нейтральний до вендора псевдонім для helper-функцій журналу подій хоста memory | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста memory | Нейтральний до вендора псевдонім для helper-функцій файлів/runtime хоста memory | + | `plugin-sdk/memory-host-markdown` | Helper-функції керованого markdown | Спільні helper-функції керованого markdown для плагінів, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Lazy runtime-фасад менеджера пошуку active-memory | + | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста memory | Нейтральний до вендора псевдонім для helper-функцій статусу хоста memory | + | `plugin-sdk/memory-lancedb` | Вбудовані helper-функції memory-lancedb | Поверхня helper-функцій memory-lancedb | + | `plugin-sdk/testing` | Тестові утиліти | Test helpers і mocks | -Ця таблиця навмисно містить поширену підмножину для міграції, а не повну -поверхню SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною +поверхнею SDK. Повний список із понад 200 entrypoint-ів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще включає деякі допоміжні шви для вбудованих Plugin, такі як +Цей список усе ще містить деякі seams helper-функцій вбудованих плагінів, такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для -підтримки та сумісності вбудованих Plugin, але навмисно не включені до -поширеної таблиці міграції й не є рекомендованою ціллю для -нового коду Plugin. +підтримки та сумісності вбудованих плагінів, але навмисно +не включені до поширеної таблиці міграції й не є рекомендованою ціллю для +нового коду плагінів. -Те саме правило стосується інших сімейств вбудованих допоміжних модулів, зокрема: +Те саме правило застосовується й до інших сімейств helper-функцій вбудованих плагінів, таких як: -- допоміжних функцій підтримки браузера: `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-функції підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- вбудованих поверхонь допоміжних модулів/Plugin, таких як `plugin-sdk/googlechat`, +- поверхні вбудованих helper-функцій/плагінів, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -490,131 +495,130 @@ OpenClaw не вилучає і не переосмислює документо `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` зараз надає вузьку поверхню -допоміжних функцій токена: `DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню helper-функцій токена: +`DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти експорт, -перевірте джерельний код у `src/plugin-sdk/` або запитайте в Discord. +Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти export, +перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. ## Активні застарівання -Вужчі застарівання, які застосовуються до Plugin SDK, контракту провайдера, -поверхні runtime і маніфесту. Кожен із них усе ще працює сьогодні, але буде вилучений -у майбутньому мажорному випуску. Запис під кожним елементом зіставляє старий API з його +Вужчі застарівання, які застосовуються в усьому SDK плагінів, контракті провайдера, +поверхні runtime і маніфесті. Кожне з них іще працює сьогодні, але буде вилучене +в одному з майбутніх мажорних релізів. Запис під кожним елементом зіставляє старий API з його канонічною заміною. - + **Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`. **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі - експорти — лише імпортуються з вужчого підшляху. `command-auth` - повторно експортує їх як compat-заглушки. + exports — лише імпортовані з вужчого subpath. `command-auth` + повторно експортує їх як compat stubs. ```typescript - // До + // Before import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; - // Після + // After import { buildHelpMessage } from "openclaw/plugin-sdk/command-status"; ``` - + **Старе**: `resolveInboundMentionRequirement({ facts, policy })` і `shouldDropInboundForMention(...)` з `openclaw/plugin-sdk/channel-inbound` або `openclaw/plugin-sdk/channel-mention-gating`. **Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає - один об’єкт рішення замість двох окремих викликів. + єдиний об’єкт рішення замість двох окремих викликів. - Downstream channel Plugin (Slack, Discord, Matrix, MS Teams) уже - перейшли на це. + Downstream channel-плагіни (Slack, Discord, Matrix, Microsoft Teams) уже + перейшли. - - `openclaw/plugin-sdk/channel-runtime` — це compat-shim для старіших - channel Plugin. Не імпортуйте його в новому коді; використовуйте - `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів - runtime. + + `openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших + channel-плагінів. Не імпортуйте його в новому коді; використовуйте + `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів runtime. - Допоміжні функції `channelActions*` у `openclaw/plugin-sdk/channel-actions` - застаріли разом із сирими експортами каналу типу "actions". Натомість - відкривайте можливості через семантичну поверхню `presentation` — channel Plugin - оголошують, що саме вони рендерять (картки, кнопки, списки вибору), а не - які сирі назви дій вони приймають. + Helper-функції `channelActions*` у `openclaw/plugin-sdk/channel-actions` є + застарілими разом із сирими exports каналу «actions». Натомість розкривайте + можливості через семантичну поверхню `presentation` — channel-плагіни + оголошують, що саме вони відображають (cards, buttons, selects), а не які сирі + назви дій вони приймають. - - **Старе**: фабрика `tool()` з `openclaw/plugin-sdk/provider-web-search`. + + **Старе**: factory `tool()` з `openclaw/plugin-sdk/provider-web-search`. - **Нове**: реалізуйте `createTool(...)` безпосередньо в Plugin провайдера. - OpenClaw більше не потрібна допоміжна функція SDK для реєстрації обгортки інструмента. + **Нове**: реалізуйте `createTool(...)` безпосередньо в плагіні провайдера. + OpenClaw більше не потребує helper-функції SDK для реєстрації wrapper-а інструмента. - + **Старе**: `formatInboundEnvelope(...)` (і - `ChannelMessageForAgent.channelEnvelope`) для побудови плоского простого текстового prompt + `ChannelMessageForAgent.channelEnvelope`) для створення плоского текстового prompt envelope із вхідних повідомлень каналу. - **Нове**: `BodyForAgent` плюс структуровані блоки user-context. Channel - Plugin прикріплюють метадані маршрутизації (гілка, тема, reply-to, реакції) як - типізовані поля замість конкатенації їх у рядок prompt. Допоміжна функція - `formatAgentEnvelope(...)` усе ще підтримується для синтезованих - envelope, видимих асистенту, але вхідні прості текстові envelope + **Нове**: `BodyForAgent` разом зі структурованими блоками контексту користувача. + Channel-плагіни прикріплюють метадані маршрутизації (thread, topic, reply-to, reactions) як + типізовані поля замість конкатенації їх у рядок prompt. Helper-функція + `formatAgentEnvelope(...)` іще підтримується для синтезованих envelope, + видимих асистенту, але вхідні текстові envelope у відкритому вигляді поступово виводяться з ужитку. - Зони впливу: `inbound_claim`, `message_received` і будь-який користувацький - channel Plugin, який додатково обробляв текст `channelEnvelope`. + Порушені ділянки: `inbound_claim`, `message_received` і будь-який власний + channel-плагін, який виконував постобробку тексту `channelEnvelope`. - Чотири псевдоніми типів виявлення тепер є тонкими обгортками над - типами епохи каталогу: + Чотири псевдоніми типів виявлення тепер є тонкими wrappers над типами епохи + каталогу: - | Старий псевдонім | Новий тип | - | ------------------------- | ------------------------ | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | Старий псевдонім | Новий тип | + | ------------------------- | ------------------------- | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - А також застарілий статичний набір `ProviderCapabilities` — Plugin провайдерів - повинні прикріплювати факти можливостей через контракт runtime провайдера, + Плюс застарілий статичний набір `ProviderCapabilities` — плагіни провайдера + мають прикріплювати факти capability через контракт runtime провайдера, а не через статичний об’єкт. - - **Старе** (три окремі хуки в `ProviderThinkingPolicy`): + + **Старе** (три окремі hooks у `ProviderThinkingPolicy`): `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і `resolveDefaultThinkingLevel(ctx)`. - **Нове**: один `resolveThinkingProfile(ctx)`, який повертає - `ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і - ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені значення - за рангом профілю. + **Нове**: єдиний `resolveThinkingProfile(ctx)`, який повертає + `ProviderThinkingProfile` із канонічним `id`, необов’язковою `label` і + ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені + значення за рангом профілю. - Реалізуйте один хук замість трьох. Застарілі хуки продовжують працювати протягом + Реалізуйте один hook замість трьох. Застарілі hooks продовжують працювати під час вікна застарівання, але не комбінуються з результатом профілю. - + **Старе**: реалізація `resolveExternalOAuthProfiles(...)` без - оголошення провайдера в маніфесті Plugin. + оголошення провайдера в маніфесті плагіна. - **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті Plugin + **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті плагіна **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях - "резервної auth" видає попередження під час виконання і буде вилучений. + «auth fallback» показує попередження під час runtime і буде вилучений. ```json { @@ -626,29 +630,29 @@ OpenClaw не вилучає і не переосмислює документо - + **Старе** поле маніфесту: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. - **Нове**: відобразіть той самий пошук env var у `setup.providers[].envVars` - в маніфесті. Це консолідує метадані env налаштування/статусу в одному - місці й дозволяє не запускати runtime Plugin лише для відповіді на - пошук env var. + **Нове**: віддзеркальте той самий пошук env vars у `setup.providers[].envVars` + у маніфесті. Це консолідує метадані env для setup/status в одному + місці й дає змогу уникнути запуску runtime плагіна лише для відповіді на + пошук env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності до завершення вікна застарівання. - + **Старе**: три окремі виклики — `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`. - **Нове**: один виклик у memory-state API — + **Нове**: один виклик в API memory-state — `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. - Ті самі слоти, один виклик реєстрації. Додаткові допоміжні функції пам’яті + Ті самі слоти, один виклик реєстрації. Додаткові helper-функції memory (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, `registerMemoryEmbeddingProvider`) це не зачіпає. @@ -657,48 +661,48 @@ OpenClaw не вилучає і не переосмислює документо Два застарілі псевдоніми типів усе ще експортуються з `src/plugins/runtime/types.ts`: - | Старе | Нове | - | ---------------------------- | ------------------------------ | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | Старе | Нове | + | ----------------------------- | ------------------------------- | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - Метод runtime `readSession` застарів на користь + Метод runtime `readSession` є застарілим на користь `getSessionMessages`. Та сама сигнатура; старий метод викликає новий. - **Старе**: `runtime.tasks.flow` (в однині) повертав живий accessor TaskFlow. + **Старе**: `runtime.tasks.flow` (однина) повертав live accessor TaskFlow. - **Нове**: `runtime.tasks.flows` (у множині) повертає доступ до TaskFlow на основі DTO, - безпечний для імпорту й не потребує завантаження повного task runtime. + **Нове**: `runtime.tasks.flows` (множина) повертає доступ до TaskFlow на основі DTO, + який є безпечним для імпорту й не вимагає завантаження повного runtime завдань. ```typescript - // До + // Before const flow = api.runtime.tasks.flow(ctx); - // Після + // After const flows = api.runtime.tasks.flows(ctx); ``` - - Розглянуто вище в розділі "Як виконати міграцію → Перенесіть розширення результатів інструментів Pi на - middleware". Додано тут для повноти: вилучений шлях лише для Pi + + Розглянуто вище в розділі «Як виконати міграцію → Перенесіть розширення результатів інструментів Pi на + middleware». Додано тут для повноти: вилучений шлях лише для Pi `api.registerEmbeddedExtensionFactory(...)` замінено на - `api.registerAgentToolResultMiddleware(...)` з явним списком runtime - у `contracts.agentToolResultMiddleware`. + `api.registerAgentToolResultMiddleware(...)` з явним + списком runtime у `contracts.agentToolResultMiddleware`. - `OpenClawSchemaType`, повторно експортований із `openclaw/plugin-sdk`, тепер є - однорядковим псевдонімом для `OpenClawConfig`. Віддавайте перевагу канонічній назві. + `OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є + однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу канонічній назві. ```typescript - // До + // Before import type { OpenClawSchemaType } from "openclaw/plugin-sdk"; - // Після + // After import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema"; ``` @@ -706,24 +710,24 @@ OpenClaw не вилучає і не переосмислює документо -Застарівання на рівні extension (усередині вбудованих channel/provider Plugin у -`extensions/`) відстежуються у їхніх власних barrel-файлах `api.ts` і `runtime-api.ts`. -Вони не впливають на контракти сторонніх Plugin і тут не перелічені. -Якщо ви напряму використовуєте локальний barrel вбудованого Plugin, прочитайте +Застарівання на рівні розширень (усередині вбудованих channel/provider плагінів у +`extensions/`) відстежуються у їхніх власних barrels `api.ts` і `runtime-api.ts`. +Вони не впливають на контракти сторонніх плагінів і тут не перелічені. +Якщо ви напряму використовуєте локальний barrel вбудованого плагіна, прочитайте коментарі про застарівання в цьому barrel перед оновленням. -## Графік вилучення +## Хронологія вилучення -| Коли | Що відбувається | -| --------------------- | ---------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні видають попередження під час виконання | -| **Наступний мажорний випуск** | Застарілі поверхні буде вилучено; Plugin, які все ще їх використовують, перестануть працювати | +| Коли | Що відбувається | +| ---------------------- | ----------------------------------------------------------------------- | +| **Зараз** | Застарілі поверхні показують попередження під час runtime | +| **Наступний мажорний реліз** | Застарілі поверхні буде вилучено; плагіни, які все ще їх використовують, перестануть працювати | -Усі основні Plugin уже мігровано. Зовнішнім Plugin слід виконати міграцію -до наступного мажорного випуску. +Усі core-плагіни вже мігровано. Зовнішнім плагінам слід виконати міграцію +до наступного мажорного релізу. -## Тимчасове приглушення попереджень +## Тимчасове вимкнення попереджень Установіть ці змінні середовища, поки працюєте над міграцією: @@ -732,13 +736,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий запасний варіант, а не постійне рішення. +Це тимчасовий обхідний шлях, а не постійне рішення. ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту підшляхів -- [Channel Plugin](/uk/plugins/sdk-channel-plugins) — створення channel Plugin -- [Provider Plugin](/uk/plugins/sdk-provider-plugins) — створення provider Plugin -- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибокий огляд архітектури -- [Маніфест Plugin](/uk/plugins/manifest) — довідник зі схеми маніфесту +- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший плагін +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів +- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів +- [Внутрішня будова плагінів](/uk/plugins/architecture) — глибокий огляд архітектури +- [Маніфест плагіна](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index ea05bfb78..fe0bf59a7 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,36 +1,36 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту в плагіні + - Вибір правильного підшляху plugin-sdk для імпорту Plugin - Аудит підшляхів bundled-plugin і допоміжних поверхонь summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' -title: підшляхи Plugin SDK +title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-27T14:20:22Z" + generated_at: "2026-04-27T20:08:43Z" model: gpt-5.4 provider: openai - source_hash: 8d71e64f699d40419c682d7401a341241ffb9204fb94b9831e204d9ba1d50489 + source_hash: b55ce02a25cfe9fe1bea2263bad31b50cc72c06affa451cc9cecac4404e70d79 source_path: plugins/sdk-subpaths.md workflow: 15 --- - Plugin SDK доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований - повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також там присутні, але є деталлю реалізації, - якщо тільки якась сторінка документації явно не просуває їх. + Plugin SDK надається як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці наведено каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований + повний список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`; + зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але вони є + деталлю реалізації, якщо лише якась сторінка документації не просуває їх явно. - Посібник з авторства плагінів дивіться в [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Щоб ознайомитися з посібником з розробки Plugin, див. [Огляд Plugin SDK](/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` | + | Підшлях | Ключові експорти | + | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/migration` | Допоміжні елементи провайдера міграції, як-от `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, як-от `copyMigrationFileItem` і `writeMigrationReport` | + | `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, як-от `copyMigrationFileItem` і `writeMigrationReport` | @@ -39,55 +39,55 @@ x-i18n: | `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` | Спільні допоміжні засоби майстра налаштування, запити 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` | Допоміжні засоби для конфігурації/обмеження дій багатьох облікових записів, допоміжні засоби fallback для облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + fallback за замовчуванням | + | `plugin-sdk/account-core` | Допоміжні засоби конфігурації та action gate для кількох облікових записів, допоміжні засоби резервного використання облікового запису за замовчуванням | + | `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/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності bundled | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/перевірки Telegram custom-command з fallback для bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби для обмеження авторизації команд | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю контракту bundled | + | `plugin-sdk/command-gating` | Вузькі допоміжні засоби gate авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення draft stream | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для inbound route + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби для запису й dispatch вхідних відповідей | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення потоку чернеток | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для вхідної маршрутизації та побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби для запису та диспетчеризації вхідних відповідей | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження outbound media | - | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей outbound send для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound delivery, identity, send delegate, session, formatting і планування payload | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot для runtime config | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення policy груп під час виконання | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary стану каналу | + | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей вихідного надсилання для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної доставки, ідентичності, делегата надсилання, сесій, форматування та планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник media payload агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, спарювання та налаштованих прив’язок | + | `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` | Спільні prelude-експорти plugin каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби для рішень group-access | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Compatibility barrel для inbound debounce, зіставлення mention, допоміжних засобів mention-policy і допоміжних засобів envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби inbound debounce | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy і тексту mention без ширшої поверхні inbound runtime | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування inbound envelope | - | `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування каналу | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для відкинутих inbound і збоїв typing/ack | - | `plugin-sdk/channel-send-result` | Типи результату відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій над повідомленнями каналу, а також застарілі допоміжні засоби native schema, збережені для сумісності плагінів | + | `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-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних повідомлень | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок і тексту згадок без ширшої поверхні вхідного runtime | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідного envelope | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту та форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для відкинутих вхідних повідомлень і збоїв typing/ack | + | `plugin-sdk/channel-send-result` | Типи результатів відповіді | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби native schema, збережені для сумісності Plugin | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контрактів каналів | + | `plugin-sdk/channel-contract` | Типи контракту каналу | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контрактів секретів, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | @@ -95,29 +95,29 @@ x-i18n: | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних стандартних налаштувань сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних типових значень сервера, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Стандартні значення backend CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-key під час виконання для provider plugins | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-key, як-от `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні інтерактивні допоміжні засоби входу для provider plugins | + | `plugin-sdk/cli-backend` | Типові значення backend CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API key під час виконання для Plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API key/запису профілю, як-от `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату auth OAuth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin провайдерів | | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку auth env var для провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники replay-policy, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | + | `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 для провайдерів, помилки HTTP провайдерів і допоміжні засоби multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для провайдерів, яким не потрібне підключення ввімкнення plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и credential | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для web-search провайдерів | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Універсальні допоміжні засоби HTTP/можливостей endpoint провайдера, HTTP-помилки провайдера та допоміжні засоби 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 для провайдерів, яким не потрібне підключення enable Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scope-овані setter/getter облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper-ів і спільні допоміжні wrapper-и для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби native transport для провайдерів, як-от guarded fetch, перетворення transport message і writable transport event streams | - | `plugin-sdk/provider-onboard` | Допоміжні засоби patch конфігурації онбордингу | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби native transport провайдерів, як-от guarded fetch, трансформації транспортних повідомлень і потоки подій writable transport | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | @@ -127,170 +127,181 @@ x-i18n: | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і action-auth у межах того самого чату | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Native адаптери можливостей/доставки approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native approval adapter для гарячих channel entrypoint | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для approval handler; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + account-binding | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для exec/plugin approval | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload для exec/plugin approval, допоміжні засоби native approval routing/runtime і допоміжні засоби структурованого відображення approval, як-от `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання dedupe для вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування channel contract без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Native command auth, форматування меню динамічних аргументів і допоміжні засоби native session-target | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та auth дій у межах того самого чату | + | `plugin-sdk/approval-client-runtime` | Native допоміжні засоби профілю/фільтра затвердження exec | + | `plugin-sdk/approval-delivery-runtime` | Native адаптери можливостей/доставки затверджень | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway затверджень | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені native допоміжні засоби завантаження адаптера затверджень для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника затверджень; віддавайте перевагу вужчим адаптерним/gateway швам, якщо їх достатньо | + | `plugin-sdk/approval-native-runtime` | Native допоміжні засоби цілей затвердження + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на затвердження exec/plugin | + | `plugin-sdk/approval-runtime` | Допоміжні засоби payload затвердження exec/plugin, native допоміжні засоби маршрутизації/runtime затверджень і допоміжні засоби структурованого відображення затверджень, як-от `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Native auth команд, форматування меню динамічних аргументів і native допоміжні засоби цільових сесій | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | - | `plugin-sdk/command-surface` | Нормалізація command-body і допоміжні засоби command-surface | + | `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні засоби command surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь secret каналів/плагінів | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби policy allowlist хостів і SSRF для приватної мережі | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, SSRF-guarded fetch, SSRF error і SSRF policy | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби Webhook request/target і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body/timeout запиту | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання контрактів секретів для поверхонь секретів channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу контрактів секретів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, gate для DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned dispatcher без широкої infra runtime surface | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned dispatcher, fetch із захистом від SSRF, помилка SSRF і допоміжні засоби політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби парсингу введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення необроблених websocket/body | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/тайм-ауту запиту | - + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад browser config для нормалізованого профілю/стандартних значень, розбору CDP URL і допоміжних засобів auth для browser-control | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервного копіювання/встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, логера, тайм-аутів, повторних спроб і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованих профілів/типових значень, парсингу CDP URL і допоміжних засобів auth browser-control | + | `plugin-sdk/channel-runtime-context` | Універсальні допоміжні засоби реєстрації та пошуку channel runtime-context | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби plugin command/hook/http/interactive | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності Plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язки runtime, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, wait, version, argument-invocation і lazy command-group | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway client, Gateway CLI RPC, помилки протоколу Gateway і patch стану каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації плагінів, як-от `OpenClawConfig` і типи конфігурації каналів/провайдерів | - | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку plugin-config під час виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної зміни конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби snapshot конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot`, і setter-и test snapshot | - | `plugin-sdk/telegram-command-config` | Нормалізація назви/опису команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled Telegram contract недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення autolink для посилань на файли без широкого barrel `text-runtime` | - | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники approval-capability, допоміжні засоби auth/profile, native routing/runtime і форматування шляху структурованого відображення approval | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, Heartbeat, планувальник reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді та conversation-label | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, як-от `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і лінивих груп команд | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway, CLI RPC Gateway, помилок протоколу Gateway і патчів статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig` і типів конфігурації каналів/провайдерів | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації Plugin під час виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setter-и тестових знімків | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли bundled поверхня контракту Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файли без широкого barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Допоміжні засоби затвердження exec/plugin, побудовники можливостей затвердження, допоміжні засоби auth/профілів, native допоміжні засоби маршрутизації/runtime і форматування шляху структурованого відображення затверджень | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і міток розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, як-от `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking для text/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби для шляху session store, session-key, updated-at і зміни store | - | `plugin-sdk/cron-store-runtime` | Допоміжні засоби для шляху/load/save Cron store | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключів сесій, updated-at і мутації сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби summary стану каналу/облікового запису, стандартні значення runtime-state і допоміжні засоби метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби target resolver | + | `plugin-sdk/routing` | Допоміжні засоби прив’язки маршрутів/ключів сесій/облікових записів, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типових значень runtime state і метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування URL-рядків з input типу fetch/request | - | `plugin-sdk/run-command` | Виконавець команд із тайм-аутом і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | + | `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` | Витягування канонічних полів send target з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів для тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби subsystem logger і редагування | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілей надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби логера підсистеми та редагування | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму й перетворення таблиць Markdown | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби override моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk provider | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk-провайдера | | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби dedupe cache на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch | - | `plugin-sdk/acp-binding-resolve-runtime` | Визначення ACP binding лише для читання без import життєвого циклу запуску | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema для agent runtime | - | `plugin-sdk/boolean-param` | Нестрогий зчитувач boolean-параметрів | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковим зберіганням | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесій ACP і 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` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстрації/build/serialize native command | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих agent harness: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби мосту OpenClaw tool, допоміжні засоби policy інструментів runtime-plan, класифікація terminal outcome, допоміжні засоби форматування/деталізації прогресу інструментів і утиліти результатів спроб | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів спарювання | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, статусу та ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби виведення списку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native команд | + | `plugin-sdk/agent-harness` | Експериментальна surface довіреного Plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики tool плану runtime, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Допоміжні засоби system event/Heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого cache | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби для diagnostic flag, event і trace-context | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | - | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без import proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Обмежений зчитувач body відповіді без широкої поверхні media runtime | - | `plugin-sdk/session-binding-runtime` | Поточний стан binding conversation без configured binding routing або pairing store | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких import запису/обслуговування config | - | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту і фільтрація додаткового контексту без широких import config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації primitive record/string без import markdown/logging | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | + | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | + | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності асинхронних завдань | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | + | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб осушення черги очікуваної вихідної доставки | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів локальних файлів і джерел медіа | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | + | `plugin-sdk/number-runtime` | Допоміжний засіб приведення числових значень | + | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | + | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | + | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи runtime | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace context | + | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Засіб читання body відповіді з обмеженням без широкої media runtime surface | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ спарювання | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Допоміжні засоби визначення видимості контексту та фільтрації додаткового контексту без широких імпортів конфігурації/безпеки | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних записів/рядків без імпортів markdown/логування | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби для каталогу/ідентичності/workspace агента | - | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів на основі config | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації повторних спроб і виконавця повторних спроб | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогів/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для media, а також побудовники media payload | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники media payload | | `plugin-sdk/media-store` | Вузькі допоміжні засоби media store, як-от `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації media, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів розуміння media, а також орієнтовані на провайдерів експорти допоміжних засобів для image/audio | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, як-от видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби directive-tag і утиліти safe-text | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking для outbound text | - | `plugin-sdk/speech` | Типи провайдерів speech, а також орієнтовані на провайдерів експорти directive, registry, validation і допоміжних засобів speech | - | `plugin-sdk/speech-core` | Спільні типи провайдерів speech, registry, directive, normalization і експорти допоміжних засобів speech | - | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription, допоміжні засоби registry і спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби registry | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутні моделі | + | `plugin-sdk/media-understanding` | Типи провайдерів для розуміння медіа, а також провайдер-орієнтовані експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/Markdown/логування, як-от видалення тексту, видимого асистенту, допоміжні засоби рендерингу/chunking/таблиць Markdown, допоміжні засоби редагування, допоміжні засоби directive tag і утиліти безпечного тексту | + | `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 і registry | - | `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` | Допоміжні засоби registry цілей Webhook і встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних media | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | + | `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` для користувачів Plugin SDK | + | `plugin-sdk/testing` | Публічні допоміжні засоби тестування extensions, зокрема `installCommonResolveTargetErrorCases`, `shouldAckReaction`, `writeSkill`, `createTestRegistry` і завантаження env для live generation | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helper-ів | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексування/пошуку пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/допоміжних засобів CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embeddings хоста пам’яті, доступ до registry, локальний провайдер і загальні допоміжні засоби batch/remote | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і універсальні пакетні/віддалені допоміжні засоби | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби основного runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів основного runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для плагінів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста пам’яті | + | `plugin-sdk/memory-host-core` | Незалежний від постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Незалежний від постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Незалежний від постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого Markdown для Plugin, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | + | `plugin-sdk/memory-host-status` | Незалежний від постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | 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-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `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 | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/helper для bundled channel. Нові плагіни повинні імпортувати загальні підшляхи SDK або локальні barrel-експорти плагіна. | - | Допоміжні засоби auth/специфічні для плагінів | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser Plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `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` | Поверхня допоміжних засобів/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/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних засобів bundled channel. Нові Plugin мають імпортувати універсальні підшляхи SDK або локальні barrel Plugin. | + | Допоміжні засоби auth/специфічні для Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled features/Plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | @@ -298,4 +309,4 @@ x-i18n: - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення плагінів](/uk/plugins/building-plugins) +- [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/providers/index.md b/docs/uk/providers/index.md index 1c96e9603..0b2fa615a 100644 --- a/docs/uk/providers/index.md +++ b/docs/uk/providers/index.md @@ -1,24 +1,23 @@ --- read_when: - Ви хочете вибрати провайдера моделі - - Вам потрібен короткий огляд підтримуваних бекендів LLM + - Вам потрібен швидкий огляд підтримуваних LЛM-бекендів summary: Провайдери моделей (LLM), які підтримує OpenClaw title: Каталог провайдерів x-i18n: - generated_at: "2026-04-27T09:30:51Z" + generated_at: "2026-04-27T20:08:42Z" model: gpt-5.4 provider: openai - source_hash: 5a20e0fd3464755880656da60e95d72e214dd13fc99d9aa4f3b7daaa212d12ec + source_hash: 61143200b2e7a74392cf8871bfcd210fe35dbd5118e2e8bc7b15265192fd2bde source_path: providers/index.md workflow: 15 --- # Провайдери моделей -OpenClaw може використовувати багато провайдерів LLM. Виберіть провайдера, пройдіть автентифікацію, а потім установіть -модель за замовчуванням у форматі `provider/model`. +OpenClaw може використовувати багато провайдерів LLM. Виберіть провайдера, пройдіть автентифікацію, а потім задайте модель за замовчуванням у форматі `provider/model`. -Шукаєте документацію про chat-канали (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/тощо)? Див. [Channels](/uk/channels). +Шукаєте документацію для чат-каналів (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/тощо)? Див. [Канали](/uk/channels). ## Швидкий старт @@ -49,14 +48,14 @@ OpenClaw може використовувати багато провайдер - [fal](/uk/providers/fal) - [Fireworks](/uk/providers/fireworks) - [GitHub Copilot](/uk/providers/github-copilot) -- [Gradium](/uk/providers/gradium) - [Моделі GLM](/uk/providers/glm) - [Google (Gemini)](/uk/providers/google) +- [Gradium](/uk/providers/gradium) - [Groq (LPU-інференс)](/uk/providers/groq) -- [Hugging Face (Inference)](/uk/providers/huggingface) +- [Hugging Face (інференс)](/uk/providers/huggingface) - [inferrs (локальні моделі)](/uk/providers/inferrs) - [Kilocode](/uk/providers/kilocode) -- [LiteLLM (уніфікований gateway)](/uk/providers/litellm) +- [LiteLLM (уніфікований Gateway)](/uk/providers/litellm) - [LM Studio (локальні моделі)](/uk/providers/lmstudio) - [MiniMax](/uk/providers/minimax) - [Mistral](/uk/providers/mistral) @@ -77,7 +76,7 @@ OpenClaw може використовувати багато провайдер - [Synthetic](/uk/providers/synthetic) - [Tencent Cloud (TokenHub)](/uk/providers/tencent) - [Together AI](/uk/providers/together) -- [Venice (Venice AI, зосереджений на конфіденційності)](/uk/providers/venice) +- [Venice (Venice AI, з акцентом на приватність)](/uk/providers/venice) - [Vercel AI Gateway](/uk/providers/vercel-ai-gateway) - [vLLM (локальні моделі)](/uk/providers/vllm) - [Volcengine (Doubao)](/uk/providers/volcengine) @@ -89,9 +88,9 @@ OpenClaw може використовувати багато провайдер ## Спільні оглядові сторінки - [Додаткові вбудовані варіанти](/uk/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy і Gemini CLI OAuth -- [Генерація зображень](/uk/tools/image-generation) - спільний інструмент `image_generate`, вибір провайдера та failover -- [Генерація музики](/uk/tools/music-generation) - спільний інструмент `music_generate`, вибір провайдера та failover -- [Генерація відео](/uk/tools/video-generation) - спільний інструмент `video_generate`, вибір провайдера та failover +- [Генерація зображень](/uk/tools/image-generation) - Спільний інструмент `image_generate`, вибір провайдера та failover +- [Генерація музики](/uk/tools/music-generation) - Спільний інструмент `music_generate`, вибір провайдера та failover +- [Генерація відео](/uk/tools/video-generation) - Спільний інструмент `video_generate`, вибір провайдера та failover ## Провайдери транскрибування @@ -104,7 +103,6 @@ OpenClaw може використовувати багато провайдер ## Інструменти спільноти -- [Claude Max API Proxy](/uk/providers/claude-max-api-proxy) - проксі від спільноти для облікових даних підписки Claude (перед використанням перевірте політику/умови Anthropic) +- [Claude Max API Proxy](/uk/providers/claude-max-api-proxy) - Проксі від спільноти для облікових даних підписки Claude (перед використанням перевірте політику/умови Anthropic) -Повний каталог провайдерів (xAI, Groq, Mistral тощо) та розширену конфігурацію -див. у [Model providers](/uk/concepts/model-providers). +Повний каталог провайдерів (xAI, Groq, Mistral тощо) і розширену конфігурацію див. у розділі [Провайдери моделей](/uk/concepts/model-providers). diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index c5cd9f95f..59c421119 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,75 +1,75 @@ --- read_when: - - Вам потрібно налагодити ідентифікатори сеансів, JSONL транскриптів або поля sessions.json - - Ви змінюєте поведінку авто-Compaction або додаєте підготовче обслуговування перед Compaction + - Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля в sessions.json + - Ви змінюєте поведінку авто-Compaction або додаєте прибирання перед Compaction - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Поглиблений розбір: сховище сеансів і транскрипти, життєвий цикл та внутрішня логіка (авто)Compaction' -title: Поглиблений розбір керування сеансами +summary: 'Глибокий огляд: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)Compaction' +title: Глибокий огляд керування сесіями x-i18n: - generated_at: "2026-04-27T14:21:20Z" + generated_at: "2026-04-27T20:08:48Z" model: gpt-5.4 provider: openai - source_hash: ccbfd09d01a12d38ab71510fbb81416283fc6c6459ff66ee82e36868e008d118 + source_hash: aeb8a0569bc6ae1f1512107a4d0aef2b7caa43fac8ef6d0f1c0cc1a101451430 source_path: reference/session-management-compaction.md workflow: 15 --- -OpenClaw керує сеансами наскрізно в таких напрямах: +OpenClaw керує сесіями наскрізно в таких ділянках: -- **Маршрутизація сеансів** (як вхідні повідомлення зіставляються з `sessionKey`) -- **Сховище сеансів** (`sessions.json`) і те, що воно відстежує -- **Збереження транскриптів** (`*.jsonl`) і їхня структура -- **Гігієна транскриптів** (виправлення, специфічні для провайдера, перед запусками) +- **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`) +- **Сховище сесій** (`sessions.json`) і що саме воно відстежує +- **Збереження транскриптів** (`*.jsonl`) та їхню структуру +- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запуском) - **Обмеження контексту** (вікно контексту проти відстежуваних токенів) - **Compaction** (ручний і автоматичний Compaction) та де підключати роботу перед Compaction - **Тихе службове обслуговування** (записи пам’яті, які не повинні створювати видимий для користувача вивід) -Якщо вам спершу потрібен огляд вищого рівня, почніть із: +Якщо спершу вам потрібен огляд вищого рівня, почніть із: -- [Керування сеансами](/uk/concepts/session) +- [Керування сесіями](/uk/concepts/session) - [Compaction](/uk/concepts/compaction) - [Огляд пам’яті](/uk/concepts/memory) - [Пошук у пам’яті](/uk/concepts/memory-search) -- [Очищення сеансів](/uk/concepts/session-pruning) +- [Обрізання сесій](/uk/concepts/session-pruning) - [Гігієна транскриптів](/uk/reference/transcript-hygiene) --- ## Джерело істини: Gateway -OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сеансу. +OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. -- UI (macOS app, веб Control UI, TUI) мають звертатися до Gateway за списками сеансів і кількістю токенів. -- У віддаленому режимі файли сеансів розміщені на віддаленому хості; «перевірка локальних файлів на вашому Mac» не покаже того, що фактично використовує Gateway. +- Інтерфейси (застосунок macOS, вебінтерфейс Control UI, TUI) повинні запитувати в Gateway списки сесій і кількість токенів. +- У віддаленому режимі файли сесій розміщуються на віддаленому хості; «перевірка локальних файлів на Mac» не відображатиме те, що використовує Gateway. --- ## Два шари збереження -OpenClaw зберігає сеанси у двох шарах: +OpenClaw зберігає сесії у двох шарах: -1. **Сховище сеансів (`sessions.json`)** +1. **Сховище сесій (`sessions.json`)** - Мапа ключ/значення: `sessionKey -> SessionEntry` - - Маленьке, змінюване, безпечно редагується (або можна видаляти записи) - - Відстежує метадані сеансу (поточний ідентифікатор сеансу, останню активність, перемикачі, лічильники токенів тощо) + - Невелике, змінюване, безпечне для редагування (або видалення записів) + - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - Транскрипт лише з додаванням із деревоподібною структурою (записи мають `id` + `parentId`) - - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction + - Зберігає фактичну розмову + виклики інструментів + зведення Compaction - Використовується для відновлення контексту моделі для майбутніх ходів - Великі контрольні точки налагодження до Compaction пропускаються, щойно активний - транскрипт перевищує обмеження розміру контрольної точки, що дозволяє уникнути другої гігантської + транскрипт перевищує ліміт розміру контрольної точки, що дозволяє уникнути другої гігантської копії `.checkpoint.*.jsonl`. --- ## Розташування на диску -Для кожного агента, на хості Gateway: +Для кожного агента на хості Gateway: - Сховище: `~/.openclaw/agents//sessions/sessions.json` - Транскрипти: `~/.openclaw/agents//sessions/.jsonl` - - Сеанси тем Telegram: `.../-topic-.jsonl` + - Сесії тем Telegram: `.../-topic-.jsonl` OpenClaw визначає ці шляхи через `src/config/sessions.ts`. @@ -77,27 +77,27 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`. ## Обслуговування сховища та контроль диска -Збереження сеансів має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: +Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів транскриптів і супровідних файлів траєкторій: -- `mode`: `warn` (за замовчуванням) або `enforce` -- `pruneAfter`: поріг віку застарілих записів (за замовчуванням `30d`) -- `maxEntries`: обмеження кількості записів у `sessions.json` (за замовчуванням `500`) -- `rotateBytes`: ротація `sessions.json`, коли файл стає завеликим (за замовчуванням `10mb`) -- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.` (за замовчуванням: такий самий, як `pruneAfter`; `false` вимикає очищення) -- `maxDiskBytes`: необов’язковий бюджет каталогу сеансів -- `highWaterBytes`: необов’язкове цільове значення після очищення (за замовчуванням `80%` від `maxDiskBytes`) +- `mode`: `warn` (типово) або `enforce` +- `pruneAfter`: поріг віку застарілих записів для очищення (типово `30d`) +- `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) +- `rotateBytes`: ротація `sessions.json`, коли файл перевищує розмір (типово `10mb`) +- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) +- `maxDiskBytes`: необов’язковий бюджет каталогу сесій на диску +- `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Звичайні записи Gateway пакетно очищають `maxEntries` для обмежень виробничого масштабу, тому сховище може тимчасово перевищувати налаштоване обмеження до наступного очищення за верхнім порогом, яке знову зменшить його до заданого рівня. `openclaw sessions cleanup --enforce` усе ще негайно застосовує налаштоване обмеження. +Звичайні записи Gateway пакетно очищають `maxEntries` для лімітів виробничого масштабу, тож сховище може тимчасово перевищити налаштоване обмеження до наступного очищення за верхньою межею, яке знову зменшить його. `openclaw sessions cleanup --enforce` однак застосовує налаштований ліміт негайно. -Порядок примусового очищення для бюджету диска (`mode: "enforce"`): +Порядок примусового очищення бюджету диска (`mode: "enforce"`): -1. Спочатку видаляються найстаріші архівовані або осиротілі артефакти транскриптів. -2. Якщо цього все ще недостатньо, витісняються найстаріші записи сеансів та їхні файли транскриптів. -3. Процес триває, доки використання не стане меншим або рівним `highWaterBytes`. +1. Спочатку видалити найстаріші архівні, осиротілі транскрипти або осиротілі артефакти траєкторій. +2. Якщо використання все ще вище цільового значення, витіснити найстаріші записи сесій і їхні файли транскриптів/траєкторій. +3. Продовжувати, доки використання не стане на рівні `highWaterBytes` або нижче. -У `mode: "warn"` OpenClaw повідомляє про потенційні витіснення, але не змінює сховище/файли. +У режимі `mode: "warn"` OpenClaw повідомляє про можливі витіснення, але не змінює сховище/файли. -Запуск обслуговування на вимогу: +Запускайте обслуговування за потреби: ```bash openclaw sessions cleanup --dry-run @@ -106,85 +106,85 @@ openclaw sessions cleanup --enforce --- -## Cron-сеанси та журнали запусків +## Cron-сесії та журнали запусків -Ізольовані запуски cron також створюють записи/транскрипти сеансів, і для них є окремі механізми зберігання: +Ізольовані запуски Cron теж створюють записи сесій/транскрипти й мають окремі параметри зберігання: -- `cron.sessionRetention` (за замовчуванням `24h`) очищає старі ізольовані сеанси запусків cron зі сховища сеансів (`false` вимикає це). -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищають файли `~/.openclaw/cron/runs/.jsonl` (за замовчуванням: `2_000_000` байтів і `2000` рядків). +- `cron.sessionRetention` (типово `24h`) очищає старі ізольовані сесії запусків Cron зі сховища сесій (`false` вимикає це). +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищають файли `~/.openclaw/cron/runs/.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків). -Коли cron примусово створює новий ізольований сеанс запуску, він санітизує попередній -запис сеансу `cron:` перед записом нового рядка. Він переносить безпечні -налаштування, як-от параметри thinking/fast/verbose, мітки та явні -перевизначення моделі/auth, вибрані користувачем. Він відкидає навколишній контекст розмови, -такий як маршрутизація channel/group, політика надсилання чи черги, підвищення привілеїв, походження та прив’язка runtime ACP, -щоб новий ізольований запуск не міг успадкувати застарілу доставку або -повноваження runtime від старішого запуску. +Коли Cron примусово створює нову ізольовану сесію запуску, він санітизує попередній +запис сесії `cron:` перед записом нового рядка. Він переносить безпечні +налаштування, такі як параметри thinking/fast/verbose, мітки та явні +вибрані користувачем перевизначення моделі/автентифікації. Він відкидає фоновий +контекст розмови, такий як маршрутизація каналу/групи, політика надсилання або черги, +підвищення привілеїв, походження та прив’язка середовища виконання ACP, щоб новий +ізольований запуск не міг успадкувати застарілу доставку або повноваження +середовища виконання від старішого запуску. --- -## Ключі сеансів (`sessionKey`) +## Ключі сесій (`sessionKey`) `sessionKey` визначає, _у якому кошику розмови_ ви перебуваєте (маршрутизація + ізоляція). -Типові шаблони: +Поширені шаблони: -- Основний/прямий чат (для агента): `agent::` (за замовчуванням `main`) +- Основний/прямий чат (для кожного агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` - Webhook: `hook:` (якщо не перевизначено) -Канонічні правила описано в [/concepts/session](/uk/concepts/session). +Канонічні правила задокументовано тут: [/concepts/session](/uk/concepts/session). --- -## Ідентифікатори сеансів (`sessionId`) +## Ідентифікатори сесій (`sessionId`) Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, що продовжує розмову). -Основні правила: +Практичні правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (за замовчуванням о 4:00 за місцевим часом хоста gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання. -- **Завершення через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне скидання, і завершення через бездіяльність, спрацьовує те, що завершується раніше. -- **Системні події** (Heartbeat, cron wakeups, сповіщення exec, службовий облік gateway) можуть змінювати рядок сеансу, але не подовжують свіжість щоденного скидання/скидання через бездіяльність. Під час переходу на новий сеанс через скидання queued-сповіщення системних подій для попереднього сеансу відкидаються до побудови нового запиту. -- **Захист від fork батьківського потоку** (`session.parentForkMaxTokens`, за замовчуванням `100000`) пропускає fork батьківського транскрипту, якщо батьківський сеанс уже надто великий; новий потік починається з нуля. Установіть `0`, щоб вимкнути. +- **Щоденне скидання** (типово о 4:00 ранку за локальним часом хоста gateway) створює новий `sessionId` при наступному повідомленні після межі скидання. +- **Завершення через неактивність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна неактивності. Якщо налаштовані і щоденне скидання, і неактивність, спрацьовує те, що настане раніше. +- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, службове обслуговування gateway) можуть змінювати рядок сесії, але не подовжують актуальність щоденного скидання/скидання через неактивність. Під час переходу через скидання відкладені сповіщення системних подій для попередньої сесії відкидаються до побудови нового запиту. +- **Захист від відгалуження батьківського ланцюжка** (`session.parentForkMaxTokens`, типово `100000`) пропускає відгалуження батьківського транскрипту, якщо батьківська сесія вже надто велика; новий потік починається заново. Установіть `0`, щоб вимкнути. -Деталь реалізації: рішення приймається в `initSessionState()` у `src/auto-reply/reply/session.ts`. +Деталь реалізації: рішення ухвалюється в `initSessionState()` у `src/auto-reply/reply/session.ts`. --- -## Схема сховища сеансів (`sessions.json`) +## Схема сховища сесій (`sessions.json`) Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`. -Ключові поля (неповний перелік): +Ключові поля (не вичерпно): - `sessionId`: поточний ідентифікатор транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`) -- `sessionStartedAt`: час початку поточного `sessionId`; саме він визначає - свіжість щоденного скидання. Для застарілих рядків може виводитися із заголовка сеансу JSONL. -- `lastInteractionAt`: час останньої реальної взаємодії користувача/каналу; саме він визначає - свіжість скидання через бездіяльність, тому Heartbeat, cron і події exec не підтримують сеанси - активними. Для застарілих рядків без цього поля як свіжість для бездіяльності використовується - відновлений час початку сеансу. -- `updatedAt`: час останньої зміни рядка сховища, використовується для списків, очищення та - службового обліку. Це не авторитетне поле для свіжості щоденного скидання/скидання через бездіяльність. -- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту -- `chatType`: `direct | group | room` (допомагає UI та політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для міток груп/каналів +- `sessionStartedAt`: позначка часу початку для поточного `sessionId`; саме її використовує актуальність щоденного скидання. + У застарілих рядках вона може виводитися із заголовка сесії в JSONL. +- `lastInteractionAt`: позначка часу останньої реальної взаємодії користувача/каналу; саме її використовує актуальність + скидання через неактивність, тому події heartbeat, cron і exec не підтримують життя сесії. + Для застарілих рядків без цього поля використовується відновлений час початку сесії. +- `updatedAt`: позначка часу останньої зміни рядка сховища, яка використовується для виведення списків, очищення та + службового обліку. Це не авторитетне поле для актуальності щоденного скидання/скидання через неактивність. +- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту +- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання) +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - - `sendPolicy` (перевизначення для конкретного сеансу) + - `sendPolicy` (перевизначення для конкретної сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` - Лічильники токенів (best-effort / залежать від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: скільки разів авто-Compaction завершувався для цього ключа сеансу -- `memoryFlushAt`: час останнього скидання пам’яті перед Compaction -- `memoryFlushCompactionCount`: кількість Compaction на момент останнього скидання +- `compactionCount`: скільки разів авто-Compaction завершувався для цього ключа сесії +- `memoryFlushAt`: позначка часу останнього скидання пам’яті перед Compaction +- `memoryFlushCompactionCount`: лічильник Compaction на момент останнього скидання -Сховище безпечно редагувати, але авторитетом лишається Gateway: у процесі роботи з сеансами він може переписувати або повторно гідратувати записи. +Сховище безпечно редагувати, але Gateway є джерелом істини: під час виконання сесій він може перезаписувати або повторно гідратувати записи. --- @@ -194,16 +194,16 @@ openclaw sessions cleanup --enforce Файл має формат JSONL: -- Перший рядок: заголовок сеансу (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язково `parentSession`) -- Далі: записи сеансу з `id` + `parentId` (дерево) +- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язковий `parentSession`) +- Далі: записи сесії з `id` + `parentId` (дерево) Помітні типи записів: - `message`: повідомлення user/assistant/toolResult -- `custom_message`: повідомлення, інжектовані розширенням, які _входять_ в контекст моделі (можуть бути приховані від UI) -- `custom`: стан розширення, який _не_ входить в контекст моделі -- `compaction`: збережений підсумок Compaction із `firstKeptEntryId` і `tokensBefore` -- `branch_summary`: збережений підсумок під час навігації гілкою дерева +- `custom_message`: повідомлення, вставлені розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від інтерфейсу) +- `custom`: стан розширення, який _не потрапляє_ у контекст моделі +- `compaction`: збережене зведення Compaction з `firstKeptEntryId` і `tokensBefore` +- `branch_summary`: збережене зведення під час навігації гілкою дерева OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. @@ -211,45 +211,46 @@ OpenClaw навмисно **не** «виправляє» транскрипти ## Вікна контексту проти відстежуваних токенів -Важливі два різні поняття: +Важливі дві різні концепції: -1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сеансів**: ковзні статистики, записані в `sessions.json` (використовуються для /status і панелей керування) +1. **Вікно контексту моделі**: жорстке обмеження для моделі (токени, видимі моделі) +2. **Лічильники сховища сесій**: ковзна статистика, записувана в `sessions.json` (використовується для /status і панелей) -Якщо ви налаштовуєте обмеження: +Якщо ви налаштовуєте ліміти: - Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — це оцінка/значення звітності під час runtime; не вважайте його суворою гарантією. +- `contextTokens` у сховищі — це оцінка/звітне значення під час виконання; не сприймайте його як сувору гарантію. -Докладніше: [/token-use](/uk/reference/token-use). +Докладніше див. [/token-use](/uk/reference/token-use). --- ## Compaction: що це таке -Compaction підсумовує старішу частину розмови в збережений запис `compaction` у транскрипті та зберігає недавні повідомлення без змін. +Compaction підсумовує старішу частину розмови у збережений запис `compaction` у транскрипті та залишає недоторканими недавні повідомлення. Після Compaction майбутні ходи бачать: -- Підсумок Compaction +- Зведення Compaction - Повідомлення після `firstKeptEntryId` -Compaction є **постійним** (на відміну від очищення сеансу). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). +Compaction є **постійним** (на відміну від обрізання сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). -## Межі фрагментів Compaction і парування інструментів +## Межі блоків Compaction і парування інструментів -Коли OpenClaw ділить довгий транскрипт на фрагменти для Compaction, він зберігає -виклики інструментів assistant разом із відповідними записами `toolResult`. +Коли OpenClaw ділить довгий транскрипт на блоки Compaction, він зберігає +виклики інструментів від assistant у парі з відповідними записами `toolResult`. -- Якщо поділ за часткою токенів потрапляє між викликом інструмента та його результатом, OpenClaw - зміщує межу до повідомлення assistant із викликом інструмента, а не розділяє пару. -- Якщо кінцевий блок результатів інструментів інакше змусив би фрагмент перевищити цільовий розмір, - OpenClaw зберігає цей очікувальний блок інструментів і залишає непідсумований хвіст без змін. -- Перервані/помилкові блоки викликів інструментів не утримують відкритим очікувальний поділ. +- Якщо межа поділу за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw + зсуває межу до повідомлення assistant із викликом інструмента, а не розділяє + пару. +- Якщо кінцевий блок результатів інструментів інакше виштовхнув би блок за цільовий розмір, + OpenClaw зберігає цей очікуваний блок інструментів і залишає непідсумований хвіст недоторканим. +- Перервані/помилкові блоки викликів інструментів не утримують очікуваний поділ відкритим. --- -## Коли відбувається авто-Compaction (Pi runtime) +## Коли відбувається авто-Compaction (середовище виконання Pi) У вбудованому агенті Pi авто-Compaction спрацьовує у двох випадках: @@ -257,7 +258,7 @@ Compaction є **постійним** (на відміну від очищенн (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` та схожі варіанти, сформовані провайдером) → виконати Compaction → повторити спробу. +exceeded` та подібні варіанти, сформовані провайдером) → compact → повторити спробу. 2. **Порогове обслуговування**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` @@ -265,22 +266,22 @@ exceeded` та схожі варіанти, сформовані провайд Де: - `contextWindow` — це вікно контексту моделі -- `reserveTokens` — це запас, зарезервований для запитів + наступного виводу моделі +- `reserveTokens` — це запас токенів, зарезервований для запитів + наступного виводу моделі -Це семантика runtime Pi (OpenClaw споживає події, але рішення про Compaction приймає Pi). +Це семантика середовища виконання Pi (OpenClaw споживає події, але рішення про Compaction приймає Pi). OpenClaw також може запускати локальний попередній Compaction перед відкриттям наступного -запуску, коли встановлено `agents.defaults.compaction.maxActiveTranscriptBytes` і -активний файл транскрипту досягає цього розміру. Це захист за розміром файлу для локальної -вартості повторного відкриття, а не сире архівування: OpenClaw усе одно виконує звичайний семантичний Compaction, -і для цього потрібен `truncateAfterCompaction`, щоб стиснений підсумок міг стати -новим наступним транскриптом. +запуску, якщо задано `agents.defaults.compaction.maxActiveTranscriptBytes` і +активний файл транскрипту досягає цього розміру. Це запобіжник розміру файлу для локальної +вартості повторного відкриття, а не просто архівування: OpenClaw усе одно виконує звичайний +семантичний Compaction, і для цього потрібен `truncateAfterCompaction`, щоб зведення після Compaction +могло стати новим транскриптом-наступником. --- ## Налаштування Compaction (`reserveTokens`, `keepRecentTokens`) -Налаштування Compaction у Pi знаходяться в налаштуваннях Pi: +Налаштування Pi для Compaction розташовані в параметрах Pi: ```json5 { @@ -295,24 +296,24 @@ OpenClaw також може запускати локальний попере OpenClaw також застосовує мінімальний безпечний поріг для вбудованих запусків: - Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення. -- Мінімальний поріг за замовчуванням — `20000` токенів. +- Типовий мінімальний поріг — `20000` токенів. - Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. -- Якщо значення вже вище, OpenClaw не змінює його. -- Ручний `/compact` враховує явне `agents.defaults.compaction.keepRecentTokens` - і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету збереження - ручний Compaction залишається жорсткою контрольною точкою, а відновлений контекст починається - з нового підсумку. -- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у байтове значення або - рядок на кшталт `"20mb"`, щоб виконувати локальний Compaction перед ходом, коли активний - транскрипт стає великим. Цей захист активний лише тоді, коли - також увімкнено `truncateAfterCompaction`. Залиште значення не заданим або встановіть `0`, - щоб вимкнути. +- Якщо значення вже вище, OpenClaw залишає його без змін. +- Ручний `/compact` враховує явний `agents.defaults.compaction.keepRecentTokens` + і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету на збереження + ручний Compaction лишається жорсткою контрольною точкою, а відновлений контекст починається + з нового зведення. +- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у значення байтів або + рядок на кшталт `"20mb"`, щоб запускати локальний Compaction перед ходом, коли активний + транскрипт стає великим. Цей запобіжник активний лише тоді, коли + також увімкнено `truncateAfterCompaction`. Залиште значення не заданим або встановіть `0`, щоб + вимкнути. - Коли увімкнено `agents.defaults.compaction.truncateAfterCompaction`, - OpenClaw після Compaction переносить активний транскрипт до стисненого successor JSONL. - Старий повний транскрипт залишається в архіві й зв’язується з контрольної точки - Compaction замість переписування на місці. + OpenClaw після Compaction ротуватиме активний транскрипт у компактний JSONL-наступник. + Старий повний транскрипт залишиться заархівованим і буде зв’язаний із + контрольною точкою Compaction замість перезапису на місці. -Чому: залишити достатній запас для багатокрокового «службового обслуговування» (наприклад, записів пам’яті) до того, як Compaction стане неминучим. +Чому: щоб залишити достатній запас для багатокрокового «службового обслуговування» (наприклад, записів у пам’ять) до того, як Compaction стане неминучим. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). @@ -321,101 +322,101 @@ OpenClaw також застосовує мінімальний безпечни ## Підключувані провайдери Compaction -Plugin можуть реєструвати провайдера Compaction через `registerCompactionProvider()` в API plugin. Коли `agents.defaults.compaction.provider` встановлено в id зареєстрованого провайдера, захисне розширення делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. +Plugin можуть реєструвати провайдера Compaction через `registerCompactionProvider()` у API Plugin. Коли `agents.defaults.compaction.provider` встановлено в ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. -- `provider`: id зареєстрованого plugin-провайдера Compaction. Залиште порожнім для типового підсумовування LLM. -- Установлення `provider` примусово вмикає `mode: "safeguard"`. +- `provider`: ідентифікатор зареєстрованого Plugin-провайдера Compaction. Залиште не заданим для типового підсумовування LLM. +- Встановлення `provider` примусово задає `mode: "safeguard"`. - Провайдери отримують ті самі інструкції Compaction і політику збереження ідентифікаторів, що й вбудований шлях. -- Захисний режим і далі зберігає контекст суфікса недавніх ходів і розділених ходів після виводу провайдера. -- Вбудоване підсумовування safeguard повторно дистилює попередні підсумки разом із новими повідомленнями - замість того, щоб дослівно зберігати весь попередній підсумок. -- Режим safeguard за замовчуванням вмикає аудити якості підсумків; установіть - `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби за некоректного виводу. -- Якщо провайдер зазнає збою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого підсумовування LLM. -- Сигнали abort/timeout повторно викидаються (не приглушуються), щоб поважати скасування викликальника. +- Safeguard усе одно зберігає контекст суфікса недавніх ходів і розділених ходів після виводу провайдера. +- Вбудоване підсумовування safeguard повторно дистилює попередні зведення разом із новими повідомленнями, + замість того щоб зберігати повне попереднє зведення дослівно. +- Режим safeguard типово вмикає аудити якості зведення; установіть + `qualityGuard.enabled: false`, щоб пропустити логіку повторної спроби за неправильно сформованого виводу. +- Якщо провайдер зазнає невдачі або повертає порожній результат, OpenClaw автоматично повертається до вбудованого підсумовування LLM. +- Сигнали abort/timeout повторно викидаються як є (не поглинаються), щоб поважати скасування з боку викликача. Джерело: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. --- -## Поверхні, видимі користувачеві +## Видимі для користувача поверхні -Спостерігати за Compaction і станом сеансу можна через: +Ви можете спостерігати за Compaction і станом сесії через: -- `/status` (у будь-якому чат-сеансі) +- `/status` (у будь-якій чат-сесії) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Докладний режим: `🧹 Auto-compaction complete` + лічильник Compaction +- Докладний режим: `🧹 Auto-compaction complete` + кількість Compaction --- ## Тихе службове обслуговування (`NO_REPLY`) -OpenClaw підтримує «тихі» ходи для фонових завдань, коли користувач не повинен бачити проміжний вивід. +OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. -Узгодження: +Домовленість: -- Assistant починає свій вивід із точного тихого токена `NO_REPLY` / - `no_reply`, щоб позначити «не надсилати відповідь користувачеві». -- OpenClaw прибирає/приглушує це на рівні доставки. -- Приглушення точного тихого токена нечутливе до регістру, тому `NO_REPLY` і - `no_reply` зараховуються, коли все навантаження складається лише з тихого токена. -- Це лише для справжніх фонових ходів без доставки; це не скорочення для +- Assistant починає свій вивід з точного тихого токена `NO_REPLY` / + `no_reply`, щоб позначити «не доставляти відповідь користувачу». +- OpenClaw прибирає/пригнічує це на рівні доставки. +- Пригнічення точного тихого токена є нечутливим до регістру, тож `NO_REPLY` і + `no_reply` обидва зараховуються, коли весь вміст складається лише з тихого токена. +- Це призначено тільки для справжніх фонових ходів / ходів без доставки; це не скорочення для звичайних дієвих запитів користувача. -Починаючи з `2026.1.10`, OpenClaw також приглушує **draft/typing streaming**, коли -частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали -частковий вивід посеред ходу. +Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокове чернеткове введення/набирання**, коли +частковий блок починається з `NO_REPLY`, щоб тихі операції не розкривали частковий +вивід посеред ходу. --- ## «Скидання пам’яті» перед Compaction (реалізовано) -Мета: до того, як відбудеться авто-Compaction, виконати тихий агентний хід, який запише сталий +Мета: перед тим, як станеться авто-Compaction, виконати тихий агентний хід, який записує тривалий стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб Compaction не міг стерти критичний контекст. -OpenClaw використовує підхід **скидання перед порогом**: +OpenClaw використовує підхід **скидання до досягнення порога**: -1. Відстежувати використання контексту сеансу. -2. Коли воно перетинає «м’який поріг» (нижче за поріг Compaction у Pi), запустити тиху - директиву «запиши пам’ять зараз» для агента. +1. Відстежувати використання контексту сесії. +2. Коли воно перетинає «м’який поріг» (нижче за поріг Compaction у Pi), запускати тиху + інструкцію «запиши пам’ять зараз» для агента. 3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач нічого не бачив. Конфігурація (`agents.defaults.compaction.memoryFlush`): -- `enabled` (за замовчуванням: `true`) -- `softThresholdTokens` (за замовчуванням: `4000`) +- `enabled` (типово: `true`) +- `softThresholdTokens` (типово: `4000`) - `prompt` (повідомлення користувача для ходу скидання) - `systemPrompt` (додатковий системний запит, доданий для ходу скидання) Примітки: -- Prompt/system prompt за замовчуванням містять підказку `NO_REPLY` для приглушення +- Типовий prompt/systemPrompt містить підказку `NO_REPLY` для пригнічення доставки. - Скидання виконується один раз за цикл Compaction (відстежується в `sessions.json`). -- Скидання виконується лише для вбудованих сеансів Pi (backend CLI його пропускають). -- Скидання пропускається, коли робочий простір сеансу доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Опис розмітки файлів робочого простору та шаблонів запису див. у [Пам’ять](/uk/concepts/memory). +- Скидання виконується лише для вбудованих Pi-сесій (бекенди CLI його пропускають). +- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Див. [Пам’ять](/uk/concepts/memory), щоб ознайомитися зі структурою файлів робочого простору та шаблонами запису. -Pi також надає hook `session_before_compact` в API розширення, але логіка -скидання в OpenClaw сьогодні розміщена на боці Gateway. +Pi також надає хук `session_before_compact` в API розширень, але логіка +скидання OpenClaw сьогодні розміщена на боці Gateway. --- -## Контрольний список усунення неполадок +## Контрольний список усунення несправностей -- Неправильний ключ сеансу? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. +- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. - Невідповідність між сховищем і транскриптом? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`. - Надто частий Compaction? Перевірте: - вікно контексту моделі (занадто мале) - - налаштування Compaction (`reserveTokens` занадто велике для вікна моделі може викликати раніший Compaction) - - роздування `toolResult`: увімкніть/налаштуйте очищення сеансу -- Витік тихих ходів? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення приглушення streaming. + - налаштування Compaction (`reserveTokens`, завелике для вікна моделі, може спричиняти раніший Compaction) + - роздуття `toolResult`: увімкніть/налаштуйте обрізання сесій +- Тихі ходи просочуються? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення потокового виводу. ## Пов’язане -- [Керування сеансами](/uk/concepts/session) -- [Очищення сеансів](/uk/concepts/session-pruning) +- [Керування сесіями](/uk/concepts/session) +- [Обрізання сесій](/uk/concepts/session-pruning) - [Рушій контексту](/uk/concepts/context-engine) diff --git a/docs/uk/tools/trajectory.md b/docs/uk/tools/trajectory.md index bc665df87..b738f3307 100644 --- a/docs/uk/tools/trajectory.md +++ b/docs/uk/tools/trajectory.md @@ -1,35 +1,33 @@ --- read_when: - - Налагодження того, чому агент відповів, завершився помилкою або викликав інструменти певним чином - - Експортування support-бандла для сесії OpenClaw - - Дослідження контексту prompt-ів, викликів інструментів, помилок runtime або метаданих використання - - Вимкнення або перенесення запису trajectory -summary: Експорт скорочених trajectory-бандлів для налагодження сесії агента OpenClaw -title: Trajectory-бандли + - Налагодження причин, чому агент відповів, зазнав збою або викликав інструменти певним чином + - Експорт пакета підтримки для сеансу OpenClaw + - Розслідування контексту підказки, викликів інструментів, помилок середовища виконання або метаданих використання + - Вимкнення або перенесення захоплення траєкторій +summary: Експортуйте відредаговані пакети траєкторій для налагодження сеансу агента OpenClaw +title: Пакети траєкторій x-i18n: - generated_at: "2026-04-23T23:09:01Z" + generated_at: "2026-04-27T20:09:05Z" model: gpt-5.4 provider: openai - source_hash: be799691e0c3375efd24e3bec9ce8f9ab22f01a0f8a9ce4288b7e6e952c29da4 + source_hash: bca4fa444ad84b59c7508767ec1b950fdde073c0b83771c9d63e3e71c239840d source_path: tools/trajectory.md workflow: 15 --- -Запис trajectory — це вбудований у OpenClaw “чорний ящик” для кожної сесії. Він записує -структуровану часову шкалу для кожного запуску агента, а потім `/export-trajectory` пакує -поточну сесію в скорочений support-бандл. +Захоплення траєкторій — це помодульний бортовий самописець OpenClaw для кожного сеансу. Воно записує структуровану часову шкалу для кожного запуску агента, а потім `/export-trajectory` пакує поточний сеанс у відредагований пакет підтримки. -Використовуйте це, коли вам потрібно відповісти на запитання на кшталт: +Використовуйте це, коли потрібно відповісти на такі запитання: -- Які prompt, system prompt та інструменти були надіслані моделі? -- Які повідомлення транскрипту й виклики інструментів привели до цієї відповіді? -- Чи запуск завершився timeout, abort, Compaction або помилкою провайдера? -- Які модель, Plugin-и, Skills і налаштування runtime були активними? -- Які метадані usage і prompt-cache повернув провайдер? +- Які prompt, системний prompt та інструменти були надіслані моделі? +- Які повідомлення транскрипту та виклики інструментів привели до цієї відповіді? +- Чи завершився запуск через тайм-аут, переривання, Compaction або помилку провайдера? +- Які модель, plugins, Skills і налаштування середовища виконання були активні? +- Які метадані використання та кешу prompt повернув провайдер? ## Швидкий старт -Надішліть це в активній сесії: +Надішліть це в активному сеансі: ```text /export-trajectory @@ -41,7 +39,7 @@ x-i18n: /trajectory ``` -OpenClaw записує бандл у робочий простір: +OpenClaw записує пакет у робочу область: ```text .openclaw/trajectory-exports/openclaw-trajectory--/ @@ -53,19 +51,17 @@ OpenClaw записує бандл у робочий простір: /export-trajectory bug-1234 ``` -Користувацький шлях визначається всередині `.openclaw/trajectory-exports/`. Абсолютні -шляхи й шляхи з `~` відхиляються. +Користувацький шлях буде визначено всередині `.openclaw/trajectory-exports/`. Абсолютні шляхи та шляхи з `~` відхиляються. ## Доступ -Експорт trajectory — це команда власника. Відправник має пройти звичайні перевірки -авторизації команд і перевірки власника для каналу. +Експорт траєкторії — це команда власника. Відправник має пройти звичайні перевірки авторизації команд і перевірки власника для каналу. ## Що записується -Запис trajectory типово увімкнений для запусків агента OpenClaw. +Захоплення траєкторій увімкнене за замовчуванням для запусків агентів OpenClaw. -Події runtime включають: +Події середовища виконання включають: - `session.started` - `trace.metadata` @@ -75,17 +71,17 @@ OpenClaw записує бандл у робочий простір: - `trace.artifacts` - `session.ended` -Події транскрипту також відновлюються з активної гілки сесії: +Події транскрипту також відтворюються з активної гілки сеансу: - повідомлення користувача - повідомлення помічника - виклики інструментів - результати інструментів -- Compaction +- compactions - зміни моделі -- мітки й користувацькі записи сесії +- мітки та користувацькі записи сеансу -Події записуються як JSON Lines з таким маркером schema: +Події записуються у форматі JSON Lines з таким маркером схеми: ```json { @@ -94,101 +90,96 @@ OpenClaw записує бандл у робочий простір: } ``` -## Файли бандла +## Файли пакета -Експортований бандл може містити: +Експортований пакет може містити: | Файл | Вміст | -| --------------------- | ----------------------------------------------------------------------------------------------- | -| `manifest.json` | Схема бандла, вихідні файли, кількість подій і список згенерованих файлів | -| `events.jsonl` | Упорядкована часова шкала runtime і транскрипту | -| `session-branch.json` | Скорочена активна гілка транскрипту і заголовок сесії | -| `metadata.json` | Версія OpenClaw, OS/runtime, модель, знімок config, Plugin-и, Skills і метадані prompt-ів | -| `artifacts.json` | Фінальний статус, помилки, usage, prompt cache, кількість Compaction, текст помічника і метадані інструментів | -| `prompts.json` | Надіслані prompt-и й вибрані подробиці побудови prompt-ів | -| `system-prompt.txt` | Останній скомпільований system prompt, якщо його було записано | -| `tools.json` | Визначення інструментів, надісланих моделі, якщо їх було записано | +| --------------------- | ------------------------------------------------------------------------------------------------ | +| `manifest.json` | Схема пакета, вихідні файли, кількість подій і список згенерованих файлів | +| `events.jsonl` | Упорядкована часова шкала середовища виконання і транскрипту | +| `session-branch.json` | Відредагована активна гілка транскрипту та заголовок сеансу | +| `metadata.json` | Версія OpenClaw, ОС/середовище виконання, модель, знімок конфігурації, plugins, Skills і метадані prompt | +| `artifacts.json` | Підсумковий статус, помилки, використання, кеш prompt, кількість Compaction, текст помічника та метадані інструментів | +| `prompts.json` | Надіслані prompts і вибрані деталі побудови prompt | +| `system-prompt.txt` | Останній скомпільований системний prompt, якщо його було захоплено | +| `tools.json` | Визначення інструментів, надіслані моделі, якщо їх було захоплено | -`manifest.json` перелічує файли, наявні в цьому бандлі. Деякі файли пропускаються, -якщо сесія не записала відповідні runtime-дані. +`manifest.json` перелічує файли, наявні в цьому пакеті. Деякі файли пропускаються, якщо сеанс не захопив відповідні дані середовища виконання. -## Місце запису +## Розташування захоплення -Типово runtime-події trajectory записуються поруч із файлом сесії: +За замовчуванням події траєкторії середовища виконання записуються поруч із файлом сеансу: ```text .trajectory.jsonl ``` -OpenClaw також записує файл-вказівник best-effort поруч із сесією: +OpenClaw також записує файл-вказівник за принципом best-effort поруч із сеансом: ```text .trajectory-path.json ``` -Задайте `OPENCLAW_TRAJECTORY_DIR`, щоб зберігати runtime-sidecar-и trajectory в -окремому каталозі: +Установіть `OPENCLAW_TRAJECTORY_DIR`, щоб зберігати побічні файли траєкторії середовища виконання в окремому каталозі: ```bash export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories ``` -Коли цю змінну задано, OpenClaw записує в цей каталог один JSONL-файл на id сесії. +Коли цю змінну встановлено, OpenClaw записує в цьому каталозі один JSONL-файл на кожен id сеансу. -## Вимкнення запису +Обслуговування сеансів видаляє побічні файли траєкторій, коли пов’язаний із ними запис сеансу обрізається, обмежується або витісняється через дисковий бюджет сеансів. Файли середовища виконання поза каталогом сеансів видаляються лише тоді, коли ціль вказівника все ще підтверджує, що належить цьому сеансу. -Задайте `OPENCLAW_TRAJECTORY=0` перед запуском OpenClaw: +## Вимкнення захоплення + +Установіть `OPENCLAW_TRAJECTORY=0` перед запуском OpenClaw: ```bash export OPENCLAW_TRAJECTORY=0 ``` -Це вимикає запис trajectory runtime. `/export-trajectory` все ще може експортувати -гілку транскрипту, але файли лише runtime, як-от скомпільований контекст, -артефакти провайдера й метадані prompt-ів, можуть бути відсутні. +Це вимикає захоплення траєкторій середовища виконання. `/export-trajectory` усе ще може експортувати гілку транскрипту, але файли лише середовища виконання, як-от скомпільований контекст, артефакти провайдера та метадані prompt, можуть бути відсутні. ## Конфіденційність і обмеження -Trajectory-бандли призначені для підтримки й налагодження, а не для публічного розміщення. -OpenClaw скорочує чутливі значення перед записом файлів експорту: +Пакети траєкторій призначені для підтримки та налагодження, а не для публічного розміщення. OpenClaw редагує чутливі значення перед записом файлів експорту: -- облікові дані та відомі поля payload, схожі на секрети +- облікові дані та відомі поля корисного навантаження, схожі на секрети - дані зображень -- шляхи локального стану -- шляхи робочого простору, замінені на `$WORKSPACE_DIR` -- шляхи домашнього каталогу, де їх виявлено +- шляхи до локального стану +- шляхи робочої області, замінені на `$WORKSPACE_DIR` +- шляхи до домашнього каталогу, де їх виявлено Експортер також обмежує розмір вхідних даних: -- runtime-sidecar файли: 50 MiB -- файли сесій: 50 MiB -- runtime-події: 200,000 +- побічні файли середовища виконання: 50 MiB +- файли сеансів: 50 MiB +- події середовища виконання: 200,000 - загальна кількість експортованих подій: 250,000 -- окремі рядки runtime-подій обрізаються при перевищенні 256 KiB +- окремі рядки подій середовища виконання обрізаються понад 256 KiB -Переглядайте бандли перед тим, як ділитися ними поза межами вашої команди. Скорочення виконується в режимі best-effort -і не може знати всі секрети, специфічні для вашого застосунку. +Перегляньте пакети перед тим, як ділитися ними за межами вашої команди. Редагування працює за принципом best-effort і не може знати всі специфічні для застосунку секрети. ## Усунення несправностей -Якщо в експорті немає runtime-подій: +Якщо в експорті немає подій середовища виконання: - переконайтеся, що OpenClaw було запущено без `OPENCLAW_TRAJECTORY=0` -- перевірте, чи вказує `OPENCLAW_TRAJECTORY_DIR` на каталог, доступний для запису -- надішліть ще одне повідомлення в сесії, а потім експортуйте ще раз -- перегляньте `manifest.json` на предмет `runtimeEventCount` +- перевірте, чи `OPENCLAW_TRAJECTORY_DIR` вказує на каталог, доступний для запису +- надішліть ще одне повідомлення в сеансі, а потім експортуйте знову +- перевірте `manifest.json` на наявність `runtimeEventCount` -Якщо команда відхиляє шлях виводу: +Якщо команда відхиляє вихідний шлях: -- використовуйте відносну назву, як-от `bug-1234` +- використовуйте відносну назву на кшталт `bug-1234` - не передавайте `/tmp/...` або `~/...` - зберігайте експорт усередині `.openclaw/trajectory-exports/` -Якщо експорт завершується помилкою через розмір, сесія або sidecar перевищили -безпечні межі експорту. Почніть нову сесію або експортуйте менше відтворення. +Якщо експорт завершується з помилкою розміру, сеанс або побічний файл перевищив безпечні обмеження експорту. Почніть новий сеанс або експортуйте менший сценарій відтворення. ## Пов’язане -- [Diff-и](/uk/tools/diffs) -- [Керування сесіями](/uk/concepts/session) +- [Diffs](/uk/tools/diffs) +- [Керування сеансами](/uk/concepts/session) - [Інструмент Exec](/uk/tools/exec)