chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d6163d1a66
commit
1ef5eec8d0
@ -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` плюс один явний виняток для цитати/відповіді.
|
||||
|
||||
Поки цю модель посилення безпеки не буде узгоджено реалізовано в усіх каналах, очікуйте відмінностей залежно від поверхні.
|
||||
Поки цю модель посилення безпеки не реалізовано узгоджено в усіх каналах, очікуйте відмінностей між платформами.
|
||||
|
||||
|
||||
|
||||
|
||||
Якщо вам потрібно...
|
||||
Якщо ви хочете...
|
||||
|
||||
| Мета | Що налаштувати |
|
||||
| -------------------------------------------- | -------------------------------------------------------- |
|
||||
| Дозволити всі групи, але відповідати лише на @згадування | `groups: { "*": { requireMention: true } }` |
|
||||
| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` |
|
||||
| Лише певні групи | `groups: { "<group-id>": { ... } }` (без ключа `"*"`) |
|
||||
| Лише ви можете запускати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
| Мета | Що налаштувати |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| Дозволити всі групи, але відповідати лише на @згадки | `groups: { "*": { requireMention: true } }` |
|
||||
| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` |
|
||||
| Лише певні групи | `groups: { "<group-id>": { ... } }` (без ключа `"*"`) |
|
||||
| Лише ви можете активувати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
|
||||
## Ключі сесій
|
||||
|
||||
- Для групових сесій використовуються ключі сесій `agent:<agentId>:<channel>:group:<id>` (для кімнат/каналів — `agent:<agentId>:<channel>:channel:<id>`).
|
||||
- Для тем форумів Telegram до ідентифікатора групи додається `:topic:<threadId>`, щоб кожна тема мала власну сесію.
|
||||
- Групові сесії використовують ключі сесій `agent:<agentId>:<channel>:group:<id>` (кімнати/канали використовують `agent:<agentId>:<channel>:channel:<id>`).
|
||||
- Теми форуму Telegram додають `:topic:<threadId>` до ідентифікатора групи, тому кожна тема має власну сесію.
|
||||
- Прямі чати використовують основну сесію (або окрему для кожного відправника, якщо це налаштовано).
|
||||
- Heartbeat для групових сесій пропускаються.
|
||||
- Heartbeat-и для групових сесій пропускаються.
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## Шаблон: особисті DM + публічні групи (один агент)
|
||||
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а «публічний» трафік — це **групи**.
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а ваш «публічний» трафік — це **групи**.
|
||||
|
||||
Чому: у режимі одного агента DM зазвичай потрапляють в **основний** ключ сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете ізоляцію з `mode: "non-main"`, ці групові сесії виконуватимуться в Docker, а ваша основна DM-сесія залишиться на хості.
|
||||
Чому: у режимі одного агента DM зазвичай потрапляють до ключа **основної** сесії (`agent:main:main`), тоді як групи завжди використовують ключі **неосновних** сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете 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`, коли він доступний, у форматі `<channel>:<token>`.
|
||||
- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-<slug>` (нижній регістр, пробіли -> `-`, зберігаються `#@+._-`).
|
||||
- Мітки в UI використовують `displayName`, якщо він доступний, у форматі `<channel>:<token>`.
|
||||
- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-<slug>` (нижній регістр, пробіли -> `-`, зберігати `#@+._-`).
|
||||
|
||||
## Політика груп
|
||||
|
||||
Керуйте тим, як обробляються повідомлення з груп/кімнат для кожного каналу:
|
||||
|
||||
```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.<id>.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.<id>.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.<provider>` відсутній), політика груп переходить у 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.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
- `mentionPatterns` — це безпечні regex-шаблони, нечутливі до регістру; недійсні шаблони та небезпечні форми вкладеного повторення ігноруються.
|
||||
- Платформи, які надають явні згадки, усе одно проходять перевірку; шаблони є запасним варіантом.
|
||||
- Перевизначення для агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів спільно використовують одну групу).
|
||||
- Керування згадками застосовується лише тоді, коли виявлення згадки можливе (налаштовані нативні згадки або `mentionPatterns`).
|
||||
- Значення за замовчуванням для Discord зберігаються в `channels.discord.guilds."*"` (можна перевизначати для окремої гільдії/каналу).
|
||||
- Контекст історії групи однаково обгортається в усіх каналах і є **лише pending** (повідомлення, пропущені через керування згадками); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
|
||||
## Обмеження інструментів для груп/каналів (необов’язково)
|
||||
|
||||
Деякі конфігурації каналів дають змогу обмежувати, які інструменти доступні **всередині конкретної групи/кімнати/каналу**.
|
||||
Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині конкретної групи/кімнати/каналу**.
|
||||
|
||||
- `tools`: дозволити/заборонити інструменти для всієї групи.
|
||||
- `toolsBySender`: перевизначення для окремих відправників усередині групи.
|
||||
- `toolsBySender`: перевизначення для окремих відправників у межах групи.
|
||||
Використовуйте явні префікси ключів:
|
||||
`id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` і 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:<id>`.
|
||||
- Перегляд чатів: `imsg chats --limit 20`.
|
||||
- Для маршрутизації або allowlist-ів віддавайте перевагу `chat_id:<id>`.
|
||||
- Список чатів: `imsg chats --limit 20`.
|
||||
- Відповіді в групі завжди повертаються до того самого `chat_id`.
|
||||
|
||||
## Особливості WhatsApp
|
||||
|
||||
Див. [Повідомлення в групах](/channels/group-messages) для поведінки, специфічної для WhatsApp (впровадження історії, деталі обробки згадувань).
|
||||
Див. [Групові повідомлення](/uk/channels/group-messages) для поведінки, специфічної лише для WhatsApp (впровадження історії, подробиці обробки згадок).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
```
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Підключення" icon="link" href="/channels/pairing">
|
||||
Типова політика DM для невідомих відправників — pairing.
|
||||
<Card title="Прив’язка" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика DM — прив’язка для невідомих відправників.
|
||||
</Card>
|
||||
<Card title="Усунення проблем із каналами" icon="wrench" href="/channels/troubleshooting">
|
||||
Кросканальна діагностика та сценарії відновлення.
|
||||
<Card title="Усунення проблем каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/gateway/configuration">
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналу.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -85,30 +85,30 @@ openclaw gateway
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Схваліть перший запит на pairing (якщо використовується режим pairing)">
|
||||
<Step title="Схваліть перший запит на прив’язку (якщо використовується режим прив’язки)">
|
||||
|
||||
```bash
|
||||
openclaw pairing list whatsapp
|
||||
openclaw pairing approve whatsapp <CODE>
|
||||
```
|
||||
|
||||
Термін дії запитів на pairing спливає через 1 годину. Для кожного каналу може бути не більше 3 незавершених запитів.
|
||||
Запити на прив’язку спливають через 1 годину. Кількість запитів у стані очікування обмежена до 3 на канал.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовано для такого варіанта, але конфігурації з особистим номером також підтримуються.)
|
||||
OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але конфігурації з особистим номером також підтримуються.)
|
||||
</Note>
|
||||
|
||||
## Сценарії розгортання
|
||||
## Схеми розгортання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Окремий номер (рекомендовано)">
|
||||
Це найзручніший операційний режим:
|
||||
Це найчистіший операційний режим:
|
||||
|
||||
- окрема ідентичність WhatsApp для OpenClaw
|
||||
- чіткіші allowlist для DM та межі маршрутизації
|
||||
- чіткіші allowlist-и DM та межі маршрутизації
|
||||
- менша ймовірність плутанини з чатом із самим собою
|
||||
|
||||
Мінімальний шаблон політики:
|
||||
@ -127,31 +127,32 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Резервний варіант з особистим номером">
|
||||
Onboarding підтримує режим особистого номера і записує базову конфігурацію, зручну для чату із самим собою:
|
||||
Онбординг підтримує режим особистого номера та записує базову конфігурацію, дружню до чату із самим собою:
|
||||
|
||||
- `dmPolicy: "allowlist"`
|
||||
- `allowFrom` містить ваш особистий номер
|
||||
- `selfChatMode: true`
|
||||
|
||||
Під час runtime захист чату із самим собою спирається на прив’язаний власний номер і `allowFrom`.
|
||||
Під час виконання захист для чату із самим собою спирається на прив’язаний власний номер і `allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Область каналу лише для WhatsApp Web">
|
||||
Канал платформи обміну повідомленнями у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
|
||||
Канал платформи обміну повідомленнями у поточній архітектурі каналів OpenClaw побудований на WhatsApp Web (`Baileys`).
|
||||
|
||||
У вбудованому реєстрі чат-каналів немає окремого каналу повідомлень Twilio WhatsApp.
|
||||
Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі чат-каналів немає.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Модель 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:<agentId>:whatsapp:group:<jid>`).
|
||||
- Транспорт WhatsApp Web дотримується стандартних змінних середовища проксі на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста, а не специфічним налаштуванням проксі WhatsApp для каналу.
|
||||
|
||||
## Контроль доступу та активація
|
||||
|
||||
@ -159,52 +160,52 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
<Tab title="Політика DM">
|
||||
`channels.whatsapp.dmPolicy` керує доступом до прямих чатів:
|
||||
|
||||
- `pairing` (типово)
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist`
|
||||
- `open` (потребує, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`allowFrom` приймає номери у форматі E.164 (внутрішньо нормалізуються).
|
||||
`allowFrom` приймає номери у стилі E.164 (внутрішньо нормалізуються).
|
||||
|
||||
Перевизначення для кількох облікових записів: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над значеннями канального рівня для цього облікового запису.
|
||||
|
||||
Подробиці поведінки runtime:
|
||||
Деталі поведінки під час виконання:
|
||||
|
||||
- pairings зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, типово дозволяється прив’язаний власний номер
|
||||
- вихідні DM `fromMe` ніколи не проходять auto-paired
|
||||
- прив’язки зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, прив’язаний власний номер дозволяється за замовчуванням
|
||||
- вихідні `fromMe` DM ніколи не прив’язуються автоматично
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Групова політика + allowlists">
|
||||
<Tab title="Групова політика + allowlist-и">
|
||||
Доступ до груп має два рівні:
|
||||
|
||||
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`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Згадки + /activation">
|
||||
У групах відповіді типово вимагають згадки.
|
||||
Для відповідей у групі за замовчуванням потрібна згадка.
|
||||
|
||||
Виявлення згадок включає:
|
||||
Виявлення згадки включає:
|
||||
|
||||
- явні згадки 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` оновлює стан сесії (а не глобальну конфігурацію). Доступ до нього обмежений власником.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Поведінка особистого номера та чату із самим собою
|
||||
|
||||
Коли прив’язаний власний номер також присутній у `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]`
|
||||
|
||||
## Нормалізація повідомлень і контекст
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вхідна envelope + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp обгортаються в спільну inbound envelope.
|
||||
<Accordion title="Вхідний конверт + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp загортаються у спільний вхідний конверт.
|
||||
|
||||
Якщо існує цитована відповідь, контекст додається в такому вигляді:
|
||||
Якщо існує цитована відповідь, контекст додається в такому форматі:
|
||||
|
||||
```text
|
||||
[Replying to <sender> id:<stanzaId>]
|
||||
[Відповідь на <sender> id:<stanzaId>]
|
||||
<quoted body or media placeholder>
|
||||
[/Replying]
|
||||
[/Відповідь]
|
||||
```
|
||||
|
||||
Метадані відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
|
||||
Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Заповнювачі медіа та витягування location/contact">
|
||||
Вхідні повідомлення лише з медіа нормалізуються за допомогою заповнювачів, наприклад:
|
||||
<Accordion title="Заповнювачі медіа та витягування геолокації/контактів">
|
||||
Вхідні повідомлення, що містять лише медіа, нормалізуються із заповнювачами, такими як:
|
||||
|
||||
- `<media:image>`
|
||||
- `<media:video>`
|
||||
@ -256,29 +257,29 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
- `<media:document>`
|
||||
- `<media:sticker>`
|
||||
|
||||
Дані location і contact нормалізуються в текстовий контекст перед маршрутизацією.
|
||||
Дані геолокації та контактів нормалізуються в текстовий контекст перед маршрутизацією.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Відкладене додавання історії групи">
|
||||
Для груп необроблені повідомлення можуть буферизуватися й додаватися як контекст, коли бот нарешті активується.
|
||||
<Accordion title="Вставка історії очікування для груп">
|
||||
Для груп необроблені повідомлення можуть буферизуватися і вставлятися як контекст, коли бот нарешті активується.
|
||||
|
||||
- типове обмеження: `50`
|
||||
- ліміт за замовчуванням: `50`
|
||||
- конфігурація: `channels.whatsapp.historyLimit`
|
||||
- резервне значення: `messages.groupChat.historyLimit`
|
||||
- `0` вимикає
|
||||
|
||||
Маркери додавання:
|
||||
Маркери вставки:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
- `[Повідомлення чату з часу вашої останньої відповіді — для контексту]`
|
||||
- `[Поточне повідомлення — відповідайте на нього]`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Read receipts">
|
||||
Read receipts типово ввімкнені для прийнятих вхідних повідомлень WhatsApp.
|
||||
<Accordion title="Підтвердження прочитання">
|
||||
Підтвердження прочитання ввімкнені за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
|
||||
|
||||
Вимкнення глобально:
|
||||
Вимкнути глобально:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -290,7 +291,7 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення для окремого облікового запису:
|
||||
Перевизначення для кожного облікового запису:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -306,7 +307,7 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
}
|
||||
```
|
||||
|
||||
Для self-chat read receipts пропускаються, навіть якщо глобально ввімкнені.
|
||||
Для ходів у чаті із самим собою підтвердження прочитання пропускаються, навіть якщо вони глобально ввімкнені.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -314,43 +315,43 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
## Доставка, розбиття на частини та медіа
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Розбиття тексту">
|
||||
- типове обмеження частини: `channels.whatsapp.textChunkLimit = 4000`
|
||||
<Accordion title="Розбиття тексту на частини">
|
||||
- ліміт частини за замовчуванням: `channels.whatsapp.textChunkLimit = 4000`
|
||||
- `channels.whatsapp.chunkMode = "length" | "newline"`
|
||||
- режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім резервно використовує безпечне за довжиною розбиття
|
||||
- режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного за довжиною розбиття
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка вихідних медіа">
|
||||
- підтримуються 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://` або локальні шляхи
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження розміру медіа та резервна поведінка">
|
||||
- обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- для перевизначень окремих облікових записів використовується `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вкладатися в ліміти
|
||||
- при збої надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість тихого відкидання відповіді
|
||||
- обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
|
||||
- обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
|
||||
- перевизначення для кожного облікового запису використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб відповідати обмеженням
|
||||
- у разі помилки надсилання медіа резервна логіка для першого елемента надсилає текстове попередження замість тихого пропуску відповіді
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Рівень реакцій
|
||||
|
||||
`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.<id>.reactionLevel`.
|
||||
Перевизначення для кожного облікового запису використовують `channels.whatsapp.accounts.<id>.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` тут не використовується)
|
||||
|
||||
## Кілька облікових записів і облікові дані
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вибір облікового запису та типові значення">
|
||||
- ID облікових записів беруться з `channels.whatsapp.accounts`
|
||||
- типове вибирання облікового запису: `default`, якщо він є, інакше перший налаштований ID облікового запису (відсортований)
|
||||
- ID облікових записів внутрішньо нормалізуються для пошуку
|
||||
<Accordion title="Вибір облікового запису та значення за замовчуванням">
|
||||
- ідентифікатори облікових записів беруться з `channels.whatsapp.accounts`
|
||||
- вибір облікового запису за замовчуванням: `default`, якщо присутній, інакше перший налаштований id облікового запису (відсортований)
|
||||
- ідентифікатори облікових записів внутрішньо нормалізуються для пошуку
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Шляхи до облікових даних і сумісність із застарілими даними">
|
||||
- поточний шлях до auth: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
<Accordion title="Шляхи до облікових даних і сумісність зі спадщиною">
|
||||
- поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- резервний файл: `creds.json.bak`
|
||||
- застаріла default auth у `~/.openclaw/credentials/` усе ще розпізнається/мігрує для сценаріїв з default account
|
||||
- застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для сценаріїв з обліковим записом за замовчуванням
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка виходу">
|
||||
`openclaw channels logout --channel whatsapp [--account <id>]` очищає стан auth WhatsApp для цього облікового запису.
|
||||
`openclaw channels logout --channel whatsapp [--account <id>]` очищає стан автентифікації WhatsApp для цього облікового запису.
|
||||
|
||||
У каталогах застарілої auth `oauth.json` зберігається, тоді як файли auth Baileys видаляються.
|
||||
У застарілих каталогах автентифікації `oauth.json` зберігається, тоді як файли автентифікації Baileys видаляються.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Інструменти, дії та записи конфігурації
|
||||
## Інструменти, дії та запис конфігурації
|
||||
|
||||
- Підтримка інструментів агента включає дію реакції WhatsApp (`react`).
|
||||
- Обмеження дій:
|
||||
- `channels.whatsapp.actions.reactions`
|
||||
- `channels.whatsapp.actions.polls`
|
||||
- Записи конфігурації, ініційовані з каналу, типово ввімкнені (вимкнення через `channels.whatsapp.configWrites=false`).
|
||||
- Запис конфігурації, ініційований каналом, увімкнений за замовчуванням (вимикається через `channels.whatsapp.configWrites=false`).
|
||||
|
||||
## Усунення проблем
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Не прив’язано (потрібен QR)">
|
||||
Симптом: статус каналу повідомляє, що прив’язку не виконано.
|
||||
Симптом: статус каналу повідомляє, що його не прив’язано.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -434,8 +435,8 @@ Ack reactions залежать від `reactionLevel` — вони пригні
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Прив’язано, але відключено / цикл повторного підключення">
|
||||
Симптом: прив’язаний обліковий запис із повторюваними відключеннями або спробами повторного підключення.
|
||||
<Accordion title="Прив’язано, але відключено / цикл перепідключення">
|
||||
Симптом: прив’язаний обліковий запис із повторними відключеннями або спробами перепідключення.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -444,14 +445,14 @@ Ack reactions залежать від `reactionLevel` — вони пригні
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
За потреби прив’яжіть заново через `channels login`.
|
||||
За потреби повторно прив’яжіть через `channels login`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Немає активного listener під час надсилання">
|
||||
Вихідні надсилання швидко завершуються помилкою, якщо для цільового облікового запису немає активного listener gateway.
|
||||
<Accordion title="Немає активного слухача під час надсилання">
|
||||
Вихідні надсилання одразу завершуються помилкою, коли для цільового облікового запису не існує активного слухача gateway.
|
||||
|
||||
Переконайтеся, що gateway працює і обліковий запис прив’язано.
|
||||
Переконайтеся, що gateway запущено і обліковий запис прив’язано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -460,22 +461,22 @@ Ack reactions залежать від `reactionLevel` — вони пригні
|
||||
|
||||
- `groupPolicy`
|
||||
- `groupAllowFrom` / `allowFrom`
|
||||
- записи allowlist у `groups`
|
||||
- вимогу згадки (`requireMention` + шаблони згадок)
|
||||
- дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому залишайте лише один `groupPolicy` для кожної області
|
||||
- записи allowlist-а `groups`
|
||||
- обмеження за згадкою (`requireMention` + шаблони згадок)
|
||||
- дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` для кожної області
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Попередження про runtime Bun">
|
||||
Runtime gateway WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram.
|
||||
<Accordion title="Попередження середовища виконання Bun">
|
||||
Середовище виконання gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Вказівники на довідник конфігурації
|
||||
|
||||
Основний довідник:
|
||||
Основне посилання:
|
||||
|
||||
- [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)
|
||||
|
||||
@ -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 <provider/model>`.
|
||||
- Правила резервного перемикання під час виконання, проби періоду охолодження та збереження перевизначень сесії
|
||||
задокументовані в [/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.<id>` перед
|
||||
використанням під час виконання; 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:
|
||||
- `<PROVIDER>_API_KEYS` (список через кому або крапку з комою)
|
||||
- `<PROVIDER>_API_KEY` (основний ключ)
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_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/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Розігрів WebSocket для OpenAI Responses типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Прогрівання WebSocket OpenAI Responses типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/<model>"].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/<model>"].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/<model>"].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/<model>"].params.tool_stream` як `false`, щоб
|
||||
`agents.defaults.models["xai/<model>"].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.<id>` лише тоді, коли хочете перевизначити
|
||||
типову базову 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) — посібники з налаштування для кожного постачальника
|
||||
|
||||
@ -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 <id>
|
||||
@ -44,71 +43,65 @@ openclaw models auth login --provider <id>
|
||||
|
||||
## Сховище токенів (навіщо воно існує)
|
||||
|
||||
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/<agentId>/agent/auth-profiles.json`
|
||||
- Застарілий файл сумісності: `~/.openclaw/agents/<agentId>/agent/auth.json`
|
||||
(статичні записи `api_key` очищаються, якщо виявляються)
|
||||
- Профілі автентифікації (OAuth + API keys + необов’язкові посилання на значення): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Файл сумісності зі старою схемою: `~/.openclaw/agents/<agentId>/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
|
||||
|
||||
<Warning>
|
||||
У публічній документації 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).
|
||||
</Warning>
|
||||
|
||||
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 ...@<profileId>`
|
||||
@ -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) — ключі конфігурації автентифікації
|
||||
|
||||
@ -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:
|
||||
# Автентифікація (постачальники моделей)
|
||||
|
||||
<Note>
|
||||
Ця сторінка охоплює автентифікацію **постачальника моделей** (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).
|
||||
</Note>
|
||||
|
||||
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.<id>.mode` встановлено `"oauth"`, введення `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється.
|
||||
- облікові дані `api_key` можуть використовувати `keyRef: { source, provider, id }`
|
||||
- облікові дані `token` можуть використовувати `tokenRef: { source, provider, id }`
|
||||
- Профілі в режимі OAuth не підтримують облікові дані SecretRef; якщо `auth.profiles.<id>.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.<provider>` пропускає збережений профіль, 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_<PROVIDER>_KEY` (єдиний override)
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (одне перевизначення)
|
||||
- `<PROVIDER>_API_KEYS`
|
||||
- `<PROVIDER>_API_KEY`
|
||||
- `<PROVIDER>_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 <alias-or-id>@<profileId>`, щоб закріпити конкретні облікові дані постачальника для поточного сеансу (приклади ідентифікаторів профілів: `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 <id>`, щоб націлити на конкретного агента; не вказуйте його, щоб використовувати налаштованого агента за замовчуванням.
|
||||
Під час налагодження проблем із порядком `openclaw models status --probe` показує пропущені
|
||||
Використовуйте `--agent <id>`, щоб націлитися на конкретного агента; не вказуйте його, щоб використовувати налаштованого агента за замовчуванням.
|
||||
Коли ви налагоджуєте проблеми з порядком, `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 і залишає вказівки щодо наступних кроків.
|
||||
|
||||
@ -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:
|
||||
Ідентифікатор провайдера стає лівою частиною посилання на модель:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -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-сесію.
|
||||
|
||||
<Warning>
|
||||
Вбудований бекенд Anthropic `claude-cli` було видалено після того, як змінилася
|
||||
межа білінгу OpenClaw в Anthropic. OpenClaw і далі підтримує загальні CLI-
|
||||
бекенди, але трафік Anthropic API слід спрямовувати безпосередньо через провайдера Anthropic,
|
||||
а не через видалений локальний шлях Claude CLI.
|
||||
</Warning>
|
||||
<Note>
|
||||
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає
|
||||
використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує
|
||||
нову політику.
|
||||
</Note>
|
||||
|
||||
## Сеанси
|
||||
## Сесії
|
||||
|
||||
- Якщо 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>` і далі перевизначає типове значення плагіна.
|
||||
- Очищення конфігурації, специфічне для бекенду, і далі належить плагіну через необов’язковий
|
||||
- `id` бекенду стає префіксом провайдера в посиланнях на модель.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` як і раніше перевизначає типове значення плагіна.
|
||||
- Очищення конфігурації, специфічне для бекенду, як і раніше керується плагіном через необов’язковий
|
||||
хук `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 <generated-file>`
|
||||
|
||||
Якщо жоден 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 підтримує шляхи до файлів).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Попередження про перевизначення постачальника OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції 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.<provider>`. Doctor переписує старі форми
|
||||
Сюди також входять застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це
|
||||
`talk.provider` + `talk.providers.<provider>`. 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.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт.
|
||||
- Якщо `channels.<channel>.defaultAccount` вказано на невідомий ID акаунта, doctor попереджає і перелічує налаштовані ID акаунтів.
|
||||
- Якщо налаштовано два або більше записи `channels.<channel>.accounts`, але немає `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.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/<agentId>/sessions/`
|
||||
- Каталог агента:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID акаунта: `default`)
|
||||
- зі старого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий 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).
|
||||
|
||||
@ -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 у перший день і для операційної роботи надалі.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Поглиблене усунення несправностей" icon="siren" href="/gateway/troubleshooting">
|
||||
<Card title="Поглиблене усунення неполадок" icon="siren" href="/uk/gateway/troubleshooting">
|
||||
Діагностика за симптомами з точними послідовностями команд і сигнатурами журналів.
|
||||
</Card>
|
||||
<Card title="Конфігурація" icon="sliders" href="/gateway/configuration">
|
||||
Посібник із налаштування, орієнтований на завдання, + повний довідник із конфігурації.
|
||||
<Card title="Configuration" icon="sliders" href="/uk/gateway/configuration">
|
||||
Практичний посібник із налаштування + повний довідник конфігурації.
|
||||
</Card>
|
||||
<Card title="Керування секретами" icon="key-round" href="/gateway/secrets">
|
||||
Контракт SecretRef, поведінка runtime snapshot і операції migrate/reload.
|
||||
<Card title="Керування секретами" icon="key-round" href="/uk/gateway/secrets">
|
||||
Контракт SecretRef, поведінка знімків під час виконання та операції міграції/перезавантаження.
|
||||
</Card>
|
||||
<Card title="Контракт плану секретів" icon="shield-check" href="/gateway/secrets-plan-contract">
|
||||
Точні правила target/path для `secrets apply` і поведінка auth-profile лише з ref.
|
||||
<Card title="Контракт плану секретів" icon="shield-check" href="/uk/gateway/secrets-plan-contract">
|
||||
Точні правила target/path для `secrets apply` і поведінка профілю автентифікації лише з посиланнями.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте стан сервісу">
|
||||
<Step title="Перевірте стан служби">
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -54,43 +54,43 @@ openclaw status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Ознаки здорового базового стану: `Runtime: running` і `RPC probe: ok`.
|
||||
Базовий справний стан: `Runtime: running` і `RPC probe: ok`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте готовність каналу">
|
||||
<Step title="Перевірте готовність каналів">
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
За доступного gateway ця команда виконує live-перевірки каналів для кожного облікового запису та необов’язкові аудити.
|
||||
Якщо gateway недоступний, CLI повертається до зведень каналів лише на основі конфігурації
|
||||
замість live-виводу перевірки.
|
||||
За доступного gateway ця команда виконує живі перевірки каналів для кожного облікового запису та необов’язкові аудити.
|
||||
Якщо gateway недоступний, CLI повертається до зведень каналів лише за конфігурацією
|
||||
замість виводу живих probe-перевірок.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Перезавантаження конфігурації Gateway відстежує активний шлях до файлу конфігурації (визначений із типових значень profile/state або через `OPENCLAW_CONFIG_PATH`, якщо його задано).
|
||||
Перезавантаження конфігурації Gateway відстежує активний шлях до файла конфігурації (визначений із типових значень профілю/стану або через `OPENCLAW_CONFIG_PATH`, якщо його задано).
|
||||
Типовий режим — `gateway.reload.mode="hybrid"`.
|
||||
Після першого успішного завантаження запущений процес обслуговує активний in-memory snapshot конфігурації; успішне перезавантаження атомарно замінює цей snapshot.
|
||||
Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно підміняє цей знімок.
|
||||
</Note>
|
||||
|
||||
## Модель 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/<agentId>`.
|
||||
- `openclaw/default` — це стабільний псевдонім, який завжди зіставляється з налаштованим типовим агентом.
|
||||
- Використовуйте `x-openclaw-model`, коли вам потрібно перевизначити провайдера/модель backend; інакше зберігається керування звичайною моделлю та налаштуванням embedding вибраного агента.
|
||||
- `/v1/models` орієнтований насамперед на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/<agentId>`.
|
||||
- `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`.
|
||||
|
||||
<Warning>
|
||||
SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти
|
||||
все одно мають надсилати `token`/`password`, навіть через тунель. Для режимів із
|
||||
ідентифікацією запит усе одно має відповідати цьому шляху автентифікації.
|
||||
SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти все одно
|
||||
мають надсилати `token`/`password` навіть через тунель. Для режимів з ідентифікацією
|
||||
запит усе одно має задовольняти цей шлях автентифікації.
|
||||
</Warning>
|
||||
|
||||
Див.: [Remote Gateway](/gateway/remote), [Автентифікація](/gateway/authentication), [Tailscale](/gateway/tailscale).
|
||||
Див.: [Remote Gateway](/uk/gateway/remote), [Authentication](/uk/gateway/authentication), [Tailscale](/uk/gateway/tailscale).
|
||||
|
||||
## Супервізія та життєвий цикл сервісу
|
||||
## Нагляд і життєвий цикл служби
|
||||
|
||||
Для надійності, подібної до production, використовуйте запуск під супервізією.
|
||||
Для надійності на рівні production використовуйте запуск під наглядом.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS (launchd)">
|
||||
@ -203,7 +204,7 @@ openclaw gateway restart
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
Мітки LaunchAgent — `ai.openclaw.gateway` (типово) або `ai.openclaw.<profile>` (іменований profile). `openclaw doctor` перевіряє й виправляє дрейф конфігурації сервісу.
|
||||
Мітки LaunchAgent: `ai.openclaw.gateway` (типово) або `ai.openclaw.<profile>` (іменований профіль). `openclaw doctor` перевіряє і виправляє дрейф конфігурації служби.
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -215,13 +216,13 @@ systemctl --user enable --now openclaw-gateway[-<profile>].service
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
Щоб сервіс не зупинявся після виходу з системи, увімкніть lingering:
|
||||
Щоб служба лишалася активною після виходу з сеансу, увімкніть lingering:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger <user>
|
||||
```
|
||||
|
||||
Приклад ручного user unit, коли потрібен кастомний шлях встановлення:
|
||||
Приклад user-unit вручну, коли потрібен власний шлях встановлення:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
@ -253,24 +254,24 @@ openclaw gateway restart
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
Керований нативний запуск Windows використовує Scheduled Task з назвою `OpenClaw Gateway`
|
||||
(або `OpenClaw Gateway (<profile>)` для іменованих profile). Якщо створення Scheduled Task
|
||||
заборонено, OpenClaw повертається до launcher у Startup-folder для кожного користувача,
|
||||
який вказує на `gateway.cmd` у каталозі state.
|
||||
Керований нативний автозапуск у Windows використовує Scheduled Task з назвою `OpenClaw Gateway`
|
||||
(або `OpenClaw Gateway (<profile>)` для іменованих профілів). Якщо створення Scheduled Task
|
||||
заборонено, OpenClaw переходить до launcher у Startup-folder для поточного користувача,
|
||||
який вказує на `gateway.cmd` у каталозі стану.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Linux (system service)">
|
||||
|
||||
Використовуйте system unit для багатокористувацьких/постійно ввімкнених хостів.
|
||||
Використовуйте системний unit для багатокористувацьких/постійно активних хостів.
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now openclaw-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
Використовуйте те саме тіло сервісу, що й для user unit, але встановлюйте його в
|
||||
`/etc/systemd/system/openclaw-gateway[-<profile>].service` і за потреби скоригуйте
|
||||
Використовуйте той самий вміст служби, що й для user unit, але встановіть його в
|
||||
`/etc/systemd/system/openclaw-gateway[-<profile>].service` і скоригуйте
|
||||
`ExecStart=`, якщо ваш бінарний файл `openclaw` розташований в іншому місці.
|
||||
|
||||
</Tab>
|
||||
@ -278,8 +279,8 @@ sudo systemctl enable --now openclaw-gateway[-<profile>].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)
|
||||
|
||||
@ -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 <requestId>`. |
|
||||
| Код деталей | Значення | Рекомендована дія |
|
||||
| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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 <requestId>`. |
|
||||
|
||||
Перевірка міграції 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 "<name>" 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; '<feature>' 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 <name>`, щоб закрити активну керовану сесію й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway.
|
||||
- `browser.cdpUrl has invalid port` → у налаштованого URL CDP неправильний або позадіапазонний порт.
|
||||
- `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome.
|
||||
- `Remote CDP for profile "<name>" 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; '<feature>' 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 <name>`, щоб закрити активну керовану сесію та звільнити стан емуляції 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)
|
||||
|
||||
1500
docs/uk/help/faq.md
1500
docs/uk/help/faq.md
File diff suppressed because it is too large
Load Diff
@ -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=<n>` щоб примусово задати кількість воркерів (обмежено 16).
|
||||
- `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід.
|
||||
- Охоплення:
|
||||
- Наскрізна поведінка multi-instance gateway
|
||||
- Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії
|
||||
- `OPENCLAW_E2E_WORKERS=<n>` щоб примусово встановити кількість 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 <CODE>`.
|
||||
- Посилання на реалізацію: `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: "<base64>" }]`
|
||||
- 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 <agent> --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@<version>'`
|
||||
- Примітки:
|
||||
- Ця лінія використовує поверхню `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/<agentId>/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/<agentId>/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.<capability>` не налаштовано
|
||||
- Корисно після змін у надсиланні 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 <discord-channel-id> ...`
|
||||
- Зберігайте цей скрипт для 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, щоб нові класи не могли бути тихо пропущені.
|
||||
|
||||
@ -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/<first-wave-subpaths>.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`
|
||||
@ -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>
|
||||
```
|
||||
|
||||
Якщо застосунок повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний ключ),
|
||||
попередній очікувальний запит замінюється, і створюється новий `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://<gateway-host>: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)
|
||||
|
||||
@ -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, але нові
|
||||
плагіни не повинні їх використовувати, а наявні плагіни слід перенести до того, як наступний
|
||||
мажорний реліз їх прибере.
|
||||
|
||||
<Warning>
|
||||
Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів.
|
||||
Plugins, які й далі імпортують із цих поверхонь, перестануть працювати,
|
||||
коли це станеться.
|
||||
Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних релізів.
|
||||
Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться.
|
||||
</Warning>
|
||||
|
||||
## Чому це змінилося
|
||||
|
||||
Старий підхід спричиняв проблеми:
|
||||
Старий підхід створював проблеми:
|
||||
|
||||
- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки
|
||||
не пов’язаних між собою модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення
|
||||
циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є
|
||||
стабільними, а які — внутрішніми
|
||||
- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми
|
||||
|
||||
Сучасний plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим, самодостатнім модулем із чітким призначенням і задокументованим
|
||||
контрактом.
|
||||
Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим самодостатнім модулем із чітким призначенням і задокументованим контрактом.
|
||||
|
||||
Застарілі зручні 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`
|
||||
|
||||
## Як виконати міграцію
|
||||
|
||||
<Steps>
|
||||
<Step title="Перевірте резервну поведінку Windows wrapper">
|
||||
Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані
|
||||
wrapper-и Windows `.cmd`/`.bat` тепер безпечно завершуються помилкою, якщо
|
||||
ви явно не передасте `allowShellFallback: true`.
|
||||
<Step title="Перевірте fallback-поведінку Windows wrapper">
|
||||
Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows
|
||||
wrapper-и `.cmd`/`.bat` тепер аварійно завершуються із закритою помилкою, якщо ви явно не передасте
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -100,14 +92,13 @@ OpenClaw перейшов від широкого шару зворотної с
|
||||
});
|
||||
```
|
||||
|
||||
Якщо ваш виклик не покладається навмисно на резервний перехід через shell,
|
||||
не встановлюйте `allowShellFallback` і натомість обробляйте викинуту
|
||||
помилку.
|
||||
Якщо ваш викликаючий код навмисно не покладається на shell fallback, не задавайте
|
||||
`allowShellFallback`, а натомість обробляйте викинуту помилку.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Знайдіть застарілі імпорти">
|
||||
Знайдіть у своєму plugin імпорти з будь-якої із застарілих поверхонь:
|
||||
Знайдіть у своєму плагіні імпорти з будь-якої із застарілих поверхонь:
|
||||
|
||||
```bash
|
||||
grep -r "plugin-sdk/compat" my-plugin/
|
||||
@ -116,9 +107,8 @@ OpenClaw перейшов від широкого шару зворотної с
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Замініть їх на цільові імпорти">
|
||||
Кожен експорт зі старої поверхні зіставляється з певним сучасним шляхом
|
||||
імпорту:
|
||||
<Step title="Замініть на точкові імпорти">
|
||||
Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту:
|
||||
|
||||
```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.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
@ -174,173 +163,173 @@ OpenClaw перейшов від широкого шару зворотної с
|
||||
<Accordion title="Таблиця поширених шляхів імпорту">
|
||||
| Шлях імпорту | Призначення | Ключові експорти |
|
||||
| --- | --- | --- |
|
||||
| `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 |
|
||||
</Accordion>
|
||||
|
||||
Ця таблиця навмисно містить поширену підмножину для міграції, а не повну
|
||||
поверхню 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) — довідник схеми маніфесту
|
||||
|
||||
@ -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. Ця сторінка —
|
||||
довідник про **що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте практичний посібник?**
|
||||
- Перший 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)
|
||||
</Tip>
|
||||
|
||||
## Правило імпорту
|
||||
@ -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` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи auth і безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
<Accordion title="Підшляхи автентифікації та безпеки">
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Підшлях | Ключові експорти |
|
||||
<Accordion title="Підшляхи runtime і сховищ">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Ключові експорти |
|
||||
| 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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Ключові експорти |
|
||||
| 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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи bundled-helper">
|
||||
| Сімейство | Поточні підшляхи | Призначення |
|
||||
<Accordion title="Зарезервовані підшляхи вбудованих helper-ів">
|
||||
| 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` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх типової конфігурації plugin перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після злиття (наприклад, для нормалізації старих форм прапорців).
|
||||
- `id` бекенду стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`.
|
||||
- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача як і раніше має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
|
||||
типового значення плагіна перед запуском 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<string, unknown>` | Конфігурація, специфічна для plugin, з `plugins.entries.<id>.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<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helper-и runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного 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 # Легка точка входу лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Facade-loaded публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні файли входу) тепер віддають
|
||||
перевагу активному 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-и онбордингу/конфігурації
|
||||
|
||||
<Warning>
|
||||
Production-код extension також має уникати імпортів
|
||||
`openclaw/plugin-sdk/<other-plugin>`. Якщо допоміжна функція справді є
|
||||
спільною, перенесіть її до нейтрального підшляху SDK, такого як
|
||||
`openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
capability-орієнтованої поверхні, замість жорсткого зв’язування двох plugins.
|
||||
Production-код розширень також повинен уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо helper справді є спільним, підніміть його до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
surface, орієнтованої на можливості, замість того, щоб зв’язувати два плагіни між собою.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
@ -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) — поглиблена архітектура та модель можливостей плагінів
|
||||
|
||||
@ -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-ключ і динамічним визначенням моделей.
|
||||
|
||||
<Info>
|
||||
Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Початок роботи](/uk/plugins/building-plugins) для базової структури пакета
|
||||
та налаштування маніфесту.
|
||||
Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Getting Started](/uk/plugins/building-plugins) про базову структуру
|
||||
пакета й налаштування маніфесту.
|
||||
</Info>
|
||||
|
||||
## Покроковий розбір
|
||||
## Покрокове проходження
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
@ -87,16 +87,16 @@ x-i18n:
|
||||
</CodeGroup>
|
||||
|
||||
Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти
|
||||
облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов’язковим
|
||||
і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ID моделей
|
||||
облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов'язковим
|
||||
і дає змогу OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими id моделей
|
||||
на кшталт `acme-large` ще до появи runtime hooks. Якщо ви публікуєте
|
||||
постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build`
|
||||
у `package.json` є обов’язковими.
|
||||
обов'язкові в `package.json`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Зареєструйте постачальника">
|
||||
Мінімальному постачальнику потрібні `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 <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 постачальника.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте динамічне визначення моделей">
|
||||
Якщо ваш постачальник приймає довільні ID моделей (наприклад, проксі або маршрутизатор),
|
||||
Якщо ваш постачальник приймає довільні id моделей (як проксі або маршрутизатор),
|
||||
додайте `resolveDynamicModel`:
|
||||
|
||||
```typescript
|
||||
@ -248,16 +248,16 @@ x-i18n:
|
||||
```
|
||||
|
||||
Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного
|
||||
попереднього прогріву — після його завершення `resolveDynamicModel` буде запущено знову.
|
||||
прогрівання — `resolveDynamicModel` буде запущено знову після його завершення.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте runtime hooks (за потреби)">
|
||||
Більшості постачальників потрібні лише `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` експортує збирач постачальника
|
||||
плюс допоміжні засоби для онбордингу/конфігурації
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Обмін токенами">
|
||||
Для постачальників, яким потрібен обмін токенами перед кожним викликом inference:
|
||||
<Tab title="Обмін токенів">
|
||||
Для постачальників, яким потрібен обмін токенів перед кожним викликом inference:
|
||||
|
||||
```typescript
|
||||
prepareRuntimeAuth: async (ctx) => {
|
||||
@ -404,8 +404,8 @@ x-i18n:
|
||||
},
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Користувацькі заголовки">
|
||||
Для постачальників, яким потрібні користувацькі заголовки запиту або модифікації тіла:
|
||||
<Tab title="Власні заголовки">
|
||||
Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту:
|
||||
|
||||
```typescript
|
||||
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
|
||||
@ -422,9 +422,9 @@ x-i18n:
|
||||
},
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Ідентичність нативного транспорту">
|
||||
Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в
|
||||
універсальних HTTP- або WebSocket-транспортах:
|
||||
<Tab title="Ідентичність нативного transport">
|
||||
Для постачальників, яким потрібні нативні заголовки або метадані
|
||||
запиту/сеансу в загальних transport HTTP або WebSocket:
|
||||
|
||||
```typescript
|
||||
resolveTransportTurnState: (ctx) => ({
|
||||
@ -444,8 +444,8 @@ x-i18n:
|
||||
}),
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Використання і білінг">
|
||||
Для постачальників, які надають дані про використання/білінг:
|
||||
<Tab title="Usage і білінг">
|
||||
Для постачальників, які надають дані usage/білінгу:
|
||||
|
||||
```typescript
|
||||
resolveUsageAuth: async (ctx) => {
|
||||
@ -460,79 +460,79 @@ x-i18n:
|
||||
</Tabs>
|
||||
|
||||
<Accordion title="Усі доступні hooks постачальника">
|
||||
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.<id>` |
|
||||
| 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).
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте додаткові можливості (необов’язково)">
|
||||
<Step title="Додайте додаткові можливості (необов'язково)">
|
||||
<a id="step-5-add-extra-capabilities"></a>
|
||||
Плагін постачальника може реєструвати 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`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Тестування">
|
||||
<Step title="Протестуйте">
|
||||
<a id="step-6-test"></a>
|
||||
```typescript src/provider.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -691,7 +696,7 @@ x-i18n:
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Публікація в ClawHub
|
||||
## Опублікуйте в ClawHub
|
||||
|
||||
Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін:
|
||||
|
||||
@ -707,29 +712,29 @@ clawhub package publish your-org/your-plugin
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/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 і вбудовані приклади
|
||||
|
||||
201
docs/uk/plugins/webhooks.md
Normal file
201
docs/uk/plugins/webhooks.md
Normal file
@ -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/<routeId>`
|
||||
- `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 <secret>` або `x-openclaw-webhook-secret: <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)
|
||||
@ -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, якщо вони вже налаштовані, і далі
|
||||
враховуються під час виконання.
|
||||
|
||||
<Warning>
|
||||
Для 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).
|
||||
</Warning>
|
||||
|
||||
## Варіант 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:<level>`) або в params моделі:
|
||||
- Для моделей Anthropic Claude 4.6 в OpenClaw типовим значенням є `adaptive` thinking, якщо явний рівень thinking не задано.
|
||||
- Ви можете перевизначити його для окремого повідомлення (`/think:<level>`) або в параметрах моделі:
|
||||
`agents.defaults.models["anthropic/<model>"].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).
|
||||
|
||||
@ -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.<provider>.models[].contextTokens`:
|
||||
Якщо вам потрібне інше ефективне обмеження, установіть `models.providers.<provider>.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.<provider/model>.params.transport`:
|
||||
Ви можете встановити `agents.defaults.models.<provider/model>.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["<provider>/<model>"].params.serviceTier`,
|
||||
щоб передавати це поле далі на нативні кінцеві точки OpenAI/Codex Responses.
|
||||
OpenClaw установіть `agents.defaults.models["<provider>/<model>"].params.serviceTier`,
|
||||
щоб передати це поле далі на нативних endpoint OpenAI/Codex Responses.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -384,34 +399,34 @@ OpenClaw задайте `agents.defaults.models["<provider>/<model>"].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["<provider>/<model>"].params.fastMode`
|
||||
- Чат/UI: `/fast status|on|off`
|
||||
- Config: `agents.defaults.models["<provider>/<model>"].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).
|
||||
|
||||
@ -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.<name>.apiKey`), які можуть експортувати ключі в env процесу Skill.
|
||||
- **Skills** (`skills.entries.<name>.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.<name>.apiKey`. Якщо Skill використовує цей ключ для зовнішніх
|
||||
API, це може спричиняти витрати відповідно до провайдера цього Skill.
|
||||
Skills можуть зберігати `apiKey` у `skills.entries.<name>.apiKey`. Якщо skill використовує цей ключ для зовнішніх
|
||||
API, це може спричиняти витрати відповідно до постачальника цього skill.
|
||||
|
||||
Див. [Skills](/tools/skills).
|
||||
Див. [Skills](/uk/tools/skills).
|
||||
|
||||
@ -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=<n>`, а для докладних логів установіть `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=<n>`, а для докладних логів установіть `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 <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
|
||||
Якщо `pnpm test` дає флейки на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
|
||||
|
||||
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
|
||||
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
|
||||
@ -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
|
||||
|
||||
@ -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.<provider>.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).
|
||||
|
||||
@ -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).
|
||||
|
||||
## Деталі процесу (локальний режим)
|
||||
## Докладно про потік (локальний режим)
|
||||
|
||||
<Steps>
|
||||
<Step title="Виявлення наявної конфігурації">
|
||||
- Якщо існує `~/.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)
|
||||
</Step>
|
||||
<Step title="Модель/автентифікація">
|
||||
- **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/<agentId>/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/<agentId>/agent/auth-profiles.json` (API-ключі + OAuth). `~/.openclaw/credentials/oauth.json` — лише застаріле джерело імпорту.
|
||||
- Докладніше: [/concepts/oauth](/uk/concepts/oauth)
|
||||
<Note>
|
||||
Порада для headless/server: завершіть OAuth на машині з браузером, а потім скопіюйте
|
||||
Порада для безголових серверів: завершіть OAuth на машині з браузером, а потім скопіюйте
|
||||
`auth-profiles.json` цього агента (наприклад,
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` або відповідний шлях
|
||||
`$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json`
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` або відповідний
|
||||
шлях `$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json`
|
||||
є лише застарілим джерелом імпорту.
|
||||
</Note>
|
||||
</Step>
|
||||
<Step title="Workspace">
|
||||
- Типово `~/.openclaw/workspace` (можна налаштувати).
|
||||
- Ініціалізує файли workspace, потрібні для bootstrap ritual агента.
|
||||
- Повна структура workspace + інструкція з резервного копіювання: [Agent workspace](/uk/concepts/agent-workspace)
|
||||
- Ініціалізує файли workspace, потрібні для ритуалу початкового запуску агента.
|
||||
- Повну структуру workspace та посібник із резервного копіювання див. тут: [Agent workspace](/uk/concepts/agent-workspace)
|
||||
</Step>
|
||||
<Step title="Gateway">
|
||||
- Порт, 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 <ENV_VAR>`.
|
||||
- Потребує непорожньої змінної середовища в середовищі процесу онбордингу.
|
||||
- **Згенерувати/зберегти 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 <ENV_VAR>`.
|
||||
- Потребує непорожньої змінної середовища в оточенні процесу онбордингу.
|
||||
- Не можна поєднувати з `--gateway-token`.
|
||||
- Вимикайте автентифікацію, лише якщо повністю довіряєте кожному локальному процесу.
|
||||
- Для bind, відмінних від loopback, автентифікація все одно обов’язкова.
|
||||
- Вимикайте автентифікацію лише якщо ви повністю довіряєте кожному локальному процесу.
|
||||
- Прив’язки не до loopback усе одно вимагають автентифікації.
|
||||
</Step>
|
||||
<Step title="Канали">
|
||||
- [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 <channel> <code>` або використовуйте списки дозволених.
|
||||
- Безпека DM: типово використовується pairing. Перше DM надсилає код; підтвердіть через `openclaw pairing approve <channel> <code>` або використовуйте allowlists.
|
||||
</Step>
|
||||
<Step title="Вебпошук">
|
||||
- Виберіть підтримуваного провайдера, наприклад 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`.
|
||||
</Step>
|
||||
<Step title="Встановлення демона">
|
||||
- macOS: LaunchAgent
|
||||
- Потребує активної сесії користувача; для headless використовуйте власний LaunchDaemon (не постачається).
|
||||
- Linux (і Windows через WSL2): користувацький модуль systemd
|
||||
- Під час онбордингу виконується спроба ввімкнути lingering через `loginctl enable-linger <user>`, щоб 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 <user>`, щоб 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` не задано, встановлення демона блокується, доки режим не буде явно вказано.
|
||||
</Step>
|
||||
<Step title="Перевірка працездатності">
|
||||
<Step title="Перевірка стану">
|
||||
- Запускає Gateway (за потреби) і виконує `openclaw health`.
|
||||
- Порада: `openclaw status --deep` додає до виводу статусу live gateway health probe, включно з перевірками каналів, де це підтримується (потребує доступного gateway).
|
||||
- Порада: `openclaw status --deep` додає живу перевірку стану gateway до виводу status, зокрема probe каналів, коли вони підтримуються (потрібен доступний gateway).
|
||||
</Step>
|
||||
<Step title="Skills (рекомендовано)">
|
||||
- Зчитує доступні Skills і перевіряє вимоги.
|
||||
- Дає змогу вибрати менеджер Node: **npm / pnpm** (bun не рекомендовано).
|
||||
- Установлює необов’язкові залежності (деякі використовують Homebrew у macOS).
|
||||
- Дає змогу вибрати менеджер node: **npm / pnpm** (bun не рекомендовано).
|
||||
- Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS).
|
||||
</Step>
|
||||
<Step title="Завершення">
|
||||
- Підсумок + наступні кроки, зокрема застосунки для iOS/Android/macOS для додаткових можливостей.
|
||||
- Підсумок + наступні кроки, зокрема застосунки для iOS/Android/macOS для додаткових функцій.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Якщо GUI не виявлено, онбординг виводить інструкції з пробросу порту SSH для Control UI замість відкриття браузера.
|
||||
Якщо ресурси Control UI відсутні, онбординг намагається їх зібрати; резервний варіант — `pnpm ui:build` (автоматично встановлює залежності UI).
|
||||
Якщо графічний інтерфейс не виявлено, онбординг друкує інструкції для переспрямування портів SSH для Control UI замість відкриття браузера.
|
||||
Якщо ресурси Control UI відсутні, онбординг намагається зібрати їх; резервний варіант — `pnpm ui:build` (автоматично встановлює UI-залежності).
|
||||
</Note>
|
||||
|
||||
## Неінтерактивний режим
|
||||
|
||||
Використовуйте `--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` є взаємовиключними.
|
||||
|
||||
<Note>
|
||||
`--json` **не** означає неінтерактивний режим. Для сценаріїв використовуйте `--non-interactive` (і `--workspace`).
|
||||
`--json` **не** означає неінтерактивний режим. Для скриптів використовуйте `--non-interactive` (і `--workspace`).
|
||||
</Note>
|
||||
|
||||
Приклади команд для конкретних провайдерів наведені в [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/<version>/`.
|
||||
- Записує `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/<accountId>/`.
|
||||
Сесії зберігаються в `~/.openclaw/agents/<agentId>/sessions/`.
|
||||
Облікові дані WhatsApp розміщуються в `~/.openclaw/credentials/whatsapp/<accountId>/`.
|
||||
Сеанси зберігаються в `~/.openclaw/agents/<agentId>/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)
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
## Приклади для окремих провайдерів
|
||||
## Приклади для конкретних провайдерів
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Приклад API-ключа Anthropic">
|
||||
@ -130,7 +130,7 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Синтетичний приклад">
|
||||
<Accordion title="Приклад Synthetic">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
@ -162,7 +162,7 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Приклад користувацького провайдера">
|
||||
<Accordion title="Приклад custom-провайдера">
|
||||
```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 \
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Anthropic setup-token знову доступний як застарілий/ручний шлях онбордингу.
|
||||
Використовуйте його з розумінням того, що Anthropic повідомила користувачам OpenClaw, що
|
||||
шлях входу Claude в OpenClaw потребує **Extra Usage**. Для виробничого використання віддавайте перевагу
|
||||
API-ключу Anthropic.
|
||||
Anthropic setup-token залишається доступним як підтримуваний шлях токена онбордингу, але OpenClaw тепер надає перевагу повторному використанню Claude CLI, коли це можливо.
|
||||
Для production надавайте перевагу API-ключу Anthropic.
|
||||
|
||||
## Додати ще одного агента
|
||||
|
||||
Використовуйте `openclaw agents add <name>`, щоб створити окремого агента з власним робочим простором,
|
||||
сесіями та профілями автентифікації. Запуск без `--workspace` відкриває майстер.
|
||||
Використовуйте `openclaw agents add <name>`, щоб створити окремого агента з власними 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-<agentId>`.
|
||||
- Робочі простори за замовчуванням мають формат `~/.openclaw/workspace-<agentId>`.
|
||||
- Додайте `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)
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
<Info>
|
||||
Найшвидший перший чат: відкрийте Control UI (налаштування каналів не потрібне). Запустіть
|
||||
Найшвидший перший чат: відкрийте Control UI (налаштування каналу не потрібне). Виконайте
|
||||
`openclaw dashboard` і спілкуйтеся в браузері. Документація: [Dashboard](/web/dashboard).
|
||||
</Info>
|
||||
|
||||
Щоб пізніше змінити налаштування:
|
||||
Щоб змінити налаштування пізніше:
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
@ -42,71 +42,71 @@ openclaw agents add <name>
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Онбординг 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).
|
||||
</Tip>
|
||||
|
||||
## QuickStart проти Advanced
|
||||
## QuickStart чи Advanced
|
||||
|
||||
Онбординг починається з вибору **QuickStart** (типові параметри) або **Advanced** (повний контроль).
|
||||
Онбординг починається з вибору **QuickStart** (типові значення) або **Advanced** (повний контроль).
|
||||
|
||||
<Tabs>
|
||||
<Tab title="QuickStart (типові параметри)">
|
||||
<Tab title="QuickStart (типові значення)">
|
||||
- Локальний 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** (вам запропонують вказати ваш номер телефону)
|
||||
</Tab>
|
||||
<Tab title="Advanced (повний контроль)">
|
||||
- Показує кожен крок (режим, робочий простір, gateway, канали, демон, Skills).
|
||||
- Відкриває всі кроки (режим, workspace, gateway, канали, daemon, Skills).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Що налаштовує онбординг
|
||||
|
||||
**Локальний режим (типовий)** проводить вас через такі кроки:
|
||||
**Локальний режим (за замовчуванням)** проводить вас через такі кроки:
|
||||
|
||||
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 <ENV_VAR>`.
|
||||
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 <ENV_VAR>`.
|
||||
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 і необов’язкові залежності.
|
||||
|
||||
<Note>
|
||||
Повторний запуск онбордингу **не** стирає нічого, якщо ви явно не виберете **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`.
|
||||
</Note>
|
||||
|
||||
**Віддалений режим** лише налаштовує локальний клієнт для підключення до Gateway в іншому місці.
|
||||
Він **не** встановлює і **не** змінює нічого на віддаленому хості.
|
||||
**Віддалений режим** налаштовує лише локальний клієнт для підключення до Gateway в іншому місці.
|
||||
Він **не** встановлює та не змінює нічого на віддаленому хості.
|
||||
|
||||
## Додати ще одного агента
|
||||
|
||||
Використовуйте `openclaw agents add <name>`, щоб створити окремого агента з власним робочим простором,
|
||||
сесіями та профілями автентифікації. Запуск без `--workspace` запускає онбординг.
|
||||
Використовуйте `openclaw agents add <name>`, щоб створити окремого агента з власними workspace,
|
||||
sessions і профілями автентифікації. Запуск без `--workspace` запускає онбординг.
|
||||
|
||||
Що це встановлює:
|
||||
Що він встановлює:
|
||||
|
||||
- `agents.list[].name`
|
||||
- `agents.list[].workspace`
|
||||
@ -114,21 +114,21 @@ API key, а інші працюють без ключа. Ви також мож
|
||||
|
||||
Примітки:
|
||||
|
||||
- Типові робочі простори мають формат `~/.openclaw/workspace-<agentId>`.
|
||||
- Workspace за замовчуванням мають формат `~/.openclaw/workspace-<agentId>`.
|
||||
- Додайте `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)
|
||||
|
||||
67
docs/uk/tools/media-overview.md
Normal file
67
docs/uk/tools/media-overview.md
Normal file
@ -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 | | | | |
|
||||
|
||||
<Note>
|
||||
Розуміння медіа використовує будь-яку модель із підтримкою vision або audio, зареєстровану у вашій конфігурації постачальника. У таблиці вище виділено постачальників зі спеціалізованою підтримкою розуміння медіа; більшість постачальників LLM із мультимодальними моделями (Anthropic, Google, OpenAI тощо) також можуть розуміти вхідні медіа, якщо їх налаштовано як активну модель відповіді.
|
||||
</Note>
|
||||
|
||||
## Як працює асинхронна генерація
|
||||
|
||||
Генерація відео та музики виконується як фонові завдання, оскільки обробка в постачальника зазвичай триває від 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) -- розуміння вхідних зображень, аудіо та відео
|
||||
@ -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 запускає генерацію музики як
|
||||
фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли трек готовий,
|
||||
щоб агент міг надіслати готове аудіо назад у
|
||||
початковий канал.
|
||||
|
||||
<Note>
|
||||
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або вкажіть API-ключ провайдера.
|
||||
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API key провайдера.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
### Генерація на основі спільного провайдера
|
||||
### Генерація через спільних провайдерів
|
||||
|
||||
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 <taskId>`, щоб переглядати статуси queued, running і terminal для генерації.
|
||||
- Пробудження після завершення: OpenClaw впроваджує внутрішню подію завершення назад у той самий сеанс, щоб модель могла самостійно написати користувацьке подальше повідомлення.
|
||||
- Підказка в prompt: пізніші користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку часу виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` знову бездумно.
|
||||
- Режим без сеансу: прямі/локальні контексти без реального сеансу агента все одно виконуються вбудовано й повертають фінальний результат аудіо в тому самому ході.
|
||||
- Запуски агента на основі сесії: `music_generate` створює фонове завдання, негайно повертає відповідь про запуск/завдання і пізніше надсилає готовий трек в окремому повідомленні агента.
|
||||
- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають стан завдання замість запуску нової генерації.
|
||||
- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерації музики, пов’язане із сесією, без запуску нового.
|
||||
- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб перевірити статуси 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 <taskId>
|
||||
openclaw tasks cancel <taskId>
|
||||
```
|
||||
|
||||
Запобігання дублюванню: якщо для поточної сесії вже є завдання музики зі станом `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)
|
||||
|
||||
@ -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-ключів.
|
||||
|
||||
<Note>
|
||||
Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви його не бачите серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
|
||||
Інструмент `video_generate` з’являється лише тоді, коли доступний щонайменше один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
|
||||
</Note>
|
||||
|
||||
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 <taskId>`, щоб перевірити хід виконання через CLI.
|
||||
Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан завдання замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб перевіряти прогрес із CLI.
|
||||
|
||||
Поза запусками агента на основі сесій (наприклад, під час прямих викликів інструмента) інструмент повертається до вбудованої генерації та повертає остаточний шлях до медіафайлу в тому самому ході.
|
||||
Поза агентськими запусками, що підтримуються сесією (наприклад, прямі виклики інструментів), інструмент переходить до вбудованої генерації й повертає фінальний шлях до медіа в тому самому ході.
|
||||
|
||||
### Життєвий цикл завдання
|
||||
|
||||
Кожен запит `video_generate` проходить через чотири стани:
|
||||
|
||||
1. **queued** -- завдання створено, очікує, поки провайдер прийме його.
|
||||
2. **running** -- провайдер виконує обробку (зазвичай 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності).
|
||||
3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову.
|
||||
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки.
|
||||
|
||||
Перевірка стану з CLI:
|
||||
|
||||
```bash
|
||||
openclaw tasks list
|
||||
openclaw tasks show <taskId>
|
||||
openclaw tasks cancel <taskId>
|
||||
```
|
||||
|
||||
Запобігання дублюванню: якщо для поточної сесії завдання відео вже має стан `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)
|
||||
|
||||
456
docs/uk/tts.md
456
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>`: налаштування провайдера, якими володіє провайдер, із ключем за id speech-провайдера.
|
||||
- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються в `messages.tts.providers.<id>` під час завантаження.
|
||||
- `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: <primary> -> <used>` плюс `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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user