From 1ef5eec8d07318013e34c223d2a7558036d26376 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 15:34:38 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/groups.md | 393 ++--- docs/uk/channels/matrix.md | 626 +++---- docs/uk/channels/whatsapp.md | 269 +-- docs/uk/concepts/model-providers.md | 547 +++--- docs/uk/concepts/oauth.md | 143 +- docs/uk/gateway/authentication.md | 129 +- docs/uk/gateway/cli-backends.md | 168 +- docs/uk/gateway/configuration-reference.md | 1003 ++++++----- docs/uk/gateway/doctor.md | 435 +++-- docs/uk/gateway/index.md | 219 +-- docs/uk/gateway/troubleshooting.md | 332 ++-- docs/uk/help/faq.md | 1500 +++++++++-------- docs/uk/help/testing.md | 630 +++---- ...refactor-real-plugin-sdk-workspace-plan.md | 578 +++++++ docs/uk/platforms/ios.md | 192 ++- docs/uk/plugins/sdk-migration.md | 414 +++-- docs/uk/plugins/sdk-overview.md | 632 +++---- docs/uk/plugins/sdk-provider-plugins.md | 323 ++-- docs/uk/plugins/webhooks.md | 201 +++ docs/uk/providers/anthropic.md | 196 +-- docs/uk/providers/openai.md | 289 ++-- docs/uk/reference/api-usage-costs.md | 187 +- docs/uk/reference/test.md | 68 +- docs/uk/reference/token-use.md | 168 +- docs/uk/reference/wizard.md | 189 ++- docs/uk/start/wizard-cli-automation.md | 40 +- docs/uk/start/wizard.md | 116 +- docs/uk/tools/media-overview.md | 67 + docs/uk/tools/music-generation.md | 224 ++- docs/uk/tools/video-generation.md | 239 ++- docs/uk/tts.md | 456 +---- 31 files changed, 5690 insertions(+), 5283 deletions(-) create mode 100644 docs/uk/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md create mode 100644 docs/uk/plugins/webhooks.md create mode 100644 docs/uk/tools/media-overview.md diff --git a/docs/uk/channels/groups.md b/docs/uk/channels/groups.md index f4f0b78d3..d7b8f3792 100644 --- a/docs/uk/channels/groups.md +++ b/docs/uk/channels/groups.md @@ -1,40 +1,40 @@ --- read_when: - - Зміна поведінки групового чату або керування згадуваннями -summary: Поведінка групових чатів на різних поверхнях (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) + - Зміна поведінки групових чатів або керування згадками +summary: Поведінка групових чатів на різних платформах (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: Групи x-i18n: - generated_at: "2026-04-05T17:58:18Z" + generated_at: "2026-04-06T15:28:10Z" model: gpt-5.4 provider: openai - source_hash: 8620de6f7f0b866bf43a307fdbec3399790f09f22a87703704b0522caba80b18 + source_hash: 83d20f2958ed6ad3354f0078553b3c6a38643ea8ef38573c40e89ebef2fa8421 source_path: channels/groups.md workflow: 15 --- # Групи -OpenClaw однаково обробляє групові чати на різних поверхнях: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo. +OpenClaw однаково обробляє групові чати на різних платформах: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo. ## Вступ для початківців (2 хвилини) -OpenClaw «живе» у ваших власних облікових записах месенджерів. Окремого користувача-бота WhatsApp немає. +OpenClaw «живе» у ваших власних облікових записах месенджерів. Окремого користувача-бота WhatsApp не існує. Якщо **ви** перебуваєте в групі, OpenClaw може бачити цю групу й відповідати там. -Типова поведінка: +Поведінка за замовчуванням: - Групи обмежені (`groupPolicy: "allowlist"`). -- Для відповідей потрібне згадування, якщо ви явно не вимкнете керування згадуваннями. +- Для відповідей потрібна згадка, якщо ви явно не вимкнули керування згадками. -Простими словами: відправники зі списку дозволу можуть запускати OpenClaw, згадуючи його. +Інакше кажучи: відправники з allowlist можуть активувати OpenClaw, згадавши його. > Коротко > -> - **Доступ до DM** контролюється через `*.allowFrom`. -> - **Доступ до груп** контролюється через `*.groupPolicy` + списки дозволу (`*.groups`, `*.groupAllowFrom`). -> - **Запуск відповіді** контролюється через керування згадуваннями (`requireMention`, `/activation`). +> - **Доступ до DM** керується через `*.allowFrom`. +> - **Доступ до груп** керується через `*.groupPolicy` + allowlist-и (`*.groups`, `*.groupAllowFrom`). +> - **Запуск відповіді** керується керуванням згадками (`requireMention`, `/activation`). -Коротка схема (що відбувається з повідомленням у групі): +Швидка схема (що відбувається з повідомленням у групі): ``` groupPolicy? disabled -> drop @@ -43,375 +43,192 @@ requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` -## Видимість контексту і списки дозволу +## Видимість контексту та allowlist-и -У безпеці груп задіяно два різні механізми керування: +У безпеці груп беруть участь два різні механізми: -- **Авторизація запуску**: хто може запускати агента (`groupPolicy`, `groups`, `groupAllowFrom`, списки дозволу для конкретного каналу). -- **Видимість контексту**: який додатковий контекст передається в модель (текст відповіді, цитати, історія треду, метадані пересланого повідомлення). +- **Авторизація запуску**: хто може активувати агента (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist-и, специфічні для каналу). +- **Видимість контексту**: який додатковий контекст передається в модель (текст відповіді, цитати, історія треду, метадані пересилання). -Типово OpenClaw надає пріоритет звичайній поведінці чату й зберігає контекст здебільшого в тому вигляді, у якому його отримано. Це означає, що списки дозволу переважно визначають, хто може запускати дії, а не є універсальною межею редагування для кожного процитованого або історичного фрагмента. +За замовчуванням OpenClaw надає пріоритет звичайній поведінці чату та здебільшого зберігає контекст у тому вигляді, у якому його отримано. Це означає, що allowlist-и переважно визначають, хто може ініціювати дії, а не є універсальною межею редагування для кожного процитованого або історичного фрагмента. Поточна поведінка залежить від каналу: -- Деякі канали вже застосовують фільтрацію за відправником для додаткового контексту в окремих шляхах (наприклад, ініціалізація тредів у Slack, пошук відповіді/треду в Matrix). -- Інші канали досі передають контекст цитати/відповіді/пересилання в отриманому вигляді. +- Деякі канали вже застосовують фільтрацію за відправником для додаткового контексту в окремих шляхах (наприклад, початкове заповнення тредів у Slack, пошук відповіді/треду в Matrix). +- Інші канали все ще передають контекст цитати/відповіді/пересилання в отриманому вигляді. Напрям посилення безпеки (заплановано): -- `contextVisibility: "all"` (типово) зберігає поточну поведінку з передаванням контексту в отриманому вигляді. -- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників зі списку дозволу. +- `contextVisibility: "all"` (типово) зберігає поточну поведінку «як отримано». +- `contextVisibility: "allowlist"`` фільтрує додатковий контекст до відправників із allowlist. - `contextVisibility: "allowlist_quote"` — це `allowlist` плюс один явний виняток для цитати/відповіді. -Поки цю модель посилення безпеки не буде узгоджено реалізовано в усіх каналах, очікуйте відмінностей залежно від поверхні. +Поки цю модель посилення безпеки не реалізовано узгоджено в усіх каналах, очікуйте відмінностей між платформами. -![Потік повідомлень у групі](/images/groups-flow.svg) +![Потік групового повідомлення](/images/groups-flow.svg) -Якщо вам потрібно... +Якщо ви хочете... -| Мета | Що налаштувати | -| -------------------------------------------- | -------------------------------------------------------- | -| Дозволити всі групи, але відповідати лише на @згадування | `groups: { "*": { requireMention: true } }` | -| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` | -| Лише певні групи | `groups: { "": { ... } }` (без ключа `"*"`) | -| Лише ви можете запускати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| Мета | Що налаштувати | +| -------------------------------------------- | ---------------------------------------------------------- | +| Дозволити всі групи, але відповідати лише на @згадки | `groups: { "*": { requireMention: true } }` | +| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` | +| Лише певні групи | `groups: { "": { ... } }` (без ключа `"*"`) | +| Лише ви можете активувати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## Ключі сесій -- Для групових сесій використовуються ключі сесій `agent:::group:` (для кімнат/каналів — `agent:::channel:`). -- Для тем форумів Telegram до ідентифікатора групи додається `:topic:`, щоб кожна тема мала власну сесію. +- Групові сесії використовують ключі сесій `agent:::group:` (кімнати/канали використовують `agent:::channel:`). +- Теми форуму Telegram додають `:topic:` до ідентифікатора групи, тому кожна тема має власну сесію. - Прямі чати використовують основну сесію (або окрему для кожного відправника, якщо це налаштовано). -- Heartbeat для групових сесій пропускаються. +- Heartbeat-и для групових сесій пропускаються. ## Шаблон: особисті DM + публічні групи (один агент) -Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а «публічний» трафік — це **групи**. +Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а ваш «публічний» трафік — це **групи**. -Чому: у режимі одного агента DM зазвичай потрапляють в **основний** ключ сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main::group:`). Якщо ви ввімкнете ізоляцію з `mode: "non-main"`, ці групові сесії виконуватимуться в Docker, а ваша основна DM-сесія залишиться на хості. +Чому: у режимі одного агента DM зазвичай потрапляють до ключа **основної** сесії (`agent:main:main`), тоді як групи завжди використовують ключі **неосновних** сесій (`agent:main::group:`). Якщо ви ввімкнете sandboxing з `mode: "non-main"`, ці групові сесії працюватимуть у Docker, а ваша основна DM-сесія залишиться на хості. -Це дає вам один «мозок» агента (спільний workspace + пам’ять), але дві моделі виконання: +Це дає вам один «мозок» агента (спільний workspace + пам’ять), але два режими виконання: - **DM**: повні інструменти (хост) -- **Групи**: sandbox + інструменти лише для обміну повідомленнями (Docker) +- **Групи**: sandbox + обмежені інструменти (Docker) -> Якщо вам потрібні справді окремі робочі простори/персони («особисте» і «публічне» ніколи не повинні змішуватися), використовуйте другого агента + bindings. Див. [Маршрутизація кількох агентів](/concepts/multi-agent). +> Якщо вам потрібні справді окремі workspace/персони («особисте» і «публічне» ніколи не мають змішуватися), використовуйте другого агента + прив’язки. Див. [Багатоагентна маршрутизація](/concepts/multi-agent). Приклад (DM на хості, групи в sandbox + лише інструменти для обміну повідомленнями): - -```json5 -{ - agents: { - defaults: { - sandbox: { - mode: "non-main", // groups/channels are non-main -> sandboxed - scope: "session", // strongest isolation (one container per group/channel) - workspaceAccess: "none", - }, - }, - }, - tools: { - sandbox: { - tools: { - // If allow is non-empty, everything else is blocked (deny still wins). - allow: ["group:messaging", "group:sessions"], - deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"], - }, - }, - }, -} -``` - -Потрібно, щоб «групи могли бачити лише папку X» замість «без доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в sandbox лише шляхи зі списку дозволу: - -```json5 -{ - agents: { - defaults: { - sandbox: { - mode: "non-main", - scope: "session", - workspaceAccess: "none", - docker: { - binds: [ - // hostPath:containerPath:mode - "/home/user/FriendsShared:/data:ro", - ], - }, - }, - }, - }, -} -``` - +__OC_I18N_900001__ +Хочете, щоб «групи могли бачити лише папку X» замість «без доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в sandbox лише шляхи з allowlist: +__OC_I18N_900002__ Пов’язане: -- Ключі конфігурації та типові значення: [Конфігурація шлюзу](/gateway/configuration-reference#agentsdefaultssandbox) -- Налагодження причин блокування інструмента: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- Докладно про bind mount: [Ізоляція](/gateway/sandboxing#custom-bind-mounts) +- Ключі конфігурації та значення за замовчуванням: [Конфігурація шлюзу](/gateway/configuration-reference#agentsdefaultssandbox) +- Налагодження, чому інструмент заблоковано: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) +- Докладніше про bind mounts: [Sandboxing](/gateway/sandboxing#custom-bind-mounts) ## Мітки відображення -- Мітки інтерфейсу використовують `displayName`, коли він доступний, у форматі `:`. -- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-` (нижній регістр, пробіли -> `-`, зберігаються `#@+._-`). +- Мітки в UI використовують `displayName`, якщо він доступний, у форматі `:`. +- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-` (нижній регістр, пробіли -> `-`, зберігати `#@+._-`). ## Політика груп -Керуйте тим, як обробляються повідомлення з груп/кімнат для кожного каналу: - -```json5 -{ - channels: { - whatsapp: { - groupPolicy: "disabled", // "open" | "disabled" | "allowlist" - groupAllowFrom: ["+15551234567"], - }, - telegram: { - groupPolicy: "disabled", - groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username) - }, - signal: { - groupPolicy: "disabled", - groupAllowFrom: ["+15551234567"], - }, - imessage: { - groupPolicy: "disabled", - groupAllowFrom: ["chat_id:123"], - }, - msteams: { - groupPolicy: "disabled", - groupAllowFrom: ["user@org.com"], - }, - discord: { - groupPolicy: "allowlist", - guilds: { - GUILD_ID: { channels: { help: { allow: true } } }, - }, - }, - slack: { - groupPolicy: "allowlist", - channels: { "#general": { allow: true } }, - }, - matrix: { - groupPolicy: "allowlist", - groupAllowFrom: ["@owner:example.org"], - groups: { - "!roomId:example.org": { allow: true }, - "#alias:example.org": { allow: true }, - }, - }, - }, -} -``` - +Керуйте тим, як обробляються повідомлення груп/кімнат для кожного каналу: +__OC_I18N_900003__ | Політика | Поведінка | | ------------- | ------------------------------------------------------------ | -| `"open"` | Групи обходять списки дозволу; керування згадуваннями все ще застосовується. | -| `"disabled"` | Повністю блокує всі повідомлення з груп. | -| `"allowlist"` | Дозволяє лише групи/кімнати, що відповідають налаштованому списку дозволу. | +| `"open"` | Групи обходять allowlist-и; керування згадками все одно застосовується. | +| `"disabled"` | Повністю блокувати всі групові повідомлення. | +| `"allowlist"` | Дозволяти лише групи/кімнати, що відповідають налаштованому allowlist. | Примітки: -- `groupPolicy` відокремлена від керування згадуваннями (яке вимагає @згадувань). -- Для WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo використовуйте `groupAllowFrom` (резервний варіант: явний `allowFrom`). -- Схвалення сполучення DM (записи в сховищі `*-allowFrom`) застосовуються лише до доступу через DM; авторизація відправників у групах залишається явною й керується списками дозволу груп. -- Для Discord список дозволу використовує `channels.discord.guilds..channels`. -- Для Slack список дозволу використовує `channels.slack.channels`. -- Для Matrix список дозволу використовує `channels.matrix.groups`. Віддавайте перевагу ідентифікаторам або псевдонімам кімнат; пошук імен приєднаних кімнат виконується за принципом best-effort, а нерозпізнані імена ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom`, щоб обмежувати відправників; також підтримуються списки дозволу `users` для окремих кімнат. -- Групові DM керуються окремо (`channels.discord.dm.*`, `channels.slack.dm.*`). -- Список дозволу Telegram може відповідати ID користувачів (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменам користувачів (`"@alice"` або `"alice"`); префікси не залежать від регістру. -- Типове значення — `groupPolicy: "allowlist"`; якщо ваш список дозволу груп порожній, повідомлення з груп блокуються. +- `groupPolicy` відокремлено від керування згадками (яке вимагає @згадок). +- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: використовуйте `groupAllowFrom` (запасний варіант: явний `allowFrom`). +- Підтвердження DM pairing (записи в сховищі `*-allowFrom`) застосовуються лише до доступу в DM; авторизація відправника в групі залишається явною через allowlist-и груп. +- Discord: allowlist використовує `channels.discord.guilds..channels`. +- Slack: allowlist використовує `channels.slack.channels`. +- Matrix: allowlist використовує `channels.matrix.groups`. Віддавайте перевагу ID кімнат або псевдонімам; пошук назв приєднаних кімнат виконується за принципом best-effort, а нерозпізнані назви ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom`, щоб обмежити відправників; також підтримуються allowlist-и `users` для окремих кімнат. +- Group DM керуються окремо (`channels.discord.dm.*`, `channels.slack.dm.*`). +- Allowlist Telegram може відповідати ID користувачів (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменам користувачів (`"@alice"` або `"alice"`); префікси нечутливі до регістру. +- За замовчуванням використовується `groupPolicy: "allowlist"`; якщо ваш allowlist груп порожній, групові повідомлення блокуються. - Безпека під час виконання: коли блок провайдера повністю відсутній (`channels.` відсутній), політика груп переходить у fail-closed режим (зазвичай `allowlist`) замість успадкування `channels.defaults.groupPolicy`. -Коротка ментальна модель (порядок обробки для повідомлень у групі): +Швидка ментальна модель (порядок перевірки для групових повідомлень): 1. `groupPolicy` (open/disabled/allowlist) -2. списки дозволу груп (`*.groups`, `*.groupAllowFrom`, список дозволу конкретного каналу) -3. керування згадуваннями (`requireMention`, `/activation`) +2. group allowlist-и (`*.groups`, `*.groupAllowFrom`, allowlist, специфічний для каналу) +3. керування згадками (`requireMention`, `/activation`) -## Керування згадуваннями (типово) +## Керування згадками (типово) -Для повідомлень у групі потрібне згадування, якщо це не перевизначено для конкретної групи. Типові значення для кожної підсистеми задаються через `*.groups."*"`. - -Відповідь на повідомлення бота зараховується як неявне згадування (коли канал підтримує метадані відповіді). Це стосується Telegram, WhatsApp, Slack, Discord і Microsoft Teams. - -```json5 -{ - channels: { - whatsapp: { - groups: { - "*": { requireMention: true }, - "123@g.us": { requireMention: false }, - }, - }, - telegram: { - groups: { - "*": { requireMention: true }, - "123456789": { requireMention: false }, - }, - }, - imessage: { - groups: { - "*": { requireMention: true }, - "123": { requireMention: false }, - }, - }, - }, - agents: { - list: [ - { - id: "main", - groupChat: { - mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"], - historyLimit: 50, - }, - }, - ], - }, -} -``` +Групові повідомлення вимагають згадки, якщо це не перевизначено для конкретної групи. Значення за замовчуванням зберігаються для кожної підсистеми в `*.groups."*"`. +Відповідь на повідомлення бота вважається неявною згадкою (коли канал підтримує метадані відповіді). Це застосовується до Telegram, WhatsApp, Slack, Discord і Microsoft Teams. +__OC_I18N_900004__ Примітки: -- `mentionPatterns` — це безпечні regex-шаблони без урахування регістру; недійсні шаблони та небезпечні форми з вкладеним повторенням ігноруються. -- Поверхні, які надають явні згадування, усе одно їх передають; шаблони є резервним варіантом. -- Перевизначення для окремого агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів спільно використовують одну групу). -- Керування згадуваннями застосовується лише тоді, коли можливе виявлення згадування (наявні нативні згадування або налаштовано `mentionPatterns`). -- Для Discord типові значення зберігаються в `channels.discord.guilds."*"` (можна перевизначити для окремої гільдії/каналу). -- Контекст історії групи однаково обгортається в усіх каналах і є **лише для pending** (повідомлення, пропущені через керування згадуваннями); використовуйте `messages.groupChat.historyLimit` для глобального типового значення та `channels..historyLimit` (або `channels..accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути. +- `mentionPatterns` — це безпечні regex-шаблони, нечутливі до регістру; недійсні шаблони та небезпечні форми вкладеного повторення ігноруються. +- Платформи, які надають явні згадки, усе одно проходять перевірку; шаблони є запасним варіантом. +- Перевизначення для агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів спільно використовують одну групу). +- Керування згадками застосовується лише тоді, коли виявлення згадки можливе (налаштовані нативні згадки або `mentionPatterns`). +- Значення за замовчуванням для Discord зберігаються в `channels.discord.guilds."*"` (можна перевизначати для окремої гільдії/каналу). +- Контекст історії групи однаково обгортається в усіх каналах і є **лише pending** (повідомлення, пропущені через керування згадками); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels..historyLimit` (або `channels..accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути. ## Обмеження інструментів для груп/каналів (необов’язково) -Деякі конфігурації каналів дають змогу обмежувати, які інструменти доступні **всередині конкретної групи/кімнати/каналу**. +Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині конкретної групи/кімнати/каналу**. - `tools`: дозволити/заборонити інструменти для всієї групи. -- `toolsBySender`: перевизначення для окремих відправників усередині групи. +- `toolsBySender`: перевизначення для окремих відправників у межах групи. Використовуйте явні префікси ключів: `id:`, `e164:`, `username:`, `name:` і wildcard `"*"`. - Старі ключі без префікса все ще приймаються й зіставляються лише як `id:`. + Застарілі ключі без префікса все ще приймаються та зіставляються лише як `id:`. -Порядок визначення (найконкретніше має пріоритет): +Порядок визначення (найбільш специфічне має пріоритет): 1. збіг `toolsBySender` для групи/каналу 2. `tools` для групи/каналу -3. типовий збіг `toolsBySender` для `"*"` -4. типове `tools` для `"*"` +3. збіг `toolsBySender` за замовчуванням (`"*"` ) +4. `tools` за замовчуванням (`"*"`) Приклад (Telegram): - -```json5 -{ - channels: { - telegram: { - groups: { - "*": { tools: { deny: ["exec"] } }, - "-1001234567890": { - tools: { deny: ["exec", "read", "write"] }, - toolsBySender: { - "id:123456789": { alsoAllow: ["exec"] }, - }, - }, - }, - }, - }, -} -``` - +__OC_I18N_900005__ Примітки: -- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної/агентської політики інструментів (deny все одно має пріоритет). +- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної/агентської політики інструментів (заборона все одно має пріоритет). - Деякі канали використовують іншу вкладеність для кімнат/каналів (наприклад, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). -## Списки дозволу груп +## Group allowlists -Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як список дозволу груп. Використовуйте `"*"`, щоб дозволити всі групи й водночас задати типову поведінку для згадувань. +Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як allowlist груп. Використовуйте `"*"`, щоб дозволити всі групи й водночас задати типову поведінку згадок. -Поширена плутанина: схвалення сполучення DM — це не те саме, що авторизація груп. -Для каналів, які підтримують сполучення DM, сховище pairing розблоковує лише DM. Команди в групах усе одно вимагають явної авторизації відправника групи з конфігураційних списків дозволу, таких як `groupAllowFrom`, або задокументованого резервного механізму конфігурації для цього каналу. +Поширена плутанина: підтвердження DM pairing — це не те саме, що авторизація групи. +Для каналів, які підтримують DM pairing, сховище pairing відкриває лише DM. Команди в групах усе одно вимагають явної авторизації відправника групи через allowlist-и конфігурації, такі як `groupAllowFrom`, або задокументований запасний варіант конфігурації для цього каналу. -Типові наміри (копіюйте/вставляйте): +Поширені сценарії (скопіювати/вставити): 1. Вимкнути всі відповіді в групах - -```json5 -{ - channels: { whatsapp: { groupPolicy: "disabled" } }, -} -``` - +__OC_I18N_900006__ 2. Дозволити лише певні групи (WhatsApp) +__OC_I18N_900007__ +3. Дозволити всі групи, але вимагати згадку (явно) +__OC_I18N_900008__ +4. Лише власник може активувати в групах (WhatsApp) +__OC_I18N_900009__ +## Activation (лише для власника) -```json5 -{ - channels: { - whatsapp: { - groups: { - "123@g.us": { requireMention: true }, - "456@g.us": { requireMention: false }, - }, - }, - }, -} -``` - -3. Дозволити всі групи, але вимагати згадування (явно) - -```json5 -{ - channels: { - whatsapp: { - groups: { "*": { requireMention: true } }, - }, - }, -} -``` - -4. Лише власник може запускати в групах (WhatsApp) - -```json5 -{ - channels: { - whatsapp: { - groupPolicy: "allowlist", - groupAllowFrom: ["+15551234567"], - groups: { "*": { requireMention: true } }, - }, - }, -} -``` - -## Активація (лише для власника) - -Власники груп можуть перемикати активацію для окремої групи: +Власники груп можуть перемикати активацію для кожної групи: - `/activation mention` - `/activation always` -Власник визначається через `channels.whatsapp.allowFrom` (або через власний E.164 бота, якщо значення не задано). Надішліть команду як окреме повідомлення. Інші поверхні наразі ігнорують `/activation`. +Власник визначається через `channels.whatsapp.allowFrom` (або через власний E.164 бота, якщо значення не задано). Надсилайте команду як окреме повідомлення. Інші платформи наразі ігнорують `/activation`. ## Поля контексту -Для вхідних даних груп задаються: +Вхідні payload-и груп встановлюють: - `ChatType=group` - `GroupSubject` (якщо відомо) - `GroupMembers` (якщо відомо) -- `WasMentioned` (результат керування згадуваннями) -- Теми форумів Telegram також містять `MessageThreadId` і `IsForum`. +- `WasMentioned` (результат керування згадками) +- Теми форуму Telegram також містять `MessageThreadId` і `IsForum`. -Примітки для конкретних каналів: +Примітки для окремих каналів: -- BlueBubbles може за бажанням збагачувати неіменованих учасників груп macOS з локальної бази контактів перед заповненням `GroupMembers`. Це вимкнено типово й виконується лише після проходження звичайної перевірки груп. +- BlueBubbles може за бажанням доповнювати учасників без імен у групах macOS з локальної бази Contacts перед заповненням `GroupMembers`. Це вимкнено за замовчуванням і виконується лише після успішного проходження звичайної перевірки групи. -Системний prompt агента містить вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати таблиць Markdown, мінімізувати порожні рядки, дотримуватися звичайних інтервалів у чаті та уникати буквального введення послідовностей `\n`. +Системний prompt агента містить вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати Markdown-таблиць, мінімізувати порожні рядки й дотримуватися звичайних інтервалів чату, а також не вводити буквально послідовності `\n`. ## Особливості iMessage -- Для маршрутизації або списків дозволу надавайте перевагу `chat_id:`. -- Перегляд чатів: `imsg chats --limit 20`. +- Для маршрутизації або allowlist-ів віддавайте перевагу `chat_id:`. +- Список чатів: `imsg chats --limit 20`. - Відповіді в групі завжди повертаються до того самого `chat_id`. ## Особливості WhatsApp -Див. [Повідомлення в групах](/channels/group-messages) для поведінки, специфічної для WhatsApp (впровадження історії, деталі обробки згадувань). +Див. [Групові повідомлення](/uk/channels/group-messages) для поведінки, специфічної лише для WhatsApp (впровадження історії, подробиці обробки згадок). diff --git a/docs/uk/channels/matrix.md b/docs/uk/channels/matrix.md index 6df38a5d7..9d240eb54 100644 --- a/docs/uk/channels/matrix.md +++ b/docs/uk/channels/matrix.md @@ -5,25 +5,25 @@ read_when: summary: Статус підтримки Matrix, налаштування та приклади конфігурації title: Matrix x-i18n: - generated_at: "2026-04-06T03:59:09Z" + generated_at: "2026-04-06T15:30:18Z" model: gpt-5.4 provider: openai - source_hash: 06f833bf0ede81bad69f140994c32e8cc5d1635764f95fc5db4fc5dc25f2b85e + source_hash: 22d10be40bb7c2cc197f5ab4ba7c8067b67867bff477efb374b930dd79aefe8a source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix — це вбудований канальний plugin Matrix для OpenClaw. -Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, геолокацію та E2EE. +Matrix — це вбудований плагін каналу Matrix для OpenClaw. +Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, локацію та E2EE. -## Вбудований plugin +## Вбудований плагін -Matrix постачається як вбудований plugin у поточних релізах OpenClaw, тому звичайним -пакетованим збіркам не потрібне окреме встановлення. +Matrix постачається як вбудований плагін у поточних випусках OpenClaw, тому звичайні +пакетні збірки не потребують окремого встановлення. -Якщо ви використовуєте старішу збірку або нестандартне встановлення без Matrix, установіть +Якщо ви використовуєте старішу збірку або кастомне встановлення без Matrix, установіть його вручну: Установлення з npm: @@ -38,21 +38,22 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -Див. [Plugins](/uk/tools/plugin), щоб дізнатися про поведінку plugin і правила встановлення. +Див. [Plugins](/uk/tools/plugin) щодо поведінки плагінів і правил встановлення. ## Налаштування -1. Переконайтеся, що plugin Matrix доступний. - - У поточних пакетованих релізах OpenClaw він уже вбудований. - - У старіших/нестандартних установленнях його можна додати вручну командами вище. +1. Переконайтеся, що плагін Matrix доступний. + - У поточних пакетних випусках OpenClaw він уже вбудований. + - У старіших/кастомних установленнях його можна додати вручну командами вище. 2. Створіть обліковий запис Matrix на вашому homeserver. 3. Налаштуйте `channels.matrix` одним із варіантів: - `homeserver` + `accessToken`, або - `homeserver` + `userId` + `password`. 4. Перезапустіть gateway. 5. Почніть DM із ботом або запросіть його до кімнати. + - Нові запрошення Matrix працюють лише тоді, коли `channels.matrix.autoJoin` дозволяє їх. -Інтерактивні шляхи налаштування: +Шляхи інтерактивного налаштування: ```bash openclaw channels add @@ -62,20 +63,58 @@ openclaw configure --section channels Що саме запитує майстер Matrix: - URL homeserver -- спосіб автентифікації: токен доступу або пароль -- ID користувача лише якщо ви обираєте автентифікацію паролем +- метод автентифікації: access token або пароль +- ID користувача, лише якщо ви обираєте автентифікацію паролем - необов’язкова назва пристрою - чи вмикати E2EE -- чи налаштовувати доступ до кімнат Matrix зараз +- чи налаштувати доступ до кімнат Matrix зараз Важлива поведінка майстра: -- Якщо змінні середовища автентифікації Matrix уже існують для вибраного облікового запису, і цей обліковий запис ще не має збереженої автентифікації в конфігурації, майстер запропонує скористатися env-ярликом і запише для цього облікового запису лише `enabled: true`. -- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введена назва облікового запису нормалізується до ID облікового запису, який використовується в конфігурації та env vars. Наприклад, `Ops Bot` стає `ops-bot`. -- Підказки для allowlist DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли живий пошук у каталозі знаходить одну точну відповідність; інакше майстер попросить повторити спробу з повним Matrix ID. -- Підказки для allowlist кімнат одразу приймають ID кімнат і аліаси. Вони також можуть виконувати живе розпізнавання назв приєднаних кімнат, але нерозпізнані назви під час налаштування зберігаються лише як введені й пізніше ігноруються під час виконання розв’язання allowlist. Надавайте перевагу `!room:server` або `#alias:server`. -- Ідентичність кімнати/сесії під час виконання використовує стабільний Matrix room ID. Аліаси, оголошені в кімнаті, використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи. -- Щоб розв’язати назви кімнат перед їх збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. +- Якщо для вибраного облікового запису вже існують змінні середовища автентифікації Matrix, і для цього облікового запису ще не збережено автентифікацію в config, майстер пропонує скористатися env і записує лише `enabled: true` для цього облікового запису. +- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введене ім’я облікового запису нормалізується в ID облікового запису, який використовується в config і env vars. Наприклад, `Ops Bot` перетворюється на `ops-bot`. +- Підказки allowlist для DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли живий пошук у каталозі знаходить один точний збіг; інакше майстер попросить повторити спробу з повним Matrix ID. +- Підказки allowlist для кімнат напряму приймають ID кімнат і псевдоніми. Вони також можуть у реальному часі визначати назви приєднаних кімнат, але нерозпізнані назви під час налаштування лише зберігаються як введені й пізніше ігноруються під час runtime-розв’язання allowlist. Віддавайте перевагу `!room:server` або `#alias:server`. +- Ідентичність кімнати/сесії під час runtime використовує стабільний ID кімнати Matrix. Псевдоніми, оголошені в кімнаті, використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи. +- Щоб визначити назви кімнат перед їх збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. + + +`channels.matrix.autoJoin` за замовчуванням має значення `off`. + +Якщо залишити його невстановленим, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тому він не з’являтиметься в нових групах або запрошених DM, якщо ви спершу не приєднаєтеся вручну. + +Установіть `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення він приймає, або встановіть `autoJoin: "always"`, якщо хочете, щоб він приєднувався до кожного запрошення. + + +Приклад allowlist: + +```json5 +{ + channels: { + matrix: { + autoJoin: "allowlist", + autoJoinAllowlist: ["!ops:example.org", "#support:example.org"], + groups: { + "!ops:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +Приєднуватися до кожного запрошення: + +```json5 +{ + channels: { + matrix: { + autoJoin: "always", + }, + }, +} +``` Мінімальне налаштування на основі токена: @@ -92,7 +131,7 @@ openclaw configure --section channels } ``` -Налаштування на основі пароля (після входу токен кешується): +Налаштування на основі пароля (токен кешується після входу): ```json5 { @@ -109,10 +148,10 @@ openclaw configure --section channels ``` Matrix зберігає кешовані облікові дані в `~/.openclaw/credentials/matrix/`. -Обліковий запис за замовчуванням використовує `credentials.json`; іменовані облікові записи використовують `credentials-.json`. -Коли там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення статусу каналу, навіть якщо поточна автентифікація не задана безпосередньо в конфігурації. +Обліковий запис за замовчуванням використовує `credentials.json`; іменовані облікові записи — `credentials-.json`. +Коли там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення статусу каналу, навіть якщо поточну автентифікацію не встановлено безпосередньо в config. -Еквіваленти змінних середовища (використовуються, коли ключ конфігурації не заданий): +Еквіваленти змінних середовища (використовуються, коли ключ config не встановлено): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -121,7 +160,7 @@ Matrix зберігає кешовані облікові дані в `~/.opencl - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Для неосновних облікових записів використовуйте env vars у межах облікового запису: +Для облікових записів не за замовчуванням використовуйте env vars з областю дії облікового запису: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -140,14 +179,14 @@ Matrix зберігає кешовані облікові дані в `~/.opencl - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix екранує розділові символи в ID облікових записів, щоб уникнути колізій у env vars з областю дії. -Наприклад, `-` стає `_X2D_`, тому `ops-prod` відображається в `MATRIX_OPS_X2D_PROD_*`. +Matrix екранує розділові знаки в ID облікових записів, щоб уникнути колізій env vars з областю дії. +Наприклад, `-` стає `_X2D_`, тому `ops-prod` перетворюється на `MATRIX_OPS_X2D_PROD_*`. -Інтерактивний майстер пропонує ярлик через env vars лише тоді, коли ці env vars автентифікації вже присутні, а вибраний обліковий запис ще не має збереженої автентифікації Matrix у конфігурації. +Інтерактивний майстер пропонує скористатися env vars лише тоді, коли ці env vars автентифікації вже присутні і для вибраного облікового запису ще не збережено автентифікацію Matrix у config. ## Приклад конфігурації -Ось практична базова конфігурація з pairing DM, allowlist кімнат і ввімкненим E2EE: +Це практична базова конфігурація з pairing для DM, allowlist кімнат і увімкненим E2EE: ```json5 { @@ -183,18 +222,19 @@ Matrix екранує розділові символи в ID облікових ``` `autoJoin` застосовується до запрошень Matrix загалом, а не лише до запрошень у кімнати/групи. -Це включає нові запрошення у стилі DM. На момент запрошення OpenClaw не може надійно визначити, чи -запрошену кімнату буде врешті оброблено як DM або як групу, тому всі запрошення спочатку проходять -через однакове рішення `autoJoin`. `dm.policy` усе ще застосовується після того, як бот приєднається і кімнату буде -класифіковано як DM, тому `autoJoin` керує поведінкою приєднання, а `dm.policy` — поведінкою відповіді/доступу. +Це включає нові запрошення у стилі DM. Під час запрошення OpenClaw не може надійно визначити, чи +запрошена кімната зрештою вважатиметься DM чи групою, тому всі запрошення спочатку проходять через однакове +рішення `autoJoin`. `dm.policy` усе одно застосовується після того, як бот приєднається і кімнату буде +класифіковано як DM, тож `autoJoin` керує поведінкою приєднання, а `dm.policy` — поведінкою +відповідей/доступу. ## Попередній перегляд потокових відповідей -Потокова передача відповідей у Matrix є опцією, яку потрібно ввімкнути. +Потокове передавання відповідей у Matrix є opt-in. -Установіть `channels.matrix.streaming` у значення `"partial"`, якщо хочете, щоб OpenClaw надсилав один живий попередній -перегляд відповіді, редагував цей попередній перегляд на місці, поки модель генерує текст, а потім завершував його, коли -відповідь буде готова: +Установіть `channels.matrix.streaming` у значення `"partial"`, якщо хочете, щоб OpenClaw надсилав одну живу +відповідь попереднього перегляду, редагував цей попередній перегляд на місці, поки модель генерує текст, а +потім завершував його, коли відповідь буде готова: ```json5 { @@ -207,35 +247,35 @@ Matrix екранує розділові символи в ID облікових ``` - `streaming: "off"` — значення за замовчуванням. OpenClaw чекає на фінальну відповідь і надсилає її один раз. -- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді помічника за допомогою звичайних текстових повідомлень Matrix. Це зберігає застарілу поведінку Matrix із попереднім переглядом перед фінальною відповіддю, тож стандартні клієнти можуть надсилати сповіщення за першим текстом потокового попереднього перегляду, а не за завершеним блоком. -- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку відповіді помічника. Використовуйте це лише тоді, коли ви також налаштували push rules отримувача для завершених редагувань попереднього перегляду. -- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Якщо потоковий попередній перегляд увімкнено, Matrix зберігає живий чернетковий варіант для поточного блоку та залишає завершені блоки як окремі повідомлення. -- Коли попередній перегляд увімкнено, а `blockStreaming` вимкнено, Matrix редагує живу чернетку на місці й завершує ту саму подію, коли блок або хід завершено. -- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потоковий попередній перегляд і повертається до звичайної фінальної доставки. +- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку асистента, використовуючи звичайні текстові повідомлення Matrix. Це зберігає застарілу поведінку Matrix "спочатку попередній перегляд", тому стандартні клієнти можуть надсилати сповіщення за першим потоковим текстом попереднього перегляду, а не за завершеним блоком. +- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку асистента. Використовуйте це лише тоді, коли ви також налаштували push rules одержувачів для фіналізованих редагувань попереднього перегляду. +- `blockStreaming: true` вмикає окремі повідомлення про прогрес у Matrix. Якщо попередній перегляд потокового передавання увімкнено, Matrix зберігає живу чернетку для поточного блоку й залишає завершені блоки як окремі повідомлення. +- Коли попередній перегляд потокового передавання увімкнений, а `blockStreaming` вимкнено, Matrix редагує живу чернетку на місці й фіналізує ту саму подію, коли блок або хід завершуються. +- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потокове передавання попереднього перегляду й повертається до звичайної фінальної доставки. - Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий попередній перегляд більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа. -- Редагування попереднього перегляду потребує додаткових викликів Matrix API. Залиште потокову передачу вимкненою, якщо хочете найобережнішу поведінку щодо лімітів запитів. +- Редагування попереднього перегляду потребують додаткових викликів Matrix API. Залишайте streaming вимкненим, якщо хочете найконсервативнішу поведінку щодо обмежень швидкості. -`blockStreaming` сам по собі не вмикає чернеткові попередні перегляди. -Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додавайте `blockStreaming: true` лише якщо ви також хочете, щоб завершені блоки помічника залишалися видимими як окремі повідомлення про прогрес. +`blockStreaming` сам по собі не вмикає чернетки попереднього перегляду. +Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додавайте `blockStreaming: true` лише якщо також хочете, щоб завершені блоки асистента залишалися видимими як окремі повідомлення про прогрес. -Якщо вам потрібні стандартні сповіщення Matrix без власних push rules, використовуйте `streaming: "partial"` для поведінки з попереднім переглядом або залиште `streaming` вимкненим для доставки лише фінальної відповіді. Якщо `streaming: "off"`: +Якщо вам потрібні стандартні сповіщення Matrix без кастомних push rules, використовуйте `streaming: "partial"` для поведінки "спочатку попередній перегляд" або залиште `streaming` вимкненим для доставки лише фінальної відповіді. З `streaming: "off"`: - `blockStreaming: true` надсилає кожен завершений блок як звичайне повідомлення Matrix зі сповіщенням. - `blockStreaming: false` надсилає лише фінальну завершену відповідь як звичайне повідомлення Matrix зі сповіщенням. -### Власні push rules для тихих завершених попередніх переглядів +### Власні push rules для тихих фіналізованих попередніх переглядів Якщо ви використовуєте власну інфраструктуру Matrix і хочете, щоб тихі попередні перегляди надсилали сповіщення лише тоді, коли блок або -фінальна відповідь завершені, встановіть `streaming: "quiet"` і додайте push rule для кожного користувача для завершених редагувань попереднього перегляду. +фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте push rule для кожного користувача для фіналізованих редагувань попереднього перегляду. -Зазвичай це налаштовується на рівні користувача-отримувача, а не як глобальна зміна конфігурації homeserver: +Зазвичай це налаштування на боці користувача-одержувача, а не глобальна зміна config homeserver: -Коротка схема перед початком: +Швидка схема перед початком: -- користувач-отримувач = людина, яка має отримати сповіщення +- користувач-одержувач = людина, яка має отримати сповіщення - користувач-бот = обліковий запис Matrix OpenClaw, який надсилає відповідь -- використовуйте access token користувача-отримувача для наведених нижче викликів API -- зіставляйте `sender` у push rule із повним MXID користувача-бота +- для викликів API нижче використовуйте access token користувача-одержувача +- у push rule зіставляйте `sender` із повним MXID користувача-бота 1. Налаштуйте OpenClaw на використання тихих попередніх переглядів: @@ -249,13 +289,13 @@ Matrix екранує розділові символи в ID облікових } ``` -2. Переконайтеся, що обліковий запис отримувача вже отримує звичайні push-сповіщення Matrix. Правила тихого попереднього перегляду - працюють лише тоді, коли цей користувач уже має справні pushers/пристрої. +2. Переконайтеся, що обліковий запис одержувача вже отримує звичайні push-сповіщення Matrix. Правила для тихих попередніх переглядів + працюють лише тоді, коли в цього користувача вже налаштовані pushers/пристрої. -3. Отримайте access token користувача-отримувача. +3. Отримайте access token користувача-одержувача. - Використовуйте токен користувача, який отримує повідомлення, а не токен бота. - - Зазвичай найпростіше повторно використати токен наявної сесії клієнта. - - Якщо вам потрібно створити новий токен, можна увійти через стандартний Matrix Client-Server API: + - Найпростіше зазвичай повторно використати токен існуючої сесії клієнта. + - Якщо потрібно створити новий токен, можна ввійти через стандартний Matrix Client-Server API: ```bash curl -sS -X POST \ @@ -271,7 +311,7 @@ curl -sS -X POST \ }' ``` -4. Переконайтеся, що обліковий запис отримувача вже має pushers: +4. Перевірте, що обліковий запис одержувача вже має pushers: ```bash curl -sS \ @@ -279,10 +319,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Якщо у відповіді немає активних pushers/пристроїв, спочатку виправте звичайні сповіщення Matrix, а вже потім додавайте -наведене нижче правило OpenClaw. +Якщо це повертає відсутність активних pushers/пристроїв, спершу виправте звичайні сповіщення Matrix, перш ніж додавати +правило OpenClaw нижче. -OpenClaw позначає завершені редагування попереднього перегляду лише для тексту так: +OpenClaw позначає фіналізовані редагування попереднього перегляду лише тексту таким чином: ```json { @@ -290,7 +330,7 @@ OpenClaw позначає завершені редагування попере } ``` -5. Створіть override push rule для кожного облікового запису отримувача, який має отримувати ці сповіщення: +5. Створіть override push rule для кожного облікового запису одержувача, який повинен отримувати ці сповіщення: ```bash curl -sS -X PUT \ @@ -320,25 +360,25 @@ curl -sS -X PUT \ }' ``` -Замініть ці значення перед виконанням команди: +Замініть ці значення перед запуском команди: - `https://matrix.example.org`: базовий URL вашого homeserver - `$USER_ACCESS_TOKEN`: access token користувача, який отримує повідомлення -- `openclaw-finalized-preview-botname`: ID правила, унікальний для цього бота для цього користувача-отримувача -- `@bot:example.org`: MXID вашого Matrix-бота OpenClaw, а не MXID користувача-отримувача +- `openclaw-finalized-preview-botname`: ID правила, унікальний для цього бота для цього користувача +- `@bot:example.org`: MXID вашого Matrix-бота OpenClaw, а не MXID користувача-одержувача Важливо для конфігурацій із кількома ботами: -- Push rules мають ключ `ruleId`. Повторний запуск `PUT` для того самого ID правила оновлює саме це правило. -- Якщо один користувач-отримувач повинен отримувати сповіщення для кількох облікових записів Matrix-ботів OpenClaw, створіть одне правило на кожного бота з унікальним ID правила для кожного збігу за відправником. +- Ключем для push rules є `ruleId`. Повторний запуск `PUT` для того самого ID правила оновлює саме це правило. +- Якщо один користувач-одержувач має отримувати сповіщення від кількох облікових записів Matrix OpenClaw, створіть окреме правило для кожного бота з унікальним ID правила для кожного збігу `sender`. - Простий шаблон — `openclaw-finalized-preview-`, наприклад `openclaw-finalized-preview-ops` або `openclaw-finalized-preview-support`. -Правило оцінюється щодо відправника події: +Правило оцінюється відносно відправника події: -- автентифікуйтеся токеном користувача-отримувача -- зіставляйте `sender` з MXID бота OpenClaw +- автентифікуйтеся токеном користувача-одержувача +- зіставте `sender` з MXID бота OpenClaw -6. Переконайтеся, що правило існує: +6. Перевірте, що правило існує: ```bash curl -sS \ @@ -346,10 +386,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Протестуйте потокову відповідь. У тихому режимі в кімнаті має з’явитися тихий чернетковий попередній - перегляд, а фінальне редагування на місці має надіслати сповіщення, щойно блок або хід завершиться. +7. Протестуйте потокову відповідь. У тихому режимі кімната повинна показувати тиху чернетку попереднього перегляду, а фінальне + редагування на місці має надіслати сповіщення після завершення блоку або ходу. -Якщо пізніше потрібно видалити правило, видаліть той самий ID правила, використовуючи токен користувача-отримувача: +Якщо вам потрібно видалити правило пізніше, видаліть той самий ID правила токеном користувача-одержувача: ```bash curl -sS -X DELETE \ @@ -359,37 +399,37 @@ curl -sS -X DELETE \ Примітки: -- Створюйте правило з access token користувача-отримувача, а не бота. -- Нові користувацькі правила `override` вставляються перед стандартними правилами приглушення, тому додатковий параметр порядку не потрібен. -- Це впливає лише на редагування попереднього перегляду, що містять лише текст, які OpenClaw може безпечно завершити на місці. Резервні сценарії з медіа та застарілим попереднім переглядом усе ще використовують звичайну доставку Matrix. -- Якщо `GET /_matrix/client/v3/pushers` не показує pushers, користувач ще не має робочої доставки push-повідомлень Matrix для цього облікового запису/пристрою. +- Створюйте правило з access token користувача-одержувача, а не бота. +- Нові користувацькі правила `override` вставляються перед стандартними правилами придушення, тож додатковий параметр порядку не потрібен. +- Це впливає лише на редагування попереднього перегляду лише тексту, які OpenClaw може безпечно фіналізувати на місці. Відкат до медіа та відкат через застарілий попередній перегляд, як і раніше, використовують звичайну доставку Matrix. +- Якщо `GET /_matrix/client/v3/pushers` не показує pushers, користувач ще не має налаштованої доставки push-повідомлень Matrix для цього облікового запису/пристрою. #### Synapse -Для Synapse зазвичай достатньо наведеного вище налаштування: +Для Synapse наведеного вище налаштування зазвичай вже достатньо: -- Спеціальна зміна `homeserver.yaml` для сповіщень про завершений попередній перегляд OpenClaw не потрібна. -- Якщо ваше розгортання Synapse уже надсилає звичайні push-сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules` вище. -- Якщо Synapse працює за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно досягає Synapse. -- Якщо ви використовуєте Synapse workers, переконайтеся, що pushers працюють коректно. Доставка push-повідомлень обробляється основним процесом або `synapse.app.pusher` / налаштованими pusher workers. +- Жодних спеціальних змін у `homeserver.yaml` для сповіщень про фіналізований попередній перегляд OpenClaw не потрібно. +- Якщо ваше розгортання Synapse вже надсилає звичайні push-сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules` вище. +- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse. +- Якщо ви використовуєте workers Synapse, переконайтеся, що pushers працюють справно. Доставкою push-повідомлень займається основний процес або `synapse.app.pusher` / налаштовані pusher workers. #### Tuwunel -Для Tuwunel використовуйте той самий потік налаштування та виклик API `pushrules`, показані вище: +Для Tuwunel використовуйте той самий сценарій налаштування та виклик API `pushrules`, наведений вище: -- Специфічна для Tuwunel конфігурація для самого маркера завершеного попереднього перегляду не потрібна. +- Жодної конфігурації, специфічної для Tuwunel, для самого маркера фіналізованого попереднього перегляду не потрібно. - Якщо звичайні сповіщення Matrix уже працюють для цього користувача, основним кроком налаштування є токен користувача + виклик `pushrules` вище. -- Якщо сповіщення ніби зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цей параметр у Tuwunel 1.4.2 12 вересня 2025 року, і він може навмисно приглушувати push-повідомлення на інші пристрої, поки один пристрій активний. +- Якщо здається, що сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи увімкнено `suppress_push_when_active`. Tuwunel додав цю опцію у Tuwunel 1.4.2 12 вересня 2025 року, і вона може навмисно пригнічувати push-повідомлення на інші пристрої, поки один пристрій активний. ## Шифрування та верифікація -В зашифрованих (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, тому попередні перегляди зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Налаштування не потрібне — plugin автоматично визначає стан E2EE. +В зашифрованих (E2EE) кімнатах вихідні події із зображеннями використовують `thumbnail_file`, тому попередній перегляд зображення шифрується разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Конфігурація не потрібна — плагін автоматично визначає стан E2EE. ### Кімнати бот-до-бота За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються. -Використовуйте `allowBots`, якщо ви навмисно хочете дозволити трафік Matrix між агентами: +Використовуйте `allowBots`, якщо ви навмисно хочете дозволити міжагентний трафік Matrix: ```json5 { @@ -406,13 +446,13 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів Matrix-ботів у дозволених кімнатах і DM. -- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе ще дозволені. +- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і DM. +- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе одно дозволені. - `groups..allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати. -- OpenClaw усе ще ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповідей. -- Matrix тут не має вбудованого прапорця бота; OpenClaw трактує «створене ботом» як «надіслане іншим налаштованим обліковим записом Matrix на цьому gateway OpenClaw». +- OpenClaw, як і раніше, ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповіді. +- Matrix тут не надає нативного прапорця бота; OpenClaw трактує "написане ботом" як "надіслане іншим налаштованим обліковим записом Matrix на цьому gateway OpenClaw". -Використовуйте строгі allowlist кімнат і вимоги щодо згадок, коли вмикаєте трафік бот-до-бота в спільних кімнатах. +Використовуйте суворі allowlist кімнат і вимоги до згадування, коли вмикаєте трафік бот-до-бота в спільних кімнатах. Увімкнення шифрування: @@ -454,7 +494,7 @@ openclaw matrix verify status --include-recovery-key --json openclaw matrix verify bootstrap ``` -Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису та необов’язковим `name`. Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) для спільного шаблону. +Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису та необов’язковим `name`. Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) щодо спільного шаблону. Докладна діагностика bootstrap: @@ -462,13 +502,13 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -Примусове скидання ідентичності cross-signing перед ініціалізацією: +Примусово скинути поточну identity cross-signing перед bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Верифікація цього пристрою за допомогою recovery key: +Верифікувати цей пристрій за допомогою recovery key: ```bash openclaw matrix verify device "" @@ -480,7 +520,7 @@ openclaw matrix verify device "" openclaw matrix verify device "" --verbose ``` -Перевірка стану резервного копіювання ключів кімнат: +Перевірка стану резервного копіювання ключів кімнати: ```bash openclaw matrix verify backup status @@ -492,7 +532,7 @@ openclaw matrix verify backup status openclaw matrix verify backup status --verbose ``` -Відновлення ключів кімнат із серверної резервної копії: +Відновлення ключів кімнати з резервної копії на сервері: ```bash openclaw matrix verify backup restore @@ -504,20 +544,20 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -Видалення поточної серверної резервної копії та створення нової базової резервної копії. Якщо збережений -ключ резервної копії не вдається коректно завантажити, це скидання також може повторно створити secret storage, щоб -під час майбутніх холодних стартів можна було завантажити новий ключ резервної копії: +Видалити поточну резервну копію на сервері й створити нову базову лінію резервного копіювання. Якщо збережений +ключ резервної копії не вдається коректно завантажити, це скидання також може відтворити secret storage, щоб +майбутні холодні запуски могли завантажувати новий ключ резервної копії: ```bash openclaw matrix verify backup reset --yes ``` -Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують докладну діагностику лише з `--verbose`. -Використовуйте `--json` для повного машинозчитуваного виводу в скриптах. +Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з `--verbose`. +Використовуйте `--json` для повного машинозчитуваного виводу в сценаріях. -У конфігураціях із кількома обліковими записами CLI-команди Matrix використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. -Якщо ви налаштували кілька іменованих облікових записів, спочатку задайте `channels.matrix.defaultAccount`, інакше такі неявні CLI-операції зупиняться й попросять вас явно вибрати обліковий запис. -Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроями були явно спрямовані на іменований обліковий запис: +У конфігураціях із кількома обліковими записами команди CLI Matrix використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. +Якщо ви налаштуєте кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше такі неявні операції CLI зупиняться й попросять вас явно вибрати обліковий запис. +Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроями явно були націлені на іменований обліковий запис: ```bash openclaw matrix verify status --account assistant @@ -525,43 +565,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Коли шифрування вимкнено або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`. +Коли шифрування вимкнене або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ config цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`. ### Що означає "verified" -OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною ідентичністю cross-signing. +OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною identity cross-signing. На практиці `openclaw matrix verify status --verbose` показує три сигнали довіри: - `Locally trusted`: цьому пристрою довіряє лише поточний клієнт - `Cross-signing verified`: SDK повідомляє, що пристрій верифіковано через cross-signing - `Signed by owner`: пристрій підписано вашим власним self-signing key -`Verified by owner` стає `yes` лише тоді, коли присутні верифікація через cross-signing або підпис власника. +`Verified by owner` стає `yes` лише тоді, коли присутня верифікація через cross-signing або підпис власника. Локальної довіри самої по собі недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. ### Що робить bootstrap `openclaw matrix verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів Matrix. -Вона послідовно виконує все наведене нижче: +Вона виконує все наведене нижче у такому порядку: - ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо -- ініціалізує cross-signing і завантажує відсутні відкриті ключі cross-signing +- ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing - намагається позначити та підписати поточний пристрій через cross-signing -- створює нову серверну резервну копію ключів кімнат, якщо її ще не існує +- створює нову серверну резервну копію ключів кімнат, якщо вона ще не існує -Якщо homeserver вимагає інтерактивну автентифікацію для завантаження ключів cross-signing, OpenClaw спочатку намагається виконати завантаження без автентифікації, потім із `m.login.dummy`, а потім із `m.login.password`, коли налаштовано `channels.matrix.password`. +Якщо homeserver вимагає інтерактивної автентифікації для завантаження ключів cross-signing, OpenClaw спочатку пробує завантаження без автентифікації, потім із `m.login.dummy`, а потім із `m.login.password`, коли налаштовано `channels.matrix.password`. -Використовуйте `--force-reset-cross-signing` лише тоді, коли ви свідомо хочете відкинути поточну ідентичність cross-signing і створити нову. +Використовуйте `--force-reset-cross-signing` лише тоді, коли ви свідомо хочете відкинути поточну identity cross-signing і створити нову. -Якщо ви свідомо хочете відкинути поточну резервну копію ключів кімнат і почати нову +Якщо ви свідомо хочете відкинути поточну резервну копію ключів кімнат і розпочати нову базову лінію резервного копіювання для майбутніх повідомлень, використовуйте `openclaw matrix verify backup reset --yes`. -Робіть це лише тоді, коли ви погоджуєтеся, що невідновлювана стара зашифрована історія -залишиться недоступною і що OpenClaw може повторно створити secret storage, якщо поточний секрет -резервної копії не вдається безпечно завантажити. +Робіть це лише тоді, коли ви погоджуєтеся, що стару зашифровану історію, яку неможливо відновити, буде +недоступно й надалі, і що OpenClaw може перевідтворити secret storage, якщо поточний секрет +резервної копії неможливо безпечно завантажити. ### Нова базова лінія резервного копіювання -Якщо ви хочете зберегти працездатність майбутніх зашифрованих повідомлень і погоджуєтеся втратити невідновлювану стару історію, виконайте ці команди в такому порядку: +Якщо ви хочете зберегти працездатність майбутніх зашифрованих повідомлень і погоджуєтеся втратити стару історію, яку неможливо відновити, виконайте ці команди в такому порядку: ```bash openclaw matrix verify backup reset --yes @@ -569,68 +609,68 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Додайте `--account ` до кожної команди, якщо хочете явно націлити їх на іменований обліковий запис Matrix. +Додавайте `--account ` до кожної команди, якщо хочете явно націлити її на іменований обліковий запис Matrix. ### Поведінка під час запуску Коли `encryption: true`, Matrix за замовчуванням встановлює `startupVerification` у `"if-unverified"`. -Під час запуску, якщо цей пристрій усе ще не верифікований, Matrix надішле запит на самоверифікацію в іншому клієнті Matrix, +Під час запуску, якщо цей пристрій досі не верифікований, Matrix надішле запит на самоверифікацію в іншому клієнті Matrix, пропустить дублікати запитів, якщо один уже очікує, і застосує локальний cooldown перед повторною спробою після перезапусків. -Невдалі спроби створення запиту за замовчуванням повторюються швидше, ніж успішне створення запиту. +За замовчуванням невдалі спроби запитів повторюються швидше, ніж успішне створення запиту. Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`, -якщо вам потрібне коротше або довше вікно повторної спроби. +якщо хочете коротше або довше вікно повторної спроби. -Під час запуску також автоматично виконується обережний прохід ініціалізації crypto. -Цей прохід спочатку намагається повторно використати поточні secret storage та ідентичність cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний потік відновлення bootstrap. +Під час запуску також автоматично виконується консервативний прохід bootstrap криптографії. +Цей прохід спершу намагається повторно використати поточні secret storage та identity cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний сценарій відновлення bootstrap. -Якщо під час запуску виявлено пошкоджений стан bootstrap і налаштовано `channels.matrix.password`, OpenClaw може спробувати суворіший шлях відновлення. -Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю ідентичність замість автоматичного скидання. +Якщо під час запуску виявлено зіпсований стан bootstrap і налаштовано `channels.matrix.password`, OpenClaw може спробувати суворіший шлях відновлення. +Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю identity, а не скидає її автоматично. -Оновлення з попереднього публічного plugin Matrix: +Оновлення з попереднього публічного плагіна Matrix: -- OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, access token і ідентичність пристрою, коли це можливо. -- Перш ніж буде виконано будь-які практичні зміни міграції Matrix, OpenClaw створює або повторно використовує recovery snapshot у `~/Backups/openclaw-migrations/`. -- Якщо ви використовуєте кілька облікових записів Matrix, перед оновленням зі старої схеми flat-store задайте `channels.matrix.defaultAccount`, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан. -- Якщо попередній plugin зберігав локально ключ розшифрування резервної копії ключів кімнат Matrix, startup або `openclaw doctor --fix` автоматично імпортує його в новий потік recovery key. -- Якщо access token Matrix змінився після підготовки міграції, startup тепер сканує сусідні корені сховища з hash токена на наявність відкладеного стану відновлення застарілих даних, перш ніж відмовитися від автоматичного відновлення резервної копії. -- Якщо access token Matrix змінюється пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер надає перевагу повторному використанню найповнішого наявного кореня сховища з hash токена замість початку з порожнього каталогу стану Matrix. -- Під час наступного запуску gateway резервні ключі кімнат буде автоматично відновлено в нове crypto store. -- Якщо старий plugin мав лише локальні ключі кімнат, які ніколи не були збережені в резервній копії, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною до ручного відновлення. -- Див. [Matrix migration](/uk/install/migrating-matrix), щоб ознайомитися з повним потоком оновлення, обмеженнями, командами відновлення та поширеними повідомленнями міграції. +- OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, access token і identity пристрою, коли це можливо. +- Перш ніж буде виконано будь-які дієві зміни міграції Matrix, OpenClaw створює або повторно використовує recovery snapshot у `~/Backups/openclaw-migrations/`. +- Якщо ви використовуєте кілька облікових записів Matrix, встановіть `channels.matrix.defaultAccount` перед оновленням зі старого макета flat-store, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан. +- Якщо попередній плагін зберігав локально ключ дешифрування резервної копії ключів кімнати Matrix, під час запуску або `openclaw doctor --fix` його буде автоматично імпортовано в новий сценарій recovery key. +- Якщо access token Matrix змінився після підготовки міграції, під час запуску тепер виконується сканування сусідніх кореневих каталогів сховища token-hash у пошуках очікуваного застарілого стану відновлення перед тим, як відмовитися від автоматичного відновлення резервної копії. +- Якщо access token Matrix змінюється пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер віддає перевагу повторному використанню найповнішого наявного кореневого каталогу token-hash замість початку з порожнього каталогу стану Matrix. +- Під час наступного запуску gateway резервні копії ключів кімнат автоматично відновлюються в нове crypto store. +- Якщо старий плагін мав лише локальні ключі кімнат, які ніколи не резервувалися, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну. +- Див. [Matrix migration](/uk/install/migrating-matrix) щодо повного сценарію оновлення, обмежень, команд відновлення й типових повідомлень міграції. -Зашифрований стан під час виконання організовано за коренями hash токена для кожного облікового запису та користувача в +Зашифрований runtime state організовано в кореневих каталогах token-hash для кожного облікового запису й користувача в `~/.openclaw/matrix/accounts//__//`. Цей каталог містить sync store (`bot-storage.json`), crypto store (`crypto/`), файл recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), -прив’язки тредів (`thread-bindings.json`) і стан startup verification (`startup-verification.json`), +прив’язки тредів (`thread-bindings.json`) і стан верифікації під час запуску (`startup-verification.json`), коли ці можливості використовуються. -Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний -корінь для цього кортежу account/homeserver/user, щоб попередній sync state, crypto state, прив’язки тредів -і стан startup verification залишалися доступними. +Коли токен змінюється, але identity облікового запису лишається тією самою, OpenClaw повторно використовує найкращий наявний +кореневий каталог для цього кортежу account/homeserver/user, щоб попередній sync state, crypto state, прив’язки тредів +і стан верифікації під час запуску залишалися доступними. ### Модель Node crypto store -Matrix E2EE у цьому plugin використовує офіційний шлях Rust crypto із `matrix-js-sdk` у Node. -Цей шлях очікує persistence на основі IndexedDB, якщо ви хочете, щоб crypto state зберігався після перезапусків. +Matrix E2EE у цьому плагіні використовує офіційний шлях Rust crypto з `matrix-js-sdk` у Node. +Цей шлях очікує збереження на основі IndexedDB, якщо ви хочете, щоб crypto state переживав перезапуски. -Наразі OpenClaw забезпечує це в Node так: +Наразі OpenClaw надає це в Node таким чином: -- використовує `fake-indexeddb` як shim API IndexedDB, якого очікує SDK -- відновлює вміст Rust crypto IndexedDB з `crypto-idb-snapshot.json` перед `initRustCrypto` -- зберігає оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після ініціалізації та під час виконання -- серіалізує відновлення та збереження snapshot щодо `crypto-idb-snapshot.json` за допомогою advisory file lock, щоб persistence під час виконання gateway і обслуговування CLI не конфліктували на одному й тому самому файлі snapshot +- використовує `fake-indexeddb` як shim IndexedDB API, який очікує SDK +- відновлює вміст IndexedDB Rust crypto з `crypto-idb-snapshot.json` перед `initRustCrypto` +- зберігає оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після init і під час runtime +- серіалізує відновлення та збереження snapshot відносно `crypto-idb-snapshot.json` за допомогою дорадчого file lock, щоб збереження під час роботи gateway і обслуговування CLI не змагалися за один і той самий файл snapshot -Це plumbing сумісності/сховища, а не власна реалізація crypto. -Файл snapshot є чутливим станом під час виконання і зберігається з обмежувальними правами доступу до файлу. -У моделі безпеки OpenClaw хост gateway і локальний каталог стану OpenClaw уже перебувають у межах довіреної межі оператора, тому це насамперед питання операційної надійності, а не окрема віддалена межа довіри. +Це plumbing сумісності/зберігання, а не кастомна реалізація криптографії. +Файл snapshot є чутливим runtime state і зберігається з обмежувальними правами доступу до файлів. +У межах моделі безпеки OpenClaw хост gateway і локальний каталог стану OpenClaw уже входять до довіреної межі оператора, тому це насамперед операційне питання надійності, а не окрема межа віддаленої довіри. Заплановане покращення: -- додати підтримку SecretRef для постійного ключового матеріалу Matrix, щоб recovery keys і пов’язані секрети шифрування сховища можна було брати з провайдерів secrets OpenClaw, а не лише з локальних файлів +- додати підтримку SecretRef для постійного ключового матеріалу Matrix, щоб recovery keys і пов’язані секрети шифрування сховища можна було брати з провайдерів секретів OpenClaw, а не лише з локальних файлів ## Керування профілем -Оновіть власний профіль Matrix для вибраного облікового запису за допомогою: +Оновіть self-profile Matrix для вибраного облікового запису за допомогою: ```bash openclaw matrix profile set --name "OpenClaw Assistant" @@ -639,37 +679,37 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png Додайте `--account `, якщо хочете явно націлити команду на іменований обліковий запис Matrix. -Matrix безпосередньо приймає URL аватарів `mxc://`. Коли ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix і записує розв’язаний URL `mxc://` назад у `channels.matrix.avatarUrl` (або в перевизначення вибраного облікового запису). +Matrix напряму приймає URL аватарів `mxc://`. Коли ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix, а потім зберігає визначений URL `mxc://` назад у `channels.matrix.avatarUrl` (або у вибране перевизначення облікового запису). -## Автоматичні сповіщення про верифікацію +## Автоматичні повідомлення про верифікацію -Тепер Matrix публікує повідомлення про життєвий цикл верифікації безпосередньо в строгій DM-кімнаті верифікації як повідомлення `m.notice`. +Matrix тепер публікує повідомлення про життєвий цикл верифікації безпосередньо в сувору DM-кімнату верифікації як повідомлення `m.notice`. Це включає: - повідомлення про запит верифікації -- повідомлення про готовність до верифікації (з явною підказкою «Верифікувати за емодзі») +- повідомлення про готовність до верифікації (з явною підказкою "Verify by emoji") - повідомлення про початок і завершення верифікації -- деталі SAS (емодзі та десяткові значення), коли вони доступні +- деталі SAS (emoji і десяткові числа), коли вони доступні -Вхідні запити верифікації від іншого клієнта Matrix відстежуються та автоматично приймаються OpenClaw. -Для потоків самоверифікації OpenClaw також автоматично запускає SAS-потік, коли стає доступною верифікація за емодзі, і підтверджує свій бік. -Для запитів верифікації від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім очікує, доки SAS-потік продовжиться у звичайному режимі. -Щоб завершити верифікацію, вам усе одно потрібно порівняти SAS у вигляді емодзі або десяткових чисел у вашому клієнті Matrix і підтвердити там «They match». +Вхідні запити верифікації від іншого клієнта Matrix відстежуються й автоматично приймаються OpenClaw. +Для сценаріїв самоверифікації OpenClaw також автоматично запускає сценарій SAS, коли стає доступною верифікація emoji, і підтверджує свою сторону. +Для запитів верифікації від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, поки сценарій SAS продовжиться звичайним чином. +Щоб завершити верифікацію, вам усе одно потрібно порівняти emoji або десятковий SAS у вашому клієнті Matrix і там підтвердити "They match". -OpenClaw не приймає бездумно дублікати самостійно ініційованих потоків. Під час запуску не створюється новий запит, якщо запит на самоверифікацію вже очікує. +OpenClaw не приймає сліпо автоматично дубльовані сценарії, ініційовані ним самим. Під час запуску створення нового запиту пропускається, якщо запит на самоверифікацію вже очікує. -Системні повідомлення/повідомлення протоколу верифікації не пересилаються в pipeline чату агента, тому вони не породжують `NO_REPLY`. +Повідомлення протоколу/системи верифікації не пересилаються в конвеєр чату агента, тому вони не створюють `NO_REPLY`. ### Гігієна пристроїв -Старі пристрої Matrix під керуванням OpenClaw можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. -Перелічіть їх за допомогою: +Старі пристрої Matrix, керовані OpenClaw, можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. +Перегляньте їх за допомогою: ```bash openclaw matrix devices list ``` -Видаліть застарілі пристрої Matrix під керуванням OpenClaw за допомогою: +Видаліть застарілі пристрої Matrix, керовані OpenClaw, за допомогою: ```bash openclaw matrix devices prune-stale @@ -677,53 +717,53 @@ openclaw matrix devices prune-stale ### Відновлення Direct Room -Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі одиночні кімнати замість активного DM. Перевірити поточне зіставлення для співрозмовника можна так: +Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі окремі кімнати замість активного DM. Щоб перевірити поточне зіставлення для співрозмовника, використовуйте: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Відновити його можна так: +Щоб відновити його: ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -Відновлення зберігає логіку, специфічну для Matrix, усередині plugin: +Відновлення зберігає логіку, специфічну для Matrix, усередині плагіна: -- воно надає перевагу строгому DM 1:1, який уже зіставлено в `m.direct` -- інакше воно повертається до будь-якого поточного приєднаного строгого DM 1:1 із цим користувачем -- якщо справного DM не існує, воно створює нову direct room і переписує `m.direct`, щоб указати на неї +- воно надає перевагу суворому 1:1 DM, який уже зіставлено в `m.direct` +- інакше повертається до будь-якого поточного приєднаного суворого 1:1 DM із цим користувачем +- якщо справного DM не існує, створює нову direct room і переписує `m.direct`, щоб вона вказувала на неї -Потік відновлення не видаляє старі кімнати автоматично. Він лише вибирає справний DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення про верифікацію та інші потоки direct-message знову були спрямовані в правильну кімнату. +Сценарій відновлення не видаляє старі кімнати автоматично. Він лише вибирає справний DM і оновлює зіставлення, щоб нові надсилання Matrix, повідомлення про верифікацію та інші сценарії direct-message знову потрапляли до правильної кімнати. ## Треди -Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилань через message tool. +Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилань через message-tool. -- `dm.sessionScope: "per-user"` (за замовчуванням) залишає маршрутизацію DM Matrix прив’язаною до відправника, тож кілька DM-кімнат можуть ділити одну сесію, коли вони розв’язуються до того самого співрозмовника. -- `dm.sessionScope: "per-room"` ізолює кожну кімнату DM Matrix в окремий ключ сесії, водночас зберігаючи звичайні перевірки автентифікації та allowlist для DM. -- Явні прив’язки розмов Matrix усе ще мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибрану ними цільову сесію. -- `threadReplies: "off"` залишає відповіді на верхньому рівні та зберігає вхідні повідомлення в треді на батьківській сесії. +- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію Matrix DM з областю дії відправника, тому кілька DM-кімнат можуть спільно використовувати одну сесію, якщо вони визначаються як той самий співрозмовник. +- `dm.sessionScope: "per-room"` ізолює кожну Matrix DM-кімнату у власний ключ сесії, водночас використовуючи звичайні перевірки автентифікації DM і allowlist. +- Явні прив’язки розмов Matrix усе одно мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибрану цільову сесію. +- `threadReplies: "off"` залишає відповіді на верхньому рівні й зберігає вхідні повідомлення з тредів на батьківській сесії. - `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді. -- `threadReplies: "always"` залишає відповіді в кімнаті в треді з коренем у повідомленні-тригері та маршрутизує цю розмову через відповідну сесію з областю дії треду від першого повідомлення-тригера. -- `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете зберігати треди кімнат ізольованими, залишаючи DM пласкими. -- Вхідні повідомлення в треді включають кореневе повідомлення треду як додатковий контекст агента. -- Надсилання через message tool тепер автоматично успадковують поточний тред Matrix, коли ціллю є та сама кімната або та сама ціль DM-користувача, якщо не вказано явний `threadId`. -- Повторне використання цілі DM-користувача в межах тієї самої сесії спрацьовує лише тоді, коли метадані поточної сесії доводять, що це той самий DM-співрозмовник у тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації з областю дії користувача. -- Коли OpenClaw бачить, що DM-кімната Matrix конфліктує з іншою DM-кімнатою в тій самій спільній DM-сесії Matrix, він публікує одноразове `m.notice` у цій кімнаті з escape hatch `/focus`, коли прив’язки тредів увімкнено, і з підказкою `dm.sessionScope`. -- Прив’язки тредів під час виконання підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треду `/acp spawn` тепер працюють у кімнатах Matrix і DM. -- `/focus` на верхньому рівні кімнати/DM Matrix створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. -- Виконання `/focus` або `/acp spawn --thread here` усередині наявного треду Matrix натомість прив’язує цей поточний тред. +- `threadReplies: "always"` зберігає відповіді в кімнаті всередині треду, коренем якого є повідомлення-тригер, і маршрутизує цю розмову через відповідну сесію з областю дії треду від першого повідомлення-тригера. +- `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди кімнат, залишаючи DM пласкими. +- Вхідні повідомлення з тредів включають кореневе повідомлення треду як додатковий контекст агента. +- Надсилання через message-tool тепер автоматично успадковують поточний тред Matrix, коли ціль — та сама кімната або той самий цільовий користувач DM, якщо не вказано явний `threadId`. +- Повторне використання цілі користувача DM для тієї самої сесії спрацьовує лише тоді, коли метадані поточної сесії підтверджують того самого співрозмовника DM у тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації з областю дії користувача. +- Коли OpenClaw бачить, що кімната Matrix DM конфліктує з іншою DM-кімнатою в тій самій спільній сесії Matrix DM, він публікує одноразове `m.notice` у цій кімнаті з аварійним варіантом `/focus`, коли ввімкнено прив’язки тредів і підказку `dm.sessionScope`. +- Runtime-прив’язки тредів підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треду `/acp spawn` тепер працюють у кімнатах і DM Matrix. +- `/focus` верхнього рівня в кімнаті/DM Matrix створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. +- Виконання `/focus` або `/acp spawn --thread here` всередині наявного треду Matrix натомість прив’язує цей поточний тред. ## Прив’язки розмов ACP -Кімнати Matrix, DM і наявні треди Matrix можна перетворити на довговічні робочі простори ACP без зміни поверхні чату. +Кімнати, DM та наявні треди Matrix можна перетворювати на довговічні робочі простори ACP без зміни поверхні чату. -Швидкий потік для оператора: +Швидкий сценарій для оператора: -- Виконайте `/acp spawn codex --bind here` усередині DM Matrix, кімнати або наявного треду, яким ви хочете й далі користуватися. -- У верхньорівневому DM або кімнаті Matrix поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії ACP. +- Виконайте `/acp spawn codex --bind here` всередині Matrix DM, кімнати або наявного треду, який ви хочете й надалі використовувати. +- У Matrix DM або кімнаті верхнього рівня поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії ACP. - Усередині наявного треду Matrix `--bind here` прив’язує цей поточний тред на місці. - `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. - `/acp close` закриває сесію ACP і видаляє прив’язку. @@ -731,9 +771,9 @@ Matrix підтримує нативні треди Matrix як для авто Примітки: - `--bind here` не створює дочірній тред Matrix. -- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw має створити або прив’язати дочірній тред Matrix. +- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw потрібно створити або прив’язати дочірній тред Matrix. -### Конфігурація прив’язки тредів +### Конфігурація прив’язок тредів Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для каналу: @@ -743,27 +783,27 @@ Matrix успадковує глобальні значення за замов - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Прапорці створення прив’язок тредів у Matrix потрібно вмикати явно: +Прапорці створення з прив’язкою до тредів у Matrix мають режим opt-in: - Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити верхньорівневому `/focus` створювати й прив’язувати нові треди Matrix. - Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати сесії ACP до тредів Matrix. ## Реакції -Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні ack reactions. +Matrix підтримує вихідні дії з реакціями, вхідні сповіщення про реакції та вхідні ack reactions. - Інструменти вихідних реакцій контролюються `channels["matrix"].actions.reactions`. -- `react` додає реакцію до певної події Matrix. -- `reactions` перелічує поточне зведення реакцій для певної події Matrix. -- `emoji=""` видаляє власні реакції облікового запису бота на цю подію. -- `remove: true` видаляє лише вказану реакцію emoji з облікового запису бота. +- `react` додає реакцію до конкретної події Matrix. +- `reactions` показує поточний зведений список реакцій для конкретної події Matrix. +- `emoji=""` видаляє власні реакції облікового запису бота на цій події. +- `remove: true` видаляє з облікового запису бота лише реакцію із зазначеним emoji. -Область дії ack reactions визначається в такому порядку: +Область дії ack reactions визначається у стандартному порядку OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- резервний emoji ідентичності агента +- резервний emoji identity агента Область дії ack reaction визначається в такому порядку: @@ -775,33 +815,33 @@ Matrix підтримує вихідні дії реакцій, вхідні с - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- значення за замовчуванням: `own` +- за замовчуванням: `own` Поточна поведінка: -- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони спрямовані на повідомлення Matrix, створені ботом. +- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони націлені на повідомлення Matrix, створені ботом. - `reactionNotifications: "off"` вимикає системні події реакцій. -- Видалення реакцій усе ще не синтезується в системні події, тому що Matrix подає їх як редагування, а не як окремі видалення `m.reaction`. +- Видалення реакцій як і раніше не синтезується в системні події, оскільки Matrix показує це як redactions, а не як окреме видалення `m.reaction`. ## Контекст історії -- `channels.matrix.historyLimit` керує тим, скільки нещодавніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix запускає агента. -- Значення резервно береться з `messages.groupChat.historyLimit`. Якщо обидва не встановлені, ефективне значення за замовчуванням — `0`, тож повідомлення кімнат, обмежені згадками, не буферизуються. Установіть `0`, щоб вимкнути. -- Історія кімнат Matrix стосується лише кімнат. DM, як і раніше, використовують звичайну історію сесії. -- Історія кімнат Matrix працює лише для очікуваних повідомлень: OpenClaw буферизує повідомлення кімнати, які ще не викликали відповідь, а потім фіксує це вікно, коли надходить згадка або інший тригер. -- Поточне повідомлення-тригер не включається до `InboundHistory`; воно залишається в основному вхідному тілі для цього ходу. -- Повторні спроби тієї самої події Matrix повторно використовують початковий snapshot історії замість зміщення вперед до новіших повідомлень кімнати. +- `channels.matrix.historyLimit` керує тим, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix запускає агента. +- Використовується fallback до `messages.groupChat.historyLimit`. Якщо обидва значення не встановлено, фактичне значення за замовчуванням — `0`, тому повідомлення кімнати з вимогою згадування не буферизуються. Установіть `0`, щоб вимкнути. +- Історія кімнат Matrix обмежується лише кімнатою. DM, як і раніше, використовують звичайну історію сесії. +- Історія кімнат Matrix є лише pending: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім робить snapshot цього вікна, коли надходить згадування або інший тригер. +- Поточне повідомлення-тригер не включається в `InboundHistory`; воно залишається в основному вхідному тілі для цього ходу. +- Повторні спроби для тієї самої події Matrix повторно використовують оригінальний snapshot історії, а не зсуваються вперед до новіших повідомлень кімнати. ## Видимість контексту -Matrix підтримує спільний контроль `contextVisibility` для додаткового контексту кімнати, такого як витягнутий текст відповіді, корені тредів і очікувана історія. +Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, наприклад отриманого тексту відповіді, коренів тредів і pending history. - `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається як отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist кімнати/користувача. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. +- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все одно зберігає одну явну цитовану відповідь. Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення запустити відповідь. -Авторизація тригера, як і раніше, визначається через `groupPolicy`, `groups`, `groupAllowFrom` і налаштування політики DM. +Авторизація тригера, як і раніше, походить із налаштувань `groupPolicy`, `groups`, `groupAllowFrom` і політики DM. ## Приклад політики DM і кімнат @@ -826,7 +866,7 @@ Matrix підтримує спільний контроль `contextVisibility` } ``` -Див. [Groups](/uk/channels/groups), щоб дізнатися про поведінку щодо згадок і allowlist. +Див. [Groups](/uk/channels/groups) щодо поведінки з вимогою згадування та allowlist. Приклад pairing для Matrix DM: @@ -835,53 +875,53 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -Якщо непідтверджений користувач Matrix продовжує надсилати вам повідомлення до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати відповідь-нагадування після короткого cooldown замість створення нового коду. +Якщо користувач Matrix без схвалення продовжує писати вам до схвалення, OpenClaw повторно використовує той самий pending code pairing і може знову надіслати нагадування після короткого cooldown замість створення нового коду. -Див. [Pairing](/uk/channels/pairing), щоб ознайомитися зі спільним потоком pairing DM і структурою зберігання. +Див. [Pairing](/uk/channels/pairing) щодо спільного сценарію pairing для DM і структури зберігання. ## Підтвердження exec Matrix може діяти як клієнт підтвердження exec для облікового запису Matrix. - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (необов’язково; резервно використовує `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (необов’язково; fallback до `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Ті, хто підтверджує, мають бути Matrix user ID, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"`, і можна розв’язати принаймні одного того, хто підтверджує, або з `execApprovals.approvers`, або з `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтвердження. Інакше запити на підтвердження резервно переходять до інших налаштованих маршрутів підтвердження або до резервної політики підтвердження exec. +Погоджувачами мають бути Matrix user ID, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні підтвердження exec, коли `enabled` не встановлено або має значення `"auto"` і принаймні одного погоджувача можна визначити або з `execApprovals.approvers`, або з `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтверджень. Інакше запити на підтвердження повертаються до інших налаштованих маршрутів підтвердження або fallback policy для підтвердження exec. -Нативна маршрутизація Matrix сьогодні стосується лише exec: +Нативна маршрутизація Matrix наразі працює лише для exec: - `channels.matrix.execApprovals.*` керує нативною маршрутизацією DM/каналу лише для підтверджень exec. -- Підтвердження plugin, як і раніше, використовують спільний `/approve` у тому самому чаті плюс будь-яке налаштоване пересилання `approvals.plugin`. -- Matrix усе ще може повторно використовувати `channels.matrix.dm.allowFrom` для авторизації підтверджень plugin, коли може безпечно визначити тих, хто підтверджує, але не має окремого нативного шляху fanout DM/каналу для підтверджень plugin. +- Підтвердження плагінів, як і раніше, використовують спільне `/approve` у тому самому чаті плюс будь-яке налаштоване пересилання `approvals.plugin`. +- Matrix усе ще може повторно використовувати `channels.matrix.dm.allowFrom` для авторизації підтверджень плагінів, коли може безпечно визначити погоджувачів, але не надає окремого нативного шляху fanout DM/каналу для підтверджень плагінів. Правила доставки: -- `target: "dm"` надсилає запити на підтвердження в DM тим, хто підтверджує -- `target: "channel"` надсилає запит назад до вихідної кімнати або DM Matrix -- `target: "both"` надсилає в DM тим, хто підтверджує, і до вихідної кімнати або DM Matrix +- `target: "dm"` надсилає запити на підтвердження в DM погоджувачів +- `target: "channel"` надсилає запит назад до вихідної кімнати Matrix або DM +- `target: "both"` надсилає запити і в DM погоджувачів, і до вихідної кімнати Matrix або DM -Запити на підтвердження Matrix ініціалізують ярлики реакцій на основному повідомленні підтвердження: +Запити на підтвердження Matrix додають ярлики реакцій до основного повідомлення підтвердження: - `✅` = дозволити один раз -- `❌` = заборонити +- `❌` = відхилити - `♾️` = дозволити завжди, якщо таке рішення дозволене ефективною політикою exec -Ті, хто підтверджує, можуть реагувати на це повідомлення або використовувати резервні slash commands: `/approve allow-once`, `/approve allow-always` або `/approve deny`. +Погоджувачі можуть реагувати на це повідомлення або використати резервні slash-команди: `/approve allow-once`, `/approve allow-always` або `/approve deny`. -Підтверджувати або відхиляти можуть лише розв’язані особи, які мають на це право. Доставка в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. +Лише визначені погоджувачі можуть схвалювати або відхиляти. Доставка в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. -Запити на підтвердження Matrix повторно використовують спільний core approval planner. Специфічна для Matrix нативна поверхня — це лише транспорт для підтверджень exec: маршрутизація кімнати/DM і поведінка send/update/delete повідомлень. +Запити на підтвердження Matrix повторно використовують спільний core approval planner. Нативна поверхня, специфічна для Matrix, є лише транспортним рівнем для підтверджень exec: маршрутизація кімнат/DM і поведінка надсилання/оновлення/видалення повідомлень. -Перевизначення для окремого облікового запису: +Перевизначення для облікового запису: - `channels.matrix.accounts..execApprovals` Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals) -## Приклад із кількома обліковими записами +## Приклад кількох облікових записів ```json5 { @@ -911,29 +951,31 @@ Matrix може діяти як клієнт підтвердження exec д } ``` -Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис їх не перевизначає. -Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix через `groups..account` (або застарілий `rooms..account`). +Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не перевизначає їх. +Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix за допомогою `groups..account` (або застарілого `rooms..account`). Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` усе ще працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. -Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (`homeserver` плюс `accessToken` або `homeserver` плюс `userId` і `password`); іменовані облікові записи можуть залишатися доступними для виявлення з `homeserver` плюс `userId`, коли кешовані облікові дані пізніше задовольнять автентифікацію. -Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, просування під час відновлення/налаштування з одного облікового запису до кількох зберігає цей обліковий запис замість створення нового запису `accounts.default`. У просунутий обліковий запис переміщуються лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки залишаються на верхньому рівні. -Установіть `defaultAccount`, якщо хочете, щоб OpenClaw надавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probing і CLI-операцій. -Якщо ви налаштували кілька іменованих облікових записів, задайте `defaultAccount` або передавайте `--account ` для CLI-команд, які залежать від неявного вибору облікового запису. +Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все ще можуть лишатися доступними для виявлення з `homeserver` плюс `userId`, коли кешовані облікові дані задовольнять автентифікацію пізніше. +Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, просування налаштування/відновлення від одного облікового запису до кількох зберігає цей обліковий запис замість створення нового запису `accounts.default`. До просунутого облікового запису переміщуються лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки залишаються на верхньому рівні. +Установіть `defaultAccount`, якщо хочете, щоб OpenClaw віддавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probing і операцій CLI. +Якщо ви налаштували кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для команд CLI, які покладаються на неявний вибір облікового запису. Передавайте `--account ` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, якщо хочете перевизначити цей неявний вибір для однієї команди. ## Приватні/LAN homeserver -За замовчуванням OpenClaw блокує приватні/внутрішні homeserver Matrix для захисту від SSRF, якщо ви -явно не ввімкнете це окремо для кожного облікового запису. +За замовчуванням OpenClaw блокує приватні/внутрішні Matrix homeserver для захисту від SSRF, якщо ви +явно не ввімкнете це для кожного облікового запису окремо. -Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому імені хоста, увімкніть -`allowPrivateNetwork` для цього облікового запису Matrix: +Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому hostname, увімкніть +`network.dangerouslyAllowPrivateNetwork` для цього облікового запису Matrix: ```json5 { channels: { matrix: { homeserver: "http://matrix-synapse:8008", - allowPrivateNetwork: true, + network: { + dangerouslyAllowPrivateNetwork: true, + }, accessToken: "syt_internal_xxx", }, }, @@ -950,12 +992,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Ця явна згода дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver, такі як -`http://matrix.example.org:8008`, як і раніше, блокуються. Коли можливо, надавайте перевагу `https://`. +Цей opt-in дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver, наприклад +`http://matrix.example.org:8008`, як і раніше, блокуються. За можливості віддавайте перевагу `https://`. ## Проксіювання трафіку Matrix -Якщо для вашого розгортання Matrix потрібен явний вихідний HTTP(S) proxy, задайте `channels.matrix.proxy`: +Якщо для вашого розгортання Matrix потрібен явний вихідний HTTP(S) proxy, установіть `channels.matrix.proxy`: ```json5 { @@ -969,87 +1011,87 @@ openclaw matrix account add \ } ``` -Іменовані облікові записи можуть перевизначати значення верхнього рівня через `channels.matrix.accounts..proxy`. -OpenClaw використовує те саме налаштування proxy для трафіку Matrix під час виконання та для probes статусу облікового запису. +Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням через `channels.matrix.accounts..proxy`. +OpenClaw використовує той самий параметр proxy для runtime-трафіку Matrix і перевірок статусу облікового запису. -## Розв’язання цілі +## Розв’язання цілей -Matrix приймає такі форми цілей усюди, де OpenClaw просить вас вказати ціль кімнати або користувача: +Matrix приймає такі форми цілей усюди, де OpenClaw просить вас указати ціль кімнати або користувача: - Користувачі: `@user:server`, `user:@user:server` або `matrix:user:@user:server` - Кімнати: `!room:server`, `room:!room:server` або `matrix:room:!room:server` -- Аліаси: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server` +- Псевдоніми: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server` Живий пошук у каталозі використовує обліковий запис Matrix, у який виконано вхід: -- Пошук користувачів запитує каталог користувачів Matrix на цьому homeserver. -- Пошук кімнат безпосередньо приймає явні ID кімнат і аліаси, а потім резервно переходить до пошуку серед назв приєднаних кімнат для цього облікового запису. -- Пошук за назвами приєднаних кімнат є best-effort. Якщо назву кімнати не вдається розв’язати до ID або аліаса, її буде проігноровано під час виконання розв’язання allowlist. +- Пошук користувачів звертається до каталогу користувачів Matrix на цьому homeserver. +- Пошук кімнат напряму приймає явні ID кімнат і псевдоніми, а потім повертається до пошуку назв приєднаних кімнат для цього облікового запису. +- Пошук за назвою приєднаної кімнати працює за принципом best-effort. Якщо назву кімнати не вдається визначити як ID або псевдонім, вона ігнорується під час runtime-розв’язання allowlist. -## Посилання на конфігурацію +## Довідник конфігурації - `enabled`: увімкнути або вимкнути канал. -- `name`: необов’язкова мітка облікового запису. +- `name`: необов’язкова мітка для облікового запису. - `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix. - `homeserver`: URL homeserver, наприклад `https://matrix.example.org`. -- `allowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver розв’язується в `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`. +- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver визначається як `localhost`, LAN/Tailscale IP або внутрішній хост на кшталт `matrix-synapse`. - `proxy`: необов’язковий URL HTTP(S) proxy для трафіку Matrix. Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням власним `proxy`. - `userId`: повний Matrix user ID, наприклад `@bot:example.org`. -- `accessToken`: access token для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються звичайні текстові значення й значення SecretRef у providers env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). -- `password`: пароль для входу на основі пароля. Підтримуються звичайні текстові значення й значення SecretRef. +- `accessToken`: access token для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються звичайні текстові значення та значення SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). +- `password`: пароль для входу на основі пароля. Підтримуються звичайні текстові значення та значення SecretRef. - `deviceId`: явний Matrix device ID. -- `deviceName`: відображувана назва пристрою для входу за паролем. -- `avatarUrl`: збережений URL власного аватара для синхронізації профілю та оновлень `set-profile`. -- `initialSyncLimit`: ліміт подій початкової синхронізації під час запуску. +- `deviceName`: display name пристрою для входу за паролем. +- `avatarUrl`: збережений URL власного аватара для синхронізації профілю й оновлень `set-profile`. +- `initialSyncLimit`: ліміт подій синхронізації під час запуску. - `encryption`: увімкнути E2EE. -- `allowlistOnly`: примусово використовувати лише поведінку allowlist для DM і кімнат. +- `allowlistOnly`: примусова поведінка лише за allowlist для DM і кімнат. - `allowBots`: дозволити повідомлення від інших налаштованих облікових записів Matrix OpenClaw (`true` або `"mentions"`). - `groupPolicy`: `open`, `allowlist` або `disabled`. - `contextVisibility`: режим видимості додаткового контексту кімнати (`all`, `allowlist`, `allowlist_quote`). - `groupAllowFrom`: allowlist user ID для трафіку кімнат. -- Записи `groupAllowFrom` мають бути повними Matrix user ID. Нерозв’язані імена під час виконання ігноруються. -- `historyLimit`: максимальна кількість повідомлень кімнати, які включаються як контекст історії групи. Резервно використовує `messages.groupChat.historyLimit`; якщо обидва не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. -- `replyToMode`: `off`, `first` або `all`. +- Записи `groupAllowFrom` мають бути повними Matrix user ID. Нерозпізнані імена ігноруються під час runtime. +- `historyLimit`: максимальна кількість повідомлень кімнати, які включаються як контекст історії групи. Використовує fallback до `messages.groupChat.historyLimit`; якщо обидва значення не встановлено, фактичне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. +- `replyToMode`: `off`, `first`, `all` або `batched`. - `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix. -- `streaming`: `off` (за замовчуванням), `partial`, `quiet`, `true` або `false`. `partial` і `true` вмикають чернеткові оновлення з попереднім переглядом через звичайні текстові повідомлення Matrix. `quiet` використовує попередні перегляди-повідомлення без сповіщень для самохостингових конфігурацій із push rules. -- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків помічника, поки активний потоковий чернетковий попередній перегляд. +- `streaming`: `off` (за замовчуванням), `partial`, `quiet`, `true` або `false`. `partial` і `true` вмикають оновлення чернеток за принципом "спочатку попередній перегляд" зі звичайними текстовими повідомленнями Matrix. `quiet` використовує попередні тихі повідомлення для власних конфігурацій push rules. +- `blockStreaming`: `true` вмикає окремі повідомлення про прогрес для завершених блоків асистента, поки активне потокове передавання чернетки попереднього перегляду. - `threadReplies`: `off`, `inbound` або `always`. -- `threadBindings`: перевизначення на рівні каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів. -- `startupVerification`: режим автоматичного запиту на самоверифікацію під час запуску (`if-unverified`, `off`). +- `threadBindings`: перевизначення для каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів. +- `startupVerification`: режим автоматичного запиту самоверифікації під час запуску (`if-unverified`, `off`). - `startupVerificationCooldownHours`: cooldown перед повторною спробою автоматичних запитів верифікації під час запуску. -- `textChunkLimit`: розмір частини вихідного повідомлення. +- `textChunkLimit`: розмір chunk для вихідного повідомлення. - `chunkMode`: `length` або `newline`. - `responsePrefix`: необов’язковий префікс повідомлення для вихідних відповідей. - `ackReaction`: необов’язкове перевизначення ack reaction для цього каналу/облікового запису. - `ackReactionScope`: необов’язкове перевизначення області дії ack reaction (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: режим вхідних сповіщень про реакції (`own`, `off`). -- `mediaMaxMb`: обмеження розміру медіа в MB для обробки медіа Matrix. Воно застосовується до вихідних надсилань і обробки вхідних медіа. -- `autoJoin`: політика автоматичного приєднання за запрошенням (`always`, `allowlist`, `off`). За замовчуванням: `off`. Це застосовується до запрошень Matrix загалом, включно із запрошеннями у стилі DM, а не лише до запрошень у кімнати/групи. OpenClaw приймає це рішення на момент запрошення, перш ніж зможе надійно класифікувати приєднану кімнату як DM або групу. -- `autoJoinAllowlist`: кімнати/аліаси, дозволені, коли `autoJoin` має значення `allowlist`. Під час обробки запрошення записи аліасів розв’язуються до ID кімнат; OpenClaw не довіряє стану аліаса, заявленому запрошеною кімнатою. +- `mediaMaxMb`: обмеження розміру медіа в МБ для обробки медіа в Matrix. Застосовується до вихідних надсилань і обробки вхідних медіа. +- `autoJoin`: політика автоматичного приєднання до запрошень (`always`, `allowlist`, `off`). За замовчуванням: `off`. Це застосовується до запрошень Matrix загалом, включно із запрошеннями у стилі DM, а не лише до запрошень у кімнати/групи. OpenClaw ухвалює це рішення під час запрошення, до того як може надійно класифікувати приєднану кімнату як DM або групу. +- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `allowlist`. Записи з псевдонімами визначаються в ID кімнат під час обробки запрошення; OpenClaw не довіряє стану псевдоніма, заявленому запрошеною кімнатою. - `dm`: блок політики DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати й класифікував її як DM. Це не змінює того, чи буде запрошення автоматично прийнято. -- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо ви вже не розв’язали їх через живий пошук у каталозі. -- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната DM Matrix зберігала окремий контекст, навіть якщо співрозмовник той самий. +- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати й класифікував її як DM. Це не змінює того, чи буде запрошення автоматично прийняте. +- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо ви вже не визначили їх через живий пошук у каталозі. +- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната Matrix DM зберігала окремий контекст, навіть якщо співрозмовник той самий. - `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає верхньорівневе налаштування `threadReplies` як для розміщення відповідей, так і для ізоляції сесій у DM. - `execApprovals`: нативна доставка підтверджень exec у Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: Matrix user ID, яким дозволено підтверджувати запити exec. Необов’язково, якщо `dm.allowFrom` уже визначає тих, хто підтверджує. +- `execApprovals.approvers`: Matrix user ID, яким дозволено схвалювати запити exec. Необов’язкове, якщо `dm.allowFrom` уже визначає погоджувачів. - `execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). - `accounts`: іменовані перевизначення для кожного облікового запису. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів. -- `groups`: карта політик для кожної кімнати. Надавайте перевагу ID кімнат або аліасам; нерозв’язані назви кімнат під час виконання ігноруються. Ідентичність сесії/групи використовує стабільний room ID після розв’язання, тоді як зрозумілі людині мітки, як і раніше, беруться з назв кімнат. +- `groups`: карта політик для кімнат. Віддавайте перевагу ID кімнат або псевдонімам; нерозпізнані назви кімнат ігноруються під час runtime. Ідентичність сесії/групи після визначення використовує стабільний ID кімнати, тоді як людиночитані мітки й далі походять із назв кімнат. - `groups..account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами. -- `groups..allowBots`: перевизначення на рівні кімнати для відправників-налаштованих-ботів (`true` або `"mentions"`). +- `groups..allowBots`: перевизначення на рівні кімнати для відправників із налаштованих ботів (`true` або `"mentions"`). - `groups..users`: allowlist відправників для конкретної кімнати. -- `groups..tools`: перевизначення allow/deny для інструментів на рівні кімнати. -- `groups..autoReply`: перевизначення вимоги згадок на рівні кімнати. `true` вимикає вимоги згадок для цієї кімнати; `false` знову примусово вмикає їх. +- `groups..tools`: перевизначення allow/deny інструментів для конкретної кімнати. +- `groups..autoReply`: перевизначення вимоги згадування на рівні кімнати. `true` вимикає вимоги до згадування для цієї кімнати; `false` примусово вмикає їх знову. - `groups..skills`: необов’язковий фільтр Skills на рівні кімнати. -- `groups..systemPrompt`: необов’язковий фрагмент системного prompt на рівні кімнати. -- `rooms`: застарілий аліас для `groups`. -- `actions`: контроль доступу до інструментів для кожної дії (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `groups..systemPrompt`: необов’язковий фрагмент system prompt на рівні кімнати. +- `rooms`: застарілий псевдонім для `groups`. +- `actions`: контроль доступу до інструментів для окремих дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Пов’язане - [Channels Overview](/uk/channels) — усі підтримувані канали -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Groups](/uk/channels/groups) — поведінка групового чату та обмеження за згадками +- [Pairing](/uk/channels/pairing) — автентифікація DM і сценарій pairing +- [Groups](/uk/channels/groups) — поведінка групового чату та вимога згадування - [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Security](/uk/gateway/security) — модель доступу та зміцнення безпеки +- [Security](/uk/gateway/security) — модель доступу та посилення безпеки diff --git a/docs/uk/channels/whatsapp.md b/docs/uk/channels/whatsapp.md index 2e94ccfe7..ad674937c 100644 --- a/docs/uk/channels/whatsapp.md +++ b/docs/uk/channels/whatsapp.md @@ -1,44 +1,44 @@ --- read_when: - - Працюєте над поведінкою каналу WhatsApp/web або маршрутизацією вхідних повідомлень -summary: Підтримка каналу WhatsApp, контроль доступу, поведінка доставки та операційні аспекти + - Робота над поведінкою каналу WhatsApp/web або маршрутизацією вхідних повідомлень +summary: Підтримка каналу WhatsApp, контроль доступу, поведінка доставки та операції title: WhatsApp x-i18n: - generated_at: "2026-04-05T18:00:12Z" + generated_at: "2026-04-06T15:28:11Z" model: gpt-5.4 provider: openai - source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49 + source_hash: 9e2ce84d869ace6c0bebd9ec17bdbbef997a5c31e5da410b02a19a0f103f7359 source_path: channels/whatsapp.md workflow: 15 --- -# WhatsApp (Web channel) +# WhatsApp (Web-канал) -Статус: готовий до використання у production через WhatsApp Web (Baileys). Gateway керує прив’язаними сесіями. +Статус: готовий до production через WhatsApp Web (Baileys). Gateway керує прив’язаними сесіями. ## Встановлення (за потреби) -- Під час onboarding (`openclaw onboard`) і `openclaw channels add --channel whatsapp` - з’являється запит на встановлення плагіна WhatsApp, коли ви вперше вибираєте цей канал. +- Онбординг (`openclaw onboard`) і `openclaw channels add --channel whatsapp` + пропонують установити плагін WhatsApp, коли ви вперше вибираєте його. - `openclaw channels login --channel whatsapp` також пропонує процес встановлення, якщо - плагін ще не встановлено. -- Dev channel + git checkout: типово використовується локальний шлях до плагіна. -- Stable/Beta: типово використовується npm-пакет `@openclaw/whatsapp`. + плагін ще не присутній. +- Канал розробки + git checkout: за замовчуванням використовується локальний шлях до плагіна. +- Stable/Beta: за замовчуванням використовується npm-пакет `@openclaw/whatsapp`. -Ручне встановлення також доступне: +Ручне встановлення також залишається доступним: ```bash openclaw plugins install @openclaw/whatsapp ``` - - Типова політика DM для невідомих відправників — pairing. + + Стандартна політика DM — прив’язка для невідомих відправників. - - Кросканальна діагностика та сценарії відновлення. + + Міжканальна діагностика та сценарії відновлення. - + Повні шаблони та приклади конфігурації каналу. @@ -85,30 +85,30 @@ openclaw gateway - + ```bash openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - Термін дії запитів на pairing спливає через 1 годину. Для кожного каналу може бути не більше 3 незавершених запитів. + Запити на прив’язку спливають через 1 годину. Кількість запитів у стані очікування обмежена до 3 на канал. -OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовано для такого варіанта, але конфігурації з особистим номером також підтримуються.) +OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але конфігурації з особистим номером також підтримуються.) -## Сценарії розгортання +## Схеми розгортання - Це найзручніший операційний режим: + Це найчистіший операційний режим: - окрема ідентичність WhatsApp для OpenClaw - - чіткіші allowlist для DM та межі маршрутизації + - чіткіші allowlist-и DM та межі маршрутизації - менша ймовірність плутанини з чатом із самим собою Мінімальний шаблон політики: @@ -127,31 +127,32 @@ OpenClaw рекомендує за можливості запускати Whats - Onboarding підтримує режим особистого номера і записує базову конфігурацію, зручну для чату із самим собою: + Онбординг підтримує режим особистого номера та записує базову конфігурацію, дружню до чату із самим собою: - `dmPolicy: "allowlist"` - `allowFrom` містить ваш особистий номер - `selfChatMode: true` - Під час runtime захист чату із самим собою спирається на прив’язаний власний номер і `allowFrom`. + Під час виконання захист для чату із самим собою спирається на прив’язаний власний номер і `allowFrom`. - Канал платформи обміну повідомленнями у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`). + Канал платформи обміну повідомленнями у поточній архітектурі каналів OpenClaw побудований на WhatsApp Web (`Baileys`). - У вбудованому реєстрі чат-каналів немає окремого каналу повідомлень Twilio WhatsApp. + Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі чат-каналів немає. -## Модель runtime +## Модель виконання -- Gateway керує сокетом WhatsApp і циклом повторного підключення. -- Вихідні надсилання потребують активного listener WhatsApp для цільового облікового запису. -- Чати status і broadcast ігноруються (`@status`, `@broadcast`). -- Прямі чати використовують правила DM-сесій (`session.dmScope`; типове значення `main` зводить DM до основної сесії агента). +- Gateway керує сокетом WhatsApp і циклом перепідключення. +- Надсилання назовні вимагає активного слухача WhatsApp для цільового облікового запису. +- Чати статусів і розсилок ігноруються (`@status`, `@broadcast`). +- Прямі чати використовують правила сесій DM (`session.dmScope`; значення за замовчуванням `main` зводить DM до основної сесії агента). - Групові сесії ізольовані (`agent::whatsapp:group:`). +- Транспорт WhatsApp Web дотримується стандартних змінних середовища проксі на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста, а не специфічним налаштуванням проксі WhatsApp для каналу. ## Контроль доступу та активація @@ -159,52 +160,52 @@ OpenClaw рекомендує за можливості запускати Whats `channels.whatsapp.dmPolicy` керує доступом до прямих чатів: - - `pairing` (типово) + - `pairing` (за замовчуванням) - `allowlist` - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` - `allowFrom` приймає номери у форматі E.164 (внутрішньо нормалізуються). + `allowFrom` приймає номери у стилі E.164 (внутрішньо нормалізуються). Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над значеннями канального рівня для цього облікового запису. - Подробиці поведінки runtime: + Деталі поведінки під час виконання: - - pairings зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom` - - якщо allowlist не налаштовано, типово дозволяється прив’язаний власний номер - - вихідні DM `fromMe` ніколи не проходять auto-paired + - прив’язки зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom` + - якщо allowlist не налаштовано, прив’язаний власний номер дозволяється за замовчуванням + - вихідні `fromMe` DM ніколи не прив’язуються автоматично - + Доступ до груп має два рівні: 1. **Allowlist членства в групі** (`channels.whatsapp.groups`) - - якщо `groups` не вказано, усі групи є допустимими - - якщо `groups` присутній, він діє як group allowlist (дозволено `"*"`) + - якщо `groups` пропущено, усі групи є допустимими + - якщо `groups` присутній, він діє як allowlist груп (`"*"` дозволено) 2. **Політика відправників у групі** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) - - `open`: allowlist відправників оминається + - `open`: allowlist відправників обходиться - `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`) - - `disabled`: блокувати весь вхідний груповий трафік + - `disabled`: блокувати всі вхідні групові повідомлення - Резервна логіка allowlist відправників: + Резервна логіка allowlist-а відправників: - - якщо `groupAllowFrom` не задано, runtime резервно використовує `allowFrom`, коли воно доступне - - allowlist відправників оцінюються перед активацією згадкою/відповіддю + - якщо `groupAllowFrom` не задано, під час виконання використовується `allowFrom`, якщо він доступний + - allowlist-и відправників перевіряються перед активацією за згадкою/відповіддю - Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика runtime має значення `allowlist` (із попередженням у логах), навіть якщо задано `channels.defaults.groupPolicy`. + Примітка: якщо блоку `channels.whatsapp` взагалі не існує, резервна групова політика під час виконання — `allowlist` (із попередженням у журналі), навіть якщо задано `channels.defaults.groupPolicy`. - У групах відповіді типово вимагають згадки. + Для відповідей у групі за замовчуванням потрібна згадка. - Виявлення згадок включає: + Виявлення згадки включає: - - явні згадки WhatsApp ідентичності бота - - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) - - неявне виявлення reply-to-bot (відправник відповіді збігається з ідентичністю бота) + - явні згадки ідентичності бота у WhatsApp + - налаштовані шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) + - неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота) Примітка щодо безпеки: @@ -216,39 +217,39 @@ OpenClaw рекомендує за можливості запускати Whats - `/activation mention` - `/activation always` - `activation` оновлює стан сесії (а не глобальну конфігурацію). Доступ до неї обмежений власником. + `activation` оновлює стан сесії (а не глобальну конфігурацію). Доступ до нього обмежений власником. ## Поведінка особистого номера та чату із самим собою -Коли прив’язаний власний номер також присутній у `allowFrom`, активуються запобіжники для чату із самим собою в WhatsApp: +Коли прив’язаний власний номер також присутній у `allowFrom`, активується захист WhatsApp для чату із самим собою: -- пропускати read receipts для ходів self-chat -- ігнорувати поведінку auto-trigger за mention-JID, яка інакше пінгувала б вас самих -- якщо `messages.responsePrefix` не задано, відповіді self-chat типово використовують `[{identity.name}]` або `[openclaw]` +- пропускати підтвердження прочитання для ходів у чаті із самим собою +- ігнорувати поведінку автозапуску за JID-згадкою, яка інакше пінгувала б вас самих +- якщо `messages.responsePrefix` не задано, відповіді в чаті із самим собою за замовчуванням мають формат `[{identity.name}]` або `[openclaw]` ## Нормалізація повідомлень і контекст - - Вхідні повідомлення WhatsApp обгортаються в спільну inbound envelope. + + Вхідні повідомлення WhatsApp загортаються у спільний вхідний конверт. - Якщо існує цитована відповідь, контекст додається в такому вигляді: + Якщо існує цитована відповідь, контекст додається в такому форматі: ```text - [Replying to id:] + [Відповідь на id:] - [/Replying] + [/Відповідь] ``` - Метадані відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164). + Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника). - - Вхідні повідомлення лише з медіа нормалізуються за допомогою заповнювачів, наприклад: + + Вхідні повідомлення, що містять лише медіа, нормалізуються із заповнювачами, такими як: - `` - `` @@ -256,29 +257,29 @@ OpenClaw рекомендує за можливості запускати Whats - `` - `` - Дані location і contact нормалізуються в текстовий контекст перед маршрутизацією. + Дані геолокації та контактів нормалізуються в текстовий контекст перед маршрутизацією. - - Для груп необроблені повідомлення можуть буферизуватися й додаватися як контекст, коли бот нарешті активується. + + Для груп необроблені повідомлення можуть буферизуватися і вставлятися як контекст, коли бот нарешті активується. - - типове обмеження: `50` + - ліміт за замовчуванням: `50` - конфігурація: `channels.whatsapp.historyLimit` - резервне значення: `messages.groupChat.historyLimit` - `0` вимикає - Маркери додавання: + Маркери вставки: - - `[Chat messages since your last reply - for context]` - - `[Current message - respond to this]` + - `[Повідомлення чату з часу вашої останньої відповіді — для контексту]` + - `[Поточне повідомлення — відповідайте на нього]` - - Read receipts типово ввімкнені для прийнятих вхідних повідомлень WhatsApp. + + Підтвердження прочитання ввімкнені за замовчуванням для прийнятих вхідних повідомлень WhatsApp. - Вимкнення глобально: + Вимкнути глобально: ```json5 { @@ -290,7 +291,7 @@ OpenClaw рекомендує за можливості запускати Whats } ``` - Перевизначення для окремого облікового запису: + Перевизначення для кожного облікового запису: ```json5 { @@ -306,7 +307,7 @@ OpenClaw рекомендує за можливості запускати Whats } ``` - Для self-chat read receipts пропускаються, навіть якщо глобально ввімкнені. + Для ходів у чаті із самим собою підтвердження прочитання пропускаються, навіть якщо вони глобально ввімкнені. @@ -314,43 +315,43 @@ OpenClaw рекомендує за можливості запускати Whats ## Доставка, розбиття на частини та медіа - - - типове обмеження частини: `channels.whatsapp.textChunkLimit = 4000` + + - ліміт частини за замовчуванням: `channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім резервно використовує безпечне за довжиною розбиття + - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного за довжиною розбиття - - підтримуються image, video, audio (голосова PTT-нотатка) і payload document - - `audio/ogg` переписується в `audio/ogg; codecs=opus` для сумісності з голосовими нотатками - - анімоване відтворення GIF підтримується через `gifPlayback: true` під час надсилання video - - captions застосовуються до першого елемента медіа під час надсилання payload відповіді з кількома медіа + - підтримуються payload-и image, video, audio (голосове повідомлення PTT) і document + - `audio/ogg` переписується як `audio/ogg; codecs=opus` для сумісності з голосовими повідомленнями + - відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання video + - підписи застосовуються до першого елемента медіа під час надсилання payload-ів відповіді з кількома медіа - джерелом медіа може бути HTTP(S), `file://` або локальні шляхи - - обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) - - обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) - - для перевизначень окремих облікових записів використовується `channels.whatsapp.accounts..mediaMaxMb` - - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вкладатися в ліміти - - при збої надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість тихого відкидання відповіді + - обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`) + - обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`) + - перевизначення для кожного облікового запису використовують `channels.whatsapp.accounts..mediaMaxMb` + - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб відповідати обмеженням + - у разі помилки надсилання медіа резервна логіка для першого елемента надсилає текстове попередження замість тихого пропуску відповіді ## Рівень реакцій -`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції в WhatsApp: +`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp: -| Рівень | Ack reactions | Реакції, ініційовані агентом | Опис | -| ------------- | ------------- | ---------------------------- | ------------------------------------------------ | -| `"off"` | Ні | Ні | Жодних реакцій | -| `"ack"` | Так | Ні | Лише ack reactions (підтвердження до відповіді) | -| `"minimal"` | Так | Так (обмежено) | Ack + реакції агента з обережними вказівками | -| `"extensive"` | Так | Так (заохочуються) | Ack + реакції агента з активним заохоченням | +| Рівень | Реакції-підтвердження | Реакції, ініційовані агентом | Опис | +| ------------- | --------------------- | ---------------------------- | ------------------------------------------------ | +| `"off"` | Ні | Ні | Жодних реакцій | +| `"ack"` | Так | Ні | Лише реакції-підтвердження (отримання до відповіді) | +| `"minimal"` | Так | Так (консервативно) | Підтвердження + реакції агента з консервативними вказівками | +| `"extensive"` | Так | Так (заохочуються) | Підтвердження + реакції агента із заохочувальними вказівками | -Типове значення: `"minimal"`. +За замовчуванням: `"minimal"`. -Для перевизначень окремих облікових записів використовуйте `channels.whatsapp.accounts..reactionLevel`. +Перевизначення для кожного облікового запису використовують `channels.whatsapp.accounts..reactionLevel`. ```json5 { @@ -364,8 +365,8 @@ OpenClaw рекомендує за можливості запускати Whats ## Реакції-підтвердження -WhatsApp підтримує негайні ack reactions після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. -Ack reactions залежать від `reactionLevel` — вони пригнічуються, коли `reactionLevel` дорівнює `"off"`. +WhatsApp підтримує миттєві реакції-підтвердження при отриманні вхідного повідомлення через `channels.whatsapp.ackReaction`. +Реакції-підтвердження залежать від `reactionLevel` — вони пригнічуються, коли `reactionLevel` дорівнює `"off"`. ```json5 { @@ -384,46 +385,46 @@ Ack reactions залежать від `reactionLevel` — вони пригні Примітки щодо поведінки: - надсилаються одразу після прийняття вхідного повідомлення (до відповіді) -- збої логуються, але не блокують звичайну доставку відповіді -- у груповому режимі `mentions` реакція ставиться для ходів, активованих згадкою; групова активація `always` оминає цю перевірку -- WhatsApp використовує `channels.whatsapp.ackReaction` (застаріле `messages.ackReaction` тут не використовується) +- помилки логуються, але не блокують звичайну доставку відповіді +- у груповому режимі `mentions` реакція ставиться на ходах, активованих згадкою; групова активація `always` працює як обхід цієї перевірки +- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується) ## Кілька облікових записів і облікові дані - - - ID облікових записів беруться з `channels.whatsapp.accounts` - - типове вибирання облікового запису: `default`, якщо він є, інакше перший налаштований ID облікового запису (відсортований) - - ID облікових записів внутрішньо нормалізуються для пошуку + + - ідентифікатори облікових записів беруться з `channels.whatsapp.accounts` + - вибір облікового запису за замовчуванням: `default`, якщо присутній, інакше перший налаштований id облікового запису (відсортований) + - ідентифікатори облікових записів внутрішньо нормалізуються для пошуку - - - поточний шлях до auth: `~/.openclaw/credentials/whatsapp//creds.json` + + - поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp//creds.json` - резервний файл: `creds.json.bak` - - застаріла default auth у `~/.openclaw/credentials/` усе ще розпізнається/мігрує для сценаріїв з default account + - застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для сценаріїв з обліковим записом за замовчуванням - `openclaw channels logout --channel whatsapp [--account ]` очищає стан auth WhatsApp для цього облікового запису. + `openclaw channels logout --channel whatsapp [--account ]` очищає стан автентифікації WhatsApp для цього облікового запису. - У каталогах застарілої auth `oauth.json` зберігається, тоді як файли auth Baileys видаляються. + У застарілих каталогах автентифікації `oauth.json` зберігається, тоді як файли автентифікації Baileys видаляються. -## Інструменти, дії та записи конфігурації +## Інструменти, дії та запис конфігурації - Підтримка інструментів агента включає дію реакції WhatsApp (`react`). - Обмеження дій: - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- Записи конфігурації, ініційовані з каналу, типово ввімкнені (вимкнення через `channels.whatsapp.configWrites=false`). +- Запис конфігурації, ініційований каналом, увімкнений за замовчуванням (вимикається через `channels.whatsapp.configWrites=false`). ## Усунення проблем - Симптом: статус каналу повідомляє, що прив’язку не виконано. + Симптом: статус каналу повідомляє, що його не прив’язано. Виправлення: @@ -434,8 +435,8 @@ Ack reactions залежать від `reactionLevel` — вони пригні - - Симптом: прив’язаний обліковий запис із повторюваними відключеннями або спробами повторного підключення. + + Симптом: прив’язаний обліковий запис із повторними відключеннями або спробами перепідключення. Виправлення: @@ -444,14 +445,14 @@ Ack reactions залежать від `reactionLevel` — вони пригні openclaw logs --follow ``` - За потреби прив’яжіть заново через `channels login`. + За потреби повторно прив’яжіть через `channels login`. - - Вихідні надсилання швидко завершуються помилкою, якщо для цільового облікового запису немає активного listener gateway. + + Вихідні надсилання одразу завершуються помилкою, коли для цільового облікового запису не існує активного слухача gateway. - Переконайтеся, що gateway працює і обліковий запис прив’язано. + Переконайтеся, що gateway запущено і обліковий запис прив’язано. @@ -460,22 +461,22 @@ Ack reactions залежать від `reactionLevel` — вони пригні - `groupPolicy` - `groupAllowFrom` / `allowFrom` - - записи allowlist у `groups` - - вимогу згадки (`requireMention` + шаблони згадок) - - дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому залишайте лише один `groupPolicy` для кожної області + - записи allowlist-а `groups` + - обмеження за згадкою (`requireMention` + шаблони згадок) + - дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` для кожної області - - Runtime gateway WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram. + + Середовище виконання gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram. ## Вказівники на довідник конфігурації -Основний довідник: +Основне посилання: -- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp) +- [Довідник конфігурації - WhatsApp](/uk/gateway/configuration-reference#whatsapp) Важливі поля WhatsApp: @@ -487,9 +488,9 @@ Ack reactions залежать від `reactionLevel` — вони пригні ## Пов’язане -- [Підключення](/channels/pairing) -- [Групи](/channels/groups) -- [Безпека](/gateway/security) -- [Маршрутизація каналів](/channels/channel-routing) -- [Маршрутизація кількох агентів](/concepts/multi-agent) -- [Усунення проблем](/channels/troubleshooting) +- [Прив’язка](/uk/channels/pairing) +- [Групи](/uk/channels/groups) +- [Безпека](/uk/gateway/security) +- [Маршрутизація каналів](/uk/channels/channel-routing) +- [Маршрутизація кількох агентів](/uk/concepts/multi-agent) +- [Усунення проблем](/uk/channels/troubleshooting) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 06712c43a..650cbcc97 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -5,36 +5,36 @@ read_when: summary: Огляд постачальників моделей із прикладами конфігурацій і потоків CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-06T12:44:34Z" + generated_at: "2026-04-06T15:29:43Z" model: gpt-5.4 provider: openai - source_hash: ec33cbfeec86c3f79ea0ec38932eebb819eba5932024b73fcf3acbc41fbce203 + source_hash: a9c1f7f8cf09b6047a64189f7440811aafc93d01335f76969afd387cc54c7ab5 source_path: concepts/model-providers.md workflow: 15 --- # Постачальники моделей -На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). -Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). +Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). +Правила вибору моделей дивіться в [/concepts/models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених моделей. +- Якщо ви задасте `agents.defaults.models`, це стане allowlist. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Правила резервного перемикання під час виконання, проби періоду охолодження та збереження перевизначень сесії - задокументовані в [/concepts/model-failover](/uk/concepts/model-failover). +- Правила резервного переходу під час виконання, перевірки під час cooldown і збереження перевизначень сесії + задокументовано в [/concepts/model-failover](/uk/concepts/model-failover). - `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання. - Плагіни постачальників можуть додавати каталоги моделей через `registerProvider({ catalog })`; OpenClaw об'єднує цей вивід у `models.providers` перед записом `models.json`. -- Маніфести постачальників можуть оголошувати `providerAuthEnvVars`, щоб загальним перевіркам - автентифікації на основі змінних середовища не потрібно було завантажувати середовище виконання плагіна. Решта мапи змінних середовища ядра - тепер використовується лише для не-плагінних/вбудованих постачальників і кількох випадків - загального пріоритету, як-от онбординг Anthropic із пріоритетом API-ключа. -- Плагіни постачальників також можуть володіти логікою виконання постачальника через +- Маніфести постачальників можуть оголошувати `providerAuthEnvVars`, щоб + загальним перевіркам автентифікації на основі змінних середовища не потрібно було завантажувати runtime плагіна. Решта мапи змінних середовища в core + тепер використовується лише для неплагінних/core постачальників і кількох випадків + загального пріоритету, наприклад онбордингу Anthropic із пріоритетом API-ключа. +- Плагіни постачальників також можуть володіти поведінкою runtime постачальника через `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -50,179 +50,175 @@ x-i18n: `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and + `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, і `onModelSelected`. -- Примітка: `capabilities` середовища виконання постачальника — це спільні метадані виконавця (сімейство постачальника, - особливості транскрипту/інструментів, підказки щодо транспорту/кешу). Це не - те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), +- Примітка: runtime `capabilities` постачальника — це спільні метадані раннера (сімейство постачальника, + особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє плагін (текстовий inference, мовлення тощо). -## Поведінка постачальника, що належить плагіну +## Поведінка постачальника, якою володіє плагін -Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає +Тепер плагіни постачальників можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає загальний цикл inference. -Типовий розподіл: +Типовий поділ: -- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу - для `openclaw onboard`, `openclaw models auth` і безголового налаштування +- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками + онбордингу/входу для `openclaw onboard`, `openclaw models auth` і headless налаштування - `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації, - застарілими псевдонімами, підказками для списку дозволених моделей під час онбордингу та записами налаштування у вибірниках онбордингу/моделей + застарілими псевдонімами, підказками allowlist для онбордингу та записами налаштування в пікерах онбордингу/моделей - `catalog`: постачальник з'являється в `models.providers` -- `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед +- `normalizeModelId`: постачальник нормалізує застарілі/preview id моделей перед пошуком або канонізацією -- `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту +- `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства transport перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника, - потім інші плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить - транспорт + потім інші плагіни постачальників із підтримкою hook, доки один із них справді не змінить + transport - `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед - використанням під час виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші - плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить конфігурацію. Якщо жоден - хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно - нормалізують підтримувані записи постачальників Google. -- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності нативного обліку використання потокового режиму для постачальників конфігурації, зумовлені кінцевою точкою -- `resolveConfigApiKey`: постачальник визначає автентифікацію маркера середовища для постачальників конфігурації - без примусового повного завантаження автентифікації під час виконання. `amazon-bedrock` тут також має - вбудований резолвер маркерів середовища AWS, хоча автентифікація Bedrock під час виконання використовує - ланцюжок за замовчуванням AWS SDK. -- `resolveSyntheticAuth`: постачальник може показувати доступність локальної/self-hosted або іншої - автентифікації на основі конфігурації без збереження відкритих секретів -- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні профілі- - заповнювачі як такі, що мають нижчий пріоритет, ніж автентифікація на основі env/config -- `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному + її використанням у runtime; OpenClaw спочатку перевіряє відповідного постачальника, потім інші + плагіни постачальників із підтримкою hook, доки один із них справді не змінить конфігурацію. Якщо жоден + hook постачальника не перепише конфігурацію, вбудовані допоміжні засоби сімейства Google + усе одно нормалізують підтримувані записи постачальників Google. +- `applyNativeStreamingUsageCompat`: постачальник застосовує сумісні переписування usage нативного streaming на основі endpoint для конфігурованих постачальників +- `resolveConfigApiKey`: постачальник визначає автентифікацію через маркер змінної середовища для конфігурованих постачальників + без примусового завантаження повної runtime-автентифікації. `amazon-bedrock` також має + тут вбудований резолвер маркерів змінних середовища AWS, хоча runtime-автентифікація Bedrock використовує + стандартний ланцюжок AWS SDK. +- `resolveSyntheticAuth`: постачальник може повідомляти про доступність локальної/self-hosted або іншої + автентифікації на основі конфігурації без збереження секретів у відкритому вигляді +- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені synthetic profile + placeholders як менш пріоритетні, ніж автентифікація на основі env/config +- `resolveDynamicModel`: постачальник приймає id моделей, яких ще немає в локальному статичному каталозі -- `prepareDynamicModel`: постачальнику потрібно оновити метадані перед повторною спробою - динамічного визначення -- `normalizeResolvedModel`: постачальнику потрібно переписати транспорт або базову URL-адресу +- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою + динамічного визначення моделі +- `normalizeResolvedModel`: постачальнику потрібні переписування transport або базового URL - `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх - моделей постачальника, навіть коли вони надходять через інший сумісний транспорт -- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальників -- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як їх побачить - вбудований виконавець -- `inspectToolSchemas`: постачальник показує специфічні для транспорту попередження схеми + моделей постачальника, навіть коли вони надходять через інший сумісний transport +- `capabilities`: постачальник публікує особливості transcript/tooling/provider-family +- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як вбудований + раннер їх побачить +- `inspectToolSchemas`: постачальник показує попередження про схеми, специфічні для transport, після нормалізації -- `resolveReasoningOutputMode`: постачальник вибирає нативні чи теговані +- `resolveReasoningOutputMode`: постачальник обирає нативні чи позначені тегами контракти виводу reasoning -- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для окремих моделей -- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю - кастомним транспортом -- `wrapStreamFn`: постачальник застосовує обгортки сумісності запиту заголовків/тіла/моделі -- `resolveTransportTurnState`: постачальник надає нативні заголовки транспорту - або метадані для кожного ходу -- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket - або політику охолодження сесії -- `createEmbeddingProvider`: постачальник володіє логікою embedding для пам'яті, коли вона - належить плагіну постачальника, а не центральному перемикачу embedding у ядрі -- `formatApiKey`: постачальник форматує збережені профілі автентифікації у - рядок `apiKey`, який очікує транспорт під час виконання -- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних - оновлювачів `pi-ai` недостатньо -- `buildAuthDoctorHint`: постачальник додає вказівки з відновлення, коли оновлення OAuth +- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі +- `createStreamFn`: постачальник замінює звичайний шлях stream повністю + власним transport +- `wrapStreamFn`: постачальник застосовує обгортки сумісності до заголовків/тіла/моделі запиту +- `resolveTransportTurnState`: постачальник надає нативні заголовки transport або метадані + для кожного ходу +- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки WebSocket-сеансу + або політику cooldown сеансу +- `createEmbeddingProvider`: постачальник володіє поведінкою embedding для пам'яті, коли вона + належить плагіну постачальника, а не комутатору embedding у core +- `formatApiKey`: постачальник форматує збережені профілі автентифікації у runtime-рядок + `apiKey`, якого очікує transport +- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних засобів оновлення `pi-ai` + недостатньо +- `buildAuthDoctorHint`: постачальник додає рекомендації щодо виправлення, коли оновлення OAuth не вдається - `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника - помилки переповнення вікна контексту, які загальні евристики можуть пропустити -- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки транспорту/API - з причинами резервного перемикання, як-от ліміт запитів або перевантаження -- `isCacheTtlEligible`: постачальник визначає, які ідентифікатори моделей вище за потоком підтримують TTL кешу підказок + помилки переповнення context window, які загальні евристики не помітять +- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки transport/API + з причинами резервного переходу, такими як ліміт швидкості або перевантаження +- `isCacheTtlEligible`: постачальник визначає, які id моделей вище за потоком підтримують prompt-cache TTL - `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації на специфічну для постачальника підказку з відновлення -- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки й може повертати - помилку, що належить постачальнику, для прямих збоїв визначення -- `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після +- `suppressBuiltInModel`: постачальник приховує застарілі рядки вище за потоком і може повертати + помилку постачальника для прямих збоїв визначення +- `augmentModelCatalog`: постачальник додає synthetic/final рядки каталогу після виявлення та об'єднання конфігурації -- `isBinaryThinking`: постачальник володіє UX двійкового thinking увімк./вимк. -- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей +- `isBinaryThinking`: постачальник володіє UX двійкового вмикання/вимикання thinking +- `supportsXHighThinking`: постачальник додає вибраним моделям підтримку `xhigh` - `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для сімейства моделей -- `applyConfigDefaults`: постачальник застосовує глобальні значення за замовчуванням, специфічні для постачальника, - під час матеріалізації конфігурації залежно від режиму автентифікації, середовища чи сімейства моделей -- `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke -- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий - токен для виконання -- `resolveUsageAuth`: постачальник визначає облікові дані використання/квоти для `/usage` - та пов'язаних поверхонь статусу/звітності -- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором кінцевої точки використання, тоді як - ядро все ще володіє оболонкою підсумку та форматуванням -- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, як-от - телеметрію або облік сесії, що належить постачальнику +- `applyConfigDefaults`: постачальник застосовує глобальні типові значення, специфічні для постачальника, + під час матеріалізації конфігурації залежно від режиму автентифікації, env або сімейства моделей +- `isModernModelRef`: постачальник володіє зіставленням бажаних live/smoke моделей +- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткочасний + runtime-токен +- `resolveUsageAuth`: постачальник визначає облікові дані для usage/quota для `/usage` + і пов'язаних поверхонь статусу/звітності +- `fetchUsageSnapshot`: постачальник володіє отриманням/парсингом endpoint usage, тоді як + core усе ще володіє оболонкою підсумку та форматуванням +- `onModelSelected`: постачальник запускає побічні ефекти після вибору моделі, як-от + телеметрія або ведення сеансу, яким володіє постачальник Поточні вбудовані приклади: -- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання даних - з кінцевої точки використання, метадані TTL кешу/сімейства постачальника та глобальні - значення конфігурації за замовчуванням з урахуванням автентифікації -- `amazon-bedrock`: специфічне для постачальника зіставлення переповнення контексту та - класифікація причин резервного перемикання для помилок Bedrock throttle/not-ready, а також - спільне сімейство відтворення `anthropic-by-model` для захистів політики повтору лише Claude - на трафіку Anthropic -- `anthropic-vertex`: захисти політики повтору лише Claude на Anthropic-message +- `anthropic`: резервний механізм прямої сумісності вперед для Claude 4.6, підказки з ремонту автентифікації, отримання + endpoint usage, метадані cache-TTL/provider-family та глобальні + типові значення конфігурації, що враховують автентифікацію +- `amazon-bedrock`: визначення переповнення контексту та класифікація + причин резервного переходу для специфічних для Bedrock помилок throttle/not-ready, а також + спільне сімейство повторного відтворення `anthropic-by-model` для захистів політики повторного відтворення лише для Claude + у трафіку Anthropic +- `anthropic-vertex`: захисти політики повторного відтворення лише для Claude в Anthropic-message трафіку -- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника, - санітизація підпису thought у Gemini-трафіку через проксі, ін'єкція reasoning через проксі - через сімейство потоків `openrouter-thinking`, пересилання метаданих маршрутизації - та політика TTL кешу -- `github-copilot`: онбординг/вхід через пристрій, резервна сумісність уперед моделей, - підказки транскрипту Claude-thinking, обмін токенів під час виконання та отримання даних - з кінцевої точки використання -- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI, - підказки про відсутню автентифікацію з урахуванням Codex, приглушення Spark, синтетичні - рядки каталогу OpenAI/Codex, політика thinking/live-моделей, нормалізація псевдонімів токенів використання - (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків - `openai-responses-defaults` для нативних обгорток OpenAI/Codex, - метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень - для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео +- `openrouter`: наскрізні id моделей, обгортки запитів, підказки capability постачальника, + очищення підпису думок Gemini у проксійованому трафіку Gemini, + ін'єкція reasoning проксі через сімейство stream `openrouter-thinking`, + пересилання метаданих маршрутизації та політика cache-TTL +- `github-copilot`: онбординг/вхід із пристрою, резервний механізм сумісності вперед для моделей, + підказки transcript thinking для Claude, обмін runtime-токенів і отримання endpoint + usage +- `openai`: резервний механізм сумісності вперед для GPT-5.4, пряма нормалізація + transport OpenAI, підказки про відсутню автентифікацію з урахуванням Codex, приглушення Spark, synthetic + рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів токенів usage + (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство stream `openai-responses-defaults` + для нативних обгорток OpenAI/Codex, метадані сімейства постачальника, вбудована реєстрація постачальника генерації зображень + для `gpt-image-1` і вбудована реєстрація постачальника генерації відео для `sora-2` -- `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1, - нативна валідація повтору Gemini, санітизація bootstrap-повтору, тегований - режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника - генерації зображень для preview-моделей Gemini image та вбудована +- `google` і `google-gemini-cli`: резервний механізм сумісності вперед для Gemini 3.1, + нативна перевірка повторного відтворення Gemini, очищення bootstrap replay, позначений тегами + режим виводу reasoning, зіставлення сучасних моделей, вбудована реєстрація постачальника генерації зображень + для preview-моделей Gemini image і вбудована реєстрація постачальника генерації відео для моделей Veo; Gemini CLI OAuth також - володіє форматуванням токенів профілю автентифікації, розбором токенів використання та - отриманням кінцевої точки квоти для поверхонь використання -- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну -- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, payload reasoning - нормалізація, санітизація підпису thought у проксі-Gemini та політика TTL кешу -- `zai`: резервна сумісність уперед для GLM-5, типові значення `tool_stream`, політика TTL кешу, - політика двійкового thinking/live-моделей і автентифікація використання + отримання квоти; - невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` -- `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для - швидких варіантів Grok, типове `tool_stream`, очищення схем інструментів / - payload reasoning, специфічне для xAI, і вбудована реєстрація постачальника генерації відео + володіє форматуванням токенів профілю автентифікації, парсингом токенів usage та отриманням endpoint квот + для поверхонь usage +- `moonshot`: спільний transport, нормалізація payload thinking, якою володіє плагін +- `kilocode`: спільний transport, заголовки запитів, якими володіє плагін, нормалізація payload reasoning, + очищення підпису думок проксійованого Gemini та політика cache-TTL +- `zai`: резервний механізм сумісності вперед для GLM-5, типові значення `tool_stream`, політика cache-TTL, + політика binary-thinking/live-model і автентифікація usage + отримання квот; + невідомі id `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` +- `xai`: нативна нормалізація transport Responses, переписування псевдонімів `/fast` для + швидких варіантів Grok, типове `tool_stream`, специфічне для xAI очищення схем інструментів / + payload reasoning і вбудована реєстрація постачальника генерації відео для `grok-imagine-video` -- `mistral`: метадані можливостей, що належать плагіну -- `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс - санітизація підпису thought у проксі-Gemini -- `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan - як-от `alibaba/wan2.6-t2v` -- `byteplus`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео +- `mistral`: метадані capability, якими володіє плагін +- `opencode` і `opencode-go`: метадані capability, якими володіє плагін, плюс + очищення підпису думок проксійованого Gemini +- `alibaba`: каталог генерації відео, яким володіє плагін, для прямих посилань на моделі Wan + на кшталт `alibaba/wan2.6-t2v` +- `byteplus`: каталоги, якими володіє плагін, плюс вбудована реєстрація постачальника генерації відео для моделей Seedance text-to-video/image-to-video -- `fal`: вбудована реєстрація постачальника генерації відео для хостованих сторонніх - моделей, реєстрація постачальника генерації зображень для моделей зображень FLUX, а також вбудована - реєстрація постачальника генерації відео для хостованих сторонніх відеомоделей +- `fal`: вбудована реєстрація постачальника генерації відео для розміщеного стороннього + постачальника генерації зображень для моделей FLUX image плюс вбудована + реєстрація постачальника генерації відео для розміщених сторонніх моделей відео - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`: - лише каталоги, що належать плагіну -- `qwen`: каталоги, що належать плагіну, для текстових моделей плюс спільні + лише каталоги, якими володіє плагін +- `qwen`: каталоги, якими володіє плагін, для текстових моделей плюс спільні реєстрації постачальників media-understanding і генерації відео для його - мультимодальних поверхонь; генерація відео Qwen використовує стандартні відео- - кінцеві точки DashScope з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` -- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних - моделей Runway на основі завдань, як-от `gen4.5` -- `minimax`: каталоги, що належать плагіну, вбудована реєстрація постачальника генерації відео + мультимодальних поверхонь; генерація відео Qwen використовує стандартні endpoint відео DashScope + з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` +- `runway`: реєстрація постачальника генерації відео, якою володіє плагін, для нативних моделей + на основі задач Runway, таких як `gen4.5` +- `minimax`: каталоги, якими володіє плагін, вбудована реєстрація постачальника генерації відео для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень - для `image-01`, гібридний вибір політики повтору Anthropic/OpenAI та логіка - автентифікації/знімка використання -- `together`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео + для `image-01`, гібридний вибір політики повторного відтворення Anthropic/OpenAI + і логіка автентифікації usage/знімка +- `together`: каталоги, якими володіє плагін, плюс вбудована реєстрація постачальника генерації відео для відеомоделей Wan -- `xiaomi`: каталоги, що належать плагіну, плюс логіка - автентифікації/знімка використання +- `xiaomi`: каталоги, якими володіє плагін, плюс логіка автентифікації usage/знімка -Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальника: `openai` і +Вбудований плагін `openai` тепер володіє обома id постачальників: `openai` і `openai-codex`. -Це охоплює постачальників, які ще вписуються в звичайні транспорти OpenClaw. Постачальник, -якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня -розширення. +Це охоплює постачальників, які все ще відповідають звичайним transport OpenClaw. Постачальник, +якому потрібен повністю власний виконавець запитів, — це окрема, глибша поверхня розширення. ## Ротація API-ключів @@ -232,19 +228,19 @@ x-i18n: - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант. -- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на відповіді з обмеженням швидкості (наприклад, - `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Для постачальників Google також включено `GOOGLE_API_KEY` як резервний варіант. +- Порядок вибору ключів зберігає пріоритет і видаляє дублікати значень. +- Запити повторюються з наступним ключем лише у відповідь на повідомлення про ліміт швидкості (for + example `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Збої, не пов'язані з лімітом запитів, завершуються негайно; ротація ключів не виконується. -- Коли всі можливі ключі не спрацьовують, повертається фінальна помилка з останньої спроби. + `workers_ai ... quota limit exceeded` або періодичні повідомлення про обмеження usage). +- Збої, не пов'язані з лімітом швидкості, завершуються негайно; ротація ключів не виконується. +- Коли всі кандидати на ключі не спрацьовують, повертається остання помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** -конфігурація `models.providers`; достатньо налаштувати автентифікацію й вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не** +потрібна конфігурація `models.providers`; просто задайте автентифікацію й виберіть модель. ### OpenAI @@ -253,18 +249,18 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) +- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Розігрів WebSocket для OpenAI Responses типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`) +- Прогрівання WebSocket OpenAI Responses типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses із `service_tier=priority` на `api.openai.com` +- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com` - Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не - до загальних проксі, сумісних з OpenAI -- Нативні маршрути OpenAI також зберігають `store` для Responses, підказки кешу промптів і - формування payload сумісності reasoning OpenAI; проксі-маршрути — ні -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex + до загальних OpenAI-сумісних проксі +- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і + формування payload сумісності reasoning OpenAI; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark розглядається як лише Codex ```json5 { @@ -279,9 +275,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік, автентифікований через API-ключ і OAuth, надісланий до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка щодо білінгу: для Anthropic в OpenClaw практичний поділ — це **API-ключ** або **підписка Claude з Extra Usage**. Anthropic повідомила користувачів OpenClaw **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що шлях входу Claude у **OpenClaw** вважається використанням через сторонній harness і потребує **Extra Usage**, що оплачується окремо від підписки. Наші локальні відтворення також показують, що рядок промпту, який ідентифікує OpenClaw, не відтворюється на шляху Anthropic SDK + API-ключ. -- Токен налаштування Anthropic знову доступний як застарілий/ручний шлях OpenClaw. Використовуйте його з розумінням, що Anthropic повідомила користувачів OpenClaw, що цей шлях потребує **Extra Usage**. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим через API-ключ і OAuth, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Setup-token Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але OpenClaw тепер надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. ```json5 { @@ -295,16 +291,16 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Автентифікація: OAuth (ChatGPT) - Приклад моделі: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) +- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) - `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на - `chatgpt.com/backend-api`, а не до загальних проксі, сумісних з OpenAI -- Має спільний перемикач `/fast` і конфігурацію `params.fastMode`, як і прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від прав доступу -- `openai-codex/gpt-5.4` зберігає нативне `contextWindow = 1050000` і типове обмеження під час виконання `contextTokens = 272000`; перевизначте це обмеження через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/робочих процесів, як-от OpenClaw. + `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі +- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від entitlement +- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типове runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. ```json5 { @@ -324,17 +320,17 @@ OpenClaw постачається з каталогом pi‑ai. Для цих } ``` -### Інші хостовані варіанти у стилі підписки +### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення кінцевих точок Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan -- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні кінцеві точки API +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): доступ через MiniMax Coding Plan OAuth або API-ключ +- [GLM Models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API ### OpenCode - Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Постачальник виконання Zen: `opencode` -- Постачальник виконання Go: `opencode-go` +- Постачальник runtime Zen: `opencode` +- Постачальник runtime Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -353,26 +349,26 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для пересилання нативного для постачальника - дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` + (або застаріле `cached_content`) для пересилання нативного для постачальника + дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` -- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI — власний потік OAuth -- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і, якщо вирішите продовжити, використовуйте некритичний обліковий запис. +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth +- Застереження: Gemini CLI OAuth у OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. - Gemini CLI OAuth постачається як частина вбудованого плагіна `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - - Увімкнення: `openclaw plugins enable google` - - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` + - Увімкніть: `openclaw plugins enable google` + - Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - Типова модель: `google-gemini-cli/gemini-3.1-pro-preview` - - Примітка: вам **не потрібно** вставляти client id або secret в `openclaw.json`. Потік входу CLI зберігає - токени в профілях автентифікації на gateway host. - - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host. - - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з - `stats`, при цьому `stats.cached` нормалізується в OpenClaw `cacheRead`. + - Примітка: ви **не** вставляєте client id або secret у `openclaw.json`. Потік входу CLI зберігає + токени в профілях автентифікації на хості gateway. + - Якщо запити не працюють після входу, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. + - JSON-відповіді Gemini CLI парсяться з `response`; usage резервно береться з + `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -381,7 +377,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Приклад моделі: `zai/glm-5` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово використовують конкретну поверхню + - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню ### Vercel AI Gateway @@ -396,39 +392,39 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Автентифікація: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Базова URL-адреса: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення - `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог - під час виконання. -- Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, +- Базовий URL: `https://api.kilo.ai/api/gateway/` +- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live + виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime + каталог. +- Точна маршрутизація вище за потоком за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). +Дивіться [/providers/kilocode](/uk/providers/kilocode) для подробиць налаштування. ### Інші вбудовані плагіни постачальників - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Приклад моделі: `openrouter/auto` -- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді, - коли запит дійсно спрямовано на `openrouter.ai` +- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли + запит справді спрямований до `openrouter.ai` - Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені - перевіреними маршрутами OpenRouter, а не довільними URL-адресами проксі -- OpenRouter залишається на проксі-шляху у стилі OpenAI-compatible, тому нативне - формування запитів лише для OpenAI (`serviceTier`, `store` для Responses, - підказки кешу промптів, payload сумісності reasoning OpenAI) не пересилається -- Посилання OpenRouter на базі Gemini зберігають лише санітизацію підпису thought у проксі-Gemini; - нативна валідація повтору Gemini та переписування bootstrap залишаються вимкненими + перевіреними маршрутами OpenRouter, а не довільними URL проксі +- OpenRouter і далі залишається на шляху проксі-типу, сумісному з OpenAI, тому нативне + формування запиту лише для OpenAI (`serviceTier`, Responses `store`, + підказки prompt-cache, payload сумісності reasoning OpenAI) не пересилається +- Посилання OpenRouter на основі Gemini зберігають лише очищення підпису думок проксійованого Gemini; + нативна перевірка повторного відтворення Gemini та переписування bootstrap залишаються вимкненими - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Приклад моделі: `kilocode/kilo/auto` -- Посилання Kilo на базі Gemini зберігають той самий шлях санітизації підпису thought - у проксі-Gemini; `kilocode/kilo/auto` та інші підказки, що не підтримують reasoning через проксі, - пропускають ін'єкцію reasoning через проксі +- Посилання Kilo на основі Gemini зберігають той самий шлях очищення підпису думок + проксійованого Gemini; `kilocode/kilo/auto` та інші підказки, що не підтримують proxy reasoning, + пропускають ін'єкцію reasoning проксі - MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth) - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` - Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7` -- Налаштування MiniMax під час онбордингу/API-ключа записує явні визначення моделей M2.7 з - `input: ["text", "image"]`; вбудований каталог постачальника тримає chat-посилання - лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника +- Онбординг MiniMax/налаштування API-ключа записує явні визначення моделей M2.7 з + `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання + лише текстовими, доки конфігурацію цього постачальника не буде матеріалізовано - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Приклад моделі: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`) @@ -440,7 +436,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - NVIDIA: `nvidia` (`NVIDIA_API_KEY`) - Приклад моделі: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` - StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`) -- Приклад моделі: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` +- Приклади моделей: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` - Together: `together` (`TOGETHER_API_KEY`) - Приклад моделі: `together/moonshotai/Kimi-K2.5` - Venice: `venice` (`VENICE_API_KEY`) @@ -458,39 +454,39 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast` - `tool_stream` типово ввімкнено; задайте - `agents.defaults.models["xai/"].params.tool_stream` як `false`, щоб + `agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб вимкнути його - Mistral: `mistral` (`MISTRAL_API_KEY`) - Приклад моделі: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. - - Базова URL-адреса, сумісна з OpenAI: `https://api.cerebras.ai/v1`. + - Моделі GLM на Cerebras використовують id `zai-glm-4.7` і `zai-glm-4.6`. + - Базовий URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) -- Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface). +- Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Дивіться [Hugging Face (Inference)](/uk/providers/huggingface). -## Постачальники через `models.providers` (кастомна/base URL) +## Постачальники через `models.providers` (власний/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **кастомних** постачальників або -проксі, сумісні з OpenAI/Anthropic. +Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або +сумісні з OpenAI/Anthropic проксі. Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -типову базову URL-адресу, заголовки або список моделей. +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) Moonshot постачається як вбудований плагін постачальника. Використовуйте вбудованого постачальника -типово й додавайте явний запис `models.providers.moonshot` лише тоді, коли -потрібно перевизначити базову URL-адресу або метадані моделі: +типово і додавайте явний запис `models.providers.moonshot` лише тоді, коли +потрібно перевизначити base URL або метадані моделі: - Постачальник: `moonshot` - Автентифікація: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` -Ідентифікатори моделей Kimi K2: +ID моделей Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -522,7 +518,7 @@ Moonshot постачається як вбудований плагін пос ### Kimi Coding -Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: +Kimi Coding використовує сумісний з Anthropic endpoint Moonshot AI: - Постачальник: `kimi` - Автентифікація: `KIMI_API_KEY` @@ -537,7 +533,7 @@ Kimi Coding використовує Anthropic-сумісну кінцеву т } ``` -Застарілий `kimi/k2p5` і далі приймається як сумісний ідентифікатор моделі. +Застарілий `kimi/k2p5` і далі приймається як id моделі для сумісності. ### Volcano Engine (Doubao) @@ -556,13 +552,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу типово використовується поверхня coding, але загальний каталог `volcengine/*` -реєструється водночас. +Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*` +реєструється одночасно. -У вибірниках онбордингу/налаштування моделі варіант автентифікації Volcengine надає перевагу і рядкам -`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, -OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній -вибірник у межах постачальника. +У пікерах онбордингу/налаштування моделі вибір автентифікації Volcengine надає перевагу обом +рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw резервно переходить до нефільтрованого каталогу замість показу порожнього +пікера з областю постачальника. Доступні моделі: @@ -580,7 +576,7 @@ OpenClaw резервно повертається до нефільтрован - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (International) +### BytePlus (міжнародний) BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. @@ -597,13 +593,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Під час онбордингу типово використовується поверхня coding, але загальний каталог `byteplus/*` -реєструється водночас. +Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*` +реєструється одночасно. -У вибірниках онбордингу/налаштування моделі варіант автентифікації BytePlus надає перевагу і рядкам -`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, -OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній -вибірник у межах постачальника. +У пікерах онбордингу/налаштування моделі вибір автентифікації BytePlus надає перевагу обом +рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw резервно переходить до нефільтрованого каталогу замість показу порожнього +пікера з областю постачальника. Доступні моделі: @@ -621,7 +617,7 @@ OpenClaw резервно повертається до нефільтрован ### Synthetic -Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: +Synthetic надає сумісні з Anthropic моделі через постачальника `synthetic`: - Постачальник: `synthetic` - Автентифікація: `SYNTHETIC_API_KEY` @@ -649,31 +645,31 @@ Synthetic надає Anthropic-сумісні моделі через поста ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує кастомні кінцеві точки: +MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint: -- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (глобальний): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` -- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` +- API-ключ MiniMax (глобальний): `--auth-choice minimax-global-api` +- API-ключ MiniMax (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). +Дивіться [/providers/minimax](/uk/providers/minimax) для подробиць налаштування, варіантів моделей і фрагментів конфігурації. -На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, -якщо ви явно його не задаєте, а `/fast on` переписує +На Anthropic-сумісному шляху streaming MiniMax OpenClaw вимикає thinking +типово, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розподіл можливостей, що належать плагіну: +Поділ можливостей, якими володіє плагін: -- Типові значення тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax -- Вебпошук залишається на ідентифікаторі постачальника `minimax` +- Розуміння зображень — це `MiniMax-VL-01` на обох шляхах автентифікації MiniMax, яким володіє плагін +- Вебпошук залишається на id постачальника `minimax` ### Ollama -Ollama постачається як вбудований плагін постачальника й використовує нативний API Ollama: +Ollama постачається як вбудований плагін постачальника та використовує нативний API Ollama: - Постачальник: `ollama` - Автентифікація: не потрібна (локальний сервер) @@ -681,7 +677,7 @@ Ollama постачається як вбудований плагін пост - Встановлення: [https://ollama.com/download](https://ollama.com/download) ```bash -# Встановіть Ollama, потім завантажте модель: +# Install Ollama, then pull a model: ollama pull llama3.3 ``` @@ -693,10 +689,10 @@ ollama pull llama3.3 } ``` -Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте її через +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до -`openclaw onboard` і вибірника моделей. Див. [/providers/ollama](/uk/providers/ollama) -щодо онбордингу, хмарного/локального режиму та кастомної конфігурації. +`openclaw onboard` і пікера моделей. Дивіться [/providers/ollama](/uk/providers/ollama) +для онбордингу, cloud/local режиму та власної конфігурації. ### vLLM @@ -705,15 +701,15 @@ vLLM постачається як вбудований плагін поста - Постачальник: `vllm` - Автентифікація: необов'язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:8000/v1` +- Типовий base URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікацію): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім задайте модель (замініть на один із ID, які повертає `/v1/models`): ```json5 { @@ -723,7 +719,7 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі див. у [/providers/vllm](/uk/providers/vllm). +Дивіться [/providers/vllm](/uk/providers/vllm) для подробиць. ### SGLang @@ -732,16 +728,16 @@ SGLang постачається як вбудований плагін пост - Постачальник: `sglang` - Автентифікація: необов'язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:30000/v1` +- Типовий base URL: `http://127.0.0.1:30000/v1` Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не -вимагає автентифікації): +вимагає автентифікацію): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім задайте модель (замініть на один із ID, які повертає `/v1/models`): ```json5 { @@ -751,11 +747,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі див. у [/providers/sglang](/uk/providers/sglang). +Дивіться [/providers/sglang](/uk/providers/sglang) для подробиць. ### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI-compatible): +Приклад (сумісний з OpenAI): ```json5 { @@ -790,20 +786,21 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для кастомних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов'язковими. +- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов'язкові. Якщо їх не вказано, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендація: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. -- Для `api: "openai-completions"` на не-нативних кінцевих точках (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. -- Проксі-маршрути у стилі OpenAI-compatible також пропускають нативне - формування запитів лише для OpenAI: без `service_tier`, без `store` для Responses, без підказок кешу промптів, без - формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). -- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не-нативних кінцевих точках `openai-completions`. +- Рекомендовано: задавати явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. +- Маршрути проксі-типу, сумісні з OpenAI, також пропускають нативне формування запиту лише для OpenAI: + без `service_tier`, без Responses `store`, без підказок prompt-cache, без + формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції + OpenClaw. +- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка резолвиться до `api.openai.com`). +- З міркувань безпеки явний `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint `openai-completions`. ## Приклади CLI @@ -813,11 +810,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. +Дивіться також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов'язане +## Пов'язані сторінки - [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб -- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделі -- [Providers](/uk/providers) — окремі посібники з налаштування постачальників +- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного переходу та поведінка повторних спроб +- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей +- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника diff --git a/docs/uk/concepts/oauth.md b/docs/uk/concepts/oauth.md index 1e61e5d8f..8a40ed72b 100644 --- a/docs/uk/concepts/oauth.md +++ b/docs/uk/concepts/oauth.md @@ -1,42 +1,41 @@ --- read_when: - - Ви хочете зрозуміти OAuth в OpenClaw наскрізь - - Ви зіткнулися з проблемами анулювання токенів / виходу з системи - - Вам потрібні потоки автентифікації Claude CLI або OAuth - - Ви хочете мати кілька облікових записів або маршрутизацію за профілями -summary: 'OAuth в OpenClaw: обмін токенами, зберігання та шаблони для кількох облікових записів' + - Ви хочете зрозуміти OAuth в OpenClaw від початку до кінця + - Ви зіткнулися з анулюванням токенів / проблемами виходу з системи + - Вам потрібні Claude CLI або OAuth-потоки автентифікації + - Ви хочете використовувати кілька облікових записів або маршрутизацію профілів +summary: 'OAuth в OpenClaw: обмін токенами, зберігання та шаблони роботи з кількома обліковими записами' title: OAuth x-i18n: - generated_at: "2026-04-05T18:01:48Z" + generated_at: "2026-04-06T15:27:43Z" model: gpt-5.4 provider: openai - source_hash: 402e20dfeb6ae87a90cba5824a56a7ba3b964f3716508ea5cc48a47e5affdd73 + source_hash: 4117fee70e3e64fd3a762403454ac2b78de695d2b85a7146750c6de615921e02 source_path: concepts/oauth.md workflow: 15 --- # OAuth -OpenClaw підтримує «автентифікацію за підпискою» через OAuth для провайдерів, які це пропонують +OpenClaw підтримує «автентифікацію за підпискою» через OAuth для провайдерів, які її пропонують (зокрема **OpenAI Codex (ChatGPT OAuth)**). Для Anthropic практичний поділ тепер такий: -- **Anthropic API key**: звичайне тарифікування Anthropic API -- **Автентифікація за підпискою Anthropic всередині OpenClaw**: Anthropic повідомила користувачів OpenClaw - **4 квітня 2026 року о 12:00 PT / 20:00 BST**, що тепер це - вимагає **Extra Usage** +- **Ключ API Anthropic**: звичайна тарифікація Anthropic API +- **Anthropic Claude CLI / автентифікація за підпискою всередині OpenClaw**: співробітники Anthropic + повідомили нам, що таке використання знову дозволене -OAuth OpenAI Codex явно підтримується для використання в зовнішніх інструментах, як-от +OpenAI Codex OAuth офіційно підтримується для використання у зовнішніх інструментах, таких як OpenClaw. На цій сторінці пояснюється: -Для Anthropic у production безпечнішим рекомендованим шляхом є автентифікація за API-ключем. +Для Anthropic у production безпечнішим рекомендованим шляхом є автентифікація за ключем API. -- як працює OAuth **обмін токенами** (PKCE) +- як працює **обмін токенами** OAuth (PKCE) - де **зберігаються** токени (і чому) - як працювати з **кількома обліковими записами** (профілі + перевизначення для окремої сесії) -OpenClaw також підтримує **плагіни провайдерів**, які постачають власні потоки -OAuth або API-key. Запускайте їх так: +OpenClaw також підтримує **плагіни провайдерів**, які постачають власні OAuth- або API‑key-потоки +автентифікації. Запускайте їх через: ```bash openclaw models auth login --provider @@ -44,71 +43,65 @@ openclaw models auth login --provider ## Сховище токенів (навіщо воно існує) -OAuth-провайдери часто випускають **новий refresh token** під час потоків входу/оновлення. Деякі провайдери (або OAuth-клієнти) можуть анулювати старі refresh token, коли для того самого користувача/застосунку видається новий. +OAuth-провайдери зазвичай випускають **новий refresh token** під час входу або оновлення токенів. Деякі провайдери (або OAuth-клієнти) можуть анулювати старі refresh token, коли для того самого користувача/застосунку видається новий. Практичний симптом: -- ви входите через OpenClaw _і_ через Claude Code / Codex CLI → один із них випадково «виходить із системи» пізніше +- ви входите через OpenClaw _і_ через Claude Code / Codex CLI → один із них пізніше випадково «вилітає з системи» -Щоб зменшити це, OpenClaw розглядає `auth-profiles.json` як **сховище токенів**: +Щоб зменшити ймовірність цього, OpenClaw розглядає `auth-profiles.json` як **сховище токенів**: -- runtime зчитує облікові дані з **одного місця** -- ми можемо зберігати кілька профілів і детерміновано маршрутизувати їх +- runtime читає облікові дані з **одного місця** +- ми можемо зберігати кілька профілів і детерміновано їх маршрутизувати - коли облікові дані повторно використовуються із зовнішнього CLI, як-от Codex CLI, OpenClaw - віддзеркалює їх із provenance і повторно зчитує це зовнішнє джерело замість того, щоб - самостійно обертати refresh token + дзеркалює їх разом із даними про походження та повторно зчитує це зовнішнє джерело замість того, + щоб самостійно оновлювати refresh token ## Зберігання (де живуть токени) Секрети зберігаються **для кожного агента окремо**: -- Профілі автентифікації (OAuth + API-ключі + необов’язкові посилання на значення): `~/.openclaw/agents//agent/auth-profiles.json` -- Застарілий файл сумісності: `~/.openclaw/agents//agent/auth.json` - (статичні записи `api_key` очищаються, якщо виявляються) +- Профілі автентифікації (OAuth + API keys + необов’язкові посилання на значення): `~/.openclaw/agents//agent/auth-profiles.json` +- Файл сумісності зі старою схемою: `~/.openclaw/agents//agent/auth.json` + (статичні записи `api_key` очищаються під час виявлення) -Застарілий файл лише для імпорту (досі підтримується, але не є основним сховищем): +Старий файл лише для імпорту (досі підтримується, але не є основним сховищем): -- `~/.openclaw/credentials/oauth.json` (імпортується до `auth-profiles.json` під час першого використання) +- `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання) -Усе перелічене вище також враховує `$OPENCLAW_STATE_DIR` (перевизначення каталогу стану). Повний довідник: [/gateway/configuration](/gateway/configuration-reference#auth-storage) +Усе вищезазначене також враховує `$OPENCLAW_STATE_DIR` (перевизначення каталогу стану). Повна довідка: [/gateway/configuration](/uk/gateway/configuration-reference#auth-storage) -Для статичних SecretRef і поведінки активації snapshot у runtime див. [Керування секретами](/gateway/secrets). +Щодо статичних посилань на секрети та поведінки активації runtime snapshot див. [Керування секретами](/uk/gateway/secrets). -## Сумісність зі застарілими токенами Anthropic +## Сумісність зі старими токенами Anthropic -У публічній документації Claude Code від Anthropic сказано, що пряме використання Claude Code залишається -в межах лімітів підписки Claude. Окремо Anthropic повідомила користувачів OpenClaw -**4 квітня 2026 року о 12:00 PT / 20:00 BST**, що **OpenClaw вважається -сторонньою harness-системою**. Наявні профілі токенів Anthropic технічно -залишаються придатними до використання в OpenClaw, але Anthropic каже, що шлях через OpenClaw тепер вимагає **Extra -Usage** (окрема оплата pay-as-you-go, окремо від підписки) для цього трафіку. +У публічній документації Anthropic для Claude Code сказано, що пряме використання Claude Code залишається в межах +лімітів підписки Claude, а співробітники Anthropic повідомили нам, що використання Claude +CLI у стилі OpenClaw знову дозволене. Тому OpenClaw вважає повторне використання Claude CLI та +використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic +не опублікує нову політику. -Актуальну документацію Anthropic щодо прямого плану Claude Code див. у [Using Claude Code +Актуальну документацію Anthropic щодо планів для прямого Claude Code див. у [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) -та [Using Claude Code with your Team or Enterprise +і [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/). -Якщо вам потрібні інші варіанти у стилі підписки в OpenClaw, див. [OpenAI -Codex](/providers/openai), [Qwen Cloud Coding -Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax), -та [Z.AI / GLM Coding Plan](/providers/glm). +Якщо вам потрібні інші варіанти в стилі підписки в OpenClaw, див. [OpenAI +Codex](/uk/providers/openai), [Qwen Cloud Coding +Plan](/uk/providers/qwen), [MiniMax Coding Plan](/uk/providers/minimax), +і [Z.AI / GLM Coding Plan](/uk/providers/glm). -OpenClaw тепер знову надає setup-token Anthropic як застарілий/ручний шлях. -До цього шляху й надалі застосовується повідомлення Anthropic про тарифікацію для OpenClaw, тож -використовуйте його з розумінням того, що Anthropic вимагає **Extra Usage** для -трафіку входу Claude, ініційованого OpenClaw. +OpenClaw також надає setup-token Anthropic як підтримуваний шлях автентифікації за токеном, але тепер надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. ## Міграція Anthropic Claude CLI -Anthropic більше не має підтримуваного локального шляху міграції Claude CLI в -OpenClaw. Використовуйте API-ключі Anthropic для трафіку Anthropic або залишайте застарілу -автентифікацію на основі токенів лише там, де вона вже налаштована, і з розумінням -того, що Anthropic розглядає цей шлях OpenClaw як **Extra Usage**. +OpenClaw знову підтримує повторне використання Anthropic Claude CLI. Якщо у вас уже є локальний +вхід у Claude на хості, onboarding/configure може повторно використати його безпосередньо. -## Обмін OAuth (як працює вхід) +## OAuth exchange (як працює вхід) Інтерактивні потоки входу OpenClaw реалізовані в `@mariozechner/pi-ai` і підключені до майстрів/команд. @@ -116,34 +109,34 @@ OpenClaw. Використовуйте API-ключі Anthropic для траф Форма потоку: -1. запустіть setup-token Anthropic або вставте токен з OpenClaw +1. запустіть Anthropic setup-token або paste-token з OpenClaw 2. OpenClaw зберігає отримані облікові дані Anthropic у профілі автентифікації 3. вибір моделі залишається на `anthropic/...` 4. наявні профілі автентифікації Anthropic залишаються доступними для відкату/керування порядком ### OpenAI Codex (ChatGPT OAuth) -OAuth OpenAI Codex явно підтримується для використання поза Codex CLI, зокрема у workflow OpenClaw. +OpenAI Codex OAuth офіційно підтримується для використання поза Codex CLI, зокрема у workflow OpenClaw. Форма потоку (PKCE): -1. згенеруйте verifier/challenge PKCE + випадковий `state` -2. відкрийте `https://auth.openai.com/oauth/authorize?...` -3. спробуйте перехопити callback на `http://127.0.0.1:1455/auth/callback` -4. якщо callback не вдається прив’язати (або ви працюєте віддалено/безголово), вставте URL переспрямування/код -5. виконайте обмін на `https://auth.openai.com/oauth/token` -6. витягніть `accountId` з access token і збережіть `{ access, refresh, expires, accountId }` +1. згенерувати verifier/challenge PKCE + випадковий `state` +2. відкрити `https://auth.openai.com/oauth/authorize?...` +3. спробувати перехопити callback на `http://127.0.0.1:1455/auth/callback` +4. якщо callback не вдається прив’язати (або ви працюєте віддалено / без headless), вставте redirect URL/code +5. виконати exchange на `https://auth.openai.com/oauth/token` +6. витягти `accountId` з access token і зберегти `{ access, refresh, expires, accountId }` Шлях у майстрі: `openclaw onboard` → вибір автентифікації `openai-codex`. -## Оновлення + завершення строку дії +## Оновлення + строк дії Профілі зберігають часову позначку `expires`. Під час runtime: -- якщо `expires` ще в майбутньому → використовується збережений access token -- якщо строк дії минув → виконується оновлення (під файловим блокуванням) і збережені облікові дані перезаписуються +- якщо `expires` у майбутньому → використовуйте збережений access token +- якщо строк дії минув → оновіть (під файловим блокуванням) і перезапишіть збережені облікові дані - виняток: повторно використані облікові дані зовнішнього CLI залишаються під зовнішнім керуванням; OpenClaw повторно зчитує сховище автентифікації CLI і ніколи сам не витрачає скопійований refresh token @@ -153,9 +146,9 @@ OAuth OpenAI Codex явно підтримується для використа Два шаблони: -### 1) Переважний: окремі агенти +### 1) Бажано: окремі агенти -Якщо ви хочете, щоб «особисте» і «робоче» ніколи не перетиналися, використовуйте ізольованих агентів (окремі сесії + облікові дані + робочий простір): +Якщо ви хочете, щоб «особистий» і «робочий» ніколи не взаємодіяли, використовуйте ізольованих агентів (окремі сесії + облікові дані + робочий простір): ```bash openclaw agents add work @@ -164,11 +157,11 @@ openclaw agents add personal Потім налаштуйте автентифікацію для кожного агента окремо (майстер) і маршрутизуйте чати до потрібного агента. -### 2) Розширений варіант: кілька профілів в одному агенті +### 2) Розширено: кілька профілів в одному агенті -`auth-profiles.json` підтримує кілька ID профілів для одного й того самого провайдера. +`auth-profiles.json` підтримує кілька ID профілів для одного провайдера. -Виберіть, який профіль використовується: +Вибрати, який профіль використовується: - глобально через порядок у конфігурації (`auth.order`) - для окремої сесії через `/model ...@` @@ -181,13 +174,13 @@ openclaw agents add personal - `openclaw channels list --json` (показує `auth[]`) -Пов’язана документація: +Пов’язані документи: -- [/concepts/model-failover](/concepts/model-failover) (правила ротації + cooldown) -- [/tools/slash-commands](/tools/slash-commands) (поверхня команд) +- [/concepts/model-failover](/uk/concepts/model-failover) (правила ротації + cooldown) +- [/tools/slash-commands](/uk/tools/slash-commands) (поверхня команд) ## Пов’язане -- [Автентифікація](/gateway/authentication) — огляд автентифікації провайдерів моделей -- [Секрети](/gateway/secrets) — зберігання облікових даних і SecretRef -- [Довідник конфігурації](/gateway/configuration-reference#auth-storage) — ключі конфігурації автентифікації +- [Автентифікація](/uk/gateway/authentication) — огляд автентифікації провайдерів моделей +- [Секрети](/uk/gateway/secrets) — зберігання облікових даних і SecretRef +- [Довідник з конфігурації](/uk/gateway/configuration-reference#auth-storage) — ключі конфігурації автентифікації diff --git a/docs/uk/gateway/authentication.md b/docs/uk/gateway/authentication.md index 8902064c5..86216104a 100644 --- a/docs/uk/gateway/authentication.md +++ b/docs/uk/gateway/authentication.md @@ -1,14 +1,14 @@ --- read_when: - - Налагодження автентифікації моделей або завершення строку дії OAuth + - Налагодження автентифікації моделей або завершення дії OAuth - Документування автентифікації або зберігання облікових даних -summary: 'Автентифікація моделей: OAuth, API-ключі та застарілий setup-token Anthropic' +summary: 'Автентифікація моделей: OAuth, API-ключі, повторне використання Claude CLI та setup-token Anthropic' title: Автентифікація x-i18n: - generated_at: "2026-04-06T12:57:04Z" + generated_at: "2026-04-06T15:27:45Z" model: gpt-5.4 provider: openai - source_hash: b13cc0bca2b27a6d8326a8cb3f8b1e1810ecd722f29c7a199ceff2fbaf70c6aa + source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231 source_path: gateway/authentication.md workflow: 15 --- @@ -16,28 +16,27 @@ x-i18n: # Автентифікація (постачальники моделей) -Ця сторінка охоплює автентифікацію **постачальника моделей** (API-ключі, OAuth і застарілий setup-token Anthropic). Для автентифікації **підключення шлюзу** (токен, пароль, trusted-proxy) див. [Configuration](/uk/gateway/configuration) і [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). +Ця сторінка охоплює автентифікацію **постачальника моделей** (API-ключі, OAuth, повторне використання Claude CLI та Anthropic setup-token). Для автентифікації **підключення шлюзу** (токен, пароль, trusted-proxy) див. [Configuration](/uk/gateway/configuration) і [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). -OpenClaw підтримує OAuth і API-ключі для постачальників моделей. Для хостів -шлюзу, що працюють постійно, API-ключі зазвичай є найпередбачуванішим варіантом. Також -підтримуються потоки підписки/OAuth, якщо вони відповідають моделі облікового запису вашого постачальника. +OpenClaw підтримує OAuth і API-ключі для постачальників моделей. Для постійно +увімкнених хостів шлюзу API-ключі зазвичай є найпередбачуванішим варіантом. Також підтримуються +сценарії підписки/OAuth, коли вони відповідають моделі вашого облікового запису постачальника. -Див. [/concepts/oauth](/uk/concepts/oauth), щоб ознайомитися з повним потоком OAuth і схемою +Див. [/concepts/oauth](/uk/concepts/oauth), щоб ознайомитися з повним процесом OAuth і схемою зберігання. Щодо автентифікації на основі SecretRef (постачальники `env`/`file`/`exec`) див. [Secrets Management](/uk/gateway/secrets). -Щодо правил відповідності облікових даних/кодів причин, які використовує `models status --probe`, див. +Щодо правил відповідності облікових даних / кодів причин, які використовує `models status --probe`, див. [Auth Credential Semantics](/uk/auth-credential-semantics). ## Рекомендоване налаштування (API-ключ, будь-який постачальник) Якщо ви запускаєте довготривалий шлюз, почніть з API-ключа для вибраного постачальника. -Для Anthropic зокрема, автентифікація через API-ключ є безпечним шляхом. Автентифікація Anthropic -у стилі підписки в OpenClaw — це застарілий шлях setup-token, і її -слід розглядати як шлях **Extra Usage**, а не як шлях лімітів тарифного плану. +Для Anthropic зокрема автентифікація за API-ключем усе ще є найпередбачуванішим серверним +налаштуванням, але OpenClaw також підтримує повторне використання локального входу Claude CLI. -1. Створіть API-ключ у консолі вашого постачальника. +1. Створіть API-ключ у консолі свого постачальника. 2. Розмістіть його на **хості шлюзу** (машині, на якій виконується `openclaw gateway`). ```bash @@ -61,26 +60,25 @@ openclaw models status openclaw doctor ``` -Якщо ви не хочете самостійно керувати змінними середовища, onboarding може зберігати +Якщо ви не хочете самостійно керувати змінними середовища, онбординг може зберігати API-ключі для використання демоном: `openclaw onboard`. Див. [Help](/uk/help), щоб дізнатися подробиці про успадкування env (`env.shellEnv`, `~/.openclaw/.env`, systemd/launchd). -## Anthropic: сумісність із застарілими токенами +## Anthropic: сумісність Claude CLI і токенів -Автентифікація Anthropic setup-token усе ще доступна в OpenClaw як -застарілий/ручний шлях. Публічна документація Anthropic Claude Code і далі охоплює пряме -використання Claude Code у терміналі в межах тарифів Claude, але Anthropic окремо повідомила -користувачам OpenClaw, що шлях входу Claude в **OpenClaw** вважається використанням -стороннього harness і потребує **Extra Usage**, що оплачується окремо від -підписки. +Автентифікація Anthropic setup-token усе ще доступна в OpenClaw як підтримуваний +шлях токена. Відтоді співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw +знову дозволено, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` +санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо на +хості доступне повторне використання Claude CLI, тепер це пріоритетний шлях. -Для найзрозумілішого шляху налаштування використовуйте API-ключ Anthropic. Якщо вам потрібно зберегти -шлях Anthropic у стилі підписки в OpenClaw, використовуйте застарілий шлях setup-token -з очікуванням, що Anthropic розглядатиме це як **Extra Usage**. +Для довготривалих хостів шлюзу API-ключ Anthropic усе ще є найпередбачуванішим +налаштуванням. Якщо ви хочете повторно використати наявний вхід Claude на тому самому хості, скористайтеся +шляхом Anthropic Claude CLI в onboarding/configure. -Ручне введення токена (будь-який постачальник; записує в `auth-profiles.json` + оновлює config): +Ручне введення токена (будь-який постачальник; записує в `auth-profiles.json` і оновлює config): ```bash openclaw models auth paste-token --provider openrouter @@ -88,11 +86,11 @@ openclaw models auth paste-token --provider openrouter Також підтримуються посилання на профілі автентифікації для статичних облікових даних: -- Облікові дані `api_key` можуть використовувати `keyRef: { source, provider, id }` -- Облікові дані `token` можуть використовувати `tokenRef: { source, provider, id }` -- Профілі режиму OAuth не підтримують облікові дані SecretRef; якщо для `auth.profiles..mode` встановлено `"oauth"`, введення `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється. +- облікові дані `api_key` можуть використовувати `keyRef: { source, provider, id }` +- облікові дані `token` можуть використовувати `tokenRef: { source, provider, id }` +- Профілі в режимі OAuth не підтримують облікові дані SecretRef; якщо `auth.profiles..mode` має значення `"oauth"`, введення `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється. -Перевірка, зручна для автоматизації (вихід `1`, якщо строк дії минув/відсутній, `2`, якщо скоро мине): +Перевірка, зручна для автоматизації (вихід `1`, якщо прострочено/відсутнє, `2`, якщо скоро спливає): ```bash openclaw models status --check @@ -109,25 +107,23 @@ openclaw models status --probe - Рядки probe можуть надходити з профілів автентифікації, облікових даних env або `models.json`. - Якщо явний `auth.order.` пропускає збережений профіль, probe повідомляє `excluded_by_auth_order` для цього профілю замість спроби використати його. -- Якщо автентифікація існує, але OpenClaw не може визначити кандидата моделі для probe - для цього постачальника, probe повідомляє `status: no_model`. -- Затримки охолодження через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується для однієї +- Якщо автентифікація існує, але OpenClaw не може визначити придатну модель-кандидат для probe для + цього постачальника, probe повідомляє `status: no_model`. +- Кулдауни rate-limit можуть бути прив’язані до конкретної моделі. Профіль, який перебуває в кулдауні для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого постачальника. Необов’язкові операційні скрипти (systemd/Termux) задокументовані тут: -[Auth monitoring scripts](/uk/help/scripts#auth-monitoring-scripts) +[Скрипти моніторингу автентифікації](/uk/help/scripts#auth-monitoring-scripts) ## Примітка щодо Anthropic -Бекенд Anthropic `claude-cli` було видалено. +Бекенд Anthropic `claude-cli` знову підтримується. -- Використовуйте API-ключі Anthropic для трафіку Anthropic в OpenClaw. -- Anthropic setup-token залишається застарілим/ручним шляхом і має використовуватися з - очікуванням тарифікації Extra Usage, про яку Anthropic повідомила користувачам OpenClaw. -- `openclaw doctor` тепер виявляє застарілий видалений стан Anthropic Claude CLI. Якщо - байти збережених облікових даних усе ще існують, doctor перетворює їх назад на - профілі токена/OAuth Anthropic. Якщо ні, doctor видаляє застарілу конфігурацію Claude CLI - і вказує вам на відновлення через API-ключ або setup-token. +- Співробітники Anthropic повідомили нам, що цей шлях інтеграції OpenClaw знову дозволено. +- Тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими + для запусків на основі Anthropic, якщо Anthropic не опублікує нову політику. +- API-ключі Anthropic залишаються найпередбачуванішим вибором для довготривалих хостів шлюзу + та явного контролю виставлення рахунків на сервері. ## Перевірка стану автентифікації моделі @@ -138,22 +134,22 @@ openclaw doctor ## Поведінка ротації API-ключів (шлюз) -Деякі постачальники підтримують повторну спробу запиту з альтернативними ключами, коли виклик API -натрапляє на обмеження частоти постачальника. +Деякі постачальники підтримують повторну спробу запиту з альтернативними ключами, коли API-виклик +натрапляє на обмеження частоти запитів постачальника. - Порядок пріоритету: - - `OPENCLAW_LIVE__KEY` (єдиний override) + - `OPENCLAW_LIVE__KEY` (одне перевизначення) - `_API_KEYS` - `_API_KEY` - `_API_KEY_*` - Постачальники Google також включають `GOOGLE_API_KEY` як додатковий резервний варіант. -- Той самий список ключів дедуплікується перед використанням. -- OpenClaw виконує повторну спробу з наступним ключем лише для помилок обмеження частоти (наприклад, +- Перед використанням той самий список ключів очищається від дублікатів. +- OpenClaw повторює спробу з наступним ключем лише для помилок rate-limit (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached` або `workers_ai ... quota limit exceeded`). -- Помилки, не пов’язані з обмеженням частоти, не повторюються з альтернативними ключами. -- Якщо всі ключі не спрацюють, повертається остаточна помилка з останньої спроби. +- Для помилок, не пов’язаних із rate-limit, повторні спроби з альтернативними ключами не виконуються. +- Якщо всі ключі не спрацювали, повертається фінальна помилка з останньої спроби. ## Керування тим, які облікові дані використовуються @@ -161,11 +157,11 @@ requests`, `ThrottlingException`, `concurrency limit reached` або Використовуйте `/model @`, щоб закріпити конкретні облікові дані постачальника для поточного сеансу (приклади ідентифікаторів профілів: `anthropic:default`, `anthropic:work`). -Використовуйте `/model` (або `/model list`) для компактного вибору; використовуйте `/model status` для повного подання (кандидати + наступний профіль автентифікації, а також відомості про endpoint постачальника, якщо їх налаштовано). +Використовуйте `/model` (або `/model list`) для компактного вибору; використовуйте `/model status` для повного подання (кандидати + наступний профіль автентифікації, а також відомості про кінцеву точку постачальника, якщо їх налаштовано). -### Для агента (override CLI) +### Для агента (перевизначення CLI) -Установіть явний override порядку профілів автентифікації для агента (зберігається в `auth-state.json` цього агента): +Установіть явне перевизначення порядку профілів автентифікації для агента (зберігається в `auth-state.json` цього агента): ```bash openclaw models auth order get --provider anthropic @@ -173,36 +169,25 @@ openclaw models auth order set --provider anthropic anthropic:default openclaw models auth order clear --provider anthropic ``` -Використовуйте `--agent `, щоб націлити на конкретного агента; не вказуйте його, щоб використовувати налаштованого агента за замовчуванням. -Під час налагодження проблем із порядком `openclaw models status --probe` показує пропущені +Використовуйте `--agent `, щоб націлитися на конкретного агента; не вказуйте його, щоб використовувати налаштованого агента за замовчуванням. +Коли ви налагоджуєте проблеми з порядком, `openclaw models status --probe` показує пропущені збережені профілі як `excluded_by_auth_order` замість того, щоб мовчки їх пропускати. -Під час налагодження проблем із затримками охолодження пам’ятайте, що вони можуть бути прив’язані -до одного id моделі, а не до всього профілю постачальника. +Коли ви налагоджуєте проблеми з кулдауном, пам’ятайте, що кулдауни rate-limit можуть бути прив’язані +до одного ідентифікатора моделі, а не до всього профілю постачальника. -## Усунення несправностей +## Усунення неполадок ### "Облікові дані не знайдено" Якщо профіль Anthropic відсутній, налаштуйте API-ключ Anthropic на -**хості шлюзу** або налаштуйте застарілий шлях Anthropic setup-token, а потім повторно перевірте: +**хості шлюзу** або налаштуйте шлях Anthropic setup-token, а потім повторно перевірте: ```bash openclaw models status ``` -### Строк дії токена скоро минає/минув +### Токен скоро спливає/прострочений -Виконайте `openclaw models status`, щоб підтвердити, строк дії якого профілю скоро минає. Якщо застарілий -профіль токена Anthropic відсутній або строк його дії минув, оновіть це налаштування через +Виконайте `openclaw models status`, щоб підтвердити, який профіль скоро спливає. Якщо +профіль токена Anthropic відсутній або прострочений, оновіть це налаштування через setup-token або перейдіть на API-ключ Anthropic. - -Якщо на машині все ще є застарілий видалений стан Anthropic Claude CLI зі старіших -збірок, виконайте: - -```bash -openclaw doctor --yes -``` - -Doctor перетворює `anthropic:claude-cli` назад на токен/OAuth Anthropic, якщо -байти збережених облікових даних усе ще існують. Інакше він видаляє застарілі -посилання профілю/конфігурації/моделі Claude CLI і залишає вказівки щодо наступних кроків. diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index f4079a610..1492b8d5f 100644 --- a/docs/uk/gateway/cli-backends.md +++ b/docs/uk/gateway/cli-backends.md @@ -1,15 +1,15 @@ --- read_when: - Вам потрібен надійний резервний варіант, коли API-провайдери не працюють - - Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх - - Ви хочете зрозуміти MCP loopback-міст для доступу CLI-бекенду до інструментів + - Ви запускаєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх + - Ви хочете зрозуміти loopback-міст MCP для доступу CLI-бекенду до інструментів summary: 'CLI-бекенди: локальний резервний AI CLI з необов’язковим мостом інструментів MCP' title: CLI-бекенди x-i18n: - generated_at: "2026-04-06T12:43:15Z" + generated_at: "2026-04-06T15:27:59Z" model: gpt-5.4 provider: openai - source_hash: fe30bb4d5f51adcda53bf69a4f88e27832e78630ed5bfd8a33a66b6412b66f2d + source_hash: f061357f420455ad6ffaabe7fe28f1fb1b1769d73a4eb2e6f45c6eb3c2e36667 source_path: gateway/cli-backends.md workflow: 15 --- @@ -20,28 +20,28 @@ OpenClaw може запускати **локальні AI CLI** як **лише обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід: - **Інструменти OpenClaw не впроваджуються безпосередньо**, але бекенди з `bundleMcp: true` - можуть отримувати інструменти gateway через loopback-міст MCP. + можуть отримувати інструменти шлюзу через loopback-міст MCP. - **JSONL-стримінг** для CLI, які це підтримують. -- **Сеанси підтримуються** (тому наступні звернення залишаються узгодженими). +- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими). - **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень. -Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли вам -потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. +Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли +вам потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. -Якщо вам потрібне повноцінне середовище виконання harness із керуванням сеансами ACP, фоновими завданнями, -прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте +Якщо вам потрібне повноцінне середовище виконання harness із керуванням сесіями ACP, фоновими завданнями, +прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, використовуйте [ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP. ## Швидкий старт для початківців Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI -реєструє бекенд за замовчуванням): +реєструє типовий бекенд): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише +Якщо ваш шлюз працює під launchd/systemd і PATH мінімальний, додайте лише шлях до команди: ```json5 @@ -61,13 +61,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на -хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація -явно посилається на цей бекенд у model ref або в +хості шлюзу, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація +явно посилається на цей бекенд у посиланні на модель або в `agents.defaults.cliBackends`. -## Використання як резервного варіанта +## Використання як резервного варіанту -Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі не працюють: +Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють: ```json5 { @@ -88,20 +88,20 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 Примітки: -- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі CLI-бекенду. -- Якщо основний провайдер завершується помилкою (автентифікація, обмеження частоти, тайм-аути), OpenClaw - спробує CLI-бекенд наступним. +- Якщо ви використовуєте `agents.defaults.models` (дозволений список), ви також маєте включити туди моделі CLI-бекенду. +- Якщо основний провайдер не працює (автентифікація, ліміти частоти, тайм-аути), OpenClaw + далі спробує CLI-бекенд. ## Огляд конфігурації -Усі CLI-бекенди розміщуються тут: +Усі CLI-бекенди знаходяться тут: ``` agents.defaults.cliBackends ``` Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`). -Ідентифікатор провайдера стає лівою частиною вашого model ref: +Ідентифікатор провайдера стає лівою частиною посилання на модель: ``` / @@ -145,36 +145,36 @@ agents.defaults.cliBackends ## Як це працює 1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). -2. **Формує system prompt** із використанням того самого prompt OpenClaw і контексту робочого простору. -3. **Виконує CLI** з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою. -4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. -5. **Зберігає ідентифікатори сеансів** для кожного бекенду, щоб наступні звернення повторно використовували той самий сеанс CLI. +2. **Створює системний промпт** із використанням того самого промпту OpenClaw і контексту робочого простору. +3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою. +4. **Аналізує вивід** (JSON або звичайний текст) і повертає фінальний текст. +5. **Зберігає ідентифікатори сесій** для кожного бекенду, щоб наступні звернення повторно використовували ту саму CLI-сесію. - -Вбудований бекенд Anthropic `claude-cli` було видалено після того, як змінилася -межа білінгу OpenClaw в Anthropic. OpenClaw і далі підтримує загальні CLI- -бекенди, але трафік Anthropic API слід спрямовувати безпосередньо через провайдера Anthropic, -а не через видалений локальний шлях Claude CLI. - + +Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic +повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає +використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує +нову політику. + -## Сеанси +## Сесії -- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або - `sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити +- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або + `sessionArgs` (заповнювач `{sessionId}`), коли ідентифікатор потрібно вставити в кілька прапорців. -- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте - `resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput` - (для відновлення не у форматі JSON). +- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, задайте + `resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput` + (для відновлення не в JSON). - `sessionMode`: - - `always`: завжди передавати ідентифікатор сеансу (новий UUID, якщо нічого не збережено). - - `existing`: передавати ідентифікатор сеансу, лише якщо його вже було збережено. - - `none`: ніколи не передавати ідентифікатор сеансу. + - `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено). + - `existing`: надсилати ідентифікатор сесії, лише якщо його було збережено раніше. + - `none`: ніколи не надсилати ідентифікатор сесії. Примітки щодо серіалізації: -- `serialize: true` зберігає впорядкованість запусків у тій самій смузі. -- Більшість CLI серіалізують роботу в одній смузі провайдера. -- OpenClaw скидає повторне використання збереженого CLI-сеансу, коли змінюється стан автентифікації бекенду, зокрема після повторного входу, ротації токена або зміни облікових даних профілю автентифікації. +- `serialize: true` зберігає порядок запусків в одній смузі. +- Більшість CLI серіалізують у межах однієї смуги провайдера. +- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється стан автентифікації бекенду, зокрема після повторного входу, ротації токена або зміни облікових даних профілю автентифікації. ## Зображення (передавання далі) @@ -185,29 +185,29 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці +OpenClaw записуватиме зображення base64 у тимчасові файли. Якщо задано `imageArg`, ці шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає -шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично +шляхи до файлів у промпт (ін’єкція шляху), чого достатньо для CLI, які автоматично завантажують локальні файли зі звичайних шляхів. ## Входи / виходи -- `output: "json"` (типово) намагається розібрати JSON і витягти текст та ідентифікатор сеансу. -- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а - дані використання — зі `stats`, коли `usage` відсутній або порожній. -- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента, а також ідентифікатори сеансу, +- `output: "json"` (типово) намагається розібрати JSON і витягти текст та ідентифікатор сесії. +- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а + usage — з `stats`, коли `usage` відсутній або порожній. +- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента та ідентифікатори сесії, якщо вони присутні. - `output: "text"` трактує stdout як фінальну відповідь. Режими введення: -- `input: "arg"` (типово) передає prompt як останній аргумент CLI. -- `input: "stdin"` надсилає prompt через stdin. -- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. +- `input: "arg"` (типово) передає промпт як останній аргумент CLI. +- `input: "stdin"` надсилає промпт через stdin. +- Якщо промпт дуже довгий і задано `maxPromptArgChars`, використовується stdin. -## Типові значення (належать плагіну) +## Типові значення (керуються плагіном) -Вбудований плагін OpenAI також реєструє типові значення для `codex-cli`: +Вбудований плагін OpenAI також реєструє типове значення для `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -218,7 +218,7 @@ OpenClaw записуватиме base64-зображення у тимчасо - `imageArg: "--image"` - `sessionMode: "existing"` -Вбудований плагін Google також реєструє типові значення для `google-gemini-cli`: +Вбудований плагін Google також реєструє типове значення для `google-gemini-cli`: - `command: "gemini"` - `args: ["--prompt", "--output-format", "json"]` @@ -227,68 +227,68 @@ OpenClaw записуватиме base64-зображення у тимчасо - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Передумова: локальна Gemini CLI має бути встановлена та доступна як +Передумова: локальна Gemini CLI має бути встановлена й доступна як `gemini` у `PATH` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`). -Примітки щодо JSON у Gemini CLI: +Примітки щодо JSON Gemini CLI: -- Текст відповіді зчитується з поля JSON `response`. -- Дані використання беруться зі `stats`, якщо `usage` відсутній або порожній. -- `stats.cached` нормалізується у `cacheRead` OpenClaw. -- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із +- Текст відповіді читається з поля JSON `response`. +- Usage резервно береться з `stats`, коли `usage` відсутній або порожній. +- `stats.cached` нормалізується в OpenClaw `cacheRead`. +- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з `stats.input_tokens - stats.cached`. -Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`). +Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`). -## Типові значення, що належать плагіну +## Типові значення, керовані плагіном -Типові значення CLI-бекенду тепер є частиною поверхні плагіна: +Типові значення CLI-бекендів тепер є частиною поверхні плагіна: - Плагіни реєструють їх через `api.registerCliBackend(...)`. -- `id` бекенду стає префіксом провайдера в model ref. -- Конфігурація користувача в `agents.defaults.cliBackends.` і далі перевизначає типове значення плагіна. -- Очищення конфігурації, специфічне для бекенду, і далі належить плагіну через необов’язковий +- `id` бекенду стає префіксом провайдера в посиланнях на модель. +- Конфігурація користувача в `agents.defaults.cliBackends.` як і раніше перевизначає типове значення плагіна. +- Очищення конфігурації, специфічне для бекенду, як і раніше керується плагіном через необов’язковий хук `normalizeConfig`. ## Bundle MCP overlays CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може -увімкнути згенероване накладання конфігурації MCP за допомогою `bundleMcp: true`. +увімкнути згенерований накладений MCP-конфіг із `bundleMcp: true`. Поточна вбудована поведінка: -- `codex-cli`: без накладання bundle MCP -- `google-gemini-cli`: без накладання bundle MCP +- `codex-cli`: без накладеного bundle MCP +- `google-gemini-cli`: без накладеного bundle MCP Коли bundle MCP увімкнено, OpenClaw: -- запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI -- автентифікує міст за допомогою токена для кожного сеансу (`OPENCLAW_MCP_TOKEN`) -- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу -- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору -- об’єднує їх із будь-яким наявним `--mcp-config` бекенду +- запускає loopback HTTP MCP-сервер, який надає інструменти шлюзу процесу CLI +- автентифікує міст за допомогою токена на рівні сесії (`OPENCLAW_MCP_TOKEN`) +- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу +- завантажує увімкнені bundle-MCP-сервери для поточного робочого простору +- об’єднує їх з наявним `--mcp-config` бекенду - переписує аргументи CLI, щоб передати `--strict-mcp-config --mcp-config ` -Якщо жоден MCP-сервер не ввімкнено, OpenClaw однаково впроваджує strict-конфігурацію, коли +Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно впроваджує строгий конфіг, коли бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими. ## Обмеження - **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у - протокол CLI-бекенду. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають + протокол CLI-бекенду. Бекенди бачать інструменти шлюзу лише тоді, коли вони вмикають `bundleMcp: true`. -- **Стримінг залежить від бекенду.** Деякі бекенди транслюють JSONL; інші буферизують +- **Стримінг залежить від бекенду.** Деякі бекенди транслюють JSONL, інші буферизують до завершення. -- **Структуровані виходи** залежать від формату JSON CLI. -- **Сеанси Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш - структуровано, ніж початковий запуск `--json`. Сеанси OpenClaw однаково працюють +- **Структуровані виходи** залежать від JSON-формату CLI. +- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш + структуровано, ніж початковий запуск `--json`. Сесії OpenClaw все одно працюють нормально. -## Усунення неполадок +## Усунення несправностей - **CLI не знайдено**: задайте `command` як повний шлях. -- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. -- **Немає безперервності сеансу**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює +- **Неправильна назва моделі**: використайте `modelAliases`, щоб зіставити `provider/model` → модель CLI. +- **Немає безперервності сесії**: переконайтеся, що `sessionArg` задано, а `sessionMode` не має значення `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). - **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів). diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index eb5592d2a..9856a030b 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,21 +1,21 @@ --- read_when: - - Потрібна точна семантика або значення за замовчуванням для полів конфігурації - - Ви перевіряєте блоки конфігурації каналу, моделі, gateway або інструментів + - Вам потрібна точна семантика або значення за замовчуванням для полів конфігурації + - Ви перевіряєте блоки конфігурації каналів, моделей, шлюзу або інструментів summary: Повний довідник для кожного ключа конфігурації OpenClaw, значень за замовчуванням і налаштувань каналів title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-06T12:47:39Z" + generated_at: "2026-04-06T15:34:37Z" model: gpt-5.4 provider: openai - source_hash: 67e3197e2dca37f43285b8aa0e5c77ef1662e1ba28ee874d4e7cbc90e6160ca3 + source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128 source_path: gateway/configuration-reference.md workflow: 15 --- # Довідник з конфігурації -Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду за завданнями див. [Configuration](/uk/gateway/configuration). +Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. @@ -23,34 +23,34 @@ x-i18n: ## Канали -Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`). +Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). -### Доступ до DM і груп +### Доступ до приватних повідомлень і груп -Усі канали підтримують політики DM і політики груп: +Усі канали підтримують політики для приватних повідомлень і груп: -| Політика DM | Поведінка | -| ------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код зв’язування; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених після зв’язування) | -| `open` | Дозволити всі вхідні DM (потрібен `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| Політика DM | Поведінка | +| ------------------- | ------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів сполучення) | +| `open` | Дозволити всі вхідні приватні повідомлення (потребує `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні приватні повідомлення | -| Політика груп | Поведінка | -| --------------------- | ----------------------------------------------------- | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених для груп (обмеження за згадуванням усе ще застосовується) | -| `disabled` | Блокувати всі повідомлення груп/кімнат | +| Політика груп | Поведінка | +| -------------------- | ------------------------------------------------------ | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `open` | Обійти списки дозволених груп (фільтрація за згадуваннями все одно застосовується) | +| `disabled` | Блокувати всі повідомлення в групах/кімнатах | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` у провайдера не встановлено. -Коди зв’язування спливають через 1 годину. Кількість очікуючих запитів на зв’язування DM обмежена **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` встановлює значення за замовчуванням, коли `groupPolicy` у провайдера не задано. +Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп у runtime повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску. -### Перевизначення моделі для каналу +### Перевизначення моделі для каналів -Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналів застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`). ```json5 { @@ -71,7 +71,7 @@ x-i18n: } ``` -### Типові значення каналів і heartbeat +### Типові значення для каналів і heartbeat Використовуйте `channels.defaults` для спільної поведінки політики груп і heartbeat у різних провайдерів: @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/потоків/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитат/відповідей). Перевизначення на рівні каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати стани справних каналів у вивід heartbeat. -- `channels.defaults.heartbeat.showAlerts`: включати стани деградації/помилок у вивід heartbeat. -- `channels.defaults.heartbeat.useIndicator`: виводити компактний heartbeat у стилі індикатора. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не задано. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (як `allowlist`, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати здорові стани каналів у вивід heartbeat. +- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові стани у вивід heartbeat. +- `channels.defaults.heartbeat.useIndicator`: відображати компактний heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через веб-канал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через вебканал шлюзу (Baileys Web). Він запускається автоматично, коли існує пов’язана сесія. ```json5 { @@ -150,10 +150,10 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він } ``` -- Вихідні команди за замовчуванням використовують обліковий запис `default`, якщо він є; інакше — перший налаштований `account id` (у відсортованому порядку). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей вибір типового облікового запису, якщо він відповідає налаштованому `account id`. -- Застарілий однообліковий каталог автентифікації Baileys переноситься командою `openclaw doctor` у `whatsapp/default`. -- Перевизначення для окремих облікових записів: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований `account id` (відсортований). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. +- Застарілий каталог автентифікації Baileys для одного облікового запису переноситься `openclaw doctor` у `whatsapp/default`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -176,19 +176,19 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він "99": { requireMention: false, skills: ["search"], - systemPrompt: "Тримайся теми.", + systemPrompt: "Дотримуйся теми.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git-резервна копія" }, + { command: "backup", description: "Резервна копія Git" }, { command: "generate", description: "Створити зображення" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникати обмежень частоти для редагування попереднього перегляду) + streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникнути обмежень rate limit на попередній перегляд і редагування) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. -- У багатооблікових конфігураціях (2+ `account id`) задайте явний типовий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення невалідне. -- `configWrites: false` блокує ініційовані через Telegram записи в конфігурацію (міграції ID supergroup, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форумів (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоку Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), з `TELEGRAM_BOT_TOKEN` як резервом для облікового запису за замовчуванням. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. +- У багатооблікових конфігураціях (2+ `account id`) задайте явний типово вибраний обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення невалідне. +- `configWrites: false` блокує ініційовані Telegram записи в конфігурацію (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд стриму в Telegram використовує `sendMessage` + `editMessageText` (працює в приватних і групових чатах). - Політика повторних спроб: див. [Retry policy](/uk/concepts/retry). ### Discord @@ -283,7 +283,7 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in для `sessions_spawn({ thread: true })` + spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -319,34 +319,34 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, із `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. -- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; числові ID без префікса відхиляються. -- Slug guild — у нижньому регістрі, з пробілами, заміненими на `-`; ключі каналів використовують slug-ім’я (без `#`). Віддавайте перевагу ID guild. -- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення для каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). -- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до потоків Discord: - - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до потоків (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` та прив’язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного зняття фокуса після неактивності в годинах (`0` вимикає) +- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервом для облікового запису за замовчуванням. +- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик для облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. +- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; прості числові ID відхиляються. +- Slug-и guild мають бути в нижньому регістрі з пробілами, заміненими на `-`; ключі каналів використовують slug-ім’я (без `#`). Віддавайте перевагу ID guild. +- Повідомлення, створені ботами, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення від ботів, які згадують бота (власні повідомлення все одно фільтруються). +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення навіть якщо вони менші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного unfocus через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: opt-in перемикач для автоматичного створення/прив’язки потоку `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і потоків (використовуйте ID каналу/потоку в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів Discord components v2. -- `channels.discord.voice` вмикає розмови у голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. + - `spawnSubagentSessions`: прапорець opt-in для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте channel/thread id у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` встановлює акцентний колір для контейнерів Discord components v2. +- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. - `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw додатково намагається відновити приймання голосу, виходячи та повторно приєднуючись до голосової сесії після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. -- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінними ім’ям/тегом (режим аварійної сумісності). -- `channels.discord.execApprovals`: нативна доставка погоджень exec у Discord і авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли approvers можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати запити exec. Якщо пропущено, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. +- OpenClaw також намагається відновити прийом голосу, виходячи й знову приєднуючись до голосової сесії після повторних помилок дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму стриму. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. +- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним ім’ям/тегом (режим сумісності break-glass). +- `channels.discord.execApprovals`: доставка схвалень exec у нативному форматі Discord та авторизація схвалювачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено схвалювати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо не вказано, пересилаються схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає їх у DM approver’ам, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Якщо target включає `"channel"`, кнопками можуть користуватися лише визначені approver’и. - - `cleanupAfterResolve`: коли `true`, видаляє DM із погодженням після схвалення, відмови або тайм-ауту. + - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає у DM схвалювачам, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли `target` включає `"channel"`, кнопки можуть використовувати лише визначені схвалювачі. + - `cleanupAfterResolve`: якщо `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту. **Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). @@ -379,11 +379,11 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він } ``` -- JSON сервісного облікового запису: вбудований (`serviceAccount`) або з файла (`serviceAccountFile`). -- Також підтримується SecretRef для сервісного облікового запису (`serviceAccountRef`). +- JSON облікового запису сервісу: вбудований (`serviceAccount`) або через файл (`serviceAccountFile`). +- Також підтримується SecretRef для облікового запису сервісу (`serviceAccountRef`). - Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Використовуйте `spaces/` або `users/` як цілі доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email principal (режим аварійної сумісності). +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email principal (режим сумісності break-glass). ### Slack @@ -434,7 +434,7 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він textChunkLimit: 4000, chunkMode: "length", streaming: "partial", // off | partial | block | progress (режим попереднього перегляду) - nativeStreaming: true, // використовувати нативний API потокової передачі Slack, коли streaming=partial + nativeStreaming: true, // використовувати нативний Slack streaming API, коли streaming=partial mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,34 +448,34 @@ WhatsApp працює через веб-канал gateway (Baileys Web). Він } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного підхоплення зі змінних середовища типового облікового запису). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (на корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні +- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резерв із env для облікового запису за замовчуванням). +- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або на рівні облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу для кожного - облікового запису, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode — +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштовано через SecretRef, але поточний шлях команди/runtime не зміг + налаштований через SecretRef, але поточний шлях команди/runtime не зміг отримати значення секрету. -- `configWrites: false` блокує ініційовані через Slack записи в конфігурацію. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. -- `channels.slack.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. +- `configWrites: false` блокує ініційовані Slack записи в конфігурацію. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. +- `channels.slack.streaming` — канонічний ключ режиму стриму. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються. - Використовуйте `user:` (DM) або `channel:` як цілі доставки. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій потоків:** `thread.historyScope` — окремо для потоку (типово) або спільно для каналу. `thread.inheritParent` копіює розшифровку батьківського каналу в нові потоки. +**Ізоляція сесій у гілках:** `thread.historyScope` — на рівні гілки (типово) або спільна в межах каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові гілки. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна доставка погоджень exec у Slack і авторизація тих, хто погоджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім прибирає її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: доставка схвалень exec у нативному форматі Slack та авторизація схвалювачів. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------- | -------- | ----------------------- | -| reactions | увімкнено | Реакції + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріпити/відкріпити/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких emoji | +| Група дій | Типово | Примітки | +| ----------- | ------- | ---------------------- | +| reactions | увімкнено | Реагувати + перелік реакцій | +| messages | увімкнено | Читати/надсилати/редагувати/видаляти | +| pins | увімкнено | Закріпити/відкріпити/перелік | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список кастомних emoji | ### Mattermost @@ -499,7 +499,7 @@ Mattermost постачається як plugin: `openclaw plugins install @open native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Необов’язкова явна URL-адреса для розгортань через reverse proxy/публічних розгортань + // Необов’язковий явний URL для reverse proxy/публічних розгортань callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,23 +509,23 @@ Mattermost постачається як plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на згадування через @, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з тригерного префікса). +Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (на кожне повідомлення), `onchar` (на повідомлення, що починаються з префікса-тригера). -Коли нативні команди Mattermost увімкнені: +Коли увімкнені нативні команди Mattermost: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. -- `commands.callbackUrl` має вказувати на endpoint gateway OpenClaw і бути доступним із сервера Mattermost. -- Нативні callbacks slash-команд автентифікуються токенами для кожної команди, які - Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або не - активовано жодної команди, OpenClaw відхиляє callbacks із повідомленням +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. +- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути досяжним із сервера Mattermost. +- Нативні callback-и slash-команд автентифікуються за допомогою токенів кожної команди, які + Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдасться або жодні + команди не будуть активовані, OpenClaw відхилить callback-и з `Unauthorized: invalid command token.` -- Для приватних/tailnet/internal хостів callback Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив callback host/domain. - Використовуйте значення host/domain, а не повні URL-адреси. -- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані через Mattermost записи в конфігурацію. +- Для приватних/tailnet/внутрішніх хостів callback-ів Mattermost може вимагати, + щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а. + Використовуйте значення хоста/домену, а не повні URL. +- `channels.mattermost.configWrites`: дозволяти або забороняти ініційовані Mattermost записи в конфігурацію. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадуваннями для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. ### Signal @@ -549,12 +549,12 @@ Mattermost постачається як plugin: `openclaw plugins install @open **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). - `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити ініційовані через Signal записи в конфігурацію. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- `channels.signal.configWrites`: дозволяти або забороняти ініційовані Signal записи в конфігурацію. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. ### BlueBubbles -BlueBubbles — рекомендований шлях для iMessage (на базі plugin, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях для iMessage (на основі plugin, налаштовується під `channels.bluebubbles`). ```json5 { @@ -562,7 +562,7 @@ BlueBubbles — рекомендований шлях для iMessage (на ба bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, керування групами та розширені дії: + // serverUrl, password, webhookPath, керування групами й розширені дії: // див. /channels/bluebubbles }, }, @@ -570,13 +570,13 @@ BlueBubbles — рекомендований шлях для iMessage (на ба ``` - Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. - Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте BlueBubbles handle або target string (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). +- Повна конфігурація каналу BlueBubbles описана в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. +OpenClaw запускає `imsg rpc` (JSON-RPC поверх stdio). Демон або порт не потрібні. ```json5 { @@ -600,14 +600,14 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. -- Потрібен Full Disk Access до БД Messages. +- Потребує Full Disk Access до БД Messages. - Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. - `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ relay-host уже є в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити ініційовані через iMessage записи в конфігурацію. +- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ relay-хоста вже є в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволяти або забороняти ініційовані iMessage записи в конфігурацію. - Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює через extension і налаштовується в `channels.matrix`. +Matrix працює через extension і налаштовується під `channels.matrix`. ```json5 { @@ -651,24 +651,25 @@ Matrix працює через extension і налаштовується в `cha } ``` -- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.allowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і `allowPrivateNetwork` — незалежні механізми керування. +- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем — `userId` + `password`. +- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей opt-in для мережі — незалежні елементи керування. - `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.execApprovals`: нативна доставка погоджень exec у Matrix і авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли approvers можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено погоджувати запити exec. - - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: доставка схвалень exec у нативному форматі Matrix та авторизація схвалювачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати exec-запити. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо не вказано, пересилаються схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення для окремих облікових записів: `channels.matrix.accounts..execApprovals`. + - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і пошук у live directory використовують ту саму політику proxy, що й трафік runtime. -- Повну конфігурацію Matrix, правила адресації та приклади налаштування описано в [Matrix](/uk/channels/matrix). +- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику proxy, що й runtime-трафік. +- Повна конфігурація Matrix, правила адресації та приклади налаштування описані в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює через extension і налаштовується в `channels.msteams`. +Microsoft Teams працює через extension і налаштовується під `channels.msteams`. ```json5 { @@ -676,7 +677,7 @@ Microsoft Teams працює через extension і налаштовуєтьс msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, політики команд/каналів: + // appId, appPassword, tenantId, webhook, політики team/channel: // див. /channels/msteams }, }, @@ -684,11 +685,11 @@ Microsoft Teams працює через extension і налаштовуєтьс ``` - Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих команд/каналів) описано в [Microsoft Teams](/uk/channels/msteams). +- Повна конфігурація Teams (облікові дані, webhook, політика DM/груп, перевизначення для команди/каналу) описана в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює через extension і налаштовується в `channels.irc`. +IRC працює через extension і налаштовується під `channels.irc`. ```json5 { @@ -710,12 +711,12 @@ IRC працює через extension і налаштовується в `channe ``` - Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому `account id`. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадуванням) описано в [IRC](/uk/channels/irc). +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`. +- Повна конфігурація каналу IRC (host/port/TLS/channels/allowlists/фільтрація за згадуваннями) описана в [IRC](/uk/channels/irc). ### Багатообліковість (усі канали) -Запускайте кілька облікових записів для одного каналу (кожен зі своїм `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -727,7 +728,7 @@ IRC працює через extension і налаштовується в `channe botToken: "123456:ABC...", }, alerts: { - name: "Бот для сповіщень", + name: "Бот сповіщень", botToken: "987654:XYZ...", }, }, @@ -737,27 +738,27 @@ IRC працює через extension і налаштовується в `channe ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени зі змінних середовища застосовуються лише до **типового** облікового запису. -- Базові параметри каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. +- Токени з env застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені на рівні облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або онбординг каналу), поки конфігурація каналу ще однооблікова на верхньому рівні, OpenClaw спочатку переносить account-scoped значення верхнього рівня для однооблікової конфігурації в карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Для більшості каналів вони переміщуються в `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. -- Наявні прив’язки лише для каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з `accountId` залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи account-scoped однооблікові значення верхнього рівня в підвищений обліковий запис, обраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/default ціль. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), коли ще використовується однокористувацька конфігурація верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня, що стосуються одного облікового запису, у карту облікових записів каналу, щоб оригінальний обліковий запис продовжив працювати. Для більшості каналів вони переміщуються в `channels..accounts.default`; Matrix може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише каналу (без `accountId`) і далі збігаються з обліковим записом за замовчуванням; прив’язки на рівні облікового запису лишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня, що належать одному обліковому запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/типову ціль. -### Інші канали extension +### Інші extension-канали -Багато каналів extension налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). -Див. повний індекс каналів: [Channels](/uk/channels). +Багато extension-каналів налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадуванням у групових чатах +### Фільтрація за згадуваннями в групових чатах -Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні шаблони regex). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-патерни). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Невалідні шаблони й небезпечні вкладені повтори ігноруються. -- Обмеження за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадки або хоча б один шаблон). +- **Metadata mentions**: нативні @-згадки платформи. Ігноруються в режимі self-chat у WhatsApp. +- **Text patterns**: безпечні regex-патерни в `agents.list[].groupChat.mentionPatterns`. Невалідні патерни й небезпечні вкладені повторення ігноруються. +- Фільтрація за згадуваннями застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один патерн). ```json5 { @@ -770,9 +771,9 @@ IRC працює через extension і налаштовується в `channe } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` встановлює глобальне значення за замовчуванням. Канали можуть перевизначити його через `channels..historyLimit` (або на рівні облікового запису). Задайте `0`, щоб вимкнути. -#### Ліміти історії DM +#### Ліміти історії для DM ```json5 { @@ -787,13 +788,13 @@ IRC працює через extension і налаштовується в `channe } ``` -Розв’язання: перевизначення для окремого DM → типове значення провайдера → без ліміту (зберігається все). +Розв’язання: перевизначення для конкретного DM → типове значення провайдера → без ліміту (зберігається все). -Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, реагує лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові патерни): ```json5 { @@ -819,13 +820,13 @@ IRC працює через extension і налаштовується в `channe ```json5 { commands: { - native: "auto", // реєструвати нативні команди там, де це підтримується + native: "auto", // реєструвати нативні команди, коли підтримується text: true, // розбирати /commands у повідомленнях чату - bash: false, // дозволити ! (псевдонім: /bash) + bash: false, // дозволити ! (аліас: /bash) bashForegroundMs: 2000, config: false, // дозволити /config debug: false, // дозволити /debug - restart: false, // дозволити /restart + інструмент перезапуску gateway + restart: false, // дозволити /restart + інструмент перезапуску шлюзу allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -835,28 +836,28 @@ IRC працює через extension і налаштовується в `channe } ``` - + -- Текстові команди мають бути **окремими** повідомленнями з початковим `/`. +- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`. - `native: "auto"` вмикає нативні команди для Discord/Telegram, але залишає Slack вимкненим. -- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищує раніше зареєстровані команди. -- `channels.telegram.customCommands` додає додаткові записи в меню бота Telegram. -- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів із правом запису. -- `channels..configWrites` контролює мутації конфігурації для кожного каналу (типово: true). -- Для багатооблікових каналів `channels..accounts..configWrites` також контролює записи, що націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналу/зв’язування та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. +- Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. +- `channels.telegram.customCommands` додає додаткові пункти меню бота Telegram. +- `bash: true` вмикає `! ` для shell хоста. Потребує `tools.elevated.enabled` і того, щоб відправник був у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи через `/config set|unset` також потребують `operator.admin`; read-only `/config show` лишається доступним для звичайних операторських клієнтів із правом запису. +- `channels..configWrites` керує мутаціями конфігурації на рівні каналу (типово: true). +- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `allowFrom` задається для кожного провайдера. Якщо вказано, це **єдине** джерело авторизації (списки дозволених/сполучення каналу і `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики access group, коли `allowFrom` не задано. --- -## Типові налаштування агентів +## Типові значення агентів ### `agents.defaults.workspace` -Типово: `~/.openclaw/workspace`. +Типове значення: `~/.openclaw/workspace`. ```json5 { @@ -866,7 +867,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, підіймаючись угору від workspace. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt-а. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від workspace. ```json5 { @@ -892,15 +893,15 @@ IRC працює через extension і налаштовується в `channe } ``` -- Пропустіть `agents.defaults.skills`, щоб типово Skills не обмежувалися. +- Пропустіть `agents.defaults.skills`, щоб типово дозволити всі Skills без обмежень. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Задайте `agents.list[].skills: []`, щоб не мати Skills. -- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він +- Задайте `agents.list[].skills: []`, щоб не було жодних Skills. +- Непорожній список `agents.list[].skills` є кінцевим набором для цього агента; він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` -Вимикає автоматичне створення файлів bootstrap workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -910,9 +911,9 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.contextInjection` -Керує тим, коли файли bootstrap workspace вбудовуються в системний prompt. Типово: `"always"`. +Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після compacting усе одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt-а. Запуски heartbeat і повторні спроби після compaction усе одно перебудовують контекст. ```json5 { @@ -922,7 +923,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на файл bootstrap workspace до обрізання. Типово: `20000`. +Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типове значення: `20000`. ```json5 { @@ -932,7 +933,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються з усіх файлів bootstrap workspace. Типово: `150000`. +Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типове значення: `150000`. ```json5 { @@ -942,12 +943,12 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли контекст bootstrap обрізається. -Типово: `"once"`. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. +Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний prompt. -- `"once"`: вбудовувати попередження один раз на кожну унікальну сигнатуру обрізання (рекомендовано). -- `"always"`: вбудовувати попередження при кожному запуску, коли є обрізання. +- `"off"`: ніколи не вставляти текст попередження в системний prompt. +- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -957,10 +958,10 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. -Типово: `1200`. +Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. +Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-token і розмір корисного навантаження запиту для сценаріїв із великою кількістю скриншотів. +Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скріншотів. Більші значення зберігають більше візуальних деталей. ```json5 @@ -971,7 +972,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt-а (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -981,7 +982,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.timeFormat` -Формат часу в системному prompt. Типово: `auto` (налаштування ОС). +Формат часу в системному prompt-і. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1035,42 +1036,42 @@ IRC працює через extension і налаштовується в `channe ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядкований список резервних. + - Рядкова форма задає лише основну модель. + - Об’єктна форма задає основну модель плюс впорядковані резервні моделі. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як конфігурація vision-model. + - Використовується шляхом інструмента `image` як конфігурація vision-моделі. - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо пропущено, `image_generate` все одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо поле пропущено, `image_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо пропущено, `music_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. + - Якщо поле пропущено, `music_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо пропущено, `video_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. + - Якщо поле пропущено, `video_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео у порядку provider-id. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера. - Вбудований провайдер генерації відео Qwen наразі підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделей. - - Якщо пропущено, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель. + - Якщо поле пропущено, інструмент PDF повертається до `imageModel`, а потім до розв’язаної моделі сесії/типової моделі. - `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується в режимі резервного витягування для інструмента `pdf`. -- `verboseDefault`: типовий рівень деталізації для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`. -- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`. -- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропустите провайдера, OpenClaw спочатку спробує alias, потім унікальний match серед налаштованих провайдерів для точного ID моделі, і лише потім повернеться до налаштованого типового провайдера (застаріла сумісність, тому краще явно використовувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення від видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених моделей для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ID агента) перевизначає за ключами. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. +- `pdfMaxPages`: типова максимальна кількість сторінок, які враховуються в режимі резервного витягування в інструменті `pdf`. +- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. +- `elevatedDefault`: типовий рівень elevated output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропустите провайдера, OpenClaw спершу спробує alias, потім унікальний збіг серед налаштованих провайдерів для цього точного model id, і лише після цього повернеться до типового налаштованого провайдера (застаріла поведінка сумісності, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення з видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: глобальні типові параметри провайдера, застосовані до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Подробиці див. у [Prompt Caching](/uk/reference/prompt-caching). +- Засоби запису конфігурації, які мутують ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. -**Вбудовані скорочені alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення alias** (застосовуються лише коли модель є в `agents.defaults.models`): | Alias | Модель | | ------------------- | -------------------------------------- | @@ -1083,15 +1084,15 @@ IRC працює через extension і налаштовується в `channe | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані alias завжди мають вищий пріоритет за типові. +Ваші налаштовані alias завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x автоматично вмикається режим thinking, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. -Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Задайте `agents.defaults.models["zai/"].params.tool_stream` як `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, якщо не задано явний рівень thinking. +Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI типово вмикають `tool_stream` для стримінгу викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Моделі Anthropic Claude 4.6 типово використовують thinking `adaptive`, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. +Необов’язкові CLI backends для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -1119,8 +1120,8 @@ IRC працює через extension і налаштовується в `channe } ``` -- CLI-бекенди орієнтовані на текст; інструменти завжди вимкнені. -- Сесії підтримуються, якщо задано `sessionArg`. +- CLI backends орієнтовані на текст; інструменти завжди вимкнені. +- Сесії підтримуються, коли задано `sessionArg`. - Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.heartbeat` @@ -1150,13 +1151,13 @@ IRC працює через extension і налаштовується в `channe } ``` -- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. -- `suppressToolErrorWarnings`: коли true, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. -- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та видає `reason=dm-blocked`. -- `lightContext`: коли true, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: коли true, кожен heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeats запускаються **лише для цих агентів**. -- Heartbeats виконують повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. +- `suppressToolErrorWarnings`: якщо true, пригнічує payload-и з попередженнями про помилки інструментів під час запусків heartbeat. +- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і повертає `reason=dm-blocked`. +- `lightContext`: якщо true, heartbeat-запуски використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: якщо true, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у cron `sessionTarget: "isolated"`. Зменшує витрати токенів на heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, heartbeat запускається **лише для цих агентів**. +- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1169,15 +1170,15 @@ IRC працює через extension і налаштовується в `channe timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Зберігайте ID розгортання, ID квитків і пари host:port точно без змін.", // використовується, коли identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + identifierInstructions: "Точно зберігай deployment ID, ticket ID і пари host:port.", // використовується, коли identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну вставку model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction notifyUser: true, // надсилати коротке повідомлення, коли починається compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Сесія наближається до compaction. Збережіть довготривалі спогади зараз.", - prompt: "Запишіть будь-які тривалі нотатки в memory/YYYY-MM-DD.md; дайте точну тиху відповідь токеном NO_REPLY, якщо нічого зберігати.", + systemPrompt: "Сесія наближається до compaction. Збережи тривалі спогади зараз.", + prompt: "Запиши будь-які довготривалі нотатки в memory/YYYY-MM-DD.md; відповідай точним silent token NO_REPLY, якщо зберігати нічого.", }, }, }, @@ -1185,18 +1186,18 @@ IRC працює через extension і налаштовується в `channe } ``` -- `mode`: `default` або `safeguard` (узагальнення довгих історій шматками). Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типово: `900`. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. -- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які слід повторно вбудувати після compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Якщо не встановлено або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має працювати на одній моделі, а підсумки compaction — на іншій; якщо не встановлено, compaction використовує основну модель сесії. -- `notifyUser`: коли `true`, надсилає користувачу коротке сповіщення, коли починається compaction (наприклад, "Compacting context..."). За замовчуванням вимкнено, щоб compaction залишався тихим. -- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження довготривалих спогадів. Пропускається, коли workspace лише для читання. +- `mode`: `default` або `safeguard` (підсумовування шматками для довгої історії). Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволених для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки зі збереження непрозорих ідентифікаторів під час підсумовування compaction. +- `identifierInstructions`: необов’язковий користувацький текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 у AGENTS.md, які повторно вставляються після compaction. Типово `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторну вставку. Якщо не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як legacy fallback. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має лишатися на одній моделі, а підсумки compaction мають створюватися на іншій; якщо не задано, compaction використовує основну модель сесії. +- `notifyUser`: якщо `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction відбувався тихо. +- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням у LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1204,7 +1205,7 @@ IRC працює через extension і налаштовується в `channe defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини + ttl: "1h", // тривалість (ms/s/m/h), одиниця за замовчуванням: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1220,25 +1221,25 @@ IRC працює через extension і налаштовується в `channe -- `mode: "cache-ttl"` вмикає проходи pruning. -- `ttl` керує тим, як часто pruning може запускатися знову (після останнього торкання кешу). -- Pruning спочатку м’яко обрізає завеликі результати інструментів, а потім повністю очищує старіші результати інструментів, якщо це потрібно. +- `mode: "cache-ttl"` вмикає проходи обрізання. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко підрізає завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. -**Soft-trim** зберігає початок і кінець, вставляючи `...` посередині. +**М’яке обрізання** зберігає початок + кінець і вставляє `...` посередині. -**Hard-clear** замінює весь результат інструмента заповнювачем. +**Жорстке очищення** замінює весь результат інструмента на заповнювач. Примітки: -- Блоки зображень ніколи не обрізаються й не очищуються. -- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. -- Якщо є менше ніж `keepLastAssistants` повідомлень помічника, pruning пропускається. +- Блоки зображень ніколи не обрізаються/не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Докладніше див. [Session Pruning](/uk/concepts/session-pruning). +Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). -### Блокова потокова передача +### Блочний стримінг ```json5 { @@ -1248,19 +1249,19 @@ IRC працює через extension і налаштовується в `channe blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (використовує minMs/maxMs) }, }, } ``` -- Для каналів, окрім Telegram, потрібен явний `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Канали, відмінні від Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блочні відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти на рівні облікового запису). Signal/Slack/Discord/Google Chat типово використовують `minChars: 1500`. +- `humanDelay`: випадкова пауза між блочними відповідями. `natural` = 800–2500ms. Перевизначення для агента: `agents.list[].humanDelay`. -Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про поведінку та деталі chunking. +Деталі поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming). -### Індикатори набору тексту +### Індикатори введення ```json5 { @@ -1328,7 +1329,7 @@ IRC працює через extension і налаштовується в `channe identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Також підтримуються SecretRefs / вбудований вміст: + // Також підтримуються SecretRef / вбудований вміст: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1377,50 +1378,50 @@ IRC працює через extension і налаштовується в `channe } ``` - + -**Бекенд:** +**Backend:** - `docker`: локальний runtime Docker (типово) -- `ssh`: загальний віддалений runtime на базі SSH +- `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація SSH backend:** - `target`: SSH-ціль у форматі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, який використовується для workspace за scope +- `workspaceRoot`: абсолютний віддалений корінь, який використовується для workspace кожного scope - `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час runtime - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет автентифікації SSH:** +**Пріоритет SSH auth:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на базі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox +- Значення `*Data`, що використовують SecretRef, розв’язуються з активного знімка runtime секретів до початку sandbox-сесії -**Поведінка SSH-бекенда:** +**Поведінка SSH backend:** -- один раз засіває віддалений workspace після створення або перевідтворення -- потім підтримує віддалений SSH-workspace як канонічний -- маршрутизує `exec`, файлові інструменти та media-шляхи через SSH +- один раз ініціалізує віддалений workspace після створення або перевідтворення +- після цього підтримує віддалений SSH workspace як канонічний +- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує браузерні контейнери sandbox +- не підтримує browser-контейнери в sandbox **Доступ до workspace:** -- `none`: workspace sandbox за scope під `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано тільки для читання в `/agent` -- `rw`: workspace агента змонтовано для читання/запису в `/workspace` +- `none`: sandbox workspace для кожного scope під `~/.openclaw/sandboxes` +- `ro`: sandbox workspace у `/workspace`, workspace агента монтується як лише для читання в `/agent` +- `rw`: workspace агента монтується з читанням/записом у `/workspace` **Scope:** -- `session`: окремий контейнер + workspace для кожної сесії +- `session`: окремий контейнер + workspace на сесію - `agent`: один контейнер + workspace на агента (типово) - `shared`: спільний контейнер і workspace (без ізоляції між сесіями) @@ -1452,30 +1453,30 @@ IRC працює через extension і налаштовується в `channe **Режим OpenShell:** -- `mirror`: засіяти remote з local перед exec, синхронізувати назад після exec; local workspace лишається канонічним -- `remote`: засіяти remote один раз при створенні sandbox, потім підтримувати remote workspace як канонічний +- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний workspace лишається канонічним +- `remote`: один раз ініціалізує віддалене середовище, коли sandbox створюється, а далі віддалений workspace лишається канонічним -У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після кроку засівання. -Транспорт — це SSH у sandbox OpenShell, але plugin володіє життєвим циклом sandbox і необов’язковою синхронізацією mirror. +У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації. +Транспорт — SSH у sandbox OpenShell, але plugin керує життєвим циклом sandbox та необов’язковою mirror-синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, доступний для запису root і root user. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного root і користувача root. -**Для контейнерів типовим є `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід у мережу. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). +**Контейнери типово використовують `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід назовні. +`"host"` блокується. `"container:"` типово блокується, якщо ви явно не встановите +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. +**Вхідні вкладення** тимчасово розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні й агентні `binds` об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки на рівні агента об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб розкривати пароль у спільному URL). +**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ для спостереження через noVNC типово використовує VNC auth, і OpenClaw видає короткоживучий token URL (замість того, щоб показувати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує націлювання на браузер хоста із sandbox-сесій. -- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна загальна bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхід до CDP на межі контейнера CIDR-діапазоном (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо встановлено (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску задано в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: +- `allowHostControl: false` (типово) блокує sandbox-сесіям доступ до браузера хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (окрема bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. +- `cdpSourceRange` необов’язково обмежує доступ до CDP на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox browser. Якщо задано (включно з `[]`), замінює `docker.binds` для browser-контейнера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1492,31 +1493,31 @@ IRC працює через extension і налаштовується в `channe - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (типово увімкнено) + - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово увімкнені й можуть бути вимкнені через + типово увімкнені, їх можна вимкнути за допомогою `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо ваш робочий процес - від них залежить. + залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; задайте `0`, щоб використати - типове обмеження процесів Chromium. - - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; використовуйте власний browser image з власною + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; задайте `0`, щоб використовувати + типове обмеження Chromium. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення — це базова конфігурація образу контейнера; використовуйте власний browser image з власним entrypoint, щоб змінити типові параметри контейнера. -Sandboxing браузера і `sandbox.docker.binds` наразі доступні лише для Docker. +Browser sandboxing і `sandbox.docker.binds` наразі працюють лише з Docker. Зібрати образи: ```bash -scripts/sandbox-setup.sh # основний образ sandbox -scripts/sandbox-browser-setup.sh # необов’язковий образ браузера +scripts/sandbox-setup.sh # основний sandbox image +scripts/sandbox-browser-setup.sh # необов’язковий browser image ``` -### `agents.list` (перевизначення для окремого агента) +### `agents.list` (перевизначення на рівні агента) ```json5 { @@ -1529,14 +1530,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } - thinkingDefault: "high", // перевизначення рівня thinking для окремого агента - reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента - fastModeDefault: false, // перевизначення fast mode для окремого агента - params: { cacheRetention: "none" }, // перевизначає ключі matching defaults.models params - skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано + thinkingDefault: "high", // перевизначення рівня thinking для агента + reasoningDefault: "on", // перевизначення видимості reasoning для агента + fastModeDefault: false, // перевизначення fast mode для агента + params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем + skills: ["docs-search"], // замінює agents.defaults.skills, коли задано identity: { name: "Samantha", - theme: "кориснивий лінивець", + theme: "helpful sloth", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1565,23 +1566,23 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ``` - `id`: стабільний ID агента (обов’язково). -- `default`: якщо встановлено для кількох, перший перемагає (із попередженням у журналі). Якщо не встановлено ні для кого, типовим стає перший елемент списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallbacks). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallbacks, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для агентних перевизначень, наприклад `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо він заданий; явний список замінює типові значення, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення або сесії. -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast-mode для окремого повідомлення або сесії. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії ACP harness. -- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `default`: якщо задано для кількох, перший перемагає (у лог записується попередження). Якщо не задано ніде, типовим є перший елемент списку. +- `model`: рядкова форма перевизначає лише `primary`; об’єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback-и). Cron jobs, які перевизначають лише `primary`, усе одно успадковують типові fallback-и, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку на рівні агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень на кшталт `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли їх задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення на рівні повідомлення або сесії. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning на рівні повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення fast mode (`true | false`). Застосовується, коли не задано перевизначення fast mode на рівні повідомлення або сесії. +- `runtime`: необов’язковий дескриптор runtime на рівні агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP harness sessions. +- `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. - `subagents.allowAgents`: список дозволених ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які виконувалися б без sandbox. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія-запитувач ізольована в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn` без `agentId` (примушує явно вибирати профіль; типово false). --- -## Маршрутизація з кількома агентами +## Багатоагентна маршрутизація Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). @@ -1600,27 +1601,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля match для binding +### Поля збігу прив’язки - `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` за замовчуванням означає route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = обліковий запис за замовчуванням) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) - `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок match:** +**Детермінований порядок збігу:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (на рівні каналу) -6. Типовий агент +5. `match.accountId: "*"` (на весь канал) +6. Агент за замовчуванням У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route binding, описаний вище. +Для записів `type: "acp"` OpenClaw виконує пошук за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує вищенаведений рівневий порядок прив’язок route. ### Профілі доступу для окремих агентів @@ -1671,7 +1672,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1717,11 +1718,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Деталі пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Подробиці пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- -## Сесія +## Session ```json5 { @@ -1743,7 +1744,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропустити fork батьківського потоку вище цього числа токенів (0 вимикає) + parentForkMaxTokens: 100000, // пропустити fork від батьківської гілки вище цього числа токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1755,7 +1756,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, threadBindings: { enabled: true, - idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) + idleHours: 24, // типове автоматичне unfocus через неактивність у годинах (`0` вимикає) maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) }, mainKey: "main", // застаріле (runtime завжди використовує "main") @@ -1768,43 +1769,43 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. +- **`scope`**: базова стратегія групування сесій для контекстів групових чатів. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст справді потрібен). + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM використовують спільну головну сесію. + - `main`: усі DM спільно використовують основну сесію. - `per-peer`: ізоляція за ID відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багато користувацьких inbox). + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатоадресних inbox). - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). -- **`identityLinks`**: мапа канонічних ID до peers із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` — після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що закінчується раніше. -- **`resetByType`**: перевизначення для окремих типів (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений при створенні forked thread session (типово `100000`). - - Якщо `totalTokens` батьківської сесії вищий за це значення, OpenClaw запускає нову thread session замість успадкування історії transcript батьківської сесії. - - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти parent forking. -- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для головного кошика direct-chat. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у форматі reply-back між агентами під час agent-to-agent обміну (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. -- **`sendPolicy`**: match за `channel`, `chatType` (`direct|group|channel`, зі старим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша відмова перемагає. -- **`maintenance`**: очищення сховища сесій + керування строком зберігання. +- **`identityLinks`**: відображення канонічних ID на peers із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує той, що спливає першим. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. +- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення forked thread session (типово `100000`). + - Якщо батьківський `totalTokens` вищий за це значення, OpenClaw запускає нову thread session замість успадкування історії транскрипту батьківської сесії. + - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти форк від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для основного кошика direct-chat. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість взаємних ходів відповіді між агентами під час agent-to-agent обміну (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. +- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, з legacy alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона перемагає. +- **`maintenance`**: керування очищенням і зберіганням session store. - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: граничний вік для застарілих записів (типово `30d`). + - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` він лише пише попередження в журнал; у режимі `enforce` він спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. - - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) + - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`). + - `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` лише логує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до гілок. + - `enabled`: головний прапорець за замовчуванням (провайдери можуть перевизначити; Discord використовує `channels.discord.threadBindings.enabled`) + - `idleHours`: типове автоматичне unfocus через неактивність у годинах (`0` вимикає; провайдери можуть перевизначити) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначити) --- -## Повідомлення +## Messages ```json5 { @@ -1836,36 +1837,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Префікс відповіді -Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення на рівні каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Розв’язання (найспецифічніше перемагає): account → channel → global. `""` вимикає та зупиняє каскад. `"auto"` виводиться як `[{identity.name}]`. +Розв’язання (перемагає найконкретніше): account → channel → global. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. -**Змінні шаблону:** +**Шаблонні змінні:** -| Змінна | Опис | Приклад | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | --------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Ім’я ідентичності агента | (те саме, що `"auto"`) | +| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. -### Реакція підтвердження +### Реакція-підтвердження - Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок розв’язання: account → channel → `messages.ackReaction` → резервне значення з identity. +- Порядок розв’язання: account → channel → `messages.ackReaction` → резерв із identity. - Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє ack після відповіді у Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції життєвого циклу статусу у Slack, Discord і Telegram. - У Slack і Discord відсутнє значення зберігає status reactions увімкненими, коли активні ack reactions. - У Telegram явно задайте `true`, щоб увімкнути status reactions. +- `removeAckAfterReply`: прибирає ack після відповіді в Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції життєвого циклу статусу в Slack, Discord і Telegram. + У Slack і Discord, якщо не задано, статусні реакції залишаються увімкненими, коли активні ack-реакції. + У Telegram встановіть це явно в `true`, щоб увімкнути статусні реакції життєвого циклу. ### Вхідний debounce -Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаться негайно. Керівні команди обходять debounce. ### TTS (text-to-speech) @@ -1908,18 +1909,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує автоматичним TTS. `/tts off|always|inbound|tagged` перевизначає це для сесії. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автопідсумку. -- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово `false` (opt-in). -- API keys резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `auto` керує auto-TTS. `/tts off|always|inbound|tagged` перевизначає значення для сесії. +- `summaryModel` перевизначає `agents.defaults.model.primary` для авто-підсумку. +- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (opt-in). +- API key беруться з резерву `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. - `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-compatible TTS server і послаблює перевірку model/voice. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як сумісний з OpenAI TTS server і послаблює перевірку model/voice. --- ## Talk -Типові налаштування для режиму Talk (macOS/iOS/Android). +Типові значення для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1943,51 +1944,51 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, якщо налаштовано кілька Talk-провайдерів. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) сумісні лише для підтримки та автоматично мігруються в `talk.providers.`. -- Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає звичайні рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. -- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні імена. -- `silenceTimeoutMs` визначає, скільки Talk mode чекає після мовчання користувача, перш ніж надіслати transcript. Якщо не задано, використовується типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька Talk-провайдерів. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`. +- Voice ID беруться з резерву `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. +- Резерв `ELEVENLABS_API_KEY` застосовується лише коли API key для Talk не налаштовано. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні імена. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після мовчання користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- -## Інструменти +## Tools ### Профілі інструментів `tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: -Локальний онбординг за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). | Профіль | Включає | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що й відсутність значення) | +| `full` | Без обмежень (те саме, що не задавати) | ### Групи інструментів -| Група | Інструменти | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation`| `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без provider plugins) | +| Група | Інструменти | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (без provider plugin-ів) | ### `tools.allow` / `tools.deny` -Глобальна політика allow/deny для інструментів (deny має вищий пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона перемагає). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть коли Docker sandbox вимкнений. ```json5 { @@ -1997,7 +1998,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.byProvider` -Додатково обмежує інструменти для певних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny. +Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny. ```json5 { @@ -2013,7 +2014,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.elevated` -Керує elevated-доступом до exec поза sandbox: +Керує elevated-доступом exec поза sandbox: ```json5 { @@ -2029,9 +2030,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. -- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). +- Перевизначення для агента (`agents.list[].tools.elevated`) може лише додатково обмежити. +- `/elevated on|off|ask|full` зберігає стан для сесії; inline directives застосовуються до одного повідомлення. +- Elevated `exec` обходить sandbox і використовує налаштований escape path (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2055,8 +2056,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб активувати виявлення. -Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки від циклів інструментів **типово вимкнені**. Встановіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2077,14 +2078,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `historySize`: максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. -- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторів для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. +- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `warningThreshold`: поріг повторюваного патерна без прогресу для попереджень. +- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування шаблонів без прогресу. -- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати про чергування пар без прогресу. +- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2118,7 +2119,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.media` -Налаштовує розуміння вхідного медіаконтенту (зображення/аудіо/відео): +Налаштовує розуміння вхідних медіа (зображення/аудіо/відео): ```json5 { @@ -2126,7 +2127,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: надсилати завершені асинхронні музичні/відеозавдання безпосередньо в канал + directSend: false, // opt-in: надсилати завершені асинхронні задачі music/video безпосередньо в канал }, audio: { enabled: true, @@ -2155,27 +2156,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б **Запис провайдера** (`type: "provider"` або пропущено): - `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення ID моделі +- `model`: перевизначення model id - `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` -**CLI-запис** (`type: "cli"`): +**Запис CLI** (`type: "cli"`): - `command`: виконуваний файл -- `args`: параметризовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: шаблонні аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки використовується наступний запис. +- Помилки призводять до fallback на наступний запис. -Автентифікація провайдера використовує стандартний порядок: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. +Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Поля async completion:** -- `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типово: `false` - (застарілий шлях пробудження requester-session/model-delivery). +- `asyncCompletion.directSend`: коли `true`, завершені асинхронні задачі `music_generate` + і `video_generate` спочатку намагаються доставитися прямо в канал. Типове значення: `false` + (застарілий шлях requester-session wake/model-delivery). @@ -2194,9 +2195,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.sessions` -Керує тим, які сесії можуть бути цілями для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`). -Типово: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). +Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). ```json5 { @@ -2211,22 +2212,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: -- `self`: лише ключ поточної сесії. +- `self`: лише поточний ключ сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (subagents). -- `agent`: будь-яка сесія, що належить поточному ID агента (може включати інших користувачів, якщо ви використовуєте сесії per-sender під одним ID агента). -- `all`: будь-яка сесія. Націлення між агентами все одно потребує `tools.agentToAgent`. -- Sandbox clamp: коли поточна сесія виконується в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). +- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- Затискач sandbox: коли поточна сесія ізольована і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово стає `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Керує підтримкою вбудованих вкладень для `sessions_spawn`. +Керує підтримкою inline-вкладень для `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: установіть true, щоб дозволити вбудовані вкладення файлів + enabled: false, // opt-in: встановіть true, щоб дозволити inline-вкладення файлів maxTotalBytes: 5242880, // 5 MB сумарно для всіх файлів maxFiles: 50, maxFileBytes: 1048576, // 1 MB на файл @@ -2239,16 +2240,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: -- Вкладення підтримуються лише для `runtime: "subagent"`. ACP runtime їх відхиляє. -- Файли матеріалізуються в child workspace за шляхом `.openclaw/attachments//` з файлом `.manifest.json`. -- Вміст вкладень автоматично редагується з persistence transcript. -- Входи Base64 перевіряються зі строгими правилами alphabet/padding і захистом розміру до декодування. -- Дозволи на файли: `0700` для каталогів і `0600` для файлів. -- Очищення підкоряється політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. +- Файли матеріалізуються в дочірньому workspace під `.openclaw/attachments//` з `.manifest.json`. +- Вміст вкладень автоматично редагується з персистентності транскрипту. +- Входи Base64 перевіряються зі строгими перевірками алфавіту/падінгу і захистом за розміром до декодування. +- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. +- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не діє правило автоматичного ввімкнення, залежне від runtime. +Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не діє правило auto-enable, специфічне для runtime. ```json5 { @@ -2263,8 +2264,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типово: `false` для провайдерів, відмінних від OpenAI. Запуски OpenAI та OpenAI Codex вмикають його автоматично. -- Коли ввімкнено, системний prompt також додає інструкції з використання, щоб модель застосовувала його лише для суттєвої роботи й утримувала не більше одного кроку в стані `in_progress`. +- Типове значення: `false` для не-OpenAI провайдерів. Запуски OpenAI і OpenAI Codex автоматично вмикають його. +- Коли він увімкнений, системний prompt також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала максимум один крок у стані `in_progress`. ### `agents.defaults.subagents` @@ -2284,16 +2285,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `model`: типова модель для spawned sub-agents. Якщо пропущено, sub-agents успадковують модель викликача. -- `allowAgents`: типовий список дозволених ID цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- `model`: типова модель для породжених sub-agents. Якщо не задано, sub-agents успадковують модель викликувача. +- `allowAgents`: типовий список дозволених цільових ID агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає без тайм-ауту. - Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні провайдери та base URL +## Користувацькі провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2322,40 +2323,40 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. -- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет злиття для відповідних ID провайдера: - - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження вже визначених секретів. - - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). - - Порожні або відсутні `apiKey`/`baseUrl` агента резервно беруться з `models.providers` у конфігурації. - - Для відповідних моделей `contextWindow`/`maxTokens` використовується вище значення з явної конфігурації та неявних значень каталогу. - - Для відповідних моделей `contextTokens` зберігає явне runtime-обмеження, якщо воно присутнє; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю перезаписала `models.json`. - - Збереження маркерів є авторитетним відносно джерела: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних runtime-значень секретів. +- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. +- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). +- Пріоритет злиття для однакових provider ID: + - Непорожні значення `baseUrl` в agent `models.json` мають пріоритет. + - Непорожні значення `apiKey` в agent мають пріоритет лише коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` провайдера, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розв’язаних секретів. + - Значення заголовків провайдера, керовані SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). + - Порожні або відсутні `apiKey`/`baseUrl` в agent повертаються до `models.providers` у конфігурації. + - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. + - Для однакових моделей `contextTokens` зберігає явний runtime cap, коли він заданий; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. + - Персистентність маркерів є авторитетною від джерела: маркери записуються з активного знімка вихідної конфігурації (до розв’язання), а не з розв’язаних runtime-значень секретів. ### Деталі полів провайдера -- `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів за ключем provider id. -- `models.providers.*.api`: адаптер запиту (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). +- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). +- `models.providers`: карта користувацьких провайдерів за provider id. +- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). - `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/env substitution). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions`, вставляє `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базова URL upstream API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. +- `models.providers.*.baseUrl`: базовий URL upstream API. +- `models.providers.*.headers`: додаткові статичні заголовки для proxy/tenant routing. - `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (об’єднуються з типовими заголовками провайдера). Значення приймають SecretRef. + - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативне `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/відсутній `baseUrl` зберігає типову поведінку OpenAI. -- `plugins.entries.amazon-bedrock.config.discovery`: кореневі налаштування auto-discovery Bedrock. +- `models.providers.*.models.*.contextWindow`: нативні метадані вікна контексту моделі. +- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. +- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань auto-discovery Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне discovery. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для discovery. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового discovery. @@ -2416,7 +2417,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Встановіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2433,11 +2434,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Встановіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні alias. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` -- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте власного провайдера з перевизначенням base URL. +- Coding endpoint (типовий): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint задайте користувацького провайдера з перевизначенням base URL. @@ -2478,8 +2479,8 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoints Moonshot оголошують сумісність зі streaming usage на спільному -транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями endpoint, +Нативні endpoint-и Moonshot оголошують сумісність використання streaming на спільному +транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями endpoint-а, а не лише за вбудованим provider id. @@ -2498,7 +2499,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2537,7 +2538,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має бути без `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2577,12 +2578,12 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -Установіть `MINIMAX_API_KEY`. Скорочення: +Встановіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. -Каталог моделей тепер типово містить лише M2.7. -На Anthropс-compatible streaming path OpenClaw типово вимикає MiniMax thinking, -якщо ви явно самі не задасте `thinking`. `/fast on` або +Каталог моделей тепер типово включає лише M2.7. +На streaming path, сумісному з Anthropic, OpenClaw типово вимикає thinking MiniMax, +якщо ви явно не задасте `thinking` самі. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2590,7 +2591,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте хостовані моделі в режимі merge як резерв. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному залізі; залишайте hosted-моделі злитими як резерв. @@ -2611,7 +2612,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або звичайний рядок + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або відкритий рядок env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2621,14 +2622,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (managed/workspace Skills не зачіпаються). +- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (managed/workspace Skills не зачіпає). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли true, віддавати перевагу інсталяторам Homebrew, якщо `brew` - доступний, перш ніж повертатися до інших типів інсталяторів. -- `install.nodeManager`: бажаний node installer для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: якщо true, віддавати перевагу встановлювачам Homebrew, коли `brew` + доступний, перш ніж переходити до інших типів встановлювачів. +- `install.nodeManager`: пріоритет node installer для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає Skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручне поле API key для Skills, які оголошують primary env var (звичайний рядок або об’єкт SecretRef). +- `entries..apiKey`: зручне поле API key для Skills, які оголошують основну env var (відкритий рядок або об’єкт SecretRef). --- @@ -2639,24 +2640,4 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й plugins: { enabled: true, allow: ["voice-call"], - deny: [], - load: { - paths: ["~/Projects/oss/voice-call-extension"], - }, - entries: { - "voice-call": { - enabled: true, - hooks: { - allowPromptInjection: false, - }, - config: { provider: "twilio" }, - }, - }, - }, -} -``` - -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. -- Discovery приймає нативні OpenClaw plugins, а також сумісні пакети Codex і Claude, включно з manifestless Claude default-layout bundles. -- **Зміни конфігурації вимагають перезапуску gateway.** -- `allow`: необов’язковий список дозволених (завантажуються лише перелічені plugins). `deny` має вищий \ No newline at end of file + deny: \ No newline at end of file diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index f04790639..738267ac5 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -5,17 +5,18 @@ read_when: summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-06T12:44:06Z" + generated_at: "2026-04-06T15:29:18Z" model: gpt-5.4 provider: openai - source_hash: f20637d373c3b1be7c4a3d5424228908b5639cfded8ad5acb9c29f882d0f8d2b + source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для виправлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі +конфігурації/стан, перевіряє працездатність і надає практичні кроки для відновлення. ## Швидкий старт @@ -23,114 +24,113 @@ x-i18n: openclaw doctor ``` -### Безголовий режим / автоматизація +### Headless / автоматизація ```bash openclaw doctor --yes ``` -Приймає типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно). +Приймає типові значення без запитів (зокрема кроки відновлення restart/service/sandbox, де це застосовно). ```bash openclaw doctor --repair ``` -Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). +Застосовує рекомендовані виправлення без запитів (виправлення + restart там, де це безпечно). ```bash openclaw doctor --repair --force ``` -Застосовує також агресивні виправлення (перезаписує користувацькі конфігурації supervisor). +Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації supervisor). ```bash openclaw doctor --non-interactive ``` -Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людини. +Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії restart/service/sandbox, які потребують підтвердження людиною. Міграції застарілого стану запускаються автоматично, якщо їх виявлено. ```bash openclaw doctor --deep ``` -Сканує системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks). +Сканує системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks). -Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: +Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json ``` -## Що він робить (коротко) +## Що робить команда (підсумок) -- Необов’язкове передстартове оновлення для git-інсталяцій (лише в інтерактивному режимі). -- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). -- Перевірка справності + запит на перезапуск. -- Зведення стану Skills (доступні/відсутні/заблоковані) і стану плагінів. +- Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі). +- Перевірка актуальності UI protocol (перебудовує Control UI, якщо схема protocol новіша). +- Перевірка працездатності + запит на restart. +- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан плагінів. - Нормалізація конфігурації для застарілих значень. -- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. -- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. -- Попередження про перевизначення постачальника OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. +- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. +- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. -- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). -- Міграція застарілих ключів контрактів маніфесту плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні webhook-завдання з `notify: true`). +- Міграція застарілого стану на диску (sessions/каталог агента/автентифікація WhatsApp). +- Міграція застарілих ключів контрактів у маніфестах плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні webhook jobs із `notify: true`). - Перевірка файлів блокування сесій і очищення застарілих блокувань. -- Перевірки цілісності стану та прав доступу (сесії, транскрипти, каталог стану). -- Перевірки прав доступу до файла конфігурації (`chmod 600`) при локальному запуску. -- Справність автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для профілів автентифікації. -- Виявлення додаткового робочого каталогу (`~/openclaw`). -- Відновлення образу пісочниці, коли ізоляцію ввімкнено. +- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). +- Перевірки прав доступу до файлу конфігурації (chmod 600) при локальному запуску. +- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких добігає кінця, і повідомляє про стани cooldown/disabled для auth-profile. +- Виявлення додаткового каталогу workspace (`~/openclaw`). +- Відновлення образу sandbox, якщо sandbox увімкнено. - Міграція застарілих служб і виявлення додаткових gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). -- Перевірки runtime gateway (службу встановлено, але вона не запущена; кешований launchd label). -- Попередження про стан каналів (перевіряються із запущеного gateway). +- Перевірки runtime gateway (службу встановлено, але вона не запущена; кешована мітка launchd). +- Попередження про стан каналів (зондуються із запущеного gateway). - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. -- Перевірки найкращих практик runtime gateway (Node проти Bun, шляхи version manager). +- Перевірки рекомендованих практик runtime gateway (Node проти Bun, шляхи менеджерів версій). - Діагностика конфліктів порту gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. -- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, якщо джерела токена немає; не перезаписує конфігурації токена через SecretRef). +- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, якщо немає його джерела; не перезаписує конфігурації токенів через SecretRef). - Перевірка systemd linger у Linux. -- Перевірка розміру bootstrap-файлів робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). -- Перевірка стану shell completion та автоінсталяція/оновлення. -- Перевірка готовності постачальника embedding для memory search (локальна модель, віддалений API-ключ або бінарник QMD). -- Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарник tsx). +- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до межі для контекстних файлів). +- Перевірка стану shell completion і автоматичне встановлення/оновлення. +- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API key або двійковий файл QMD). +- Перевірки вихідного встановлення (невідповідність pnpm workspace, відсутні UI assets, відсутній двійковий файл tsx). - Записує оновлену конфігурацію + метадані wizard. ## Докладна поведінка та обґрунтування -### 0) Необов’язкове оновлення (git-інсталяції) +### 0) Необов’язкове оновлення (git-встановлення) Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує -оновитися (fetch/rebase/build) перед запуском doctor. +оновити систему (fetch/rebase/build) перед запуском doctor. ### 1) Нормалізація конфігурації -Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` +Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. -Це також включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — -це `talk.provider` + `talk.providers.`. Doctor переписує старі форми +Сюди також входять застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це +`talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` у мапу постачальників. +`talk.apiKey` у мапу провайдерів. ### 2) Міграції застарілих ключів конфігурації -Коли конфігурація містить застарілі ключі, інші команди відмовляються працювати -й просять запустити `openclaw doctor`. +Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися +і просять виконати `openclaw doctor`. Doctor: -- Пояснить, які застарілі ключі було знайдено. -- Покажe міграцію, яку він застосував. -- Перезапише `~/.openclaw/openclaw.json` оновленою схемою. +- Пояснює, які саме застарілі ключі знайдено. +- Показує застосовану міграцію. +- Перезаписує `~/.openclaw/openclaw.json` за оновленою схемою. Gateway також автоматично запускає міграції doctor під час старту, коли виявляє -застарілий формат конфігурації, тож застарілі конфігурації виправляються без -ручного втручання. -Міграції сховища cron завдань обробляються через `openclaw doctor --fix`. +застарілий формат конфігурації, тому старі конфігурації виправляються без ручного втручання. +Міграції сховища cron jobs виконує `openclaw doctor --fix`. Поточні міграції: @@ -154,30 +154,30 @@ Gateway також автоматично запускає міграції doct - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Для каналів з іменованими `accounts`, але зі збереженими верхньорівневими значеннями каналу для одиничного акаунта, перемістити ці значення, прив’язані до акаунта, у підвищений акаунт, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) +- Для каналів з іменованими `accounts`, але зі збереженими верхньорівневими значеннями каналу для одного облікового запису, перенести ці значення рівня облікового запису до підвищеного облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- видалення `browser.relayBindHost` (застаріле налаштування relay для розширення) +- видалити `browser.relayBindHost` (застаріле налаштування extension relay) -Попередження doctor також включають рекомендації щодо акаунта за замовчуванням для багатокаунтних каналів: +Попередження doctor також містять рекомендації щодо типового облікового запису для багатoоблікових каналів: -- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт. -- Якщо `channels..defaultAccount` вказано на невідомий ID акаунта, doctor попереджає і перелічує налаштовані ID акаунтів. +- Якщо налаштовано два або більше записи `channels..accounts`, але немає `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис. +- Якщо `channels..defaultAccount` вказано для невідомого ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. -### 2b) Перевизначення постачальника OpenCode +### 2b) Перевизначення провайдера OpenCode Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Через це моделі можуть використовувати неправильний API або мати нульову вартість. Doctor попереджає про це, щоб ви -могли прибрати перевизначення і відновити маршрутизацію API та вартість для кожної моделі. +могли прибрати перевизначення та відновити маршрутизацію API і вартість для кожної моделі. -### 2c) Міграція браузера і готовність Chrome MCP +### 2c) Міграція browser і готовність Chrome MCP -Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor +Якщо ваша конфігурація browser все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` @@ -187,16 +187,16 @@ Doctor також перевіряє шлях host-local Chrome MCP, коли в "user"` або налаштований профіль `existing-session`: - перевіряє, чи встановлено Google Chrome на тому самому хості для типових - профілів автопідключення + профілів з автоматичним підключенням - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 -- нагадує ввімкнути remote debugging на сторінці inspect у браузері (наприклад, +- нагадує увімкнути remote debugging на сторінці inspect у браузері (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, або `edge://inspect/#remote-debugging`) -Doctor не може ввімкнути це налаштування у Chrome за вас. Host-local Chrome MCP -усе ще вимагає: +Doctor не може увімкнути це налаштування на стороні Chrome за вас. Host-local Chrome MCP +досі потребує: -- браузер на базі Chromium 144+ на хості gateway/node +- браузер на основі Chromium 144+ на хості gateway/node - локально запущений браузер - увімкнений remote debugging у цьому браузері - підтвердження першого запиту згоди на підключення в браузері @@ -204,39 +204,39 @@ Doctor не може ввімкнути це налаштування у Chrome Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше, потребують керованого -браузера або сирого профілю CDP. +browser або сирого профілю CDP. -Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших -безголових сценаріїв. Вони, як і раніше, використовують сирий CDP. +Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших +headless-потоків. Вони й надалі використовують сирий CDP. ### 2d) TLS-передумови OAuth -Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації -OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може -перевірити ланцюжок сертифікатів. Якщо перевірка не проходить через помилку сертифіката (наприклад, -`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), -doctor виводить рекомендації щодо виправлення для конкретної платформи. У macOS із Node, встановленим через Homebrew, -виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується -навіть якщо gateway справний. +Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, +щоб переконатися, що локальний стек Node/OpenSSL TLS може +перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад +`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), +doctor виводить інструкції з виправлення для конкретної платформи. На macOS із Node від Homebrew +виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується +навіть якщо gateway працездатний. -### 3) Міграції застарілого стану (розмітка на диску) +### 3) Міграції застарілого стану (структура на диску) -Doctor може мігрувати старіші розмітки на диску до поточної структури: +Doctor може переносити старіші структури на диску до поточної структури: -- Сховище сесій + транскрипти: +- Сховище sessions + transcripts: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий ID акаунта: `default`) + - зі старого `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо -залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує -застарілі сесії + каталог агента під час старту, тож історія/автентифікація/моделі потрапляють у -каталог для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно -мігрується лише через `openclaw doctor`. Нормалізація постачальника Talk/мапи постачальників тепер -порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють +залишить будь-які старі каталоги як резервні копії. Gateway/CLI також автоматично мігрує +старі sessions + каталог агента під час старту, щоб history/auth/models потрапляли до +шляху для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно +мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер +порівнює структурну рівність, тому відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `doctor --fix`. ### 3a) Міграції застарілих маніфестів плагінів @@ -245,15 +245,15 @@ Doctor сканує всі встановлені маніфести плагі можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, -`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об’єкт `contracts` +`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. ### 3b) Міграції застарілого сховища cron -Doctor також перевіряє сховище cron завдань (`~/.openclaw/cron/jobs.json` типово, -або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник +Doctor також перевіряє сховище cron jobs (`~/.openclaw/cron/jobs.json` типово, +або `cron.store`, якщо воно перевизначене) на старі форми jobs, які планувальник досі приймає для сумісності. Поточні очищення cron включають: @@ -263,245 +263,238 @@ Doctor також перевіряє сховище cron завдань (`~/.ope - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` - верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - псевдоніми delivery `provider` у payload → явний `delivery.channel` -- прості застарілі резервні webhook-завдання з `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook` +- прості застарілі резервні webhook jobs із `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` -Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без -зміни поведінки. Якщо завдання поєднує застарілий резервний notify з уже наявним -не-webhook режимом delivery, doctor попереджає і залишає це завдання для ручної перевірки. +Doctor автоматично мігрує jobs з `notify: true` лише тоді, коли може зробити це +без зміни поведінки. Якщо job поєднує застарілий резервний notify із наявним +режимом delivery, відмінним від webhook, doctor попереджає і залишає цей job для ручного перегляду. ### 3c) Очищення блокувань сесій -Doctor сканує кожен каталог сесій агента на наявність застарілих write-lock файлів — файлів, що залишилися -після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: -шлях, PID, чи PID досі активний, вік блокування і чи +Doctor сканує каталог сесій кожного агента на наявність застарілих файлів write-lock — файлів, +які залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: +шлях, PID, чи PID ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` -він видаляє застарілі файли блокування автоматично; інакше лише виводить примітку і -просить повторно запустити з `--fix`. +він автоматично видаляє застарілі файли блокування; інакше виводить примітку та +пропонує повторно запустити команду з `--fix`. -### 4) Перевірки цілісності стану (збереження сесій, маршрутизація і безпека) +### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека) Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите -сесії, облікові дані, журнали і конфігурацію (якщо тільки у вас немає резервних копій деінде). +sessions, облікові дані, журнали та конфігурацію (якщо тільки у вас немає резервних копій деінде). Doctor перевіряє: -- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує заново створити +- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити каталог і нагадує, що не може відновити відсутні дані. -- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу +- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). -- **Каталог стану під хмарною синхронізацією macOS**: попереджає, коли стан знаходиться в iCloud Drive +- **Каталог стану macOS у хмарній синхронізації**: попереджає, якщо стан розташовано в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або - `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O - і конфлікти блокувань/синхронізації. -- **Каталог стану на Linux на SD або eMMC**: попереджає, коли стан знаходиться на джерелі монтування `mmcblk*`, - оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій - під час запису сесій та облікових даних. -- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій - потрібні для збереження історії та уникнення збоїв `ENOENT`. -- **Невідповідність транскриптів**: попереджає, коли в останніх записах сесій відсутні - файли транскриптів. -- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний транскрипт має лише один - рядок (історія не накопичується). -- **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних - домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може - розділитися між інсталяціями). + `~/Library/CloudStorage/...`, оскільки шляхи на основі синхронізації можуть спричиняти повільніше введення-виведення + і гонки блокувань/синхронізації. +- **Каталог стану Linux на SD або eMMC**: попереджає, якщо стан розташовано на джерелі монтування `mmcblk*`, + оскільки випадкове введення-виведення на носіях SD або eMMC може бути повільнішим і швидше зношуватися + при записі сесій та облікових даних. +- **Відсутні каталоги sessions**: `sessions/` і каталог сховища сесій + потрібні для збереження history та уникнення збоїв `ENOENT`. +- **Невідповідність transcript**: попереджає, коли в недавніх записах сесій відсутні + файли transcript. +- **Основна сесія “1-line JSONL”**: виявляє, коли основний transcript містить лише один + рядок (history не накопичується). +- **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних + домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може + розділитися між встановленнями). - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там). -- **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є - доступним для читання групою/усіма, і пропонує обмежити до `600`. +- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` + доступний на читання для групи/всіх користувачів, і пропонує обмежити права до `600`. -### 5) Справність автентифікації моделей (строк дії OAuth) +### 5) Стан автентифікації моделей (строк дії OAuth) -Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени -ось-ось закінчаться або вже прострочені, і може оновити їх, коли це безпечно. Якщо профіль -Anthropic OAuth/token застарів, він радить використати Anthropic API key або застарілий -шлях setup-token Anthropic. +Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени +ось-ось завершаться або вже завершилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic +OAuth/token застарів, він пропонує ключ Anthropic API або +шлях Anthropic setup-token. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. -Doctor також виявляє застарілий видалений стан Anthropic Claude CLI. Якщо старі -байти облікових даних `anthropic:claude-cli` все ще існують у `auth-profiles.json`, -doctor перетворює їх назад на профілі Anthropic token/OAuth і переписує -застарілі посилання на моделі `claude-cli/...` та `agents.defaults.cliBackends.claude-cli`. -Якщо цих байтів уже немає, doctor видаляє застарілу конфігурацію і виводить команди для відновлення. +Doctor також повідомляє про auth profiles, які тимчасово непридатні до використання через: -Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: +- короткі cooldown (обмеження швидкості/тайм-аути/помилки автентифікації) +- довші відключення (помилки тарифікації/кредитів) -- короткі cooldown (rate limit/timeout/auth failure) -- триваліші відключення (збій billing/credit) +### 6) Перевірка моделі hooks -### 6) Перевірка моделі Hooks - -Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель щодо -каталогу та allowlist і попереджає, якщо воно не буде розв’язане або заборонене. +Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель у +каталозі та allowlist і попереджає, коли воно не може бути розв’язане або не дозволене. ### 7) Відновлення образу sandbox -Коли sandboxing увімкнено, doctor перевіряє Docker-образи і пропонує зібрати їх або -перейти на застарілі назви, якщо поточний образ відсутній. +Коли sandbox увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або +перемкнутися на застарілі назви, якщо поточний образ відсутній. -### 7b) Runtime-залежності вбудованих плагінів +### 7b) Runtime dependencies вбудованих плагінів -Doctor перевіряє, що runtime-залежності вбудованих плагінів (наприклад, -пакети runtime плагіна Discord) присутні в корені інсталяції OpenClaw. -Якщо чогось бракує, doctor повідомляє про пакети і встановлює їх у режимі +Doctor перевіряє, чи наявні runtime dependencies вбудованих плагінів (наприклад, +runtime packages плагіна Discord) у кореневому каталозі встановлення OpenClaw. +Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Міграції служб gateway і підказки з очищення +### 8) Міграції служб gateway і підказки для очищення Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і -пропонує видалити їх та встановити службу OpenClaw з поточним -портом gateway. Він також може сканувати додаткові gateway-подібні служби і виводити підказки щодо очищення. -Служби OpenClaw gateway, названі за профілем, вважаються повноцінними і не +пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. +Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки для очищення. +Служби OpenClaw gateway з назвами профілів вважаються повноцінними й не позначаються як "додаткові". -### 8b) Стартова міграція Matrix +### 8b) Міграція стартового Matrix -Коли обліковий запис каналу Matrix має відкладену або придатну до виконання міграцію застарілого стану, -doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім -запускає кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку +Коли для облікового запису каналу Matrix є очікувана або застосовна міграція застарілого стану, +doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім +виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а -старт продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка -повністю пропускається. +запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) цю перевірку +повністю пропущено. ### 9) Попередження безпеки -Doctor виводить попередження, коли постачальник відкритий для DM без allowlist +Doctor видає попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним чином. ### 10) systemd linger (Linux) -Якщо запуск відбувається як служба користувача systemd, doctor перевіряє, що linger увімкнено, щоб +Якщо робота відбувається як служба користувача systemd, doctor гарантує, що linger увімкнено, щоб gateway залишався активним після виходу з системи. -### 11) Стан робочого простору (Skills, плагіни і застарілі каталоги) +### 11) Стан workspace (Skills, плагіни та застарілі каталоги) -Doctor виводить зведення стану робочого простору для типового агента: +Doctor виводить підсумок стану workspace для типового агента: -- **Стан Skills**: підраховує доступні, з відсутніми вимогами та заблоковані allowlist Skills. -- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору - існують поруч із поточним робочим простором. -- **Стан плагінів**: підраховує завантажені/вимкнені/з помилками плагіни; перелічує ID плагінів для будь-яких - помилок; повідомляє про можливості bundle plugin. +- **Стан Skills**: рахує доступні, з відсутніми вимогами та заблоковані allowlist Skills. +- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace + існують поруч із поточним workspace. +- **Стан плагінів**: рахує завантажені/вимкнені/з помилками плагіни; перелічує ID плагінів для + будь-яких помилок; повідомляє про можливості bundle plugins. - **Попередження сумісності плагінів**: позначає плагіни, які мають проблеми сумісності з поточним runtime. -- **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, які були +- **Діагностика плагінів**: показує всі попередження або помилки під час завантаження, які видані реєстром плагінів. -### 11b) Розмір bootstrap-файлу +### 11b) Розмір bootstrap-файлів -Doctor перевіряє, чи файли bootstrap робочого простору (наприклад, `AGENTS.md`, -`CLAUDE.md` або інші інжектовані контекстні файли) не наближаються або не перевищують налаштований -ліміт символів. Він повідомляє для кожного файла необроблену кількість символів порівняно з інжектованою, -відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість -інжектованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються -до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` +Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, +`CLAUDE.md` або інші ін’єктовані файли контексту) не наблизилися або не перевищили +налаштований ліміт символів. Він повідомляє для кожного файлу сирі та ін’єктовані значення кількості символів, відсоток обрізання, +причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих +символів як частку від загального бюджету. Коли файли обрізано або вони близькі до межі, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion -Doctor перевіряє, чи встановлено автодоповнення для поточної оболонки +Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): -- Якщо профіль оболонки використовує повільний шаблон динамічного completion - (`source <(openclaw completion ...)`), doctor оновлює його до швидшого +- Якщо профіль оболонки використовує повільну схему динамічного completion + (`source <(openclaw completion ...)`), doctor оновлює її до швидшого варіанта з кешованим файлом. - Якщо completion налаштовано в профілі, але файл кешу відсутній, - doctor автоматично генерує кеш заново. + doctor автоматично повторно генерує кеш. - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). -Запустіть `openclaw completion --write-state`, щоб вручну перегенерувати кеш. +Запустіть `openclaw completion --write-state`, щоб вручну повторно згенерувати кеш. ### 12) Перевірки автентифікації gateway (локальний токен) -Doctor перевіряє готовність автентифікації локального токена gateway. +Doctor перевіряє готовність локальної автентифікації gateway на основі токена. -- Якщо режим токена потребує токена і джерела токена немає, doctor пропонує згенерувати його. +- Якщо режиму токена потрібен токен і джерела токена немає, doctor пропонує згенерувати його. - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. -- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли токен SecretRef не налаштований. +- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef для токена. -### 12b) Відновлення лише для читання з урахуванням SecretRef +### 12b) Виправлення в режимі лише читання з урахуванням SecretRef -Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки runtime. +Деякі потоки виправлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime з негайним збоєм. -- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. -- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. -- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. +- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільових виправлень конфігурації. +- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` для `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні. +- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. -### 13) Перевірка справності gateway + перезапуск +### 13) Перевірка працездатності gateway + restart -Doctor виконує перевірку справності і пропонує перезапустити gateway, коли він виглядає -несправним. +Doctor запускає перевірку працездатності й пропонує перезапустити gateway, якщо той +виглядає несправним. -### 13b) Готовність memory search +### 13b) Готовність пошуку в пам’яті -Doctor перевіряє, чи готовий налаштований постачальник embedding для memory search -для типового агента. Поведінка залежить від налаштованого backend і provider: +Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті +для типового агента. Поведінка залежить від налаштованого backend і провайдера: -- **QMD backend**: перевіряє, чи доступний і чи може запускатися бінарник `qmd`. - Якщо ні, виводить рекомендації щодо виправлення, зокрема npm-пакет і параметр ручного шляху до бінарника. -- **Явно вказаний локальний provider**: перевіряє наявність локального файла моделі або розпізнаного - URL віддаленої/завантажуваної моделі. Якщо нічого не знайдено, пропонує перейти на віддаленого provider. -- **Явно вказаний віддалений provider** (`openai`, `voyage` тощо): перевіряє, чи присутній API key - у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. -- **Auto provider**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого - provider у порядку автодобору. +- **Backend QMD**: перевіряє, чи доступний і чи запускається двійковий файл `qmd`. + Якщо ні, виводить інструкції з виправлення, включно з npm-пакетом і параметром ручного шляху до двійкового файлу. +- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаної + віддаленої/завантажуваної URL-адреси моделі. Якщо нічого не знайдено, пропонує перейти на віддаленого провайдера. +- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API key + у середовищі або в сховищі автентифікації. Якщо його немає, виводить практичні підказки. +- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого + провайдера у порядку автоматичного вибору. -Коли доступний результат перевірки gateway (gateway був справний на момент -перевірки), doctor зіставляє його з конфігурацією, видимою з CLI, і зазначає +Коли доступний результат probe від gateway (на момент +перевірки gateway був працездатним), doctor звіряє його результат із конфігурацією, видимою CLI, і відзначає будь-які розбіжності. -Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime. +Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding у runtime. ### 14) Попередження про стан каналів -Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє -попередження з рекомендованими виправленнями. +Якщо gateway працездатний, doctor запускає probe стану каналів і повідомляє +попередження разом із запропонованими виправленнями. ### 15) Аудит конфігурації supervisor + відновлення -Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність -відсутніх або застарілих типових значень (наприклад, залежностей systemd network-online і -затримки перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може -перезаписати файл служби/завдання відповідно до поточних типових значень. +Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на +відсутні або застарілі типові значення (наприклад залежності systemd network-online і +затримку restart). Коли виявляється невідповідність, він +рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних типових значень. Примітки: - `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor. -- `openclaw doctor --yes` приймає типові запити на відновлення. +- `openclaw doctor --yes` приймає типові запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. -- Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення служби перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби supervisor. -- Якщо автентифікація токеном потребує токена, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні рекомендації. -- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим явно не буде встановлено. -- Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. +- Якщо для токен-автентифікації потрібен токен і `gateway.auth.token` керується через SecretRef, шлях встановлення/відновлення служби в doctor перевіряє SecretRef, але не зберігає відкриті значення токенів, отримані з нього, у метаданих середовища служби supervisor. +- Якщо для токен-автентифікації потрібен токен, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення та надає практичні вказівки. +- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно задано. +- Для користувацьких systemd units у Linux перевірки розбіжностей токенів у doctor тепер враховують і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. -### 16) Діагностика runtime gateway + порту +### 16) Діагностика runtime gateway і порту Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти -на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже -запущений, SSH-тунель). +на порту gateway (типово `18789`) і повідомляє про ймовірні причини (gateway уже +запущено, SSH tunnel). -### 17) Найкращі практики runtime gateway +### 17) Рекомендовані практики runtime gateway -Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому через version manager -(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, -а шляхи через version manager можуть ламатися після оновлень, оскільки служба не -завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, коли -вона доступна (Homebrew/apt/choco). +Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому +менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Каналам WhatsApp + Telegram потрібен Node, +а шляхи менеджерів версій можуть ламатися після оновлень, тому що служба не +завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо +воно доступне (Homebrew/apt/choco). ### 18) Запис конфігурації + метадані wizard -Doctor зберігає всі зміни конфігурації і проставляє метадані wizard, щоб зафіксувати +Doctor зберігає всі зміни конфігурації й проставляє метадані wizard, щоб зафіксувати запуск doctor. -### 19) Поради щодо робочого простору (резервні копії + система пам’яті) +### 19) Поради щодо workspace (резервне копіювання + система пам’яті) -Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, -якщо робочий простір ще не перебуває під git. +Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання, +якщо workspace ще не перебуває під git. -Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника щодо -структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). +Повний посібник зі структури +workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab) див. у [/concepts/agent-workspace](/uk/concepts/agent-workspace). diff --git a/docs/uk/gateway/index.md b/docs/uk/gateway/index.md index 89e253334..6eb4b93df 100644 --- a/docs/uk/gateway/index.md +++ b/docs/uk/gateway/index.md @@ -1,33 +1,33 @@ --- read_when: - Запуск або налагодження процесу gateway -summary: Runbook для сервісу Gateway, його життєвого циклу та операцій -title: Runbook Gateway +summary: Операційний посібник для служби Gateway, її життєвого циклу та експлуатації +title: Операційний посібник Gateway x-i18n: - generated_at: "2026-04-05T18:03:49Z" + generated_at: "2026-04-06T15:28:26Z" model: gpt-5.4 provider: openai - source_hash: 0ec17674370de4e171779389c83580317308a4f07ebf335ad236a47238af18e1 + source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd source_path: gateway/index.md workflow: 15 --- -# Runbook Gateway +# Операційний посібник Gateway -Використовуйте цю сторінку для запуску сервісу Gateway в перший день і його експлуатації надалі. +Використовуйте цю сторінку для запуску Gateway у перший день і для операційної роботи надалі. - + Діагностика за симптомами з точними послідовностями команд і сигнатурами журналів. - - Посібник із налаштування, орієнтований на завдання, + повний довідник із конфігурації. + + Практичний посібник із налаштування + повний довідник конфігурації. - - Контракт SecretRef, поведінка runtime snapshot і операції migrate/reload. + + Контракт SecretRef, поведінка знімків під час виконання та операції міграції/перезавантаження. - - Точні правила target/path для `secrets apply` і поведінка auth-profile лише з ref. + + Точні правила target/path для `secrets apply` і поведінка профілю автентифікації лише з посиланнями. @@ -38,15 +38,15 @@ x-i18n: ```bash openclaw gateway --port 18789 -# debug/trace дзеркаляться у stdio +# debug/trace дзеркально виводяться у stdio openclaw gateway --port 18789 --verbose -# примусово завершує listener на вибраному порту, потім запускає +# примусово завершує процес, що слухає вибраний порт, а потім запускає openclaw gateway --force ``` - + ```bash openclaw gateway status @@ -54,43 +54,43 @@ openclaw status openclaw logs --follow ``` -Ознаки здорового базового стану: `Runtime: running` і `RPC probe: ok`. +Базовий справний стан: `Runtime: running` і `RPC probe: ok`. - + ```bash openclaw channels status --probe ``` -За доступного gateway ця команда виконує live-перевірки каналів для кожного облікового запису та необов’язкові аудити. -Якщо gateway недоступний, CLI повертається до зведень каналів лише на основі конфігурації -замість live-виводу перевірки. +За доступного gateway ця команда виконує живі перевірки каналів для кожного облікового запису та необов’язкові аудити. +Якщо gateway недоступний, CLI повертається до зведень каналів лише за конфігурацією +замість виводу живих probe-перевірок. -Перезавантаження конфігурації Gateway відстежує активний шлях до файлу конфігурації (визначений із типових значень profile/state або через `OPENCLAW_CONFIG_PATH`, якщо його задано). +Перезавантаження конфігурації Gateway відстежує активний шлях до файла конфігурації (визначений із типових значень профілю/стану або через `OPENCLAW_CONFIG_PATH`, якщо його задано). Типовий режим — `gateway.reload.mode="hybrid"`. -Після першого успішного завантаження запущений процес обслуговує активний in-memory snapshot конфігурації; успішне перезавантаження атомарно замінює цей snapshot. +Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно підміняє цей знімок. -## Модель runtime +## Модель виконання -- Один постійно запущений процес для маршрутизації, control plane і підключень каналів. +- Один постійно активний процес для маршрутизації, control plane та підключень каналів. - Один мультиплексований порт для: - - WebSocket control/RPC + - контролю WebSocket/RPC - HTTP API, сумісних з OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`) - - Control UI і hooks -- Типовий режим bind: `loopback`. -- Автентифікація типово обов’язкова. Для конфігурацій зі спільним секретом використовуйте + - Control UI та hooks +- Типовий режим прив’язки: `loopback`. +- Автентифікація за замовчуванням обов’язкова. Налаштування зі спільним секретом використовують `gateway.auth.token` / `gateway.auth.password` (або - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а для конфігурацій - з reverse proxy не на loopback можна використовувати `gateway.auth.mode: "trusted-proxy"`. + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а конфігурації + reverse proxy поза loopback можуть використовувати `gateway.auth.mode: "trusted-proxy"`. -## Endpoint, сумісні з OpenAI +## Кінцеві точки, сумісні з OpenAI Найважливіша поверхня сумісності OpenClaw тепер така: @@ -104,37 +104,37 @@ openclaw channels status --probe - Більшість інтеграцій Open WebUI, LobeChat і LibreChat спочатку перевіряють `/v1/models`. - Багато конвеєрів RAG і пам’яті очікують `/v1/embeddings`. -- Клієнти, нативні для агентів, дедалі частіше віддають перевагу `/v1/responses`. +- Клієнти, орієнтовані на агентів, дедалі частіше надають перевагу `/v1/responses`. Примітка щодо планування: -- `/v1/models` орієнтований на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/`. -- `openclaw/default` — це стабільний псевдонім, який завжди зіставляється з налаштованим типовим агентом. -- Використовуйте `x-openclaw-model`, коли вам потрібно перевизначити провайдера/модель backend; інакше зберігається керування звичайною моделлю та налаштуванням embedding вибраного агента. +- `/v1/models` орієнтований насамперед на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/`. +- `openclaw/default` — це стабільний псевдонім, який завжди вказує на налаштованого агента за замовчуванням. +- Використовуйте `x-openclaw-model`, якщо вам потрібно перевизначити постачальника/модель бекенда; інакше вибраний агент і надалі керуватиме звичайним налаштуванням моделі та вбудовувань. -Усе це працює на головному порту Gateway і використовує ту саму межу автентифікації довіреного оператора, що й решта HTTP API Gateway. +Усе це працює на основному порту Gateway і використовує той самий довірений периметр автентифікації оператора, що й решта HTTP API Gateway. -### Пріоритет порту й bind +### Пріоритет порту та режиму прив’язки -| Налаштування | Порядок визначення | -| ------------ | -------------------------------------------------------------- | +| Параметр | Порядок визначення | +| -------- | ------------------ | | Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | -| Режим bind | CLI/перевизначення → `gateway.bind` → `loopback` | +| Режим прив’язки | CLI/override → `gateway.bind` → `loopback` | -### Режими hot reload +### Режими гарячого перезавантаження -| `gateway.reload.mode` | Поведінка | -| --------------------- | ------------------------------------------ | -| `off` | Без перезавантаження конфігурації | -| `hot` | Застосовує лише безпечні для hot зміни | -| `restart` | Перезапуск при змінах, що вимагають reload | -| `hybrid` (типово) | Hot-застосування, коли безпечно, і перезапуск, коли потрібно | +| `gateway.reload.mode` | Поведінка | +| --------------------- | --------- | +| `off` | Без перезавантаження конфігурації | +| `hot` | Застосовує лише зміни, безпечні для hot-reload | +| `restart` | Перезапускає за змін, що вимагають перезапуску | +| `hybrid` (типово) | Гаряче застосовує, коли безпечно, і перезапускає, коли потрібно | -## Набір операторських команд +## Набір команд оператора ```bash openclaw gateway status -openclaw gateway status --deep # додає системне сканування сервісу +openclaw gateway status --deep # додає сканування служби на рівні системи openclaw gateway status --json openclaw gateway install openclaw gateway restart @@ -144,15 +144,15 @@ openclaw logs --follow openclaw doctor ``` -`gateway status --deep` призначено для додаткового виявлення сервісів (LaunchDaemons/systemd system +`gateway status --deep` призначено для додаткового виявлення служб (LaunchDaemons/systemd system units/schtasks), а не для глибшої RPC-перевірки стану. ## Кілька gateway на одному хості -У більшості інсталяцій має працювати один gateway на машину. Один gateway може обслуговувати кількох -агентів і каналів. +У більшості встановлень має працювати один gateway на машину. Один gateway може обслуговувати кількох +агентів і канали. -Кілька gateway потрібні лише тоді, коли вам навмисно потрібна ізоляція або аварійний бот. +Кілька gateway потрібні лише тоді, коли вам навмисно потрібна ізоляція або резервний бот. Корисні перевірки: @@ -161,37 +161,38 @@ openclaw gateway status --deep openclaw gateway probe ``` -Чого очікувати: +Що очікувати: - `gateway status --deep` може повідомити `Other gateway-like services detected (best effort)` - і надрукувати підказки з очищення, якщо ще лишилися застарілі інсталяції launchd/systemd/schtasks. -- `gateway probe` може попередити про `multiple reachable gateways`, коли відповідає більше ніж одна ціль. + і вивести підказки з очищення, якщо навколо лишилися застарілі встановлення launchd/systemd/schtasks. +- `gateway probe` може попередити про `multiple reachable gateways`, коли відповідає + більше однієї цілі. - Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного gateway окремо. -Детальне налаштування: [/gateway/multiple-gateways](/gateway/multiple-gateways). +Детальне налаштування: [/gateway/multiple-gateways](/uk/gateway/multiple-gateways). ## Віддалений доступ -Бажано: Tailscale/VPN. +Рекомендовано: Tailscale/VPN. Резервний варіант: SSH-тунель. ```bash ssh -N -L 18789:127.0.0.1:18789 user@host ``` -Після цього підключайте клієнти локально до `ws://127.0.0.1:18789`. +Потім підключайте клієнти локально до `ws://127.0.0.1:18789`. -SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти -все одно мають надсилати `token`/`password`, навіть через тунель. Для режимів із -ідентифікацією запит усе одно має відповідати цьому шляху автентифікації. +SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти все одно +мають надсилати `token`/`password` навіть через тунель. Для режимів з ідентифікацією +запит усе одно має задовольняти цей шлях автентифікації. -Див.: [Remote Gateway](/gateway/remote), [Автентифікація](/gateway/authentication), [Tailscale](/gateway/tailscale). +Див.: [Remote Gateway](/uk/gateway/remote), [Authentication](/uk/gateway/authentication), [Tailscale](/uk/gateway/tailscale). -## Супервізія та життєвий цикл сервісу +## Нагляд і життєвий цикл служби -Для надійності, подібної до production, використовуйте запуск під супервізією. +Для надійності на рівні production використовуйте запуск під наглядом. @@ -203,7 +204,7 @@ openclaw gateway restart openclaw gateway stop ``` -Мітки LaunchAgent — `ai.openclaw.gateway` (типово) або `ai.openclaw.` (іменований profile). `openclaw doctor` перевіряє й виправляє дрейф конфігурації сервісу. +Мітки LaunchAgent: `ai.openclaw.gateway` (типово) або `ai.openclaw.` (іменований профіль). `openclaw doctor` перевіряє і виправляє дрейф конфігурації служби. @@ -215,13 +216,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -Щоб сервіс не зупинявся після виходу з системи, увімкніть lingering: +Щоб служба лишалася активною після виходу з сеансу, увімкніть lingering: ```bash sudo loginctl enable-linger ``` -Приклад ручного user unit, коли потрібен кастомний шлях встановлення: +Приклад user-unit вручну, коли потрібен власний шлях встановлення: ```ini [Unit] @@ -253,24 +254,24 @@ openclaw gateway restart openclaw gateway stop ``` -Керований нативний запуск Windows використовує Scheduled Task з назвою `OpenClaw Gateway` -(або `OpenClaw Gateway ()` для іменованих profile). Якщо створення Scheduled Task -заборонено, OpenClaw повертається до launcher у Startup-folder для кожного користувача, -який вказує на `gateway.cmd` у каталозі state. +Керований нативний автозапуск у Windows використовує Scheduled Task з назвою `OpenClaw Gateway` +(або `OpenClaw Gateway ()` для іменованих профілів). Якщо створення Scheduled Task +заборонено, OpenClaw переходить до launcher у Startup-folder для поточного користувача, +який вказує на `gateway.cmd` у каталозі стану. -Використовуйте system unit для багатокористувацьких/постійно ввімкнених хостів. +Використовуйте системний unit для багатокористувацьких/постійно активних хостів. ```bash sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -Використовуйте те саме тіло сервісу, що й для user unit, але встановлюйте його в -`/etc/systemd/system/openclaw-gateway[-].service` і за потреби скоригуйте +Використовуйте той самий вміст служби, що й для user unit, але встановіть його в +`/etc/systemd/system/openclaw-gateway[-].service` і скоригуйте `ExecStart=`, якщо ваш бінарний файл `openclaw` розташований в іншому місці. @@ -278,8 +279,8 @@ sudo systemctl enable --now openclaw-gateway[-].service ## Кілька gateway на одному хості -У більшості конфігурацій слід запускати **один** Gateway. -Використовуйте кілька лише для суворої ізоляції/резервування (наприклад, rescue profile). +У більшості конфігурацій має працювати **один** Gateway. +Використовуйте кілька лише для суворої ізоляції/резервування (наприклад, профіль відновлення). Контрольний список для кожного екземпляра: @@ -295,9 +296,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002 ``` -Див.: [Кілька gateway](/gateway/multiple-gateways). +Див.: [Multiple gateways](/uk/gateway/multiple-gateways). -### Швидкий шлях для dev profile +### Швидкий шлях для dev-профілю ```bash openclaw --dev setup @@ -305,34 +306,34 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -Типові значення включають ізольований state/config і базовий порт gateway `19001`. +Типові значення включають ізольовані state/config і базовий порт gateway `19001`. -## Короткий довідник з протоколу (погляд оператора) +## Коротка довідка з протоколу (погляд оператора) -- Першим кадром клієнта має бути `connect`. -- Gateway повертає snapshot `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy). +- Перший кадр клієнта має бути `connect`. +- Gateway повертає знімок `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy). - `hello-ok.features.methods` / `events` — це консервативний список виявлення, а не - згенерований дамп кожного доступного допоміжного маршруту. + згенерований дамп усіх доступних маршрутів helper. - Запити: `req(method, params)` → `res(ok/payload|error)`. - До поширених подій належать `connect.challenge`, `agent`, `chat`, `session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`, `health`, `heartbeat`, події життєвого циклу pairing/approval і `shutdown`. -Запуски агентів мають дві стадії: +Запуски агентів складаються з двох етапів: 1. Негайне підтвердження прийняття (`status:"accepted"`) -2. Фінальна відповідь про завершення (`status:"ok"|"error"`), з потоковими подіями `agent` між ними. +2. Остаточна відповідь завершення (`status:"ok"|"error"`), із потоковими подіями `agent` між ними. -Повну документацію з протоколу див. в [Gateway Protocol](/gateway/protocol). +Повну документацію з протоколу див.: [Gateway Protocol](/uk/gateway/protocol). ## Операційні перевірки -### Доступність +### Перевірка доступності - Відкрийте WS і надішліть `connect`. -- Очікуйте відповідь `hello-ok` зі snapshot. +- Очікуйте відповідь `hello-ok` зі знімком. -### Готовність +### Перевірка готовності ```bash openclaw gateway status @@ -342,32 +343,32 @@ openclaw health ### Відновлення після пропусків -Події не відтворюються повторно. За розривів у послідовності оновіть стан (`health`, `system-presence`) перед продовженням. +Події не відтворюються повторно. За пропусків у послідовності оновіть стан (`health`, `system-presence`), перш ніж продовжувати. ## Типові сигнатури збоїв -| Сигнатура | Імовірна проблема | -| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | Bind не на loopback без валідного шляху автентифікації gateway | -| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт порту | -| `Gateway start blocked: set gateway.mode=local` | У конфігурації задано remote mode, або в пошкодженій конфігурації відсутній stamp local-mode | -| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і gateway | +| Сигнатура | Імовірна проблема | +| --------- | ----------------- | +| `refusing to bind gateway ... without auth` | Прив’язка не до loopback без дійсного шляху автентифікації gateway | +| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт порту | +| `Gateway start blocked: set gateway.mode=local` | У конфігурації встановлено remote mode або в пошкодженій конфігурації відсутній штамп local-mode | +| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і gateway | -Для повних послідовностей діагностики використовуйте [Усунення несправностей Gateway](/gateway/troubleshooting). +Щоб отримати повні послідовності діагностики, скористайтеся [Gateway Troubleshooting](/uk/gateway/troubleshooting). ## Гарантії безпеки -- Клієнти протоколу Gateway швидко завершуються помилкою, коли Gateway недоступний (без неявного резервного переходу до прямого каналу). -- Невалідні/не-`connect` перші кадри відхиляються й з’єднання закривається. -- Плавне завершення роботи надсилає подію `shutdown` перед закриттям сокета. +- Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного fallback на прямий канал). +- Некоректні перші кадри або кадри не типу `connect` відхиляються, і з’єднання закривається. +- Коректне завершення роботи надсилає подію `shutdown` перед закриттям сокета. --- -Пов’язане: +Пов’язані сторінки: -- [Усунення несправностей](/gateway/troubleshooting) -- [Фоновий процес](/gateway/background-process) -- [Конфігурація](/gateway/configuration) -- [Стан](/gateway/health) -- [Doctor](/gateway/doctor) -- [Автентифікація](/gateway/authentication) +- [Troubleshooting](/uk/gateway/troubleshooting) +- [Background Process](/uk/gateway/background-process) +- [Configuration](/uk/gateway/configuration) +- [Health](/uk/gateway/health) +- [Doctor](/uk/gateway/doctor) +- [Authentication](/uk/gateway/authentication) diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 8979f6a1f..18f9e3643 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,22 +1,22 @@ --- read_when: - - Хаб усунення несправностей направив вас сюди для глибшої діагностики + - Центр усунення несправностей направив вас сюди для поглибленої діагностики - Вам потрібні стабільні розділи runbook за симптомами з точними командами -summary: Поглиблений runbook з усунення несправностей для gateway, каналів, автоматизації, nodes і browser +summary: Поглиблений runbook з усунення несправностей для шлюзу, каналів, автоматизації, вузлів і браузера title: Усунення несправностей x-i18n: - generated_at: "2026-04-05T18:06:19Z" + generated_at: "2026-04-06T15:29:04Z" model: gpt-5.4 provider: openai - source_hash: 028226726e6adc45ca61d41510a953c4e21a3e85f3082af9e8085745c6ac3ec1 + source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729 source_path: gateway/troubleshooting.md workflow: 15 --- -# Усунення несправностей Gateway +# Усунення несправностей шлюзу Ця сторінка — поглиблений runbook. -Почніть із [/help/troubleshooting](/help/troubleshooting), якщо спершу хочете пройти швидкий потік тріажу. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік тріажу. ## Послідовність команд @@ -34,12 +34,12 @@ openclaw channels status --probe - `openclaw gateway status` показує `Runtime: running` і `RPC probe: ok`. - `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу. -- `openclaw channels status --probe` показує актуальний стан транспорту для кожного облікового запису і, - де це підтримується, результати probe/audit на кшталт `works` або `audit ok`. +- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і, + де підтримується, результати probe/audit, наприклад `works` або `audit ok`. -## Anthropic 429: extra usage required for long context +## Anthropic 429: потрібне додаткове використання для довгого контексту -Використовуйте це, коли логи/помилки містять: +Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash @@ -50,25 +50,25 @@ openclaw config get agents.defaults.models Зверніть увагу на таке: -- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. -- Поточні облікові дані Anthropic не придатні для long-context використання. -- Запити завершуються помилкою лише для довгих сесій/запусків моделей, яким потрібен шлях 1M beta. +- Для вибраної моделі Anthropic Opus/Sonnet встановлено `params.context1m: true`. +- Поточні облікові дані Anthropic не дають права на використання довгого контексту. +- Запити падають лише на довгих сесіях/запусках моделі, яким потрібен beta-шлях 1M. Варіанти виправлення: -1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного контекстного вікна. -2. Використовуйте API ключ Anthropic з білінгом або увімкніть Anthropic Extra Usage в обліковому записі Anthropic OAuth/передплати. -3. Налаштуйте fallback-моделі, щоб запуски продовжувалися, коли Anthropic відхиляє long-context запити. +1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. +2. Використовуйте облікові дані Anthropic, які дають право на запити з довгим контекстом, або перейдіть на ключ API Anthropic. +3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic з довгим контекстом відхиляються. Пов’язане: -- [/providers/anthropic](/providers/anthropic) -- [/reference/token-use](/reference/token-use) -- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) +- [/providers/anthropic](/uk/providers/anthropic) +- [/reference/token-use](/uk/reference/token-use) +- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) ## Немає відповідей -Якщо канали працюють, але відповідей немає, перевірте маршрутизацію й політики, перш ніж щось перепідключати. +Якщо канали підключені, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. ```bash openclaw status @@ -80,25 +80,25 @@ openclaw logs --follow Зверніть увагу на таке: -- Очікує схвалення pairing для відправників у DM. -- Керування згадуваннями в групі (`requireMention`, `mentionPatterns`). -- Невідповідності allowlist каналу/групи. +- Pairing очікує підтвердження для відправників у DM. +- Обмеження згадування для груп (`requireMention`, `mentionPatterns`). +- Невідповідності allowlist для каналу/групи. -Поширені сигнатури: +Типові ознаки: -- `drop guild message (mention required` → повідомлення групи ігнорується, доки не буде згадування. +- `drop guild message (mention required` → групове повідомлення ігнорується, доки немає згадки. - `pairing request` → відправника потрібно схвалити. - `blocked` / `allowlist` → відправника/канал відфільтровано політикою. Пов’язане: -- [/channels/troubleshooting](/channels/troubleshooting) -- [/channels/pairing](/channels/pairing) -- [/channels/groups](/channels/groups) +- [/channels/troubleshooting](/uk/channels/troubleshooting) +- [/channels/pairing](/uk/channels/pairing) +- [/channels/groups](/uk/channels/groups) ## Підключення dashboard/control UI -Коли dashboard/control UI не підключається, перевірте URL, режим auth і припущення щодо безпечного контексту. +Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. ```bash openclaw gateway status @@ -110,46 +110,46 @@ openclaw gateway status --json Зверніть увагу на таке: -- Правильні URL probe і dashboard. -- Невідповідність режиму auth/token між клієнтом і gateway. +- Правильний URL probe і URL dashboard. +- Невідповідність режиму/токена автентифікації між клієнтом і шлюзом. - Використання HTTP там, де потрібна ідентичність пристрою. -Поширені сигнатури: +Типові ознаки: -- `device identity required` → небезпечний контекст або відсутня auth пристрою. -- `origin not allowed` → `Origin` браузера не входить до `gateway.controlUi.allowedOrigins` - (або ви підключаєтеся з origin браузера не через loopback без явного +- `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. +- `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins` + (або ви підключаєтеся з origin браузера, що не є loopback, без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - challenge-based потік auth пристрою (`connect.challenge` + `device.nonce`). + challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний - payload (або зі старою часовою позначкою) для поточного handshake. + payload (або використав застарілий timestamp) для поточного рукостискання. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. -- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scopes, збережений разом із paired - токеном пристрою. Виклики з явними `deviceToken` / явними `scopes` зберігають свій - запитаний набір scopes. -- Поза цим шляхом повторної спроби пріоритет auth під час connect такий: - спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, - потім bootstrap token. -- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як лімітатор зафіксує невдачу. Тому дві неправильні +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із pair-ованим + токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають + свій запитаний набір scope. +- Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний + токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, + потім bootstrap-токен. +- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для одного й того самого + `{scope, ip}` серіалізуються до того, як лімітер зафіксує помилку. Тому дві хибні одночасні повторні спроби від того самого клієнта можуть призвести до `retry later` - у другій спробі замість двох звичайних mismatch. -- `too many failed authentication attempts (retry later)` від клієнта loopback із browser-origin - → повторні невдачі від того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. -- повторювані `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та повторно схваліть/оберніть токен пристрою за потреби. -- `gateway connect failed:` → неправильний хост/порт/url цілі. + у другій спробі замість двох звичайних невідповідностей. +- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin + → повторні невдалі спроби з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. +- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація спільного токена/токена пристрою; оновіть конфігурацію токена та за потреби повторно схваліть/ротуйте токен пристрою. +- `gateway connect failed:` → неправильний хост/порт/URL призначення. -### Швидка мапа кодів деталей auth +### Швидка карта кодів деталей автентифікації -Використовуйте `error.details.code` із невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалого відповіді `connect`, щоб вибрати наступну дію: -| Код деталей | Значення | Рекомендована дія | -| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав потрібний shared token. | Вставте/задайте токен у клієнті й повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з токеном auth gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scopes; виклики з явними `deviceToken` / `scopes` зберігають запитаний набір scopes. Якщо помилка лишається, виконайте [контрольний список відновлення після дрейфу токена](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для пристрою застарів або відкликаний. | Оберніть/повторно схваліть токен пристрою через [devices CLI](/cli/devices), потім перепідключіться. | -| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть pending-запит: `openclaw devices list`, потім `openclaw devices approve `. | +| Код деталей | Значення | Рекомендована дія | +| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації шлюзу. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явним `deviceToken` / `scopes` зберігають запитувані scope. Якщо все ще не працює, виконайте [контрольний список відновлення після дрейфу токена](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [devices CLI](/cli/devices), потім перепідключіться. | +| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. | Перевірка міграції device auth v2: @@ -159,63 +159,63 @@ openclaw doctor openclaw gateway status ``` -Якщо логи показують помилки nonce/signature, оновіть клієнт, що підключається, і перевірте, що він: +Якщо журнали показують помилки nonce/signature, оновіть клієнт, що підключається, і переконайтеся, що він: 1. чекає на `connect.challenge` 2. підписує payload, прив’язаний до challenge -3. надсилає `connect.params.device.nonce` із тим самим challenge nonce +3. надсилає `connect.params.device.nonce` з тим самим challenge nonce -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляється: +Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляються: -- сесії з paired-device token можуть керувати лише **власним** пристроєм, якщо - виклик не має також `operator.admin` -- `openclaw devices rotate --scope ...` може запитувати лише ті scopes оператора, +- сесії токена pair-ованого пристрою можуть керувати лише **власним** пристроєм, якщо + виклик також не має `operator.admin` +- `openclaw devices rotate --scope ...` може запитувати лише ті scope оператора, які сесія виклику вже має Пов’язане: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/gateway/configuration) (режими auth gateway) -- [/gateway/trusted-proxy-auth](/gateway/trusted-proxy-auth) -- [/gateway/remote](/gateway/remote) +- [/gateway/configuration](/uk/gateway/configuration) (режими автентифікації шлюзу) +- [/gateway/trusted-proxy-auth](/uk/gateway/trusted-proxy-auth) +- [/gateway/remote](/uk/gateway/remote) - [/cli/devices](/cli/devices) -## Сервіс Gateway не працює +## Сервіс шлюзу не працює -Використовуйте це, коли сервіс установлено, але процес не тримається запущеним. +Використовуйте це, коли сервіс установлено, але процес не утримується запущеним. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # також сканує системні сервіси +openclaw gateway status --deep # також сканувати системні сервіси ``` Зверніть увагу на таке: -- `Runtime: stopped` із підказками щодо завершення. -- Невідповідність конфігурації сервісу (`Config (cli)` vs `Config (service)`). -- Конфлікти портів/слухачів. -- Додаткові інсталяції launchd/systemd/schtasks при використанні `--deep`. +- `Runtime: stopped` з підказками щодо завершення. +- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). +- Конфлікти порту/слухача. +- Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. - Підказки очищення `Other gateway-like services detected (best effort)`. -Поширені сигнатури: +Типові ознаки: -- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим local gateway не ввімкнено, або файл конфігурації було перезаписано й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб знову записати очікувану конфігурацію local-mode. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → bind не через loopback без валідного шляху auth gateway (token/password або trusted-proxy, якщо налаштовано). +- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим шлюзу не ввімкнено, або файл конфігурації було пошкоджено й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → bind не на loopback без дійсного шляху автентифікації шлюзу (токен/пароль або trusted-proxy там, де його налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. -- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні units launchd/systemd/schtasks. У більшості конфігурацій має бути один gateway на машину; якщо вам усе ж потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks-юнити. У більшості конфігурацій має бути один шлюз на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). Пов’язане: -- [/gateway/background-process](/gateway/background-process) -- [/gateway/configuration](/gateway/configuration) -- [/gateway/doctor](/gateway/doctor) +- [/gateway/background-process](/uk/gateway/background-process) +- [/gateway/configuration](/uk/gateway/configuration) +- [/gateway/doctor](/uk/gateway/doctor) -## Попередження gateway probe +## Попередження probe шлюзу -Використовуйте це, коли `openclaw gateway probe` до чогось достукується, але все одно виводить блок попередження. +Використовуйте це, коли `openclaw gateway probe` досягає цілі, але все одно виводить блок попередження. ```bash openclaw gateway probe @@ -226,24 +226,24 @@ openclaw gateway probe --ssh user@gateway-host Зверніть увагу на таке: - `warnings[].code` і `primaryTargetId` у JSON-виводі. -- Чи стосується попередження fallback через SSH, кількох gateway, відсутніх scopes або нерозв’язаних auth refs. +- Чи стосується попередження резервного SSH-шляху, кількох шлюзів, відсутніх scope або нерозв’язаних auth refs. -Поширені сигнатури: +Типові ознаки: -- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не спрацювало, але команда все одно спробувала direct-цілі з конфігурації/loopback. -- `multiple reachable gateways detected` → відповіло більше ніж одна ціль. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані слухачі. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → connect спрацював, але detail RPC обмежено через scopes; зв’яжіть ідентичність пристрою або використайте облікові дані з `operator.read`. -- текст попередження про нерозв’язаний SecretRef `gateway.auth.*` / `gateway.remote.*` → матеріал auth був недоступний у цьому шляху команди для невдалої цілі. +- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі. +- `multiple reachable gateways detected` → відповіла більш ніж одна ціль. Зазвичай це означає навмисну багатошлюзову конфігурацію або застарілі/дубльовані слухачі. +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → connect спрацював, але детальний RPC обмежено scope; pair-уйте ідентичність пристрою або використовуйте облікові дані з `operator.read`. +- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → матеріали автентифікації були недоступні в цьому шляху команди для цілі, що завершилася помилкою. Пов’язане: - [/cli/gateway](/cli/gateway) -- [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host) -- [/gateway/remote](/gateway/remote) +- [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host) +- [/gateway/remote](/uk/gateway/remote) ## Канал підключений, але повідомлення не проходять -Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -255,26 +255,26 @@ openclaw config get channels Зверніть увагу на таке: -- Політику DM (`pairing`, `allowlist`, `open`, `disabled`). -- Allowlist групи й вимоги до згадувань. +- Політика DM (`pairing`, `allowlist`, `open`, `disabled`). +- Allowlist групи та вимоги до згадки. - Відсутні дозволи/scopes API каналу. -Поширені сигнатури: +Типові ознаки: -- `mention required` → повідомлення ігнорується через політику згадувань у групі. -- `pairing` / сліди pending approval → відправника не схвалено. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з auth/дозволами каналу. +- `mention required` → повідомлення ігнорується політикою згадки в групі. +- `pairing` / сліди очікуваного схвалення → відправника не схвалено. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу. Пов’язане: -- [/channels/troubleshooting](/channels/troubleshooting) -- [/channels/whatsapp](/channels/whatsapp) -- [/channels/telegram](/channels/telegram) -- [/channels/discord](/channels/discord) +- [/channels/troubleshooting](/uk/channels/troubleshooting) +- [/channels/whatsapp](/uk/channels/whatsapp) +- [/channels/telegram](/uk/channels/telegram) +- [/channels/discord](/uk/channels/discord) ## Доставка cron і heartbeat -Якщо cron або heartbeat не запустилися чи не доставили результат, спочатку перевірте стан планувальника, а потім ціль доставки. +Якщо cron або heartbeat не спрацювали чи не були доставлені, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -286,29 +286,29 @@ openclaw logs --follow Зверніть увагу на таке: -- Cron увімкнений і присутнє наступне пробудження. +- Cron увімкнено і є наступне пробудження. - Статус історії запусків завдань (`ok`, `skipped`, `error`). - Причини пропуску heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). -Поширені сигнатури: +Типові ознаки: - `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. -- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/логів/runtime. +- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/журналів/runtime. - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але в цьому тіку жодне завдання ще не належить до виконання. -- `heartbeat: unknown accountId` → недійсний account id для цілі доставки heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat розв’язалася в destination типу DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. +- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не підлягає виконанню в цьому тіку. +- `heartbeat: unknown accountId` → недійсний id облікового запису для цілі доставки heartbeat. +- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat була зіставлена з призначенням у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. Пов’язане: -- [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting) -- [/automation/cron-jobs](/automation/cron-jobs) -- [/gateway/heartbeat](/gateway/heartbeat) +- [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting) +- [/automation/cron-jobs](/uk/automation/cron-jobs) +- [/gateway/heartbeat](/uk/gateway/heartbeat) -## Збій paired tool вузла +## Збій інструмента pair-ованого вузла -Якщо node paired, але tools не працюють, ізолюйте стан foreground, дозволів і погоджень. +Якщо вузол pair-ований, але інструменти не працюють, окремо перевірте передній план, дозволи та стан схвалення. ```bash openclaw nodes status @@ -320,26 +320,26 @@ openclaw status Зверніть увагу на таке: -- Node online з очікуваними можливостями. -- Дозволи ОС для камери/мікрофона/локації/екрана. -- Стан exec approvals і allowlist. +- Вузол у мережі з очікуваними можливостями. +- Надані ОС-дозволи для камери/мікрофона/геолокації/екрана. +- Стан схвалень exec і allowlist. -Поширені сигнатури: +Типові ознаки: -- `NODE_BACKGROUND_UNAVAILABLE` → застосунок node має бути на передньому плані. +- `NODE_BACKGROUND_UNAVAILABLE` → застосунок вузла має бути на передньому плані. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС. -- `SYSTEM_RUN_DENIED: approval required` → очікується погодження exec. -- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано через allowlist. +- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. +- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. Пов’язане: -- [/nodes/troubleshooting](/nodes/troubleshooting) -- [/nodes/index](/nodes/index) -- [/tools/exec-approvals](/tools/exec-approvals) +- [/nodes/troubleshooting](/uk/nodes/troubleshooting) +- [/nodes/index](/uk/nodes/index) +- [/tools/exec-approvals](/uk/tools/exec-approvals) ## Збій browser tool -Використовуйте це, коли дії browser tool завершуються помилкою, хоча сам gateway працює справно. +Використовуйте це, коли дії browser tool не працюють, хоча сам шлюз справний. ```bash openclaw browser status @@ -351,41 +351,41 @@ openclaw doctor Зверніть увагу на таке: -- Чи задано `plugins.allow` і чи включає воно `browser`. -- Валідний шлях до виконуваного файла браузера. +- Чи встановлено `plugins.allow` і чи містить він `browser`. +- Дійсний шлях до виконуваного файла браузера. - Досяжність профілю CDP. - Доступність локального Chrome для профілів `existing-session` / `user`. -Поширені сигнатури: +Типові ознаки: - `unknown command "browser"` або `unknown command 'browser'` → вбудований browser plugin виключено через `plugins.allow`. -- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому plugin ніколи не завантажувався. -- `Failed to start Chrome CDP on port` → процес браузера не зміг запуститися. +- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому плагін ніколи не завантажився. +- `Failed to start Chrome CDP on port` → не вдалося запустити процес браузера. - `browser.executablePath not found` → налаштований шлях недійсний. - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`. -- `browser.cdpUrl has invalid port` → у налаштованому URL CDP вказано неправильний або недопустимий порт. -- `No Chrome tabs found for profile="user"` → профіль підключення Chrome MCP не має відкритих локальних вкладок Chrome. -- `Remote CDP for profile "" is not reachable` → налаштований віддалений endpoint CDP недосяжний із хоста gateway. -- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → для профілю attach-only немає досяжної цілі, або HTTP endpoint відповів, але CDP WebSocket все одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → у поточній інсталяції gateway відсутній повний пакет Playwright; ARIA snapshots і базові screenshots сторінки все ще можуть працювати, але навігація, AI snapshots, screenshots елементів за CSS-селекторами й експорт PDF залишаються недоступними. -- `fullPage is not supported for element screenshots` → запит screenshot поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики screenshot для Chrome MCP / `existing-session` мають використовувати захоплення сторінки або snapshot `--ref`, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooks завантаження файлів у Chrome MCP потребують snapshot refs, а не CSS-селекторів. -- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте по одному завантаженню за раз. -- `existing-session dialog handling does not support timeoutMs.` → hooks діалогів у профілях Chrome MCP не підтримують перевизначення timeout. -- `response body is not supported for existing-session profiles yet.` → `responsebody` все ще потребує керованого браузера або профілю raw CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. +- `browser.cdpUrl has invalid port` → у налаштованого URL CDP неправильний або позадіапазонний порт. +- `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. +- `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста шлюзу. +- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має досяжної цілі, або HTTP-кінцева точка відповіла, але CDP WebSocket усе одно не вдалося відкрити. +- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні шлюзу немає повного пакета Playwright; знімки ARIA і базові знімки сторінки все ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селекторами та експорт PDF залишаються недоступними. +- `fullPage is not supported for element screenshots` → запит на знімок екрана змішав `--full-page` з `--ref` або `--element`. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі знімка, а не CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів Chrome MCP потребують посилань зі знімка, а не CSS-селекторів. +- `existing-session file uploads currently support one file at a time.` → надсилайте по одному завантаженню за виклик у профілях Chrome MCP. +- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout. +- `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого профілю CDP. +- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або віддаленого CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію та звільнити стан емуляції Playwright/CDP без перезапуску всього шлюзу. Пов’язане: -- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) -- [/tools/browser](/tools/browser) +- [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting) +- [/tools/browser](/uk/tools/browser) -## Якщо після оновлення щось раптово зламалося +## Якщо ви оновилися і щось раптом зламалося -Більшість проблем після оновлення — це дрейф конфігурації або суворіші значення за замовчуванням, які тепер примусово застосовуються. +Більшість проблем після оновлення пов’язані з дрейфом конфігурації або з жорсткішими типовими значеннями, які тепер застосовуються. -### 1) Поведінка auth і перевизначення URL змінилася +### 1) Змінилася поведінка автентифікації та перевизначення URL ```bash openclaw gateway status @@ -396,13 +396,13 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на remote, навіть якщо локальний сервіс працює справно. -- Явні виклики `--url` не виконують fallback до збережених облікових даних. +- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на remote, навіть якщо локальний сервіс працює нормально. +- Явні виклики `--url` не повертаються до збережених облікових даних. -Поширені сигнатури: +Типові ознаки: -- `gateway connect failed:` → неправильна URL-ціль. -- `unauthorized` → endpoint досяжний, але auth неправильна. +- `gateway connect failed:` → неправильна ціль URL. +- `unauthorized` → кінцева точка досяжна, але автентифікація неправильна. ### 2) Guardrails для bind і auth стали суворішими @@ -416,15 +416,15 @@ openclaw logs --follow Що перевірити: -- Bind не через loopback (`lan`, `tailnet`, `custom`) потребують валідного шляху auth gateway: shared token/password auth або правильно налаштованого розгортання `trusted-proxy` не через loopback. -- Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. +- Bind не на loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації шлюзу: спільна автентифікація токеном/паролем або правильно налаштоване розгортання `trusted-proxy` не на loopback. +- Старі ключі, як-от `gateway.token`, не замінюють `gateway.auth.token`. -Поширені сигнатури: +Типові ознаки: -- `refusing to bind gateway ... without auth` → bind не через loopback без валідного шляху auth gateway. -- `RPC probe: failed` коли runtime працює → gateway живий, але недоступний із поточними auth/url. +- `refusing to bind gateway ... without auth` → bind не на loopback без дійсного шляху автентифікації шлюзу. +- `RPC probe: failed` while runtime is running → шлюз живий, але недоступний із поточними auth/url. -### 3) Стан pairing та ідентичності пристрою змінився +### 3) Змінився стан pairing та ідентичності пристрою ```bash openclaw devices list @@ -435,15 +435,15 @@ openclaw doctor Що перевірити: -- Pending approvals пристроїв для dashboard/nodes. -- Pending approvals pairing для DM після змін політики чи ідентичності. +- Очікувані схвалення пристроїв для dashboard/nodes. +- Очікувані схвалення DM pairing після змін політики або ідентичності. -Поширені сигнатури: +Типові ознаки: -- `device identity required` → auth пристрою не задоволено. +- `device identity required` → вимоги device auth не виконано. - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо після перевірок конфігурація сервісу й runtime все ще не збігаються, перевстановіть метадані сервісу з тим самим каталогом профілю/стану: +Якщо конфігурація сервісу та runtime все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого каталогу профілю/стану: ```bash openclaw gateway install --force @@ -452,6 +452,6 @@ openclaw gateway restart Пов’язане: -- [/gateway/pairing](/gateway/pairing) -- [/gateway/authentication](/gateway/authentication) -- [/gateway/background-process](/gateway/background-process) +- [/gateway/pairing](/uk/gateway/pairing) +- [/gateway/authentication](/uk/gateway/authentication) +- [/gateway/background-process](/uk/gateway/background-process) diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index e038ab195..7a2ce426e 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Відповідь на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання - Тріаж проблем, про які повідомляють користувачі, перед глибшим налагодженням summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw -title: Поширені запитання +title: FAQ x-i18n: - generated_at: "2026-04-06T12:48:08Z" + generated_at: "2026-04-06T15:34:21Z" model: gpt-5.4 provider: openai - source_hash: 391262b77c6c9b35253fd46b7d6fab324816c3cc25830f322f840fad0c9f58cf + source_hash: bddcde55cf4bcec4913aadab4c665b235538104010e445e4c99915a1672b1148 source_path: help/faq.md workflow: 15 --- -# Поширені запитання +# FAQ -Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, мультиагентність, OAuth/API-ключі, відмовостійкість моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, багатоагентність, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурації](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося @@ -25,15 +25,15 @@ x-i18n: openclaw status ``` - Швидкий локальний зведений стан: ОС + оновлення, доступність gateway/служби, агенти/сеанси, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). + Швидке локальне зведення: ОС + оновлення, доступність gateway/service, агенти/сесії, конфігурація провайдерів + проблеми під час виконання (коли gateway доступний). -2. **Звіт, який можна вставити й поширити (безпечний для спільного доступу)** +2. **Звіт, який можна вставити (безпечний для поширення)** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени приховано). + Діагностика лише для читання з хвостом логів (токени замасковано). 3. **Стан демона + порту** @@ -41,75 +41,75 @@ x-i18n: openclaw gateway status ``` - Показує стан supervisor під час виконання порівняно з доступністю RPC, цільовий URL probe і яку конфігурацію, імовірно, використовувала служба. + Показує runtime супервізора проти доступності RPC, цільовий URL перевірки та яку конфігурацію сервіс, імовірно, використав. -4. **Поглиблені probe-перевірки** +4. **Глибокі перевірки** ```bash openclaw status --deep ``` - Виконує живу probe-перевірку працездатності gateway, включно з перевірками каналів, де це підтримується + Виконує живу перевірку стану gateway, включно з перевірками каналів, коли це підтримується (потрібен доступний gateway). Див. [Стан](/uk/gateway/health). -5. **Перегляд останнього журналу в реальному часі** +5. **Показати кінець останнього логу** ```bash openclaw logs --follow ``` - Якщо RPC недоступний, використайте запасний варіант: + Якщо RPC недоступний, використовуйте запасний варіант: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від службових журналів; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові логи відокремлені від логів сервісу; див. [Логування](/uk/logging) та [Усунення несправностей](/uk/gateway/troubleshooting). -6. **Запустіть doctor (виправлення)** +6. **Запустити doctor (виправлення)** ```bash openclaw doctor ``` - Виправляє/мігрує конфігурацію та стан + запускає перевірки працездатності. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію/стан + запускає перевірки стану. Див. [Doctor](/uk/gateway/doctor). 7. **Знімок gateway** ```bash openclaw health --json - openclaw health --verbose # показує цільовий URL + шлях до конфігурації у разі помилок + openclaw health --verbose # shows the target URL + config path on errors ``` - Запитує в запущеного gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). + Запитує у запущеного gateway повний знімок (лише WS). Див. [Стан](/uk/gateway/health). -## Швидкий старт і початкове налаштування +## Швидкий старт і налаштування першого запуску - - Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж запитувати - у Discord, тому що більшість випадків "я застряг" — це **локальні проблеми конфігурації або середовища**, + + Використовуйте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати + в Discord, тому що більшість випадків «я застряг» — це **локальні проблеми конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали та допомагати виправляти - налаштування на рівні машини (PATH, служби, дозволи, файли автентифікації). Надайте їм **повну копію вихідного коду** - через hackable (git) install: + Ці інструменти можуть читати репозиторій, запускати команди, перевіряти логи та допомагати виправляти + налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Дайте їм **повний checkout вихідного коду** + через hackable (git) встановлення: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **з git checkout**, тому агент може читати код і документацію та - міркувати про точну версію, яку ви запускаєте. Пізніше ви завжди можете повернутися до стабільної версії, - повторно запустивши інсталятор без `--install-method git`. + Це встановлює OpenClaw **з git checkout**, тож агент може читати код + документацію та + аналізувати точну версію, яку ви запускаєте. Ви завжди можете повернутися до stable пізніше, + повторно запустивши встановлювач без `--install-method git`. - Порада: попросіть агента **спланувати й проконтролювати** виправлення (крок за кроком), а потім виконати лише - потрібні команди. Так зміни залишаться невеликими, і їх буде легше перевірити. + Порада: попросіть агента **спланувати та проконтролювати** виправлення (крок за кроком), а потім виконати лише + потрібні команди. Так зміни будуть невеликими й легшими для аудиту. - Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви виявили справжній баг або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) @@ -123,15 +123,15 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/агента + базової конфігурації. - - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. - - `openclaw doctor`: перевіряє та виправляє типові проблеми конфігурації/стану. + - `openclaw status`: швидкий знімок стану gateway/агента + базова конфігурація. + - `openclaw models status`: перевіряє автентифікацію провайдерів + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє поширені проблеми конфігурації/стану. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). - Документація з встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#first-60-seconds-if-something-is-broken). + Документація зі встановлення: [Встановлення](/uk/install), [Прапорці встановлювача](/uk/install/installer), [Оновлення](/uk/install/updating). @@ -139,122 +139,122 @@ x-i18n: Поширені причини пропуску heartbeat: - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/заголовкову заготовку - - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але жоден із інтервалів завдань ще не настав - - `alerts-disabled`: всю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній текст/каркас із заголовків + - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але жоден інтервал завдань ще не настав + - `alerts-disabled`: вся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі завдань часові позначки настання лише просуваються після завершення - реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. + У режимі завдань часові позначки виконання зсуваються лише після завершення + реального запуску heartbeat. Пропущені запуски не позначають завдання як завершені. Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). - - У репозиторії рекомендується запускати з вихідного коду та використовувати онбординг: + + Репозиторій рекомендує запуск із джерела та використання онбордингу: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати UI-ресурси. Після онбордингу зазвичай Gateway працює на порту **18789**. + Майстер також може автоматично зібрати ресурси UI. Після онбордингу зазвичай ви запускаєте Gateway на порту **18789**. - Із вихідного коду (для контриб'юторів/розробників): + Із джерела (для учасників/розробки): ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build - pnpm ui:build # автоматично встановлює залежності UI під час першого запуску + pnpm ui:build # auto-installs UI deps on first run openclaw onboard ``` - Якщо у вас ще немає глобального встановлення, запускайте через `pnpm openclaw onboard`. + Якщо у вас ще немає глобального встановлення, запустіть це через `pnpm openclaw onboard`. - Майстер відкриває браузер із чистим (без токена в URL) URL dashboard одразу після онбордингу, а також друкує посилання у зведенні. Залиште цю вкладку відкритою; якщо вона не відкрилася, скопіюйте/вставте надрукований URL на тій самій машині. + Майстер відкриває ваш браузер із чистим URL dashboard (без токена) одразу після онбордингу, а також друкує посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надрукований URL на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується автентифікація за shared secret, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Якщо запитує автентифікацію shared-secret, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - Якщо shared secret ще не налаштовано, згенеруйте токен командою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште loopback bind, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставляння shared secret, за умови довіреного gateway host); HTTP API все одно вимагають автентифікації shared secret, якщо ви навмисно не використовуєте private-ingress `none` або автентифікацію HTTP через trusted-proxy. - Некоректні одночасні спроби автентифікації Serve від того самого клієнта серіалізуються ще до того, як failed-auth limiter зафіксує їх, тому вже друга невдала повторна спроба може показувати `retry later`. - - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, потім вставте відповідний shared secret у налаштування dashboard. - - **Identity-aware reverse proxy**: залиште Gateway за trusted proxy не на loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація shared secret через tunnel усе одно застосовується; якщо буде запит, вставте налаштований токен або пароль. + - **Tailscale Serve** (рекомендовано): залишайте bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` дорівнює `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставляння shared secret, за умови довіреного хоста gateway); HTTP API усе ще вимагають shared-secret auth, якщо ви навмисно не використовуєте private-ingress `none` або HTTP-аутентифікацію trusted-proxy. + Некоректні одночасні спроби автентифікації Serve від одного клієнта серіалізуються до того, як лімітер невдалих автентифікацій зафіксує їх, тож друга невдала спроба вже може показати `retry later`. + - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний shared secret у налаштування dashboard. + - **Identity-aware reverse proxy**: тримайте Gateway за trusted proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. + - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, після чого відкрийте `http://127.0.0.1:18789/`. Автентифікація shared-secret усе ще застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит. - Див. [Dashboard](/web/dashboard) і [Web-поверхні](/web) для режимів bind і деталей автентифікації. + Див. [Dashboard](/web/dashboard) і [Web surfaces](/web) для режимів bind та деталей автентифікації. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на схвалення до чат-призначень - - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals + - `approvals.exec`: пересилає запити на підтвердження до адрес чатів + - `channels..execApprovals`: робить цей канал нативним клієнтом підтвердження для exec approvals - Політика exec на host усе одно залишається справжнім бар'єром схвалення. Конфігурація чату лише керує тим, - де з'являються запити на схвалення і як люди можуть на них відповідати. + Політика exec на хості все одно є реальним бар’єром підтвердження. Конфігурація чату лише визначає, де з’являються + запити на підтвердження і як люди можуть на них відповідати. - У більшості сценаріїв вам **не** потрібні обидві: + У більшості налаштувань вам **не** потрібні обидва варіанти: - - Якщо чат уже підтримує команди й відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно вивести схвалювачів, OpenClaw тепер автоматично вмикає native approvals із пріоритетом DM, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. - - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; агент повинен включати ручну команду `/approve` лише якщо результат інструмента каже, що чат-схвалення недоступні або ручне схвалення — єдиний шлях. - - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати до інших чатів або окремих операційних кімнат. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише якщо ви явно хочете, щоб запити на схвалення публікувалися назад у вихідну кімнату/тему. - - Схвалення plugins — це окрема категорія: вони за замовчуванням використовують `/approve` у тому самому чаті, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-approval. + - Якщо чат уже підтримує команди та відповіді, `/approve` у тому ж чаті працює через спільний шлях. + - Якщо підтримуваний нативний канал може безпечно визначати тих, хто підтверджує, OpenClaw тепер автоматично вмикає DM-first native approvals, коли `channels..execApprovals.enabled` не задано або дорівнює `"auto"`. + - Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve`, лише якщо результат інструмента каже, що підтвердження через чат недоступні або ручне підтвердження — єдиний шлях. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або окремі кімнати ops. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише якщо ви явно хочете, щоб запити на підтвердження публікувалися назад у вихідну кімнату/тему. + - Підтвердження plugins знову окремі: за замовчуванням вони використовують `/approve` у тому ж чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають plugin-approval-native обробку поверх цього. Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun для Gateway **не рекомендується**. + + Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun **не рекомендовано** для Gateway. - Так. Gateway легковаговий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 ядра** і приблизно **500MB** + Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** та приблизно **500MB** диска, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (журнали, медіа, інші служби), **рекомендується 2GB**, але це + Якщо вам потрібен додатковий запас (логи, медіа, інші сервіси), **рекомендується 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете підключати **nodes** на ноутбуці/телефоні для + Порада: маленький Pi/VPS може хостити Gateway, а ви можете під’єднати **nodes** на ноутбуці/телефоні для локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - - Коротко: це працює, але очікуйте шорстких кутів. + + Коротко: працює, але очікуйте гострих кутів. - - Використовуйте **64-бітну** ОС і Node >= 22. - - Віддавайте перевагу **hackable (git) install**, щоб бачити журнали та швидко оновлюватися. - - Починайте без channels/skills, а потім додавайте їх по одному. - - Якщо натрапляєте на дивні проблеми з бінарниками, зазвичай це проблема **сумісності ARM**. + - Використовуйте **64-bit** ОС і Node >= 22. + - Надавайте перевагу **hackable (git) install**, щоб бачити логи й швидко оновлюватися. + - Починайте без каналів/Skills, потім додавайте їх по одному. + - Якщо натрапили на дивні проблеми з бінарниками, зазвичай це проблема **ARM compatibility**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від доступності та автентифікації Gateway. TUI також надсилає - "Wake up, my friend!" автоматично під час першого вилуплення. Якщо ви бачите цей рядок **без відповіді** - і токени залишаються на 0, агент так і не запустився. + + Цей екран залежить від того, чи доступний і автентифікований Gateway. TUI також автоматично надсилає + «Wake up, my friend!» під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + і токени залишаються на 0, агент ніколи не запускався. 1. Перезапустіть Gateway: @@ -276,29 +276,29 @@ x-i18n: openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з'єднання активне і що UI + Якщо Gateway віддалений, переконайтеся, що тунель/з’єднання Tailscale працює, а UI вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - - Так. Скопіюйте **каталог стану** та **workspace**, а потім один раз запустіть Doctor. Це - збереже вашого бота **точно таким самим** (пам'ять, історія сеансів, автентифікація та + + Так. Скопіюйте **директорію стану** та **workspace**, потім один раз запустіть Doctor. Це + збереже вашого бота «точно таким самим» (пам’ять, історію сесій, автентифікацію та стан каналів), якщо ви скопіюєте **обидва** розташування: - 1. Установіть OpenClaw на новій машині. + 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). - 4. Запустіть `openclaw doctor` і перезапустіть службу Gateway. + 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. - Це збереже конфігурацію, профілі автентифікації, облікові дані WhatsApp, сеанси й пам'ять. Якщо ви в - remote mode, пам'ятайте, що store сеансів і workspace належать gateway host. + Це збереже конфігурацію, профілі автентифікації, WhatsApp credentials, сесії та пам’ять. Якщо ви працюєте у + віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і workspace. - **Важливо:** якщо ви лише commit/push свій workspace у GitHub, ви створюєте резервну копію - **пам'яті + bootstrap-файлів**, але **не** історії сеансів чи автентифікації. Вони живуть - у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push свій workspace на GitHub, ви резервуєте + **пам’ять + bootstrap файли**, але **не** історію сесій чи автентифікацію. Вони живуть + у `~/.openclaw/` (наприклад `~/.openclaw/agents//sessions/`). - Пов'язане: [Міграція](/uk/install/migrating), [Де що лежить на диску](#де-що-лежить-на-диску), + Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#where-things-live-on-disk), [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), [Віддалений режим](/uk/gateway/remote). @@ -308,18 +308,18 @@ x-i18n: Перевірте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи — вгорі. Якщо верхній розділ позначено як **Unreleased**, то наступний датований - розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і - **Fixes** (а також розділами документації/іншими, за потреби). + Найновіші записи — зверху. Якщо верхній розділ позначено як **Unreleased**, наступний датований + розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** та + **Fixes** (а також docs/іншими розділами, коли потрібно). - - Деякі підключення Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity - Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім спробуйте ще раз. + + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity + Advanced Security. Вимкніть це або додайте `docs.openclaw.ai` в allowlist, а потім повторіть спробу. Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: + Якщо ви все ще не можете зайти на сайт, документація дзеркалюється на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -330,21 +330,21 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай stable-реліз спочатку з'являється в **beta**, а потім окремий - крок просування переміщує цю ж версію в `latest`. За потреби супроводжувачі також можуть - публікувати одразу в `latest`. Саме тому beta і stable можуть - вказувати на **ту саму версію** після просування. + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний + крок підвищення переміщує цю саму версію в `latest`. Супровідники також можуть + опублікувати відразу в `latest`, коли це потрібно. Тому beta і stable можуть + вказувати на **ту саму версію** після підвищення. - Дивіться, що змінилося: + Див. що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Для однорядкових команд встановлення та різниці між beta і dev дивіться accordion нижче. + Для однорядкових команд встановлення та різниці між beta і dev див. accordion нижче. - - **Beta** — це npm dist-tag `beta` (після просування може збігатися з `latest`). - **Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`. + + **Beta** — це npm dist-tag `beta` (після підвищення може збігатися з `latest`). + **Dev** — це рухома голова `main` (git); при публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -356,15 +356,15 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Інсталятор для Windows (PowerShell): + Встановлювач для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). + Більше деталей: [Канали розробки](/uk/install/development-channels) і [Прапорці встановлювача](/uk/install/installer). - - Є два варіанти: + + Два варіанти: 1. **Dev channel (git checkout):** @@ -372,9 +372,9 @@ x-i18n: openclaw update --channel dev ``` - Це перемикає на гілку `main` і оновлює з вихідного коду. + Це перемикає вас на гілку `main` і оновлює з джерела. - 2. **Hackable install (із сайту інсталятора):** + 2. **Hackable install (із сайту встановлювача):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -382,7 +382,7 @@ x-i18n: Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому ручному clone, використайте: + Якщо ви надаєте перевагу чистому ручному clone, використовуйте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -396,25 +396,25 @@ x-i18n: - - Орієнтовно: + + Приблизно: - **Встановлення:** 2-5 хвилин - **Онбординг:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте - Якщо щось зависає, скористайтеся [Застряг інсталятор](#швидкий-старт-і-початкове-налаштування) - і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). + Якщо зависає, використовуйте [Встановлювач завис?](#quick-start-and-first-run-setup) + і швидкий цикл налагодження в [Я застряг](#quick-start-and-first-run-setup). - - Повторно запустіть інсталятор із **докладним виводом**: + + Повторно запустіть встановлювач із **детальним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Встановлення beta з докладним виводом: + Встановлення beta з детальним виводом: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -429,48 +429,48 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 ще не має окремого прапорця -Verbose. + # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - Більше параметрів: [Прапорці інсталятора](/uk/install/installer). + Більше варіантів: [Прапорці встановлювача](/uk/install/installer). - Дві поширені проблеми на Windows: + Дві поширені проблеми Windows: **1) npm error spawn git / git not found** - - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. + - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. + - Закрийте й знову відкрийте PowerShell, потім повторно запустіть встановлювач. **2) openclaw is not recognized після встановлення** - - Ваша глобальна папка bin npm не входить до PATH. + - Ваша глобальна тека npm bin не додана до PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до вашого user PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - - Після оновлення PATH закрийте й знову відкрийте PowerShell. + - Додайте цей каталог до PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Закрийте й знову відкрийте PowerShell після оновлення PATH. - Якщо вам потрібне найгладше налаштування на Windows, використовуйте **WSL2**, а не нативний Windows. + Якщо ви хочете найплавніше налаштування Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). - - Зазвичай це невідповідність code page консолі в нативних оболонках Windows. + + Зазвичай це невідповідність code page консолі у нативних оболонках Windows. Симптоми: - - Вивід `system.run`/`exec` показує китайські символи як mojibake - - Та сама команда виглядає нормально в іншому профілі термінала + - Вивід `system.run`/`exec` показує китайську як mojibake + - Та сама команда має нормальний вигляд в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -487,66 +487,66 @@ x-i18n: openclaw gateway restart ``` - Якщо це все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: + Якщо це все ще відтворюється в останньому OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **hackable (git) install**, щоб мати повний вихідний код і документацію локально, а потім запитайте + Використовуйте **hackable (git) install**, щоб мати повний вихідний код і документацію локально, а тоді запитайте вашого бота (або Claude/Codex) _з цієї папки_, щоб він міг читати репозиторій і відповідати точно. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Докладніше: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). + Більше деталей: [Встановлення](/uk/install) і [Прапорці встановлювача](/uk/install/installer). - - Коротка відповідь: дотримуйтесь інструкції для Linux, а потім запустіть онбординг. + + Коротка відповідь: дотримуйтесь гайда для Linux, а потім запустіть онбординг. - - Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux). - - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - - Інсталятор + оновлення: [Встановлення та оновлення](/uk/install/updating). + - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). + - Повний покроковий гайд: [Початок роботи](/uk/start/getting-started). + - Встановлювач + оновлення: [Встановлення та оновлення](/uk/install/updating). - - Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. + + Підійде будь-який Linux VPS. Встановіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. - Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). - Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). + Гайди: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). + Віддалений доступ: [Віддалений gateway](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть одного й дотримуйтесь інструкції: + + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Оберіть одного і дотримуйтесь гайда: - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює в хмарі: **Gateway працює на сервері**, а ви звертаєтеся до нього + Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + workspace - живуть на сервері, тому сприймайте host як джерело істини й робіть його резервні копії. + живуть на сервері, тож вважайте хост джерелом істини й робіть його резервні копії. - Ви можете підключати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ до - локального екрана/камери/canvas або запускати команди на своєму ноутбуці, зберігаючи + Ви можете під’єднувати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ + до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). + Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений gateway](/uk/gateway/remote). Nodes: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - - Коротка відповідь: **можливо, але не рекомендується**. Процес оновлення може перезапустити - Gateway (що скине активний сеанс), може вимагати чистого git checkout і - може запитати підтвердження. Безпечніше запускати оновлення з оболонки від імені оператора. + + Коротка відповідь: **можливо, але не рекомендується**. Потік оновлення може перезапустити + Gateway (що розірве активну сесію), може потребувати чистого git checkout і + може запитувати підтвердження. Безпечніше запускати оновлення з оболонки як оператор. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам усе ж потрібно автоматизувати це з агента: + Якщо вам обов’язково потрібно автоматизувати це від агента: ```bash openclaw update --yes --no-restart @@ -569,39 +569,38 @@ x-i18n: - - `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: + + `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проведе вас через: - - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, legacy setup-token Anthropic, а також локальні варіанти моделей, як-от LM Studio) - - Розташування **workspace** + bootstrap-файли - - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) - - **Встановлення демона** (LaunchAgent на macOS; user unit systemd на Linux/WSL2) - - **Перевірки працездатності** і вибір **Skills** + - **Налаштування моделей/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також локальні варіанти моделей, наприклад LM Studio) + - Розташування **workspace** + bootstrap файли + - **Налаштування gateway** (bind/port/auth/tailscale) + - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, такі як QQ Bot) + - **Встановлення демона** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) + - **Перевірки стану** та вибір **Skills** - Він також попереджає, якщо налаштована модель невідома або для неї бракує автентифікації. + Він також попереджає, якщо налаштована модель невідома або бракує автентифікації. - + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов'язкові способи автентифікації в цих провайдерів. + Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **API-ключ Anthropic**: звичайний білінг Anthropic API - - **Автентифікація підпискою Claude в OpenClaw**: Anthropic повідомила користувачам OpenClaw - **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що для цього потрібне - **Extra Usage**, яке оплачується окремо від підписки + - **Anthropic API key**: звичайна оплата Anthropic API + - **Claude CLI / Claude subscription auth в OpenClaw**: співробітники Anthropic + сказали нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` + як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову + політику - Наші локальні відтворення також показують, що `claude -p --append-system-prompt ...` може - натрапляти на той самий захист Extra Usage, коли доданий prompt ідентифікує - OpenClaw, тоді як той самий рядок prompt **не** відтворює це блокування на - шляху Anthropic SDK + API key. OpenAI Codex OAuth явно - підтримується для зовнішніх інструментів, таких як OpenClaw. + Для довгоживучих хостів gateway Anthropic API keys усе ще є більш + передбачуваним налаштуванням. OpenAI Codex OAuth явно підтримується для зовнішніх + інструментів, таких як OpenClaw. - OpenClaw також підтримує інші хостингові варіанти з підписною моделлю, зокрема + OpenClaw також підтримує інші хостингові варіанти підписки, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. @@ -613,131 +612,151 @@ x-i18n: - Так, але сприймайте це як **автентифікацію підпискою Claude з Extra Usage**. + Так. - Підписки Claude Pro/Max не включають API-ключ. У контексті OpenClaw це - означає, що застосовується спеціальне повідомлення Anthropic про білінг для OpenClaw: трафік - за підпискою вимагає **Extra Usage**. Якщо ви хочете трафік Anthropic без - цього шляху Extra Usage, використовуйте замість цього API-ключ Anthropic. + Співробітники Anthropic сказали нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому + OpenClaw розглядає автентифікацію через підписку Claude і використання `claude -p` як санкціоновані + для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо ви хочете + найпередбачуваніше серверне налаштування, замість цього використовуйте Anthropic API key. - - Так, але підтримуване трактування тепер таке: + + Так. - - Anthropic в OpenClaw із підпискою означає **Extra Usage** - - Anthropic в OpenClaw без цього шляху означає **API key** + Співробітники Anthropic сказали нам, що таке використання знову дозволене, тому OpenClaw вважає + повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, + якщо Anthropic не опублікує нову політику. - Anthropic setup-token і далі доступний як legacy/manual шлях OpenClaw, - і спеціальне повідомлення Anthropic про білінг для OpenClaw усе ще діє для нього. Ми - також локально відтворили той самий білінговий захист при прямому використанні - `claude -p --append-system-prompt ...`, коли доданий prompt - ідентифікує OpenClaw, тоді як той самий рядок prompt **не** відтворювався на - шляху Anthropic SDK + API key. - - Для production або багатокористувацьких навантажень автентифікація API key Anthropic — - безпечніший і рекомендований вибір. Якщо ви хочете інші хостингові - варіанти з підписною моделлю в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model - Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і - [GLM Models](/uk/providers/glm). + Setup-token Anthropic усе ще доступний як підтримуваний токен-шлях OpenClaw, але OpenClaw тепер віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. + Для production або багатокористувацьких навантажень автентифікація через Anthropic API key усе ще є + безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші підпискові + хостингові варіанти в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax), і [GLM + Models](/uk/providers/glm). -Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви -використовуєте **Claude CLI**, зачекайте, поки вікно скинеться, або підвищте тариф. Якщо ви -використовуєте **API key Anthropic**, перевірте Anthropic Console -на предмет використання/білінгу і за потреби підвищте ліміти. +Це означає, що ваша **квота/ліміт швидкості Anthropic** вичерпано для поточного вікна. Якщо ви +використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть план. Якщо ви +використовуєте **Anthropic API key**, перевірте Anthropic Console +на предмет використання/білінгу і за потреби збільште ліміти. Якщо повідомлення конкретно таке: - `Extra usage is required for long context requests`, то запит намагається використати - бета-функцію Anthropic із контекстом 1M (`context1m: true`). Це працює лише тоді, коли ваш - обліковий запис має право на білінг довгого контексту (білінг API key або - шлях входу в Claude через OpenClaw з увімкненим Extra Usage). + `Extra usage is required for long context requests`, запит намагається використати + 1M context beta Anthropic (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на long-context billing (оплата API key або + шлях OpenClaw Claude-login з увімкненим Extra Usage). - Порада: установіть **fallback model**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений за rate limit. - Див. [Моделі](/cli/models), [OAuth](/uk/concepts/oauth) і + Порада: задайте **fallback model**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений rate limit. + Див. [Моделі](/cli/models), [OAuth](/uk/concepts/oauth), і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має bundled-провайдер **Amazon Bedrock (Converse)**. Якщо присутні AWS env markers, OpenClaw може автоматично виявляти каталог потокових/текстових моделей Bedrock і об'єднувати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати ручний запис провайдера. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо вам зручніше керований шлях із ключем, OpenAI-сумісний проксі перед Bedrock також лишається коректним варіантом. + Так. OpenClaw має bundled-провайдера **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявити каталог streaming/text Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати ручний запис провайдера. Див. [Amazon Bedrock](/uk/providers/bedrock) та [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock теж є дійсним варіантом. - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Під час онбордингу можна пройти OAuth-процес, і за потреби буде встановлено модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Під час онбордингу можна запустити потік OAuth, і за потреби він встановить типовою модель `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) та [Онбординг (CLI)](/uk/start/wizard). - - Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/процесах - на кшталт OpenClaw. Онбординг може провести OAuth-процес за вас. + + OpenClaw розділяє ці два маршрути: - Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth + - `openai/gpt-5.4` = прямий OpenAI Platform API + + У OpenClaw вхід через ChatGPT/Codex прив’язаний до маршруту `openai-codex/*`, + а не до прямого маршруту `openai/*`. Якщо ви хочете прямий API-шлях у + OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). + Якщо ви хочете вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + + + + + `openai-codex/*` використовує маршрут Codex OAuth, і його доступні вікна квоти + керуються OpenAI та залежать від плану. На практиці ці ліміти можуть відрізнятися від + досвіду на сайті/в застосунку ChatGPT, навіть коли обидва прив’язані до одного облікового запису. + + OpenClaw може показувати поточні видимі вікна використання/квоти провайдера в + `openclaw models status`, але не вигадує і не нормалізує права ChatGPT-web + у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, + використовуйте `openai/*` з API key. + + + + + Так. OpenClaw повністю підтримує **OpenAI Code (Codex) subscription OAuth**. + OpenAI прямо дозволяє використання subscription OAuth у зовнішніх інструментах/потоках + на кшталт OpenClaw. Під час онбордингу можна запустити потік OAuth за вас. + + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers), і [Онбординг (CLI)](/uk/start/wizard). - Gemini CLI використовує **plugin auth flow**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **plugin auth flow**, а не client id або secret у `openclaw.json`. Кроки: - 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` + 1. Встановіть Gemini CLI локально, щоб `gemini` був у `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Увімкніть plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3.1-pro-preview` - 5. Якщо запити не проходять, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host + 4. Типова модель після входу: `google-gemini-cli/gemini-3.1-pro-preview` + 5. Якщо запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає OAuth-токени в auth profiles на gateway host. Деталі: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Деталі: [Провайдери моделей](/uk/concepts/model-providers). - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; невеликі карти обрізають контекст і допускають витоки. Якщо вже потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і дивіться [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають і пропускають зайве. Якщо вже потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Вибирайте endpoint-и, прив'язані до регіону. OpenRouter пропонує US-hosted варіанти для MiniMax, Kimi і GLM; виберіть US-hosted варіант, щоб зберегти дані в межах регіону. Ви все одно можете перелічувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб fallback-и залишалися доступними, водночас поважаючи вибраного регіонального провайдера. + + Вибирайте region-pinned endpoints. OpenRouter надає варіанти з хостингом у США для MiniMax, Kimi та GLM; обирайте US-hosted варіант, щоб дані залишалися в регіоні. Ви все одно можете перелічити Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти лишалися доступними й водночас поважали обраного регіонального провайдера. - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini не обов'язковий — деякі люди - купують його як завжди увімкнений host, але підійде й невеликий VPS, домашній сервер або коробка рівня Raspberry Pi. + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий — + дехто купує його як постійно ввімкнений хост, але маленький VPS, домашній сервер або коробка класу Raspberry Pi теж підійдуть. - Mac потрібен лише **для інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — - сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключайте node macOS. + Mac потрібен лише для **інструментів лише для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — + сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте macOS node. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Вам потрібен **якийсь пристрій macOS**, увійшовший у Messages. Це **не обов'язково** має бути Mac mini — - підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. + + Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini — + підійде будь-який Mac. **Використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) для iMessage — сервер BlueBubbles працює на macOS, а Gateway може працювати на Linux або в іншому місці. - Поширені сценарії: + Поширені налаштування: - - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, увійшовшому в Messages. - - Запускайте все на Mac, якщо хочете найпростіше однокомп'ютерне налаштування. + - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac із входом у Messages. + - Запускайте все на Mac, якщо хочете найпростіше налаштування на одній машині. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як - **node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові - можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключитися як + **node** (додатковий пристрій). Nodes не запускають Gateway — вони надають додаткові + можливості, такі як screen/camera/canvas і `system.run` на цьому пристрої. Поширений шаблон: - - Gateway на Mac mini (завжди увімкнений). - - MacBook Pro запускає застосунок macOS або node host і підключається до Gateway. + - Gateway на Mac mini (постійно ввімкнений). + - MacBook Pro запускає застосунок macOS або хост node і під’єднується до Gateway. - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). @@ -745,22 +764,22 @@ x-i18n: - Bun **не рекомендується**. Ми бачимо помилки під час виконання, особливо з WhatsApp і Telegram. - Використовуйте **Node** для стабільних gateway. + Bun **не рекомендовано**. Ми бачимо runtime-баґи, особливо з WhatsApp і Telegram. + Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете експериментувати з Bun, робіть це на непродукційному gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на не production gateway без WhatsApp/Telegram. - - `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім'я користувача бота. + + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не username бота. Під час онбордингу можна ввести `@username`, і він буде перетворений на числовий ID, але авторизація OpenClaw використовує лише числові ID. - Безпечніше (без стороннього бота): + Безпечніший варіант (без стороннього бота): - - Напишіть боту в DM, потім запустіть `openclaw logs --follow` і подивіться `from.id`. + - Напишіть боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: @@ -774,12 +793,12 @@ x-i18n: - - Так, через **маршрутизацію мультиагентів**. Прив'яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і store сеансів. Відповіді все одно надходитимуть від **того самого облікового запису WhatsApp**, а контроль доступу для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація мультиагентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **багатоагентну маршрутизацію**. Прив’яжіть WhatsApp **DM** кожного відправника (peer `kind: "direct"`, E.164 відправника, наприклад `+15551234567`) до різного `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть із **того самого облікового запису WhatsApp**, а контроль доступу до DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для цього облікового запису WhatsApp. Див. [Багатоагентна маршрутизація](/uk/concepts/multi-agent) та [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію мультиагентів: задайте кожному агенту власну модель за замовчуванням, а потім прив'яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації є в [Маршрутизація мультиагентів](/uk/concepts/multi-agent). Також див. [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте багатоагентну маршрутизацію: дайте кожному агенту власну типову модель, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації є в [Багатоагентній маршрутизації](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) та [Конфігурація](/uk/gateway/configuration). @@ -792,27 +811,27 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, знаходилися в non-login оболонках. - Останні збірки також додають поширені user bin-каталоги в Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в оболонках без входу. + Останні збірки також додають поширені користувацькі теки bin у Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` та `FNM_DIR`, коли вони задані. - - **Hackable (git) install:** повний checkout вихідного коду, редагований, найкращий для контриб'юторів. - Ви локально запускаєте збірки й можете виправляти код/документацію. - - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію "просто запустити". - Оновлення надходять із npm dist-tags. + - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для учасників. + Ви локально запускаєте збірки та можете вносити зміни в код/документацію. + - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для «просто запустити». + Оновлення приходять із npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - - Так. Установіть інший варіант, а потім запустіть Doctor, щоб служба gateway вказувала на нову entrypoint. - Це **не видаляє ваші дані** — змінюється лише інсталяція коду OpenClaw. Ваш стан + + Так. Встановіть інший варіант, потім запустіть Doctor, щоб сервіс gateway вказував на нову entrypoint. + Це **не видаляє ваші дані** — змінюється лише спосіб встановлення коду OpenClaw. Ваш стан (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. - Із npm на git: + З npm на git: ```bash git clone https://github.com/openclaw/openclaw.git @@ -823,7 +842,7 @@ x-i18n: openclaw gateway restart ``` - Із git на npm: + З git на npm: ```bash npm install -g openclaw@latest @@ -831,63 +850,63 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint служби gateway і пропонує переписати конфігурацію служби відповідно до поточного встановлення (у автоматизації використовуйте `--repair`). + Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (в автоматизації використовуйте `--repair`). - Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-лежить-на-диску). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#where-things-live-on-disk). - - Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо ви хочете - мінімум тертя й вас влаштовують сон/перезапуски, запускайте локально. + + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен + найменший поріг входу і вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Плюси:** безкоштовний сервер, прямий доступ до локальних файлів, видиме вікно браузера. - - **Мінуси:** сон/обриви мережі = розриви з'єднання, оновлення ОС/перезавантаження переривають роботу, машина має залишатися активною. + - **Переваги:** без вартості сервера, прямий доступ до локальних файлів, видиме вікно браузера. + - **Недоліки:** сон/обриви мережі = роз’єднання, оновлення ОС/перезавантаження переривають, машина має залишатися активною. **VPS / хмара** - - **Плюси:** завжди увімкнено, стабільна мережа, немає проблем зі сном ноутбука, простіше підтримувати в роботі. - - **Мінуси:** часто працює без голови (використовуйте знімки екрана), доступ до файлів лише віддалений, для оновлень потрібен SSH. + - **Переваги:** завжди ввімкнено, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати запуск. + - **Недоліки:** часто headless (використовуйте скріншоти), доступ до файлів лише віддалено, для оновлень потрібен SSH. - **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний реальний компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). + **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдина реальна різниця — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас уже були розриви gateway. Локальний варіант чудовий, коли ви активно користуєтеся Mac і хочете доступ до локальних файлів або UI-автоматизацію з видимим браузером. + **Рекомендовано за замовчуванням:** VPS, якщо у вас раніше були роз’єднання gateway. Локальний запуск чудовий, коли ви активно користуєтесь Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером. - Це не обов'язково, але **рекомендується для надійності та ізоляції**. + Не обов’язково, але **рекомендується для надійності та ізоляції**. - - **Виділений host (VPS/Mac mini/Pi):** завжди увімкнений, менше перебоїв через сон/перезавантаження, чистіші дозволи, легше підтримувати в роботі. - - **Спільний ноутбук/ПК:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше перерв через сон/перезавантаження, чистіші дозволи, простіше тримати запущеним. + - **Спільний ноутбук/десктоп:** цілком нормально для тестування й активного використання, але очікуйте пауз під час сну машини або оновлень. - Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному host і підключайте ноутбук як **node** для локальних screen/camera/exec інструментів. Див. [Nodes](/uk/nodes). + Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук під’єднуйте як **node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). Для рекомендацій із безпеки прочитайте [Безпека](/uk/gateway/security). - - OpenClaw легковаговий. Для базового Gateway + одного чат-каналу: + + OpenClaw легкий. Для базового Gateway + одного каналу чату: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше із запасом (журнали, медіа, кілька каналів). Інструменти node і автоматизація браузера можуть бути ресурсомісткими. + - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (логи, медіа, кілька каналів). Інструменти node і автоматизація браузера можуть споживати багато ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях установлення на Linux там протестовано найкраще. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Саме цей шлях встановлення для Linux протестовано найкраще. Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди увімкненою, доступною й мати достатньо - RAM для Gateway та будь-яких увімкнених каналів. + + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна й мати достатньо + RAM для Gateway і будь-яких каналів, які ви вмикаєте. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіаінструменти. + - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіа-інструменти. - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. Якщо ви на Windows, **WSL2 — найпростіший варіант у стилі VM** і має найкращу @@ -901,83 +920,83 @@ x-i18n: - OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на тих платформах обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, такі як QQ Bot) і також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнена control plane; сам помічник і є продуктом. + OpenClaw — це персональний AI-асистент, який ви запускаєте на власних пристроях. Він відповідає на платформах обміну повідомленнями, якими ви вже користуєтесь (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, такі як QQ Bot), а також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнений control plane; асистент — це сам продукт. - OpenClaw — це не "просто обгортка для Claude". Це **локальна control plane**, яка дає змогу запускати - потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі - станними сеансами, пам'яттю та інструментами — без передавання контролю над вашими процесами хостинговому - SaaS. + OpenClaw — це не «просто обгортка над Claude». Це **локальний-first control plane**, який дозволяє вам запускати + потужного асистента на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтесь, із + сесіями зі станом, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами + хостинговому SaaS. Основні переваги: - - **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте - workspace + історію сеансів локально. - - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і тримайте + workspace + історію сесій локально. + - **Реальні канали, а не web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, плюс мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією - і failover на рівні агента. - - **Варіант лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. - - **Маршрутизація мультиагентів:** окремі агенти для каналу, облікового запису або завдання, кожен зі своїм - workspace та значеннями за замовчуванням. - - **Відкритий код і можливість модифікації:** перевіряйте, розширюйте й самостійно розміщуйте без vendor lock-in. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією + та резервуванням на рівні агента. + - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. + - **Багатоагентна маршрутизація:** окремі агенти на канал, обліковий запис або завдання, кожен зі своїм + workspace і типовими значеннями. + - **Відкритий код і можливість зламувати/розширювати:** перевіряйте, розширюйте та self-host без vendor lock-in. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Мультиагентність](/uk/concepts/multi-agent), - [Пам'ять](/uk/concepts/memory). + Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Багатоагентність](/uk/concepts/multi-agent), + [Пам’ять](/uk/concepts/memory). - + Хороші перші проєкти: - - Створити вебсайт (WordPress, Shopify або простий статичний сайт). + - Створити сайт (WordPress, Shopify або простий статичний сайт). - Прототипувати мобільний застосунок (структура, екрани, план API). - - Організувати файли та папки (очищення, іменування, теги). - - Підключити Gmail і автоматизувати підсумки чи follow-ups. + - Організувати файли та папки (очищення, назви, теги). + - Під’єднати Gmail і автоматизувати підсумки чи follow-up. - Він може працювати з великими завданнями, але найкраще працює, коли ви ділите їх на фази й - використовуєте sub agents для паралельної роботи. + Він може впоратися з великими завданнями, але найкраще працює, коли ви ділите їх на етапи + і використовуєте sub-agents для паралельної роботи. - - Повсякденні переваги зазвичай виглядають так: + + Щоденна користь зазвичай виглядає так: - - **Персональні брифінги:** підсумки inbox, календаря та новин, які вас цікавлять. - - **Дослідження та чернетки:** швидке дослідження, підсумки й перші чернетки для листів або документів. - - **Нагадування та follow-ups:** підказки й чеклісти на основі cron або heartbeat. + - **Персональні брифінги:** підсумки пошти, календаря та новин, які вам важливі. + - **Дослідження і чернетки:** швидке дослідження, підсумки та перші чернетки листів або документів. + - **Нагадування та follow-up:** підказки та чеклісти на основі cron або heartbeat. - **Автоматизація браузера:** заповнення форм, збирання даних і повторення веб-завдань. - - **Координація між пристроями:** надішліть завдання з телефону, дозвольте Gateway виконати його на сервері й отримайте результат назад у чат. + - **Координація між пристроями:** надішліть завдання з телефону, дайте Gateway виконати його на сервері й отримайте результат назад у чат. - - Так — для **дослідження, кваліфікації й підготовки чернеток**. Він може сканувати сайти, складати короткі списки, - підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів. + + Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, складати короткі списки, + підсумовувати потенційних клієнтів і писати чернетки outreach або рекламного тексту. - Для **outreach або рекламних кампаній** залишайте людину в контурі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ та перевіряйте все перед відправленням. Найбезпечніший шаблон — дозволити - OpenClaw підготувати чернетку, а вам — затвердити її. + Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і + політик платформ, і перевіряйте все перед відправленням. Найбезпечніший шаблон — нехай + OpenClaw готує чернетку, а ви затверджуєте. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний помічник** і координаційний шар, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу кодування в репозиторії. Використовуйте OpenClaw, коли - вам потрібні довготривала пам'ять, доступ із різних пристроїв і оркестрація інструментів. + OpenClaw — це **персональний асистент** і рівень координації, а не заміна IDE. Використовуйте + Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли + вам потрібні стійка пам’ять, доступ між пристроями та оркестрація інструментів. Переваги: - - **Постійна пам'ять + workspace** між сеансами - - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (браузер, файли, планування, hooks) - - **Завжди ввімкнений Gateway** (працює на VPS, взаємодіяйте звідусіль) - - **Nodes** для локального browser/screen/camera/exec + - **Постійна пам’ять + workspace** між сесіями + - **Доступ із багатьох платформ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (browser, files, scheduling, hooks) + - **Завжди ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) + - **Nodes** для локальних browser/screen/camera/exec - Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -985,69 +1004,69 @@ x-i18n: ## Skills і автоматизація - - Використовуйте керовані overrides замість редагування копії в репозиторії. Помістіть ваші зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тому керовані overrides все одно мають вищий пріоритет за bundled skills без дотику до git. Якщо skill має бути встановлений глобально, але видимий лише деяким агентам, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні upstream, мають жити в репозиторії й надсилатися як PR. + + Використовуйте керовані overrides замість редагування копії в репозиторії. Додавайте свої зміни у `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані overrides все одно мають пріоритет над bundled Skills без змін у git. Якщо вам потрібно, щоб Skill був встановлений глобально, але видимий лише для деяких агентів, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні upstream, мають жити в репозиторії й виходити як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw трактує як `/skills` у наступному сеансі. Якщо skill має бути видимий лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює у `./skills`, що OpenClaw обробляє як `/skills` у наступній сесії. Якщо Skill має бути видимим лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. Сьогодні підтримуються такі шаблони: - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. - - **Sub-agents**: маршрутизуйте завдання до окремих агентів із різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточного сеансу. + - **Sub-agents**: маршрутизуйте завдання до окремих агентів із різними типовими моделями. + - **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточної сесії. - Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація мультиагентів](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Багатоагентна маршрутизація](/uk/concepts/multi-agent), і [Slash commands](/uk/tools/slash-commands). - Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власному сеансі, + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, повертають підсумок і зберігають чутливість вашого основного чату. - Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб побачити, що зараз робить Gateway (і чи зайнятий він). + Попросіть бота «створити sub-agent для цього завдання» або використовуйте `/subagents`. + Використовуйте `/status` у чаті, щоб побачити, що Gateway робить просто зараз (і чи він зайнятий). - Порада щодо токенів: довгі завдання й sub-agents обидва споживають токени. Якщо вас - турбує вартість, задайте дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: довгі завдання й sub-agents обидва витрачають токени. Якщо важлива + вартість, задайте дешевшу модель для sub-agents через `agents.defaults.subagents.model`. Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив'язки thread. Ви можете прив'язати Discord thread до subagent або session target, щоб подальші повідомлення в цьому thread залишалися на прив'язаному сеансі. + + Використовуйте прив’язки тредів. Ви можете прив’язати Discord thread до subagent або цільової session, щоб наступні повідомлення в цьому треді залишалися на цій прив’язаній сесії. Базовий процес: - - Створіть через `sessions_spawn` із `thread: true` (і за бажанням `mode: "session"` для сталого follow-up). - - Або вручну прив'яжіть через `/focus `. - - Використовуйте `/agents`, щоб перевірити стан прив'язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати авто-скасуванням фокусу. - - Використовуйте `/unfocus`, щоб від'єднати thread. + - Створіть через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійної подальшої роботи). + - Або вручну прив’яжіть через `/focus `. + - Використовуйте `/agents`, щоб перевірити стан прив’язки. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. + - Використовуйте `/unfocus`, щоб від’єднати тред. Потрібна конфігурація: - - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Override-и Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоприв'язка під час spawn: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Перевизначення Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоматична прив’язка під час spawn: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). - - Спочатку перевірте розв'язаний маршрут requester: + + Спочатку перевірте визначений маршрут запитувача: - - Доставка completion-mode subagent віддає перевагу будь-якому прив'язаному thread або маршруту розмови, якщо такий існує. - - Якщо completion origin містить лише канал, OpenClaw повертається до збереженого маршруту сеансу requester (`lastChannel` / `lastTo` / `lastAccountId`), тож пряма доставка все одно може спрацювати. - - Якщо немає ані прив'язаного маршруту, ані придатного збереженого маршруту, пряма доставка може не вдатися, і результат повертається до queued session delivery замість негайної публікації в чат. - - Невалідні або застарілі цілі все одно можуть примусити fallback до черги або остаточну помилку доставки. - - Якщо остання видима відповідь assistant дочірнього агента — точний тихий токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу. - - Якщо дочірній агент перевищив тайм-аут після одних лише викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка completion-mode subagent віддає перевагу будь-якому прив’язаному треду або маршруту розмови, якщо такий існує. + - Якщо походження завершення несе лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), тож пряма доставка все ще може спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат повернеться до queued session delivery замість негайної публікації в чат. + - Недійсні або застарілі цілі все одно можуть змусити перейти до queue fallback або остаточної помилки доставки. + - Якщо остання видима відповідь assistant у дочірньому процесі — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу. + - Якщо дочірній процес завершився за тайм-аутом після одних лише викликів інструментів, announce може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1055,7 +1074,7 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент сеансів](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). @@ -1063,11 +1082,11 @@ x-i18n: Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно, заплановані завдання не запускатимуться. - Контрольний список: + Чекліст: - - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. + - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - Переконайтеся, що Gateway працює 24/7 (без сну/перезапусків). - - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу host). + - Перевірте налаштування часової зони для завдання (`--tz` проти часової зони хоста). Налагодження: @@ -1080,17 +1099,17 @@ x-i18n: - + Спочатку перевірте режим доставки: - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. - - Відсутня або невалідна announce-ціль (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але облікові дані це заблокували. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` лише) вважається навмисно недоставлюваним, тому runner також пригнічує queued fallback delivery. + - Відсутня або недійсна announce target (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але credentials заблокували це. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` лише) вважається навмисно недоставним, тому runner також пригнічує queued fallback delivery. - Для ізольованих cron-завдань runner відповідає за фінальну доставку. Від агента - очікується повернення текстового підсумку, який runner надішле. `--no-deliver` зберігає - цей результат внутрішнім; це не дозволяє агенту напряму надсилати через + Для ізольованих cron jobs фінальною доставкою керує runner. Очікується, + що агент поверне текстовий підсумок для відправлення runner-ом. `--no-deliver` зберігає + цей результат внутрішнім; це не дозволяє агентові надсилати безпосередньо через message tool. Налагодження: @@ -1104,23 +1123,23 @@ x-i18n: - - Зазвичай це шлях живого перемикання моделі, а не дублювання планування. + + Зазвичай це шлях live model-switch, а не дублювання розкладу. - Ізольований cron може зберігати runtime handoff моделі та повторювати спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повтор зберігає перемкнутого - provider/model, і якщо перемикання містило новий override auth profile, cron - також зберігає це перед повтором. + Ізольований cron може зберегти runtime handoff моделі та повторити спробу, коли активний + run кидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого + провайдера/модель, а якщо перемикання несло новий override профілю автентифікації, cron + також зберігає його перед повтором. - Пов'язані правила вибору: + Пов’язані правила вибору: - - Override моделі Gmail hook має найвищий пріоритет, коли застосовно. - - Потім — `model` для кожного завдання. - - Потім — будь-який збережений override моделі cron-сеансу. - - Потім — звичайний вибір моделі агента/за замовчуванням. + - Перевизначення моделі Gmail hook має найвищий пріоритет, коли застосовно. + - Потім `model` для кожного завдання. + - Потім будь-яке збережене перевизначення моделі cron-session. + - Потім звичайний вибір типової моделі агента. - Цикл повторів обмежений. Після початкової спроби плюс 2 повторів перемикання - cron перериває виконання замість нескінченного циклу. + Цикл повторів обмежений. Після початкової спроби плюс 2 повторів через перемикання + cron переривається, а не зациклюється назавжди. Налагодження: @@ -1133,9 +1152,9 @@ x-i18n: - - Використовуйте нативні команди `openclaw skills` або просто помістіть skills у ваш workspace. Інтерфейс Skills для macOS недоступний на Linux. - Переглядати skills можна на [https://clawhub.ai](https://clawhub.ai). + + Використовуйте нативні команди `openclaw skills` або просто додайте Skills у свій workspace. UI Skills для macOS недоступний на Linux. + Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1148,11 +1167,11 @@ x-i18n: openclaw skills check ``` - Нативний `openclaw skills install` записує у каталог `skills/` - активного workspace. Окремий CLI `clawhub` потрібен лише якщо ви хочете публікувати або - синхронізувати власні skills. Для спільного встановлення між агентами помістіть skill у + Нативний `openclaw skills install` записує у каталог `skills/` активного workspace. + Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або + синхронізувати власні Skills. Для спільного встановлення між агентами розмістіть Skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете обмежити, які агенти можуть його бачити. + `agents.list[].skills`, якщо хочете звузити видимість для агентів. @@ -1160,27 +1179,27 @@ x-i18n: Так. Використовуйте планувальник Gateway: - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). - - **Heartbeat** для періодичних перевірок "основного сеансу". - - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють у чати. + - **Heartbeat** для періодичних перевірок «основної сесії». + - **Ізольовані jobs** для автономних агентів, які публікують підсумки або доставляють у чати. Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Напряму — ні. Skills для macOS контролюються `metadata.openclaw.os` плюс потрібними бінарниками, а skills з'являються в system prompt лише коли вони придатні на **gateway host**. На Linux skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не override-нете перевірку. + + Не напряму. macOS Skills обмежуються через `metadata.openclaw.os` плюс потрібні бінарники, і Skills потрапляють у system prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (наприклад `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - У вас є три підтримувані шаблони: + Є три підтримувані шаблони: - **Варіант A — запустити Gateway на Mac (найпростіше).** - Запустіть Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-порти-вже-запущені-і-віддалений-режим) або через Tailscale. Skills завантажаться нормально, бо gateway host — це macOS. + **Варіант A - запускати Gateway на Mac (найпростіше).** + Запускайте Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються нормально, бо хост Gateway — це macOS. - **Варіант B — використати node macOS (без SSH).** - Запустіть Gateway на Linux, підключіть node macOS (menubar app) і встановіть **Node Run Commands** у "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарники існують на node. Агент запускає ці skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. + **Варіант B - використовувати macOS node (без SSH).** + Запускайте Gateway на Linux, під’єднайте macOS node (menubar app) і встановіть **Node Run Commands** у режим «Always Ask» або «Always Allow» на Mac. OpenClaw може вважати macOS-only Skills придатними, коли потрібні бінарники існують на node. Агент запускає ці Skills через інструмент `nodes`. Якщо ви обираєте «Always Ask», підтвердження «Always Allow» у запиті додає цю команду до allowlist. - **Варіант C — проксіювати бінарники macOS через SSH (розширений).** - Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники резолвилися в SSH-обгортки, які запускаються на Mac. Потім override-ніть skill, щоб дозволити Linux і зберегти його придатним. + **Варіант C - проксувати бінарники macOS через SSH (просунутий).** + Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники вказували на SSH-обгортки, які запускаються на Mac. Потім перевизначте Skill, щоб дозволити Linux і зберегти його придатність. 1. Створіть SSH-обгортку для бінарника (приклад: `memo` для Apple Notes): @@ -1190,8 +1209,8 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Помістіть обгортку в `PATH` на Linux host (наприклад `~/bin/memo`). - 3. Override-ніть метадані skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Додайте обгортку в `PATH` на хості Linux (наприклад `~/bin/memo`). + 3. Перевизначте metadata Skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- @@ -1201,211 +1220,211 @@ x-i18n: --- ``` - 4. Почніть новий сеанс, щоб знімок skills оновився. + 4. Почніть нову сесію, щоб знімок Skills оновився. - Вбудованої наразі немає. + Наразі вбудованої немає. Варіанти: - - **Користувацький skill / plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніша і крихкіша. + - **Власний Skill / plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. - Якщо ви хочете зберігати контекст окремо для кожного клієнта (агентські процеси), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (агентські workflows), простий шаблон такий: - Одна сторінка Notion на клієнта (контекст + уподобання + активна робота). - - Попросіть агента зчитувати цю сторінку на початку сеансу. + - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо вам потрібна нативна інтеграція, відкрийте feature request або створіть skill - для цих API. + Якщо ви хочете нативну інтеграцію, відкрийте feature request або створіть Skill + під ці API. - Установлення skills: + Встановлення Skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі skills очікують встановлення бінарників через Homebrew; на Linux це означає Linuxbrew (див. вище пункт FAQ про Homebrew на Linux). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарники, встановлені через Homebrew; на Linux це означає Linuxbrew (див. вище пункт FAQ про Homebrew на Linux). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config), і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований браузерний профіль `user`, який підключається через Chrome DevTools MCP: + + Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо вам потрібна власна назва, створіть явний MCP-профіль: + Якщо хочете власну назву, створіть явний MCP profile: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях є локальним для host. Якщо Gateway працює деінде, або запустіть node host на машині з браузером, або використовуйте remote CDP. + Цей шлях є локальним для хоста. Якщо Gateway працює десь інде, або запускайте node host на машині браузера, або використовуйте remote CDP. Поточні обмеження `existing-session` / `user`: - - дії прив'язані до ref, а не до CSS-selector - - завантаження файлів вимагає `ref` / `inputRef` і наразі підтримує по одному файлу за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP + - дії прив’язані до ref, а не до CSS-селекторів + - uploads вимагають `ref` / `inputRef` і наразі підтримують один файл за раз + - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують managed browser або raw CDP profile -## Пісочниця та пам'ять +## Ізоляція та пам’ять - - Так. Див. [Пісочниця](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або sandbox images), див. [Docker](/uk/install/docker). + + Так. Див. [Sandboxing](/uk/gateway/sandboxing). Для налаштування, пов’язаного з Docker (повний gateway у Docker або sandbox images), див. [Docker](/uk/install/docker). - - Типовий образ орієнтований на безпеку і працює від користувача `node`, тому не + + Типовий image орієнтований на безпеку й працює від користувача `node`, тому не містить системних пакетів, Homebrew або bundled browsers. Для повнішого налаштування: - - Зробіть `/home/node` постійним за допомогою `OPENCLAW_HOME_VOLUME`, щоб кеші зберігалися. - - Додайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - - Установіть Playwright browsers через bundled CLI: + - Збережіть `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші переживали перезапуски. + - Вбудуйте системні залежності в image через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Встановіть браузери Playwright через bundled CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях є постійним. + - Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. - Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). + Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). - - Так — якщо ваш приватний трафік — це **DM**, а публічний трафік — це **групи**. + + Так — якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. - Використайте `agents.defaults.sandbox.mode: "non-main"`, щоб сеанси груп/каналів (ключі не-main) запускалися в Docker, а головний DM-сеанс залишався на host. Потім обмежте набір інструментів, доступних у sandbox-сеансах, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/каналів (неосновні ключі) працювали в Docker, тоді як основна DM-сесія залишалася на хості. Потім обмежте доступні інструменти в ізольованих сесіях через `tools.sandbox.tools`. - Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) + Покрокова інструкція + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник із ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідник ключової конфігурації: [Конфігурація gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад `"/home/user/src:/src:ro"`). Глобальні й поагентні прив'язки зливаються; поагентні прив'язки ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам'ятайте, що прив'язки обходять файлові стіни sandbox. + + Задайте `agents.defaults.sandbox.docker.binds` як `["host:path:mode"]` (наприклад `"/home/user/src:/src:ro"`). Глобальні й per-agent binds об’єднуються; per-agent binds ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що binds обходять бар’єри файлової системи sandbox. - OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв'язаним через найглибший наявний батьківський каталог. Це означає, що обходи через symlink-батьків усе одно блокуються навіть тоді, коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв'язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, визначеним через найглибшого наявного предка. Це означає, що вихід через symlink-батьків усе одно fail-closed навіть тоді, коли останній сегмент шляху ще не існує, і перевірки дозволених коренів усе одно застосовуються після визначення symlink. - Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і зауваг щодо безпеки. + Див. [Sandboxing](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток з безпеки. - - Пам'ять OpenClaw — це просто Markdown-файли у workspace агента: + + Пам’ять OpenClaw — це просто файли Markdown у workspace агента: - - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Кураторські довгострокові нотатки в `MEMORY.md` (лише основні/приватні сеанси) + - Щоденні нотатки у `memory/YYYY-MM-DD.md` + - Керовані довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії) - OpenClaw також виконує **тихе скидання пам'яті перед compaction**, щоб нагадати моделі - записати стійкі нотатки перед auto-compaction. Це запускається лише коли workspace - доступний для запису (read-only sandbox пропускає це). Див. [Пам'ять](/uk/concepts/memory). + OpenClaw також виконує **тихий pre-compaction memory flush**, щоб нагадати моделі + записати стійкі нотатки перед auto-compaction. Це працює лише тоді, коли workspace + придатний для запису (у sandbox лише для читання це пропускається). Див. [Пам’ять](/uk/concepts/memory). - - Попросіть бота **записати факт у пам'ять**. Довгострокові нотатки мають бути в `MEMORY.md`, + + Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають бути в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще область, яку ми вдосконалюємо. Корисно нагадувати моделі зберігати спогади; - вона зрозуміє, що робити. Якщо вона все одно забуває, перевірте, що Gateway використовує той самий - workspace під час кожного запуску. + Це ще сфера, яку ми покращуємо. Корисно нагадувати моделі зберігати спогади; + вона знатиме, що робити. Якщо вона все одно забуває, перевірте, що Gateway використовує той самий + workspace при кожному запуску. - Документація: [Пам'ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). + Документація: [Пам’ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). - - Файли пам'яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеження — це - сховище, а не модель. **Контекст сеансу** все одно обмежений вікном - контексту моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому - існує semantic memory search — він повертає в контекст лише релевантні частини. + + Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеження — це + ваше сховище, а не модель. **Контекст сесії** все одно обмежений контекстним вікном моделі, + тому довгі розмови можуть стискатися або обрізатися. Саме тому існує + пошук по пам’яті — він повертає назад у контекст лише релевантні частини. - Документація: [Пам'ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). + Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - Лише якщо ви використовуєте **embeddings OpenAI**. Codex OAuth покриває chat/completions і - **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід у Codex CLI)** не допоможе для semantic memory search. Для embeddings OpenAI + Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває chat/completions і + **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або + логін Codex CLI)** не допомагає для semantic memory search. Для OpenAI embeddings усе одно потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли - може знайти API key (auth profiles, `models.providers.*.apiKey` або env vars). - Він віддає перевагу OpenAI, якщо знаходить ключ OpenAI, інакше Gemini, якщо знаходить ключ Gemini, + може визначити API key (auth profiles, `models.providers.*.apiKey` або env vars). + Він віддає перевагу OpenAI, якщо визначається ключ OpenAI, інакше Gemini, якщо визначається ключ Gemini, потім Voyage, потім Mistral. Якщо жодного віддаленого ключа немає, memory search залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний локальний шлях до моделі, OpenClaw - надає перевагу `local`. Ollama підтримується, коли ви явно встановлюєте + віддає перевагу `local`. Ollama підтримується, коли ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви хочете залишатися локальними, установіть `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо ви хочете embeddings Gemini, установіть - `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** - — деталі налаштування див. у [Пам'ять](/uk/concepts/memory). + Якщо ви хочете залишитися локально, задайте `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо ви хочете embeddings Gemini, задайте + `memorySearch.provider = "gemini"` і вкажіть `GEMINI_API_KEY` (або + `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — + див. [Пам’ять](/uk/concepts/memory) для деталей налаштування. -## Де що лежить на диску +## Де що зберігається на диску - Ні — **стан OpenClaw локальний**, але **зовнішні служби все одно бачать те, що ви їм надсилаєте**. + Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** сеанси, файли пам'яті, конфігурація та workspace живуть на gateway host - (`~/.openclaw` + каталог вашого workspace). + - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та workspace живуть на хості Gateway + (`~/.openclaw` + ваш каталог workspace). - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), ідуть до - їхніх API, а платформи чатів (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на - своїх серверах. - - **Ви контролюєте слід:** використання локальних моделей зберігає prompts на вашій машині, але трафік - каналів усе одно проходить через сервери цих каналів. + їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх + серверах. + - **Ви контролюєте обсяг:** використання локальних моделей тримає prompts на вашій машині, але трафік каналу + усе одно проходить через сервери цього каналу. - Пов'язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам'ять](/uk/concepts/memory). + Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). - Усе живе в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): + Усе живе під `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): - | Path | Призначення | - | --------------------------------------------------------------- | ------------------------------------------------------------------- | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy-імпорт OAuth (копіюється в auth profiles під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys і необов'язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов'язкове файлове secret payload для провайдерів `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy-файл сумісності (статичні записи `api_key` очищуються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Поагентний стан (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (по агенту) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сеансів (по агенту) | + | Path | Призначення | + | --------------------------------------------------------------- | ------------------------------------------------------------------ | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в auth profiles при першому використанні) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язковий file-backed secret payload для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Застарілий файл сумісності (статичні записи `api_key` очищено) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | - Legacy-шлях single-agent: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`). + Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **workspace** (AGENTS.md, файли пам'яті, skills тощо) є окремим і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли пам’яті, Skills тощо) розташований окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). Ці файли живуть у **workspace агента**, а не в `~/.openclaw`. - - **Workspace (на агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (або legacy fallback `memory.md`, коли `MEMORY.md` відсутній), - `memory/YYYY-MM-DD.md`, необов'язковий `HEARTBEAT.md`. - - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, auth profiles, sessions, logs, - і спільні skills (`~/.openclaw/skills`). + - **Workspace (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (або застарілий запасний варіант `memory.md`, якщо `MEMORY.md` відсутній), + `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. + - **State dir (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, auth profiles, sessions, logs, + і спільні Skills (`~/.openclaw/skills`). - Workspace за замовчуванням — `~/.openclaw/workspace`, налаштовується через: + Типовий workspace — `~/.openclaw/workspace`, налаштовується через: ```json5 { @@ -1413,41 +1432,41 @@ x-i18n: } ``` - Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway щоразу використовує той самий - workspace (і пам'ятайте: remote mode використовує **workspace gateway host**, + Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує той самий + workspace при кожному запуску (і пам’ятайте: у віддаленому режимі використовується **workspace хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете зберегти сталу поведінку або вподобання, попросіть бота **записати це в + Порада: якщо ви хочете стійку поведінку або вподобання, попросіть бота **записати це в AGENTS.md або MEMORY.md**, а не покладатися на історію чату. - Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам'ять](/uk/concepts/memory). + Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). - Зберігайте **workspace агента** у **приватному** git-репозиторії та робіть його резервні копії - у приватному місці (наприклад, приватний GitHub). Це захоплює пам'ять + файли AGENTS/SOUL/USER - і дає змогу пізніше відновити "розум" помічника. + Помістіть ваш **workspace агента** у **приватний** git-репозиторій і робіть його резервні копії + у приватному місці (наприклад приватний GitHub). Це збереже пам’ять + файли AGENTS/SOUL/USER + та дозволить вам пізніше відновити «розум» асистента. - **Не** комітьте нічого з `~/.openclaw` (облікові дані, сеанси, токени або зашифровані secret payloads). - Якщо вам потрібне повне відновлення, окремо робіть резервні копії і workspace, і каталогу стану - (див. питання про міграцію вище). + **Не** робіть commit нічого з `~/.openclaw` (credentials, sessions, tokens або encrypted secrets payloads). + Якщо вам потрібне повне відновлення, робіть резервні копії і workspace, і state directory + окремо (див. питання про міграцію вище). Документація: [Workspace агента](/uk/concepts/agent-workspace). - Див. окремий посібник: [Видалення](/uk/install/uninstall). + Див. окремий гайд: [Видалення](/uk/install/uninstall). - Так. Workspace — це **типовий cwd** і якір пам'яті, а не жорстка sandbox. - Відносні шляхи резолвляться всередині workspace, але абсолютні шляхи можуть звертатися до інших - розташувань host, якщо пісочниця не ввімкнена. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або поагентні налаштування sandbox. Якщо ви - хочете, щоб репозиторій був типовим робочим каталогом, направте `workspace` - цього агента в корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + Так. Workspace — це **типовий cwd** і якір пам’яті, а не жорсткий sandbox. + Відносні шляхи визначаються всередині workspace, але абсолютні шляхи можуть звертатися до інших + розташувань хоста, якщо sandboxing не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для окремих агентів. Якщо ви + хочете, щоб репозиторій був типовим робочим каталогом, вкажіть `workspace` + цього агента на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. Приклад (репозиторій як типовий cwd): @@ -1464,30 +1483,30 @@ x-i18n: - - Стан сеансів належить **gateway host**. Якщо ви в remote mode, потрібний вам store сеансів знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сеансами](/uk/concepts/session). + + Станом сесій володіє **хост gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). ## Основи конфігурації - - OpenClaw читає необов'язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема типовий workspace `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються досить безпечні типові значення (включно з типовим workspace `~/.openclaw/workspace`). - - Bind-и не на loopback **вимагають валідного шляху автентифікації gateway**. На практиці це означає: + + Bind без loopback **вимагає дійсного шляху автентифікації gateway**. На практиці це означає: - - автентифікація shared secret: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не на loopback + - shared-secret auth: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy без loopback ```json5 { @@ -1504,31 +1523,31 @@ x-i18n: Примітки: - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. - - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише коли `gateway.auth.*` не задано. - - Для автентифікації паролем установіть `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв'язати, розв'язання закривається з помилкою (без маскувального remote fallback). - - Налаштування Control UI із shared secret автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення shared secrets в URL. - - Із `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback на тому ж host усе одно **не** задовольняє trusted-proxy auth. Trusted proxy має бути налаштованим джерелом не на loopback. + - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. + - Для автентифікації паролем задайте `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не визначено, визначення fail-closed (без маскувального remote fallback). + - Налаштування shared-secret у Control UI автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентичністю, такі як Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запитів. Уникайте розміщення shared secrets в URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback на тому самому хості все одно **не** задовольняють trusted-proxy auth. Trusted proxy має бути налаштованим джерелом без loopback. - - OpenClaw за замовчуванням примусово вимагає автентифікацію gateway, зокрема на loopback. У звичайному типовому шляху це означає token auth: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим token і автоматично генерує токен, зберігаючи його в `gateway.auth.token`, тож **локальні WS-клієнти мають автентифікуватися**. Це блокує іншим локальним процесам можливість викликати Gateway. + + OpenClaw за замовчуванням вимагає автентифікацію gateway, включно з loopback. У нормальному типовому сценарії це означає token auth: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим token і автоматично генерує його, зберігаючи в `gateway.auth.token`, тому **локальні WS-клієнти мають автентифікуватися**. Це блокує інші локальні процеси від виклику Gateway. - Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для identity-aware reverse proxy не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен у будь-який момент: `openclaw doctor --generate-gateway-token`. + Якщо вам більше підходить інший шлях автентифікації, ви можете явно вибрати режим пароля (або, для identity-aware reverse proxy без loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен у будь-який момент: `openclaw doctor --generate-gateway-token`. - Gateway стежить за конфігурацією й підтримує hot-reload: + Gateway відстежує конфігурацію і підтримує hot-reload: - - `gateway.reload.mode: "hybrid"` (типово): hot-apply безпечних змін, перезапуск для критичних + - `gateway.reload.mode: "hybrid"` (типово): hot-apply для безпечних змін, restart для критичних - також підтримуються `hot`, `restart`, `off` - - Установіть `cli.banner.taglineMode` у конфігурації: + + Задайте `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1540,23 +1559,23 @@ x-i18n: } ``` - - `off`: приховує текст слогану, але залишає рядок із назвою/версією банера. + - `off`: приховує текст tagline, але залишає рядок назви/версії banner. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: циклічні кумедні/сезонні слогани (типова поведінка). - - Якщо ви взагалі не хочете банер, установіть env `OPENCLAW_HIDE_BANNER=1`. + - `random`: ротаційні кумедні/сезонні tagline (типова поведінка). + - Якщо ви взагалі не хочете banner, задайте env `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` працює без API key. `web_search` залежить від обраного + + `web_fetch` працює без API key. `web_search` залежить від вибраного провайдера: - - Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, вимагають своїх звичайних налаштувань API key. - - Ollama Web Search не потребує ключа, але використовує налаштований вами Ollama host і вимагає `ollama signin`. + - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, вимагають звичайного налаштування API key. + - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama і вимагає `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна HTML-інтеграція. - - SearXNG не потребує ключа/самостійно розміщується; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа/self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. + **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть провайдера. Альтернативи через середовище: - Brave: `BRAVE_API_KEY` @@ -1592,65 +1611,65 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // необов'язково; опустіть для auto-detect + provider: "firecrawl", // optional; omit for auto-detect }, }, }, } ``` - Конфігурація вебпошуку, специфічна для провайдера, тепер живе в `plugins.entries..config.webSearch.*`. - Legacy-шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але не повинні використовуватися в нових конфігураціях. - Конфігурація fallback web-fetch Firecrawl живе в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація web-search для провайдера тепер знаходиться під `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. + Конфігурація запасного web-fetch Firecrawl знаходиться під `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - - Якщо ви використовуєте allowlist-и, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. + - Якщо ви використовуєте allowlists, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). - - Якщо `tools.web.fetch.provider` опущено, OpenClaw автоматично виявляє першого готового fallback-провайдера fetch із доступних облікових даних. Наразі bundled-провайдер — Firecrawl. - - Демони читають env vars із `~/.openclaw/.env` (або середовища служби). + - Якщо `tools.web.fetch.provider` опущено, OpenClaw автоматично визначає першого готового запасного провайдера fetch з доступних credentials. Наразі bundled-провайдер — Firecrawl. + - Демони читають env vars з `~/.openclaw/.env` (або з середовища сервісу). - Документація: [Вебінструменти](/uk/tools/web). + Документація: [Web tools](/uk/tools/web). - - `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об'єкт, усе - інше буде видалено. + + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, все + інше видаляється. Відновлення: - Відновіть із резервної копії (git або скопійований `~/.openclaw/openclaw.json`). - - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і переналаштуйте канали/моделі. - - Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію. - - Локальний coding agent часто може відновити робочу конфігурацію з журналів або історії. + - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і знову налаштуйте канали/моделі. + - Якщо це сталося неочікувано, створіть bug report і додайте вашу останню відому конфігурацію або будь-яку резервну копію. + - Локальний coding-агент часто може відновити робочу конфігурацію з логів або історії. Як уникнути: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені в точному шляху або формі поля; він повертає вузол shallow schema плюс підсумки безпосередніх дочірніх елементів для поступового уточнення. + - Спочатку використовуйте `config.schema.lookup`, якщо ви не впевнені в точному шляху або формі поля; він повертає поверхневий вузол схеми плюс короткі зведення безпосередніх дочірніх елементів для поетапного заглиблення. - Використовуйте `config.patch` для часткових RPC-редагувань; залиште `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте інструмент `gateway`, доступний лише власнику, із запуску агента, він усе одно відхиляє записи в `tools.exec.ask` / `tools.exec.security` (включно з legacy-аліасами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Якщо ви використовуєте owner-only інструмент `gateway` у запуску агента, він усе одно відхилить записи в `tools.exec.ask` / `tools.exec.security` (включно зі застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Конфігурація](/cli/config), [Налаштування](/cli/configure), [Doctor](/uk/gateway/doctor). + Документація: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/uk/gateway/doctor). - - Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: + + Поширений шаблон — **один Gateway** (наприклад Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сеансами. + - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією і сесіями. - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Agents (працівники):** окремі "мізки"/workspace для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). - - **Sub-agents:** запускають фонову роботу з основного агента, коли потрібен паралелізм. - - **TUI:** підключається до Gateway і перемикає агентів/сеанси. + - **Agents (workers):** окремі «мізки»/workspace для спеціальних ролей (наприклад «Hetzner ops», «Personal data»). + - **Sub-agents:** породжують фонову роботу з основного агента, коли потрібен паралелізм. + - **TUI:** підключається до Gateway і перемикає агентів/сесії. - Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). + Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Багатоагентна маршрутизація](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). - + Так. Це опція конфігурації: ```json5 @@ -1664,28 +1683,28 @@ x-i18n: } ``` - Типове значення — `false` (із вікном). Headless частіше провокує антибот-перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). + За замовчуванням `false` (headful). Headless частіше викликає антибот-перевірки на деяких сайтах. Див. [Browser](/uk/tools/browser). - Headless використовує **той самий Chromium engine** і працює для більшості автоматизацій (форми, кліки, скрапінг, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості автоматизації (форми, кліки, скрапінг, логіни). Основні відмінності: - - Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуальна інформація). - - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, антибот). - Наприклад, X/Twitter часто блокує headless-сеанси. + - Немає видимого вікна браузера (використовуйте скріншоти, якщо потрібна візуалізація). + - Деякі сайти суворіше ставляться до автоматизації в режимі headless (CAPTCHAs, anti-bot). + Наприклад, X/Twitter часто блокує headless sessions. - Установіть `browser.executablePath` на ваш бінарник Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway. - Повні приклади конфігурації див. у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + Задайте `browser.executablePath` для вашого бінарника Brave (або будь-якого браузера на базі Chromium) і перезапустіть Gateway. + Див. повні приклади конфігурації в [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені gateway та nodes +## Віддалені gateways і nodes - - Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і - лише потім викликає nodes через **Gateway WebSocket**, коли потрібен node tool: + + Повідомлення Telegram обробляє **gateway**. Gateway запускає агента і + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram @@ -1693,18 +1712,18 @@ x-i18n: - - Коротка відповідь: **підключіть ваш комп'ютер як node**. Gateway працює деінде, але може + + Коротка відповідь: **під’єднайте ваш комп’ютер як node**. Gateway працює деінде, але він може викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на завжди ввімкненому host (VPS/домашній сервер). - 2. Додайте gateway host і ваш комп'ютер до одного tailnet. + 1. Запустіть Gateway на постійно ввімкненому хості (VPS/домашній сервер). + 2. Помістіть хост Gateway і ваш комп’ютер в один tailnet. 3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH tunnel). 4. Локально відкрийте застосунок macOS і підключіться в режимі **Remote over SSH** (або напряму через tailnet), щоб він міг зареєструватися як node. - 5. Схваліть node на Gateway: + 5. Підтвердьте node на Gateway: ```bash openclaw devices list @@ -1713,10 +1732,10 @@ x-i18n: Окремий TCP bridge не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування про безпеку: підключення node macOS дозволяє `system.run` на цій машині. Підключайте - лише ті пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). + Нагадування щодо безпеки: під’єднання macOS node дозволяє `system.run` на цій машині. Підключайте + лише пристрої, яким довіряєте, і перегляньте [Безпеку](/uk/gateway/security). - Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). + Документація: [Nodes](/uk/nodes), [Gateway protocol](/uk/gateway/protocol), [віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). @@ -1725,93 +1744,93 @@ x-i18n: - Gateway працює: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан каналів: `openclaw channels status` + - Стан каналу: `openclaw channels status` Потім перевірте автентифікацію та маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` встановлено правильно. - - Якщо ви підключаєтеся через SSH tunnel, підтвердьте, що локальний tunnel працює й указує на правильний порт. - - Переконайтеся, що ваші allowlist-и (DM або група) включають ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` задано правильно. + - Якщо ви підключаєтеся через SSH tunnel, переконайтеся, що локальний тунель активний і вказує на правильний порт. + - Переконайтеся, що ваші allowlists (DM або group) містять ваш обліковий запис. Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - - Так. Вбудованого мосту "бот-до-бота" немає, але це можна реалізувати кількома + + Так. Вбудованого моста «бот-до-бота» немає, але це можна зібрати кількома надійними способами: **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай бот A надішле повідомлення боту B, а потім бот B відповість як звично. + Нехай Бот A надсилає повідомлення Боту B, а тоді Бот B відповідає як завжди. - **CLI-міст (універсально):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючи на чат, де інший бот - слухає. Якщо один із ботів працює на віддаленому VPS, направте ваш CLI на цей віддалений Gateway + **CLI bridge (загальний):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націлюючись на чат, який слухає інший бот. + Якщо один бот працює на віддаленому VPS, направте ваш CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускається з машини, яка може досягти цільового Gateway): + Приклад шаблону (запускати з машини, яка може досягнути цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте обмежувач, щоб два боти не зациклилися нескінченно (відповідати лише на згадки, channel - allowlist-и або правило "не відповідати на повідомлення ботів"). + Порада: додайте обмеження, щоб два боти не зациклювалися безкінечно (режим лише за згадкою, channel + allowlists або правило «не відповідати на повідомлення ботів»). Документація: [Віддалений доступ](/uk/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/uk/tools/agent-send). - Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм workspace, моделями за замовчуванням, - і маршрутизацією. Це типовий сценарій, і він набагато дешевший і простіший, ніж запускати - окремий VPS на кожного агента. + Ні. Один Gateway може хостити кількох агентів, кожен зі своїм workspace, типовими моделями + та маршрутизацією. Це нормальна схема, і вона значно дешевша й простіша, ніж запуск + одного VPS на агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, якими ви не хочете ділитися. В інших випадках достатньо одного Gateway і - кількох агентів або sub-agents. + різні конфігурації, які ви не хочете ділити. В іншому разі тримайте один Gateway і + використовуйте кілька агентів або sub-agents. - Так — nodes є першокласним способом доступу до ноутбука з віддаленого Gateway, і вони - дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легковаговим (невеликий VPS або коробка рівня Raspberry Pi цілком підходять; 4 GB RAM більш ніж достатньо), тож поширений - сценарій — host, що завжди увімкнений, плюс ваш ноутбук як node. + Так — nodes є основним способом дістатися до ноутбука з віддаленого Gateway, і вони + відкривають більше, ніж просто shell-доступ. Gateway працює на macOS/Linux (Windows через WSL2) і є + легким (малий VPS або коробка класу Raspberry Pi цілком підходять; 4 GB RAM більш ніж достатньо), тому поширене + налаштування — це постійно ввімкнений хост плюс ваш ноутбук як node. - - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристроїв. - - **Безпечніший контроль виконання.** `system.run` контролюється allowlist-ами/схваленнями node на цьому ноутбуці. + - **Немає потреби у вхідному SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairинг пристроїв. + - **Безпечніший контроль виконання.** `system.run` контролюється allowlists/approvals node на цьому ноутбуці. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або підключайтеся до локального Chrome на host через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних робочих процесів агентів і + SSH підходить для епізодичного shell-доступу, але nodes простіші для постійних агентських workflows і автоматизації пристроїв. - Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Браузер](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Browser](/uk/tools/browser). - - Ні. На одному host зазвичай має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферія, яка підключається - до gateway (nodes iOS/Android або режим "node mode" у menubar app на macOS). Для headless node - host-ів і керування через CLI див. [Node host CLI](/cli/node). + + Ні. Лише **один gateway** має працювати на хості, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateways](/uk/gateway/multiple-gateways)). Nodes — це периферія, яка підключається + до gateway (nodes на iOS/Android або режим «node mode» у menubar app на macOS). Для headless node + hosts і керування через CLI див. [Node host CLI](/cli/node). - Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. + Повний restart потрібен для змін `gateway`, `discovery` і `canvasHost`. Так. - - `config.schema.lookup`: перевірити одне піддерево конфігурації разом із shallow schema node, відповідною UI-підказкою та підсумками безпосередніх дочірніх елементів перед записом + - `config.schema.lookup`: перевірити одне піддерево конфігурації з його поверхневим вузлом схеми, підібраною підказкою UI та короткими зведеннями безпосередніх дочірніх елементів перед записом - `config.get`: отримати поточний знімок + hash - - `config.patch`: безпечне часткове оновлення (переважний варіант для більшості RPC-редагувань) - - `config.apply`: перевірити + повністю замінити конфігурацію, а потім перезапустити - - Runtime tool `gateway`, доступний лише власнику, як і раніше відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; legacy-аліаси `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.patch`: безпечне часткове оновлення (переважно для більшості RPC-редагувань) + - `config.apply`: перевірити + замінити повну конфігурацію, потім перезапустити + - Owner-only runtime tool `gateway` усе ще відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1819,25 +1838,25 @@ x-i18n: } ``` - Це задає ваш workspace і обмежує, хто може запускати бота. + Це задає ваш workspace і обмежує, хто може активувати бота. - + Мінімальні кроки: - 1. **Установіть і увійдіть на VPS** + 1. **Встановіть + увійдіть на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Установіть і увійдіть на Mac** - - Використовуйте застосунок Tailscale і ввійдіть у той самий tailnet. + 2. **Встановіть + увійдіть на Mac** + - Використайте застосунок Tailscale і увійдіть у той самий tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - - В admin console Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім'я. - 4. **Використовуйте hostname tailnet** + - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільну назву. + 4. **Використовуйте ім’я хоста tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1847,53 +1866,53 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив'язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - - Serve відкриває **Control UI + WS Gateway**. Nodes підключаються через той самий endpoint Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через ту ж WS endpoint Gateway. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac в одному tailnet**. - 2. **Використовуйте застосунок macOS у Remote mode** (ціллю SSH може бути hostname tailnet). + 1. **Переконайтеся, що VPS + Mac в одному tailnet**. + 2. **Використовуйте застосунок macOS у Remote mode** (ціллю SSH може бути ім’я хоста tailnet). Застосунок пробросить порт Gateway і підключиться як node. - 3. **Схваліть node** на gateway: + 3. **Підтвердьте node** на gateway: ```bash openclaw devices list openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Виявлення](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Gateway protocol](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [віддалений режим macOS](/uk/platforms/mac/remote). - + Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **node**. Це дозволяє зберегти один Gateway і уникнути дублювання конфігурації. Локальні node tools - наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. + **node**. Так ви збережете один Gateway і уникнете дублювання конфігурації. Локальні node tools + наразі доступні лише на macOS, але ми плануємо поширити їх на інші ОС. - Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. - Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Кілька gateways](/uk/gateway/multiple-gateways). -## Змінні середовища та завантаження .env +## Env vars і завантаження .env - + OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - - `.env` із поточного робочого каталогу - - глобальний fallback `.env` із `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - `.env` з поточного робочого каталогу + - глобальний fallback `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із файлів `.env` не перевизначає наявні env vars. + Жоден із `.env` файлів не перевизначає вже наявні env vars. - Ви також можете задати inline env vars у конфігурації (застосовуються лише якщо відсутні в env процесу): + Ви також можете задавати inline env vars у конфігурації (застосовуються лише якщо їх бракує у process env): ```json5 { @@ -1904,15 +1923,15 @@ x-i18n: } ``` - Повний порядок пріоритету та джерела див. у [/environment](/uk/help/environment). + Див. [/environment](/uk/help/environment) для повного пріоритету та джерел. - + Два поширені виправлення: - 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися навіть тоді, коли служба не успадковує env вашої оболонки. - 2. Увімкніть імпорт оболонки (зручна опція за вибором): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої оболонки. + 2. Увімкніть імпорт оболонки (опційна зручність): ```json5 { @@ -1925,18 +1944,18 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: + Це запускає вашу login shell і імпортує лише очікувані відсутні ключі (ніколи не перевизначає). Еквіваленти env var: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` повідомляє, чи ввімкнено **імпорт env з оболонки**. "Shell env: off" - **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не завантажуватиме - вашу login shell автоматично. + + `openclaw models status` повідомляє, чи увімкнено **імпорт shell env**. «Shell env: off» + **не** означає, що ваших env vars бракує — це лише означає, що OpenClaw не буде + автоматично завантажувати вашу login shell. - Якщо Gateway працює як служба (launchd/systemd), він не успадковує середовище - вашої оболонки. Виправлення — зробити одне з цього: + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище вашої оболонки. + Виправлення — зробити одне з цього: 1. Помістити токен у `~/.openclaw/.env`: @@ -1944,8 +1963,8 @@ x-i18n: COPILOT_GITHUB_TOKEN=... ``` - 2. Або ввімкнути імпорт оболонки (`env.shellEnv.enabled: true`). - 3. Або додати його в блок `env` конфігурації (застосовується лише якщо відсутній). + 2. Або ввімкнути імпорт shell (`env.shellEnv.enabled: true`). + 3. Або додати його в блок `env` конфігурації (застосовується лише якщо ключа бракує). Потім перезапустіть gateway і перевірте ще раз: @@ -1959,18 +1978,18 @@ x-i18n: -## Сеанси та кілька чатів +## Сесії та кілька чатів - Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сеансами](/uk/concepts/session). + Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сесіями](/uk/concepts/session). - - Сеанси можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). - Установіть додатне значення, щоб увімкнути завершення за бездіяльністю. Коли воно ввімкнене, **наступне** - повідомлення після періоду бездіяльності починає новий session id для цього chat key. - Це не видаляє транскрипти — просто починається новий сеанс. + + Сесії можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типово **0**). + Задайте додатне значення, щоб увімкнути завершення через бездіяльність. Коли це ввімкнено, **наступне** + повідомлення після періоду бездіяльності запускає новий session id для цього chat key. + Це не видаляє транскрипти — просто починає нову сесію. ```json5 { @@ -1982,35 +2001,35 @@ x-i18n: - - Так, через **маршрутизацію мультиагентів** і **sub-agents**. Ви можете створити одного координуючого - агента і кількох робочих агентів із власними workspace та моделями. + + Так, через **багатоагентну маршрутизацію** і **sub-agents**. Ви можете створити одного координатора + та кількох агентів-працівників із власними workspace і моделями. - Водночас це краще сприймати як **цікавий експеримент**. Це дорого з погляду токенів і часто - менш ефективно, ніж використовувати одного бота з окремими сеансами. Типова модель, яку ми - уявляємо, — це один бот, з яким ви спілкуєтеся, з різними сеансами для паралельної роботи. Цей - бот також може за потреби запускати sub-agents. + Втім, краще ставитися до цього як до **цікавого експерименту**. Це важко для токенів і часто + менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку + ми уявляємо, — це один бот, з яким ви говорите, але з різними сесіями для паралельної роботи. Цей + бот також може за потреби породжувати sub-agents. - Документація: [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). + Документація: [Багатоагентна маршрутизація](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). - Контекст сеансу обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато - файлів можуть викликати compaction або truncation. + Контекст сесії обмежений вікном моделі. Довгі чати, великий вивід інструментів або багато + файлів можуть спричинити стискання або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - Використовуйте `/compact` перед довгими завданнями та `/new` під час зміни тем. - - Тримайте важливий контекст у workspace і просіть бота перечитувати його. - - Використовуйте sub-agents для довгих або паралельних завдань, щоб основний чат залишався меншим. - - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. + - Зберігайте важливий контекст у workspace і попросіть бота знову його прочитати. + - Використовуйте sub-agents для довгої чи паралельної роботи, щоб основний чат залишався меншим. + - Оберіть модель із більшим контекстним вікном, якщо це часто трапляється. - - Використовуйте команду reset: + + Використовуйте команду скидання: ```bash openclaw reset @@ -2022,7 +2041,7 @@ x-i18n: openclaw reset --scope full --yes --non-interactive ``` - Потім повторно виконайте налаштування: + Потім знову запустіть налаштування: ```bash openclaw onboard --install-daemon @@ -2031,15 +2050,15 @@ x-i18n: Примітки: - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скидайте кожен каталог стану окремо (типово це `~/.openclaw-`). - - Dev reset: `openclaw gateway --dev --reset` (лише для dev; стирає dev config + credentials + sessions + workspace). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен state dir (типово це `~/.openclaw-`). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; стирає dev config + credentials + sessions + workspace). Використовуйте один із цих варіантів: - - **Compact** (зберігає розмову, але підсумовує старіші ходи): + - **Стиснення** (зберігає розмову, але підсумовує старі ходи): ``` /compact @@ -2047,40 +2066,40 @@ x-i18n: або `/compact `, щоб спрямувати підсумок. - - **Reset** (новий session ID для того самого chat key): + - **Скидання** (новий session ID для того самого chat key): ``` /new /reset ``` - Якщо це повторюється: + Якщо це продовжує траплятися: - - Увімкніть або налаштуйте **обрізання сеансів** (`agents.defaults.contextPruning`), щоб прибирати старий вивід інструментів. - - Використовуйте модель із більшим вікном контексту. + - Увімкніть або налаштуйте **session pruning** (`agents.defaults.contextPruning`), щоб обрізати старий вивід інструментів. + - Використовуйте модель із більшим контекстним вікном. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання сеансів](/uk/concepts/session-pruning), [Керування сеансами](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Session pruning](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). - Це помилка валідації провайдера: модель видала блок `tool_use` без обов'язкового - `input`. Зазвичай це означає, що історія сеансу застаріла або пошкоджена (часто після довгих thread - або зміни tool/schema). + Це помилка валідації провайдера: модель згенерувала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих тредів + або зміни інструмента/схеми). - Виправлення: почніть новий сеанс за допомогою `/new` (окреме повідомлення). + Виправлення: почніть нову сесію через `/new` (окреме повідомлення). - Heartbeats за замовчуванням запускаються кожні **30m** (**1h** при використанні OAuth auth). Налаштуйте або вимкніть їх: + За замовчуванням heartbeats запускаються кожні **30m** (**1h** при використанні OAuth auth). Налаштуйте або вимкніть їх: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // або "0m", щоб вимкнути + every: "2h", // or "0m" to disable }, }, }, @@ -2089,17 +2108,17 @@ x-i18n: Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики. - Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити. + Якщо файл відсутній, heartbeat усе одно запускається, і модель сама вирішує, що робити. - Для override-ів на агента використовуйте `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Перевизначення для кожного агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - + Ні. OpenClaw працює на **вашому власному обліковому записі**, тож якщо ви є в групі, OpenClaw може її бачити. За замовчуванням відповіді в групах блокуються, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). - Якщо ви хочете, щоб лише **ви** могли запускати відповіді в групі: + Якщо ви хочете, щоб тільки **ви** могли запускати відповіді в групі: ```json5 { @@ -2115,7 +2134,7 @@ x-i18n: - Варіант 1 (найшвидший): дивіться журнали в реальному часі й надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): дивіться логи та надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json @@ -2124,67 +2143,74 @@ x-i18n: Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/дозволено): перелічіть групи з конфігурації: + Варіант 2 (якщо вже налаштовано/в allowlist): перелічіть групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Журнали](/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Логи](/cli/logs). Дві поширені причини: - - Увімкнено перевірку згадок (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групи немає в allowlist. + - Увімкнено керування згадками (типово). Ви повинні @згадати бота (або відповідати `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і група не входить до allowlist. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Прямі чати за замовчуванням згортаються в основний сеанс. Групи/канали мають власні session keys, а теми Telegram / thread-и Discord — це окремі сеанси. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + + Direct chats за замовчуванням згортаються в основну сесію. Групи/канали мають власні ключі сесій, а Telegram topics / Discord threads — це окремі сесії. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - Жорстких обмежень немає. Десятки (навіть сотні) — нормально, але слідкуйте за: + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але звертайте увагу на: - - **Зростанням диска:** sessions + transcripts живуть у `~/.openclaw/agents//sessions/`. - - **Вартістю токенів:** більше агентів означає більше одночасного використання моделей. - - **Операційною складністю:** auth profiles, workspaces і channel routing на агента. + - **Зростання диска:** sessions + transcripts живуть у `~/.openclaw/agents//sessions/`. + - **Витрати токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційне навантаження:** auth profiles, workspaces і channel routing для кожного агента. Поради: - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). - - Очищайте старі сеанси (видаляйте JSONL або записи сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб знаходити stray workspace і невідповідності профілів. + - Очищайте старі сесії (видаляйте JSONL або записи сховища), якщо диск росте. + - Використовуйте `openclaw doctor`, щоб знаходити зайві workspaces і невідповідності профілів. - - Так. Використовуйте **Маршрутизацію мультиагентів**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за - каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив'язаний до конкретних агентів. + + Так. Використовуйте **Багатоагентну маршрутизацію**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. - Доступ до браузера потужний, але це не рівнозначно "може робити все, що й людина" — антибот-захист, CAPTCHA і MFA - усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на host, - або CDP на машині, де насправді запускається браузер. + Доступ браузера потужний, але це не «робить усе, що може людина» — anti-bot, CAPTCHAs і MFA можуть + усе одно блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості + або CDP на машині, яка фактично запускає браузер. - Найкращий шаблон налаштування: + Найкраща практика налаштування: - - Host Gateway, що завжди увімкнений (VPS/Mac mini). + - Завжди ввімкнений хост Gateway (VPS/Mac mini). - Один агент на роль (bindings). - - Канали Slack, прив'язані до цих агентів. - - Локальний браузер через Chrome MCP або node за потреби. + - Канали Slack, прив’язані до цих агентів. + - Локальний браузер через Chrome MCP або node, коли це потрібно. - Документація: [Маршрутизація мультиагентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). + Документація: [Багатоагентна маршрутизація](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + [Browser](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: значення за замовчуванням, вибір, аліаси, перемикання +## Моделі: типові значення, вибір, псевдоніми, перемикання - + Типова модель OpenClaw — це те, що ви задаєте як: + + ``` + agents.defaults.model.primary + ``` + + На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви оп \ No newline at end of file diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index adef40852..b17c1a7f9 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Локальний запуск тестів або запуск у CI + - Запуск тестів локально або в CI - Додавання регресій для багів моделей/провайдерів - - Налагодження поведінки gateway та agent -summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест' + - Налагодження поведінки gateway + агента +summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-06T12:44:31Z" + generated_at: "2026-04-06T15:30:48Z" model: gpt-5.4 provider: openai - source_hash: b18d68d08b851dea994af250f7cb833a34523601d04fd2f118def9777c961b55 + source_hash: a2c8af6ff9cbef3d148f9d51016d9bc35b069a4467fb72874be265872ca13da1 source_path: help/testing.md workflow: 15 --- @@ -20,10 +20,10 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: -- Що охоплює кожен набір (і що він навмисно _не_ охоплює) +- Що покриває кожен набір (і що він навмисно _не_ покриває) - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресії для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -31,10 +31,10 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл спостереження Vitest (сучасна конфігурація projects): `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Прямий таргетинг файлу тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -Коли ви змінюєте тести або хочете мати більше впевненості: +Коли ви змінюєте тести або хочете більше впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` @@ -42,20 +42,20 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Коли налагоджуєте реальні провайдери/моделі (потрібні реальні облікові дані): - Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростаючий реалізм» (і зростаючу флейковість/вартість): -### Unit / integration (типово) +### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: нативні `projects` Vitest через `vitest.config.ts` -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, що охоплюються `vitest.unit.config.ts` -- Охоплення: +- Конфігурація: нативні Vitest `projects` через `vitest.config.ts` +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і включені до allowlist node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Обсяг: - Чисті unit-тести - Внутрішньопроцесні integration-тести (gateway auth, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів @@ -64,129 +64,132 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Реальні ключі не потрібні - Має бути швидким і стабільним - Примітка щодо projects: - - `pnpm test`, `pnpm test:watch` і `pnpm test:changed` тепер усі використовують однакову нативну кореневу конфігурацію `projects` Vitest. - - Прямі фільтри файлів нативно маршрутизуються через граф кореневого проєкту, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` працює без спеціального обгорткового скрипта. + - Нетаргетований `pnpm test` усе ще використовує конфігурацію root `projects` Vitest. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені шляхи git у ті самі scoped lanes, коли diff торкається лише маршрутизованих source/test файлів; зміни config/setup усе ще повертаються до широкого повторного запуску root project. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, що пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, щоб зміни helper-файлів не спричиняли повторний запуск усього важкого набору для цього каталогу. - Примітка щодо embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context ущільнення, + - Коли ви змінюєте вхідні дані для виявлення message-tool або контекст виконання compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані допоміжні регресії для чистих меж routing/normalization. - - Також підтримуйте в здоровому стані integration-набори embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. + - Також підтримуйте інтеграційні набори embedded runner у справному стані: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є - достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped ids і поведінка compaction як і раніше проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих інтеграційних шляхів. - Примітка щодо pool: - - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у кореневих projects, e2e та live-конфігураціях. - - Коренева UI-лінія зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner. - - `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` з конфігурації projects у кореневому `vitest.config.ts`. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. + - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner для root projects, e2e і live config. + - Root UI lane зберігає свій `jsdom` setup та optimizer, але тепер також працює на спільному non-isolated runner. + - `pnpm test` успадковує ті самі значення `threads` + `isolate: false` з конфігурації root `projects` у `vitest.config.ts`. + - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо вам потрібно порівняти з типовою поведінкою V8. - Примітка щодо швидкої локальної ітерації: - - `pnpm test:changed` запускає нативну конфігурацію projects з `--changed origin/main`. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму нативну конфігурацію projects, лише з вищою верхньою межею воркерів. - - Автоматичне масштабування локальних воркерів тепер навмисно консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька паралельних запусків Vitest типово шкодять менше. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-режимі лишалися коректними, коли змінюється тестова обв’язка. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка щодо налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпортів і вивід деталізації імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими відносно `origin/main`. - - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для витрат на запуск і трансформацію Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для unit-набору з вимкненим паралелізмом між файлами. + - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи однозначно зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості worker-ів. + - Автомасштабування локальних worker-ів тепер навмисно консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням менше шкодять. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб changed-mode повторні запуски залишалися коректними, коли змінюється wiring тестів. + - Конфігурація зберігає ввімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете мати одне явне місце кешу для прямого профілювання. +- Примітка щодо perf-debug: + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту, а також вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий профільний вигляд файлами, зміненими відносно `origin/main`. + - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для накладних витрат запуску та трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим паралелізмом файлів. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: - - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - - Працює в тихому режимі за замовчуванням, щоб зменшити накладні витрати на консольний I/O. +- Значення runtime за замовчуванням: + - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. + - Використовує адаптивну кількість worker-ів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. -- Охоплення: - - Наскрізна поведінка multi-instance gateway - - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії + - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість worker-ів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. +- Обсяг: + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, прив’язка вузлів і важчі мережеві сценарії - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестів (може працювати повільніше) + - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: OpenShell backend smoke - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Охоплення: - - Запускає ізольований gateway OpenShell на хості через Docker +- Обсяг: + - Запускає ізольований OpenShell gateway на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Проганяє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку remote-canonical filesystem через sandbox fs bridge + - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через fs bridge sandbox-а - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібні локальний CLI `openshell` і працездатний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox + - Лише opt-in; не входить до стандартного запуску `pnpm test:e2e` + - Потрібні локальний CLI `openshell` і справний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний CLI binary або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Охоплення: +- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику tool, проблем auth і поведінки rate limit + - Виявлення змін формату провайдера, особливостей tool-calling, проблем auth і поведінки rate limit - Очікування: - - За задумом не є CI-stable (реальні мережі, реальні політики провайдера, квоти, збої) - - Коштує грошей / використовує rate limits - - Краще запускати звужені підмножини, а не «все» -- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише коли навмисно хочете, щоб live-тести використовували вашу реальну домашню директорію. -- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежить від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit. + - Не є стабільним для CI за своєю природою (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає rate limits + - Краще запускати звужені піднабори, а не «все» +- Live-запуски зчитують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи завантаження gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові логи. +- Ротація API-ключів (специфічно для провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера було видно як активні навіть тоді, коли захоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. - - Налаштовуйте heartbeats прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeats gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність навіть під час довгих викликів провайдера, коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway одразу передаються під час live-запусків. + - Налаштовуйте heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте таку таблицю рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо зміни значні) -- Торкаєтеся мережевої логіки gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклики tool: запустіть звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) +- Зміни в gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / специфічних для провайдера збоїв / tool calling: запускайте звужений `pnpm test:live` ## Live: sweep можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android node, і перевірити поведінку контракту команд. -- Охоплення: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить застосунок). - - Перевірка `node.invoke` gateway для кожної команди на вибраному Android node. +- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android node, і перевірити поведінку контракту команд. +- Обсяг: + - Передумови/ручне налаштування (набір не встановлює/не запускає/не прив’язує застосунок). + - Перевірка `node.invoke` gateway для вибраного Android node по кожній команді. - Потрібне попереднє налаштування: - - Android-застосунок уже підключений і pair-ений із gateway. + - Android app уже підключено та прив’язано до gateway. - Застосунок утримується на передньому плані. - - Дозволи/підтвердження захоплення надані для можливостей, які ви очікуєте успішно пройти. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішними. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke моделей (profile keys) +## Live: smoke моделей (ключі профілів) Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи взагалі провайдер/модель може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). +- «Пряма модель» показує, чи здатні провайдер/модель взагалі відповісти з наданим ключем. +- «Gateway smoke» показує, що повний pipeline gateway+agent працює для цієї моделі (sessions, history, tools, sandbox policy тощо). ### Шар 1: Пряме завершення моделі (без gateway) @@ -194,58 +197,58 @@ Live-тести поділено на два шари, щоб можна бул - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) + - Запустити невелике completion для кожної моделі (і таргетовані регресії там, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався сфокусованим на gateway smoke -- Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску сучасного allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke +- Як вибрати моделі: + - `OPENCLAW_LIVE_MODELS=modern` щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` є псевдонімом для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) -- Як вибирати провайдерів: +- Як вибрати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: profile store і резервні варіанти через env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: зі сховища профілів і резервних env-значень + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламаний / ключ невалідний» від «pipeline gateway agent зламаний» - - Містить малі ізольовані регресії (наприклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline агента gateway зламаний» + - Містить невеликі, ізольовані регресії (наприклад, reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) -### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + dev agent smoke (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) - - Пройтися моделями-з-ключами і перевірити: - - «осмислену» відповідь (без tools) + - Створити/змінити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Ітеруватися по моделях із ключами й перевіряти: + - «змістовну» відповідь (без tools) - що працює реальний виклик tool (read probe) - - необов’язкові додаткові tool probes (exec+read probe) - - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють -- Подробиці probes (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить agent виконати `read` цього файла та повернути nonce. - - `exec+read` probe: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` повернути його. + - додаткові probes tools за потреби (exec+read probe) + - що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probe-ів (щоб ви могли швидко пояснити збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) -- Як вибирати моделі: - - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити -- Як вибирати провайдерів (уникати «OpenRouter для всього»): + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Як вибрати моделі: + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` є псевдонімом для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір +- Як вибрати провайдерів (уникайте «усе OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Tool + image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на tool) - - image probe виконується, коли модель оголошує підтримку image input + - `read` probe + `exec+read` probe (навантаження на tools) + - image probe запускається, коли модель рекламує підтримку image input - Потік (на високому рівні): - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає multimodal user message до моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: дрібні помилки дозволені) + - Gateway розбирає attachments в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent передає моделі multimodal user message + - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки допустимі) -Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list @@ -255,21 +258,21 @@ openclaw models list --json ## Live: smoke CLI backend (Codex CLI або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent через локальний CLI backend, не торкаючись вашої типової config. +- Мета: перевірити pipeline Gateway + agent з використанням локального CLI backend, не торкаючись вашої стандартної конфігурації. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Типові значення: +- Значення за замовчуванням: - Модель: `codex-cli/gpt-5.4` - Команда: `codex` - Аргументи: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]` -- Перевизначення (необов’язково): +- Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи вставляються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість вставляння в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням аргументів зображення, коли задано `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне image attachment (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до image-файлів як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням image-аргументів, коли встановлено `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити resume flow. Приклад: @@ -280,7 +283,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Рецепт для Docker: +Рецепт Docker: ```bash pnpm test:docker:live-cli-backend @@ -289,21 +292,21 @@ pnpm test:docker:live-cli-backend Примітки: - Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає smoke live CLI-backend усередині Docker-образу репозиторію від непривілейованого користувача `node`. -- Для `codex-cli` він встановлює Linux-пакет `@openai/codex` у кешований префікс із правом запису за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Для `codex-cli` він установлює Linux-пакет `@openai/codex` у кешований доступний для запису префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` - Мета: перевірити реальний conversation-bind flow ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати synthetic conversation каналу повідомлень на місці - - надіслати звичайне follow-up повідомлення в тій самій conversation - - перевірити, що follow-up потрапив у transcript прив’язаної ACP session + - прив’язати synthetic message-channel conversation на місці + - надіслати звичайне follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Типові значення: +- Значення за замовчуванням: - ACP agent: `claude` - Synthetic channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` @@ -312,8 +315,8 @@ pnpm test:docker:live-cli-backend - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця лінія використовує поверхню `chat.send` gateway з admin-only synthetic полями originating-route, щоб тести могли приєднати контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. + - Цей lane використовує поверхню gateway `chat.send` з admin-only synthetic originating-route полями, щоб тести могли прикріпити контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -323,53 +326,53 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Рецепт для Docker: +Рецепт Docker: ```bash pnpm test:docker:live-acp-bind ``` -Примітки для Docker: +Примітки щодо Docker: - Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Він читає `~/.profile`, підготовлює відповідні CLI auth material у контейнері, встановлює `acpx` у npm-префікс із правом запису, а потім за потреби встановлює запитаний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`). -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав доступність змінних середовища провайдера із завантаженого profile для дочірнього harness CLI. +- Він зчитує `~/.profile`, підготовлює відповідні auth-матеріали CLI в контейнері, установлює `acpx` у доступний для запису npm prefix, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`), якщо його немає. +- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого profile доступними для дочірнього harness CLI. -### Рекомендовані рецепти live-запусків +### Рекомендовані live-рецепти -Вузькі явні allowlist — найшвидші та найменш нестабільні: +Вузькі, явні allowlist-и є найшвидшими та найменш флейковими: -- Одна модель, direct (без gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклики tool для кількох провайдерів: +- Tool calling через кілька провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API-ключ Gemini + Antigravity): - - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (Gemini API key + Antigravity): + - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: -- `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окремі auth та особливості tooling). +- `google/...` використовує Gemini API (API key). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (auth через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власний auth і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / auth профілю); це те, що більшість користувачів має на увазі під «Gemini». + - CLI: OpenClaw викликає локальний binary `gemini`; він має власну auth-модель і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live є opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live є opt-in), але це **рекомендовані** моделі, які слід регулярно покривати на робочій машині з ключами. -### Сучасний набір smoke (виклик tool + image) +### Сучасний smoke-набір (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: -- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -377,12 +380,12 @@ pnpm test:docker:live-acp-bind - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запускати gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик tool (Read + необов’язковий Exec) +### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на сімейство провайдерів: +Виберіть принаймні одну модель з кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -390,46 +393,46 @@ pnpm test:docker:live-acp-bind - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (корисно мати): +Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновішу доступну) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання image (вкладення → multimodal message) +### Vision: надсилання image (attachment → multimodal message) -Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб прогнати image probe. +Додайте принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable variants тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використайте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), а також будь-який сумісний з OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко фіксувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко зафіксувати «всі моделі» в документації. Авторитетний список — це все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth на agent: `~/.openclaw/agents//agent/auth-profiles.json` (це й означає «profile keys» у live-тестах) -- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Директорія legacy state: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутня, але це не основне сховище profile-key) -- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного agent, legacy `credentials/` і підтримувані зовнішні директорії auth CLI у тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються з цієї staged config, щоб probes не працювали у вашому реальному host workspace. +- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється у staged live home, якщо присутній, але це не основне сховище ключів профілю) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, застарілий каталог `credentials/` і підтримувані зовнішні каталоги auth CLI у тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються в цій staged-конфігурації, щоб probes не торкалися вашого реального робочого середовища хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або скористайтеся Docker-ранерами нижче (вони можуть монтувати `~/.profile` в контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрипція аудіо) +## Deepgram live (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` @@ -444,21 +447,21 @@ Live-тести знаходять облікові дані так само, я - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Охоплення: - - Проганяє вбудовані шляхи comfy для image, video і `music_generate` +- Обсяг: + - Перевіряє вбудовані шляхи comfy image, video і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації plugin + - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації плагіна ## Live для генерації зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` -- Охоплення: - - Перелічує кожен зареєстрований plugin-провайдер генерації зображень - - Завантажує відсутні provider env vars із вашого login shell (`~/.profile`) перед probes - - Типово використовує live/env API-ключі раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдери без придатного auth/profile/model - - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: +- Обсяг: + - Перелічує кожен зареєстрований provider plugin генерації зображень + - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдери без придатних auth/profile/model + - Запускає стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -471,199 +474,234 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища profiles і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Live для генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- Охоплення: - - Проганяє спільний вбудований шлях провайдера генерації музики +- Обсяг: + - Перевіряє спільний вбудований шлях provider для генерації музики - Наразі покриває Google і MiniMax - - Завантажує provider env vars із вашого login shell (`~/.profile`) перед probes - - Пропускає провайдери без придатного auth/profile/model + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдери без придатних auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` з input лише у вигляді prompt + - `edit`, коли провайдер оголошує `capabilities.edit.enabled` + - Поточне покриття спільної лінії: + - `google`: `generate`, `edit` + - `minimax`: `generate` + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + +## Live для генерації відео + +- Тест: `extensions/video-generation-providers.live.test.ts` +- Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- Обсяг: + - Перевіряє спільний вбудований шлях provider для генерації відео + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдери без придатних auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` з input лише у вигляді prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний відеовхід на основі буфера в межах спільного sweep + - Поточне live-покриття `videoToVideo`: + - `google` + - `openai` + - `runway` лише коли вибрана модель — `runway/gen4_aleph` + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалених URL-посилань `http(s)` / MP4 +- Необов’язкове звуження: + - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` + - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Docker-ранери (необов’язкові перевірки «працює в Linux») Ці Docker-ранери поділяються на дві групи: -- Ранери для live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний config dir і workspace (а також читають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери для live-запусків типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і зчитують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - вам явно потрібне ширше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам навмисно потрібен більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker lanes. - Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери для live-моделей також bind-mount лише потрібні домівки auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашню директорію контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи auth store на хості: +Docker-ранери live-моделей також bind-mount-ять лише потрібні auth-home каталогів CLI (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени, не змінюючи host auth store: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) - CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) - Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke інсталяції + псевдонім `/plugin` + семантика restart для бандла Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Міст MCP channel (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Плагіни (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-ранери для live-моделей також монтують поточний checkout лише для читання і -розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним і водночас дає змогу запускати Vitest точно по вашому локальному source/config. -Під час підготовки пропускаються великі локальні кеші й артефакти збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні директорії виводу `.build` або -Gradle, тож Docker live-запуски не витрачають хвилини на копіювання +Docker-ранери live-моделей також монтують поточний checkout лише для читання і +підготовлюють його в тимчасовому workdir усередині контейнера. Це зберігає runtime +image компактним, але водночас дає змогу запускати Vitest саме на вашому локальному source/config. +Етап підготовки пропускає великі локальні кеші та результати збирання застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги виходу `.build` або +Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали -реальні воркери каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали +реальні channel worker-и Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway -live-покриття з цієї Docker-лінії. -`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, -запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +live-покриття з цього Docker lane. +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint-ами, +запускає закріплений контейнер Open WebUI проти цього gateway, входить +через Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає реальний chat request через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити холодний старт. -Для цієї лінії потрібен придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON-пейлоад на кшталт `{ "ok": true, "model": +образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. +Цей lane очікує придатний live-ключ моделі, і `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord чи iMessage. Він піднімає seeded Gateway -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення conversation через routing, читання transcript, metadata вкладень, -поведінку live event queue, routing вихідного надсилання і channel- та -permission-сповіщення в стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -інспектує raw stdio MCP frames напряму, тож smoke перевіряє саме те, що -міст реально випромінює, а не лише те, що вміє показати конкретний клієнтський SDK. +реального облікового запису Telegram, Discord або iMessage. Він піднімає seeded Gateway +container, запускає другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих conversation, читання transcript, metadata attachment-ів, +поведінку черги live-подій, маршрутизацію вихідного надсилання, а також сповіщення каналу + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо інспектує сирі stdio MCP frame-и, тому smoke перевіряє те, що +міст фактично видає, а не лише те, що трапляється на поверхню певного SDK клієнта. -Ручний smoke plain-language thread для ACP (не CI): +Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки routing ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки ACP thread routing, тому не видаляйте його. -Корисні env vars: +Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker -- Зовнішні auth dirs/files CLI у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - - Типові директорії: `.minimax` - - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні директорії/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і зчитується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker +- Зовнішні auth-каталоги/файли CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів + - Каталоги за замовчуванням: `.minimax` + - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища profiles (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt з перевіркою nonce, який використовує smoke Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway відкриває для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, використаний у smoke Open WebUI - `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег образу Open WebUI -## Перевірка документації +## Базова перевірка документації -Після редагування документації запускайте перевірки документації: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків на сторінці: `pnpm docs:check-links:anchors`. +Запускайте перевірки docs після редагування документації: `pnpm check:docs`. +Запускайте повну перевірку anchor-ів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик tools gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусовий auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Gateway tool calling (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Оцінювання надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: - Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні wizard flows, що перевіряють wiring session і ефекти config (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, що перевіряють wiring сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Decisioning:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Compliance:** чи читає agent `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? -- **Workflow contracts:** багатокрокові сценарії, що перевіряють порядок tool, перенесення history session і межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок tools, перенесення history сесії та межі sandbox. -Майбутні evals спершу мають залишатися детермінованими: +Майбутні eval-и мають насамперед залишатися детермінованими: -- Сценарний runner з mock-провайдерами для перевірки викликів tool + порядку, читання skill-файлів і wiring session. -- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live evals (opt-in, із керуванням через env) лише після того, як безпечний для CI набір буде на місці. +- Scenario runner з mock-провайдерами для перевірки викликів tools + їхнього порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, зосереджених на skill (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval-и (opt-in, із керуванням через env) лише після того, як безпечний для CI набір буде готовий. -## Contract tests (форма plugin і channel) +## Contract-тести (форма plugin і channel) -Contract tests перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму interface contract. Вони проходять по всіх знайдених plugins і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте команди contract явно, -коли торкаєтеся спільних поверхонь channel або provider. +Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір +перевірок форми та поведінки. Unit lane `pnpm test` за замовчуванням навмисно +пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, +коли ви змінюєте спільні поверхні channel або provider. ### Команди -- Усі contracts: `pnpm test:contracts` -- Лише contracts channel: `pnpm test:contracts:channels` -- Лише contracts provider: `pnpm test:contracts:plugins` +- Усі контракти: `pnpm test:contracts` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Contracts channel +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Contract майстра setup -- **session-binding** - Поведінка прив’язування session +- **plugin** - Базова форма plugin-а (id, name, capabilities) +- **setup** - Контракт майстра налаштування +- **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка thread ID +- **threading** - Обробка ID thread - **directory** - API directory/roster - **group-policy** - Застосування group policy -### Contracts status провайдера +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Status probes каналу -- **registry** - Форма registry plugin +- **status** - Probes статусу channel +- **registry** - Форма registry plugin-ів -### Contracts provider +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contract потоку auth -- **auth-choice** - Вибір/selection auth +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/відбір auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/interface plugin -- **wizard** - Майстер setup +- **discovery** - Виявлення plugin-ів +- **loader** - Завантаження plugin-ів +- **runtime** - Runtime provider-а +- **shape** - Форма/інтерфейс plugin-а +- **wizard** - Майстер налаштування ### Коли запускати -- Після зміни exports або subpaths у plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin-а +- Після рефакторингу реєстрації або виявлення plugin-ів -Contract tests запускаються в CI і не потребують реальних API-ключів. +Contract-тести запускаються в CI й не потребують реальних API-ключів. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або захоплення точної трансформації форми запиту) -- Якщо це за своєю природою лише live-проблема (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Намагайтеся націлюватися на найменший шар, який виявляє баг: - - баг перетворення/повторення запиту провайдера → direct models test - - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибраній цілі на клас SecretRef з metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або фіксація точної трансформації форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому шару, який ловить баг: + - баг перетворення/відтворення запиту провайдера → тест прямих моделей + - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock-тест +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній sampled-цілі для кожного класу SecretRef з metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не могли бути тихо пропущені. diff --git a/docs/uk/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/uk/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md new file mode 100644 index 000000000..9d3891305 --- /dev/null +++ b/docs/uk/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md @@ -0,0 +1,578 @@ +--- +date: 2026-04-05T00:00:00Z +status: active +title: 'рефакторинг: Поступово перетворити plugin-sdk на справжній пакет workspace' +type: refactor +x-i18n: + generated_at: "2026-04-06T15:29:48Z" + model: gpt-5.4 + provider: openai + source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 + source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md + workflow: 15 +--- + +# рефакторинг: Поступово перетворити plugin-sdk на справжній пакет workspace + +## Огляд + +Цей план вводить справжній пакет workspace для plugin SDK у +`packages/plugin-sdk` і використовує його, щоб підключити невелику першу хвилю розширень до +меж пакетів, які примусово перевіряються компілятором. Мета — змусити заборонені відносні +імпорти падати під час звичайного `tsc` для вибраного набору вбудованих +розширень-постачальників, не змушуючи виконувати міграцію в межах усього репозиторію й не створюючи +величезну поверхню конфліктів злиття. + +Ключовий інкрементальний крок — деякий час запускати паралельно два режими: + +| Режим | Форма імпорту | Хто його використовує | Примусове застосування | +| ----------- | ------------------------ | ------------------------------------ | -------------------------------------------- | +| Застарілий режим | `openclaw/plugin-sdk/*` | усі наявні розширення, які не підключені до нового режиму | поточна дозволена поведінка зберігається | +| Режим opt-in | `@openclaw/plugin-sdk/*` | лише розширення першої хвилі | локальний для пакета `rootDir` + посилання проєкту | + +## Постановка проблеми + +Поточний репозиторій експортує велику публічну поверхню plugin SDK, але це не справжній +пакет workspace. Натомість: + +- кореневий `tsconfig.json` напряму зіставляє `openclaw/plugin-sdk/*` із + `src/plugin-sdk/*.ts` +- розширення, які не були підключені до попереднього експерименту, усе ще поділяють цю + глобальну поведінку source alias +- додавання `rootDir` працює лише тоді, коли дозволені імпорти SDK перестають розв’язуватися в сирий + вихідний код репозиторію + +Це означає, що репозиторій може описувати бажану політику меж, але TypeScript +не забезпечує її чистого примусового застосування для більшості розширень. + +Потрібен інкрементальний шлях, який: + +- робить `plugin-sdk` справжнім +- переміщує SDK до пакета workspace з назвою `@openclaw/plugin-sdk` +- змінює лише приблизно 10 розширень у першому PR +- залишає решту дерева розширень на старій схемі до подальшого очищення +- уникає використання процесу `tsconfig.plugin-sdk.dts.json` + генерації декларацій під час postinstall як основного механізму для розгортання першої хвилі + +## Трасування вимог + +- R1. Створити справжній пакет workspace для plugin SDK під `packages/`. +- R2. Назвати новий пакет `@openclaw/plugin-sdk`. +- R3. Надати новому пакету SDK власні `package.json` і `tsconfig.json`. +- R4. Під час вікна міграції зберегти працездатність застарілих імпортів `openclaw/plugin-sdk/*` для розширень, які не підключені до нового режиму. +- R5. У першому PR підключити лише невелику першу хвилю розширень. +- R6. Для розширень першої хвилі має діяти fail-closed для відносних імпортів, які виходять + за межі кореня їхнього пакета. +- R7. Розширення першої хвилі мають споживати SDK через залежність пакета + і TS project reference, а не через кореневі псевдоніми `paths`. +- R8. План має уникати обов’язкового кроку генерації postinstall у межах усього репозиторію для + коректної роботи редактора. +- R9. Розгортання першої хвилі має бути придатним для рев’ю та злиття як PR помірного розміру, + а не як рефакторинг на 300+ файлів у межах усього репозиторію. + +## Межі охоплення + +- Без повної міграції всіх вбудованих розширень у першому PR. +- Без вимоги видаляти `src/plugin-sdk` у першому PR. +- Без вимоги негайно переналаштовувати кожен кореневий шлях збірки чи тестування на використання нового пакета. +- Без спроби примусово забезпечити squiggles у VS Code для кожного розширення, яке не підключене до нового режиму. +- Без широкого очищення lint для решти дерева розширень. +- Без великих змін поведінки під час виконання, окрім розв’язання імпортів, належності пакетів + і примусового застосування меж для розширень, підключених до нового режиму. + +## Контекст і дослідження + +### Відповідний код і шаблони + +- `pnpm-workspace.yaml` уже включає `packages/*` і `extensions/*`, тож + новий пакет workspace у `packages/plugin-sdk` вписується в наявну структуру + репозиторію. +- Наявні пакети workspace, такі як `packages/memory-host-sdk/package.json` + і `packages/plugin-package-contract/package.json`, уже використовують локальні для пакета + карти `exports`, що базуються на `src/*.ts`. +- Кореневий `package.json` зараз публікує поверхню SDK через `./plugin-sdk` + і `./plugin-sdk/*` exports, які спираються на `dist/plugin-sdk/*.js` і + `dist/plugin-sdk/*.d.ts`. +- `src/plugin-sdk/entrypoints.ts` і `scripts/lib/plugin-sdk-entrypoints.json` + уже виконують роль канонічного інвентарю entrypoint для поверхні SDK. +- Кореневий `tsconfig.json` зараз зіставляє: + - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` + - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` +- Попередній експеримент із межами показав, що локальний для пакета `rootDir` працює для + заборонених відносних імпортів лише після того, як дозволені імпорти SDK перестають розв’язуватися в сирий + вихідний код за межами пакета розширення. + +### Набір розширень першої хвилі + +Цей план передбачає, що до першої хвилі входить набір, орієнтований на постачальників, який найменш імовірно +потягне за собою складні крайові випадки runtime каналів: + +- `extensions/anthropic` +- `extensions/exa` +- `extensions/firecrawl` +- `extensions/groq` +- `extensions/mistral` +- `extensions/openai` +- `extensions/perplexity` +- `extensions/tavily` +- `extensions/together` +- `extensions/xai` + +### Інвентар поверхні SDK для першої хвилі + +Наразі розширення першої хвилі імпортують керовану підмножину підшляхів SDK. +Початковий пакет `@openclaw/plugin-sdk` має покривати лише такі: + +- `agent-runtime` +- `cli-runtime` +- `config-runtime` +- `core` +- `image-generation` +- `media-runtime` +- `media-understanding` +- `plugin-entry` +- `plugin-runtime` +- `provider-auth` +- `provider-auth-api-key` +- `provider-auth-login` +- `provider-auth-runtime` +- `provider-catalog-shared` +- `provider-entry` +- `provider-http` +- `provider-model-shared` +- `provider-onboard` +- `provider-stream-family` +- `provider-stream-shared` +- `provider-tools` +- `provider-usage` +- `provider-web-fetch` +- `provider-web-search` +- `realtime-transcription` +- `realtime-voice` +- `runtime-env` +- `secret-input` +- `security-runtime` +- `speech` +- `testing` + +### Інституційні висновки + +- У цій робочій копії не було релевантних записів `docs/solutions/`. + +### Зовнішні посилання + +- Для цього плану не потрібні були зовнішні дослідження. Репозиторій уже містить + потрібні шаблони пакетів workspace та експорту SDK. + +## Ключові технічні рішення + +- Ввести `@openclaw/plugin-sdk` як новий пакет workspace, зберігши при цьому + застарілу кореневу поверхню `openclaw/plugin-sdk/*` під час міграції. + Обґрунтування: це дозволяє першій хвилі розширень перейти на справжнє + розв’язання пакетів, не змушуючи змінювати всі розширення й усі кореневі шляхи збірки одночасно. + +- Використовувати окрему базову конфігурацію для меж з opt-in, наприклад + `extensions/tsconfig.package-boundary.base.json`, замість заміни + наявної бази розширень для всіх. + Обґрунтування: під час міграції репозиторій має одночасно підтримувати і застарілий, і opt-in режим розширень. + +- Використовувати TS project references від розширень першої хвилі до + `packages/plugin-sdk/tsconfig.json` і встановити + `disableSourceOfProjectReferenceRedirect` для режиму меж opt-in. + Обґрунтування: це дає `tsc` справжній граф пакетів і водночас ускладнює fallback редактора та + компілятора до обходу сирого вихідного коду. + +- Зберегти `@openclaw/plugin-sdk` приватним у першій хвилі. + Обґрунтування: безпосередня мета — внутрішнє примусове застосування меж і безпека + міграції, а не публікація другого зовнішнього контракту SDK до стабілізації поверхні. + +- Перемістити в першому реалізаційному зрізі лише підшляхи SDK для першої хвилі та + зберегти compatibility bridges для решти. + Обґрунтування: фізичне переміщення всіх 315 файлів `src/plugin-sdk/*.ts` в одному PR — + це саме та поверхня конфліктів злиття, якої цей план намагається уникнути. + +- Не покладатися на `scripts/postinstall-bundled-plugins.mjs` для побудови декларацій SDK + для першої хвилі. + Обґрунтування: явні потоки build/reference легше пояснювати й вони роблять поведінку + репозиторію більш передбачуваною. + +## Відкриті питання + +### Вирішено під час планування + +- Які розширення мають увійти до першої хвилі? + Використовувати 10 наведених вище розширень provider/web-search, оскільки вони + структурно ізольованіші, ніж важчі пакети каналів. + +- Чи має перший PR замінити все дерево розширень? + Ні. Перший PR має підтримувати два режими паралельно й підключати лише + першу хвилю. + +- Чи має перша хвиля вимагати побудови декларацій під час postinstall? + Ні. Граф пакетів/посилань має бути явним, а CI має навмисно запускати + відповідну локальну для пакета перевірку типів. + +### Відкладено до реалізації + +- Чи може пакет першої хвилі вказувати безпосередньо на локальні для пакета `src/*.ts` + лише через project references, чи все ж для пакета `@openclaw/plugin-sdk` + потрібен невеликий крок генерації декларацій. + Це питання валідації TS graph, яке належить до реалізації. + +- Чи має кореневий пакет `openclaw` негайно проксувати підшляхи SDK першої хвилі до + виводів `packages/plugin-sdk`, чи й надалі використовувати згенеровані + compatibility shim у `src/plugin-sdk`. + Це деталь сумісності та форми збірки, яка залежить від мінімального + шляху реалізації, що зберігає зелений CI. + +## Технічний дизайн високого рівня + +> Це ілюструє задуманий підхід і є орієнтовною підказкою для рев’ю, а не специфікацією реалізації. Агент, який реалізує зміни, має сприймати це як контекст, а не як код, який треба відтворити. + +```mermaid +flowchart TB + subgraph Legacy["Застарілі розширення (без змін)"] + L1["extensions/*\nopenclaw/plugin-sdk/*"] + L2["root tsconfig paths"] + L1 --> L2 + L2 --> L3["src/plugin-sdk/*"] + end + + subgraph OptIn["Розширення першої хвилі"] + O1["10 розширень з opt-in"] + O2["extensions/tsconfig.package-boundary.base.json"] + O3["rootDir = '.'\nproject reference"] + O4["@openclaw/plugin-sdk"] + O1 --> O2 + O2 --> O3 + O3 --> O4 + end + + subgraph SDK["Новий пакет workspace"] + P1["packages/plugin-sdk/package.json"] + P2["packages/plugin-sdk/tsconfig.json"] + P3["packages/plugin-sdk/src/.ts"] + P1 --> P2 + P2 --> P3 + end + + O4 --> SDK +``` + +## Одиниці реалізації + +- [ ] **Одиниця 1: Увести справжній пакет workspace `@openclaw/plugin-sdk`** + +**Мета:** Створити справжній пакет workspace для SDK, який зможе володіти +поверхнею підшляхів першої хвилі без примусової міграції в межах усього репозиторію. + +**Вимоги:** R1, R2, R3, R8, R9 + +**Залежності:** Немає + +**Файли:** + +- Створити: `packages/plugin-sdk/package.json` +- Створити: `packages/plugin-sdk/tsconfig.json` +- Створити: `packages/plugin-sdk/src/index.ts` +- Створити: `packages/plugin-sdk/src/*.ts` для підшляхів SDK першої хвилі +- Змінити: `pnpm-workspace.yaml`, лише якщо потрібні коригування glob шаблонів пакетів +- Змінити: `package.json` +- Змінити: `src/plugin-sdk/entrypoints.ts` +- Змінити: `scripts/lib/plugin-sdk-entrypoints.json` +- Тест: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` + +**Підхід:** + +- Додати новий пакет workspace з назвою `@openclaw/plugin-sdk`. +- Почати з підшляхів SDK першої хвилі, а не з усього дерева з 315 файлів. +- Якщо пряме переміщення entrypoint першої хвилі створить надто великий diff, перший + PR може спочатку ввести цей підшлях у `packages/plugin-sdk/src` як тонкий + package wrapper, а потім у наступному PR перемкнути джерело істини для цього кластера підшляхів на пакет. +- Повторно використати наявний механізм інвентарю entrypoint, щоб поверхня пакета першої хвилі + декларувалася в одному канонічному місці. +- Зберегти кореневі exports пакета для застарілих користувачів, поки пакет workspace + стане новим контрактом opt-in. + +**Шаблони, яких слід дотримуватися:** + +- `packages/memory-host-sdk/package.json` +- `packages/plugin-package-contract/package.json` +- `src/plugin-sdk/entrypoints.ts` + +**Сценарії тестування:** + +- Щасливий шлях: пакет workspace експортує кожен підшлях першої хвилі, перелічений у + плані, і жоден обов’язковий експорт першої хвилі не відсутній. +- Крайовий випадок: метадані exports пакета лишаються стабільними, коли список entrypoint першої хвилі + повторно генерується або порівнюється з канонічним інвентарем. +- Інтеграція: застарілі кореневі exports SDK у пакеті залишаються присутніми після введення нового workspace package. + +**Перевірка:** + +- Репозиторій містить дійсний пакет workspace `@openclaw/plugin-sdk` зі + стабільною картою exports першої хвилі та без регресії застарілих exports у кореневому + `package.json`. + +- [ ] **Одиниця 2: Додати TS-режим меж з opt-in для розширень із примусовими межами пакетів** + +**Мета:** Визначити режим конфігурації TS, який використовуватимуть розширення з opt-in, +водночас залишивши наявну TS-поведінку розширень без змін для всіх інших. + +**Вимоги:** R4, R6, R7, R8, R9 + +**Залежності:** Одиниця 1 + +**Файли:** + +- Створити: `extensions/tsconfig.package-boundary.base.json` +- Створити: `tsconfig.boundary-optin.json` +- Змінити: `extensions/xai/tsconfig.json` +- Змінити: `extensions/openai/tsconfig.json` +- Змінити: `extensions/anthropic/tsconfig.json` +- Змінити: `extensions/mistral/tsconfig.json` +- Змінити: `extensions/groq/tsconfig.json` +- Змінити: `extensions/together/tsconfig.json` +- Змінити: `extensions/perplexity/tsconfig.json` +- Змінити: `extensions/tavily/tsconfig.json` +- Змінити: `extensions/exa/tsconfig.json` +- Змінити: `extensions/firecrawl/tsconfig.json` +- Тест: `src/plugins/contracts/extension-package-project-boundaries.test.ts` +- Тест: `test/extension-package-tsc-boundary.test.ts` + +**Підхід:** + +- Залишити `extensions/tsconfig.base.json` для застарілих розширень. +- Додати нову базову конфігурацію opt-in, яка: + - встановлює `rootDir: "."` + - містить посилання на `packages/plugin-sdk` + - вмикає `composite` + - вимикає project-reference source redirect, коли це потрібно +- Додати окремий solution config для графа typecheck першої хвилі замість + перебудови кореневого TS-проєкту репозиторію в тому самому PR. + +**Примітка щодо виконання:** Почніть із canary typecheck локально для пакета з одним +розширенням opt-in, яке спочатку падає, перш ніж застосовувати шаблон до всіх 10. + +**Шаблони, яких слід дотримуватися:** + +- Наявний шаблон локального `tsconfig.json` розширень із попередньої + роботи над межами +- Шаблон пакета workspace з `packages/memory-host-sdk` + +**Сценарії тестування:** + +- Щасливий шлях: кожне розширення з opt-in успішно проходить typecheck через + TS-конфігурацію package-boundary. +- Шлях помилки: canary relative import із `../../src/cli/acp-cli.ts` падає + з `TS6059` для розширення з opt-in. +- Інтеграція: розширення без opt-in лишаються недоторканими й не зобов’язані + брати участь у новому solution config. + +**Перевірка:** + +- Існує окремий граф typecheck для 10 розширень з opt-in, і погані + відносні імпорти з одного з них падають під звичайним `tsc`. + +- [ ] **Одиниця 3: Перенести розширення першої хвилі на `@openclaw/plugin-sdk`** + +**Мета:** Змінити розширення першої хвилі так, щоб вони споживали справжній пакет SDK +через метадані залежностей, project references та імпорти за назвою пакета. + +**Вимоги:** R5, R6, R7, R9 + +**Залежності:** Одиниця 2 + +**Файли:** + +- Змінити: `extensions/anthropic/package.json` +- Змінити: `extensions/exa/package.json` +- Змінити: `extensions/firecrawl/package.json` +- Змінити: `extensions/groq/package.json` +- Змінити: `extensions/mistral/package.json` +- Змінити: `extensions/openai/package.json` +- Змінити: `extensions/perplexity/package.json` +- Змінити: `extensions/tavily/package.json` +- Змінити: `extensions/together/package.json` +- Змінити: `extensions/xai/package.json` +- Змінити: production і test imports під коренями кожного з 10 розширень, які + зараз посилаються на `openclaw/plugin-sdk/*` + +**Підхід:** + +- Додати `@openclaw/plugin-sdk: workspace:*` до `devDependencies` розширень + першої хвилі. +- Замінити в цих пакетах імпорти `openclaw/plugin-sdk/*` на + `@openclaw/plugin-sdk/*`. +- Залишити внутрішні локальні імпорти розширення на локальні barrel, такі як `./api.ts` і + `./runtime-api.ts`. +- Не змінювати розширення без opt-in у цьому PR. + +**Шаблони, яких слід дотримуватися:** + +- Наявні barrel локальних імпортів розширень (`api.ts`, `runtime-api.ts`) +- Форма залежностей пакета, яку використовують інші пакети workspace `@openclaw/*` + +**Сценарії тестування:** + +- Щасливий шлях: кожне мігроване розширення, як і раніше, реєструється/завантажується через свої наявні + тести plugin після переписування імпортів. +- Крайовий випадок: імпорти SDK лише для тестів у наборі розширень з opt-in, як і раніше, коректно + розв’язуються через новий пакет. +- Інтеграція: мігровані розширення не потребують кореневих псевдонімів + `openclaw/plugin-sdk/*` для typechecking. + +**Перевірка:** + +- Розширення першої хвилі збираються та тестуються проти `@openclaw/plugin-sdk` + без потреби в застарілому кореневому шляху-псевдонімі SDK. + +- [ ] **Одиниця 4: Зберегти застарілу сумісність, поки міграція залишається частковою** + +**Мета:** Зберегти працездатність решти репозиторію, поки SDK існує і в застарілій, +і в новій формі пакета під час міграції. + +**Вимоги:** R4, R8, R9 + +**Залежності:** Одиниці 1-3 + +**Файли:** + +- Змінити: `src/plugin-sdk/*.ts` для compatibility shim першої хвилі за потреби +- Змінити: `package.json` +- Змінити: збірку або plumbing exports, які формують артефакти SDK +- Тест: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` +- Тест: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts` + +**Підхід:** + +- Зберегти кореневий `openclaw/plugin-sdk/*` як compatibility surface для застарілих + розширень і для зовнішніх споживачів, які ще не переходять. +- Використовувати або згенеровані shim, або кореневу proxy wiring exports для підшляхів + першої хвилі, які переміщено в `packages/plugin-sdk`. +- Не намагатися прибрати кореневу поверхню SDK на цій фазі. + +**Шаблони, яких слід дотримуватися:** + +- Наявна генерація кореневих exports SDK через `src/plugin-sdk/entrypoints.ts` +- Наявна сумісність package export у кореневому `package.json` + +**Сценарії тестування:** + +- Щасливий шлях: застарілий кореневий імпорт SDK, як і раніше, розв’язується для розширення без opt-in + після появи нового пакета. +- Крайовий випадок: підшлях першої хвилі працює як через застарілу кореневу поверхню, так і через + поверхню нового пакета під час вікна міграції. +- Інтеграція: contract tests для індексу/пакета plugin-sdk і далі бачать узгоджену + публічну поверхню. + +**Перевірка:** + +- Репозиторій підтримує і застарілий, і opt-in режим споживання SDK без + поломки незмінених розширень. + +- [ ] **Одиниця 5: Додати локальне примусове застосування та задокументувати контракт міграції** + +**Мета:** Додати CI та настанови для учасників, які забезпечують нову поведінку для +першої хвилі, не вдаючи, що мігроване все дерево розширень. + +**Вимоги:** R5, R6, R8, R9 + +**Залежності:** Одиниці 1-4 + +**Файли:** + +- Змінити: `package.json` +- Змінити: файли workflow CI, які мають запускати typecheck меж першої хвилі з opt-in +- Змінити: `AGENTS.md` +- Змінити: `docs/plugins/sdk-overview.md` +- Змінити: `docs/plugins/sdk-entrypoints.md` +- Змінити: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` + +**Підхід:** + +- Додати явний gate для першої хвилі, наприклад окремий запуск `tsc -b` solution для + `packages/plugin-sdk` плюс 10 розширень з opt-in. +- Задокументувати, що репозиторій тепер підтримує і застарілий, і opt-in режими розширень, + і що нова робота над межами розширень має надавати перевагу маршруту через новий пакет. +- Зафіксувати правило міграції наступної хвилі, щоб подальші PR могли додавати більше розширень + без повторного обговорення архітектури. + +**Шаблони, яких слід дотримуватися:** + +- Наявні contract tests у `src/plugins/contracts/` +- Наявні оновлення документації, які пояснюють поетапні міграції + +**Сценарії тестування:** + +- Щасливий шлях: новий gate typecheck першої хвилі проходить для пакета workspace + і розширень з opt-in. +- Шлях помилки: додавання нового забороненого відносного імпорту в розширенні з opt-in + ламає локальний gate typecheck. +- Інтеграція: CI ще не вимагає, щоб розширення без opt-in задовольняли новий + режим package-boundary. + +**Перевірка:** + +- Шлях примусового застосування для першої хвилі задокументований, протестований і придатний до запуску + без примусу до міграції всього дерева розширень. + +## Вплив на систему загалом + +- **Граф взаємодії:** ця робота зачіпає джерело істини SDK, кореневі package + exports, метадані пакетів розширень, розкладку TS graph і перевірки CI. +- **Поширення помилок:** основним очікуваним режимом відмови стають помилки TS під час компіляції + (`TS6059`) у розширеннях з opt-in замість збоїв лише в користувацьких скриптах. +- **Ризики життєвого циклу стану:** подвійна поверхня під час міграції створює ризик розходження між + кореневими compatibility export і новим пакетом workspace. +- **Паритет поверхні API:** підшляхи першої хвилі мають залишатися семантично ідентичними через + і `openclaw/plugin-sdk/*`, і `@openclaw/plugin-sdk/*` під час + переходу. +- **Покриття інтеграції:** unit tests недостатньо; потрібні локальні package-graph + typecheck, щоб довести межу. +- **Незмінні інваріанти:** розширення без opt-in зберігають поточну поведінку + в PR 1. Цей план не заявляє про примусове застосування меж імпортів у межах усього репозиторію. + +## Ризики та залежності + +| Ризик | Пом’якшення | +| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| Пакет першої хвилі все ще розв’язується назад у сирий вихідний код, і `rootDir` фактично не працює в режимі fail-closed | Зробити першим кроком реалізації canary package-reference на одному розширенні з opt-in, перш ніж розширювати на весь набір | +| Переміщення надто великої частини вихідного коду SDK одразу відтворює початкову проблему конфліктів злиття | Перемістити в першому PR лише підшляхи першої хвилі та зберегти кореневі compatibility bridge | +| Застаріла й нова поверхні SDK семантично розходяться | Зберігати єдиний inventory entrypoint, додати compatibility contract tests і явно зафіксувати паритет подвійної поверхні | +| Кореневі шляхи збірки/тестів репозиторію випадково починають неконтрольовано залежати від нового пакета | Використовувати окремий solution config для opt-in і не вносити зміни в кореневу TS topology у першому PR | + +## Поетапне постачання + +### Фаза 1 + +- Увести `@openclaw/plugin-sdk` +- Визначити поверхню підшляхів першої хвилі +- Довести, що одне розширення з opt-in може працювати в режимі fail-closed через `rootDir` + +### Фаза 2 + +- Підключити 10 розширень першої хвилі +- Зберегти кореневу сумісність для всіх інших + +### Фаза 3 + +- Додавати більше розширень у наступних PR +- Переміщати більше підшляхів SDK у пакет workspace +- Прибрати кореневу сумісність лише після зникнення набору застарілих розширень + +## Документація / операційні примітки + +- Перший PR має явно описуватися як міграція з подвійним режимом, а не як + завершення примусового застосування в межах усього репозиторію. +- Посібник із міграції має спрощувати додавання нових розширень у подальших PR + за тим самим шаблоном package/dependency/reference. + +## Джерела та посилання + +- Попередній план: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` +- Конфігурація workspace: `pnpm-workspace.yaml` +- Наявний inventory entrypoint SDK: `src/plugin-sdk/entrypoints.ts` +- Наявні кореневі exports SDK: `package.json` +- Наявні шаблони пакетів workspace: + - `packages/memory-host-sdk/package.json` + - `packages/plugin-package-contract/package.json` diff --git a/docs/uk/platforms/ios.md b/docs/uk/platforms/ios.md index a434dfd27..8d7b40519 100644 --- a/docs/uk/platforms/ios.md +++ b/docs/uk/platforms/ios.md @@ -1,38 +1,38 @@ --- read_when: - - Сполучення або повторне підключення вузла iOS - - Запуск застосунку iOS з вихідного коду - - Налагодження виявлення gateway або команд canvas -summary: 'Застосунок вузла iOS: підключення до Gateway, сполучення, canvas і усунення несправностей' -title: Застосунок iOS + - Pairing або повторне підключення iOS-вузла + - Запуск iOS-застосунку з вихідного коду + - Налагодження виявлення шлюзу або команд canvas +summary: 'iOS-застосунок вузла: підключення до Gateway, pairing, canvas і усунення несправностей' +title: iOS App x-i18n: - generated_at: "2026-04-05T18:10:44Z" + generated_at: "2026-04-06T15:29:39Z" model: gpt-5.4 provider: openai - source_hash: 1e9d9cec58afd4003dff81d3e367bfbc6a634c1b229e433e08fd78fbb5f2e5a9 + source_hash: f3e0a6e33e72d4c9f1f17ef70a1b67bae9ebe4a2dca16677ea6b28d0ddac1b4e source_path: platforms/ios.md workflow: 15 --- -# Застосунок iOS (вузол) +# iOS App (вузол) -Доступність: внутрішнє попереднє ознайомлення. Застосунок iOS ще не розповсюджується публічно. +Доступність: внутрішнє preview. iOS-застосунок ще не розповсюджується публічно. ## Що він робить - Підключається до Gateway через WebSocket (LAN або tailnet). -- Надає можливості вузла: Canvas, знімок екрана, захоплення з камери, геолокація, режим розмови, голосове пробудження. -- Отримує команди `node.invoke` і повідомляє про події стану вузла. +- Надає можливості вузла: Canvas, знімок екрана, захоплення з камери, геолокація, режим розмови, Voice wake. +- Отримує команди `node.invoke` і повідомляє події стану вузла. ## Вимоги -- Gateway, запущений на іншому пристрої (macOS, Linux або Windows через WSL2). +- Gateway запущений на іншому пристрої (macOS, Linux або Windows через WSL2). - Мережевий шлях: - Та сама LAN через Bonjour, **або** - Tailnet через unicast DNS-SD (приклад домену: `openclaw.internal.`), **або** - - Ручне введення host/port (резервний варіант). + - Ручне задання host/port (резервний варіант). -## Швидкий старт (сполучення + підключення) +## Швидкий старт (pair + connect) 1. Запустіть Gateway: @@ -40,18 +40,18 @@ x-i18n: openclaw gateway --port 18789 ``` -2. У застосунку iOS відкрийте Settings і виберіть знайдений gateway (або увімкніть Manual Host і введіть host/port). +2. У застосунку iOS відкрийте Settings і виберіть знайдений gateway (або ввімкніть Manual Host і введіть host/port). -3. Підтвердьте запит на сполучення на хості gateway: +3. Схваліть запит pairing на хості шлюзу: ```bash openclaw devices list openclaw devices approve ``` -Якщо застосунок повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний ключ), -попередній очікувальний запит замінюється, і створюється новий `requestId`. -Перед підтвердженням знову виконайте `openclaw devices list`. +Якщо застосунок повторює спробу pairing зі зміненими даними автентифікації (роль/scopes/публічний ключ), +попередній незавершений запит замінюється, і створюється новий `requestId`. +Перед схваленням знову виконайте `openclaw devices list`. 4. Перевірте підключення: @@ -62,10 +62,10 @@ openclaw gateway call node.list --params "{}" ## Push через relay для офіційних збірок -Офіційно розповсюджувані збірки iOS використовують зовнішній push relay замість публікації необробленого APNs-токена -до gateway. +Офіційні розповсюджувані збірки iOS використовують зовнішній push relay замість публікації сирого токена APNs +у шлюз. -Вимога на боці gateway: +Вимога на боці Gateway: ```json5 { @@ -81,86 +81,86 @@ openclaw gateway call node.list --params "{}" } ``` -Як працює цей процес: +Як працює потік: -- Застосунок iOS реєструється в relay за допомогою App Attest і квитанції застосунку. -- Relay повертає непрозорий relay handle разом із send grant у межах реєстрації. -- Застосунок iOS отримує ідентичність сполученого gateway і включає її до relay-реєстрації, щоб relay-backed реєстрація була делегована саме цьому gateway. -- Застосунок пересилає цю relay-backed реєстрацію до сполученого gateway через `push.apns.register`. -- Gateway використовує збережений relay handle для `push.test`, пробудження у фоновому режимі та сигналів пробудження. -- Base URL relay на gateway має збігатися з URL relay, вбудованим в офіційну/TestFlight збірку iOS. -- Якщо згодом застосунок підключається до іншого gateway або до збірки з іншим relay base URL, він оновлює relay-реєстрацію замість повторного використання старої прив’язки. +- iOS-застосунок реєструється в relay за допомогою App Attest і receipt застосунку. +- Relay повертає непрозорий relay handle разом із send grant, обмеженим областю реєстрації. +- iOS-застосунок отримує ідентичність pair-ованого gateway і включає її в реєстрацію relay, тож relay-backed реєстрація делегується саме цьому gateway. +- Застосунок передає цю relay-backed реєстрацію pair-ованому gateway через `push.apns.register`. +- Gateway використовує збережений relay handle для `push.test`, фонових пробуджень і wake nudges. +- Base URL relay шлюзу має збігатися з URL relay, вбудованим в офіційну/TestFlight збірку iOS. +- Якщо застосунок пізніше підключиться до іншого gateway або до збірки з іншим base URL relay, він оновить relay-реєстрацію замість повторного використання старої прив’язки. -Що **не** потрібно gateway для цього шляху: +Що gateway **не** потрібно для цього шляху: -- Жодного relay-токена на рівні розгортання. -- Жодного прямого APNs-ключа для relay-backed надсилань з офіційних/TestFlight збірок. +- Жодного relay-токена для всього розгортання. +- Жодного прямого ключа APNs для relay-backed надсилання в офіційних/TestFlight збірках. -Очікуваний робочий процес оператора: +Очікуваний потік для оператора: 1. Встановіть офіційну/TestFlight збірку iOS. -2. Встановіть `gateway.push.apns.relay.baseUrl` на gateway. -3. Сполучіть застосунок із gateway і дочекайтеся завершення підключення. -4. Застосунок автоматично публікує `push.apns.register` після того, як має APNs-токен, сеанс оператора підключено, а relay-реєстрація успішна. -5. Після цього `push.test`, пробудження при повторному підключенні та сигнали пробудження можуть використовувати збережену relay-backed реєстрацію. +2. Задайте `gateway.push.apns.relay.baseUrl` на шлюзі. +3. Pair-уйте застосунок зі шлюзом і дочекайтеся завершення підключення. +4. Застосунок автоматично публікує `push.apns.register`, щойно матиме токен APNs, сесію оператора буде підключено, а реєстрація relay завершиться успішно. +5. Після цього `push.test`, пробудження для перепідключення та wake nudges зможуть використовувати збережену relay-backed реєстрацію. Примітка щодо сумісності: -- `OPENCLAW_APNS_RELAY_BASE_URL` усе ще працює як тимчасове перевизначення через змінну середовища для gateway. +- `OPENCLAW_APNS_RELAY_BASE_URL` як і раніше працює як тимчасове перевизначення env для gateway. ## Потік автентифікації та довіри -Relay існує для забезпечення двох обмежень, які прямий APNs-на-gateway не може забезпечити для +Relay існує, щоб забезпечити дві умови, які прямий APNs-on-gateway не може надати для офіційних збірок iOS: -- Лише справжні збірки OpenClaw для iOS, розповсюджені через Apple, можуть використовувати розміщений relay. -- Gateway може надсилати relay-backed push лише для пристроїв iOS, які були сполучені саме з цим +- Лише справжні збірки OpenClaw для iOS, розповсюджені через Apple, можуть використовувати hosted relay. +- Gateway може надсилати relay-backed push лише для iOS-пристроїв, які виконали pairing саме з цим gateway. -Поетапно: +Покроково: 1. `iOS app -> gateway` - - Спочатку застосунок сполучається з gateway через звичайний потік автентифікації Gateway. - - Це надає застосунку автентифікований сеанс вузла та автентифікований сеанс оператора. - - Сеанс оператора використовується для виклику `gateway.identity.get`. + - Спочатку застосунок виконує pairing зі шлюзом через звичайний потік автентифікації Gateway. + - Це дає застосунку автентифіковану сесію вузла та автентифіковану сесію оператора. + - Сесія оператора використовується для виклику `gateway.identity.get`. 2. `iOS app -> relay` - Застосунок викликає кінцеві точки реєстрації relay через HTTPS. - - Реєстрація включає доказ App Attest і квитанцію застосунку. - - Relay перевіряє bundle ID, доказ App Attest і квитанцію Apple та вимагає - офіційного/продакшн-шляху розповсюдження. - - Саме це не дозволяє локальним Xcode/dev збіркам використовувати розміщений relay. Локальна збірка може бути - підписаною, але вона не задовольняє вимогу relay щодо офіційного підтвердження розповсюдження через Apple. + - Реєстрація включає App Attest proof і receipt застосунку. + - Relay перевіряє bundle ID, App Attest proof і Apple receipt та вимагає + офіційний/production шлях розповсюдження. + - Саме це блокує локальні Xcode/dev збірки від використання hosted relay. Локальна збірка може бути + підписана, але вона не задовольняє вимогу офіційного підтвердження розповсюдження через Apple, яку очікує relay. -3. `gateway identity delegation` - - Перед relay-реєстрацією застосунок отримує ідентичність сполученого gateway з +3. `делегування ідентичності gateway` + - Перед реєстрацією relay застосунок отримує ідентичність pair-ованого gateway через `gateway.identity.get`. - - Застосунок включає цю ідентичність gateway до payload relay-реєстрації. - - Relay повертає relay handle і send grant у межах реєстрації, делеговані + - Застосунок включає цю ідентичність gateway у payload реєстрації relay. + - Relay повертає relay handle і send grant, обмежений областю реєстрації, делеговані цій ідентичності gateway. 4. `gateway -> relay` - - Gateway зберігає relay handle і send grant із `push.apns.register`. - - Для `push.test`, пробуджень при повторному підключенні та сигналів пробудження gateway підписує запит на надсилання + - Gateway зберігає relay handle і send grant з `push.apns.register`. + - Для `push.test`, пробуджень перепідключення і wake nudges gateway підписує запит на надсилання власною ідентичністю пристрою. - - Relay перевіряє і збережений send grant, і підпис gateway відносно делегованої + - Relay перевіряє і збережений send grant, і підпис gateway щодо делегованої ідентичності gateway з реєстрації. - Інший gateway не може повторно використати цю збережену реєстрацію, навіть якщо якимось чином отримає handle. 5. `relay -> APNs` - - Relay володіє продакшн-обліковими даними APNs і необробленим APNs-токеном для офіційної збірки. - - Gateway ніколи не зберігає необроблений APNs-токен для relay-backed офіційних збірок. - - Relay надсилає фінальний push до APNs від імені сполученого gateway. + - Relay володіє production-обліковими даними APNs і сирим токеном APNs для офіційної збірки. + - Gateway ніколи не зберігає сирий токен APNs для relay-backed офіційних збірок. + - Relay надсилає фінальний push до APNs від імені pair-ованого gateway. -Чому було створено таку архітектуру: +Навіщо створено цей дизайн: -- Щоб не зберігати продакшн-облікові дані APNs на gateway користувача. -- Щоб не зберігати на gateway необроблені APNs-токени офіційних збірок. -- Щоб дозволити використання розміщеного relay лише для офіційних/TestFlight збірок OpenClaw. -- Щоб один gateway не міг надсилати push-пробудження на пристрої iOS, що належать іншому gateway. +- Щоб production-облікові дані APNs не потрапляли на шлюзи користувачів. +- Щоб не зберігати сирі токени APNs офіційних збірок на gateway. +- Щоб дозволити використання hosted relay лише для офіційних/TestFlight збірок OpenClaw. +- Щоб один gateway не міг надсилати push-пробудження на iOS-пристрої, що належать іншому gateway. -Локальні/ручні збірки й далі використовують прямий APNs. Якщо ви тестуєте такі збірки без relay, -gateway усе ще потребує прямих облікових даних APNs: +Локальні/ручні збірки й надалі використовують прямий APNs. Якщо ви тестуєте такі збірки без relay, +gateway, як і раніше, потребує прямих облікових даних APNs: ```bash export OPENCLAW_APNS_TEAM_ID="TEAMID" @@ -168,27 +168,43 @@ export OPENCLAW_APNS_KEY_ID="KEYID" export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)" ``` +Це env vars runtime на хості gateway, а не налаштування Fastlane. `apps/ios/fastlane/.env` зберігає лише +облікові дані App Store Connect / TestFlight, такі як `ASC_KEY_ID` і `ASC_ISSUER_ID`; він не налаштовує +пряму доставку APNs для локальних збірок iOS. + +Рекомендоване зберігання на хості gateway: + +```bash +mkdir -p ~/.openclaw/credentials/apns +chmod 700 ~/.openclaw/credentials/apns +mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8 +chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8 +export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8" +``` + +Не комітьте файл `.p8` і не розміщуйте його в checkout репозиторію. + ## Шляхи виявлення ### Bonjour (LAN) -Застосунок iOS переглядає `_openclaw-gw._tcp` у `local.` і, якщо налаштовано, той самий -домен wide-area DNS-SD. Gateway у тій самій LAN з’являються автоматично через `local.`; +iOS-застосунок шукає `_openclaw-gw._tcp` у `local.` і, якщо налаштовано, у тому самому +домені wide-area DNS-SD discovery. Gateway у тій самій LAN автоматично з’являються через `local.`; міжмережеве виявлення може використовувати налаштований wide-area домен без зміни типу beacon. -### Tailnet (міжмережеве) +### Tailnet (міжмережевий) Якщо mDNS заблоковано, використовуйте зону unicast DNS-SD (виберіть домен; приклад: `openclaw.internal.`) і Tailscale split DNS. -Приклад для CoreDNS див. у [Bonjour](/uk/gateway/bonjour). +Див. [Bonjour](/uk/gateway/bonjour) для прикладу CoreDNS. -### Ручне введення host/port +### Ручний host/port -У Settings увімкніть **Manual Host** і введіть host gateway + port (типово `18789`). +У Settings увімкніть **Manual Host** і введіть host шлюзу + port (типово `18789`). ## Canvas + A2UI -Вузол iOS відображає canvas у WKWebView. Використовуйте `node.invoke`, щоб керувати ним: +iOS-вузол рендерить canvas у WKWebView. Використовуйте `node.invoke`, щоб керувати ним: ```bash openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://:18789/__openclaw__/canvas/"}' @@ -196,10 +212,10 @@ openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"ur Примітки: -- Хост canvas у Gateway обслуговує `/__openclaw__/canvas/` і `/__openclaw__/a2ui/`. +- Canvas host Gateway обслуговує `/__openclaw__/canvas/` і `/__openclaw__/a2ui/`. - Він обслуговується HTTP-сервером Gateway (той самий port, що й `gateway.port`, типово `18789`). -- Вузол iOS автоматично переходить до A2UI при підключенні, коли оголошено URL хоста canvas. -- Повернутися до вбудованого каркаса можна через `canvas.navigate` і `{"url":""}`. +- iOS-вузол автоматично переходить до A2UI під час підключення, коли рекламується URL canvas host. +- Поверніться до вбудованого scaffold за допомогою `canvas.navigate` і `{"url":""}`. ### Canvas eval / snapshot @@ -211,20 +227,20 @@ openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaSc openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}' ``` -## Голосове пробудження + режим розмови +## Voice wake + talk mode -- Голосове пробудження та режим розмови доступні в Settings. -- iOS може призупиняти фонове аудіо; вважайте голосові функції режимом best-effort, коли застосунок неактивний. +- Voice wake і режим розмови доступні в Settings. +- iOS може призупиняти фонове аудіо; розглядайте голосові функції як best-effort, коли застосунок не активний. ## Поширені помилки -- `NODE_BACKGROUND_UNAVAILABLE`: переведіть застосунок iOS на передній план (команди canvas/camera/screen цього вимагають). -- `A2UI_HOST_NOT_CONFIGURED`: Gateway не оголосив URL хоста canvas; перевірте `canvasHost` у [конфігурації Gateway](/uk/gateway/configuration). -- Запит на сполучення так і не з’являється: виконайте `openclaw devices list` і підтвердьте вручну. -- Повторне підключення не вдається після перевстановлення: токен сполучення в Keychain було очищено; повторно сполучіть вузол. +- `NODE_BACKGROUND_UNAVAILABLE`: переведіть iOS-застосунок на передній план (команди canvas/camera/screen цього потребують). +- `A2UI_HOST_NOT_CONFIGURED`: Gateway не оголосив URL canvas host; перевірте `canvasHost` у [конфігурації Gateway](/uk/gateway/configuration). +- Запит pairing ніколи не з’являється: виконайте `openclaw devices list` і схваліть його вручну. +- Повторне підключення не працює після перевстановлення: токен pairing у Keychain було очищено; виконайте pairing вузла знову. -## Пов’язана документація +## Пов’язані документи -- [Сполучення](/uk/channels/pairing) -- [Виявлення](/uk/gateway/discovery) +- [Pairing](/uk/channels/pairing) +- [Discovery](/uk/gateway/discovery) - [Bonjour](/uk/gateway/bonjour) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index c811d19c9..1019dc2a7 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -2,16 +2,16 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви оновлюєте plugin до сучасної архітектури plugin - - Ви підтримуєте зовнішній plugin OpenClaw + - Ви оновлюєте плагін до сучасної архітектури плагінів OpenClaw + - Ви підтримуєте зовнішній плагін OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть із застарілого шару зворотної сумісності на сучасний plugin SDK +summary: Перехід із застарілого шару зворотної сумісності на сучасний Plugin SDK title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-06T04:11:07Z" + generated_at: "2026-04-06T15:30:56Z" model: gpt-5.4 provider: openai - source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33 + source_hash: 770eca214dcd7c7c22ee507d4bb4359b505a29c9ecd4458f7b5e1362c5cd0d6e source_path: plugins/sdk-migration.md workflow: 15 --- @@ -19,73 +19,65 @@ x-i18n: # Міграція Plugin SDK OpenClaw перейшов від широкого шару зворотної сумісності до сучасної -архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш plugin -було створено до появи нової архітектури, цей посібник допоможе вам виконати -міграцію. +архітектури плагінів із точковими, задокументованими імпортами. Якщо ваш плагін +було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система plugin надавала дві дуже широкі поверхні, які дозволяли plugin -імпортувати все потрібне з однієї точки входу: +Стара система плагінів надавала дві дуже широкі поверхні, які дозволяли плагінам імпортувати +все необхідне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував - десятки допоміжних засобів. Його було запроваджено, щоб старіші plugin на - основі hooks продовжували працювати, поки створювалася нова архітектура - plugin. -- **`openclaw/extension-api`** — міст, який надавав plugins прямий доступ до - допоміжних засобів на боці хоста, таких як вбудований запускальник агентів. +- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував десятки + допоміжних функцій. Його було запроваджено, щоб старі плагіни на основі hooks продовжували працювати, + поки будувалася нова архітектура плагінів. +- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до + допоміжних засобів на боці хоста, таких як вбудований виконавець агента. -Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, -але нові plugins не повинні їх використовувати, а наявні plugins мають -перейти з них до того, як у наступному мажорному релізі їх буде видалено. +Обидві поверхні тепер **застарілі**. Вони все ще працюють під час runtime, але нові +плагіни не повинні їх використовувати, а наявні плагіни слід перенести до того, як наступний +мажорний реліз їх прибере. - Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. - Plugins, які й далі імпортують із цих поверхонь, перестануть працювати, - коли це станеться. + Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних релізів. + Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. ## Чому це змінилося -Старий підхід спричиняв проблеми: +Старий підхід створював проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки - не пов’язаних між собою модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення - циклів імпорту -- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є - стабільними, а які — внутрішніми +- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних модулів +- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту +- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми -Сучасний plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим, самодостатнім модулем із чітким призначенням і задокументованим -контрактом. +Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні seams провайдерів для вбудованих каналів також зникли. -Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +Застарілі зручні seams провайдерів для вбудованих каналів також зникли. Імпорти +на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -допоміжні seams із брендуванням каналу та -`openclaw/plugin-sdk/telegram-core` були приватними скороченнями для mono-repo, -а не стабільними контрактами plugin. Натомість використовуйте вузькі -загальні subpaths SDK. Усередині робочого простору вбудованих plugin -залишайте допоміжні засоби, що належать провайдеру, у власному -`api.ts` або `runtime-api.ts` цього plugin. +канальні допоміжні seams із брендовими назвами та +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями mono-repo, а не +стабільними контрактами плагінів. Натомість використовуйте вузькі загальні subpath Plugin SDK. Усередині +workspace вбудованих плагінів зберігайте допоміжні засоби, що належать провайдеру, у власних +`api.ts` або `runtime-api.ts` цього плагіна. Поточні приклади вбудованих провайдерів: -- Anthropic зберігає допоміжні засоби потоку, специфічні для Claude, у - власному seam `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби моделей за - замовчуванням і конструктори realtime-провайдерів у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби onboarding/config +- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному seam `api.ts` / + `contract-api.ts` +- OpenAI зберігає builder-и провайдерів, допоміжні засоби типових моделей і builder-и realtime-провайдерів у власному `api.ts` +- OpenRouter зберігає builder провайдера та допоміжні засоби onboarding/config у власному + `api.ts` ## Як виконати міграцію - - Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані - wrapper-и Windows `.cmd`/`.bat` тепер безпечно завершуються помилкою, якщо - ви явно не передасте `allowShellFallback: true`. + + Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows + wrapper-и `.cmd`/`.bat` тепер аварійно завершуються із закритою помилкою, якщо ви явно не передасте + `allowShellFallback: true`. ```typescript // Before @@ -100,14 +92,13 @@ OpenClaw перейшов від широкого шару зворотної с }); ``` - Якщо ваш виклик не покладається навмисно на резервний перехід через shell, - не встановлюйте `allowShellFallback` і натомість обробляйте викинуту - помилку. + Якщо ваш викликаючий код навмисно не покладається на shell fallback, не задавайте + `allowShellFallback`, а натомість обробляйте викинуту помилку. - Знайдіть у своєму plugin імпорти з будь-якої із застарілих поверхонь: + Знайдіть у своєму плагіні імпорти з будь-якої із застарілих поверхонь: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -116,9 +107,8 @@ OpenClaw перейшов від широкого шару зворотної с - - Кожен експорт зі старої поверхні зіставляється з певним сучасним шляхом - імпорту: + + Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: ```typescript // Before (deprecated backwards-compatibility layer) @@ -134,8 +124,8 @@ OpenClaw перейшов від широкого шару зворотної с import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на боці хоста використовуйте впроваджений runtime - plugin замість прямого імпорту: + Для допоміжних засобів на боці хоста використовуйте вбудований runtime плагіна замість + прямого імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -146,8 +136,7 @@ OpenClaw перейшов від широкого шару зворотної с const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Той самий шаблон застосовується й до інших застарілих допоміжних засобів - bridge: + Той самий шаблон застосовується й до інших допоміжних засобів застарілого bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -157,7 +146,7 @@ OpenClaw перейшов від широкого шару зворотної с | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні засоби session store | `api.runtime.agent.session.*` | + | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | @@ -174,173 +163,173 @@ OpenClaw перейшов від широкого шару зворотної с | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий парасольковий повторний експорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Експорт кореневої схеми config | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цільові визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори статусу налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для етапу налаштування | Адаптери patch налаштування, безпечні для імпорту, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Допоміжні засоби інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку облікових записів/config/action-gate | + | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу плагіна | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/builders точок входу каналів | `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 для етапу налаштування | Безпечні для імпорту setup patch adapters, допоміжні засоби lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies | + | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби setup adapter | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/config/action-gate облікових записів | | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікового запису | Допоміжні засоби списку облікових записів/дій з обліковим записом | - | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви сполучення DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + індикатора набору | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів config | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Конструктори схем config | Типи схем config каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби config команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Відстеження статусу облікового запису | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + конструктора envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідної відповіді | Спільні допоміжні засоби запису та dispatch | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback до типового | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для облікових записів | Допоміжні засоби списку облікових записів / дій з обліковими записами | + | `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` | Налаштування префікса reply + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Factory для adapters конфігурації | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Builder-и схем конфігурації | Типи схем конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання опису, перевірка дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Розв’язання політик для груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Допоміжні засоби inbound envelope | Спільні допоміжні засоби побудови route + envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби inbound reply | Спільні допоміжні засоби record-and-dispatch | | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні засоби вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби ідентичності вихідних даних/send delegate | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Життєвий цикл прив’язки потоків і допоміжні засоби адаптера | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор media payload агента для застарілих макетів полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | - | `plugin-sdk/channel-send-result` | Типи результату send | Типи результату відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/встановлення plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime | Допоміжні засоби logger/env runtime, timeout, retry і backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime plugin | Допоміжні засоби plugin commands/hooks/http/interactive | - | `plugin-sdk/hook-runtime` | Допоміжні засоби pipeline hooks | Спільні допоміжні засоби pipeline webhook/internal hook | + | `plugin-sdk/outbound-media` | Допоміжні засоби outbound media | Спільне завантаження outbound media | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound runtime | Допоміжні засоби outbound identity/send delegate | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби thread-binding | Допоміжні засоби життєвого циклу та adapters thread-binding | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Builder payload медіа агента для застарілих layout полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | + | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів reply | + | `plugin-sdk/runtime-store` | Постійне сховище плагіна | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/plugin-install | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Logger/runtime env, timeout, retry та backoff helpers | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime плагінів | Допоміжні засоби commands/hooks/http/interactive для плагінів | + | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра hooks | Спільні допоміжні засоби конвеєра webhook/internal hook | | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби runtime CLI | Форматування команд, очікування, допоміжні засоби версії | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби gateway | Клієнт gateway і допоміжні засоби patch статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби config | Допоміжні засоби завантаження/запису config | + | `plugin-sdk/process-runtime` | Допоміжні засоби process | Спільні допоміжні засоби exec | + | `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби gateway | Клієнт gateway і допоміжні засоби patch status каналів | + | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби запиту approval | Payload approval для exec/plugin, допоміжні засоби capability/profile approval, нативні допоміжні засоби маршрутизації/runtime approval | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth approval | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Нативні допоміжні засоби profile/filter approval для exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Нативні адаптери capability/delivery approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Нативні допоміжні засоби прив’язки цілей/облікових записів approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval для exec/plugin | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, DM gating, external-content і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби runtime SSRF | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/approval-runtime` | Допоміжні засоби prompts погодження | Payload погодження exec/plugin, допоміжні засоби capability/profile погодження, native routing/runtime погодження | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth погодження | Розв’язання approver, auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта погодження | Native helpers профілю/фільтра погодження exec | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби delivery погодження | Native adapters capability/delivery погодження | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей погодження | Native helpers binding цілей/облікових записів погодження | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply погодження | Helpers payload reply для погодження exec/plugin | + | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні helpers довіри, DM gating, external-content та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Helpers allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Pinned-dispatcher, guarded fetch, helpers політики SSRF | | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичного gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, helpers графа помилок | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, proxy helpers | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, засоби запуску політик | + | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконувачі policy | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Мапування вхідних даних allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні засоби gating команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу | + | `plugin-sdk/allowlist-resolution` | Відображення входів allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Керування доступом до команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, helpers реєстру команд | + | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні засоби secret input | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів webhook | Утиліти цілей webhook | | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла webhook-запиту | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідний dispatch, heartbeat, планувальник відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch відповіді | Допоміжні засоби finalize + dispatch провайдера | - | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування reference відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk відповіді | Допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби session store | Допоміжні засоби шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів state і OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключа session | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації ключа session | - | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори зведень статусу каналу/облікового запису, типові значення runtime-state, допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілі | Спільні допоміжні засоби target resolver | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягування рядкових URL з request-подібних вхідних даних | - | `plugin-sdk/run-command` | Допоміжні засоби команд із таймером | Виконавець команд із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Зчитувачі параметрів | Загальні зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витягування send для tool | Витягування канонічних полів цілі send з аргументів tool | - | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби тимчасового шляху для завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби logging | Допоміжні засоби logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-table | Допоміжні засоби режиму таблиць markdown | - | `plugin-sdk/reply-payload` | Типи payload відповіді повідомлення | Типи payload відповіді | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | Допоміжні засоби виявлення/config self-hosted провайдера | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі допоміжні засоби виявлення/config self-hosted провайдера | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime провайдера | Допоміжні засоби визначення API key під час виконання | + | `plugin-sdk/reply-runtime` | Спільний runtime reply | Inbound dispatch, heartbeat, планувальник reply, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch reply | Helpers finalize + provider dispatch | + | `plugin-sdk/reply-history` | Допоміжні засоби історії reply | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань reply | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні засоби chunks reply | Допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Шлях сховища + helpers updated-at | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби state та OAuth dir | + | `plugin-sdk/routing` | Допоміжні засоби routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers нормалізації session-key | + | `plugin-sdk/status-helpers` | Допоміжні засоби стану каналів | Builder-и підсумку стану каналу/облікового запису, типові значення runtime-state, helpers метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби розв’язання цілей | Спільні helpers розв’язання цілей | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Helpers нормалізації slug/рядків | + | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягання рядкових URL із вхідних даних, подібних до запиту | + | `plugin-sdk/run-command` | Допоміжні засоби команд із таймерами | Виконавець команд із таймером і нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витягнення надсилання tool | Витягання канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні helpers шляхів для тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні засоби логування | Logger підсистеми та helpers редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби таблиць Markdown | Допоміжні засоби режиму таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload reply | + | `plugin-sdk/provider-setup` | Відібрані допоміжні засоби налаштування локальних/self-hosted провайдерів | Допоміжні засоби виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Точкові допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime-автентифікації провайдера | Допоміжні засоби runtime для розв’язання API key | | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API key провайдера | Допоміжні засоби onboarding/profile-write для API key | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth провайдера | Стандартний конструктор результату auth OAuth | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби результатів автентифікації провайдера | Стандартний builder результату OAuth-автентифікації | | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars auth провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/повторного відтворення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики повторного відтворення, допоміжні засоби endpoint провайдера та нормалізації model-id | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars автентифікації провайдера | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и policy replay, helpers endpoint провайдера та helpers нормалізації model-id | | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Patches onboarding провайдера | Допоміжні засоби config onboarding | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/config провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдера | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгортки потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Patch-и onboarding провайдера | Допоміжні засоби конфігурації onboarding | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Загальні helpers можливостей HTTP/endpoint провайдера | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Helpers реєстрації/кешу провайдера web-fetch | + | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Helpers реєстрації/кешу/конфігурації провайдера web-search | + | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності tools/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також helpers сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні засоби usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші helpers usage провайдера | + | `plugin-sdk/provider-stream` | Допоміжні засоби обгортки потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні helpers обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби fetch/transform/store медіа та конструктори media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдерів media understanding та експорти допоміжних засобів зображення/аудіо для провайдера | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби text/logging | - | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби speech | Типи провайдерів speech та експорти допоміжних засобів directives, registry і validation для провайдера | - | `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдерів speech, registry, directives, normalization | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи провайдерів і допоміжні засоби registry | - | `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи провайдерів і допоміжні засоби registry | - | `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` | Примітиви config каналу | Вузькі примітиви channel config-schema | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису config каналу | Допоміжні засоби авторизації запису config каналу | - | `plugin-sdk/channel-plugin-common` | Спільний прелюд каналу | Експорти спільного прелюду channel plugin | - | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби config allowlist | Допоміжні засоби редагування/читання config allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до групи | Спільні допоміжні засоби рішень щодо group-access | - | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard для direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей webhook | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляху webhook | Допоміжні засоби нормалізації шляху webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів plugin SDK | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби media | Допоміжні засоби отримання/перетворення/зберігання media плюс builder-и media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації media | Спільні helpers failover, вибір кандидатів і повідомлення про відсутню модель для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні засоби media understanding | Типи провайдера media understanding плюс provider-facing експорти helpers зображення/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення тексту, видимого асистенту, helpers рендерингу/chunking/table для markdown, helpers редагування, helpers тегів директив, утиліти безпечного тексту та пов’язані helpers тексту/логування | + | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжна функція chunking вихідного тексту | + | `plugin-sdk/speech` | Допоміжні засоби speech | Типи провайдерів speech плюс provider-facing helpers директив, реєстру й валідації | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдерів speech, реєстр, директиви, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи провайдера та helpers реєстру | + | `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи провайдера та helpers реєстру | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Helpers типів, failover, auth і реєстру для генерації зображень | + | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату для генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, helpers failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату для генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, helpers failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних reply | Нормалізація/зменшення payload інтерактивних reply | + | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude плагіна каналу | + | `plugin-sdk/channel-status` | Допоміжні засоби стану каналу | Спільні helpers snapshot/summary стану каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні helpers прийняття рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні helpers auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви passive-channel/status та ambient proxy helper | + | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей webhook | Реєстр цілей webhook і helpers встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів webhook | Допоміжні засоби нормалізації шляхів webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних media | + | `plugin-sdk/zod` | Повторний експорт zod | Повторно експортований `zod` для споживачів Plugin SDK | | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів memory manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти базового рушія хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Експорти рушія embedding хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Експорти рушія сховища хоста пам’яті | + | `plugin-sdk/memory-core-engine-runtime` | Runtime facade рушія пам’яті | Runtime facade індексу/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти foundation engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Експорти embedding engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD-рушій хоста пам’яті | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій зберігання хоста пам’яті | Експорти storage engine хоста пам’яті | | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | Мультимодальні допоміжні засоби хоста пам’яті | | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті | | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті | + | `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-core` | Базовий runtime хоста пам’яті | Допоміжні засоби core 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` | Фасад пошуку активної пам’яті | Лінивий фасад runtime search-manager активної пам’яті | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні helpers керованого markdown для плагінів, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Facade активного пошуку в пам’яті | Lazy facade runtime менеджера активного пошуку в пам’яті | + | `plugin-sdk/memory-host-status` | Псевдонім стану хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів стану хоста пам’яті | | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні засоби memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks | + | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестів і mocks | Ця таблиця навмисно містить поширену підмножину для міграції, а не повну -поверхню SDK. Повний список із понад 200 точок входу міститься у +поверхню SDK. Повний список із понад 200 entrypoints міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -У цьому списку все ще є деякі seams допоміжних засобів вбудованих plugin, -такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для -підтримки та сумісності вбудованих plugin, але навмисно не включені до -таблиці поширеної міграції й не є рекомендованою ціллю для нового коду plugin. +Цей список усе ще включає деякі допоміжні seams вбудованих плагінів, такі як +`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для +підтримки вбудованих плагінів і сумісності, але навмисно +опущені з таблиці поширеної міграції й не є рекомендованою ціллю для +нового коду плагінів. -Те саме правило застосовується до інших сімейств вбудованих допоміжних засобів, -таких як: +Те саме правило застосовується до інших сімейств вбудованих 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` +- helpers підтримки browser: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих допоміжних засобів/plugin, такі як `plugin-sdk/googlechat`, +- поверхні вбудованих helper/plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -349,40 +338,39 @@ OpenClaw перейшов від широкого шару зворотної с `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних -засобів токена `DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` наразі надає вузьку +поверхню token-helper `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете -знайти потрібний експорт, перегляньте вихідний код у `src/plugin-sdk/` або -запитайте в Discord. +Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти експорт, +перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. -## Часова шкала видалення +## Графік вилучення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні виводять попередження під час виконання | -| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні видають попередження під час runtime | +| **У наступному мажорному релізі** | Застарілі поверхні буде вилучено; плагіни, які все ще їх використовують, перестануть працювати | -Усі core plugins уже мігровано. Зовнішні plugins мають виконати міграцію +Усі core-плагіни вже мігровано. Зовнішнім плагінам слід виконати міграцію до наступного мажорного релізу. ## Тимчасове приглушення попереджень -Поки ви працюєте над міграцією, установіть ці змінні середовища: +Задайте ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий обхідний механізм, а не постійне рішення. +Це тимчасовий запасний вихід, а не постійне рішення. ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin +- [Початок роботи](/uk/plugins/building-plugins) — створення вашого першого плагіна - [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins -- [Внутрішня будова Plugins](/uk/plugins/architecture) — глибоке занурення в архітектуру -- [Маніфест Plugin](/uk/plugins/manifest) — довідник зі схеми маніфесту +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів +- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів +- [Внутрішня будова плагінів](/uk/plugins/architecture) — детальний розбір архітектури +- [Маніфест плагіна](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index d7abea323..8dc2ebfc2 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - Вам потрібно знати, з якого підшляху SDK імпортувати - - Ви хочете мати довідник для всіх методів реєстрації в OpenClawPluginApi + - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-06T12:45:46Z" + generated_at: "2026-04-06T15:31:29Z" model: gpt-5.4 provider: openai - source_hash: e045097753f33d13d570f6ce5297d2a7c0f0ad8b31515d0d9021386c8004354c + source_hash: a08fa2d63e82ec921d63310eeede4ef868c452471402a55a1133deeaf78db0a8 source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є -довідником про **що імпортувати** і **що можна зареєструвати**. +Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка — +довідник про **що імпортувати** і **що можна реєструвати**. **Шукаєте практичний посібник?** - - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins) + - Плагін каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Плагін провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) ## Правило імпорту @@ -36,258 +36,257 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий, самодостатній модуль. Це забезпечує швидкий -запуск і запобігає проблемам із циклічними залежностями. Для специфічних для -каналів допоміжних функцій точки входу/збирання віддавайте перевагу -`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої umbrella-поверхні та спільних допоміжних функцій, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +запобігає проблемам із циклічними залежностями. Для специфічних для каналів +entry/build helper-ів віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої umbrella-поверхні та спільних helper-ів, таких як `buildChannelConfigSchema`. -Не додавайте і не використовуйте convenience-шви, названі на честь провайдерів, -такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +Не додавайте й не використовуйте convenience-seam-інтерфейси з назвами провайдерів, як-от +`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шви з брендингом каналів. Bundled plugins мають комбінувати загальні -підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці plugin-локальні barrel-файли, або додавати вузький -загальний контракт SDK, якщо потреба справді є міжканальною. +helper-seam-інтерфейси з брендуванням каналів. Вбудовані плагіни повинні комбінувати загальні +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core +має або використовувати ці локальні barrel-файли плагіна, або додавати вузький загальний контракт SDK, +коли потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір допоміжних швів для -bundled-plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Згенерована карта export-ів усе ще містить невеликий набір helper-seam-інтерфейсів для вбудованих плагінів, +таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для підтримки bundled-plugin і сумісності; їх навмисно -не включено до спільної таблиці нижче, і вони не є рекомендованим шляхом -імпорту для нових сторонніх plugins. +підшляхи існують лише для підтримки вбудованих плагінів і сумісності; вони +навмисно не включені до загальної таблиці нижче й не є рекомендованим +шляхом імпорту для нових сторонніх плагінів. ## Довідник підшляхів Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи bundled-plugin усе ще з’являються в цьому -згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності, -якщо лише якась сторінка документації явно не оголошує один із них публічним. +Зарезервовані helper-підшляхи вбудованих плагінів усе ще з’являються в цьому згенерованому списку. +Розглядайте їх як деталі реалізації/поверхні сумісності, якщо лише сторінка документації +явно не просуває якийсь із них як публічний. -### Точка входу plugin +### Точка входу плагіна -| Підшлях | Ключові експорти | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Subpath | Key exports | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | | `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` | Спільні helper-и майстра налаштування, запити 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` | Допоміжні функції багатoакаунтної конфігурації/керування обмеженнями дій, допоміжні функції fallback для акаунта за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації account-id | - | `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні функції fallback за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції списків акаунтів/дій над акаунтами | + | `plugin-sdk/account-core` | Helper-и багатoоблікової конфігурації/action-gate і helper-и резервного повернення до типового облікового запису | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper-и нормалізації account-id | + | `plugin-sdk/account-resolution` | Пошук облікового запису + helper-и резервного повернення до типового | + | `plugin-sdk/account-helpers` | Вузькі helper-и списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із fallback на bundled-contract | + | `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Helper-и нормалізації/валідації кастомних команд Telegram із резервною підтримкою вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції вхідних маршрутів + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису й диспетчеризації вхідних подій | - | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні функції вихідної ідентичності/делегата надсилання | - | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл thread-binding і допоміжні функції адаптера | - | `plugin-sdk/agent-media-payload` | Legacy-збирач медіапейлоада агента | - | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмови/thread, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція snapshot конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні функції розв’язання групової політики runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні функції snapshot/summary стану каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin | - | `plugin-sdk/allowlist-config-edit` | Допоміжні функції читання/редагування конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Спільні допоміжні функції auth/guard для direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/скорочення інтерактивного reply payload | - | `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, допоміжні функції envelope | - | `plugin-sdk/channel-send-result` | Типи результату reply | + | `plugin-sdk/inbound-envelope` | Спільні helper-и побудови вхідних маршрутів і envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні helper-и запису та диспетчеризації вхідних повідомлень | + | `plugin-sdk/messaging-targets` | Helper-и розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні helper-и завантаження вихідних медіа | + | `plugin-sdk/outbound-runtime` | Helper-и делегування вихідної ідентичності/надсилання | + | `plugin-sdk/thread-bindings-runtime` | Helper-и життєвого циклу та адаптерів прив’язок потоків | + | `plugin-sdk/agent-media-payload` | Застарілий builder медіапейлоада агента | + | `plugin-sdk/conversation-runtime` | Helper-и прив’язки розмови/потоку, pairing і налаштованих прив’язок | + | `plugin-sdk/runtime-config-snapshot` | Helper знімка конфігурації runtime | + | `plugin-sdk/runtime-group-policy` | Helper-и розв’язання групової політики runtime | + | `plugin-sdk/channel-status` | Спільні helper-и знімків/підсумків статусу каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу | + | `plugin-sdk/channel-config-writes` | Helper-и авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні експорти prelude для плагінів каналів | + | `plugin-sdk/allowlist-config-edit` | Helper-и читання/редагування конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні helper-и рішень доступу до груп | + | `plugin-sdk/direct-dm` | Спільні helper-и auth/guard для прямих DM | + | `plugin-sdk/interactive-runtime` | Helper-и нормалізації/скорочення інтерактивних payload-ів відповіді | + | `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, helper-и envelope | + | `plugin-sdk/channel-send-result` | Типи результатів відповіді | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/channel-targets` | Helper-и розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контракту каналу | - | `plugin-sdk/channel-feedback` | Зв’язування feedback/reaction | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime-розв’язання API-ключів для plugin провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні функції onboarding/запису профілю API-ключа, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для plugin провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища для auth провайдера | + | `plugin-sdk/provider-setup` | Кураторські helper-и налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Спеціалізовані helper-и налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI-бекендів + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Helper-и розв’язання API-ключів у runtime для плагінів провайдерів | + | `plugin-sdk/provider-auth-api-key` | Helper-и онбордингу/запису профілю API-ключів, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний builder результату OAuth-auth | + | `plugin-sdk/provider-auth-login` | Спільні helper-и інтерактивного входу для плагінів провайдерів | + | `plugin-sdk/provider-env-vars` | Helper-и пошуку env vars для auth провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі replay-policy, допоміжні функції endpoint провайдерів і нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, helper-и endpoint-ів провайдерів і helper-и нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування web-fetch провайдера | - | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/конфігурації web-search провайдера | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні функції wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні функції виправлення конфігурації onboarding | - | `plugin-sdk/global-singleton` | Допоміжні функції process-local singleton/map/cache | + | `plugin-sdk/provider-http` | Загальні helper-и HTTP/можливостей endpoint-ів провайдерів | + | `plugin-sdk/provider-web-fetch` | Helper-и реєстрації/кешування web-fetch провайдерів | + | `plugin-sdk/provider-web-search` | Helper-и реєстрації/кешування/конфігурації web-search провайдерів | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics, а також helper-и сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібне | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper-ів і спільні helper-и wrapper-ів для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Helper-и патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Helper-и process-local singleton/map/cache | - - | Підшлях | Ключові експорти | + + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, допоміжні функції авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання approver і auth дій у межах того самого чату | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції native exec approval profile/filter | - | `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні функції native approval target + account-binding | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply payload для approval exec/plugin | - | `plugin-sdk/command-auth-native` | Native command auth + допоміжні функції native session-target | - | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | - | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні функції поверхні команд | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper-и реєстру команд, helper-и авторизації відправника | + | `plugin-sdk/approval-auth-runtime` | Helper-и розв’язання того, хто схвалює, і action-auth у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Helper-и профілів/фільтрів native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval | + | `plugin-sdk/approval-native-runtime` | Helper-и цілей native approval + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Helper-и payload-ів відповіді для exec/plugin approval | + | `plugin-sdk/command-auth-native` | Native command auth + helper-и цілей native session | + | `plugin-sdk/command-detection` | Спільні helper-и виявлення команд | + | `plugin-sdk/command-surface` | Helper-и нормалізації тіла команди та command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, обмеження DM, зовнішнього контенту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватних мереж | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні функції розбору secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні функції webhook request/target | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла request/тайм-ауту | + | `plugin-sdk/security-runtime` | Спільні helper-и довіри, DM-gating, external-content і збирання секретів | + | `plugin-sdk/ssrf-policy` | Helper-и allowlist хостів і SSRF-політики приватних мереж | + | `plugin-sdk/ssrf-runtime` | Helper-и pinned-dispatcher, fetch із SSRF-захистом і SSRF-політики | + | `plugin-sdk/secret-input` | Helper-и розбору секретних входів | + | `plugin-sdk/webhook-ingress` | Helper-и webhook-запитів/цілей | + | `plugin-sdk/webhook-request-guards` | Helper-и розміру тіла запиту/timeout | - - | Підшлях | Ключові експорти | + + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні функції runtime/логування/резервних копій/встановлення plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/runtime` | Широкі helper-и runtime/logging/backup/встановлення плагінів | + | `plugin-sdk/runtime-env` | Вузькі helper-и env runtime, logger, timeout, retry і backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції plugin command/hook/http/interactive | - | `plugin-sdk/hook-runtime` | Спільні допоміжні функції webhook та внутрішнього hook pipeline | - | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy-імпорту/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні функції виконання process | - | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування та версій | - | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway і виправлення статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки дублікатів/конфліктів, навіть коли bundled Telegram contract surface недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні функції approval exec/plugin, збирачі approval-capability, auth/profile, native routing/runtime helpers | - | `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для inbound/reply, chunking, dispatch, heartbeat, планувальник reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize для reply | - | `plugin-sdk/reply-history` | Спільні допоміжні функції короткого вікна історії reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні helper-и команд/хуків/http/interactive для плагінів | + | `plugin-sdk/hook-runtime` | Спільні helper-и пайплайна webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Helper-и lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper-и exec процесів | + | `plugin-sdk/cli-runtime` | Helper-и форматування CLI, очікування та версій | + | `plugin-sdk/gateway-runtime` | Helper-и клієнта шлюзу та patch-ів статусу каналу | + | `plugin-sdk/config-runtime` | Helper-и завантаження/запису конфігурації | + | `plugin-sdk/telegram-command-config` | Helper-и нормалізації назв/описів команд Telegram і перевірок дублікатів/конфліктів, навіть коли surface вбудованого контракту Telegram недоступний | + | `plugin-sdk/approval-runtime` | Helper-и exec/plugin approval, builder-и approval-capability, helper-и auth/profile, helper-и native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні helper-и runtime для inbound/reply, chunking, dispatch, heartbeat, planner відповіді | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-и dispatch/finalize відповіді | + | `plugin-sdk/reply-history` | Спільні helper-и короткого вікна історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні функції шляху session store + updated-at | - | `plugin-sdk/state-paths` | Допоміжні функції шляхів до каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні функції route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні функції summary стану каналу/акаунта, типові значення runtime-state і допоміжні функції метаданих issues | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції розв’язання цілей | - | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних входів | - | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні функції subsystem logger і редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму markdown-таблиць | - | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису JSON-стану | - | `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні функції disk-backed dedupe cache | - | `plugin-sdk/acp-runtime` | Допоміжні функції ACP runtime/session і reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Зчитувач нечітких boolean-параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні функції bootstrap пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу та допоміжні функції статусу | - | `plugin-sdk/models-provider-runtime` | Допоміжні функції команд `/models` і reply провайдера | - | `plugin-sdk/skill-commands-runtime` | Допоміжні функції виведення списку skill-команд | - | `plugin-sdk/native-command-registry` | Допоміжні функції native command registry/build/serialize | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Допоміжні функції system event/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Допоміжні функції графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Обгорнуті допоміжні функції fetch, proxy і pinned lookup | - | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні функції dir/identity/workspace агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/reply-chunking` | Вузькі helper-и chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Helper-и шляхів сховища сесій + updated-at | + | `plugin-sdk/state-paths` | Helper-и шляхів для state/OAuth-каталогів | + | `plugin-sdk/routing` | Helper-и маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні helper-и підсумків статусу каналу/облікового запису, типові значення runtime-state і helper-и метаданих issue | + | `plugin-sdk/target-resolver-runtime` | Спільні helper-и розв’язання цілей | + | `plugin-sdk/string-normalization-runtime` | Helper-и нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів | + | `plugin-sdk/run-command` | Runner команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витяг канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні helper-и шляхів до тимчасових завантажень | + | `plugin-sdk/logging-core` | Helper-и subsystem logger і redaction | + | `plugin-sdk/markdown-table-runtime` | Helper-и режиму markdown-таблиць | + | `plugin-sdk/json-store` | Невеликі helper-и читання/запису стану JSON | + | `plugin-sdk/file-lock` | Re-entrant helper-и file-lock | + | `plugin-sdk/persistent-dedupe` | Helper-и дискового dedupe-кешу | + | `plugin-sdk/acp-runtime` | Helper-и runtime/сесій ACP і reply-dispatch | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента | + | `plugin-sdk/boolean-param` | Гнучкий читач boolean-параметрів | + | `plugin-sdk/dangerous-name-runtime` | Helper-и розв’язання збігів небезпечних назв | + | `plugin-sdk/device-bootstrap` | Helper-и device bootstrap і pairing token | + | `plugin-sdk/extension-shared` | Спільні примітиви helper-ів passive-channel, status і ambient proxy | + | `plugin-sdk/models-provider-runtime` | Helper-и відповіді команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Helper-и списку команд Skills | + | `plugin-sdk/native-command-registry` | Helper-и реєстру/build/serialize native command | + | `plugin-sdk/provider-zai-endpoint` | Helper-и визначення endpoint-ів Z.AI | + | `plugin-sdk/infra-runtime` | Helper-и системних подій/heartbeat | + | `plugin-sdk/collection-runtime` | Невеликі helper-и обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Helper-и diagnostic flag і event | + | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні helper-и класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Обгорнуті helper-и fetch, proxy і pinned lookup | + | `plugin-sdk/host-runtime` | Helper-и нормалізації hostname і SCP-хостів | + | `plugin-sdk/retry-runtime` | Helper-и конфігурації retry і runner-а retry | + | `plugin-sdk/agent-runtime` | Helper-и каталогу/ідентичності/workspace агента | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогу з опорою на конфігурацію | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа плюс збирачі media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа плюс експорти допоміжних функцій зображень/аудіо для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/логування, такі як видалення видимого для асистента тексту, рендер/chunking/table helpers для markdown, допоміжні функції редагування чутливих даних, тегів директив і safe-text utilities | - | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech-провайдера плюс експорти допоміжних функцій директив, реєстру та валідації для провайдерів | - | `plugin-sdk/speech-core` | Спільні типи speech-провайдера, реєстр, директиви та допоміжні функції нормалізації | - | `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі та допоміжні функції реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні функції реєстру | - | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції реєстру | - | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/webhook-targets` | Допоміжні функції реєстру webhook target і встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху webhook | - | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт `zod` для користувачів Plugin SDK | + | `plugin-sdk/media-runtime` | Спільні helper-и fetch/transform/store для медіа, а також builder-и медіапейлоадів | + | `plugin-sdk/media-generation-runtime` | Спільні helper-и failover для генерації медіа, вибір candidate-ів і повідомлення про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдерів media understanding і provider-facing експорти helper-ів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні helper-и тексту/markdown/logging, такі як видалення тексту, видимого асистенту, helper-и render/chunking/table для markdown, helper-и redaction, helper-и directive-tag і safe-text | + | `plugin-sdk/text-chunking` | Helper chunking для вихідного тексту | + | `plugin-sdk/speech` | Типи speech-провайдерів і provider-facing helper-и directive, registry і validation | + | `plugin-sdk/speech-core` | Спільні типи speech-провайдерів, helper-и registry, directive і normalization | + | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і helper-и registry | + | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і helper-и registry | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, helper-и failover, auth і registry | + | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, helper-и failover, пошук провайдера і розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, helper-и failover, пошук провайдера і розбір model-ref | + | `plugin-sdk/webhook-targets` | Helper-и реєстру цілей webhook і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Helper-и нормалізації шляхів webhook | + | `plugin-sdk/web-media` | Спільні helper-и завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Підшлях | Ключові експорти | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для менеджера/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексації/пошуку в пам’яті | + | `plugin-sdk/memory-core` | Поверхня helper-ів вбудованого memory-core для helper-ів manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти engine векторних подань хоста пам’яті | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції 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` | Допоміжні функції runtime CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних функцій core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних функцій журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції керованого markdown для plugins, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Активний runtime-фасад пам’яті для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних функцій статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні helper-и хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Helper-и запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Helper-и секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Helper-и журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Helper-и статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Helper-и CLI runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Helper-и core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Helper-и файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для helper-ів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для helper-ів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для helper-ів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні helper-и керованого markdown для плагінів, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Активний фасад runtime пам’яті для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для helper-ів статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня helper-ів вбудованого memory-lancedb | - - | Сімейство | Поточні підшляхи | Призначення | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin (`browser-support` лишається barrel-файлом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних функцій/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій bundled IRC | - | Допоміжні функції для конкретних каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні шви bundled-каналів | - | Допоміжні функції для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні шви bundled 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` | Helper-и підтримки вбудованого browser plugin (`browser-support` залишається barrel-файлом сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper-ів/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper-ів/runtime вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper-ів вбудованого IRC | + | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Поверхні сумісності/helper-ів вбудованих каналів | + | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Поверхні helper-ів вбудованих функцій/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | @@ -298,56 +297,57 @@ bundled-plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, ### Реєстрація можливостей -| Метод | Що реєструє | -| ----------------------------------------------- | ------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний backend CLI inference | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Двосторонні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Web search | +| Method | What it registers | +| ------------------------------------------------ | -------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerCliBackend(...)` | Локальний CLI-бекенд inference | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні сесії realtime voice | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що реєструє | -| ------------------------------ | -------------------------------------------- | +| Method | What it registers | +| ------------------------------- | ------------------------------------------------------ | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацьку команду (в оминання LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | ### Інфраструктура -| Метод | Що реєструє | -| --------------------------------------------- | ------------------------------------ | -| `api.registerHook(events, handler, opts?)` | Hook події | -| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway | -| `api.registerGatewayMethod(name, handler)` | Метод Gateway RPC | -| `api.registerCli(registrar, opts?)` | Підкоманду CLI | -| `api.registerService(service)` | Фоновий сервіс | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | +| Method | What it registers | +| ---------------------------------------------- | ------------------------------------------ | +| `api.registerHook(events, handler, opts?)` | Хук подій | +| `api.registerHttpRoute(params)` | HTTP-endpoint шлюзу | +| `api.registerGatewayMethod(name, handler)` | RPC-метод шлюзу | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний handler | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | -Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, -`wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin -намагається призначити методу gateway вужчу область доступу. Для методів, що -належать plugin, віддавайте перевагу специфічним для plugin префіксам. +Зарезервовані простори імен адміністрування core (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити +вужчий scope методу шлюзу. Віддавайте перевагу специфічним для плагіна префіксам для +методів, що належать плагіну. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: - `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, маршрутизації та лінивої реєстрації CLI plugin +- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої довідки CLI, + маршрутизації та lazy-реєстрації CLI плагіна -Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в -звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен -корінь команди верхнього рівня, що експонується цим registrar. +Якщо ви хочете, щоб команда плагіна залишалася lazy-loaded у звичайному шляху кореневого CLI, +надайте `descriptors`, які покривають кожен корінь команди верхнього рівня, що відкривається +цим registrar. ```typescript api.registerCli( @@ -359,7 +359,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -367,122 +367,122 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореня -CLI. Цей eager-шлях сумісності все ще підтримується, але він не встановлює -placeholder-и на основі descriptor для лінивого завантаження під час парсингу. +Використовуйте лише `commands`, тільки якщо вам не потрібна lazy-реєстрація кореневого CLI. +Цей eager-шлях сумісності все ще підтримується, але він не встановлює +placeholders на основі descriptor для lazy loading на етапі розбору. -### Реєстрація CLI backend +### Реєстрація CLI-бекенду -`api.registerCliBackend(...)` дає plugin змогу володіти типовою конфігурацією -локального backend AI CLI, такого як `codex-cli`. +`api.registerCliBackend(...)` дає плагіну змогу володіти типовою конфігурацією для локального +AI CLI-бекенду, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`. -- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх типової конфігурації plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після злиття (наприклад, для нормалізації старих форм прапорців). +- `id` бекенду стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`. +- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача як і раніше має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + типового значення плагіна перед запуском CLI. +- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування сумісності після злиття + (наприклад, нормалізація старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що реєструє | -| ----------------------------------------- | ----------------------------------- | -| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один) | -| `api.registerMemoryPromptSection(builder)` | Збирач розділу prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| Method | What it registers | +| ------------------------------------------ | ---------------------------------------- | +| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) | +| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding пам’яті +### Адаптери векторних подань пам’яті -| Метод | Що реєструє | -| --------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin | +| Method | What it registers | +| ---------------------------------------------- | --------------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер векторних подань пам’яті для активного плагіна | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` є ексклюзивними для plugins пам’яті. -- `registerMemoryEmbeddingProvider` дає активному plugin пам’яті змогу - реєструвати один або більше id адаптерів embedding (наприклад `openai`, - `gemini` або користувацький id, визначений plugin). -- Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, зіставляється з цими - зареєстрованими id адаптерів. + `registerMemoryRuntime` є ексклюзивними для плагінів пам’яті. +- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу реєструвати один + або кілька id адаптерів векторних подань (наприклад, `openai`, `gemini` або + користувацький id, визначений плагіном). +- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих + id адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| ------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| Method | What it does | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | | `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | ### Семантика рішень hook -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перехоплює dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропущений `cancel`), а не як перевизначення. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler заявляє про диспетчеризацію, handler-и з нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. ### Поля об’єкта API -| Поле | Тип | Опис | -| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія plugin (необов’язково) | -| `api.description` | `string?` | Опис plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела plugin | -| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для plugin, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Розв’язує шлях відносно кореня plugin | +| Field | Type | Description | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ | +| `api.id` | `string` | id плагіна | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний in-memory знімок runtime, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helper-и runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня плагіна | -## Внутрішня угода для модулів +## Угода щодо внутрішніх модулів -У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні runtime-експорти - index.ts # Точка входу plugin - setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) + runtime-api.ts # Лише внутрішні експорти runtime + index.ts # Точка входу плагіна + setup-entry.ts # Легка точка входу лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Facade-loaded публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні файли входу) тепер віддають -перевагу активному snapshot конфігурації runtime, якщо OpenClaw уже запущено. -Якщо snapshot runtime ще не існує, вони використовують fallback до розв’язаного -файла конфігурації на диску. +Facade-loaded публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер надають перевагу +активному знімку конфігурації runtime, коли OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до розв’язаного файла конфігурації на диску. -Plugins провайдерів також можуть експортувати вузький plugin-локальний contract -barrel, коли допоміжна функція навмисно є специфічною для провайдера і поки що -не належить до загального підшляху SDK. Поточний bundled-приклад: провайдер -Anthropic зберігає свої допоміжні функції потоків Claude у власному публічному -шві `api.ts` / `contract-api.ts` замість перенесення логіки Anthropic beta-header -і `service_tier` до загального контракту `plugin-sdk/*`. +Плагіни провайдерів також можуть відкривати вузький локальний barrel-контракт плагіна, коли +helper навмисно є специфічним для провайдера і поки що не належить до загального підшляху SDK. +Поточний вбудований приклад: провайдер Anthropic зберігає свої helper-и потоку Claude +у власному публічному seam `api.ts` / `contract-api.ts` замість того, щоб просувати логіку +Anthropic beta-header і `service_tier` у загальний контракт +`plugin-sdk/*`. -Інші поточні bundled-приклади: +Інші поточні вбудовані приклади: -- `@openclaw/openai-provider`: `api.ts` експортує builder-и провайдерів, - допоміжні функції моделей за замовчуванням і builder-и realtime-провайдерів +- `@openclaw/openai-provider`: `api.ts` експортує builder-и провайдера, + helper-и типових моделей і builder-и realtime-провайдерів - `@openclaw/openrouter-provider`: `api.ts` експортує builder провайдера та - допоміжні функції onboarding/конфігурації + helper-и онбордингу/конфігурації - Production-код extension також має уникати імпортів - `openclaw/plugin-sdk/`. Якщо допоміжна функція справді є - спільною, перенесіть її до нейтрального підшляху SDK, такого як - `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - capability-орієнтованої поверхні, замість жорсткого зв’язування двох plugins. + Production-код розширень також повинен уникати імпортів `openclaw/plugin-sdk/`. + Якщо helper справді є спільним, підніміть його до нейтрального підшляху SDK, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + surface, орієнтованої на можливості, замість того, щоб зв’язувати два плагіни між собою. ## Пов’язане @@ -490,6 +490,6 @@ Anthropic зберігає свої допоміжні функції поток - [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` - [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` - [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації -- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint -- [SDK Migration](/uk/plugins/sdk-migration) — міграція з застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура і модель можливостей +- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та lint-правила +- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих surface-інтерфейсів +- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей плагінів diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 9a0c9a784..efa255169 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,33 +1,33 @@ --- read_when: - Ви створюєте новий плагін постачальника моделей - - Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw - - Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime hooks + - Ви хочете додати до OpenClaw OpenAI-сумісний проксі або власну LLM + - Вам потрібно зрозуміти автентифікацію постачальників, каталоги та runtime hooks sidebarTitle: Provider Plugins summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw title: Створення плагінів постачальників x-i18n: - generated_at: "2026-04-06T12:45:52Z" + generated_at: "2026-04-06T15:31:24Z" model: gpt-5.4 provider: openai - source_hash: 89e7402742c87cb31265db1d98b34ca17ba57ad1c61952fa8c7da834306986f5 + source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Створення плагінів постачальників -Цей посібник пояснює, як створити плагін постачальника, який додає до OpenClaw -постачальника моделей (LLM). Наприкінці у вас буде постачальник із каталогом моделей, -автентифікацією через API key і динамічним визначенням моделей. +У цьому посібнику покроково розглядається створення плагіна постачальника, який додає до OpenClaw постачальника моделей +(LLM). Наприкінці ви матимете постачальника з каталогом моделей, +автентифікацією через API-ключ і динамічним визначенням моделей. - Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Початок роботи](/uk/plugins/building-plugins) для базової структури пакета - та налаштування маніфесту. + Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте + [Getting Started](/uk/plugins/building-plugins) про базову структуру + пакета й налаштування маніфесту. -## Покроковий розбір +## Покрокове проходження @@ -87,16 +87,16 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов’язковим - і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ID моделей + облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов'язковим + і дає змогу OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими id моделей на кшталт `acme-large` ще до появи runtime hooks. Якщо ви публікуєте постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build` - у `package.json` є обов’язковими. + обов'язкові в `package.json`. - Мінімальному постачальнику потрібні `id`, `label`, `auth` і `catalog`: + Мінімальний постачальник потребує `id`, `label`, `auth` і `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -171,9 +171,9 @@ x-i18n: `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією через API key - і одним runtime на основі каталогу, надавайте перевагу вужчому - хелперу `defineSingleProviderPluginEntry(...)`: + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з + автентифікацією через API-ключ і одним runtime на основі каталогу, віддавайте перевагу вужчому + допоміжному засобу `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -208,24 +208,24 @@ x-i18n: }); ``` - Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми та - типову модель агента під час onboarding, використовуйте preset-хелпери з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери: - `createDefaultModelPresetAppliers(...)`, + Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми й + типову модель агента під час онбордингу, використовуйте готові допоміжні засоби з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі допоміжні засоби — + це `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативний endpoint постачальника підтримує streamed usage blocks на - звичайному транспорті `openai-completions`, надавайте перевагу спільним хелперам каталогів із - `openclaw/plugin-sdk/provider-catalog-shared` замість жорстко закодованих перевірок `provider-id`. Функції - `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, тож - нативні endpoint у стилі Moonshot/DashScope також можуть підключатися, навіть якщо плагін використовує власний `provider id`. + Коли нативний endpoint постачальника підтримує блоки streamed usage на + звичайному transport `openai-completions`, віддавайте перевагу спільним допоміжним засобам каталогу з + `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко закодованим перевіркам + id постачальника. `supportsNativeStreamingUsageCompat(...)` і + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з мапи можливостей endpoint, тому нативні endpoint у стилі Moonshot/DashScope + також підключаються, навіть коли плагін використовує власний id постачальника. - Якщо ваш постачальник приймає довільні ID моделей (наприклад, проксі або маршрутизатор), + Якщо ваш постачальник приймає довільні id моделей (як проксі або маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -248,16 +248,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - попереднього прогріву — після його завершення `resolveDynamicModel` буде запущено знову. + прогрівання — `resolveDynamicModel` буде запущено знову після його завершення. - Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks - поступово, у міру того як цього вимагатиме ваш постачальник. + Більшості постачальників достатньо `catalog` + `resolveDynamicModel`. Додавайте hooks + поступово, у міру того як цього потребуватиме ваш постачальник. - Спільні builder-хелпери тепер охоплюють найтиповіші сімейства replay/tool-compat, - тому плагінам зазвичай не потрібно вручну підключати кожен hook окремо: + Спільні збирачі допоміжних засобів тепер покривають найпоширеніші сімейства replay/tool-compat, + тому плагінам зазвичай не потрібно вручну підключати кожен hook по одному: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -281,11 +281,11 @@ x-i18n: | Family | Що воно підключає | | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною перевіркою Gemini-turn там, де цього потребує транспорт | - | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель дійсно має Claude id | - | `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим tagged reasoning-output | - | `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну перевірку replay Gemini або переписування bootstrap | - | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для сумісних з OpenAI transport, включно з очищенням id викликів інструментів, виправленнями порядку assistant-first і загальною перевіркою ходів Gemini там, де це потрібно transport | + | `anthropic-by-model` | Політика replay з урахуванням Claude, вибрана за `modelId`, тому transport Anthropic-message отримують очищення thinking-блоків, специфічне для Claude, лише коли визначена модель справді має id Claude | + | `google-gemini` | Нативна політика replay Gemini плюс очищення bootstrap replay і режим виводу reasoning з тегами | + | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі transport; не вмикає нативну перевірку replay Gemini або переписування bootstrap | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов'язкове відкидання thinking-блоків лише для Claude залишається обмеженим стороною Anthropic | Реальні вбудовані приклади: @@ -299,13 +299,13 @@ x-i18n: | Family | Що воно підключає | | --- | --- | - | `google-thinking` | Нормалізація payload thinking Gemini на спільному stream-шляху | - | `kilocode-thinking` | Обгортка reasoning Kilo на спільному proxy stream-шляху, де `kilo/auto` і непідтримувані proxy reasoning id пропускають інжектований thinking | - | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot з конфігурації + рівня `/think` | - | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному stream-шляху | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution headers, `/fast`/`serviceTier`, text verbosity, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена типово, для постачальників на кшталт Z.AI, яким потрібен streaming інструментів, якщо його явно не вимкнено | + | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху stream | + | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху proxy stream, де для `kilo/auto` і id proxy reasoning, що не підтримуються, ін'єкція thinking пропускається | + | `moonshot-thinking` | Відображення payload нативного двійкового thinking Moonshot з конфігурації + рівня `/think` | + | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху stream | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, verbosity тексту, нативний вебпошук Codex, формування payload сумісності reasoning і керування контекстом Responses | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, де пропуски для моделей, що не підтримуються, і `auto` централізовано обробляються | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена типово, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнули явно | Реальні вбудовані приклади: @@ -318,23 +318,23 @@ x-i18n: - `zai`: `tool-stream-default-on` `openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств replay - плюс спільні хелпери, з яких ці сімейства побудовані. Поширені публічні експорти + разом зі спільними допоміжними засобами, з яких ці сімейства побудовані. Типові публічні експорти включають: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - спільні builder-и replay, такі як `buildOpenAICompatibleReplayPolicy(...)`, + - спільні збирачі replay, такі як `buildOpenAICompatibleReplayPolicy(...)`, `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` і `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - хелпери replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` + - допоміжні засоби replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` і `resolveTaggedReasoningOutputMode()` - - хелпери endpoint/model, такі як `resolveProviderEndpoint(...)`, + - допоміжні засоби для endpoint/моделей, такі як `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` надає і builder сімейства, і - публічні wrapper-хелпери, які ці сімейства повторно використовують. Поширені публічні експорти + `openclaw/plugin-sdk/provider-stream` надає і збирач сімейств, і + публічні допоміжні засоби обгорток, які ці сімейства повторно використовують. Типові публічні експорти включають: - `ProviderStreamFamily` @@ -349,49 +349,49 @@ x-i18n: - спільні proxy/provider-обгортки, такі як `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` і `createMinimaxFastModeWrapper(...)` - Деякі stream-хелпери навмисно залишаються локальними для постачальника. Поточний вбудований + Деякі stream-допоміжні засоби навмисно залишаються локальними для постачальника. Поточний вбудований приклад: `@openclaw/anthropic-provider` експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і - низькорівневі builder-и обгорток Anthropic зі свого публічного шва `api.ts` / - `contract-api.ts`. Ці хелпери залишаються специфічними для Anthropic, оскільки - вони також кодують обробку Claude OAuth beta і gating `context1m`. + низькорівневі збирачі обгорток Anthropic зі свого публічного шва `api.ts` / + `contract-api.ts`. Ці допоміжні засоби залишаються специфічними для Anthropic, оскільки + вони також кодують обробку бета-можливостей Claude OAuth і gating `context1m`. - Інші вбудовані постачальники також залишають transport-специфічні обгортки локальними, коли - цю поведінку неможливо чисто розділити між сімействами. Поточний приклад: вбудований + Інші вбудовані постачальники також зберігають transport-специфічні обгортки локальними, коли + цю поведінку не вдається чисто розділити між сімействами. Поточний приклад: вбудований плагін xAI зберігає нативне формування xAI Responses у власному `wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, типовим `tool_stream`, - очищенням непідтримуваних strict-tool і видаленням reasoning-payload, - специфічним для xAI. + очищенням strict-tool, що не підтримується, і видаленням + payload reasoning, специфічного для xAI. `openclaw/plugin-sdk/provider-tools` наразі надає одне спільне - сімейство tool-schema плюс спільні хелпери schema/compat: + сімейство схем інструментів разом зі спільними допоміжними засобами схем/сумісності: - - `ProviderToolCompatFamily` документує наявний перелік спільних сімейств. + - `ProviderToolCompatFamily` документує поточний перелік спільних сімейств. - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів. - `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)` - — це базові публічні хелпери схем Gemini. - - `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI: - `toolSchemaProfile: "xai"`, непідтримувані ключові слова схеми, нативну - підтримку `web_search` і декодування HTML-entity аргументів виклику інструментів. - - `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до - визначеної моделі до того, як вона потрапить до runner. + — це базові публічні допоміжні засоби для схем Gemini. + - `resolveXaiModelCompatPatch()` повертає вбудований патч сумісності xAI: + `toolSchemaProfile: "xai"`, ключові слова схем, що не підтримуються, нативну + підтримку `web_search` і декодування аргументів викликів інструментів з HTML-сутностей. + - `applyXaiModelCompat(model)` застосовує той самий патч сумісності xAI до + визначеної моделі перед тим, як вона потрапить до раннера. Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс - `contributeResolvedModelCompat`, щоб ці compat-метадані залишалися у - власності постачальника, а не були жорстко закодовані в core. + `contributeResolvedModelCompat`, щоб ці метадані сумісності залишалися у володінні + постачальника, а не жорстко кодувалися в core як правила xAI. - Такий самий шаблон package-root також підтримує інші вбудовані постачальники: + Той самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників: - - `@openclaw/openai-provider`: `api.ts` експортує builder-и постачальника, - хелпери типових моделей і builder-и realtime provider - - `@openclaw/openrouter-provider`: `api.ts` експортує builder - постачальника плюс хелпери onboarding/config + - `@openclaw/openai-provider`: `api.ts` експортує збирачі постачальника, + допоміжні засоби типових моделей і збирачі постачальника realtime + - `@openclaw/openrouter-provider`: `api.ts` експортує збирач постачальника + плюс допоміжні засоби для онбордингу/конфігурації - - Для постачальників, яким потрібен обмін токенами перед кожним викликом inference: + + Для постачальників, яким потрібен обмін токенів перед кожним викликом inference: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -404,8 +404,8 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні користувацькі заголовки запиту або модифікації тіла: + + Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -422,9 +422,9 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в - універсальних HTTP- або WebSocket-транспортах: + + Для постачальників, яким потрібні нативні заголовки або метадані + запиту/сеансу в загальних transport HTTP або WebSocket: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -444,8 +444,8 @@ x-i18n: }), ``` - - Для постачальників, які надають дані про використання/білінг: + + Для постачальників, які надають дані usage/білінгу: ```typescript resolveUsageAuth: async (ctx) => { @@ -460,79 +460,79 @@ x-i18n: - OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2–3: + OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2-3: | # | Hook | Коли використовувати | | --- | --- | --- | - | 1 | `catalog` | Каталог моделей або типові значення `base URL` | - | 2 | `applyConfigDefaults` | Глобальні типові значення, що належать постачальнику, під час матеріалізації конфігурації | - | 3 | `normalizeModelId` | Очищення псевдонімів застарілих/preview model id перед пошуком | + | 1 | `catalog` | Каталог моделей або типові значення base URL | + | 2 | `applyConfigDefaults` | Глобальні типові значення, якими володіє постачальник, під час materialization конфігурації | + | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів model-id перед пошуком | | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для config providers | - | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику | - | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або конфігураційного сценарію | - | 9 | `shouldDeferSyntheticProfileAuth` | Зниження пріоритету синтетичних placeholder-ів збереженого профілю відносно env/config auth | - | 10 | `resolveDynamicModel` | Приймати довільні upstream model ID | + | 6 | `applyNativeStreamingUsageCompat` | Переписування compat нативного streaming-usage для конфігурованих постачальників | + | 7 | `resolveConfigApiKey` | Визначення автентифікації через env-marker, яким володіє постачальник | + | 8 | `resolveSyntheticAuth` | Synthetic auth для local/self-hosted або на основі конфігурації | + | 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет synthetic placeholder збереженого профілю порівняно з env/config auth | + | 10 | `resolveDynamicModel` | Приймати довільні id моделей вище за потоком | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | - | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | + | 12 | `normalizeResolvedModel` | Переписування transport перед раннером | Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші - плагіни постачальників, здатні працювати з hooks, доки хтось із них справді не змінить конфігурацію. - Якщо жоден provider hook не перепише підтримуваний запис конфігурації сімейства Google, - усе одно застосовується вбудований normalizer конфігурації Google. - - `resolveConfigApiKey` використовує hook постачальника, якщо він доступний. Вбудований - шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, - навіть попри те, що runtime auth Bedrock і далі використовує типовий + - `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші + плагіни постачальників із підтримкою hook, доки один із них справді не змінить конфігурацію. + Якщо жоден hook постачальника не перепише підтримуваний запис конфігурації сімейства Google, + вбудований нормалізатор конфігурації Google усе одно застосовується. + - `resolveConfigApiKey` використовує hook постачальника, якщо той наданий. Вбудований + шлях `amazon-bedrock` також має тут вбудований AWS env-marker resolver, + хоча сама runtime-автентифікація Bedrock і далі використовує стандартний ланцюжок AWS SDK. - | 13 | `contributeResolvedModelCompat` | Compat-прапорці для вендорських моделей за іншим сумісним транспортом | - | 14 | `capabilities` | Застарілий статичний контейнер можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення tool-schema, що належить постачальнику, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика tool-schema, що належить постачальнику | - | 17 | `resolveReasoningOutputMode` | Tagged vs native контракт reasoning-output | + | 13 | `contributeResolvedModelCompat` | Прапорці compat для моделей постачальника за іншим сумісним transport | + | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | + | 15 | `normalizeToolSchemas` | Очищення схем інструментів, яким володіє постачальник, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика схем інструментів, якою володіє постачальник | + | 17 | `resolveReasoningOutputMode` | Контракт виводу reasoning з тегами чи нативний | | 18 | `prepareExtraParams` | Типові параметри запиту | - | 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn | - | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному stream-шляху | - | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS/cool-down | - | 23 | `formatApiKey` | Користувацька форма runtime-токена | - | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Рекомендації для відновлення автентифікації | - | 26 | `matchesContextOverflowError` | Визначення переповнення контексту, що належить постачальнику | - | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | - | 28 | `isCacheTtlEligible` | Gating TTL кешу prompt | - | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховати застарілі upstream-рядки | - | 31 | `augmentModelCatalog` | Синтетичні рядки forward-compat | - | 32 | `isBinaryThinking` | Бінарний thinking увімк./вимк. | + | 19 | `createStreamFn` | Повністю власний transport StreamFn | + | 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла на звичайному шляху stream | + | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного ходу | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сеансу WS/cool-down | + | 23 | `formatApiKey` | Власна форма runtime-токена | + | 24 | `refreshOAuth` | Власне оновлення OAuth | + | 25 | `buildAuthDoctorHint` | Підказка щодо відновлення автентифікації | + | 26 | `matchesContextOverflowError` | Виявлення переповнення, яким володіє постачальник | + | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, якою володіє постачальник | + | 28 | `isCacheTtlEligible` | Керування TTL кешу prompt | + | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Приховати застарілі рядки вище за потоком | + | 31 | `augmentModelCatalog` | Synthetic рядки сумісності вперед у каталозі | + | 32 | `isBinaryThinking` | Двійкове thinking увімк./вимк. | | 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` | | 34 | `resolveDefaultThinkingLevel` | Типова політика `/think` | - | 35 | `isModernModelRef` | Відповідність live/smoke моделей | - | 36 | `prepareRuntimeAuth` | Обмін токенами перед inference | - | 37 | `resolveUsageAuth` | Користувацький розбір облікових даних використання | - | 38 | `fetchUsageSnapshot` | Користувацький endpoint використання | - | 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для memory/search | - | 40 | `buildReplayPolicy` | Користувацька політика replay/compaction для транскриптів | + | 35 | `isModernModelRef` | Зіставлення live/smoke моделей | + | 36 | `prepareRuntimeAuth` | Обмін токенів перед inference | + | 37 | `resolveUsageAuth` | Власний парсинг облікових даних usage | + | 38 | `fetchUsageSnapshot` | Власний endpoint usage | + | 39 | `createEmbeddingProvider` | Адаптер embedding для memory/search, яким володіє постачальник | + | 40 | `buildReplayPolicy` | Власна політика replay/compaction transcript | | 41 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | - | 42 | `validateReplayTurns` | Сувора перевірка replay-turn перед вбудованим runner | - | 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) | + | 42 | `validateReplayTurns` | Сувора перевірка ходів replay перед вбудованим раннером | + | 43 | `onModelSelected` | Зворотний виклик після вибору (наприклад, телеметрія) | Примітка щодо налаштування prompt: - - `resolveSystemPromptContribution` дозволяє постачальнику інжектувати - cache-aware рекомендації для system prompt для сімейства моделей. Надавайте перевагу цьому hook над - `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі + - `resolveSystemPromptContribution` дає постачальнику змогу додавати + системні підказки з урахуванням кешу для сімейства моделей. Віддавайте цьому перевагу замість + `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделей і має зберігати стабільний/динамічний поділ кешу. - Докладні описи й реальні приклади див. у - [Внутрішні механізми: runtime hooks постачальника](/uk/plugins/architecture#provider-runtime-hooks). + Детальні описи й приклади з реального світу дивіться в + [Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks). - + Плагін постачальника може реєструвати speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch @@ -644,19 +644,24 @@ x-i18n: } ``` - OpenClaw класифікує це як плагін **гібридних можливостей**. Це - рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див. - [Внутрішні механізми: модель володіння можливостями](/uk/plugins/architecture#capability-ownership-model). + OpenClaw класифікує це як плагін **hybrid-capability**. Це + рекомендований шаблон для корпоративних плагінів (один плагін на постачальника). Дивіться + [Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model). - Для генерації відео надавайте перевагу показаній вище структурі можливостей з урахуванням режимів: - `generate`, `imageToVideo` і `videoToVideo`. Старі пласкі поля, такі - як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, усе ще працюють - як сукупні резервні ліміти, але не можуть так чисто описувати обмеження для окремих режимів або - вимкнені режими перетворення. + Для генерації відео віддавайте перевагу показаній вище структурі можливостей із урахуванням режимів: + `generate`, `imageToVideo` і `videoToVideo`. Плоскі агреговані поля на + кшталт `maxInputImages`, `maxInputVideos` і `maxDurationSeconds` + недостатні, щоб чисто оголошувати підтримку режимів перетворення або вимкнених режимів. + + Постачальники генерації музики мають дотримуватися того самого шаблону: + `generate` для генерації лише за prompt і `edit` для генерації + на основі еталонного зображення. Плоскі агреговані поля на кшталт `maxInputImages`, + `supportsLyrics` і `supportsFormat` недостатні для оголошення підтримки редагування; + очікуваним контрактом є явні блоки `generate` / `edit`. - + ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; @@ -691,7 +696,7 @@ x-i18n: -## Публікація в ClawHub +## Опублікуйте в ClawHub Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін: @@ -707,29 +712,29 @@ clawhub package publish your-org/your-plugin ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with providerAuthEnvVars +├── package.json # metadata openclaw.providers +├── openclaw.plugin.json # Маніфест із providerAuthEnvVars ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # Тести + └── usage.ts # Endpoint usage (необов'язково) ``` -## Довідник порядку каталогу +## Довідник щодо порядку каталогів -`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих +`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих постачальників: -| Order | Коли | Варіант використання | +| Порядок | Коли | Випадок використання | | --------- | ------------- | ----------------------------------------------- | -| `simple` | Перший прохід | Звичайні постачальники з API key | -| `profile` | Після simple | Постачальники, що залежать від auth profiles | -| `paired` | Після profile | Синтез кількох пов’язаних записів | -| `late` | Останній прохід | Перевизначення наявних постачальників (виграє при конфлікті) | +| `simple` | Перший прохід | Звичайні постачальники з API-ключем | +| `profile` | Після simple | Постачальники, обмежені профілями автентифікації | +| `paired` | Після profile | Синтезувати кілька пов'язаних записів | +| `late` | Останній прохід | Перевизначити наявних постачальників (виграє при колізії) | ## Наступні кроки -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал -- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent) -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath -- [Внутрішні механізми плагінів](/uk/plugins/architecture#provider-runtime-hooks) — деталі hooks і приклади вбудованих реалізацій +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал +- [SDK Runtime](/uk/plugins/sdk-runtime) — допоміжні засоби `api.runtime` (TTS, пошук, subagent) +- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник імпортів subpath +- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — подробиці про hooks і вбудовані приклади diff --git a/docs/uk/plugins/webhooks.md b/docs/uk/plugins/webhooks.md new file mode 100644 index 000000000..209130d78 --- /dev/null +++ b/docs/uk/plugins/webhooks.md @@ -0,0 +1,201 @@ +--- +read_when: + - Ви хочете запускати або керувати TaskFlows із зовнішньої системи + - Ви налаштовуєте вбудований плагін webhooks +summary: 'Плагін Webhooks: автентифікований вхід TaskFlow для довіреної зовнішньої автоматизації' +title: Плагін Webhooks +x-i18n: + generated_at: "2026-04-06T15:30:06Z" + model: gpt-5.4 + provider: openai + source_hash: a5da12a887752ec6ee853cfdb912db0ae28512a0ffed06fe3828ef2eee15bc9d + source_path: plugins/webhooks.md + workflow: 15 +--- + +# Webhooks (плагін) + +Плагін Webhooks додає автентифіковані HTTP-маршрути, які прив’язують зовнішню +автоматизацію до TaskFlows в OpenClaw. + +Використовуйте його, якщо хочете, щоб довірена система, така як Zapier, n8n, завдання CI або +внутрішній сервіс, створювала та керувала керованими TaskFlows без потреби спочатку писати +власний плагін. + +## Де він працює + +Плагін Webhooks працює всередині процесу Gateway. + +Якщо ваш Gateway працює на іншій машині, установіть і налаштуйте плагін на +цьому хості Gateway, а потім перезапустіть Gateway. + +## Налаштування маршрутів + +Установіть конфігурацію в `plugins.entries.webhooks.config`: + +```json5 +{ + plugins: { + entries: { + webhooks: { + enabled: true, + config: { + routes: { + zapier: { + path: "/plugins/webhooks/zapier", + sessionKey: "agent:main:main", + secret: { + source: "env", + provider: "default", + id: "OPENCLAW_WEBHOOK_SECRET", + }, + controllerId: "webhooks/zapier", + description: "Zapier bridge для TaskFlow", + }, + }, + }, + }, + }, + }, +} +``` + +Поля маршруту: + +- `enabled`: необов’язкове, типове значення — `true` +- `path`: необов’язкове, типове значення — `/plugins/webhooks/` +- `sessionKey`: обов’язковий сеанс, якому належать прив’язані TaskFlows +- `secret`: обов’язковий спільний секрет або SecretRef +- `controllerId`: необов’язковий ідентифікатор контролера для створених керованих потоків +- `description`: необов’язкова примітка для оператора + +Підтримувані варіанти `secret`: + +- Звичайний рядок +- SecretRef із `source: "env" | "file" | "exec"` + +Якщо маршрут на основі секрету не може визначити свій секрет під час запуску, плагін пропускає +цей маршрут і записує попередження в журнал замість того, щоб відкривати зламану кінцеву точку. + +## Модель безпеки + +Кожен маршрут вважається довіреним і діє з повноваженнями TaskFlow свого +налаштованого `sessionKey`. + +Це означає, що маршрут може перевіряти та змінювати TaskFlows, які належать цьому сеансу, тому +вам слід: + +- Використовувати сильний унікальний секрет для кожного маршруту +- Віддавати перевагу посиланням на секрети замість вбудованих plaintext-секретів +- Прив’язувати маршрути до найвужчого сеансу, який підходить для цього робочого процесу +- Відкривати лише конкретний шлях webhook, який вам потрібен + +Плагін застосовує: + +- Автентифікацію зі спільним секретом +- Обмеження розміру тіла запиту та таймаутів +- Обмеження частоти запитів із фіксованим вікном +- Обмеження кількості одночасних запитів у польоті +- Доступ до TaskFlow, прив’язаний до власника, через `api.runtime.taskFlow.bindSession(...)` + +## Формат запиту + +Надсилайте запити `POST` з такими параметрами: + +- `Content-Type: application/json` +- `Authorization: Bearer ` або `x-openclaw-webhook-secret: ` + +Приклад: + +```bash +curl -X POST https://gateway.example.com/plugins/webhooks/zapier \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer YOUR_SHARED_SECRET' \ + -d '{"action":"create_flow","goal":"Review inbound queue"}' +``` + +## Підтримувані дії + +Наразі плагін приймає такі значення JSON `action`: + +- `create_flow` +- `get_flow` +- `list_flows` +- `find_latest_flow` +- `resolve_flow` +- `get_task_summary` +- `set_waiting` +- `resume_flow` +- `finish_flow` +- `fail_flow` +- `request_cancel` +- `cancel_flow` +- `run_task` + +### `create_flow` + +Створює керований TaskFlow для сеансу, прив’язаного до маршруту. + +Приклад: + +```json +{ + "action": "create_flow", + "goal": "Review inbound queue", + "status": "queued", + "notifyPolicy": "done_only" +} +``` + +### `run_task` + +Створює кероване дочірнє завдання всередині наявного керованого TaskFlow. + +Дозволені runtime: + +- `subagent` +- `acp` + +Приклад: + +```json +{ + "action": "run_task", + "flowId": "flow_123", + "runtime": "acp", + "childSessionKey": "agent:main:acp:worker", + "task": "Inspect the next message batch" +} +``` + +## Форма відповіді + +Успішні відповіді повертають: + +```json +{ + "ok": true, + "routeId": "zapier", + "result": {} +} +``` + +Відхилені запити повертають: + +```json +{ + "ok": false, + "routeId": "zapier", + "code": "not_found", + "error": "TaskFlow not found.", + "result": {} +} +``` + +Плагін навмисно очищає метадані власника/сеансу з відповідей webhook. + +## Пов’язана документація + +- [SDK runtime плагінів](/uk/plugins/sdk-runtime) +- [Огляд hooks і webhooks](/uk/automation/hooks) +- [CLI webhooks](/cli/webhooks) diff --git a/docs/uk/providers/anthropic.md b/docs/uk/providers/anthropic.md index 340e96546..697b51dad 100644 --- a/docs/uk/providers/anthropic.md +++ b/docs/uk/providers/anthropic.md @@ -1,65 +1,52 @@ --- read_when: - Ви хочете використовувати моделі Anthropic в OpenClaw -summary: Використовуйте Anthropic Claude через API-ключі в OpenClaw +summary: Використання Anthropic Claude через API-ключі або Claude CLI в OpenClaw title: Anthropic x-i18n: - generated_at: "2026-04-06T12:45:07Z" + generated_at: "2026-04-06T15:30:39Z" model: gpt-5.4 provider: openai - source_hash: 6af35571debf5889b63e3b4f6a05aa4e046f39740287e6e1c492916ca00df44b + source_hash: 423928fd36c66729985208d4d3f53aff1f94f63b908df85072988bdc41d5cf46 source_path: providers/anthropic.md workflow: 15 --- # Anthropic (Claude) -Anthropic створює сімейство моделей **Claude** і надає доступ через API. -У OpenClaw для нового налаштування Anthropic слід використовувати API-ключ. Наявні legacy -профілі токенів Anthropic і далі підтримуються під час виконання, якщо вони вже -налаштовані. +Anthropic створює сімейство моделей **Claude** і надає доступ через API та +Claude CLI. В OpenClaw підтримуються як API-ключі Anthropic, так і повторне використання Claude CLI. +Наявні застарілі профілі токенів Anthropic, якщо вони вже налаштовані, і далі +враховуються під час виконання. -Для Anthropic в OpenClaw розподіл оплати такий: +Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож +OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї +інтеграції, якщо Anthropic не опублікує нову політику. -- **Anthropic API key**: звичайна оплата Anthropic API. -- **Claude subscription auth всередині OpenClaw**: Anthropic повідомила користувачам OpenClaw - **4 квітня 2026 року о 12:00 PT / 20:00 BST**, що це вважається - використанням стороннього harness і вимагає **Extra Usage** (оплата за фактом використання, - виставляється окремо від підписки). - -Наші локальні відтворення підтверджують цей поділ: - -- прямий `claude -p` усе ще може працювати -- `claude -p --append-system-prompt ...` може активувати захист Extra Usage, коли - prompt ідентифікує OpenClaw -- той самий системний prompt у стилі OpenClaw **не** відтворює блокування на - шляху Anthropic SDK + `ANTHROPIC_API_KEY` - -Тож практичне правило таке: **Anthropic API key або Claude subscription з -Extra Usage**. Якщо вам потрібен найзрозуміліший production-шлях, використовуйте Anthropic API -key. +Для довготривалих хостів gateway API-ключі Anthropic усе ще є найзрозумілішим і +найпередбачуванішим шляхом для production. Якщо ви вже використовуєте Claude CLI на хості, +OpenClaw може безпосередньо повторно використати цей вхід. Поточна публічна документація Anthropic: -- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) -- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) +- [Довідник CLI Claude Code](https://code.claude.com/docs/en/cli-reference) +- [Огляд Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) -- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) -- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) +- [Використання Claude Code з вашим планом Pro або Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) +- [Використання Claude Code з вашим планом Team або Enterprise](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) -Якщо вам потрібен найзрозуміліший шлях оплати, натомість використовуйте Anthropic API -key. -OpenClaw також підтримує інші варіанти у стилі підписки, зокрема [OpenAI +Якщо вам потрібен найзрозуміліший шлях виставлення рахунків, натомість використовуйте API-ключ Anthropic. +OpenClaw також підтримує інші варіанти на основі підписки, зокрема [OpenAI Codex](/uk/providers/openai), [Qwen Cloud Coding Plan](/uk/providers/qwen), [MiniMax Coding Plan](/uk/providers/minimax) і [Z.AI / GLM Coding Plan](/uk/providers/glm). -## Варіант A: Anthropic API key +## Варіант A: API-ключ Anthropic -**Найкраще для:** стандартного доступу до API та оплати за використання. -Створіть свій API key у Anthropic Console. +**Найкраще підходить для:** стандартного доступу до API і тарифікації за використанням. +Створіть API-ключ у Anthropic Console. ### Налаштування CLI @@ -71,7 +58,7 @@ openclaw onboard openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ``` -### Фрагмент config Anthropic +### Фрагмент конфігурації Anthropic ```json5 { @@ -82,8 +69,8 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ## Типові параметри thinking (Claude 4.6) -- Для моделей Anthropic Claude 4.6 в OpenClaw за замовчуванням використовується `adaptive` thinking, якщо явно не задано рівень thinking. -- Ви можете перевизначити його для кожного повідомлення (`/think:`) або в params моделі: +- Для моделей Anthropic Claude 4.6 в OpenClaw типовим значенням є `adaptive` thinking, якщо явний рівень thinking не задано. +- Ви можете перевизначити його для окремого повідомлення (`/think:`) або в параметрах моделі: `agents.defaults.models["anthropic/"].params.thinking`. - Пов’язана документація Anthropic: - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) @@ -91,11 +78,11 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ## Fast mode (Anthropic API) -Спільний перемикач `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, включно із запитами, автентифікованими через API key і OAuth, що надсилаються до `api.anthropic.com`. +Спільне перемикання `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, зокрема запити з автентифікацією через API-ключ і OAuth, надіслані до `api.anthropic.com`. -- `/fast on` відповідає `service_tier: "auto"` -- `/fast off` відповідає `service_tier: "standard_only"` -- Типове значення в config: +- `/fast on` зіставляється з `service_tier: "auto"` +- `/fast off` зіставляється з `service_tier: "standard_only"` +- Типове значення в конфігурації: ```json5 { @@ -114,22 +101,22 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" Важливі обмеження: - OpenClaw додає рівні сервісу Anthropic лише для прямих запитів до `api.anthropic.com`. Якщо ви маршрутизуєте `anthropic/*` через proxy або gateway, `/fast` не змінює `service_tier`. -- Явно задані params моделі Anthropic `serviceTier` або `service_tier` мають пріоритет над типовою поведінкою `/fast`, якщо задано обидва параметри. -- Anthropic повідомляє фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без доступної ємності Priority Tier значення `service_tier: "auto"` усе одно може зводитися до `standard`. +- Явні параметри моделі Anthropic `serviceTier` або `service_tier` перевизначають типове значення `/fast`, якщо встановлено обидва. +- Anthropic повідомляє про фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без місткості Priority Tier значення `service_tier: "auto"` усе одно може розв’язатися як `standard`. ## Кешування prompt (Anthropic API) -OpenClaw підтримує функцію кешування prompt від Anthropic. Це **лише API**; legacy Anthropic token auth не враховує параметри кешу. +OpenClaw підтримує функцію кешування prompt від Anthropic. Це **лише для API**; застаріла автентифікація токеном Anthropic не враховує параметри кешу. ### Конфігурація -Використовуйте параметр `cacheRetention` у config моделі: +Використовуйте параметр `cacheRetention` у конфігурації моделі: -| Value | Тривалість кешу | Опис | -| ------- | --------------- | ------------------------ | -| `none` | Без кешування | Вимкнути кешування prompt | -| `short` | 5 хвилин | Типово для auth через API Key | -| `long` | 1 година | Розширений кеш | +| Value | Тривалість кешу | Опис | +| ------- | -------------- | ---- | +| `none` | Без кешування | Вимкнути кешування prompt | +| `short` | 5 хвилин | Типово для автентифікації за API Key | +| `long` | 1 година | Розширений кеш | ```json5 { @@ -147,11 +134,11 @@ OpenClaw підтримує функцію кешування prompt від Anth ### Типові значення -Під час використання автентифікації через Anthropic API Key OpenClaw автоматично застосовує `cacheRetention: "short"` (5-хвилинний кеш) для всіх моделей Anthropic. Ви можете перевизначити це, явно задавши `cacheRetention` у своїй config. +Коли використовується автентифікація через API Key Anthropic, OpenClaw автоматично застосовує `cacheRetention: "short"` (5-хвилинний кеш) для всіх моделей Anthropic. Ви можете перевизначити це, явно встановивши `cacheRetention` у конфігурації. -### Перевизначення `cacheRetention` для окремого agent +### Перевизначення cacheRetention для окремого агента -Використовуйте params на рівні моделі як базовий рівень, а потім перевизначайте конкретних agent через `agents.list[].params`. +Використовуйте params на рівні моделі як базовий рівень, а потім перевизначайте конкретних агентів через `agents.list[].params`. ```json5 { @@ -172,22 +159,22 @@ OpenClaw підтримує функцію кешування prompt від Anth } ``` -Порядок злиття config для параметрів, пов’язаних із кешем: +Порядок злиття конфігурації для параметрів, пов’язаних із кешем: 1. `agents.defaults.models["provider/model"].params` -2. `agents.list[].params` (відповідний `id`, перевизначення за ключем) +2. `agents.list[].params` (для відповідного `id`, перевизначає за ключем) -Це дає змогу одному agent зберігати довготривалий кеш, а іншому agent на тій самій моделі вимикати кешування, щоб уникнути витрат на запис для імпульсного трафіку або трафіку з низьким повторним використанням. +Це дає змогу одному агенту зберігати довготривалий кеш, тоді як інший агент на тій самій моделі вимикає кешування, щоб уникнути витрат на запис для імпульсного трафіку з низьким повторним використанням. ### Примітки щодо Bedrock Claude -- Моделі Anthropic Claude на Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо це налаштовано. -- Для моделей Bedrock не від Anthropic під час виконання примусово встановлюється `cacheRetention: "none"`. +- Моделі Anthropic Claude на Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо її налаштовано. +- Для моделей Bedrock, що не належать Anthropic, під час виконання примусово встановлюється `cacheRetention: "none"`. - Розумні типові значення Anthropic API-key також встановлюють `cacheRetention: "short"` для посилань на моделі Claude-on-Bedrock, якщо явне значення не задано. ## Вікно контексту 1M (бета Anthropic) -Вікно контексту Anthropic 1M доступне лише в beta. У OpenClaw його можна ввімкнути для кожної моделі окремо +Вікно контексту Anthropic 1M перебуває за beta-gate. В OpenClaw його можна ввімкнути для кожної моделі окремо через `params.context1m: true` для підтримуваних моделей Opus/Sonnet. ```json5 @@ -204,75 +191,62 @@ OpenClaw підтримує функцію кешування prompt від Anth } ``` -OpenClaw відображає це в `anthropic-beta: context-1m-2025-08-07` у запитах +OpenClaw зіставляє це з `anthropic-beta: context-1m-2025-08-07` у запитах Anthropic. -Це активується лише тоді, коли `params.context1m` явно встановлено в `true` для -цієї моделі. +Це активується лише тоді, коли для цієї моделі `params.context1m` явно встановлено в `true`. -Вимога: Anthropic має дозволяти використання довгого контексту для цих облікових даних -(зазвичай це оплата через API key або шлях Claude-login / legacy token auth у OpenClaw -з увімкненим Extra Usage). Інакше Anthropic повертає: -`HTTP 429: rate_limit_error: Extra usage is required for long context requests`. +Вимога: Anthropic має дозволяти використання довгого контексту для цих облікових даних. -Примітка: наразі Anthropic відхиляє beta-запити `context-1m-*` під час використання -legacy Anthropic token auth (`sk-ant-oat-*`). Якщо ви налаштуєте -`context1m: true` з цим legacy режимом auth, OpenClaw запише попередження в журнал і -повернеться до стандартного вікна контексту, пропустивши beta-заголовок context1m, -зберігши при цьому обов’язкові OAuth beta. +Примітка: Anthropic наразі відхиляє бета-запити `context-1m-*` під час використання +застарілої автентифікації токеном Anthropic (`sk-ant-oat-*`). Якщо ви налаштуєте +`context1m: true` з цим застарілим режимом автентифікації, OpenClaw запише попередження в журнал і +повернеться до стандартного вікна контексту, пропустивши заголовок бета `context1m`, +але зберігши обов’язкові бета-заголовки OAuth. -## Видалено: backend Claude CLI +## Бекенд Claude CLI -Вбудований backend Anthropic `claude-cli` було видалено. +Вбудований бекенд Anthropic `claude-cli` підтримується в OpenClaw. -- У повідомленні Anthropic від 4 квітня 2026 року сказано, що трафік Claude-login, ініційований OpenClaw, - є використанням стороннього harness і вимагає **Extra Usage**. -- Наші локальні відтворення також показують, що прямий - `claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли - доданий prompt ідентифікує OpenClaw. -- Той самий системний prompt у стилі OpenClaw не активує цей захист на - шляху Anthropic SDK + `ANTHROPIC_API_KEY`. -- Для трафіку Anthropic в OpenClaw використовуйте Anthropic API keys. -- Якщо вам потрібен локальний резервний runtime на основі CLI, використовуйте інший підтримуваний CLI backend, - наприклад Codex CLI. Див. [/gateway/cli-backends](/gateway/cli-backends). +- Співробітники Anthropic повідомили нам, що таке використання знову дозволене. +- Тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` + санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- API-ключі Anthropic залишаються найзрозумілішим шляхом для production для постійно активних хостів gateway + та явного серверного контролю виставлення рахунків. +- Докладно про налаштування та виконання див. у [/gateway/cli-backends](/uk/gateway/cli-backends). ## Примітки -- Публічна документація Anthropic для Claude Code усе ще описує пряме використання CLI, наприклад - `claude -p`, але окреме повідомлення Anthropic для користувачів OpenClaw каже, що - шлях Claude-login у **OpenClaw** є використанням стороннього harness і вимагає - **Extra Usage** (оплата за фактом використання, окремо від підписки). - Наші локальні відтворення також показують, що прямий - `claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли - доданий prompt ідентифікує OpenClaw, тоді як той самий формат prompt не - відтворюється на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. Для production ми - натомість рекомендуємо Anthropic API keys. -- setup-token Anthropic знову доступний в OpenClaw як legacy/manual шлях. Повідомлення Anthropic про оплату, специфічне для OpenClaw, і далі застосовується, тож використовуйте його з розумінням, що Anthropic вимагає **Extra Usage** для цього шляху. -- Подробиці auth і правила повторного використання наведені в [/concepts/oauth](/uk/concepts/oauth). +- У публічній документації Anthropic про Claude Code усе ще описано пряме використання CLI, таке як + `claude -p`, а співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw + знову дозволене. Ми вважаємо ці вказівки остаточними, якщо Anthropic + не опублікує нову зміну політики. +- Anthropic setup-token залишається доступним в OpenClaw як підтримуваний шлях автентифікації токеном, але OpenClaw тепер надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. +- Докладно про автентифікацію та правила повторного використання див. у [/concepts/oauth](/uk/concepts/oauth). -## Усунення проблем +## Усунення неполадок -**Помилки 401 / токен раптово став невалідним** +**Помилки 401 / токен раптово недійсний** -- Legacy Anthropic token auth може завершитися або бути відкликаним. -- Для нового налаштування перейдіть на Anthropic API key. +- Автентифікація токеном Anthropic може сплинути або бути відкликана. +- Для нових налаштувань перейдіть на API-ключ Anthropic. -**Не знайдено API key для провайдера "anthropic"** +**Не знайдено API-ключ для постачальника "anthropic"** -- Auth є **для кожного agent окремо**. Нові agent не успадковують ключі головного agent. -- Повторно запустіть onboarding для цього agent або налаштуйте API key на хості +- Автентифікація є **для кожного агента окремо**. Нові агенти не успадковують ключі головного агента. +- Повторно запустіть onboarding для цього агента або налаштуйте API-ключ на хості gateway, а потім перевірте через `openclaw models status`. -**Не знайдено облікових даних для profile `anthropic:default`** +**Не знайдено облікових даних для профілю `anthropic:default`** -- Запустіть `openclaw models status`, щоб побачити, який auth profile активний. -- Повторно запустіть onboarding або налаштуйте API key для цього шляху profile. +- Виконайте `openclaw models status`, щоб побачити, який профіль автентифікації активний. +- Повторно запустіть onboarding або налаштуйте API-ключ для шляху цього профілю. -**Немає доступного auth profile (усі в cooldown/недоступні)** +**Немає доступного профілю автентифікації (усі в кулдауні/недоступні)** -- Перевірте `openclaw models status --json` на `auth.unusableProfiles`. -- Cooldown rate limit Anthropic може бути прив’язаним до моделі, тож споріднена модель Anthropic - усе ще може бути придатною, навіть коли поточна перебуває в cooldown. -- Додайте ще один profile Anthropic або дочекайтеся завершення cooldown. +- Перевірте `openclaw models status --json` для `auth.unusableProfiles`. +- Кулдауни rate-limit Anthropic можуть бути прив’язані до конкретної моделі, тож споріднена модель Anthropic + усе ще може бути придатною, навіть якщо поточна перебуває в кулдауні. +- Додайте інший профіль Anthropic або дочекайтеся завершення кулдауну. -Більше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/uk/help/faq). +Докладніше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/uk/help/faq). diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index dff830f1f..9f3dee9c5 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,41 +1,41 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете використовувати автентифікацію підписки Codex замість ключів API -summary: Використовуйте OpenAI через ключі API або підписку Codex в OpenClaw + - Ви хочете використовувати автентифікацію підписки Codex замість API keys +summary: Використовуйте OpenAI через API keys або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-06T00:33:55Z" + generated_at: "2026-04-06T15:31:20Z" model: gpt-5.4 provider: openai - source_hash: 9e04db5787f6ed7b1eda04d965c10febae10809fc82ae4d9769e7163234471f5 + source_hash: 736ad34671584665674515aee76e2670b14b22bb3cc0bf0ab3ae2388ac136598 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI надає API для розробників для моделей GPT. Codex підтримує **вхід через ChatGPT** для доступу за підпискою -або **вхід за ключем API** для доступу з оплатою за використання. Codex cloud вимагає входу через ChatGPT. -OpenAI явно підтримує використання OAuth підписки у зовнішніх інструментах/робочих процесах, таких як OpenClaw. +OpenAI надає API для розробників для моделей GPT. Codex підтримує **вхід через ChatGPT** для доступу +за підпискою або **вхід через API key** для доступу на основі використання. Codex cloud вимагає входу через ChatGPT. +OpenAI явно підтримує використання subscription OAuth у зовнішніх інструментах/робочих процесах, як-от OpenClaw. ## Стиль взаємодії за замовчуванням -OpenClaw може додавати невелике OpenAI-специфічне накладання prompt для запусків `openai/*` і -`openai-codex/*`. За замовчуванням це накладання зберігає стиль помічника теплим, -колаборативним, лаконічним, прямим і трохи емоційно виразнішим, +OpenClaw може додавати невелике накладання prompt, специфічне для OpenAI, як для запусків `openai/*`, так і +для `openai-codex/*`. За замовчуванням це накладання зберігає асистента теплим, +спільним, лаконічним, прямим і трохи емоційно виразнішим, не замінюючи базовий системний prompt OpenClaw. Дружнє накладання також -дозволяє час від часу використовувати emoji, коли це природно, водночас зберігаючи -загальний вивід лаконічним. +дозволяє час від часу використовувати emoji, коли це доречно, водночас +зберігаючи загальний вивід стислим. -Ключ конфігурації: +Ключ config: `plugins.entries.openai.config.personality` Дозволені значення: -- `"friendly"`: за замовчуванням; увімкнути OpenAI-специфічне накладання. -- `"off"`: вимкнути накладання та використовувати лише базовий prompt OpenClaw. +- `"friendly"`: значення за замовчуванням; увімкнути накладання, специфічне для OpenAI. +- `"off"`: вимкнути накладання й використовувати лише базовий prompt OpenClaw. Область дії: @@ -43,8 +43,8 @@ OpenClaw може додавати невелике OpenAI-специфічне - Застосовується до моделей `openai-codex/*`. - Не впливає на інших провайдерів. -Ця поведінка увімкнена за замовчуванням. Залиште `"friendly"` явно, якщо хочете, -щоб це пережило майбутні локальні зміни конфігурації: +Цю поведінку ввімкнено за замовчуванням. Явно залиште `"friendly"`, якщо хочете, щоб +це збереглося попри майбутні локальні зміни config: ```json5 { @@ -60,9 +60,9 @@ OpenClaw може додавати невелике OpenAI-специфічне } ``` -### Вимкнення OpenAI prompt-накладання +### Вимкнути накладання prompt OpenAI -Якщо ви хочете використовувати незмінений базовий prompt OpenClaw, встановіть для накладання значення `"off"`: +Якщо ви хочете немодифікований базовий prompt OpenClaw, установіть для накладання значення `"off"`: ```json5 { @@ -78,26 +78,32 @@ OpenClaw може додавати невелике OpenAI-специфічне } ``` -Ви також можете встановити це безпосередньо через CLI конфігурації: +Ви також можете встановити це безпосередньо через config CLI: ```bash openclaw config set plugins.entries.openai.config.personality off ``` -## Варіант A: ключ API OpenAI (OpenAI Platform) +## Варіант A: OpenAI API key (OpenAI Platform) -**Найкраще для:** прямого доступу до API та білінгу за використанням. -Отримайте свій ключ API на інформаційній панелі OpenAI. +**Найкраще для:** прямого доступу до API й білінгу на основі використання. +Отримайте свій API key у панелі керування OpenAI. + +Підсумок маршруту: + +- `openai/gpt-5.4` = прямий маршрут через API OpenAI Platform +- Потрібен `OPENAI_API_KEY` (або еквівалентний config провайдера OpenAI) +- В OpenClaw вхід через ChatGPT/Codex маршрутизується через `openai-codex/*`, а не через `openai/*` ### Налаштування CLI ```bash openclaw onboard --auth-choice openai-api-key -# або без взаємодії +# або неінтерактивно openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` -### Фрагмент конфігурації +### Фрагмент config ```json5 { @@ -106,14 +112,14 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" } ``` -У поточній документації моделей API OpenAI вказані `gpt-5.4` і `gpt-5.4-pro` для прямого -використання API OpenAI. OpenClaw пересилає обидві через шлях Responses `openai/*`. +У поточній документації OpenAI для моделей API наведено `gpt-5.4` і `gpt-5.4-pro` для прямого +використання OpenAI API. OpenClaw пересилає обидві через шлях Responses `openai/*`. OpenClaw навмисно приховує застарілий рядок `openai/gpt-5.3-codex-spark`, -оскільки прямі виклики API OpenAI відхиляють його в реальному трафіку. +оскільки прямі виклики OpenAI API відхиляють його в реальному трафіку. -OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху прямого API OpenAI. -`pi-ai` усе ще постачає вбудований рядок для цієї моделі, але реальні запити до API OpenAI -зараз її відхиляють. У OpenClaw Spark вважається доступним лише для Codex. +OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на прямому шляху +OpenAI API. `pi-ai` усе ще постачає вбудований рядок для цієї моделі, але реальні запити OpenAI API +наразі її відхиляють. В OpenClaw Spark вважається доступним лише для Codex. ## Генерація зображень @@ -124,7 +130,7 @@ OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху пря - Генерація: до 4 зображень на запит - Режим редагування: увімкнено, до 5 еталонних зображень - Підтримує `size` -- Поточне OpenAI-специфічне застереження: OpenClaw наразі не пересилає перевизначення `aspectRatio` або +- Поточне застереження, специфічне для OpenAI: OpenClaw наразі не пересилає перевизначення `aspectRatio` або `resolution` до OpenAI Images API Щоб використовувати OpenAI як провайдера зображень за замовчуванням: @@ -141,8 +147,8 @@ OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху пря } ``` -Див. [Генерація зображень](/uk/tools/image-generation) щодо параметрів спільного інструмента, -вибору провайдера та поведінки failover. +Див. [Image Generation](/uk/tools/image-generation) щодо спільних параметрів +інструмента, вибору провайдера та поведінки failover. ## Генерація відео @@ -150,12 +156,12 @@ OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху пря інструмент `video_generate`. - Модель відео за замовчуванням: `openai/sora-2` -- Режими: текст-у-відео, зображення-у-відео та потоки посилання/редагування одного відео -- Поточні обмеження: 1 зображення або 1 відео як вхідне посилання -- Поточне OpenAI-специфічне застереження: OpenClaw наразі пересилає лише перевизначення `size` - для нативної генерації відео OpenAI. Непідтримувані необов’язкові перевизначення, +- Режими: text-to-video, image-to-video і сценарії еталонного/редагування одного відео +- Поточні обмеження: 1 вхідне еталонне зображення або 1 відео +- Поточне застереження, специфічне для OpenAI: OpenClaw наразі пересилає лише перевизначення + `size` для нативної генерації відео OpenAI. Непідтримувані необов’язкові перевизначення, такі як `aspectRatio`, `resolution`, `audio` і `watermark`, ігноруються - і повертаються як попередження інструмента. + та повертаються як попередження інструмента. Щоб використовувати OpenAI як провайдера відео за замовчуванням: @@ -171,13 +177,19 @@ OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху пря } ``` -Див. [Генерація відео](/uk/tools/video-generation) щодо параметрів спільного інструмента, -вибору провайдера та поведінки failover. +Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів +інструмента, вибору провайдера та поведінки failover. ## Варіант B: підписка OpenAI Code (Codex) -**Найкраще для:** використання доступу за підпискою ChatGPT/Codex замість ключа API. -Codex cloud вимагає входу через ChatGPT, тоді як Codex CLI підтримує вхід через ChatGPT або ключ API. +**Найкраще для:** використання доступу за підпискою ChatGPT/Codex замість API key. +Codex cloud вимагає входу через ChatGPT, тоді як Codex CLI підтримує вхід через ChatGPT або API key. + +Підсумок маршруту: + +- `openai-codex/gpt-5.4` = маршрут OAuth ChatGPT/Codex +- Використовує вхід через ChatGPT/Codex, а не прямий API key OpenAI Platform +- Обмеження на боці провайдера для `openai-codex/*` можуть відрізнятися від досвіду ChatGPT у вебверсії/застосунку ### Налаштування CLI (Codex OAuth) @@ -189,7 +201,7 @@ openclaw onboard --auth-choice openai-codex openclaw models auth login --provider openai-codex ``` -### Фрагмент конфігурації (підписка Codex) +### Фрагмент config (підписка Codex) ```json5 { @@ -197,41 +209,45 @@ openclaw models auth login --provider openai-codex } ``` -У поточній документації Codex від OpenAI вказано `gpt-5.4` як поточну модель Codex. OpenClaw -відображає її як `openai-codex/gpt-5.4` для використання через OAuth ChatGPT/Codex. +У поточній документації OpenAI для Codex `gpt-5.4` зазначено як поточну модель Codex. OpenClaw +зіставляє її з `openai-codex/gpt-5.4` для використання OAuth ChatGPT/Codex. -Якщо під час onboarding повторно використовується наявний вхід Codex CLI, ці облікові дані -і далі керуються Codex CLI. Після завершення строку дії OpenClaw спочатку повторно зчитує зовнішнє джерело Codex +Цей маршрут навмисно відокремлено від `openai/gpt-5.4`. Якщо вам потрібен +прямий шлях OpenAI Platform API, використовуйте `openai/*` з API key. Якщо вам потрібен +вхід через ChatGPT/Codex, використовуйте `openai-codex/*`. + +Якщо onboarding повторно використовує наявний вхід Codex CLI, ці облікові дані +надалі керуються Codex CLI. Після завершення строку дії OpenClaw спочатку знову зчитує зовнішнє джерело Codex і, коли провайдер може його оновити, записує оновлені облікові дані -назад до сховища Codex замість того, щоб брати їх під керування в окремій копії -лише для OpenClaw. +назад у сховище Codex замість того, щоб брати керування на себе в окремій +копії лише для OpenClaw. Якщо ваш обліковий запис Codex має право на Codex Spark, OpenClaw також підтримує: - `openai-codex/gpt-5.3-codex-spark` OpenClaw розглядає Codex Spark як доступний лише для Codex. Він не надає прямий -шлях за ключем API `openai/gpt-5.3-codex-spark`. +шлях API key `openai/gpt-5.3-codex-spark`. -OpenClaw також зберігає `openai-codex/gpt-5.3-codex-spark`, коли його виявляє `pi-ai`. -Розглядайте його як такий, що залежить від прав доступу, й експериментальний: Codex Spark -окремий від GPT-5.4 `/fast`, а доступність залежить від облікового запису Codex / -ChatGPT, під яким виконано вхід. +OpenClaw також зберігає `openai-codex/gpt-5.3-codex-spark`, коли `pi-ai` +його виявляє. Сприймайте його як залежний від entitlement та експериментальний: Codex Spark +відокремлений від GPT-5.4 `/fast`, а доступність залежить від облікового запису Codex / +ChatGPT, через який виконано вхід. -### Ліміт вікна контексту Codex +### Обмеження вікна контексту Codex -OpenClaw розглядає метадані моделі Codex і обмеження контексту під час виконання як окремі +OpenClaw розглядає метадані моделі Codex і runtime-обмеження контексту як окремі значення. Для `openai-codex/gpt-5.4`: - нативне `contextWindow`: `1050000` -- обмеження `contextTokens` під час виконання за замовчуванням: `272000` +- runtime-обмеження `contextTokens` за замовчуванням: `272000` -Це зберігає правдивість метаданих моделі, водночас залишаючи менше вікно за замовчуванням -під час виконання, яке на практиці має кращі характеристики затримки та якості. +Це зберігає правдивість метаданих моделі, водночас залишаючи менше runtime-вікно +за замовчуванням, яке на практиці має кращі характеристики затримки та якості. -Якщо ви хочете інше фактичне обмеження, задайте `models.providers..models[].contextTokens`: +Якщо вам потрібне інше ефективне обмеження, установіть `models.providers..models[].contextTokens`: ```json5 { @@ -250,45 +266,44 @@ OpenClaw розглядає метадані моделі Codex і обмеже } ``` -Використовуйте `contextWindow` лише тоді, коли ви оголошуєте або перевизначаєте нативні -метадані моделі. Використовуйте `contextTokens`, коли хочете обмежити бюджет контексту під час виконання. +Використовуйте `contextWindow` лише тоді, коли ви оголошуєте або перевизначаєте нативні метадані +моделі. Використовуйте `contextTokens`, коли хочете обмежити runtime-бюджет контексту. ### Транспорт за замовчуванням -OpenClaw використовує `pi-ai` для потокової передачі моделі. Для `openai/*` і -`openai-codex/*` транспорт за замовчуванням — `"auto"` (спочатку WebSocket, потім -резервний перехід на SSE). +OpenClaw використовує `pi-ai` для потокового передавання моделей. Для `openai/*`, і для +`openai-codex/*` транспорт за замовчуванням — `"auto"` (спочатку WebSocket, потім fallback +на SSE). -У режимі `"auto"` OpenClaw також повторює одну ранню придатну до повтору помилку WebSocket -перед переходом на SSE. Примусовий режим `"websocket"` і далі безпосередньо показує помилки транспорту -замість того, щоб приховувати їх за резервним переходом. +У режимі `"auto"` OpenClaw також повторює одну ранню придатну до повтору помилку WebSocket, +перш ніж перейти на SSE. Примусовий режим `"websocket"` все ще показує помилки транспорту безпосередньо, а не приховує їх за fallback. -Після помилки підключення або помилки WebSocket на ранньому ході в режимі `"auto"` OpenClaw позначає -шлях WebSocket для цього сеансу як деградований приблизно на 60 секунд і надсилає -наступні ходи через SSE під час охолодження замість безладного перемикання -між транспортами. +Після помилки WebSocket під час з’єднання або на ранньому ході в режимі `"auto"` OpenClaw позначає +шлях WebSocket цієї сесії як деградований приблизно на 60 секунд і надсилає +наступні ходи через SSE під час cooldown, замість того щоб безладно перемикатися між +транспортами. -Для нативних кінцевих точок сімейства OpenAI (`openai/*`, `openai-codex/*` і Azure -OpenAI Responses) OpenClaw також додає стабільний стан ідентичності сеансу та ходу -до запитів, щоб повтори, перепідключення та резервний перехід на SSE залишалися прив’язаними до тієї самої -ідентичності розмови. На нативних маршрутах сімейства OpenAI це включає стабільні заголовки -ідентичності запиту сеансу/ходу, а також відповідні метадані транспорту. +Для нативних endpoint OpenAI-сімейства (`openai/*`, `openai-codex/*` і Azure +OpenAI Responses) OpenClaw також додає стабільний стан ідентичності сесії та ходу +до запитів, щоб повторні спроби, перепідключення та fallback на SSE залишалися прив’язаними до тієї самої +ідентичності розмови. На нативних маршрутах OpenAI-сімейства це включає стабільні заголовки ідентичності запиту сесії/ходу та відповідні метадані транспорту. -OpenClaw також нормалізує лічильники використання OpenAI між варіантами транспорту перед тим, -як вони потрапляють до поверхонь сеансу/статусу. Нативний трафік OpenAI/Codex Responses може -повідомляти використання як `input_tokens` / `output_tokens` або -`prompt_tokens` / `completion_tokens`; OpenClaw розглядає їх як однакові лічильники -вхідних і вихідних токенів для `/status`, `/usage` і журналів сеансів. Коли нативний -трафік WebSocket не містить `total_tokens` (або повідомляє `0`), OpenClaw повертається до -нормалізованої суми вхідних і вихідних токенів, щоб відображення сеансу/статусу залишалися заповненими. +OpenClaw також нормалізує лічильники використання OpenAI для різних варіантів транспорту до того, +як вони потрапляють на поверхні сесії/статусу. Нативний трафік OpenAI/Codex Responses може +повідомляти про використання як `input_tokens` / `output_tokens` або +`prompt_tokens` / `completion_tokens`; OpenClaw трактує їх як однакові лічильники вхідних +і вихідних токенів для `/status`, `/usage` і журналів сесій. Коли нативний +трафік WebSocket не містить `total_tokens` (або повідомляє `0`), OpenClaw використовує +нормалізовану суму вхідних + вихідних токенів, щоб відображення сесії/статусу лишалися заповненими. -Ви можете задати `agents.defaults.models..params.transport`: +Ви можете встановити `agents.defaults.models..params.transport`: - `"sse"`: примусово використовувати SSE - `"websocket"`: примусово використовувати WebSocket - `"auto"`: спробувати WebSocket, потім перейти на SSE -Для `openai/*` (Responses API) OpenClaw також за замовчуванням увімкнув попередній прогрів WebSocket (`openaiWsWarmup: true`), коли використовується транспорт WebSocket. +Для `openai/*` (Responses API) OpenClaw також за замовчуванням вмикає warm-up WebSocket +(`openaiWsWarmup: true`), коли використовується транспорт WebSocket. Пов’язана документація OpenAI: @@ -312,12 +327,12 @@ OpenClaw також нормалізує лічильники використа } ``` -### Попередній прогрів OpenAI WebSocket +### Warm-up WebSocket OpenAI -У документації OpenAI попередній прогрів описано як необов’язковий. OpenClaw вмикає його за замовчуванням для +У документації OpenAI warm-up описано як необов’язковий. OpenClaw вмикає його за замовчуванням для `openai/*`, щоб зменшити затримку першого ходу при використанні транспорту WebSocket. -### Вимкнення попереднього прогріву +### Вимкнути warm-up ```json5 { @@ -335,7 +350,7 @@ OpenClaw також нормалізує лічильники використа } ``` -### Явне увімкнення попереднього прогріву +### Явно ввімкнути warm-up ```json5 { @@ -353,11 +368,11 @@ OpenClaw також нормалізує лічильники використа } ``` -### Пріоритетна обробка для OpenAI і Codex +### Пріоритетна обробка OpenAI і Codex API OpenAI надає пріоритетну обробку через `service_tier=priority`. У -OpenClaw задайте `agents.defaults.models["/"].params.serviceTier`, -щоб передавати це поле далі на нативні кінцеві точки OpenAI/Codex Responses. +OpenClaw установіть `agents.defaults.models["/"].params.serviceTier`, +щоб передати це поле далі на нативних endpoint OpenAI/Codex Responses. ```json5 { @@ -384,34 +399,34 @@ OpenClaw задайте `agents.defaults.models["/"].params.ser OpenClaw пересилає `params.serviceTier` як у прямі запити Responses `openai/*`, так і в запити Codex Responses `openai-codex/*`, коли ці моделі вказують -на нативні кінцеві точки OpenAI/Codex. +на нативні endpoint OpenAI/Codex. Важлива поведінка: -- прямий `openai/*` має бути спрямований на `api.openai.com` -- `openai-codex/*` має бути спрямований на `chatgpt.com/backend-api` -- якщо ви маршрутизуєте будь-якого з цих провайдерів через інший базовий URL або проксі, OpenClaw залишає `service_tier` без змін +- прямі `openai/*` мають бути націлені на `api.openai.com` +- `openai-codex/*` мають бути націлені на `chatgpt.com/backend-api` +- якщо ви маршрутизуєте будь-якого з провайдерів через інший base URL або proxy, OpenClaw залишає `service_tier` без змін ### Швидкий режим OpenAI -OpenClaw надає спільний перемикач швидкого режиму для сеансів `openai/*` і +OpenClaw надає спільний перемикач швидкого режиму як для сесій `openai/*`, так і для `openai-codex/*`: -- Chat/UI: `/fast status|on|off` -- Конфігурація: `agents.defaults.models["/"].params.fastMode` +- Чат/UI: `/fast status|on|off` +- Config: `agents.defaults.models["/"].params.fastMode` -Коли швидкий режим увімкнено, OpenClaw відображає його на пріоритетну обробку OpenAI: +Коли швидкий режим увімкнено, OpenClaw зіставляє його з пріоритетною обробкою OpenAI: - прямі виклики Responses `openai/*` до `api.openai.com` надсилають `service_tier = "priority"` - виклики Responses `openai-codex/*` до `chatgpt.com/backend-api` також надсилають `service_tier = "priority"` - наявні значення `service_tier` у payload зберігаються - швидкий режим не переписує `reasoning` або `text.verbosity` -Зокрема для GPT 5.4 найпоширеніше налаштування таке: +Для GPT 5.4 найпоширеніше налаштування таке: -- надіслати `/fast on` у сеансі, що використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4` -- або задати `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true` -- якщо ви також використовуєте Codex OAuth, задайте `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` також +- надішліть `/fast on` у сесії, що використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4` +- або встановіть `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true` +- якщо ви також використовуєте Codex OAuth, установіть `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` також Приклад: @@ -436,49 +451,49 @@ OpenClaw надає спільний перемикач швидкого реж } ``` -Перевизначення сеансу мають пріоритет над конфігурацією. Очищення перевизначення сеансу в UI Sessions -повертає сеанс до налаштованого значення за замовчуванням. +Перевизначення сесії мають пріоритет над config. Очищення перевизначення сесії в Sessions UI +повертає сесію до налаштованого значення за замовчуванням. -### Нативні OpenAI-маршрути проти OpenAI-сумісних маршрутів +### Нативні маршрути OpenAI порівняно з OpenAI-compatible -OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI -порівняно з типовими OpenAI-сумісними проксі `/v1`: +OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI +порівняно з універсальними OpenAI-compatible proxy `/v1`: - нативні маршрути `openai/*`, `openai-codex/*` і Azure OpenAI зберігають `reasoning: { effort: "none" }` без змін, коли ви явно вимикаєте reasoning -- для нативних маршрутів сімейства OpenAI схеми інструментів за замовчуванням працюють у strict mode +- нативні маршрути OpenAI-сімейства за замовчуванням використовують строгий режим для схем інструментів - приховані заголовки атрибуції OpenClaw (`originator`, `version` і `User-Agent`) додаються лише на перевірених нативних хостах OpenAI (`api.openai.com`) і нативних хостах Codex (`chatgpt.com/backend-api`) -- нативні маршрути OpenAI/Codex зберігають OpenAI-специфічне формування запиту, таке як - `service_tier`, `store` у Responses, OpenAI payload сумісності reasoning і - підказки для кешу prompt -- маршрути OpenAI-compatible у стилі проксі зберігають вільнішу поведінку сумісності й - не примушують strict-схеми інструментів, нативне формування запитів або приховані - заголовки атрибуції OpenAI/Codex +- нативні маршрути OpenAI/Codex зберігають формування запитів, специфічне для OpenAI, як-от + `service_tier`, Responses `store`, payload сумісності reasoning OpenAI і + підказки кешу prompt +- маршрути в стилі proxy OpenAI-compatible зберігають м’якшу поведінку сумісності й не + примушують до строгих схем інструментів, формування запитів лише для нативних маршрутів або прихованих + заголовків атрибуції OpenAI/Codex -Azure OpenAI залишається в категорії нативної маршрутизації щодо транспорту та -поведінки сумісності, але не отримує приховані заголовки атрибуції OpenAI/Codex. +Azure OpenAI залишається в категорії нативної маршрутизації для транспорту й поведінки сумісності, +але не отримує прихованих заголовків атрибуції OpenAI/Codex. -Це зберігає поточну поведінку нативного OpenAI Responses без примусового -накладання старих OpenAI-compatible shim на сторонні бекенди `/v1`. +Це зберігає поточну поведінку нативного OpenAI Responses, не нав’язуючи старі +OpenAI-compatible shim стороннім бекендам `/v1`. -### Серверна компактація OpenAI Responses +### Серверна compaction OpenAI Responses -Для прямих моделей OpenAI Responses (`openai/*`, що використовують `api: "openai-responses"` з -`baseUrl` на `api.openai.com`) OpenClaw тепер автоматично вмикає підказки payload для -серверної компактації OpenAI: +Для прямих моделей OpenAI Responses (`openai/*` з `api: "openai-responses"` і +`baseUrl` на `api.openai.com`) OpenClaw тепер автоматично вмикає серверні +підказки payload для compaction OpenAI: -- Примусово задає `store: true` (якщо compat моделі не задає `supportsStore: false`) -- Інжектує `context_management: [{ type: "compaction", compact_threshold: ... }]` +- Примусово встановлює `store: true` (якщо compat моделі не встановлює `supportsStore: false`) +- Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` За замовчуванням `compact_threshold` становить `70%` від `contextWindow` моделі (або `80000`, -якщо значення недоступне). +якщо він недоступний). -### Явне увімкнення серверної компактації +### Явно ввімкнути серверну compaction -Використовуйте це, коли хочете примусово інжектувати `context_management` для сумісних -моделей Responses (наприклад, Azure OpenAI Responses): +Використовуйте це, якщо хочете примусово впровадити `context_management` на сумісних +моделях Responses (наприклад Azure OpenAI Responses): ```json5 { @@ -496,7 +511,7 @@ Azure OpenAI залишається в категорії нативної ма } ``` -### Увімкнення з користувацьким порогом +### Увімкнути з власним порогом ```json5 { @@ -515,7 +530,7 @@ Azure OpenAI залишається в категорії нативної ма } ``` -### Вимкнення серверної компактації +### Вимкнути серверну compaction ```json5 { @@ -533,11 +548,11 @@ Azure OpenAI залишається в категорії нативної ма } ``` -`responsesServerCompaction` керує лише інжекцією `context_management`. -Прямі моделі OpenAI Responses і далі примусово задають `store: true`, якщо compat не встановлює +`responsesServerCompaction` керує лише впровадженням `context_management`. +Прямі моделі OpenAI Responses все одно примусово використовують `store: true`, якщо compat не встановлює `supportsStore: false`. ## Примітки - Посилання на моделі завжди використовують `provider/model` (див. [/concepts/models](/uk/concepts/models)). -- Докладно про автентифікацію та правила повторного використання — у [/concepts/oauth](/uk/concepts/oauth). +- Докладно про автентифікацію й правила повторного використання — у [/concepts/oauth](/uk/concepts/oauth). diff --git a/docs/uk/reference/api-usage-costs.md b/docs/uk/reference/api-usage-costs.md index 2861da220..9fc22fbb4 100644 --- a/docs/uk/reference/api-usage-costs.md +++ b/docs/uk/reference/api-usage-costs.md @@ -3,132 +3,133 @@ read_when: - Ви хочете зрозуміти, які функції можуть викликати платні API - Вам потрібно перевірити ключі, витрати та видимість використання - Ви пояснюєте звітування про витрати в /status або /usage -summary: Аудит того, що може витрачати гроші, які ключі використовуються та як переглядати використання -title: Використання API та витрати +summary: Перевірка того, що може витрачати кошти, які ключі використовуються і як переглядати використання +title: Використання API і витрати x-i18n: - generated_at: "2026-04-05T18:15:52Z" + generated_at: "2026-04-06T15:31:13Z" model: gpt-5.4 provider: openai - source_hash: 71789950fe54dcdcd3e34c8ad6e3143f749cdfff5bbc2f14be4b85aaa467b14c + source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd source_path: reference/api-usage-costs.md workflow: 15 --- -# Використання API та витрати +# використання API і витрати -У цьому документі перелічено **функції, які можуть викликати API-ключі**, і де відображаються їхні витрати. Він зосереджений на -функціях OpenClaw, які можуть генерувати використання провайдера або платні виклики API. +У цьому документі перелічено **функції, які можуть викликати API-ключі**, і де відображаються їхні витрати. Основна увага приділяється +функціям OpenClaw, які можуть генерувати використання постачальників або платні виклики API. ## Де відображаються витрати (чат + CLI) -**Знімок вартості для сесії** +**Знімок витрат для сеансу** -- `/status` показує поточну модель сесії, використання контексту та токени останньої відповіді. +- `/status` показує поточну модель сеансу, використання контексту та токени останньої відповіді. - Якщо модель використовує **автентифікацію через API-ключ**, `/status` також показує **орієнтовну вартість** останньої відповіді. -- Якщо метаданих живої сесії недостатньо, `/status` може відновити лічильники - токенів/кешу та мітку активної runtime-моделі з останнього запису використання в транскрипті. - Наявні ненульові live-значення все одно мають пріоритет, а загальні значення транскрипту - розміру prompt можуть перемагати, коли збережених загальних значень немає або вони менші. +- Якщо живі метадані сеансу неповні, `/status` може відновити лічильники + токенів/кешу та мітку активної runtime-моделі з останнього запису використання в transcript. + Наявні ненульові живі значення все одно мають пріоритет, а підсумки transcript розміру prompt + можуть перемагати, коли збережені підсумки відсутні або менші. -**Футер витрат для повідомлення** +**Нижній колонтитул витрат для повідомлення** -- `/usage full` додає футер використання до кожної відповіді, зокрема **орієнтовну вартість** (лише для API-ключа). -- `/usage tokens` показує лише токени; OAuth/token у стилі підписки та потоки CLI приховують грошову вартість. -- Примітка щодо Gemini CLI: коли CLI повертає JSON-вивід, OpenClaw зчитує використання з - `stats`, нормалізує `stats.cached` у `cacheRead` і за потреби виводить вхідні токени +- `/usage full` додає нижній колонтитул використання до кожної відповіді, зокрема **орієнтовну вартість** (лише для API-ключа). +- `/usage tokens` показує лише токени; потоки OAuth/токена та CLI у стилі підписки приховують вартість у доларах. +- Примітка про Gemini CLI: коли CLI повертає JSON-вивід, OpenClaw зчитує використання з + `stats`, нормалізує `stats.cached` у `cacheRead` і за потреби обчислює вхідні токени з `stats.input_tokens - stats.cached`. -Примітка щодо Anthropic: у публічній документації Claude Code від Anthropic усе ще зазначено, що пряме використання Claude -Code у терміналі входить до лімітів планів Claude. Окремо Anthropic повідомила користувачам OpenClaw, що починаючи з **4 квітня 2026 року о 12:00 PT / 20:00 BST**, шлях входу Claude через **OpenClaw** вважається використанням через сторонню оболонку і -вимагає **Extra Usage**, що оплачується окремо від підписки. Anthropic -не надає оцінку вартості за повідомлення, яку OpenClaw міг би показувати в -`/usage full`. +Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw +знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` +санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +Anthropic усе ще не надає оцінку вартості в доларах для окремого повідомлення, яку OpenClaw міг би +показувати в `/usage full`. -**Вікна використання CLI (квоти провайдерів)** +**Вікна використання CLI (квоти постачальника)** - `openclaw status --usage` і `openclaw channels list` показують **вікна використання** - провайдерів (знімки квот, а не витрати за повідомлення). -- Вивід для людини нормалізовано до формату `X% left` для всіх провайдерів. -- Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, + постачальника (знімки квот, а не витрати на окремі повідомлення). +- Зрозумілий для людини вивід нормалізується до `X% left` для всіх постачальників. +- Поточні постачальники вікон використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi і z.ai. -- Примітка щодо MiniMax: його сирі поля `usage_percent` / `usagePercent` означають залишок - квоти, тому OpenClaw інвертує їх перед відображенням. Поля на основі підрахунків усе одно мають пріоритет, - якщо вони є. Якщо провайдер повертає `model_remains`, OpenClaw віддає перевагу запису chat-моделі, - за потреби виводить мітку вікна з часових міток і включає назву моделі в мітку плану. -- Автентифікація для цих вікон квот надходить із хуків, специфічних для провайдера, коли вони доступні; - інакше OpenClaw використовує резервний варіант із відповідними OAuth/API-ключами - з auth profiles, env або config. +- Примітка щодо MiniMax: його сирі поля `usage_percent` / `usagePercent` означають + залишок квоти, тому OpenClaw інвертує їх перед показом. Поля на основі лічильників усе одно мають пріоритет, + якщо вони присутні. Якщо постачальник повертає `model_remains`, OpenClaw віддає перевагу запису моделі чату, + за потреби виводить мітку вікна з часових позначок і + включає назву моделі в мітку плану. +- Автентифікація використання для цих вікон квот надходить із хуків, специфічних для постачальника, коли вони доступні; + інакше OpenClaw повертається до відповідних облікових даних OAuth/API-ключа + з профілів автентифікації, env або config. -Докладніше та приклади див. у [Використання токенів і витрати](/reference/token-use). +Докладно та з прикладами див. [Token use & costs](/uk/reference/token-use). ## Як виявляються ключі -OpenClaw може підхоплювати облікові дані з: +OpenClaw може отримувати облікові дані з: -- **Auth profiles** (для кожного агента, зберігаються в `auth-profiles.json`). +- **Профілів автентифікації** (для кожного агента окремо, зберігаються в `auth-profiles.json`). - **Змінних середовища** (наприклад, `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`). -- **Config** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`, +- **Конфігурації** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`, `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`, `talk.providers.*.apiKey`). -- **Skills** (`skills.entries..apiKey`), які можуть експортувати ключі в env процесу Skill. +- **Skills** (`skills.entries..apiKey`), які можуть експортувати ключі в env процесу skill. ## Функції, які можуть витрачати ключі -### 1) Відповіді основної моделі (чат + інструменти) +### 1) Основні відповіді моделей (чат + інструменти) -Кожна відповідь або виклик інструмента використовує **поточного провайдера моделі** (OpenAI, Anthropic тощо). Це +Кожна відповідь або виклик інструмента використовує **поточного постачальника моделі** (OpenAI, Anthropic тощо). Це основне джерело використання та витрат. -Сюди також входять розміщені провайдери у стилі підписки, які все одно виставляють рахунки поза -локальним UI OpenClaw, як-от **OpenAI Codex**, **Alibaba Cloud Model Studio -Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** і -шлях входу Claude в Anthropic через OpenClaw з увімкненим **Extra Usage**. +Сюди також входять хостингові постачальники в стилі підписки, які все одно виставляють рахунки поза +локальним UI OpenClaw, наприклад **OpenAI Codex**, **Alibaba Cloud Model Studio +Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та +шлях входу Claude в Anthropic для OpenClaw з увімкненим **Extra Usage**. -Щодо конфігурації цін див. [Моделі](/providers/models), а щодо відображення — [Використання токенів і витрати](/reference/token-use). +Щодо конфігурації ціноутворення див. [Models](/uk/providers/models), а щодо відображення — [Token use & costs](/uk/reference/token-use). ### 2) Розуміння медіа (аудіо/зображення/відео) -Вхідні медіа можуть бути підсумовані/транскрибовані до запуску відповіді. Для цього використовуються API моделей/провайдерів. +Вхідні медіа можуть бути підсумовані/транскрибовані перед формуванням відповіді. Для цього використовуються API моделей/постачальників. - Аудіо: OpenAI / Groq / Deepgram / Google / Mistral. - Зображення: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI. - Відео: Google / Qwen / Moonshot. -Див. [Розуміння медіа](/uk/nodes/media-understanding). +Див. [Media understanding](/uk/nodes/media-understanding). ### 3) Генерація зображень і відео -Спільні можливості генерації також можуть витрачати ключі провайдерів: +Спільні можливості генерації також можуть витрачати ключі постачальників: - Генерація зображень: OpenAI / Google / fal / MiniMax - Генерація відео: Qwen -Генерація зображень може виводити типового провайдера з автентифікацією, якщо -`agents.defaults.imageGenerationModel` не задано. Для генерації відео наразі -потрібна явна `agents.defaults.videoGenerationModel`, наприклад +Генерація зображень може визначити типовий постачальник із підтримкою автентифікації, якщо +`agents.defaults.imageGenerationModel` не встановлено. Генерація відео зараз +вимагає явного `agents.defaults.videoGenerationModel`, наприклад `qwen/wan2.6-t2v`. -Див. [Генерація зображень](/tools/image-generation), [Qwen Cloud](/providers/qwen) -і [Моделі](/uk/concepts/models). +Див. [Image generation](/uk/tools/image-generation), [Qwen Cloud](/uk/providers/qwen) +і [Models](/uk/concepts/models). -### 4) Memory embeddings + семантичний пошук +### 4) Вбудовування пам’яті + семантичний пошук -Семантичний пошук у пам’яті використовує **API embedding'ів**, коли налаштовано віддалених провайдерів: +Семантичний пошук у пам’яті використовує **API вбудовувань**, коли для віддалених постачальників налаштовано: -- `memorySearch.provider = "openai"` → embedding'и OpenAI -- `memorySearch.provider = "gemini"` → embedding'и Gemini -- `memorySearch.provider = "voyage"` → embedding'и Voyage -- `memorySearch.provider = "mistral"` → embedding'и Mistral -- `memorySearch.provider = "ollama"` → embedding'и Ollama (локальні/self-hosted; зазвичай без тарифікації hosted API) -- Необов’язковий fallback на віддаленого провайдера, якщо локальні embedding'и не спрацюють +- `memorySearch.provider = "openai"` → вбудовування OpenAI +- `memorySearch.provider = "gemini"` → вбудовування Gemini +- `memorySearch.provider = "voyage"` → вбудовування Voyage +- `memorySearch.provider = "mistral"` → вбудовування Mistral +- `memorySearch.provider = "ollama"` → вбудовування Ollama (локально/self-hosted; зазвичай без тарифікації хостингового API) +- Необов’язковий перехід до віддаленого постачальника, якщо локальні вбудовування не спрацювали -Ви можете залишити все локально з `memorySearch.provider = "local"` (без використання API). +Можна повністю працювати локально з `memorySearch.provider = "local"` (без використання API). -Див. [Пам’ять](/uk/concepts/memory). +Див. [Memory](/uk/concepts/memory). -### 5) Інструмент web search +### 5) Інструмент вебпошуку -`web_search` може спричиняти витрати залежно від вашого провайдера: +`web_search` може спричиняти витрати за використання залежно від вашого постачальника: - **Brave Search API**: `BRAVE_API_KEY` або `plugins.entries.brave.config.webSearch.apiKey` - **Exa**: `EXA_API_KEY` або `plugins.entries.exa.config.webSearch.apiKey` @@ -137,66 +138,66 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** і - **Grok (xAI)**: `XAI_API_KEY` або `plugins.entries.xai.config.webSearch.apiKey` - **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY` або `plugins.entries.moonshot.config.webSearch.apiKey` - **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY` або `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web Search**: типово без ключа, але потребує доступного хоста Ollama плюс `ollama signin`; також може повторно використовувати звичайну Bearer-автентифікацію провайдера Ollama, коли хост цього вимагає +- **Ollama Web Search**: за замовчуванням без ключа, але потребує доступного хоста Ollama плюс `ollama signin`; також може повторно використовувати звичайну bearer-автентифікацію постачальника Ollama, якщо хост її вимагає - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` або `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**: `TAVILY_API_KEY` або `plugins.entries.tavily.config.webSearch.apiKey` -- **DuckDuckGo**: fallback без ключа (без тарифікації API, але неофіційний і на основі HTML) -- **SearXNG**: `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl` (без ключа/self-hosted; без тарифікації hosted API) +- **DuckDuckGo**: резервний варіант без ключа (без тарифікації API, але неофіційний і на основі HTML) +- **SearXNG**: `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl` (без ключа/self-hosted; без тарифікації хостингового API) -Застарілі шляхи провайдера `tools.web.search.*` усе ще завантажуються через тимчасовий compatibility shim, але вони більше не є рекомендованою поверхнею конфігурації. +Застарілі шляхи постачальників `tools.web.search.*` усе ще завантажуються через тимчасовий compatibility shim, але більше не є рекомендованою поверхнею конфігурації. -**Безкоштовний кредит Brave Search:** Кожен план Brave включає поновлюваний -безкоштовний кредит \$5/місяць. План Search коштує \$5 за 1 000 запитів, тож кредит покриває -1 000 запитів/місяць без оплати. Установіть ліміт використання в панелі Brave, +**Безплатний кредит Brave Search:** Кожен тарифний план Brave включає +відновлюваний безплатний кредит \$5 на місяць. План Search коштує \$5 за 1 000 запитів, тож цього кредиту достатньо для +1 000 запитів на місяць без оплати. Установіть свій ліміт використання в панелі Brave, щоб уникнути неочікуваних витрат. -Див. [Веб-інструменти](/tools/web). +Див. [Web tools](/uk/tools/web). -### 5) Інструмент web fetch (Firecrawl) +### 5) Інструмент веботримання (Firecrawl) -`web_fetch` може викликати **Firecrawl**, якщо наявний API-ключ: +`web_fetch` може викликати **Firecrawl**, якщо присутній API-ключ: - `FIRECRAWL_API_KEY` або `plugins.entries.firecrawl.config.webFetch.apiKey` -Якщо Firecrawl не налаштовано, інструмент використовує fallback на прямий fetch + readability (без платного API). +Якщо Firecrawl не налаштовано, інструмент повертається до прямого fetch + readability (без платного API). -Див. [Веб-інструменти](/tools/web). +Див. [Web tools](/uk/tools/web). -### 6) Знімки використання провайдера (status/health) +### 6) Знімки використання постачальника (status/health) -Деякі команди status викликають **endpoint'и використання провайдера**, щоб показати вікна квот або стан автентифікації. -Зазвичай це виклики невеликого обсягу, але вони все одно звертаються до API провайдерів: +Деякі команди status викликають **кінцеві точки використання постачальника**, щоб показати вікна квот або стан автентифікації. +Зазвичай це виклики з низьким обсягом, але вони все одно звертаються до API постачальників: - `openclaw status --usage` - `openclaw models status --json` -Див. [CLI моделей](/cli/models). +Див. [Models CLI](/cli/models). -### 7) Підсумовування для safeguard компактизації +### 7) Підсумовування захисту компактизації -Safeguard компактизації може підсумовувати історію сесії за допомогою **поточної моделі**, що -викликає API провайдера під час виконання. +Захист компактизації може підсумовувати історію сеансу за допомогою **поточної моделі**, що +викликає API постачальника під час виконання. -Див. [Керування сесіями + компактизація](/reference/session-management-compaction). +Див. [Session management + compaction](/uk/reference/session-management-compaction). ### 8) Сканування / probe моделей -`openclaw models scan` може виконувати probe моделей OpenRouter і використовує `OPENROUTER_API_KEY`, коли +`openclaw models scan` може виконувати probe моделей OpenRouter і використовує `OPENROUTER_API_KEY`, якщо probe увімкнено. -Див. [CLI моделей](/cli/models). +Див. [Models CLI](/cli/models). ### 9) Talk (мовлення) -Режим Talk може викликати **ElevenLabs**, якщо налаштовано: +Режим Talk може викликати **ElevenLabs**, якщо його налаштовано: - `ELEVENLABS_API_KEY` або `talk.providers.elevenlabs.apiKey` -Див. [Режим Talk](/uk/nodes/talk). +Див. [Talk mode](/uk/nodes/talk). ### 10) Skills (сторонні API) -Skills можуть зберігати `apiKey` у `skills.entries..apiKey`. Якщо Skill використовує цей ключ для зовнішніх -API, це може спричиняти витрати відповідно до провайдера цього Skill. +Skills можуть зберігати `apiKey` у `skills.entries..apiKey`. Якщо skill використовує цей ключ для зовнішніх +API, це може спричиняти витрати відповідно до постачальника цього skill. -Див. [Skills](/tools/skills). +Див. [Skills](/uk/tools/skills). diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 2b17247b9..8117178b4 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -4,47 +4,49 @@ read_when: summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-05T18:17:08Z" + generated_at: "2026-04-06T15:31:20Z" model: gpt-5.4 provider: openai - source_hash: 78390107a9ac2bdc4294d4d0204467c5efdd98faebaf308f3a4597ab966a6d26 + source_hash: f47eef441b9dc700b0f7182ebf1b494303cd1dab85aefdea414a0fae12f51963 source_path: reference/test.md workflow: 15 --- # Тести -- Повний набір інструментів тестування (набори, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (набори, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: завершує всі завислі процеси gateway, які утримують типовий контрольний порт, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, якщо попередній запуск gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: запускає набір unit-тестів із покриттям V8 (через `vitest.unit.config.ts`). Глобальні пороги становлять 70% для lines/branches/functions/statements. Покриття виключає entrypoint-и з великою часткою інтеграції (обв’язка CLI, мости gateway/telegram, статичний сервер webchat), щоб ціль залишалася зосередженою на логіці, придатній для unit-тестування. -- `pnpm test:coverage:changed`: запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: запускає нативну конфігурацію проєктів Vitest з `--changed origin/main`. Базова конфігурація розглядає файли проєктів/конфігурації як `forceRerunTriggers`, тому зміни в обв’язці за потреби все одно спричиняють ширший повторний запуск. -- `pnpm test`: напряму запускає нативну кореневу конфігурацію проєктів Vitest. Фільтри файлів нативно працюють у всіх налаштованих проєктах. -- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, із увімкненим спільним неізольованим runner-ом у конфігураціях репозиторію. +- `pnpm test:force`: Завершує будь-який завислий процес gateway, що утримує стандартний control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб server-тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: Запускає unit-набір із покриттям V8 (через `vitest.unit.config.ts`). Глобальні пороги становлять 70% для lines/branches/functions/statements. Із покриття виключено integration-heavy entrypoint-и (CLI wiring, мости gateway/telegram, статичний сервер webchat), щоб ціль залишалася сфокусованою на логіці, придатній для unit-тестування. +- `pnpm test:coverage:changed`: Запускає unit coverage лише для файлів, змінених відносно `origin/main`. +- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lanes, коли diff торкається лише routable source/test файлів. Зміни config/setup усе ще повертаються до нативного запуску root projects, щоб за потреби зміни wiring перевиконувалися широко. +- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped Vitest lanes, але все одно повертається до нативного запуску root projects, коли ви робите повний нетаргетований прогін. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lanes, які зберігають лише `test/setup.ts`, залишаючи runtime-heavy випадки на наявних lanes. +- Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lanes, щоб невеликі зміни helper-файлів не спричиняли повторний запуск важких наборів, прив’язаних до runtime. +- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, зі спільним non-isolated runner, увімкненим у всіх конфігураціях репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. - `pnpm test:extensions` запускає `vitest.extensions.config.ts`. -- `pnpm test:extensions`: запускає набори для extensions/plugins. -- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та деталізацію імпортів для нативного запуску кореневих проєктів. +- `pnpm test:extensions`: запускає набори extension/plugin. +- `pnpm test:perf:imports`: вмикає звітність Vitest про import-duration + import-breakdown, при цьому все ще використовує маршрутизацію scoped lanes для явних цілей файлів/каталогів. - `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`. - `pnpm test:perf:profile:main`: записує CPU-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: записує CPU- і heap-профілі для unit runner-а (`.artifacts/vitest-runner-profile`). -- Інтеграція gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (парування кількох екземплярів WS/HTTP/node). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`. -- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потрібні API-ключі та `LIVE=1` (або специфічний для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не вважається стабільним для CI так, як звичайні набори unit/e2e. -- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із наповненими даними та другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення про channel + permission у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP-кадри напряму, щоб smoke-тест відображав те, що міст справді надсилає. +- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`). +- Інтеграція gateway: opt-in через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: Запускає наскрізні smoke-тести gateway (multi-instance WS/HTTP/node pairing). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю worker-ів у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`. +- `pnpm test:live`: Запускає live-тести провайдерів (minimax/zai). Потребує API-ключів і `LIVE=1` (або специфічного для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. +- `pnpm test:docker:openwebui`: Запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксований чат через `/api/chat/completions`. Потребує придатного live-ключа моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не вважається стабільним для CI так, як звичайні unit/e2e-набори. +- `pnpm test:docker:mcp-channels`: Запускає seeded Gateway container і другий client container, який запускає `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих conversation, читання transcript, metadata attachment-ів, поведінку черги live events, маршрутизацію вихідного надсилання та сповіщення каналу + дозволів у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP frame-и безпосередньо, тож smoke відображає те, що міст фактично видає. ## Локальний PR gate -Для локальних перевірок land/gate PR запустіть: +Для локальних перевірок PR перед land/gate запустіть: - `pnpm check` - `pnpm build` - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` нестабільно працює на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` дає флейки на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` @@ -56,15 +58,15 @@ x-i18n: Використання: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` -- Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` -- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків чи додаткового тексту.” +- Необов’язкові env-змінні: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` +- Prompt за замовчуванням: “Reply with a single word: ok. No punctuation or extra text.” Останній запуск (2025-12-31, 20 запусків): - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) -## Бенч запуску CLI +## Бенч старту CLI Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -91,35 +93,35 @@ x-i18n: - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` - `all`: обидва preset-и -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення максимального RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, щоб вимірювання часу та збір профілів використовували однаковий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують профілі V8 для кожного запуску, щоб вимірювання часу і збирання профілів використовували один і той самий harness. -Умовні правила для збереженого виводу: +Умовні позначення для збереженого виводу: - `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` - `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює зафіксований у репозиторії baseline fixture у `test/fixtures/cli-startup-bench.json` з `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює baseline fixture, закомічений у `test/fixtures/cli-startup-bench.json`, з `runs=5` і `warmup=1` -Зафіксований у репозиторії fixture: +Fixture, закомічений у репозиторій: - `test/fixtures/cli-startup-bench.json` -- Оновити: `pnpm test:startup:bench:update` -- Порівняти поточні результати з fixture: `pnpm test:startup:bench:check` +- Оновлення через `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture через `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) -Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів. +Docker не є обов’язковим; це потрібно лише для containerized smoke-тестів онбордингу. -Повний cold-start-процес у чистому Linux-контейнері: +Повний cold-start потік у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`. -## Smoke-тест імпорту QR (Docker) +## QR import smoke (Docker) -Переконується, що `qrcode-terminal` завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісний Node 22): +Гарантує, що `qrcode-terminal` завантажується у підтримуваних Docker runtime Node (Node 24 за замовчуванням, Node 22 сумісний): ```bash pnpm test:docker:qr diff --git a/docs/uk/reference/token-use.md b/docs/uk/reference/token-use.md index 0a72fc2cb..92bbb461a 100644 --- a/docs/uk/reference/token-use.md +++ b/docs/uk/reference/token-use.md @@ -2,130 +2,131 @@ read_when: - Пояснення використання токенів, витрат або вікон контексту - Налагодження зростання контексту або поведінки ущільнення -summary: Як OpenClaw будує контекст запиту та повідомляє про використання токенів і витрати +summary: Як OpenClaw будує контекст prompt і звітує про використання токенів та витрати title: Використання токенів і витрати x-i18n: - generated_at: "2026-04-05T18:17:09Z" + generated_at: "2026-04-06T15:31:28Z" model: gpt-5.4 provider: openai - source_hash: 14e7a0ac0311298cf1484d663799a3f5a9687dd5afc9702233e983aba1979f1d + source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 source_path: reference/token-use.md workflow: 15 --- # Використання токенів і витрати -OpenClaw відстежує **токени**, а не символи. Токени залежать від моделі, але більшість -моделей у стилі OpenAI у середньому мають ~4 символи на токен для англійського тексту. +OpenClaw відстежує **токени**, а не символи. Токени залежать від моделі, але для більшості +моделей у стилі OpenAI середнє значення становить приблизно 4 символи на токен для англійського тексту. -## Як будується системний запит +## Як будується system prompt -OpenClaw збирає власний системний запит під час кожного запуску. Він містить: +OpenClaw збирає власний system prompt під час кожного запуску. Він містить: -- Список інструментів + короткі описи +- Список tools + короткі описи - Список Skills (лише метадані; інструкції завантажуються за потреби через `read`) -- Інструкції щодо самостійного оновлення -- Робочий простір + bootstrap-файли (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, якщо вони нові, а також `MEMORY.md`, якщо присутній, або `memory.md` як резервний варіант у нижньому регістрі). Великі файли обрізаються за `agents.defaults.bootstrapMaxChars` (типово: 20000), а загальний обсяг bootstrap-інʼєкції обмежується `agents.defaults.bootstrapTotalMaxChars` (типово: 150000). Файли `memory/*.md` доступні за потреби через інструменти пам’яті та не інʼєктуються автоматично. +- Інструкції для самооновлення +- Файли workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, якщо він новий, а також `MEMORY.md`, якщо він є, або `memory.md` як резервний варіант у нижньому регістрі). Великі файли обрізаються за `agents.defaults.bootstrapMaxChars` (типово: `20000`), а загальний обсяг ін’єкції bootstrap обмежується `agents.defaults.bootstrapTotalMaxChars` (типово: `150000`). Файли `memory/*.md` завантажуються за потреби через memory tools і не ін’єктуються автоматично. - Час (UTC + часовий пояс користувача) -- Теги відповіді + поведінка heartbeat -- Метадані середовища виконання (host/OS/model/thinking) +- Теги reply + поведінка heartbeat +- Метадані runtime (host/OS/model/thinking) -Повний розбір дивіться в [System Prompt](/uk/concepts/system-prompt). +Повний розбір див. у [System Prompt](/uk/concepts/system-prompt). ## Що враховується у вікні контексту -Усе, що отримує модель, зараховується до ліміту контексту: +Усе, що отримує модель, враховується в ліміт контексту: -- Системний запит (усі розділи, перелічені вище) +- System prompt (усі розділи, перелічені вище) - Історія розмови (повідомлення користувача + асистента) -- Виклики інструментів і результати інструментів -- Вкладення/транскрипти (зображення, аудіо, файли) +- Виклики tools і результати tools +- Вкладення/transcripts (зображення, аудіо, файли) - Підсумки ущільнення та артефакти обрізання - Обгортки провайдера або заголовки безпеки (не видимі, але все одно враховуються) -Для зображень OpenClaw зменшує розмір payload зображень у транскриптах/інструментах перед викликами провайдера. -Використовуйте `agents.defaults.imageMaxDimensionPx` (типово: `1200`) для налаштування цього: +Для зображень OpenClaw зменшує transcript/tool payload зображень перед викликами провайдера. +Для налаштування цього використовуйте `agents.defaults.imageMaxDimensionPx` (типово: `1200`): - Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload. -- Вищі значення зберігають більше візуальних деталей для OCR або знімків екрана з інтерфейсом. +- Вищі значення зберігають більше візуальних деталей для OCR/скриншотів із насиченим UI. -Для практичного розбору (за кожним інʼєктованим файлом, інструментами, Skills і розміром системного запиту) використовуйте `/context list` або `/context detail`. Див. [Context](/uk/concepts/context). +Для практичного розбору (для кожного ін’єктованого файлу, tools, Skills і розміру system prompt) використовуйте `/context list` або `/context detail`. Див. [Context](/uk/concepts/context). ## Як побачити поточне використання токенів Використовуйте це в чаті: -- `/status` → **картка стану з емодзі** з моделлю сесії, використанням контексту, +- `/status` → **картка статусу з emoji** з моделлю сесії, використанням контексту, вхідними/вихідними токенами останньої відповіді та **орієнтовною вартістю** (лише для API key). -- `/usage off|tokens|full` → додає **нижній колонтитул використання для кожної відповіді** до кожної відповіді. - - Зберігається для кожної сесії (зберігається як `responseUsage`). - - OAuth-автентифікація **приховує вартість** (лише токени). -- `/usage cost` → показує локальний підсумок витрат із логів сесій OpenClaw. +- `/usage off|tokens|full` → додає **нижній колонтитул використання для кожної відповіді** до кожного reply. + - Зберігається для сесії (зберігається як `responseUsage`). + - OAuth auth **приховує вартість** (лише токени). +- `/usage cost` → показує локальний підсумок витрат із журналів сесій OpenClaw. Інші поверхні: -- **TUI/Web TUI:** підтримуються `/status` і `/usage`. +- **TUI/Web TUI:** підтримуються `/status` + `/usage`. - **CLI:** `openclaw status --usage` і `openclaw channels list` показують - нормалізовані вікна квот провайдера (`X% left`, а не витрати на кожну відповідь). - Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, + нормалізовані вікна квот провайдера (`X% left`, а не вартість для кожної відповіді). + Поточні провайдери вікон використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi і z.ai. -Поверхні використання нормалізують поширені власні псевдоніми полів провайдерів перед показом. +Поверхні використання нормалізують поширені псевдоніми нативних полів провайдерів перед показом. Для трафіку OpenAI-family Responses це включає і `input_tokens` / -`output_tokens`, і `prompt_tokens` / `completion_tokens`, тож назви полів, -специфічні для транспорту, не змінюють `/status`, `/usage` або підсумки сесій. -Використання Gemini CLI JSON також нормалізується: текст відповіді береться з `response`, а -`stats.cached` мапиться на `cacheRead`, при цьому використовується `stats.input_tokens - stats.cached`, -коли CLI не надає явне поле `stats.input`. +`output_tokens`, і `prompt_tokens` / `completion_tokens`, тому специфічні для транспорту +назви полів не змінюють `/status`, `/usage` або підсумки сесії. +JSON-використання Gemini CLI також нормалізується: текст reply береться з `response`, а +`stats.cached` зіставляється з `cacheRead`, причому використовується `stats.input_tokens - stats.cached`, +коли CLI не надає явного поля `stats.input`. Для нативного трафіку OpenAI-family Responses псевдоніми використання WebSocket/SSE -нормалізуються так само, а підсумки резервно обчислюються як нормалізований input + output, якщо -`total_tokens` відсутній або дорівнює `0`. -Коли поточний знімок сесії містить мало даних, `/status` і `session_status` також можуть -відновлювати лічильники токенів/кешу та мітку активної моделі середовища виконання з -найсвіжішого журналу використання транскрипту. Наявні ненульові поточні значення й надалі -мають пріоритет над резервними значеннями з транскрипту, а більші загальні значення -з транскрипту, орієнтовані на запит, можуть переважати, коли збережені підсумки відсутні або менші. -Автентифікація використання для вікон квот провайдера надходить із хуків, специфічних для провайдера, якщо вони доступні; -інакше OpenClaw резервно використовує відповідні облікові дані OAuth/API key -з профілів автентифікації, env або config. +нормалізуються так само, а загальні суми переходять до нормалізованих input + output, коли +`total_tokens` відсутнє або дорівнює `0`. +Коли поточний snapshot сесії є розрідженим, `/status` і `session_status` також можуть +відновлювати лічильники токенів/кешу та мітку активної моделі runtime з +найновішого журналу використання transcript. Наявні ненульові поточні значення все одно мають +пріоритет над резервними значеннями з transcript, а більші загальні значення з transcript, +орієнтовані на prompt, можуть перемагати, коли збережені суми відсутні або менші. +Auth використання для вікон квот провайдера надходить із provider-specific hooks, коли вони +доступні; інакше OpenClaw повертається до зіставлення облікових даних OAuth/API-key +з профілів auth, середовища або конфігурації. ## Оцінка вартості (коли показується) -Витрати оцінюються на основі конфігурації цін вашої моделі: +Витрати оцінюються на основі вашої конфігурації тарифів моделі: ``` models.providers..models[].cost ``` Це **USD за 1M токенів** для `input`, `output`, `cacheRead` і -`cacheWrite`. Якщо ціни відсутні, OpenClaw показує лише токени. OAuth-токени +`cacheWrite`. Якщо інформація про тарифи відсутня, OpenClaw показує лише токени. OAuth tokens ніколи не показують вартість у доларах. -## Вплив TTL кешу й обрізання +## Вплив cache TTL і pruning -Кешування запитів провайдера застосовується лише в межах вікна TTL кешу. OpenClaw може -за бажанням виконувати **обрізання cache-ttl**: він обрізає сесію після завершення TTL -кешу, а потім скидає вікно кешу, щоб наступні запити могли повторно використовувати -щойно закешований контекст замість повторного кешування всієї історії. Це допомагає -зменшити витрати на запис у кеш, коли сесія простоює довше за TTL. +Кешування prompt провайдера застосовується лише в межах вікна cache TTL. OpenClaw може +необов’язково виконувати **pruning за cache-ttl**: він обрізає сесію після завершення +cache TTL, а потім скидає вікно кешу, щоб наступні запити могли повторно використати +щойно кешований контекст замість повторного кешування всієї історії. Це допомагає +зменшити вартість запису в кеш, коли сесія простоює довше за TTL. -Налаштуйте це в [Gateway configuration](/uk/gateway/configuration), а деталі -поведінки дивіться в [Session pruning](/uk/concepts/session-pruning). +Налаштуйте це у [Конфігурація gateway](/uk/gateway/configuration), а подробиці поведінки див. у +[Обрізання сесії](/uk/concepts/session-pruning). -Heartbeat може підтримувати кеш **теплим** упродовж періодів простою. Якщо TTL кешу вашої моделі -становить `1h`, встановлення інтервалу heartbeat трохи менше цього значення (наприклад, `55m`) може -допомогти уникнути повторного кешування всього запиту, зменшуючи витрати на запис у кеш. +Heartbeat може зберігати кеш **теплим** у періоди простою. Якщо cache TTL вашої моделі +становить `1h`, встановлення інтервалу heartbeat трохи менше цього значення (наприклад, `55m`) може уникнути +повторного кешування всього prompt, зменшуючи витрати на запис у кеш. -У багатoагентних конфігураціях ви можете зберігати одну спільну конфігурацію моделі та налаштовувати поведінку кешу -для кожного агента через `agents.list[].params.cacheRetention`. +У конфігураціях із кількома агентами ви можете зберігати одну спільну конфігурацію моделі та налаштовувати поведінку кешу +для кожного агента окремо за допомогою `agents.list[].params.cacheRetention`. -Повний посібник за всіма параметрами дивіться в [Prompt Caching](/reference/prompt-caching). +Повний посібник із налаштування всіх параметрів див. у [Prompt Caching](/uk/reference/prompt-caching). -Для цін Anthropic API читання з кешу значно дешевше за input-токени, -тоді як запис у кеш оплачується з вищим множником. Актуальні тарифи та множники TTL дивіться в документації Anthropic щодо цін на prompt caching: +Для тарифів Anthropic API читання з кешу значно дешевші за вхідні +токени, тоді як запис у кеш тарифікується з вищим множником. Актуальні тарифи та множники TTL див. у документації Anthropic +щодо тарифікації prompt caching: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### Приклад: підтримувати кеш 1h теплим за допомогою heartbeat +### Приклад: підтримувати 1h cache теплим за допомогою heartbeat ```yaml agents: @@ -140,7 +141,7 @@ agents: every: "55m" ``` -### Приклад: змішаний трафік із кеш-стратегією для кожного агента +### Приклад: змішаний трафік зі стратегією кешу для кожного агента ```yaml agents: @@ -150,7 +151,7 @@ agents: models: "anthropic/claude-opus-4-6": params: - cacheRetention: "long" # типовий базовий рівень для більшості агентів + cacheRetention: "long" # типова базова лінія для більшості агентів list: - id: "research" default: true @@ -158,15 +159,15 @@ agents: every: "55m" # підтримувати довгий кеш теплим для глибоких сесій - id: "alerts" params: - cacheRetention: "none" # уникати записів у кеш для сплескових сповіщень + cacheRetention: "none" # уникати запису в кеш для сплескових сповіщень ``` -`agents.list[].params` об’єднується поверх `params` вибраної моделі, тож ви можете -перевизначити лише `cacheRetention` та успадкувати інші типові параметри моделі без змін. +`agents.list[].params` зливається поверх `params` вибраної моделі, тому ви можете +перевизначити лише `cacheRetention` і успадкувати інші типові значення моделі без змін. -### Приклад: увімкнути beta-заголовок Anthropic 1M context +### Приклад: увімкнути beta-заголовок Anthropic для контексту 1M -Вікно контексту Anthropic 1M наразі доступне лише через beta. OpenClaw може вставляти +Вікно контексту Anthropic 1M зараз доступне лише за beta-доступом. OpenClaw може вставляти потрібне значення `anthropic-beta`, коли ви вмикаєте `context1m` для підтримуваних моделей Opus або Sonnet. @@ -179,24 +180,23 @@ agents: context1m: true ``` -Це мапиться на beta-заголовок Anthropic `context-1m-2025-08-07`. +Це зіставляється з beta-заголовком Anthropic `context-1m-2025-08-07`. -Це застосовується лише тоді, коли `context1m: true` встановлено для цього запису моделі. +Це застосовується лише тоді, коли `context1m: true` задано для цього запису моделі. -Вимога: облікові дані мають бути придатними для використання довгого контексту (виставлення рахунків через API key -або шлях Claude-login в OpenClaw з увімкненим Extra Usage). Інакше Anthropic відповідає -`HTTP 429: rate_limit_error: Extra usage is required for long context requests`. +Вимога: облікові дані мають мати право на використання довгого контексту. Якщо ні, +Anthropic відповість provider-side помилкою обмеження швидкості для цього запиту. -Якщо ви автентифікуєте Anthropic за допомогою OAuth/subscription-токенів (`sk-ant-oat-*`), -OpenClaw пропускає beta-заголовок `context-1m-*`, оскільки Anthropic наразі +Якщо ви автентифікуєте Anthropic за допомогою OAuth/subscription tokens (`sk-ant-oat-*`), +OpenClaw пропускає beta-заголовок `context-1m-*`, тому що Anthropic наразі відхиляє таку комбінацію з HTTP 401. -## Поради щодо зменшення тиску токенів +## Поради щодо зменшення тиску на токени - Використовуйте `/compact`, щоб підсумовувати довгі сесії. -- Обрізайте великі виводи інструментів у своїх робочих процесах. -- Зменшуйте `agents.defaults.imageMaxDimensionPx` для сесій з великою кількістю знімків екрана. -- Тримайте описи Skills короткими (список Skills інʼєктується в запит). -- Для багатослівної дослідницької роботи віддавайте перевагу меншим моделям. +- Обрізайте великі результати tools у своїх workflow. +- Зменшуйте `agents.defaults.imageMaxDimensionPx` для сесій з великою кількістю скриншотів. +- Робіть описи Skills короткими (список Skills ін’єктується в prompt). +- Віддавайте перевагу меншим моделям для багатослівної дослідницької роботи. -Точну формулу накладних витрат списку Skills дивіться в [Skills](/tools/skills). +Точну формулу накладних витрат списку Skills див. у [Skills](/uk/tools/skills). diff --git a/docs/uk/reference/wizard.md b/docs/uk/reference/wizard.md index 9674902af..2e26ae8de 100644 --- a/docs/uk/reference/wizard.md +++ b/docs/uk/reference/wizard.md @@ -1,16 +1,16 @@ --- read_when: - - Потрібно знайти конкретний крок онбордингу або прапорець + - Пошук конкретного кроку онбордингу або прапорця - Автоматизація онбордингу в неінтерактивному режимі - Налагодження поведінки онбордингу sidebarTitle: Onboarding Reference -summary: 'Повний довідник з онбордингу CLI: кожен крок, прапорець і поле конфігурації' +summary: 'Повний довідник з онбордингу в CLI: кожен крок, прапорець і поле конфігурації' title: Довідник з онбордингу x-i18n: - generated_at: "2026-04-05T18:17:22Z" + generated_at: "2026-04-06T15:32:00Z" model: gpt-5.4 provider: openai - source_hash: e02a4da4a39ba335199095723f5d3b423671eb12efc2d9e4f9e48c1e8ee18419 + source_hash: a142b9ec4323fabb9982d05b64375d2b4a4007dffc910acbee3a38ff871a7236 source_path: reference/wizard.md workflow: 15 --- @@ -18,138 +18,137 @@ x-i18n: # Довідник з онбордингу Це повний довідник для `openclaw onboard`. -Огляд вищого рівня див. у [Onboarding (CLI)](/start/wizard). +Огляд високого рівня див. у [Onboarding (CLI)](/uk/start/wizard). -## Деталі процесу (локальний режим) +## Докладно про потік (локальний режим) - Якщо існує `~/.openclaw/openclaw.json`, виберіть **Keep / Modify / Reset**. - Повторний запуск онбордингу **не** стирає нічого, якщо ви явно не виберете **Reset** (або не передасте `--reset`). - - Для CLI `--reset` типово використовує `config+creds+sessions`; використовуйте `--reset-scope full`, + - CLI `--reset` типово використовує `config+creds+sessions`; використовуйте `--reset-scope full`, щоб також видалити workspace. - - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється та просить - вас виконати `openclaw doctor` перед продовженням. - - Скидання використовує `trash` (ніколи не `rm`) і пропонує такі області: + - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється і просить + вас запустити `openclaw doctor`, перш ніж продовжувати. + - Reset використовує `trash` (ніколи не `rm`) і пропонує такі області: - Лише конфігурація - - Конфігурація + облікові дані + сесії - - Повне скидання (також видаляє workspace) + - Конфігурація + облікові дані + сеанси + - Повний скидання (також видаляє workspace) - - **Anthropic API key**: використовує `ANTHROPIC_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його для використання демоном. - - **Anthropic API key**: бажаний варіант помічника Anthropic в онбордингу/налаштуванні. - - **Anthropic setup-token (legacy/manual)**: знову доступний в онбордингу/налаштуванні, але Anthropic повідомила користувачам OpenClaw, що шлях входу Claude в OpenClaw вважається використанням сторонньої harness і вимагає **Extra Usage** в обліковому записі Claude. - - **OpenAI Code (Codex) subscription (Codex CLI)**: якщо існує `~/.codex/auth.json`, онбординг може повторно його використати. Повторно використані облікові дані Codex CLI і надалі керуються Codex CLI; після закінчення строку дії OpenClaw спочатку знову читає це джерело і, коли провайдер може їх оновити, записує оновлені облікові дані назад у сховище Codex замість того, щоб перебирати керування на себе. - - **OpenAI Code (Codex) subscription (OAuth)**: потік через браузер; вставте `code#state`. - - Установлює `agents.defaults.model` у `openai-codex/gpt-5.4`, якщо модель не задана або має вигляд `openai/*`. - - **OpenAI API key**: використовує `OPENAI_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його в профілях автентифікації. - - Установлює `agents.defaults.model` у `openai/gpt-5.4`, якщо модель не задана, має вигляд `openai/*` або `openai-codex/*`. - - **xAI (Grok) API key**: запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделей. - - **OpenCode**: запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`, отримати можна на https://opencode.ai/auth) і дає змогу вибрати каталог Zen або Go. - - **Ollama**: запитує базову URL-адресу Ollama, пропонує режим **Cloud + Local** або **Local**, виявляє доступні моделі й автоматично завантажує вибрану локальну модель за потреби. + - **API-ключ Anthropic**: використовує `ANTHROPIC_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його для використання демоном. + - **API-ключ Anthropic**: бажаний варіант Anthropic assistant в onboarding/configure. + - **Anthropic setup-token**: усе ще доступний в onboarding/configure, хоча OpenClaw тепер надає перевагу повторному використанню Claude CLI, коли це можливо. + - **Підписка OpenAI Code (Codex) (Codex CLI)**: якщо існує `~/.codex/auth.json`, онбординг може повторно використати його. Повторно використані облікові дані Codex CLI і далі керуються Codex CLI; після завершення строку дії OpenClaw спочатку знову читає це джерело і, коли постачальник може його оновити, записує оновлені облікові дані назад у сховище Codex замість того, щоб перебирати керування на себе. + - **Підписка OpenAI Code (Codex) (OAuth)**: потік через браузер; вставте `code#state`. + - Встановлює `agents.defaults.model` у `openai-codex/gpt-5.4`, коли модель не задана або має вигляд `openai/*`. + - **API-ключ OpenAI**: використовує `OPENAI_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його в профілях автентифікації. + - Встановлює `agents.defaults.model` у `openai/gpt-5.4`, коли модель не задана, має вигляд `openai/*` або `openai-codex/*`. + - **API-ключ xAI (Grok)**: запитує `XAI_API_KEY` і налаштовує xAI як постачальника моделей. + - **OpenCode**: запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`, отримайте його на https://opencode.ai/auth) і дає змогу вибрати каталог Zen або Go. + - **Ollama**: запитує базову URL-адресу Ollama, пропонує режим **Cloud + Local** або **Local**, виявляє доступні моделі та автоматично завантажує вибрану локальну модель, якщо це потрібно. - Докладніше: [Ollama](/uk/providers/ollama) - **API key**: зберігає ключ за вас. - - **Vercel AI Gateway (багатомодельний проксі)**: запитує `AI_GATEWAY_API_KEY`. + - **Vercel AI Gateway (багатомодельний proxy)**: запитує `AI_GATEWAY_API_KEY`. - Докладніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**: запитує Account ID, Gateway ID і `CLOUDFLARE_AI_GATEWAY_API_KEY`. - Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway) - - **MiniMax**: конфігурація записується автоматично; типовим хостованим значенням є `MiniMax-M2.7`. - Налаштування через API key використовує `minimax/...`, а налаштування через OAuth — - `minimax-portal/...`. + - **MiniMax**: конфігурація записується автоматично; типовим хостинговим значенням є `MiniMax-M2.7`. + Налаштування з API-ключем використовує `minimax/...`, а налаштування з OAuth — `minimax-portal/...`. - Докладніше: [MiniMax](/uk/providers/minimax) - - **StepFun**: конфігурація автоматично записується для StepFun standard або Step Plan на китайських чи глобальних кінцевих точках. - - Standard наразі містить `step-3.5-flash`, а Step Plan також містить `step-3.5-flash-2603`. + - **StepFun**: конфігурація автоматично записується для стандартного StepFun або Step Plan на китайських чи глобальних кінцевих точках. + - Стандарт зараз включає `step-3.5-flash`, а Step Plan також включає `step-3.5-flash-2603`. - Докладніше: [StepFun](/uk/providers/stepfun) - **Synthetic (сумісний з Anthropic)**: запитує `SYNTHETIC_API_KEY`. - Докладніше: [Synthetic](/uk/providers/synthetic) - **Moonshot (Kimi K2)**: конфігурація записується автоматично. - **Kimi Coding**: конфігурація записується автоматично. - Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot) - - **Skip**: автентифікацію поки не налаштовано. - - Виберіть типову модель із виявлених варіантів (або введіть provider/model вручну). Для найкращої якості та нижчого ризику prompt injection вибирайте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. - - Під час онбордингу виконується перевірка моделі й виводиться попередження, якщо налаштована модель невідома або відсутня автентифікація. - - Режим зберігання API key типово використовує прості текстові значення профілю автентифікації. Використовуйте `--secret-input-mode ref`, щоб натомість зберігати посилання на змінні середовища (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). - - Профілі автентифікації зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). `~/.openclaw/credentials/oauth.json` — це застаріле джерело лише для імпорту. + - **Skip**: автентифікація поки не налаштована. + - Виберіть типову модель із виявлених варіантів (або введіть provider/model вручну). Для найкращої якості та нижчого ризику ін’єкцій у prompt вибирайте найсильнішу модель останнього покоління, доступну у вашому стеку постачальників. + - Онбординг запускає перевірку моделі й попереджає, якщо налаштована модель невідома або для неї бракує автентифікації. + - Режим зберігання API-ключів типово використовує plaintext-значення в профілях автентифікації. Використовуйте `--secret-input-mode ref`, щоб натомість зберігати посилання на основі env (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). + - Профілі автентифікації розміщуються в `~/.openclaw/agents//agent/auth-profiles.json` (API-ключі + OAuth). `~/.openclaw/credentials/oauth.json` — лише застаріле джерело імпорту. - Докладніше: [/concepts/oauth](/uk/concepts/oauth) - Порада для headless/server: завершіть OAuth на машині з браузером, а потім скопіюйте + Порада для безголових серверів: завершіть OAuth на машині з браузером, а потім скопіюйте `auth-profiles.json` цього агента (наприклад, - `~/.openclaw/agents//agent/auth-profiles.json` або відповідний шлях - `$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json` + `~/.openclaw/agents//agent/auth-profiles.json` або відповідний + шлях `$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json` є лише застарілим джерелом імпорту. - Типово `~/.openclaw/workspace` (можна налаштувати). - - Ініціалізує файли workspace, потрібні для bootstrap ritual агента. - - Повна структура workspace + інструкція з резервного копіювання: [Agent workspace](/uk/concepts/agent-workspace) + - Ініціалізує файли workspace, потрібні для ритуалу початкового запуску агента. + - Повну структуру workspace та посібник із резервного копіювання див. тут: [Agent workspace](/uk/concepts/agent-workspace) - - Порт, bind, режим автентифікації, доступ через tailscale. - - Рекомендація щодо автентифікації: залишайте **Token** навіть для loopback, щоб локальні WS-клієнти мали проходити автентифікацію. + - Порт, bind, режим автентифікації, відкриття через Tailscale. + - Рекомендація щодо автентифікації: зберігайте **Token** навіть для loopback, щоб локальні WS-клієнти мали проходити автентифікацію. - У режимі token інтерактивне налаштування пропонує: - - **Generate/store plaintext token** (типово) - - **Use SecretRef** (необов’язково) - - Quickstart повторно використовує наявні SecretRef `gateway.auth.token` для провайдерів `env`, `file` і `exec` для probe/dashboard bootstrap під час онбордингу. - - Якщо цей SecretRef налаштовано, але його неможливо розв’язати, онбординг завершується помилкою на ранньому етапі з чітким повідомленням про виправлення замість тихого погіршення автентифікації під час виконання. - - У режимі password інтерактивне налаштування також підтримує зберігання у відкритому тексті або через SecretRef. - - Шлях SecretRef для token у неінтерактивному режимі: `--gateway-token-ref-env `. - - Потребує непорожньої змінної середовища в середовищі процесу онбордингу. + - **Згенерувати/зберегти plaintext token** (типово) + - **Використовувати SecretRef** (opt-in) + - Quickstart повторно використовує наявні SecretRef `gateway.auth.token` через постачальників `env`, `file` і `exec` для bootstrap probe/dashboard під час онбордингу. + - Якщо цей SecretRef налаштовано, але його не вдається розв’язати, онбординг завершується помилкою на ранньому етапі з чітким повідомленням щодо виправлення замість тихого погіршення runtime-автентифікації. + - У режимі password інтерактивне налаштування також підтримує зберігання у plaintext або через SecretRef. + - Шлях SecretRef token у неінтерактивному режимі: `--gateway-token-ref-env `. + - Потребує непорожньої змінної середовища в оточенні процесу онбордингу. - Не можна поєднувати з `--gateway-token`. - - Вимикайте автентифікацію, лише якщо повністю довіряєте кожному локальному процесу. - - Для bind, відмінних від loopback, автентифікація все одно обов’язкова. + - Вимикайте автентифікацію лише якщо ви повністю довіряєте кожному локальному процесу. + - Прив’язки не до loopback усе одно вимагають автентифікації. - [WhatsApp](/uk/channels/whatsapp): необов’язковий вхід через QR. - [Telegram](/uk/channels/telegram): токен бота. - [Discord](/uk/channels/discord): токен бота. - - [Google Chat](/uk/channels/googlechat): JSON сервісного облікового запису + webhook audience. - - [Mattermost](/uk/channels/mattermost) (plugin): токен бота + базова URL-адреса. + - [Google Chat](/uk/channels/googlechat): JSON облікового запису служби + webhook audience. + - [Mattermost](/uk/channels/mattermost) (плагін): токен бота + базова URL-адреса. - [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація облікового запису. - [BlueBubbles](/uk/channels/bluebubbles): **рекомендовано для iMessage**; URL-адреса сервера + пароль + webhook. - [iMessage](/uk/channels/imessage): застарілий шлях CLI `imsg` + доступ до БД. - - Безпека DM: типово використовується pairing. Під час першого DM надсилається код; схваліть його через `openclaw pairing approve ` або використовуйте списки дозволених. + - Безпека DM: типово використовується pairing. Перше DM надсилає код; підтвердіть через `openclaw pairing approve ` або використовуйте allowlists. - - Виберіть підтримуваного провайдера, наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG або Tavily (або пропустіть). - - Провайдери з API можуть використовувати змінні середовища або наявну конфігурацію для швидкого налаштування; провайдери без ключів натомість використовують свої специфічні передумови. - - Пропустити: `--skip-search`. + - Виберіть підтримуваного постачальника, наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG або Tavily (або пропустіть). + - Постачальники з API можуть використовувати змінні середовища або наявну конфігурацію для швидкого налаштування; постачальники без ключа натомість використовують свої специфічні передумови. + - Пропустіть за допомогою `--skip-search`. - Налаштувати пізніше: `openclaw configure --section web`. - macOS: LaunchAgent - - Потребує активної сесії користувача; для headless використовуйте власний LaunchDaemon (не постачається). - - Linux (і Windows через WSL2): користувацький модуль systemd - - Під час онбордингу виконується спроба ввімкнути lingering через `loginctl enable-linger `, щоб Gateway залишався запущеним після виходу з системи. - - Може запитати sudo (записує в `/var/lib/systemd/linger`); спочатку намагається без sudo. - - **Вибір середовища виконання:** Node (рекомендовано; обов’язково для WhatsApp/Telegram). Bun **не рекомендовано**. - - Якщо для token auth потрібен token, а `gateway.auth.token` керується через SecretRef, встановлення демона перевіряє його, але не зберігає розв’язані значення токена у відкритому тексті в метаданих середовища сервісу supervisor. - - Якщо для token auth потрібен token, а налаштований token SecretRef не розв’язується, встановлення демона блокується з практичними вказівками. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення демона блокується, доки режим не буде явно встановлено. + - Потребує активної користувацької сесії; для безголового режиму використовуйте власний LaunchDaemon (не постачається). + - Linux (і Windows через WSL2): systemd user unit + - Онбординг намагається ввімкнути lingering через `loginctl enable-linger `, щоб Gateway залишався запущеним після виходу з сеансу. + - Може запросити sudo (записує у `/var/lib/systemd/linger`); спочатку пробує без sudo. + - **Вибір runtime:** Node (рекомендовано; обов’язково для WhatsApp/Telegram). Bun **не рекомендовано**. + - Якщо для автентифікації token потрібен token і `gateway.auth.token` керується через SecretRef, встановлення демона перевіряє його, але не зберігає розв’язані plaintext-значення token у метаданих середовища служби супервізора. + - Якщо для автентифікації token потрібен token, а налаштований SecretRef token не розв’язується, встановлення демона блокується з практичними підказками. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення демона блокується, доки режим не буде явно вказано. - + - Запускає Gateway (за потреби) і виконує `openclaw health`. - - Порада: `openclaw status --deep` додає до виводу статусу live gateway health probe, включно з перевірками каналів, де це підтримується (потребує доступного gateway). + - Порада: `openclaw status --deep` додає живу перевірку стану gateway до виводу status, зокрема probe каналів, коли вони підтримуються (потрібен доступний gateway). - Зчитує доступні Skills і перевіряє вимоги. - - Дає змогу вибрати менеджер Node: **npm / pnpm** (bun не рекомендовано). - - Установлює необов’язкові залежності (деякі використовують Homebrew у macOS). + - Дає змогу вибрати менеджер node: **npm / pnpm** (bun не рекомендовано). + - Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS). - - Підсумок + наступні кроки, зокрема застосунки для iOS/Android/macOS для додаткових можливостей. + - Підсумок + наступні кроки, зокрема застосунки для iOS/Android/macOS для додаткових функцій. -Якщо GUI не виявлено, онбординг виводить інструкції з пробросу порту SSH для Control UI замість відкриття браузера. -Якщо ресурси Control UI відсутні, онбординг намагається їх зібрати; резервний варіант — `pnpm ui:build` (автоматично встановлює залежності UI). +Якщо графічний інтерфейс не виявлено, онбординг друкує інструкції для переспрямування портів SSH для Control UI замість відкриття браузера. +Якщо ресурси Control UI відсутні, онбординг намагається зібрати їх; резервний варіант — `pnpm ui:build` (автоматично встановлює UI-залежності). ## Неінтерактивний режим -Використовуйте `--non-interactive` для автоматизації або сценаріїв онбордингу: +Використовуйте `--non-interactive`, щоб автоматизувати або скриптувати онбординг: ```bash openclaw onboard --non-interactive \ @@ -165,7 +164,7 @@ openclaw onboard --non-interactive \ Додайте `--json` для машинозчитуваного підсумку. -Gateway token SecretRef у неінтерактивному режимі: +SecretRef token gateway у неінтерактивному режимі: ```bash export OPENCLAW_GATEWAY_TOKEN="your-token" @@ -179,13 +178,13 @@ openclaw onboard --non-interactive \ `--gateway-token` і `--gateway-token-ref-env` є взаємовиключними. -`--json` **не** означає неінтерактивний режим. Для сценаріїв використовуйте `--non-interactive` (і `--workspace`). +`--json` **не** означає неінтерактивний режим. Для скриптів використовуйте `--non-interactive` (і `--workspace`). -Приклади команд для конкретних провайдерів наведені в [CLI Automation](/start/wizard-cli-automation#provider-specific-examples). +Приклади команд для конкретних постачальників наведені в [CLI Automation](/uk/start/wizard-cli-automation#provider-specific-examples). Використовуйте цю довідкову сторінку для семантики прапорців і порядку кроків. -### Додати агента (неінтерактивно) +### Додавання агента (неінтерактивно) ```bash openclaw agents add work \ @@ -198,22 +197,22 @@ openclaw agents add work \ ## RPC майстра Gateway -Gateway надає процес онбордингу через RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). -Клієнти (застосунок macOS, Control UI) можуть відображати кроки без повторної реалізації логіки онбордингу. +Gateway надає потік онбордингу через RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). +Клієнти (застосунок macOS, Control UI) можуть відображати кроки, не реалізуючи повторно логіку онбордингу. -## Налаштування Signal (signal-cli) +## Налаштування Signal (`signal-cli`) -Під час онбордингу можна встановити `signal-cli` з GitHub releases: +Онбординг може встановлювати `signal-cli` з релізів GitHub: -- Завантажує відповідний ресурс release. +- Завантажує відповідний asset релізу. - Зберігає його в `~/.openclaw/tools/signal-cli//`. - Записує `channels.signal.cliPath` у вашу конфігурацію. Примітки: - Збірки JVM потребують **Java 21**. -- Native-збірки використовуються, коли вони доступні. -- У Windows використовується WSL2; встановлення signal-cli відбувається за сценарієм Linux усередині WSL. +- Якщо доступні, використовуються native-збірки. +- Windows використовує WSL2; встановлення signal-cli дотримується linux-потоку всередині WSL. ## Що записує майстер @@ -221,14 +220,14 @@ Gateway надає процес онбордингу через RPC (`wizard.sta - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers` (якщо вибрано Minimax) -- `tools.profile` (у локальному онбордингу типово встановлюється `"coding"`, якщо значення не задано; наявні явно встановлені значення зберігаються) +- `tools.profile` (локальний онбординг типово встановлює `"coding"`, якщо значення не задано; наявні явні значення зберігаються) - `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (деталі поведінки: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)) +- `session.dmScope` (докладно про поведінку: [CLI Setup Reference](/uk/start/wizard-cli-reference#outputs-and-internals)) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Списки дозволених каналів (Slack/Discord/Matrix/Microsoft Teams), якщо ви погоджуєтеся на це під час підказок (імена перетворюються на ID, коли це можливо). +- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams), якщо ви погодилися на них під час підказок (імена за можливості розв’язуються в ID). - `skills.install.nodeManager` - `setup --node-manager` приймає `npm`, `pnpm` або `bun`. - - У ручній конфігурації все ще можна використовувати `yarn`, безпосередньо задавши `skills.install.nodeManager`. + - Ручна конфігурація все ще може використовувати `yarn`, якщо напряму встановити `skills.install.nodeManager`. - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -237,16 +236,16 @@ Gateway надає процес онбордингу через RPC (`wizard.sta `openclaw agents add` записує `agents.list[]` і необов’язкові `bindings`. -Облікові дані WhatsApp зберігаються в `~/.openclaw/credentials/whatsapp//`. -Сесії зберігаються в `~/.openclaw/agents//sessions/`. +Облікові дані WhatsApp розміщуються в `~/.openclaw/credentials/whatsapp//`. +Сеанси зберігаються в `~/.openclaw/agents//sessions/`. Деякі канали постачаються як plugins. Коли ви вибираєте один із них під час налаштування, онбординг запропонує встановити його (npm або локальний шлях), перш ніж його можна буде налаштувати. -## Пов’язані документи +## Пов’язана документація -- Огляд онбордингу: [Onboarding (CLI)](/start/wizard) -- Онбординг у застосунку macOS: [Onboarding](/start/onboarding) -- Довідник з конфігурації: [Gateway configuration](/uk/gateway/configuration) -- Провайдери: [WhatsApp](/uk/channels/whatsapp), [Telegram](/uk/channels/telegram), [Discord](/uk/channels/discord), [Google Chat](/uk/channels/googlechat), [Signal](/uk/channels/signal), [BlueBubbles](/uk/channels/bluebubbles) (iMessage), [iMessage](/uk/channels/imessage) (застарілий) -- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config) +- Огляд онбордингу: [Onboarding (CLI)](/uk/start/wizard) +- Онбординг у застосунку macOS: [Onboarding](/uk/start/onboarding) +- Довідник із конфігурації: [Gateway configuration](/uk/gateway/configuration) +- Постачальники: [WhatsApp](/uk/channels/whatsapp), [Telegram](/uk/channels/telegram), [Discord](/uk/channels/discord), [Google Chat](/uk/channels/googlechat), [Signal](/uk/channels/signal), [BlueBubbles](/uk/channels/bluebubbles) (iMessage), [iMessage](/uk/channels/imessage) (застарілий) +- Skills: [Skills](/uk/tools/skills), [Skills config](/uk/tools/skills-config) diff --git a/docs/uk/start/wizard-cli-automation.md b/docs/uk/start/wizard-cli-automation.md index 2eec1b582..8e358b4cd 100644 --- a/docs/uk/start/wizard-cli-automation.md +++ b/docs/uk/start/wizard-cli-automation.md @@ -6,10 +6,10 @@ sidebarTitle: CLI automation summary: Скриптовий онбординг і налаштування агента для CLI OpenClaw title: Автоматизація CLI x-i18n: - generated_at: "2026-04-05T18:18:09Z" + generated_at: "2026-04-06T15:31:41Z" model: gpt-5.4 provider: openai - source_hash: 878ea3fa9f2a75cff9f1a803ccb8a52a1219102e2970883ad18e3aaec5967fd2 + source_hash: bca2dd6e482a16b27284fc76319e936e8df0ff5558134827c19f6875436cc652 source_path: start/wizard-cli-automation.md workflow: 15 --- @@ -37,13 +37,13 @@ openclaw onboard --non-interactive \ --skip-skills ``` -Додайте `--json` для машинозчитуваного підсумку. +Додайте `--json` для машиночитаного підсумку. -Використовуйте `--secret-input-mode ref`, щоб зберігати посилання на змінні середовища в профілях автентифікації замість значень у відкритому вигляді. -Інтерактивний вибір між env-посиланнями та налаштованими посиланнями провайдера (`file` або `exec`) доступний у процесі онбордингу. +Використовуйте `--secret-input-mode ref`, щоб зберігати env-backed refs у профілях auth замість значень у відкритому вигляді. +Інтерактивний вибір між env refs і налаштованими refs провайдера (`file` або `exec`) доступний у потоці онбордингу. У неінтерактивному режимі `ref` змінні середовища провайдера мають бути встановлені в середовищі процесу. -Передавання вбудованих прапорців ключів без відповідної env-змінної тепер одразу завершується помилкою. +Передавання inline-прапорців ключів без відповідної env-змінної тепер одразу завершується помилкою. Приклад: @@ -55,7 +55,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -## Приклади для окремих провайдерів +## Приклади для конкретних провайдерів @@ -130,7 +130,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -162,7 +162,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -176,7 +176,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - `--custom-api-key` є необов’язковим. Якщо його пропущено, онбординг перевіряє `CUSTOM_API_KEY`. + `--custom-api-key` необов’язковий. Якщо його пропущено, онбординг перевіряє `CUSTOM_API_KEY`. Варіант режиму ref: @@ -199,15 +199,13 @@ openclaw onboard --non-interactive \ -Anthropic setup-token знову доступний як застарілий/ручний шлях онбордингу. -Використовуйте його з розумінням того, що Anthropic повідомила користувачам OpenClaw, що -шлях входу Claude в OpenClaw потребує **Extra Usage**. Для виробничого використання віддавайте перевагу -API-ключу Anthropic. +Anthropic setup-token залишається доступним як підтримуваний шлях токена онбордингу, але OpenClaw тепер надає перевагу повторному використанню Claude CLI, коли це можливо. +Для production надавайте перевагу API-ключу Anthropic. ## Додати ще одного агента -Використовуйте `openclaw agents add `, щоб створити окремого агента з власним робочим простором, -сесіями та профілями автентифікації. Запуск без `--workspace` відкриває майстер. +Використовуйте `openclaw agents add `, щоб створити окремого агента з власними workspace, +sessions і профілями auth. Запуск без `--workspace` відкриває майстер. ```bash openclaw agents add work \ @@ -218,7 +216,7 @@ openclaw agents add work \ --json ``` -Що це налаштовує: +Що це встановлює: - `agents.list[].name` - `agents.list[].workspace` @@ -226,12 +224,12 @@ openclaw agents add work \ Примітки: -- Типові робочі простори мають формат `~/.openclaw/workspace-`. +- Робочі простори за замовчуванням мають формат `~/.openclaw/workspace-`. - Додайте `bindings`, щоб маршрутизувати вхідні повідомлення (майстер може це зробити). - Неінтерактивні прапорці: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. ## Пов’язані документи -- Центр онбордингу: [Онбординг (CLI)](/start/wizard) -- Повний довідник: [Довідник із налаштування CLI](/start/wizard-cli-reference) -- Довідник команд: [`openclaw onboard`](/cli/onboard) +- Центр онбордингу: [Онбординг (CLI)](/uk/start/wizard) +- Повний довідник: [Довідник налаштування CLI](/uk/start/wizard-cli-reference) +- Довідник команди: [`openclaw onboard`](/cli/onboard) diff --git a/docs/uk/start/wizard.md b/docs/uk/start/wizard.md index f957f17fd..ecfcf13c7 100644 --- a/docs/uk/start/wizard.md +++ b/docs/uk/start/wizard.md @@ -3,13 +3,13 @@ read_when: - Запуск або налаштування онбордингу CLI - Налаштування нової машини sidebarTitle: 'Onboarding: CLI' -summary: 'Онбординг CLI: покрокове налаштування gateway, робочого простору, каналів і Skills' +summary: 'Онбординг CLI: покрокове налаштування gateway, workspace, каналів і Skills' title: Онбординг (CLI) x-i18n: - generated_at: "2026-04-05T18:18:21Z" + generated_at: "2026-04-06T15:31:45Z" model: gpt-5.4 provider: openai - source_hash: 81e33fb4f8be30e7c2c6e0024bf9bdcf48583ca58eaf5fff5afd37a1cd628523 + source_hash: 6773b07afa8babf1b5ac94d857063d08094a962ee21ec96ca966e99ad57d107d source_path: start/wizard.md workflow: 15 --- @@ -17,20 +17,20 @@ x-i18n: # Онбординг (CLI) Онбординг CLI — це **рекомендований** спосіб налаштування OpenClaw на macOS, -Linux або Windows (через WSL2; настійно рекомендується). +Linux або Windows (через WSL2; наполегливо рекомендовано). Він налаштовує локальний Gateway або підключення до віддаленого Gateway, а також канали, Skills -і типові параметри робочого простору в одному покроковому сценарії. +і стандартні параметри workspace в одному покроковому сценарії. ```bash openclaw onboard ``` -Найшвидший перший чат: відкрийте Control UI (налаштування каналів не потрібне). Запустіть +Найшвидший перший чат: відкрийте Control UI (налаштування каналу не потрібне). Виконайте `openclaw dashboard` і спілкуйтеся в браузері. Документація: [Dashboard](/web/dashboard). -Щоб пізніше змінити налаштування: +Щоб змінити налаштування пізніше: ```bash openclaw configure @@ -42,71 +42,71 @@ openclaw agents add -Онбординг CLI містить крок вебпошуку, де ви можете вибрати провайдера, -наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, -Ollama Web Search, Perplexity, SearXNG або Tavily. Деякі провайдери потребують -API key, а інші працюють без ключа. Ви також можете налаштувати це пізніше за допомогою -`openclaw configure --section web`. Документація: [Web tools](/tools/web). +Онбординг CLI включає крок вебпошуку, де можна вибрати провайдера, +такого як Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, +Ollama Web Search, Perplexity, SearXNG або Tavily. Деяким провайдерам потрібен +API key, а інші працюють без ключа. Це також можна налаштувати пізніше через +`openclaw configure --section web`. Документація: [Web tools](/uk/tools/web). -## QuickStart проти Advanced +## QuickStart чи Advanced -Онбординг починається з вибору **QuickStart** (типові параметри) або **Advanced** (повний контроль). +Онбординг починається з вибору **QuickStart** (типові значення) або **Advanced** (повний контроль). - + - Локальний gateway (loopback) - - Типовий робочий простір (або наявний робочий простір) + - Workspace за замовчуванням (або наявний workspace) - Порт gateway **18789** - - Автентифікація gateway **Token** (генерується автоматично, навіть на loopback) + - Автентифікація gateway **Token** (генерується автоматично, навіть для loopback) - Типова політика інструментів для нових локальних налаштувань: `tools.profile: "coding"` (наявний явно заданий профіль зберігається) - - Типова ізоляція DM: локальний онбординг записує `session.dmScope: "per-channel-peer"`, якщо значення не задано. Докладніше: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals) - - Доступ через Tailscale **Вимкнено** - - Для Telegram і WhatsApp DM за замовчуванням використовується **allowlist** (вам запропонують ввести свій номер телефону) + - Типове ізолювання DM: локальний онбординг записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено. Докладніше: [CLI Setup Reference](/uk/start/wizard-cli-reference#outputs-and-internals) + - Експозиція Tailscale **Вимкнена** + - Telegram і WhatsApp DM за замовчуванням мають режим **allowlist** (вам запропонують вказати ваш номер телефону) - - Показує кожен крок (режим, робочий простір, gateway, канали, демон, Skills). + - Відкриває всі кроки (режим, workspace, gateway, канали, daemon, Skills). ## Що налаштовує онбординг -**Локальний режим (типовий)** проводить вас через такі кроки: +**Локальний режим (за замовчуванням)** проводить вас через такі кроки: -1. **Model/Auth** — виберіть будь-який підтримуваний потік провайдера/автентифікації (API key, OAuth або специфічну для провайдера ручну автентифікацію), включно з Custom Provider - (сумісний з OpenAI, сумісний з Anthropic або Unknown auto-detect). Виберіть типову модель. - Примітка з безпеки: якщо цей агент запускатиме інструменти або оброблятиме вміст webhook/hooks, віддавайте перевагу найсильнішій доступній моделі останнього покоління та дотримуйтеся суворої політики інструментів. Слабші/старіші рівні легше піддаються prompt injection. - Для неінтерактивних запусків `--secret-input-mode ref` зберігає env-backed ref у профілях автентифікації замість простих текстових значень API key. - У неінтерактивному режимі `ref` env var провайдера має бути встановлено; передавання inline key flags без цього env var одразу завершується помилкою. - В інтерактивних запусках вибір режиму secret reference дозволяє вказати або на environment variable, або на налаштований ref провайдера (`file` або `exec`), зі швидкою попередньою перевіркою перед збереженням. - Для Anthropic інтерактивний onboarding/configure пропонує **Anthropic Claude CLI** як локальний резервний варіант і **Anthropic API key** як рекомендований шлях для production. Anthropic setup-token також знову доступний як застарілий/ручний шлях OpenClaw, з очікуванням специфічного для OpenClaw тарифікаційного режиму Anthropic **Extra Usage**. -2. **Workspace** — розташування для файлів агента (типово `~/.openclaw/workspace`). Ініціалізує bootstrap-файли. -3. **Gateway** — порт, bind address, режим автентифікації, доступ через Tailscale. - В інтерактивному режимі token ви можете вибрати типове зберігання plaintext token або перейти на SecretRef. - Шлях SecretRef token у неінтерактивному режимі: `--gateway-token-ref-env `. -4. **Channels** — вбудовані та комплектні канали чату, такі як BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp та інші. -5. **Daemon** — установлює LaunchAgent (macOS), systemd user unit (Linux/WSL2) або нативне Windows Scheduled Task із резервним варіантом per-user Startup-folder. - Якщо для token auth потрібен токен і `gateway.auth.token` керується через SecretRef, установлення демона перевіряє його, але не зберігає розв’язаний токен у метаданих середовища сервісу супервізора. - Якщо для token auth потрібен токен, а налаштований token SecretRef не розв’язується, установлення демона блокується з практичними вказівками. - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення демона блокується, доки режим не буде явно встановлено. -6. **Health check** — запускає Gateway і перевіряє, що він працює. +1. **Модель/автентифікація** — виберіть будь-який підтримуваний сценарій провайдера/автентифікації (API key, OAuth або ручна автентифікація, специфічна для провайдера), включно з Custom Provider + (OpenAI-compatible, Anthropic-compatible або Unknown auto-detect). Виберіть модель за замовчуванням. + Примітка щодо безпеки: якщо цей агент виконуватиме інструменти або оброблятиме вміст webhook/hooks, віддавайте перевагу найсильнішій доступній моделі останнього покоління та зберігайте сувору політику інструментів. Слабші/старіші рівні легше піддаються prompt injection. + Для неінтерактивних запусків `--secret-input-mode ref` зберігає env-backed refs у профілях автентифікації замість відкритих значень API key. + У неінтерактивному режимі `ref` змінна середовища провайдера має бути встановлена; передавання вбудованих прапорців ключів без цієї env var призводить до негайної помилки. + В інтерактивних запусках вибір режиму secret reference дозволяє вказати або змінну середовища, або налаштований ref провайдера (`file` або `exec`), із швидкою попередньою перевіркою перед збереженням. + Для Anthropic інтерактивний onboarding/configure пропонує **Anthropic Claude CLI** як бажаний локальний шлях і **Anthropic API key** як рекомендований шлях для production. Anthropic setup-token також залишається доступним як підтримуваний шлях автентифікації токеном. +2. **Workspace** — розташування для файлів агента (за замовчуванням `~/.openclaw/workspace`). Створює початкові bootstrap-файли. +3. **Gateway** — порт, bind address, режим автентифікації, експозиція Tailscale. + В інтерактивному режимі token виберіть стандартне зберігання токена у відкритому вигляді або увімкніть SecretRef. + Неінтерактивний шлях SecretRef для token: `--gateway-token-ref-env `. +4. **Канали** — вбудовані та комплектні чат-канали, такі як BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp тощо. +5. **Daemon** — встановлює LaunchAgent (macOS), systemd user unit (Linux/WSL2) або нативне Windows Scheduled Task із резервним варіантом через Startup folder для кожного користувача. + Якщо для token auth потрібен token, а `gateway.auth.token` керується через SecretRef, встановлення daemon перевіряє його, але не зберігає визначений token у метаданих середовища сервісу supervisor. + Якщо для token auth потрібен token, а налаштований token SecretRef не визначається, встановлення daemon блокується з практичними вказівками. + Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, встановлення daemon блокується, доки режим не буде явно задано. +6. **Перевірка працездатності** — запускає Gateway і перевіряє, що він працює. 7. **Skills** — установлює рекомендовані Skills і необов’язкові залежності. Повторний запуск онбордингу **не** стирає нічого, якщо ви явно не виберете **Reset** (або не передасте `--reset`). -Для CLI `--reset` за замовчуванням охоплює config, credentials і sessions; використовуйте `--reset-scope full`, щоб також включити workspace. -Якщо config недійсний або містить застарілі ключі, онбординг попросить вас спочатку запустити `openclaw doctor`. +CLI `--reset` за замовчуванням скидає config, credentials і sessions; використовуйте `--reset-scope full`, щоб також включити workspace. +Якщо config недійсний або містить застарілі ключі, онбординг попросить вас спочатку виконати `openclaw doctor`. -**Віддалений режим** лише налаштовує локальний клієнт для підключення до Gateway в іншому місці. -Він **не** встановлює і **не** змінює нічого на віддаленому хості. +**Віддалений режим** налаштовує лише локальний клієнт для підключення до Gateway в іншому місці. +Він **не** встановлює та не змінює нічого на віддаленому хості. ## Додати ще одного агента -Використовуйте `openclaw agents add `, щоб створити окремого агента з власним робочим простором, -сесіями та профілями автентифікації. Запуск без `--workspace` запускає онбординг. +Використовуйте `openclaw agents add `, щоб створити окремого агента з власними workspace, +sessions і профілями автентифікації. Запуск без `--workspace` запускає онбординг. -Що це встановлює: +Що він встановлює: - `agents.list[].name` - `agents.list[].workspace` @@ -114,21 +114,21 @@ API key, а інші працюють без ключа. Ви також мож Примітки: -- Типові робочі простори мають формат `~/.openclaw/workspace-`. +- Workspace за замовчуванням мають формат `~/.openclaw/workspace-`. - Додайте `bindings`, щоб маршрутизувати вхідні повідомлення (онбординг може це зробити). -- Прапори неінтерактивного режиму: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. +- Неінтерактивні прапорці: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. -## Повна довідка +## Повний довідник -Детальні покрокові описи та вихідні config дивіться в -[CLI Setup Reference](/start/wizard-cli-reference). -Неінтерактивні приклади дивіться в [CLI Automation](/start/wizard-cli-automation). -Глибшу технічну довідку, включно з деталями RPC, дивіться в -[Onboarding Reference](/reference/wizard). +Докладні покрокові розбори й результати config див. у +[CLI Setup Reference](/uk/start/wizard-cli-reference). +Неінтерактивні приклади див. у [CLI Automation](/uk/start/wizard-cli-automation). +Глибший технічний довідник, включно з деталями RPC, див. у +[Onboarding Reference](/uk/reference/wizard). ## Пов’язана документація -- Довідка з команди CLI: [`openclaw onboard`](/cli/onboard) -- Огляд онбордингу: [Onboarding Overview](/start/onboarding-overview) -- Онбординг застосунку macOS: [Onboarding](/start/onboarding) -- Ритуал першого запуску агента: [Agent Bootstrapping](/start/bootstrapping) +- Довідник команд CLI: [`openclaw onboard`](/cli/onboard) +- Огляд онбордингу: [Onboarding Overview](/uk/start/onboarding-overview) +- Онбординг застосунку macOS: [Onboarding](/uk/start/onboarding) +- Ритуал першого запуску агента: [Agent Bootstrapping](/uk/start/bootstrapping) diff --git a/docs/uk/tools/media-overview.md b/docs/uk/tools/media-overview.md new file mode 100644 index 000000000..a3a42602d --- /dev/null +++ b/docs/uk/tools/media-overview.md @@ -0,0 +1,67 @@ +--- +read_when: + - Пошук огляду можливостей роботи з медіа + - Визначення, якого постачальника медіа налаштувати + - Розуміння того, як працює асинхронна генерація медіа +summary: Уніфікована цільова сторінка для можливостей генерації медіа, розуміння медіа та мовлення +title: Огляд медіа +x-i18n: + generated_at: "2026-04-06T15:31:41Z" + model: gpt-5.4 + provider: openai + source_hash: cfee08eb91ec3e827724c8fa99bff7465356f6f1ac1b146562f35651798e3fd6 + source_path: tools/media-overview.md + workflow: 15 +--- + +# Генерація та розуміння медіа + +OpenClaw генерує зображення, відео та музику, розуміє вхідні медіа (зображення, аудіо, відео) і озвучує відповіді за допомогою синтезу мовлення з тексту. Усі медіаможливості керуються інструментами: агент сам вирішує, коли їх використовувати, на основі розмови, і кожен інструмент з’являється лише тоді, коли налаштовано принаймні одного базового постачальника. + +## Можливості з першого погляду + +| Можливість | Інструмент | Постачальники | Що робить | +| -------------------- | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ | +| Генерація зображень | `image_generate` | ComfyUI, fal, Google, MiniMax, OpenAI, Vydra | Створює або редагує зображення з текстових запитів чи референсів | +| Генерація відео | `video_generate` | Alibaba, BytePlus, ComfyUI, fal, Google, MiniMax, OpenAI, Qwen, Runway, Together, Vydra, xAI | Створює відео з тексту, зображень або наявних відео | +| Генерація музики | `music_generate` | ComfyUI, Google, MiniMax | Створює музику або аудіодоріжки з текстових запитів | +| Синтез мовлення (TTS) | `tts` | ElevenLabs, Microsoft, MiniMax, OpenAI | Перетворює вихідні відповіді на озвучене аудіо | +| Розуміння медіа | (автоматично) | Будь-який постачальник моделей із підтримкою vision/audio, а також резервні варіанти CLI | Підсумовує вхідні зображення, аудіо та відео | + +## Матриця можливостей постачальників + +Ця таблиця показує, які постачальники підтримують які медіаможливості на платформі. + +| Постачальник | Зображення | Відео | Музика | TTS | STT / Транскрипція | Розуміння медіа | +| ---------- | ----- | ----- | ----- | --- | ------------------- | ------------------- | +| Alibaba | | Yes | | | | | +| BytePlus | | Yes | | | | | +| ComfyUI | Yes | Yes | Yes | | | | +| Deepgram | | | | | Yes | | +| ElevenLabs | | | | Yes | | | +| fal | Yes | Yes | | | | | +| Google | Yes | Yes | Yes | | | Yes | +| Microsoft | | | | Yes | | | +| MiniMax | Yes | Yes | Yes | Yes | | | +| OpenAI | Yes | Yes | | Yes | Yes | Yes | +| Qwen | | Yes | | | | | +| Runway | | Yes | | | | | +| Together | | Yes | | | | | +| Vydra | Yes | Yes | | | | | +| xAI | | Yes | | | | | + + +Розуміння медіа використовує будь-яку модель із підтримкою vision або audio, зареєстровану у вашій конфігурації постачальника. У таблиці вище виділено постачальників зі спеціалізованою підтримкою розуміння медіа; більшість постачальників LLM із мультимодальними моделями (Anthropic, Google, OpenAI тощо) також можуть розуміти вхідні медіа, якщо їх налаштовано як активну модель відповіді. + + +## Як працює асинхронна генерація + +Генерація відео та музики виконується як фонові завдання, оскільки обробка в постачальника зазвичай триває від 30 секунд до кількох хвилин. Коли агент викликає `video_generate` або `music_generate`, OpenClaw надсилає запит постачальнику, одразу повертає ID завдання та відстежує роботу в реєстрі завдань. Агент продовжує відповідати на інші повідомлення, поки виконується завдання. Коли постачальник завершує обробку, OpenClaw пробуджує агента, щоб той міг опублікувати готовий медіафайл назад у вихідний канал. Генерація зображень і TTS є синхронними та завершуються в межах відповіді. + +## Швидкі посилання + +- [Image Generation](/uk/tools/image-generation) -- генерація та редагування зображень +- [Video Generation](/uk/tools/video-generation) -- text-to-video, image-to-video і video-to-video +- [Music Generation](/uk/tools/music-generation) -- створення музики та аудіодоріжок +- [Text-to-Speech](/uk/tools/tts) -- перетворення відповідей на озвучене аудіо +- [Media Understanding](/uk/nodes/media-understanding) -- розуміння вхідних зображень, аудіо та відео diff --git a/docs/uk/tools/music-generation.md b/docs/uk/tools/music-generation.md index 003d8b52d..c95316938 100644 --- a/docs/uk/tools/music-generation.md +++ b/docs/uk/tools/music-generation.md @@ -1,41 +1,41 @@ --- read_when: - - Генерація музики або аудіо через агента + - Генерування музики або аудіо через агента - Налаштування провайдерів і моделей для генерації музики - - Розуміння параметрів інструмента `music_generate` -summary: Генеруйте музику за допомогою спільних провайдерів, включно з плагінами на основі workflow + - Розуміння параметрів інструмента music_generate +summary: Генеруйте музику через спільних провайдерів, зокрема плагіни на основі workflow title: Генерація музики x-i18n: - generated_at: "2026-04-06T01:46:19Z" + generated_at: "2026-04-06T15:32:09Z" model: gpt-5.4 provider: openai - source_hash: a03de8aa75cfb7248eb0c1d969fb2a6da06117967d097e6f6e95771d0f017ae1 + source_hash: 5a2c95d087d6d0b5f4aaaae2fc1f98d683cbb4991d08ed6cabae45c90519ec0c source_path: tools/music-generation.md workflow: 15 --- # Генерація музики -Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через +Інструмент `music_generate` дає змогу агенту створювати музику або аудіо через спільну можливість генерації музики з налаштованими провайдерами, такими як Google, MiniMax і налаштований через workflow ComfyUI. -Для сеансів агента на основі спільного провайдера OpenClaw запускає генерацію музики як -фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента, коли -трек готовий, щоб агент міг опублікувати готове аудіо назад у +Для сесій агентів, що працюють через спільних провайдерів, OpenClaw запускає генерацію музики як +фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли трек готовий, +щоб агент міг надіслати готове аудіо назад у початковий канал. -Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або вкажіть API-ключ провайдера. +Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API key провайдера. ## Швидкий старт -### Генерація на основі спільного провайдера +### Генерація через спільних провайдерів -1. Установіть API-ключ принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або +1. Задайте API key принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або `MINIMAX_API_KEY`. -2. За потреби встановіть бажану модель: +2. За бажанням задайте бажану модель: ```json5 { @@ -49,22 +49,22 @@ MiniMax і налаштований через workflow ComfyUI. } ``` -3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку - крізь неонове місто."_ +3. Попросіть агента: _"Створи бадьорий synthpop-трек про нічну поїздку + через неонове місто."_ -Агент викликає `music_generate` автоматично. Додавати інструмент до списку дозволених не потрібно. +Агент автоматично викликає `music_generate`. Додавати інструмент до allow-list не потрібно. -Для прямих синхронних контекстів без запуску агента на основі сеансу вбудований -інструмент усе одно повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу в результаті інструмента. +Для прямих синхронних контекстів без запуску агента на основі сесії вбудований +інструмент все одно повертається до inline-генерації та повертає фінальний шлях до медіафайлу в результаті інструмента. Приклади запитів: ```text -Згенеруй кінематографічний фортепіанний трек із м’якими струнними та без вокалу. +Generate a cinematic piano track with soft strings and no vocals. ``` ```text -Згенеруй енергійну chiptune-петлю про запуск ракети на світанку. +Generate an energetic chiptune loop about launching a rocket at sunrise. ``` ### Генерація Comfy на основі workflow @@ -72,33 +72,44 @@ MiniMax і налаштований через workflow ComfyUI. Вбудований плагін `comfy` підключається до спільного інструмента `music_generate` через реєстр провайдерів генерації музики. -1. Налаштуйте `models.providers.comfy.music` за допомогою JSON workflow та - вузлів prompt/output. -2. Якщо ви використовуєте Comfy Cloud, установіть `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. -3. Попросіть агента створити музику або викличте інструмент безпосередньо. +1. Налаштуйте `models.providers.comfy.music` із JSON workflow і + вузлами prompt/output. +2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. +3. Попросіть агента створити музику або викличте інструмент напряму. Приклад: ```text -/tool music_generate prompt="Тепла ембієнтна synth-петля з м’якою текстурою стрічки" +/tool music_generate prompt="Warm ambient synth loop with soft tape texture" ``` ## Підтримка спільних вбудованих провайдерів -| Провайдер | Модель за замовчуванням | Еталонні входи | Підтримувані елементи керування | API-ключ | -| --------- | ----------------------- | -------------- | ----------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | До 1 зображення | Визначена workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | -| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | +| Провайдер | Типова модель | Вхідні референси | Підтримувані елементи керування | API key | +| -------- | ---------------------- | ---------------- | ----------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | До 1 зображення | Визначені workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | -Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі -під час виконання: +### Матриця заявлених можливостей + +Це явний контракт режимів, який використовують `music_generate`, тести контрактів +і спільний live sweep. + +| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live lanes | +| -------- | ---------- | ------ | ----------------- | ------------------------------------------------------------------------- | +| ComfyUI | Так | Так | 1 зображення | Не входить до спільного sweep; покривається `extensions/comfy/comfy.live.test.ts` | +| Google | Так | Так | 10 зображень | `generate`, `edit` | +| MiniMax | Так | Ні | Немає | `generate` | + +Використовуйте `action: "list"`, щоб переглянути доступних спільних провайдерів і моделі +під час runtime: ```text /tool music_generate action=list ``` -Використовуйте `action: "status"`, щоб переглянути активне завдання музики на основі сеансу: +Використовуйте `action: "status"`, щоб перевірити активне завдання генерації музики, пов’язане із сесією: ```text /tool music_generate action=status @@ -107,39 +118,58 @@ MiniMax і налаштований через workflow ComfyUI. Приклад прямої генерації: ```text -/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та ніжним дощем" instrumental=true +/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true ``` ## Параметри вбудованого інструмента -| Параметр | Тип | Опис | -| ---------------- | -------- | ------------------------------------------------------------------------------------------------- | -| `prompt` | string | Запит на генерацію музики (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (за замовчуванням), `"status"` для поточного завдання сеансу або `"list"` для перегляду провайдерів | -| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | -| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту | -| `instrumental` | boolean | Запит лише на інструментальний результат, якщо провайдер це підтримує | -| `image` | string | Шлях або URL одного еталонного зображення | -| `images` | string[] | Кілька еталонних зображень (до 10) | -| `durationSeconds`| number | Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості | -| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо провайдер це підтримує | -| `filename` | string | Підказка щодо імені вихідного файлу | +| Параметр | Тип | Опис | +| ----------------- | -------- | ---------------------------------------------------------------------------------------------- | +| `prompt` | string | Prompt для генерації музики (обов’язковий для `action: "generate"`) | +| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії або `"list"` для перегляду провайдерів | +| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | +| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту | +| `instrumental` | boolean | Запросити лише інструментальний результат, якщо провайдер це підтримує | +| `image` | string | Шлях або URL одного референсного зображення | +| `images` | string[] | Кілька референсних зображень (до 10) | +| `durationSeconds` | number | Бажана тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості | +| `format` | string | Підказка формату виводу (`mp3` або `wav`), якщо провайдер це підтримує | +| `filename` | string | Підказка імені вихідного файлу | Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження, -як-от кількість входів, перед надсиланням, але непідтримувані необов’язкові підказки -ігноруються з попередженням, якщо вибраний провайдер або модель не можуть їх виконати. +наприклад кількість вхідних даних, перед надсиланням, але непідтримувані необов’язкові підказки +ігноруються з попередженням, якщо вибраний провайдер або модель не можуть їх обробити. -## Асинхронна поведінка для шляху на основі спільного провайдера +## Асинхронна поведінка для шляху через спільних провайдерів -- Запуски агента на основі сеансу: `music_generate` створює фонове завдання, негайно повертає відповідь started/task і публікує готовий трек пізніше в наступному повідомленні агента. -- Запобігання дублюванню: поки це фонове завдання все ще має стан `queued` або `running`, наступні виклики `music_generate` у тому самому сеансі повертають стан завдання замість запуску нової генерації. -- Перегляд стану: використовуйте `action: "status"`, щоб переглянути активне музичне завдання на основі сеансу без запуску нового. -- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати статуси queued, running і terminal для генерації. -- Пробудження після завершення: OpenClaw впроваджує внутрішню подію завершення назад у той самий сеанс, щоб модель могла самостійно написати користувацьке подальше повідомлення. -- Підказка в prompt: пізніші користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку часу виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` знову бездумно. -- Режим без сеансу: прямі/локальні контексти без реального сеансу агента все одно виконуються вбудовано й повертають фінальний результат аудіо в тому самому ході. +- Запуски агента на основі сесії: `music_generate` створює фонове завдання, негайно повертає відповідь про запуск/завдання і пізніше надсилає готовий трек в окремому повідомленні агента. +- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають стан завдання замість запуску нової генерації. +- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерації музики, пов’язане із сесією, без запуску нового. +- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити статуси queued, running і terminal для генерації. +- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у ту саму сесію, щоб модель сама могла написати користувацьке follow-up-повідомлення. +- Підказка для prompt: наступні користувацькі/ручні ходи в тій самій сесії отримують невелику runtime-підказку, коли завдання генерації музики вже виконується, щоб модель не викликала `music_generate` знову навмання. +- Fallback без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються inline і повертають фінальний аудіорезультат у тому самому ході. -## Налаштування +### Життєвий цикл завдання + +Кожен запит `music_generate` проходить через чотири стани: + +1. **queued** -- завдання створено, очікує, поки провайдер його прийме. +2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості). +3. **succeeded** -- трек готовий; агент пробуджується й публікує його в розмові. +4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. + +Перевірка стану через CLI: + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +Запобігання дублюванню: якщо для поточної сесії вже є завдання музики зі станом `queued` або `running`, `music_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб перевірити це явно без запуску нової генерації. + +## Конфігурація ### Вибір моделі @@ -156,37 +186,67 @@ MiniMax і налаштований через workflow ComfyUI. } ``` -### Порядок вибору провайдера +### Порядок вибору провайдерів -Під час генерації музики OpenClaw намагається використати провайдерів у такому порядку: +Під час генерації музики OpenClaw пробує провайдерів у такому порядку: -1. параметр `model` із виклику інструмента, якщо агент його вказує +1. параметр `model` із виклику інструмента, якщо агент його задає 2. `musicGenerationModel.primary` із конфігурації -3. `musicGenerationModel.fallbacks` у заданому порядку -4. Автовиявлення з використанням лише стандартних значень провайдерів на основі auth: - - спочатку поточний провайдер за замовчуванням - - решта зареєстрованих провайдерів генерації музики в порядку provider-id +3. `musicGenerationModel.fallbacks` по порядку +4. Автовиявлення з використанням лише типових значень провайдера на основі auth: + - спочатку поточний типовий провайдер + - потім решта зареєстрованих провайдерів генерації музики в порядку provider-id -Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, -помилка містить подробиці кожної спроби. +Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі спроби завершуються помилкою, +повідомлення про помилку містить подробиці кожної спроби. ## Примітки щодо провайдерів - Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує - prompt, необов’язковий текст lyrics і необов’язкові еталонні зображення. + prompt, необов’язковий текст пісні та необов’язкові референсні зображення. - MiniMax використовує пакетний endpoint `music_generation`. Поточний вбудований потік - підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та + підтримує prompt, необов’язковий текст пісні, інструментальний режим, керування тривалістю та вивід у mp3. -- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та +- Підтримка ComfyUI базується на workflow і залежить від налаштованого графа та зіставлення вузлів для полів prompt/output. -## Вибір правильного шляху +## Режими можливостей провайдерів -- Використовуйте шлях на основі спільного провайдера, якщо вам потрібні вибір моделі, відмовостійке перемикання між провайдерами та вбудований асинхронний потік завдань/стану. -- Використовуйте шлях плагіна, наприклад ComfyUI, якщо вам потрібен власний граф workflow або провайдер, який не входить до спільної вбудованої можливості музики. -- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). +Спільний контракт генерації музики тепер підтримує явне оголошення режимів: -## Живі тести +- `generate` для генерації лише за prompt +- `edit`, коли запит містить одне або кілька референсних зображень + +Нові реалізації провайдерів мають віддавати перевагу явним блокам режимів: + +```typescript +capabilities: { + generate: { + maxTracks: 1, + supportsLyrics: true, + supportsFormat: true, + }, + edit: { + enabled: true, + maxTracks: 1, + maxInputImages: 1, + supportsFormat: true, + }, +} +``` + +Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і +`supportsFormat`, недостатньо, щоб оголосити підтримку редагування. Провайдери мають +явно оголошувати `generate` і `edit`, щоб live-тести, тести контрактів і +спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів. + +## Як вибрати правильний шлях + +- Використовуйте шлях через спільних провайдерів, якщо вам потрібні вибір моделі, failover провайдерів і вбудований асинхронний потік завдань/стану. +- Використовуйте шлях плагіна, наприклад ComfyUI, якщо вам потрібен спеціальний граф workflow або провайдер, який не входить до спільної вбудованої можливості генерації музики. +- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільних провайдерів, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). + +## Live-тести Добровільне live-покриття для спільних вбудованих провайдерів: @@ -194,13 +254,23 @@ MiniMax і налаштований через workflow ComfyUI. OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts ``` +Цей live-файл завантажує відсутні env vars провайдера з `~/.profile`, типово надає +перевагу live/env API keys над збереженими профілями auth і запускає покриття +як `generate`, так і оголошеного `edit`, коли провайдер вмикає режим редагування. + +Сьогодні це означає: + +- `google`: `generate` плюс `edit` +- `minimax`: лише `generate` +- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів + Добровільне live-покриття для вбудованого музичного шляху ComfyUI: ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Файл Comfy live також охоплює workflow зображень і відео comfy, коли ці +Файл live-тестів Comfy також покриває workflow зображень і відео Comfy, коли ці розділи налаштовані. ## Пов’язане @@ -210,5 +280,5 @@ OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy. - [ComfyUI](/uk/providers/comfy) - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax) -- [Моделі](/uk/concepts/models) - конфігурація моделей і перемикання при відмові -- [Огляд інструментів](/uk/tools) +- [Моделі](/uk/concepts/models) - конфігурація моделей і failover +- [Огляд tools](/uk/tools) diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index 699ad19a4..da0f1f658 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -1,34 +1,35 @@ --- read_when: - Генерація відео через агента - - Налаштування провайдерів і моделей для генерації відео - - Розуміння параметрів інструмента video_generate -summary: Генеруйте відео з тексту, зображень або наявних відео за допомогою 12 бекендів провайдерів + - Налаштування провайдерів і моделей генерації відео + - Розуміння параметрів інструмента `video_generate` +summary: Генерація відео з тексту, зображень або наявних відео за допомогою 12 бекендів провайдерів title: Генерація відео x-i18n: - generated_at: "2026-04-06T12:27:58Z" + generated_at: "2026-04-06T15:32:24Z" model: gpt-5.4 provider: openai - source_hash: a224c0a1bd6fe61592ac22ad9a65f0ae25a378a12b79c1210f2e7101886798bb + source_hash: 7d995d91f86f863f5a69c6945043dc430eb186830348a09eeaaad94620767f7d source_path: tools/video-generation.md workflow: 15 --- # Генерація відео -Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або наявних відео. Підтримуються дванадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає відповідного провайдера на основі вашої конфігурації та доступних API-ключів. +Агенти OpenClaw можуть генерувати відео з текстових промптів, еталонних зображень або наявних відео. Підтримуються дванадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає правильного провайдера на основі вашої конфігурації та доступних API-ключів. -Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви його не бачите серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. +Інструмент `video_generate` з’являється лише тоді, коли доступний щонайменше один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. -OpenClaw розглядає генерацію відео як три режими виконання: +OpenClaw розглядає генерацію відео як три режими runtime: -- `generate` для запитів текст-у-відео без еталонного медіа +- `generate` для запитів text-to-video без еталонних медіа - `imageToVideo`, коли запит містить одне або кілька еталонних зображень - `videoToVideo`, коли запит містить одне або кілька еталонних відео -Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний режим перед надсиланням і повідомляє підтримувані режими в `action=list`. +Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний +режим перед надсиланням і повідомляє підтримувані режими в `action=list`. ## Швидкий старт @@ -38,115 +39,155 @@ OpenClaw розглядає генерацію відео як три режим export GEMINI_API_KEY="your-key" ``` -2. За бажанням закріпіть модель за замовчуванням: +2. За потреби зафіксуйте типову модель: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` -3. Попросіть агента: +3. Дайте агенту запит: -> Згенеруй 5-секундне кінематографічне відео доброзичливого лобстера, який займається серфінгом на заході сонця. +> Згенеруй 5-секундне кінематографічне відео з дружнім лобстером, який займається серфінгом на заході сонця. -Агент автоматично викликає `video_generate`. Додавання інструмента до списку дозволених не потрібне. +Агент автоматично викликає `video_generate`. Дозволений список інструментів не потрібен. -## Що відбувається, коли ви генеруєте відео +## Що відбувається під час генерації відео Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії: -1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання. +1. OpenClaw надсилає запит провайдеру й одразу повертає ID завдання. 2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). 3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення. 4. Агент публікує готове відео назад у вихідну розмову. -Поки завдання виконується, повторні виклики `video_generate` у тій самій сесії повертають поточний стан завдання замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити хід виконання через CLI. +Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан завдання замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевіряти прогрес із CLI. -Поза запусками агента на основі сесій (наприклад, під час прямих викликів інструмента) інструмент повертається до вбудованої генерації та повертає остаточний шлях до медіафайлу в тому самому ході. +Поза агентськими запусками, що підтримуються сесією (наприклад, прямі виклики інструментів), інструмент переходить до вбудованої генерації й повертає фінальний шлях до медіа в тому самому ході. + +### Життєвий цикл завдання + +Кожен запит `video_generate` проходить через чотири стани: + +1. **queued** -- завдання створено, очікує, поки провайдер прийме його. +2. **running** -- провайдер виконує обробку (зазвичай 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). +3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову. +4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. + +Перевірка стану з CLI: + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +Запобігання дублюванню: якщо для поточної сесії завдання відео вже має стан `queued` або `running`, `video_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Текст | Еталонне зображення | Еталонне відео | API-ключ | -| --------- | ------------------------------- | ----- | ------------------- | --------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Так | 1 зображення | Ні | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Так | 1 зображення | 1 відео | `XAI_API_KEY` | +| Provider | Типова модель | Текст | Еталонне зображення | Еталонне відео | API key | +| -------- | ------------------------------ | ----- | ------------------- | --------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | Yes | Yes (віддалений URL) | Yes (віддалений URL) | `MODELSTUDIO_API_KEY` | +| BytePlus | `seedance-1-0-lite-t2v-250428` | Yes | 1 зображення | No | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Yes | 1 зображення | No | `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Yes | 1 зображення | No | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Yes | 1 зображення | 1 відео | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Yes | 1 зображення | No | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Yes | 1 зображення | 1 відео | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Yes | Yes (віддалений URL) | Yes (віддалений URL) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Yes | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Yes | 1 зображення | No | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Yes | 1 зображення (`kling`) | No | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Yes | 1 зображення | 1 відео | `XAI_API_KEY` | -Деякі провайдери приймають додаткові або альтернативні змінні середовища API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related). +Деякі провайдери приймають додаткові або альтернативні env vars API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related). -Запустіть `video_generate action=list`, щоб у середовищі виконання переглянути доступних провайдерів, моделі та режими виконання. +Виконайте `video_generate action=list`, щоб під час runtime переглянути доступних провайдерів, моделі та +режими runtime. + +### Матриця заявлених можливостей + +Це явний контракт режимів, який використовують `video_generate`, контрактні тести +та спільний live sweep. + +| Provider | `generate` | `imageToVideo` | `videoToVideo` | Поточні спільні live lanes | +| -------- | ---------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | +| Alibaba | Yes | Yes | Yes | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| BytePlus | Yes | Yes | No | `generate`, `imageToVideo` | +| ComfyUI | Yes | Yes | No | Не входить до спільного sweep; специфічне для workflow покриття живе разом із тестами Comfy | +| fal | Yes | Yes | No | `generate`, `imageToVideo` | +| Google | Yes | Yes | Yes | `generate`, `imageToVideo`, `videoToVideo` | +| MiniMax | Yes | Yes | No | `generate`, `imageToVideo` | +| OpenAI | Yes | Yes | Yes | `generate`, `imageToVideo`, `videoToVideo` | +| Qwen | Yes | Yes | Yes | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| Runway | Yes | Yes | Yes | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | +| Together | Yes | Yes | No | `generate`, `imageToVideo` | +| Vydra | Yes | Yes | No | `generate`, `imageToVideo` | +| xAI | Yes | Yes | Yes | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру зараз потрібен віддалений URL MP4 | ## Параметри інструмента ### Обов’язкові -| Параметр | Тип | Опис | -| -------- | ------ | ---------------------------------------------------------------------------- | -| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | +| Parameter | Type | Description | +| --------- | ------ | --------------------------------------------------------------------------- | +| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | -### Вхідні дані контенту +### Вхідний контент -| Параметр | Тип | Опис | -| -------- | -------- | ------------------------------------- | -| `image` | string | Одне еталонне зображення (шлях або URL) | -| `images` | string[] | Кілька еталонних зображень (до 5) | -| `video` | string | Одне еталонне відео (шлях або URL) | -| `videos` | string[] | Кілька еталонних відео (до 4) | +| Parameter | Type | Description | +| --------- | -------- | -------------------------------------- | +| `image` | string | Одне еталонне зображення (шлях або URL) | +| `images` | string[] | Кілька еталонних зображень (до 5) | +| `video` | string | Одне еталонне відео (шлях або URL) | +| `videos` | string[] | Кілька еталонних відео (до 4) | ### Керування стилем -| Параметр | Тип | Опис | +| Parameter | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------ | | `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | | `resolution` | string | `480P`, `720P` або `1080P` | | `durationSeconds` | number | Цільова тривалість у секундах (округлюється до найближчого значення, підтримуваного провайдером) | -| `size` | string | Підказка щодо розміру, коли провайдер це підтримує | +| `size` | string | Підказка розміру, якщо провайдер це підтримує | | `audio` | boolean | Увімкнути згенероване аудіо, якщо підтримується | -| `watermark` | boolean | Увімкнути або вимкнути водяний знак провайдера, якщо підтримується | +| `watermark` | boolean | Увімкнути або вимкнути водяний знак провайдера, якщо підтримується | -### Додатково +### Розширені -| Параметр | Тип | Опис | -| --------- | ------ | ------------------------------------------------ | -| `action` | string | `"generate"` (типово), `"status"` або `"list"` | -| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) | -| `filename` | string | Підказка щодо назви вихідного файла | +| Parameter | Type | Description | +| ---------- | ------ | ------------------------------------------------ | +| `action` | string | `"generate"` (типово), `"status"` або `"list"` | +| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) | +| `filename` | string | Підказка для назви вихідного файла | -Не всі провайдери підтримують усі параметри. Непідтримувані перевизначення ігноруються на основі найкращих зусиль і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто велика кількість еталонних входів) призводять до помилки ще до надсилання. +Не всі провайдери підтримують усі параметри. Непідтримувані перевизначення ігноруються в режимі best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто багато еталонних входів) призводять до помилки ще до надсилання. -Еталонні входи також визначають режим виконання: +Еталонні входи також визначають режим runtime: -- Без еталонного медіа: `generate` +- Немає еталонних медіа: `generate` - Будь-яке еталонне зображення: `imageToVideo` - Будь-яке еталонне відео: `videoToVideo` -Змішані еталонні зображення та відео не є стабільною спільною поверхнею можливостей. -Рекомендується використовувати один тип еталонів на запит. +Змішані еталонні зображення й відео не є стабільною спільною поверхнею можливостей. +Краще використовувати один тип еталона на запит. ## Дії -- **generate** (типово) -- створити відео з указаного запиту та необов’язкових еталонних входів. -- **status** -- перевірити стан активного завдання відео для поточної сесії без запуску нової генерації. -- **list** -- показати доступних провайдерів, моделі та їхні можливості. +- **generate** (типово) -- створює відео з указаного промпту та необов’язкових еталонних входів. +- **status** -- перевіряє стан поточного відеозавдання для поточної сесії без запуску нової генерації. +- **list** -- показує доступних провайдерів, моделі та їхні можливості. ## Вибір моделі Під час генерації відео OpenClaw визначає модель у такому порядку: -1. **`model` параметр інструмента** -- якщо агент указує його у виклику. +1. **Параметр інструмента `model`** -- якщо агент указав його у виклику. 2. **`videoGenerationModel.primary`** -- із конфігурації. -3. **`videoGenerationModel.fallbacks`** -- пробуються по черзі. -4. **Автовиявлення** -- використовує провайдерів, які мають дійсну авторизацію, починаючи з поточного провайдера за замовчуванням, а потім решту провайдерів в алфавітному порядку. +3. **`videoGenerationModel.fallbacks`** -- використовуються по черзі. +4. **Автовизначення** -- використовує провайдерів із дійсною автентифікацією, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку. -Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі кандидати завершуються помилкою, помилка міститиме деталі кожної спроби. +Якщо провайдер не спрацьовує, автоматично використовується наступний кандидат. Якщо всі кандидати не спрацювали, помилка містить деталі кожної спроби. ```json5 { @@ -163,26 +204,26 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 ## Примітки щодо провайдерів -| Провайдер | Примітки | -| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Використовує асинхронну кінцеву точку DashScope/Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`. | -| BytePlus | Лише одне еталонне зображення. | -| ComfyUI | Виконання локально або в хмарі на основі workflow. Підтримує текст-у-відео та зображення-у-відео через налаштований граф. | -| fal | Використовує потік, підкріплений чергою, для довготривалих завдань. Лише одне еталонне зображення. | -| Google | Використовує Gemini/Veo. Підтримує одне еталонне зображення або одне еталонне відео. | -| MiniMax | Лише одне еталонне зображення. | -| OpenAI | Передається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. | -| Qwen | Той самий бекенд DashScope, що й у Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли одразу відхиляються. | -| Runway | Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. | -| Together | Лише одне еталонне зображення. | -| Vydra | Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути переадресацій, які скидають авторизацію. `veo3` входить у комплект лише як text-to-video; `kling` вимагає віддалений URL зображення. | -| xAI | Підтримує text-to-video, image-to-video та віддалені потоки редагування/розширення відео. | +| Provider | Notes | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Використовує асинхронний endpoint DashScope/Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`. | +| BytePlus | Лише одне еталонне зображення. | +| ComfyUI | Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. | +| fal | Використовує потік на основі черги для довготривалих завдань. Лише одне еталонне зображення. | +| Google | Використовує Gemini/Veo. Підтримує одне еталонне зображення або одне еталонне відео. | +| MiniMax | Лише одне еталонне зображення. | +| OpenAI | Передається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. | +| Qwen | Той самий бекенд DashScope, що й Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли одразу відхиляються. | +| Runway | Підтримує локальні файли через data URI. Video-to-video потребує `runway/gen4_aleph`. Для суто текстових запусків доступні співвідношення сторін `16:9` і `9:16`. | +| Together | Лише одне еталонне зображення. | +| Vydra | Використовує `https://www.vydra.ai/api/v1` напряму, щоб уникнути редиректів, які скидають auth. `veo3` постачається лише як text-to-video; `kling` потребує віддаленого URL зображення. | +| xAI | Підтримує text-to-video, image-to-video та потоки віддаленого редагування/розширення відео. | ## Режими можливостей провайдерів -Спільний контракт генерації відео тепер дозволяє провайдерам оголошувати -можливості, специфічні для режиму, замість лише плоских агрегованих лімітів. Нові реалізації провайдерів -мають надавати перевагу явним блокам режимів: +Спільний контракт генерації відео тепер дає провайдерам змогу оголошувати +можливості для конкретних режимів, а не лише плоскі агреговані обмеження. Нові реалізації +провайдерів мають віддавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -206,13 +247,37 @@ capabilities: { } ``` -Застарілі плоскі поля, як-от `maxInputImages` і `maxInputVideos`, усе ще працюють як -зворотно сумісні агреговані обмеження, але вони не можуть так точно -виражати ліміти для окремих режимів. +Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо, +щоб оголосити підтримку режимів трансформації. Провайдери мають явно оголошувати +`generate`, `imageToVideo` і `videoToVideo`, щоб live-тести, +контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти підтримку режимів. + +## Live-тести + +Опціональне live-покриття для спільних вбудованих провайдерів: + +```bash +OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts +``` + +Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, типово +надає перевагу live/env API-ключам над збереженими профілями auth і запускає +заявлені режими, які можна безпечно перевірити з локальними медіа: + +- `generate` для кожного провайдера в sweep +- `imageToVideo`, коли `capabilities.imageToVideo.enabled` +- `videoToVideo`, коли `capabilities.videoToVideo.enabled` і провайдер/модель + приймає локальний відеовхід на основі буфера у спільному sweep + +Сьогодні спільний live lane `videoToVideo` покриває: + +- `google` +- `openai` +- `runway` лише коли ви вибираєте `runway/gen4_aleph` ## Конфігурація -Задайте модель генерації відео за замовчуванням у конфігурації OpenClaw: +Задайте типову модель генерації відео у своїй конфігурації OpenClaw: ```json5 { @@ -249,5 +314,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 - [Together AI](/uk/providers/together) - [Vydra](/uk/providers/vydra) - [xAI](/uk/providers/xai) -- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) +- [Довідник конфігурації](/uk/gateway/configuration-reference#agent-defaults) - [Моделі](/uk/concepts/models) diff --git a/docs/uk/tts.md b/docs/uk/tts.md index 3417c5a68..399881ed9 100644 --- a/docs/uk/tts.md +++ b/docs/uk/tts.md @@ -1,459 +1,13 @@ --- -read_when: - - Увімкнення text-to-speech для відповідей - - Налаштування TTS-провайдерів або обмежень - - Використання команд /tts -summary: Text-to-speech (TTS) для вихідних відповідей -title: Text-to-Speech (застарілий шлях) +redirect: /tools/tts +title: Синтез мовлення з тексту x-i18n: - generated_at: "2026-04-05T18:22:17Z" + generated_at: "2026-04-06T15:31:42Z" model: gpt-5.4 provider: openai - source_hash: acca61773996299a582ab88e5a5db12d8f22ce8a28292ce97cc5dd5fdc2d3b83 + source_hash: 0c9ace272aa9adff93c946ee6275f6eb314dc1fa5043e0a26ecb164c990c0c59 source_path: tts.md workflow: 15 --- -# Text-to-speech (TTS) - -OpenClaw може перетворювати вихідні відповіді на аудіо за допомогою ElevenLabs, Microsoft, MiniMax або OpenAI. -Це працює всюди, де OpenClaw може надсилати аудіо. - -## Підтримувані сервіси - -- **ElevenLabs** (основний або резервний провайдер) -- **Microsoft** (основний або резервний провайдер; поточна вбудована реалізація використовує `node-edge-tts`) -- **MiniMax** (основний або резервний провайдер; використовує API T2A v2) -- **OpenAI** (основний або резервний провайдер; також використовується для підсумків) - -### Примітки щодо speech від Microsoft - -Вбудований провайдер Microsoft speech наразі використовує онлайн-сервіс -нейронного TTS від Microsoft Edge через бібліотеку `node-edge-tts`. Це хостований сервіс (не -локальний), він використовує endpoints Microsoft і не потребує API key. -`node-edge-tts` надає параметри конфігурації speech і формати виводу, але -не всі параметри підтримуються сервісом. Застарілий config і директивний ввід -з `edge` усе ще працюють і нормалізуються до `microsoft`. - -Оскільки цей шлях є публічним вебсервісом без опублікованого SLA або квоти, -сприймайте його як best-effort. Якщо вам потрібні гарантовані ліміти й підтримка, використовуйте OpenAI -або ElevenLabs. - -## Необов’язкові ключі - -Якщо ви хочете використовувати OpenAI, ElevenLabs або MiniMax: - -- `ELEVENLABS_API_KEY` (або `XI_API_KEY`) -- `MINIMAX_API_KEY` -- `OPENAI_API_KEY` - -Microsoft speech **не** потребує API key. - -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші стають резервними варіантами. -Автопідсумок використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), -тому якщо ви вмикаєте підсумки, цей провайдер також має бути автентифікований. - -## Посилання на сервіси - -- [Посібник OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) -- [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) -- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) -- [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2) -- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - -## Чи увімкнено це типово? - -Ні. Авто‑TTS **вимкнено** типово. Увімкніть його в config через -`messages.tts.auto` або для окремої сесії через `/tts always` (псевдонім: `/tts on`). - -Коли `messages.tts.provider` не задано, OpenClaw вибирає першого налаштованого -speech-провайдера в порядку автозаповнення реєстру. - -## Config - -Config TTS знаходиться в `messages.tts` у `openclaw.json`. -Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration). - -### Мінімальний config (увімкнення + провайдер) - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "elevenlabs", - }, - }, -} -``` - -### OpenAI як основний провайдер із резервним ElevenLabs - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "openai", - summaryModel: "openai/gpt-4.1-mini", - modelOverrides: { - enabled: true, - }, - providers: { - openai: { - apiKey: "openai_api_key", - baseUrl: "https://api.openai.com/v1", - model: "gpt-4o-mini-tts", - voice: "alloy", - }, - elevenlabs: { - apiKey: "elevenlabs_api_key", - baseUrl: "https://api.elevenlabs.io", - voiceId: "voice_id", - modelId: "eleven_multilingual_v2", - seed: 42, - applyTextNormalization: "auto", - languageCode: "en", - voiceSettings: { - stability: 0.5, - similarityBoost: 0.75, - style: 0.0, - useSpeakerBoost: true, - speed: 1.0, - }, - }, - }, - }, - }, -} -``` - -### Microsoft як основний провайдер (без API key) - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "microsoft", - providers: { - microsoft: { - enabled: true, - voice: "en-US-MichelleNeural", - lang: "en-US", - outputFormat: "audio-24khz-48kbitrate-mono-mp3", - rate: "+10%", - pitch: "-5%", - }, - }, - }, - }, -} -``` - -### MiniMax як основний провайдер - -```json5 -{ - messages: { - tts: { - auto: "always", - provider: "minimax", - providers: { - minimax: { - apiKey: "minimax_api_key", - baseUrl: "https://api.minimax.io", - model: "speech-2.8-hd", - voiceId: "English_expressive_narrator", - speed: 1.0, - vol: 1.0, - pitch: 0, - }, - }, - }, - }, -} -``` - -### Вимкнути Microsoft speech - -```json5 -{ - messages: { - tts: { - providers: { - microsoft: { - enabled: false, - }, - }, - }, - }, -} -``` - -### Власні обмеження + шлях до prefs - -```json5 -{ - messages: { - tts: { - auto: "always", - maxTextLength: 4000, - timeoutMs: 30000, - prefsPath: "~/.openclaw/settings/tts.json", - }, - }, -} -``` - -### Відповідати аудіо лише після вхідного голосового повідомлення - -```json5 -{ - messages: { - tts: { - auto: "inbound", - }, - }, -} -``` - -### Вимкнути автопідсумок для довгих відповідей - -```json5 -{ - messages: { - tts: { - auto: "always", - }, - }, -} -``` - -Потім виконайте: - -``` -/tts summary off -``` - -### Примітки щодо полів - -- `auto`: режим авто‑TTS (`off`, `always`, `inbound`, `tagged`). - - `inbound` надсилає аудіо лише після вхідного голосового повідомлення. - - `tagged` надсилає аудіо лише тоді, коли відповідь містить теги `[[tts]]`. -- `enabled`: застарілий перемикач (doctor мігрує його до `auto`). -- `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). -- `provider`: id speech-провайдера, наприклад `"elevenlabs"`, `"microsoft"`, `"minimax"` або `"openai"` (резервне перемикання відбувається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує першого налаштованого speech-провайдера в порядку автозаповнення реєстру. -- Застарілий `provider: "edge"` усе ще працює й нормалізується до `microsoft`. -- `summaryModel`: необов’язкова дешева модель для автопідсумку; типово `agents.defaults.model.primary`. - - Приймає `provider/model` або псевдонім налаштованої моделі. -- `modelOverrides`: дозволити моделі виводити директиви TTS (типово увімкнено). - - `allowProvider` типово дорівнює `false` (перемикання провайдера вмикається окремо). -- `providers.`: налаштування провайдера, якими володіє провайдер, із ключем за id speech-провайдера. -- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються в `messages.tts.providers.` під час завантаження. -- `maxTextLength`: жорстке обмеження для вводу TTS (символи). `/tts audio` завершується помилкою, якщо ліміт перевищено. -- `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначити локальний шлях до JSON prefs (провайдер/ліміт/підсумок). -- Значення `apiKey` використовують env vars як запасний варіант (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). -- `providers.elevenlabs.baseUrl`: перевизначити базовий URL API ElevenLabs. -- `providers.openai.baseUrl`: перевизначити endpoint OpenAI TTS. - - Порядок резолюції: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Значення, відмінні від типових, трактуються як OpenAI-сумісні endpoints TTS, тому підтримуються власні назви моделей і голосів. -- `providers.elevenlabs.voiceSettings`: - - `stability`, `similarityBoost`, `style`: `0..1` - - `useSpeakerBoost`: `true|false` - - `speed`: `0.5..2.0` (1.0 = нормально) -- `providers.elevenlabs.applyTextNormalization`: `auto|on|off` -- `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`) -- `providers.elevenlabs.seed`: ціле число `0..4294967295` (детермінованість у межах best-effort) -- `providers.minimax.baseUrl`: перевизначити базовий URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). -- `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). -- `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). -- `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0). -- `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0). -- `providers.minimax.pitch`: зсув висоти тону `-12..12` (типово 0). -- `providers.microsoft.enabled`: дозволити використання Microsoft speech (типово `true`; без API key). -- `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). -- `providers.microsoft.lang`: код мови (наприклад, `en-US`). -- `providers.microsoft.outputFormat`: формат виводу Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`). - - Допустимі значення див. у форматах виводу Microsoft Speech; не всі формати підтримуються вбудованим транспортом на базі Edge. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки з відсотками (наприклад, `+10%`, `-5%`). -- `providers.microsoft.saveSubtitles`: записувати JSON-субтитри поруч з аудіофайлом. -- `providers.microsoft.proxy`: URL проксі для запитів Microsoft speech. -- `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс). -- `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. - -## Перевизначення, керовані моделлю (типово увімкнено) - -Типово модель **може** виводити директиви TTS для однієї відповіді. -Коли `messages.tts.auto` дорівнює `tagged`, ці директиви потрібні для запуску аудіо. - -Коли цю можливість увімкнено, модель може виводити директиви `[[tts:...]]`, щоб перевизначити голос -для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб -надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише -в аудіо. - -Директиви `provider=...` ігноруються, якщо не задано `modelOverrides.allowProvider: true`. - -Приклад вмісту відповіді: - -``` -Here you go. - -[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](laughs) Read the song once more.[[/tts:text]] -``` - -Доступні ключі директив (коли увімкнено): - -- `provider` (id зареєстрованого speech-провайдера, наприклад `openai`, `elevenlabs`, `minimax` або `microsoft`; потребує `allowProvider: true`) -- `voice` (голос OpenAI) або `voiceId` (ElevenLabs / MiniMax) -- `model` (модель OpenAI TTS, id моделі ElevenLabs або модель MiniMax) -- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` -- `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (висота тону MiniMax, -12 до 12) -- `applyTextNormalization` (`auto|on|off`) -- `languageCode` (ISO 639-1) -- `seed` - -Вимкнути всі перевизначення моделі: - -```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: false, - }, - }, - }, -} -``` - -Необов’язковий allowlist (увімкнути перемикання провайдера, залишивши інші параметри налаштовуваними): - -```json5 -{ - messages: { - tts: { - modelOverrides: { - enabled: true, - allowProvider: true, - allowSeed: false, - }, - }, - }, -} -``` - -## Налаштування для користувача - -Slash-команди записують локальні перевизначення в `prefsPath` (типово: -`~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або -`messages.tts.prefsPath`). - -Збережені поля: - -- `enabled` -- `provider` -- `maxLength` (поріг підсумку; типово 1500 символів) -- `summarize` (типово `true`) - -Вони перевизначають `messages.tts.*` для цього хоста. - -## Формати виводу (фіксовані) - -- **Feishu / Matrix / Telegram / WhatsApp**: голосове повідомлення Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48kHz / 64kbps — хороший компроміс для голосових повідомлень. -- **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - - 44.1kHz / 128kbps — типовий баланс для чіткості мовлення. -- **MiniMax**: MP3 (`speech-2.8-hd`, частота дискретизації 32kHz). Формат voice note нативно не підтримується; використовуйте OpenAI або ElevenLabs для гарантованих голосових повідомлень Opus. -- **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні в сервісі. - - Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). - - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні - гарантовані голосові повідомлення Opus. - - Якщо налаштований формат виводу Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. - -Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). - -## Поведінка авто-TTS - -Коли це увімкнено, OpenClaw: - -- пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. -- пропускає дуже короткі відповіді (< 10 символів). -- підсумовує довгі відповіді, якщо це увімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). -- прикріплює згенероване аудіо до відповіді. - -Якщо відповідь перевищує `maxLength`, а підсумок вимкнено (або немає API key для -моделі підсумку), аудіо -пропускається й надсилається звичайна текстова відповідь. - -## Схема потоку - -``` -Reply -> TTS enabled? - no -> надіслати текст - yes -> є медіа / MEDIA: / коротко? - yes -> надіслати текст - no -> довжина > ліміт? - no -> TTS -> прикріпити аудіо - yes -> підсумок увімкнено? - no -> надіслати текст - yes -> підсумувати (summaryModel або agents.defaults.model.primary) - -> TTS -> прикріпити аудіо -``` - -## Використання slash-команди - -Є одна команда: `/tts`. -Подробиці про ввімкнення див. у [Slash commands](/tools/slash-commands). - -Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -`/voice` як нативну команду там. Текстова команда `/tts ...` усе одно працює. - -``` -/tts off -/tts always -/tts inbound -/tts tagged -/tts status -/tts provider openai -/tts limit 2000 -/tts summary off -/tts audio Hello from OpenClaw -``` - -Примітки: - -- Команди потребують авторизованого відправника (правила allowlist/owner усе ще застосовуються). -- Має бути ввімкнено `commands.text` або реєстрацію нативних команд. -- `off|always|inbound|tagged` — це перемикачі для окремої сесії (`/tts on` — псевдонім для `/tts always`). -- `limit` і `summary` зберігаються в локальних prefs, а не в основному config. -- `/tts audio` генерує разову аудіовідповідь (не вмикає TTS постійно). -- `/tts status` містить інформацію про резервне переключення для останньої спроби: - - успішне резервне переключення: `Fallback: -> ` плюс `Attempts: ...` - - помилка: `Error: ...` плюс `Attempts: ...` - - детальна діагностика: `Attempt details: provider:outcome(reasonCode) latency` -- Збої API OpenAI та ElevenLabs тепер містять розібрані деталі помилки провайдера й id запиту (коли провайдер його повертає), що відображається в помилках/журналах TTS. - -## Інструмент агента - -Інструмент `tts` перетворює текст на мовлення та повертає аудіовкладення для -доставки відповіді. Коли канал — Feishu, Matrix, Telegram або WhatsApp, -аудіо доставляється як голосове повідомлення, а не як вкладений файл. - -## Gateway RPC - -Методи Gateway: - -- `tts.status` -- `tts.enable` -- `tts.disable` -- `tts.convert` -- `tts.setProvider` -- `tts.providers` +Цю сторінку переміщено до [Text-to-Speech](/uk/tools/tts).