chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4cc6690f2e
commit
8074591b98
File diff suppressed because it is too large
Load Diff
@ -1,41 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування Slack або налагодження режиму сокета/HTTP у Slack
|
||||
- Налаштування Slack або налагодження режиму socket/HTTP у Slack
|
||||
summary: Налаштування Slack і поведінка під час виконання (Socket Mode + URL-адреси HTTP-запитів)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T23:30:39Z"
|
||||
generated_at: "2026-04-25T00:01:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d0ab5b0865102175477bacac2ef948cdb2e42892fdfd5adb73afe89f0f482de5
|
||||
source_hash: d8d177cad1e795ecccf31cff486b9c8036bf91b22d122e8afbd9cfaf7635e4ea
|
||||
source_path: channels/slack.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Готово до production для особистих повідомлень і каналів через інтеграції застосунку Slack. Режим за замовчуванням — Socket Mode; також підтримуються URL-адреси HTTP-запитів.
|
||||
Готово до використання в продакшені для особистих повідомлень і каналів через інтеграції застосунку Slack. Типовий режим — Socket Mode; також підтримуються URL-адреси HTTP-запитів.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Прив’язка" icon="link" href="/uk/channels/pairing">
|
||||
Для особистих повідомлень Slack режим прив’язки використовується за замовчуванням.
|
||||
<Card title="Підключення" icon="link" href="/uk/channels/pairing">
|
||||
Особисті повідомлення Slack типово працюють у режимі підключення.
|
||||
</Card>
|
||||
<Card title="Слеш-команди" icon="terminal" href="/uk/tools/slash-commands">
|
||||
Вбудована поведінка команд і каталог команд.
|
||||
Нативна поведінка команд і каталог команд.
|
||||
</Card>
|
||||
<Card title="Усунення проблем із каналами" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
<Card title="Усунення проблем каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Швидке налаштування
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (за замовчуванням)">
|
||||
<Tab title="Socket Mode (типово)">
|
||||
<Steps>
|
||||
<Step title="Створіть новий застосунок Slack">
|
||||
У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- виберіть **from a manifest** і виберіть робочий простір для свого застосунку
|
||||
- вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче та продовжте створення
|
||||
- вставте [приклад manifest](#manifest-and-scope-checklist) нижче та продовжте створення
|
||||
- згенеруйте **App-Level Token** (`xapp-...`) з `connections:write`
|
||||
- встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`)
|
||||
</Step>
|
||||
@ -55,7 +55,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний варіант через змінні середовища (лише для облікового запису за замовчуванням):
|
||||
Резервний варіант через змінні середовища (лише для типового облікового запису):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -81,7 +81,7 @@ openclaw gateway
|
||||
У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- виберіть **from a manifest** і виберіть робочий простір для свого застосунку
|
||||
- вставте [приклад маніфесту](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням
|
||||
- вставте [приклад manifest](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням
|
||||
- збережіть **Signing Secret** для перевірки запитів
|
||||
- встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`)
|
||||
|
||||
@ -104,9 +104,9 @@ openclaw gateway
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте унікальні шляхи Webhook для багатокористувацького HTTP
|
||||
Використовуйте унікальні шляхи Webhook для багатьох облікових записів HTTP
|
||||
|
||||
Для кожного облікового запису задавайте окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували.
|
||||
Надайте кожному обліковому запису окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -123,11 +123,11 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Контрольний список маніфесту та scope
|
||||
## Контрольний список manifest і scope
|
||||
|
||||
Базовий маніфест застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` слеш-команди).
|
||||
Базовий manifest застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` для слеш-команди).
|
||||
|
||||
Базовий маніфест (Socket Mode за замовчуванням):
|
||||
Базовий manifest (Socket Mode типово):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -229,14 +229,14 @@ openclaw gateway
|
||||
}
|
||||
```
|
||||
|
||||
### Додаткові налаштування маніфесту
|
||||
### Додаткові параметри manifest
|
||||
|
||||
Описано різні можливості, які розширюють наведені вище значення за замовчуванням.
|
||||
Показують різні можливості, що розширюють наведені вище типові значення.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Необов’язкові вбудовані слеш-команди">
|
||||
<Accordion title="Необов’язкові нативні слеш-команди">
|
||||
|
||||
Можна використовувати кілька [вбудованих слеш-команд](#commands-and-slash-behavior) замість однієї налаштованої команди, з такими нюансами:
|
||||
Кілька [нативних слеш-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами:
|
||||
|
||||
- Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована.
|
||||
- Одночасно можна зробити доступними не більше 25 слеш-команд.
|
||||
@ -244,7 +244,7 @@ openclaw gateway
|
||||
Замініть наявний розділ `features.slash_commands` на підмножину [доступних команд](/uk/tools/slash-commands#command-list):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (за замовчуванням)">
|
||||
<Tab title="Socket Mode (типово)">
|
||||
|
||||
```json
|
||||
"slash_commands": [
|
||||
@ -385,11 +385,11 @@ openclaw gateway
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Необов’язкові scope авторства (операції запису)">
|
||||
Додайте bot scope `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували активну ідентичність агента (власні ім’я користувача та іконку) замість типової ідентичності застосунку Slack.
|
||||
Додайте bot scope `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власні ім’я користувача та значок) замість типової ідентичності застосунку Slack.
|
||||
|
||||
Якщо ви використовуєте іконку emoji, Slack очікує синтаксис `:emoji_name:`.
|
||||
Якщо ви використовуєте значок emoji, Slack очікує синтаксис `:emoji_name:`.
|
||||
</Accordion>
|
||||
<Accordion title="Необов’язкові scope токена користувача (операції читання)">
|
||||
<Accordion title="Необов’язкові scope user token (операції читання)">
|
||||
Якщо ви налаштовуєте `channels.slack.userToken`, типовими scope читання є:
|
||||
|
||||
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
|
||||
@ -398,7 +398,7 @@ openclaw gateway
|
||||
- `reactions:read`
|
||||
- `pins:read`
|
||||
- `emoji:read`
|
||||
- `search:read` (якщо ви покладаєтеся на читання через пошук Slack)
|
||||
- `search:read` (якщо ви покладаєтесь на читання через пошук Slack)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -406,43 +406,43 @@ openclaw gateway
|
||||
## Модель токенів
|
||||
|
||||
- Для Socket Mode потрібні `botToken` + `appToken`.
|
||||
- Для HTTP mode потрібні `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові
|
||||
- Для режиму HTTP потрібні `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні
|
||||
рядки або об’єкти SecretRef.
|
||||
- Токени в конфігурації мають пріоритет над резервними значеннями зі змінних середовища.
|
||||
- Резервне значення зі змінних середовища `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного значення через змінні середовища) і за замовчуванням працює лише для читання (`userTokenReadOnly: true`).
|
||||
- Токени в конфігурації мають пріоритет над резервним варіантом через env.
|
||||
- Резервний варіант через env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до типового облікового запису.
|
||||
- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного варіанту через env) і типово працює лише для читання (`userTokenReadOnly: true`).
|
||||
|
||||
Поведінка знімка стану:
|
||||
|
||||
- Перевірка облікового запису Slack відстежує для кожних облікових даних поля
|
||||
`*Source` і `*Status` (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- Статус може бути `available`, `configured_unavailable` або `missing`.
|
||||
- `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef
|
||||
або інше не вбудоване джерело секретів, але поточний шлях команди/виконання
|
||||
- Перевірка облікового запису Slack відстежує поля `*Source` і `*Status`
|
||||
для кожних облікових даних (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- Статус має значення `available`, `configured_unavailable` або `missing`.
|
||||
- `configured_unavailable` означає, що обліковий запис налаштований через SecretRef
|
||||
або інше неinline-джерело секрету, але поточний шлях команди/виконання
|
||||
не зміг визначити фактичне значення.
|
||||
- У HTTP mode включається `signingSecretStatus`; у Socket Mode
|
||||
потрібна пара — `botTokenStatus` + `appTokenStatus`.
|
||||
- У режимі HTTP включається `signingSecretStatus`; у Socket Mode
|
||||
потрібною парою є `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Для дій/читання каталогів може надаватися перевага токену користувача, якщо його налаштовано. Для запису перевага все одно надається bot token; запис через user token дозволений лише коли `userTokenReadOnly: false`, а bot token недоступний.
|
||||
Для дій/читання каталогів user token може мати пріоритет, якщо його налаштовано. Для запису пріоритетним залишається bot token; запис через user token дозволений лише коли `userTokenReadOnly: false`, а bot token недоступний.
|
||||
</Tip>
|
||||
|
||||
## Дії та обмеження
|
||||
|
||||
Дії Slack керуються через `channels.slack.actions.*`.
|
||||
|
||||
Доступні групи дій у поточному інструментарії Slack:
|
||||
Доступні групи дій у поточному наборі інструментів Slack:
|
||||
|
||||
| Група | Типово |
|
||||
| ---------- | ------- |
|
||||
| messages | enabled |
|
||||
| reactions | enabled |
|
||||
| pins | enabled |
|
||||
| memberInfo | enabled |
|
||||
| emojiList | enabled |
|
||||
| messages | увімкнено |
|
||||
| reactions | увімкнено |
|
||||
| pins | увімкнено |
|
||||
| memberInfo | увімкнено |
|
||||
| emojiList | увімкнено |
|
||||
|
||||
Поточні дії для повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`.
|
||||
Поточні дії для повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ідентифікатори файлів Slack, показані у вхідних заповнювачах файлів, і повертає попередній перегляд зображень для зображень або метадані локального файла для інших типів файлів.
|
||||
|
||||
## Керування доступом і маршрутизація
|
||||
|
||||
@ -452,7 +452,7 @@ openclaw gateway
|
||||
|
||||
- `pairing` (типово)
|
||||
- `allowlist`
|
||||
- `open` (потребує, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`)
|
||||
- `open` (потрібно, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`)
|
||||
- `disabled`
|
||||
|
||||
Прапорці DM:
|
||||
@ -460,7 +460,7 @@ openclaw gateway
|
||||
- `dm.enabled` (типово true)
|
||||
- `channels.slack.allowFrom` (рекомендовано)
|
||||
- `dm.allowFrom` (застаріле)
|
||||
- `dm.groupEnabled` (для групових DM типово false)
|
||||
- `dm.groupEnabled` (групові DM типово false)
|
||||
- `dm.groupChannels` (необов’язковий allowlist MPIM)
|
||||
|
||||
Пріоритет для кількох облікових записів:
|
||||
@ -469,37 +469,37 @@ openclaw gateway
|
||||
- Іменовані облікові записи успадковують `channels.slack.allowFrom`, якщо їхній власний `allowFrom` не задано.
|
||||
- Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`.
|
||||
|
||||
Прив’язка в DM використовує `openclaw pairing approve slack <code>`.
|
||||
Підключення в DM використовує `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика каналів">
|
||||
<Tab title="Політика каналу">
|
||||
`channels.slack.groupPolicy` керує обробкою каналів:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
Allowlist каналів знаходиться в `channels.slack.channels` і має використовувати стабільні ID каналів.
|
||||
Allowlist каналів розміщується в `channels.slack.channels` і має використовувати стабільні ідентифікатори каналів.
|
||||
|
||||
Примітка щодо runtime: якщо `channels.slack` повністю відсутній (налаштування лише через env), runtime використовує резервне значення `groupPolicy="allowlist"` і записує попередження в журнал (навіть якщо задано `channels.defaults.groupPolicy`).
|
||||
Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується резервне значення `groupPolicy="allowlist"` і записується попередження в журнал (навіть якщо задано `channels.defaults.groupPolicy`).
|
||||
|
||||
Визначення імен/ID:
|
||||
Визначення імені/ідентифікатора:
|
||||
|
||||
- записи allowlist каналів і DM allowlist визначаються під час запуску, якщо доступ токена це дозволяє
|
||||
- нерозпізнані записи назв каналів зберігаються як налаштовано, але типово ігноруються під час маршрутизації
|
||||
- авторизація вхідних повідомлень і маршрутизація каналів типово працюють за принципом ID-first; пряме зіставлення імен користувачів/slug потребує `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- записи allowlist каналів і записи allowlist DM визначаються під час запуску, якщо доступ токена це дозволяє
|
||||
- нерозв’язані записи назв каналів зберігаються як налаштовані, але типово ігноруються для маршрутизації
|
||||
- вхідна авторизація та маршрутизація каналів типово виконуються за ідентифікатором; пряме зіставлення імені користувача/slug вимагає `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Згадки та користувачі каналів">
|
||||
Повідомлення в каналах типово проходять через обмеження за згадками.
|
||||
<Tab title="Згадки та користувачі каналу">
|
||||
Повідомлення в каналах типово обмежуються згадками.
|
||||
|
||||
Джерела згадок:
|
||||
|
||||
- явна згадка застосунку (`<@botId>`)
|
||||
- шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`)
|
||||
- неявна поведінка reply-to-bot у тредах (вимикається, коли `thread.requireExplicitMention` має значення `true`)
|
||||
- шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`)
|
||||
- неявна поведінка відповіді в гілці для бота (вимикається, коли `thread.requireExplicitMention` дорівнює `true`)
|
||||
|
||||
Керування для кожного каналу (`channels.slack.channels.<id>`; імена лише через визначення під час запуску або `dangerouslyAllowNameMatching`):
|
||||
|
||||
@ -510,35 +510,35 @@ openclaw gateway
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- формат ключа `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або wildcard `"*"`
|
||||
(застарілі ключі без префікса, як і раніше, зіставляються лише з `id:`)
|
||||
(застарілі ключі без префікса все ще зіставляються лише з `id:`)
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Треди, сесії та теги відповіді
|
||||
## Гілки, сесії та теги відповідей
|
||||
|
||||
- DM маршрутизуються як `direct`; канали — як `channel`; MPIM — як `group`.
|
||||
- Із типовим `session.dmScope=main` DM у Slack згортаються в основну сесію агента.
|
||||
- Із типовим `session.dmScope=main` DM у Slack згортаються до основної сесії агента.
|
||||
- Сесії каналів: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Відповіді в тредах можуть створювати суфікси сесій тредів (`:thread:<threadTs>`), коли це застосовно.
|
||||
- Типове значення `channels.slack.thread.historyScope` — `thread`; типове значення `thread.inheritParent` — `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` визначає, скільки наявних повідомлень треду буде отримано, коли починається нова сесія треду (типово `20`; встановіть `0`, щоб вимкнути).
|
||||
- `channels.slack.thread.requireExplicitMention` (типово `false`): коли має значення `true`, неявні згадки в тредах пригнічуються, і бот відповідає лише на явні згадки `@bot` усередині тредів, навіть якщо бот уже брав участь у треді. Без цього відповіді в треді за участю бота обходять обмеження `requireMention`.
|
||||
- Відповіді в гілках можуть створювати суфікси сесій гілок (`:thread:<threadTs>`), коли це застосовно.
|
||||
- `channels.slack.thread.historyScope` типово має значення `thread`; `thread.inheritParent` типово має значення `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` визначає, скільки наявних повідомлень гілки отримується під час запуску нової сесії гілки (типово `20`; установіть `0`, щоб вимкнути).
|
||||
- `channels.slack.thread.requireExplicitMention` (типово `false`): коли має значення `true`, пригнічує неявні згадки в гілках, тому бот відповідає лише на явні згадки `@bot` усередині гілок, навіть якщо бот уже брав участь у гілці. Без цього відповіді в гілці, у якій брав участь бот, оминають обмеження `requireMention`.
|
||||
|
||||
Керування тредами відповідей:
|
||||
Елементи керування гілками відповідей:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched` (типово `off`)
|
||||
- `channels.slack.replyToModeByChatType`: для `direct|group|channel`
|
||||
- застаріле резервне значення для прямих чатів: `channels.slack.dm.replyToMode`
|
||||
- `channels.slack.replyToModeByChatType`: для кожного `direct|group|channel`
|
||||
- застарілий резервний варіант для прямих чатів: `channels.slack.dm.replyToMode`
|
||||
|
||||
Підтримуються ручні теги відповіді:
|
||||
Підтримуються ручні теги відповідей:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
Примітка: `replyToMode="off"` вимикає **усі** треди відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"` — треди Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими вбудовано.
|
||||
Примітка: `replyToMode="off"` вимикає **усі** гілки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"` — у Slack гілки приховують повідомлення з каналу, тоді як відповіді в Telegram залишаються видимими вбудовано.
|
||||
|
||||
## Реакції-підтвердження
|
||||
## Реакції підтвердження
|
||||
|
||||
`ackReaction` надсилає emoji-підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
@ -547,7 +547,7 @@ openclaw gateway
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- резервне значення emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Примітки:
|
||||
|
||||
@ -556,22 +556,22 @@ openclaw gateway
|
||||
|
||||
## Потокова передача тексту
|
||||
|
||||
`channels.slack.streaming` керує поведінкою live preview:
|
||||
`channels.slack.streaming` керує поведінкою попереднього перегляду в реальному часі:
|
||||
|
||||
- `off`: вимкнути потокову live preview.
|
||||
- `partial` (типово): замінювати текст попереднього перегляду останнім частковим виводом.
|
||||
- `block`: додавати оновлення попереднього перегляду частинами.
|
||||
- `off`: вимкнути потоковий попередній перегляд у реальному часі.
|
||||
- `partial` (типово): замінювати текст попереднього перегляду найновішим частковим виводом.
|
||||
- `block`: додавати порційні оновлення попереднього перегляду.
|
||||
- `progress`: показувати текст стану прогресу під час генерації, а потім надсилати фінальний текст.
|
||||
- `streaming.preview.toolProgress`: коли чернетковий попередній перегляд активний, спрямовувати оновлення інструментів/прогресу в те саме редаговане повідомлення попереднього перегляду (типово: `true`). Встановіть `false`, щоб залишити окремі повідомлення інструментів/прогресу.
|
||||
- `streaming.preview.toolProgress`: коли активний чернетковий попередній перегляд, спрямовувати оновлення інструментів/прогресу в те саме відредаговане повідомлення попереднього перегляду (типово: `true`). Установіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу.
|
||||
|
||||
`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`).
|
||||
`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` дорівнює `partial` (типово: `true`).
|
||||
|
||||
- Для нативної потокової передачі тексту та появи статусу треду Slack assistant має бути доступний тред відповіді. Вибір треду, як і раніше, підпорядковується `replyToMode`.
|
||||
- Корені каналів і групових чатів усе ще можуть використовувати звичайний чернетковий попередній перегляд, коли нативна потокова передача недоступна.
|
||||
- DM верхнього рівня в Slack типово залишаються поза тредами, тому не показують попередній перегляд у стилі треду; використовуйте відповіді в тредах або `typingReaction`, якщо там потрібен видимий прогрес.
|
||||
- Для медіа та нетекстових payload використовується звичайне доставлення.
|
||||
- Фінальні повідомлення media/error скасовують відкладені редагування попереднього перегляду; придатні фінальні повідомлення text/block скидаються лише тоді, коли можуть відредагувати попередній перегляд на місці.
|
||||
- Якщо потокова передача зламається посеред відповіді, OpenClaw переходить на звичайне доставлення для решти payload.
|
||||
- Для нативної потокової передачі тексту та відображення статусу гілки помічника Slack має бути доступна гілка відповіді. Вибір гілки все одно підпорядковується `replyToMode`.
|
||||
- Кореневі повідомлення каналів і групових чатів усе ще можуть використовувати звичайний чернетковий попередній перегляд, коли нативна потокова передача недоступна.
|
||||
- DM верхнього рівня в Slack типово залишаються поза гілками, тому не показують попередній перегляд у стилі гілки; використовуйте відповіді в гілках або `typingReaction`, якщо хочете видимий прогрес там.
|
||||
- Для медіа й нетекстових корисних навантажень використовується звичайна доставка.
|
||||
- Фінальні медіа/помилки скасовують відкладені редагування попереднього перегляду; придатні фінальні текстові/блокові відповіді скидаються лише тоді, коли можуть відредагувати попередній перегляд на місці.
|
||||
- Якщо потокова передача збоїть посеред відповіді, OpenClaw повертається до звичайної доставки для решти корисних навантажень.
|
||||
|
||||
Використовуйте чернетковий попередній перегляд замість нативної потокової передачі тексту Slack:
|
||||
|
||||
@ -590,13 +590,13 @@ openclaw gateway
|
||||
|
||||
Застарілі ключі:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрує до `channels.slack.streaming.mode`.
|
||||
- булеве значення `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрується до `channels.slack.streaming.mode`.
|
||||
- булеве `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`.
|
||||
- застаріле `channels.slack.nativeStreaming` автоматично мігрує до `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Резервна реакція набору тексту
|
||||
|
||||
`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення виконання. Це найкорисніше поза відповідями в тредах, де використовується типовий індикатор стану "is typing...".
|
||||
`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення виконання. Це найбільш корисно поза відповідями в гілках, які використовують типовий індикатор стану "is typing...".
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
@ -606,26 +606,26 @@ openclaw gateway
|
||||
Примітки:
|
||||
|
||||
- Slack очікує shortcodes (наприклад, `"hourglass_flowing_sand"`).
|
||||
- Реакція виконується за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або шляху помилки.
|
||||
- Реакція надсилається за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або сценарію помилки.
|
||||
|
||||
## Медіа, розбиття на частини та доставлення
|
||||
## Медіа, розбиття на частини та доставка
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вхідні вкладення">
|
||||
Файлові вкладення Slack завантажуються з приватних URL-адрес, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, якщо отримання успішне та дозволяють обмеження розміру.
|
||||
Вкладення файлів Slack завантажуються з приватних URL-адрес, що хостяться Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, якщо отримання успішне та дозволяють обмеження розміру. Заповнювачі файлів включають Slack `fileId`, щоб агенти могли отримати оригінальний файл через `download-file`.
|
||||
|
||||
Типове обмеження розміру вхідних даних у runtime — `20MB`, якщо не перевизначено через `channels.slack.mediaMaxMb`.
|
||||
Типове обмеження розміру вхідних даних під час виконання — `20MB`, якщо не перевизначено через `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вихідний текст і файли">
|
||||
- текстові частини використовують `channels.slack.textChunkLimit` (типово 4000)
|
||||
- частини тексту використовують `channels.slack.textChunkLimit` (типово 4000)
|
||||
- `channels.slack.chunkMode="newline"` вмикає розбиття спочатку за абзацами
|
||||
- надсилання файлів використовує API завантаження Slack і може включати відповіді в тредах (`thread_ts`)
|
||||
- обмеження вихідних медіа дотримується `channels.slack.mediaMaxMb`, якщо його налаштовано; інакше надсилання в канал використовують типові значення MIME-kind із медіапайплайна
|
||||
- надсилання файлів використовує API завантаження Slack і може включати відповіді в гілках (`thread_ts`)
|
||||
- обмеження вихідних медіа підпорядковується `channels.slack.mediaMaxMb`, якщо налаштовано; інакше для надсилання в канали використовуються типові MIME-kind з медіаконвеєра
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Цілі доставлення">
|
||||
<Accordion title="Цілі доставки">
|
||||
Бажані явні цілі:
|
||||
|
||||
- `user:<id>` для DM
|
||||
@ -638,7 +638,7 @@ openclaw gateway
|
||||
|
||||
## Команди та поведінка слеш-команд
|
||||
|
||||
Слеш-команди відображаються в Slack або як одна налаштована команда, або як кілька вбудованих команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команди:
|
||||
Слеш-команди з’являються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команди:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -649,30 +649,30 @@ openclaw gateway
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
Вбудовані команди потребують [додаткових налаштувань маніфесту](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях.
|
||||
Нативні команди потребують [додаткових параметрів manifest](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях.
|
||||
|
||||
- Режим auto для вбудованих команд у Slack **вимкнений**, тому `commands.native: "auto"` не вмикає вбудовані команди Slack.
|
||||
- Автоматичний режим нативних команд для Slack **вимкнено**, тому `commands.native: "auto"` не вмикає нативні команди Slack.
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
Меню аргументів вбудованих команд використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед відправленням значення вибраного параметра:
|
||||
Нативні меню аргументів використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед надсиланням вибраного значення параметра:
|
||||
|
||||
- до 5 параметрів: button blocks
|
||||
- 6-100 параметрів: static select menu
|
||||
- понад 100 параметрів: external select з асинхронною фільтрацією параметрів, якщо доступні обробники параметрів interactivity
|
||||
- перевищено ліміти Slack: закодовані значення параметрів повертаються до buttons
|
||||
- до 5 варіантів: блоки кнопок
|
||||
- 6-100 варіантів: статичне меню вибору
|
||||
- більше 100 варіантів: зовнішній вибір з асинхронною фільтрацією варіантів, якщо доступні обробники параметрів інтерактивності
|
||||
- перевищено обмеження Slack: закодовані значення варіантів резервно переходять до кнопок
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
Сесії слеш-команд використовують ізольовані ключі на кшталт `agent:<agentId>:slack:slash:<userId>` і все одно маршрутизують виконання команд до цільової сесії розмови через `CommandTargetSessionKey`.
|
||||
Сесії слеш-команд використовують ізольовані ключі, такі як `agent:<agentId>:slack:slash:<userId>`, і все ще маршрутизують виконання команд до сесії цільової розмови за допомогою `CommandTargetSessionKey`.
|
||||
|
||||
## Інтерактивні відповіді
|
||||
|
||||
Slack може рендерити інтерактивні елементи відповіді, створені агентом, але ця можливість типово вимкнена.
|
||||
Slack може відображати інтерактивні елементи керування відповідями, створеними агентом, але ця можливість типово вимкнена.
|
||||
|
||||
Увімкніть її глобально:
|
||||
|
||||
@ -688,7 +688,7 @@ Slack може рендерити інтерактивні елементи ві
|
||||
}
|
||||
```
|
||||
|
||||
Або увімкніть її лише для одного облікового запису Slack:
|
||||
Або увімкніть лише для одного облікового запису Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -706,43 +706,44 @@ Slack може рендерити інтерактивні елементи ві
|
||||
}
|
||||
```
|
||||
|
||||
Коли її ввімкнено, агенти можуть надсилати директиви відповіді лише для Slack:
|
||||
Коли функцію ввімкнено, агенти можуть виводити директиви відповідей лише для Slack:
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
Ці директиви компілюються в Slack Block Kit і маршрутизують натискання або вибір назад через наявний шлях подій взаємодії Slack.
|
||||
Ці директиви компілюються в Slack Block Kit і спрямовують натискання або вибори назад через наявний шлях подій взаємодії Slack.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Це UI, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок.
|
||||
- Значення інтерактивних callback — це непрозорі токени, згенеровані OpenClaw, а не сирі значення, створені агентом.
|
||||
- Якщо згенеровані інтерактивні блоки перевищують ліміти Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання невалідного payload blocks.
|
||||
- Значення інтерактивного callback — це непрозорі токени, згенеровані OpenClaw, а не необроблені значення, створені агентом.
|
||||
- Якщо згенеровані інтерактивні блоки перевищують обмеження Slack Block Kit, OpenClaw резервно повертається до початкової текстової відповіді замість надсилання некоректного payload блоків.
|
||||
|
||||
## Погодження exec у Slack
|
||||
## Підтвердження exec у Slack
|
||||
|
||||
Slack може працювати як нативний клієнт погодження з інтерактивними кнопками та взаємодіями замість переходу до Web UI або термінала.
|
||||
Slack може діяти як нативний клієнт підтвердження з інтерактивними кнопками та взаємодіями, замість резервного переходу до Web UI або термінала.
|
||||
|
||||
- Погодження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналів.
|
||||
- Погодження Plugin, як і раніше, можуть визначатися через ту саму Slack-native поверхню кнопок, коли запит уже надходить у Slack, а тип id погодження — `plugin:`.
|
||||
- Авторизація того, хто погоджує, як і раніше, примусово перевіряється: лише користувачі, ідентифіковані як ті, хто погоджує, можуть погоджувати або відхиляти запити через Slack.
|
||||
- Підтвердження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналів.
|
||||
- Підтвердження Plugin також можуть визначатися через ту саму нативну поверхню кнопок Slack, коли запит уже надходить у Slack, а тип ідентифікатора підтвердження — `plugin:`.
|
||||
- Авторизація того, хто підтверджує, усе ще примусово застосовується: лише користувачі, визначені як ті, хто підтверджує, можуть схвалювати або відхиляти запити через Slack.
|
||||
|
||||
Це використовує ту саму спільну поверхню кнопок погодження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на погодження відображаються як кнопки Block Kit безпосередньо в розмові.
|
||||
Коли ці кнопки присутні, вони є основним UX погодження; OpenClaw
|
||||
має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що погодження в чаті недоступні або ручне погодження — єдиний шлях.
|
||||
Це використовує ту саму спільну поверхню кнопок підтвердження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на підтвердження відображаються як кнопки Block Kit безпосередньо в розмові.
|
||||
Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw
|
||||
має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що підтвердження в чаті недоступні
|
||||
або ручне підтвердження є єдиним шляхом.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers` (необов’язково; за можливості використовує резервне значення `commands.ownerAllowFrom`)
|
||||
- `channels.slack.execApprovals.approvers` (необов’язково; за можливості використовує резервне значення з `commands.ownerAllowFrom`)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack автоматично вмикає нативні погодження exec, коли `enabled` не задано або має значення `"auto"` і визначається принаймні один користувач, що погоджує.
|
||||
Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт погодження.
|
||||
Установіть `enabled: true`, щоб примусово ввімкнути нативні погодження, коли визначаються користувачі, що погоджують.
|
||||
Slack автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"` і визначається принаймні один
|
||||
користувач, що підтверджує. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт підтвердження.
|
||||
Установіть `enabled: true`, щоб примусово ввімкнути нативні підтвердження, коли визначаються користувачі, що підтверджують.
|
||||
|
||||
Типова поведінка без явної конфігурації погодження exec для Slack:
|
||||
Типова поведінка без явної конфігурації підтвердження exec для Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -752,8 +753,8 @@ Slack автоматично вмикає нативні погодження ex
|
||||
}
|
||||
```
|
||||
|
||||
Явна Slack-native конфігурація потрібна лише тоді, коли ви хочете перевизначити користувачів, що погоджують, додати фільтри або
|
||||
використовувати доставлення до чату-джерела:
|
||||
Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити користувачів, що підтверджують, додати фільтри або
|
||||
вибрати доставку до початкового чату:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -769,38 +770,38 @@ Slack автоматично вмикає нативні погодження ex
|
||||
}
|
||||
```
|
||||
|
||||
Спільне переспрямування `approvals.exec` налаштовується окремо. Використовуйте його лише тоді, коли запити на погодження exec також мають
|
||||
маршрутизуватися до інших чатів або явно заданих зовнішніх цілей. Спільне переспрямування `approvals.plugin` також
|
||||
налаштовується окремо; Slack-native кнопки все одно можуть обробляти погодження Plugin, коли ці запити вже надходять
|
||||
Пересилання спільних `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити на підтвердження exec також мають
|
||||
маршрутизуватися в інші чати або явні позасмугові цілі. Пересилання спільних `approvals.plugin` також є
|
||||
окремим; нативні кнопки Slack усе ще можуть визначати підтвердження Plugin, коли ці запити вже надходять
|
||||
у Slack.
|
||||
|
||||
`/approve` у тому самому чаті також працює в каналах і DM Slack, які вже підтримують команди. Повну модель переспрямування погоджень див. у [Погодження exec](/uk/tools/exec-approvals).
|
||||
`/approve` у тому ж чаті також працює в каналах і DM Slack, які вже підтримують команди. Повну модель пересилання підтверджень див. у [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
## Події та операційна поведінка
|
||||
|
||||
- Редагування/видалення повідомлень зіставляються із системними подіями.
|
||||
- Thread broadcasts (відповіді в тредах з опцією "Also send to channel") обробляються як звичайні повідомлення користувачів.
|
||||
- Розсилки з гілок ("Also send to channel" для відповідей у гілках) обробляються як звичайні повідомлення користувача.
|
||||
- Події додавання/видалення реакцій зіставляються із системними подіями.
|
||||
- Події входу/виходу учасників, створення/перейменування каналів і додавання/видалення закріплень зіставляються із системними подіями.
|
||||
- `channel_id_changed` може мігрувати ключі конфігурації каналів, коли ввімкнено `configWrites`.
|
||||
- Метадані теми/призначення каналу вважаються недовіреним контекстом і можуть впроваджуватися в контекст маршрутизації.
|
||||
- Ініціатор треду та початкове наповнення контексту історією треду фільтруються за налаштованими allowlist відправників, де це застосовно.
|
||||
- Дії блоків і взаємодії з модальними вікнами створюють структуровані системні події `Slack interaction: ...` з насиченими полями payload:
|
||||
- дії блоків: вибрані значення, мітки, значення picker і метадані `workflow_*`
|
||||
- події модальних вікон `view_submission` і `view_closed` з метаданими маршрутизованого каналу та полями форм
|
||||
- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли ввімкнено `configWrites`.
|
||||
- Метадані topic/purpose каналу вважаються недовіреним контекстом і можуть бути вставлені в контекст маршрутизації.
|
||||
- Початкове повідомлення гілки та початкове заповнення контексту історії гілки фільтруються за налаштованими allowlist відправників, коли це застосовно.
|
||||
- Дії блоків і взаємодії з модальними вікнами генерують структуровані системні події `Slack interaction: ...` з розширеними полями payload:
|
||||
- дії блоків: вибрані значення, мітки, значення вибору та метадані `workflow_*`
|
||||
- події модальних вікон `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеними даними форми
|
||||
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [Довідник конфігурації - Slack](/uk/gateway/config-channels#slack).
|
||||
Основне посилання: [Довідник конфігурації - Slack](/uk/gateway/config-channels#slack).
|
||||
|
||||
<Accordion title="Високосигнальні поля Slack">
|
||||
<Accordion title="Ключові поля Slack">
|
||||
|
||||
- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- доступ до DM: `dm.enabled`, `dmPolicy`, `allowFrom` (застаріле: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний режим; залишайте вимкненим, якщо немає потреби)
|
||||
- перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний варіант; залишайте вимкненим, якщо не потрібно)
|
||||
- доступ до каналів: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- треди/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
- гілки/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
- операції/можливості: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
|
||||
</Accordion>
|
||||
@ -809,7 +810,7 @@ Slack автоматично вмикає нативні погодження ex
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Немає відповідей у каналах">
|
||||
Перевірте по черзі:
|
||||
Перевірте по порядку:
|
||||
|
||||
- `groupPolicy`
|
||||
- allowlist каналів (`channels.slack.channels`)
|
||||
@ -831,10 +832,10 @@ openclaw doctor
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`)
|
||||
- погодження прив’язки / записи allowlist
|
||||
- події Slack Assistant DM: докладні журнали з фразою `drop message_changed`
|
||||
зазвичай означають, що Slack надіслав подію редагування треду Assistant без
|
||||
придатного для відновлення відправника-людини в метаданих повідомлення
|
||||
- підтвердження підключення / записи allowlist
|
||||
- події DM Slack Assistant: докладні журнали з `drop message_changed`
|
||||
зазвичай означають, що Slack надіслав подію відредагованої гілки Assistant без
|
||||
людського відправника, якого можна відновити, у метаданих повідомлення
|
||||
|
||||
```bash
|
||||
openclaw pairing list slack
|
||||
@ -842,34 +843,34 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode не підключається">
|
||||
Перевірте bot token + app token і те, що Socket Mode увімкнено в налаштуваннях застосунку Slack.
|
||||
<Accordion title="Режим Socket не підключається">
|
||||
Перевірте bot token + app token і ввімкнення Socket Mode в налаштуваннях застосунку Slack.
|
||||
|
||||
Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або
|
||||
`appTokenStatus: "configured_unavailable"`, обліковий запис Slack
|
||||
налаштовано, але поточний runtime не зміг визначити значення,
|
||||
що надходить через SecretRef.
|
||||
налаштований, але поточне середовище виконання не змогло визначити значення,
|
||||
що походить із SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="HTTP mode не отримує події">
|
||||
<Accordion title="Режим HTTP не отримує події">
|
||||
Перевірте:
|
||||
|
||||
- signing secret
|
||||
- шлях webhook
|
||||
- Slack Request URLs (Events + Interactivity + Slash Commands)
|
||||
- унікальний `webhookPath` для кожного HTTP-облікового запису
|
||||
- URL-адреси запитів Slack (Events + Interactivity + Slash Commands)
|
||||
- унікальний `webhookPath` для кожного облікового запису HTTP
|
||||
|
||||
Якщо в знімках облікового запису з’являється `signingSecretStatus: "configured_unavailable"`,
|
||||
HTTP-обліковий запис налаштовано, але поточний runtime не зміг
|
||||
визначити signing secret, що надходить через SecretRef.
|
||||
Якщо `signingSecretStatus: "configured_unavailable"` з’являється у знімках
|
||||
облікового запису, обліковий запис HTTP налаштований, але поточне середовище виконання не змогло
|
||||
визначити signing secret, що походить із SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані/slash-команди не спрацьовують">
|
||||
Перевірте, що саме ви хотіли використати:
|
||||
<Accordion title="Нативні/слеш-команди не спрацьовують">
|
||||
Перевірте, що саме ви мали на увазі:
|
||||
|
||||
- режим вбудованих команд (`channels.slack.commands.native: true`) з відповідними слеш-командами, зареєстрованими в Slack
|
||||
- режим нативних команд (`channels.slack.commands.native: true`) з відповідними слеш-командами, зареєстрованими в Slack
|
||||
- або режим однієї слеш-команди (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Також перевірте `commands.useAccessGroups` і allowlist каналів/користувачів.
|
||||
@ -880,8 +881,8 @@ openclaw pairing list slack
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Прив’язка" icon="link" href="/uk/channels/pairing">
|
||||
Прив’яжіть користувача Slack до Gateway.
|
||||
<Card title="Підключення" icon="link" href="/uk/channels/pairing">
|
||||
Підключити користувача Slack до Gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка каналів і групових DM.
|
||||
@ -893,7 +894,7 @@ openclaw pairing list slack
|
||||
Модель загроз і посилення захисту.
|
||||
</Card>
|
||||
<Card title="Конфігурація" icon="sliders" href="/uk/gateway/configuration">
|
||||
Структура конфігурації та пріоритетність.
|
||||
Структура конфігурації та пріоритети.
|
||||
</Card>
|
||||
<Card title="Слеш-команди" icon="terminal" href="/uk/tools/slash-commands">
|
||||
Каталог команд і поведінка.
|
||||
|
||||
163
docs/uk/ci.md
163
docs/uk/ci.md
File diff suppressed because one or more lines are too long
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви використовуєте `openclaw browser` і хочете приклади для поширених завдань
|
||||
- Ви хочете керувати браузером, що працює на іншій машині, через вузол-хост
|
||||
- Ви хочете під’єднатися до свого локального Chrome, у якому виконано вхід, через Chrome MCP
|
||||
summary: Довідка CLI для `openclaw browser` (життєвий цикл, профілі, вкладки, дії, стан і налагодження)
|
||||
- Ви хочете керувати браузером, що працює на іншій машині, через хост вузла
|
||||
- Ви хочете під’єднатися до свого локального Chrome, у якому вже виконано вхід, через Chrome MCP
|
||||
summary: Довідник CLI для `openclaw browser` (життєвий цикл, профілі, вкладки, дії, стан і налагодження)
|
||||
title: Браузер
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T23:39:04Z"
|
||||
generated_at: "2026-04-25T00:01:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c6e9201d028d94c92dec9ee87fd6097a9cfa039c777a543ca424d8b9981618e7
|
||||
source_hash: fe7dcbc830044db4814fa1671807baae82ddcb32bd5228b165bfdbcddd5128de
|
||||
source_path: cli/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw browser`
|
||||
|
||||
Керуйте поверхнею керування браузером OpenClaw і виконуйте дії браузера (життєвий цикл, профілі, вкладки, знімки стану, знімки екрана, навігація, введення, емуляція стану та налагодження).
|
||||
Керуйте поверхнею керування браузером OpenClaw і виконуйте дії в браузері (життєвий цикл, профілі, вкладки, знімки, скриншоти, навігація, введення, емуляція стану та налагодження).
|
||||
|
||||
Пов’язано:
|
||||
Пов’язане:
|
||||
|
||||
- Інструмент браузера + API: [Інструмент браузера](/uk/tools/browser)
|
||||
- Інструмент Browser + API: [інструмент Browser](/uk/tools/browser)
|
||||
|
||||
## Поширені прапорці
|
||||
|
||||
- `--url <gatewayWsUrl>`: URL WebSocket Gateway (типово з конфігурації).
|
||||
- `--token <token>`: токен Gateway (якщо потрібен).
|
||||
- `--token <token>`: токен Gateway (за потреби).
|
||||
- `--timeout <ms>`: тайм-аут запиту (мс).
|
||||
- `--expect-final`: чекати на фінальну відповідь Gateway.
|
||||
- `--browser-profile <name>`: вибрати профіль браузера (типовий — з конфігурації).
|
||||
- `--expect-final`: чекати фінальну відповідь Gateway.
|
||||
- `--browser-profile <name>`: вибрати профіль браузера (типовий береться з конфігурації).
|
||||
- `--json`: машинозчитуваний вивід (де підтримується).
|
||||
|
||||
## Швидкий старт (локально)
|
||||
@ -40,24 +40,26 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
## Швидке усунення проблем
|
||||
## Швидке усунення несправностей
|
||||
|
||||
Якщо `start` завершується з помилкою `not reachable after start`, спершу перевірте готовність CDP. Якщо `start` і `tabs` працюють, але `open` або `navigate` завершується з помилкою, площина керування браузером справна, а збій зазвичай пов’язаний із політикою SSRF для навігації.
|
||||
Якщо `start` завершується помилкою `not reachable after start`, спочатку перевірте готовність CDP. Якщо `start` і `tabs` працюють, але `open` або `navigate` не працює, площина керування браузером справна, а збій зазвичай пов’язаний із політикою SSRF навігації.
|
||||
|
||||
Мінімальна послідовність:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw doctor
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw tabs
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
```
|
||||
|
||||
Докладні вказівки: [Усунення проблем із браузером](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
|
||||
Докладні вказівки: [усунення несправностей Browser](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
|
||||
|
||||
## Життєвий цикл
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
openclaw browser doctor
|
||||
openclaw browser start
|
||||
openclaw browser stop
|
||||
openclaw browser --browser-profile openclaw reset-profile
|
||||
@ -65,19 +67,14 @@ openclaw browser --browser-profile openclaw reset-profile
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для профілів `attachOnly` і віддалених CDP `openclaw browser stop` закриває
|
||||
активний сеанс керування та скидає тимчасові перевизначення емуляції, навіть
|
||||
якщо OpenClaw не запускав процес браузера самостійно.
|
||||
- Для локальних керованих профілів `openclaw browser stop` зупиняє запущений
|
||||
процес браузера.
|
||||
- Для профілів `attachOnly` і віддалених CDP `openclaw browser stop` закриває активний сеанс керування та скидає тимчасові перевизначення емуляції, навіть якщо OpenClaw сам не запускав процес браузера.
|
||||
- Для локальних керованих профілів `openclaw browser stop` зупиняє породжений процес браузера.
|
||||
|
||||
## Якщо команда відсутня
|
||||
|
||||
Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у
|
||||
`~/.openclaw/openclaw.json`.
|
||||
Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у `~/.openclaw/openclaw.json`.
|
||||
|
||||
Коли `plugins.allow` присутній, вбудований plugin браузера має бути явно
|
||||
вказаний у списку:
|
||||
Коли `plugins.allow` присутній, вбудований плагін браузера має бути явно вказаний у списку:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -87,16 +84,16 @@ openclaw browser --browser-profile openclaw reset-profile
|
||||
}
|
||||
```
|
||||
|
||||
`browser.enabled=true` не відновлює підкоманду CLI, якщо список дозволених plugin виключає `browser`.
|
||||
`browser.enabled=true` не відновлює підкоманду CLI, якщо список дозволених плагінів виключає `browser`.
|
||||
|
||||
Пов’язано: [Інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool)
|
||||
Пов’язане: [інструмент Browser](/uk/tools/browser#missing-browser-command-or-tool)
|
||||
|
||||
## Профілі
|
||||
|
||||
Профілі — це іменовані конфігурації маршрутизації браузера. На практиці:
|
||||
|
||||
- `openclaw`: запускає або під’єднується до виділеного екземпляра Chrome під керуванням OpenClaw (ізольований каталог даних користувача).
|
||||
- `user`: керує вашим наявним сеансом Chrome із виконаним входом через Chrome DevTools MCP.
|
||||
- `openclaw`: запускає або під’єднується до окремого екземпляра Chrome, яким керує OpenClaw (ізольований каталог користувацьких даних).
|
||||
- `user`: керує вашим наявним сеансом Chrome, у якому вже виконано вхід, через Chrome DevTools MCP.
|
||||
- власні профілі CDP: вказують на локальну або віддалену кінцеву точку CDP.
|
||||
|
||||
```bash
|
||||
@ -126,37 +123,34 @@ openclaw browser focus docs
|
||||
openclaw browser close t1
|
||||
```
|
||||
|
||||
`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`,
|
||||
необов’язкову мітку та сирий `targetId`. Агенти мають передавати
|
||||
`suggestedTargetId` назад у `focus`, `close`, знімки стану та дії. Ви можете
|
||||
призначити мітку за допомогою `open --label`, `tab new --label` або `tab label`; мітки,
|
||||
ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси target-id
|
||||
усі приймаються.
|
||||
`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`, необов’язкову мітку та сирий `targetId`. Агенти мають передавати `suggestedTargetId` назад у `focus`, `close`, знімки та дії. Ви можете призначити мітку за допомогою `open --label`, `tab new --label` або `tab label`; мітки, ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси ідентифікаторів цілей — усе це підтримується.
|
||||
|
||||
## Знімок стану / знімок екрана / дії
|
||||
## Знімок / скриншот / дії
|
||||
|
||||
Знімок стану:
|
||||
Знімок:
|
||||
|
||||
```bash
|
||||
openclaw browser snapshot
|
||||
openclaw browser snapshot --urls
|
||||
```
|
||||
|
||||
Знімок екрана:
|
||||
Скриншот:
|
||||
|
||||
```bash
|
||||
openclaw browser screenshot
|
||||
openclaw browser screenshot --full-page
|
||||
openclaw browser screenshot --ref e12
|
||||
openclaw browser screenshot --labels
|
||||
```
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--full-page` призначено лише для знімків сторінки; його не можна поєднувати з `--ref`
|
||||
або `--element`.
|
||||
- Профілі `existing-session` / `user` підтримують знімки екрана сторінки та знімки екрана `--ref`
|
||||
з виводу знімка стану, але не підтримують знімки екрана CSS `--element`.
|
||||
- `--full-page` призначений лише для захоплення сторінки; його не можна поєднувати з `--ref` або `--element`.
|
||||
- Профілі `existing-session` / `user` підтримують скриншоти сторінок і скриншоти `--ref` із виводу знімка, але не підтримують скриншоти CSS `--element`.
|
||||
- `--labels` накладає поточні посилання знімка на скриншот.
|
||||
- `snapshot --urls` додає виявлені адреси посилань до AI-знімків, щоб агенти могли вибирати прямі цілі навігації замість здогадок лише за текстом посилання.
|
||||
|
||||
Навігація/клацання/введення (автоматизація UI на основі ref):
|
||||
Navigate/click/type (автоматизація UI на основі ref):
|
||||
|
||||
```bash
|
||||
openclaw browser navigate https://example.com
|
||||
@ -183,7 +177,7 @@ openclaw browser dialog --accept
|
||||
|
||||
## Стан і сховище
|
||||
|
||||
Вікно перегляду + емуляція:
|
||||
Viewport + емуляція:
|
||||
|
||||
```bash
|
||||
openclaw browser resize 1280 720
|
||||
@ -233,34 +227,31 @@ openclaw browser create-profile --name brave-live --driver existing-session --us
|
||||
openclaw browser --browser-profile chrome-live tabs
|
||||
```
|
||||
|
||||
Цей шлях доступний лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених налаштувань використовуйте натомість профіль CDP.
|
||||
Цей шлях доступний лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених сценаріїв використовуйте профіль CDP.
|
||||
|
||||
Поточні обмеження existing-session:
|
||||
|
||||
- дії на основі знімка стану використовують ref, а не CSS-селектори
|
||||
- `click` підтримує лише клацання лівою кнопкою
|
||||
- дії на основі знімків використовують ref, а не CSS-селектори
|
||||
- `click` підтримує лише лівий клік
|
||||
- `type` не підтримує `slowly=true`
|
||||
- `press` не підтримує `delayMs`
|
||||
- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють
|
||||
перевизначення тайм-ауту для окремих викликів
|
||||
- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють перевизначення тайм-ауту для окремого виклику
|
||||
- `select` підтримує лише одне значення
|
||||
- `wait --load networkidle` не підтримується
|
||||
- вивантаження файлів потребує `--ref` / `--input-ref`, не підтримує CSS
|
||||
`--element`, і наразі підтримує по одному файлу за раз
|
||||
- перехоплювачі діалогів не підтримують `--timeout`
|
||||
- знімки екрана підтримують знімки сторінки та `--ref`, але не CSS `--element`
|
||||
- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії все ще
|
||||
потребують керованого браузера або сирого профілю CDP
|
||||
- завантаження файлів вимагає `--ref` / `--input-ref`, не підтримує CSS `--element` і наразі підтримує лише один файл за раз
|
||||
- обробники діалогів не підтримують `--timeout`
|
||||
- скриншоти підтримують захоплення сторінки та `--ref`, але не CSS `--element`
|
||||
- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії, як і раніше, вимагають керованого браузера або сирого профілю CDP
|
||||
|
||||
## Віддалене керування браузером (проксі вузла-хоста)
|
||||
## Віддалене керування браузером (проксі хоста вузла)
|
||||
|
||||
Якщо Gateway працює на іншій машині, ніж браузер, запустіть **вузол-хост** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксіюватиме дії браузера до цього вузла (окремий сервер керування браузером не потрібен).
|
||||
Якщо Gateway працює на іншій машині, ніж браузер, запустіть **хост вузла** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксуватиме дії браузера до цього вузла (окремий сервер керування браузером не потрібен).
|
||||
|
||||
Використовуйте `gateway.nodes.browser.mode` для керування автоматичною маршрутизацією та `gateway.nodes.browser.node` для прив’язки до конкретного вузла, якщо підключено кілька вузлів.
|
||||
Використовуйте `gateway.nodes.browser.mode` для керування автоматичною маршрутизацією та `gateway.nodes.browser.node`, щоб закріпити конкретний вузол, якщо під’єднано кілька вузлів.
|
||||
|
||||
Безпека + віддалене налаштування: [Інструмент браузера](/uk/tools/browser), [Віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [Безпека](/uk/gateway/security)
|
||||
Безпека й віддалене налаштування: [інструмент Browser](/uk/tools/browser), [віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [безпека](/uk/gateway/security)
|
||||
|
||||
## Пов’язано
|
||||
## Пов’язане
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Браузер](/uk/tools/browser)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Browser](/uk/tools/browser)
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібна швидка діагностика стану каналу + нещодавніх одержувачів сесії
|
||||
- Вам потрібен придатний для вставлення статус “all” для налагодження
|
||||
summary: Довідка CLI для `openclaw status` (діагностика, перевірки, знімки використання)
|
||||
- Вам потрібна швидка діагностика стану каналу + одержувачі нещодавніх сеансів
|
||||
- Вам потрібен придатний для вставлення статус «all» для налагодження
|
||||
summary: Довідник CLI для `openclaw status` (діагностика, проби, знімки використання)
|
||||
title: Стан
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:16:04Z"
|
||||
generated_at: "2026-04-25T00:01:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 369de48e283766ec23ef87f79df39893957101954c4a351e46ef24104d78ec1d
|
||||
source_hash: ef182b95eabdb2c24d5d011ed3c3291308373620b893750d6d27470bd88ca3dc
|
||||
source_path: cli/status.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw status`
|
||||
|
||||
Діагностика для каналів + сесій.
|
||||
Діагностика для каналів + сеансів.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -26,23 +26,23 @@ openclaw status --usage
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--deep` запускає живі перевірки (WhatsApp Web + Telegram + Discord + Slack + Signal).
|
||||
- `--usage` виводить нормалізовані вікна використання провайдера як `X% left`.
|
||||
- Вивід стану сесії тепер розділяє `Runtime:` і `Runner:`. `Runtime` — це шлях виконання та стан пісочниці (`direct`, `docker/*`), а `Runner` повідомляє, чи використовує сесія вбудований Pi, провайдера на основі CLI або бекенд harness ACP, наприклад `codex (acp/acpx)`.
|
||||
- Необроблені поля `usage_percent` / `usagePercent` у MiniMax означають залишок квоти, тому OpenClaw інвертує їх перед показом; поля на основі підрахунку мають пріоритет, якщо присутні. Відповіді `model_remains` надають перевагу запису chat-model, за потреби виводять мітку вікна з часових позначок і включають назву моделі в мітку плану.
|
||||
- Коли поточний знімок сесії містить мало даних, `/status` може доповнити лічильники токенів і кешу з найновішого журналу використання transcript. Наявні ненульові живі значення все одно мають пріоритет над резервними значеннями з transcript.
|
||||
- Резервний варіант через transcript також може відновити мітку активної моделі runtime, якщо в живому записі сесії її немає. Якщо ця модель transcript відрізняється від вибраної моделі, status визначає контекстне вікно за відновленою моделлю runtime, а не за вибраною.
|
||||
- Для обліку розміру prompt резервний варіант через transcript надає перевагу більшому загальному значенню, орієнтованому на prompt, коли метадані сесії відсутні або менші, щоб сесії custom-provider не зводилися до показу `0` токенів.
|
||||
- Вивід включає сховища сесій для кожного агента, коли налаштовано кілька агентів.
|
||||
- Огляд включає стан встановлення/виконання сервісу хоста Gateway + Node, коли він доступний.
|
||||
- Огляд включає канал оновлення + git SHA (для вихідних checkout).
|
||||
- Інформація про оновлення відображається в Огляді; якщо оновлення доступне, status виводить підказку виконати `openclaw update` (див. [Оновлення](/uk/install/updating)).
|
||||
- `--deep` запускає живі проби (WhatsApp Web + Telegram + Discord + Slack + Signal).
|
||||
- `--usage` виводить нормалізовані вікна використання провайдера у форматі `X% left`.
|
||||
- Вивід стану сеансу розділяє `Execution:` і `Runtime:`. `Execution` — це шлях sandbox (`direct`, `docker/*`), тоді як `Runtime` повідомляє, чи використовує сеанс `OpenClaw Pi Default`, `OpenAI Codex`, бекенд CLI або бекенд ACP, такий як `codex (acp/acpx)`.
|
||||
- Сирі поля MiniMax `usage_percent` / `usagePercent` означають залишок квоти, тому OpenClaw інвертує їх перед показом; поля на основі підрахунку мають пріоритет, якщо вони присутні. Відповіді `model_remains` надають перевагу запису chat-model, за потреби виводять мітку вікна з часових позначок і включають назву моделі до мітки плану.
|
||||
- Коли поточний знімок сеансу є неповним, `/status` може підставити назад лічильники токенів і кешу з найновішого журналу використання транскрипту. Наявні ненульові живі значення все одно мають пріоритет над резервними значеннями з транскрипту.
|
||||
- Резервні дані з транскрипту також можуть відновити мітку активної моделі runtime, якщо в живому записі сеансу її немає. Якщо ця модель транскрипту відрізняється від вибраної моделі, status визначає контекстне вікно за відновленою моделлю runtime, а не за вибраною.
|
||||
- Для обліку розміру prompt резервні дані з транскрипту надають перевагу більшому загальному значенню, орієнтованому на prompt, коли метадані сеансу відсутні або менші, тому сеанси custom-provider не зводяться до показу `0` токенів.
|
||||
- Вивід включає сховища сеансів для кожного агента, якщо налаштовано кілька агентів.
|
||||
- Огляд включає статус встановлення/роботи служби хоста Gateway + Node, якщо доступно.
|
||||
- Огляд включає канал оновлень + git SHA (для checkout із вихідного коду).
|
||||
- Інформація про оновлення відображається в розділі Overview; якщо оновлення доступне, status виводить підказку виконати `openclaw update` (див. [Оновлення](/uk/install/updating)).
|
||||
- Поверхні стану лише для читання (`status`, `status --json`, `status --all`) за можливості визначають підтримувані SecretRef для цільових шляхів конфігурації.
|
||||
- Якщо підтримуваний SecretRef каналу налаштовано, але він недоступний у поточному шляху команди, status залишається в режимі лише для читання та повідомляє про деградований вивід замість аварійного завершення. Зрозумілий для людини вивід показує попередження на кшталт “configured token unavailable in this command path”, а JSON-вивід містить `secretDiagnostics`.
|
||||
- Коли локальне для команди визначення SecretRef успішне, status надає перевагу визначеному знімку та прибирає тимчасові маркери каналу “secret unavailable” з фінального виводу.
|
||||
- `status --all` включає рядок огляду Secrets і розділ діагностики, який підсумовує діагностику секретів (усічену для читабельності) без зупинки генерації звіту.
|
||||
- Якщо підтримуваний SecretRef каналу налаштовано, але він недоступний у поточному шляху команди, status залишається в режимі лише для читання і повідомляє про деградований вивід замість аварійного завершення. Людинозрозумілий вивід показує попередження на кшталт “configured token unavailable in this command path”, а JSON-вивід містить `secretDiagnostics`.
|
||||
- Коли локальне для команди визначення SecretRef вдається, status надає перевагу визначеному знімку й очищає тимчасові маркери каналу “secret unavailable” з фінального виводу.
|
||||
- `status --all` включає рядок огляду Secrets і розділ діагностики, який підсумовує діагностику секретів (усічену для читабельності), не зупиняючи генерацію звіту.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Doctor](/uk/gateway/doctor)
|
||||
|
||||
@ -1,62 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен довідник із налаштування моделей для кожного постачальника окремо
|
||||
- Вам потрібні приклади конфігурацій або команд онбордингу CLI для постачальників моделей
|
||||
summary: Огляд постачальника моделей із прикладами конфігурацій + потоками CLI
|
||||
- Ви хочете приклади конфігурацій або команд онбордингу CLI для постачальників моделей
|
||||
summary: Огляд постачальників моделей із прикладами конфігурацій + потоками CLI
|
||||
title: Постачальники моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T15:13:05Z"
|
||||
generated_at: "2026-04-25T00:01:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204
|
||||
source_hash: 1c02aff44b00748bdcb5e4dc02c1725ae4c5d4b9fe3a9da523053a7e95a03f16
|
||||
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`).
|
||||
- Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`).
|
||||
- `agents.defaults.models` працює як список дозволених значень, якщо його задано.
|
||||
- Допоміжні CLI-команди: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- `models.providers.*.models[].contextWindow` — це власні метадані моделі; `contextTokens` — це фактичне обмеження середовища виконання.
|
||||
- Правила резервного перемикання, перевірки cooldown і збереження перевизначення сесії: [Перемикання моделей при збої](/uk/concepts/model-failover).
|
||||
- Маршрути сімейства OpenAI залежать від префікса: `openai/<model>` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/<model>` використовує OAuth Codex у PI, а `openai/<model>` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний app-server harness Codex. Дивіться [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness).
|
||||
- Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/<model>` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/<model>`.
|
||||
- GPT-5.5 наразі доступна через маршрути підписки/OAuth: `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі, доступні через API, наприклад `openai/gpt-5.4`, для конфігурацій `OPENAI_API_KEY`.
|
||||
- `models.providers.*.models[].contextWindow` — це вбудовані метадані моделі; `contextTokens` — це фактичне обмеження під час виконання.
|
||||
- Правила резервного перемикання, cooldown-перевірки та збереження перевизначень сеансу див. у [Model failover](/uk/concepts/model-failover).
|
||||
- Маршрути сімейства OpenAI залежать від префікса: `openai/<model>` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/<model>` використовує Codex OAuth у PI, а `openai/<model>` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness сервера застосунку Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness).
|
||||
- Автоматичне ввімкнення Plugin дотримується тієї ж межі: `openai-codex/<model>` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/<model>`.
|
||||
- CLI-середовища виконання використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний бекенд CLI.
|
||||
Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо.
|
||||
- GPT-5.5 наразі доступна через маршрути підписки/OAuth:
|
||||
`openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness сервера застосунку Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі з доступом через API, наприклад `openai/gpt-5.4`, для налаштувань `OPENAI_API_KEY`.
|
||||
|
||||
## Поведінка постачальників, що належить Plugin
|
||||
## Поведінка постачальника, що належить Plugin
|
||||
|
||||
Більшість логіки, специфічної для постачальника, живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugin відповідають за онбординг, каталоги моделей, зіставлення auth env var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію збоїв для резервного перемикання, оновлення OAuth, звітність про використання, профілі thinking/reasoning та інше.
|
||||
Більшість специфічної для постачальника логіки живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugins відповідають за онбординг, каталоги моделей, зіставлення auth env-var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо.
|
||||
|
||||
Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення.
|
||||
Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня розширення.
|
||||
|
||||
<Note>
|
||||
Середовище виконання постачальника `capabilities` — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо).
|
||||
`capabilities` середовища виконання постачальника — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [public capability model](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий inference, мовлення тощо).
|
||||
</Note>
|
||||
|
||||
## Ротація API-ключів
|
||||
|
||||
- Підтримує загальну ротацію ключів постачальника для вибраних постачальників.
|
||||
- Підтримує загальну ротацію постачальників для вибраних постачальників.
|
||||
- Налаштуйте кілька ключів через:
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (одне live-перевизначення, найвищий пріоритет)
|
||||
- `<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
|
||||
- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень.
|
||||
- Запити повторюються з наступним ключем лише у відповідь на повідомлення про обмеження швидкості (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
|
||||
concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
|
||||
`workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
|
||||
- Помилки, не пов’язані з лімітом запитів, завершуються негайно; ротація ключів не виконується.
|
||||
- Коли всі можливі ключі завершуються невдачею, повертається остання помилка з фінальної спроби.
|
||||
- Помилки, не пов’язані з обмеженням швидкості, одразу завершуються з помилкою; ротація ключів не виконується.
|
||||
- Якщо всі можливі ключі завершуються помилкою, повертається фінальна помилка з останньої спроби.
|
||||
|
||||
## Вбудовані постачальники (каталог pi-ai)
|
||||
|
||||
OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна**
|
||||
конфігурація `models.providers`; просто задайте auth і виберіть модель.
|
||||
OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не**
|
||||
потребують конфігурації `models.providers`; достатньо налаштувати auth і вибрати модель.
|
||||
|
||||
### OpenAI
|
||||
|
||||
@ -64,18 +67,18 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
- Auth: `OPENAI_API_KEY`
|
||||
- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
|
||||
- Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini`
|
||||
- Пряма підтримка GPT-5.5 через API тут готова на майбутнє, щойно OpenAI відкриє GPT-5.5 в API
|
||||
- Пряма підтримка API для GPT-5.5 тут підготовлена на майбутнє, щойно OpenAI відкриє GPT-5.5 в API
|
||||
- CLI: `openclaw onboard --auth-choice openai-api-key`
|
||||
- Типовий transport — `auto` (спочатку WebSocket, потім SSE як резерв)
|
||||
- Типовий transport — `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Розігрів OpenAI Responses WebSocket типово ввімкнений через `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` напряму зіставляють запити `openai/*` Responses із `service_tier=priority` на `api.openai.com`
|
||||
- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast`
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі
|
||||
- Нативні маршрути OpenAI також зберігають `store` для Responses, підказки кешу prompt і формування payload для сумісності з reasoning OpenAI; проксі-маршрути цього не роблять
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не показує
|
||||
- Нативні маршрути OpenAI також зберігають Responses `store`, підказки кешу prompt і формування payload для сумісності reasoning OpenAI; проксі-маршрути цього не роблять
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -90,9 +93,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: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно.
|
||||
- Прямі публічні запити 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
|
||||
{
|
||||
@ -105,19 +108,19 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
- Постачальник: `openai-codex`
|
||||
- Auth: OAuth (ChatGPT)
|
||||
- Посилання на модель PI: `openai-codex/gpt-5.5`
|
||||
- Посилання нативного harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"`
|
||||
- Посилання на нативний harness сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"`
|
||||
- Застарілі посилання на моделі: `codex/gpt-*`
|
||||
- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише середовищем виконання Codex harness або застарілими посиланнями `codex/*`.
|
||||
- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin сервера застосунку Codex вибирається лише через середовище виконання harness Codex або застарілі посилання `codex/*`.
|
||||
- CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex`
|
||||
- Типовий transport — `auto` (спочатку WebSocket, потім SSE як резерв)
|
||||
- Типовий transport — `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- `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.5` зберігає нативний `contextWindow = 1000000` і типове обмеження середовища виконання `contextTokens = 272000`; перевизначте обмеження середовища через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/потоків роботи на кшталт OpenClaw.
|
||||
- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і типове runtime-значення `contextTokens = 272000`; перевизначте runtime-обмеження через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw.
|
||||
- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не ввімкне GPT-5.5 у публічному API.
|
||||
|
||||
```json5
|
||||
@ -138,7 +141,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
}
|
||||
```
|
||||
|
||||
### Інші розміщені варіанти в стилі підписки
|
||||
### Інші хостовані варіанти у стилі підписки
|
||||
|
||||
- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan
|
||||
- [MiniMax](/uk/providers/minimax): доступ до MiniMax Coding Plan через OAuth або API-ключ
|
||||
@ -147,8 +150,8 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
### OpenCode
|
||||
|
||||
- Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
|
||||
- Постачальник середовища Zen: `opencode`
|
||||
- Постачальник середовища Go: `opencode-go`
|
||||
- Постачальник середовища виконання Zen: `opencode`
|
||||
- Постачальник середовища виконання 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`
|
||||
|
||||
@ -162,19 +165,19 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
|
||||
- Постачальник: `google`
|
||||
- Auth: `GEMINI_API_KEY`
|
||||
- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
|
||||
- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне live-перевизначення)
|
||||
- Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
|
||||
- Сумісність: застаріла конфігурація 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`
|
||||
- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth
|
||||
- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте неважливий обліковий запис, якщо вирішите продовжити.
|
||||
- Auth: Vertex використовує gcloud ADC; Gemini CLI — свій потік OAuth
|
||||
- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити.
|
||||
- OAuth Gemini CLI постачається як частина вбудованого Plugin `google`.
|
||||
- Спочатку встановіть Gemini CLI:
|
||||
- `brew install gemini-cli`
|
||||
@ -182,9 +185,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
- Увімкнення: `openclaw plugins enable google`
|
||||
- Вхід: `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- Типова модель: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- Примітка: ви **не** вставляєте client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на хості Gateway.
|
||||
- Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway.
|
||||
- Відповіді JSON Gemini CLI аналізуються з `response`; використання береться з `stats` як резерв, а `stats.cached` нормалізується до OpenClaw `cacheRead`.
|
||||
- Примітка: вам **не потрібно** вставляти client id або secret в `openclaw.json`. Потік входу CLI зберігає токени в auth-профілях на хості gateway.
|
||||
- Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway.
|
||||
- JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться зі `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`.
|
||||
|
||||
### Z.AI (GLM)
|
||||
|
||||
@ -192,7 +195,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
- Auth: `ZAI_API_KEY`
|
||||
- Приклад моделі: `zai/glm-5.1`
|
||||
- CLI: `openclaw onboard --auth-choice zai-api-key`
|
||||
- Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*`
|
||||
- Аліаси: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*`
|
||||
- `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню
|
||||
|
||||
### Vercel AI Gateway
|
||||
@ -209,71 +212,72 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
|
||||
- Auth: `KILOCODE_API_KEY`
|
||||
- Приклад моделі: `kilocode/kilo/auto`
|
||||
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
|
||||
- Базова URL-адреса: `https://api.kilo.ai/api/gateway/`
|
||||
- Базовий URL: `https://api.kilo.ai/api/gateway/`
|
||||
- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через
|
||||
`https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання.
|
||||
- Точна маршрутизація на боці джерела для `kilocode/kilo/auto` належить Kilo Gateway,
|
||||
`https://api.kilo.ai/api/gateway/models` може додатково розширити каталог
|
||||
середовища виконання.
|
||||
- Точна маршрутизація вгору за потоком для `kilocode/kilo/auto` належить Kilo Gateway,
|
||||
а не жорстко закодована в OpenClaw.
|
||||
|
||||
Деталі налаштування дивіться в [/providers/kilocode](/uk/providers/kilocode).
|
||||
Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode).
|
||||
|
||||
### Інші вбудовані Plugin постачальників
|
||||
|
||||
| Постачальник | Id | Auth env | Приклад моделі |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
|
||||
| Постачальник | Id | Auth env | Приклад моделі |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
|
||||
| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` |
|
||||
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` |
|
||||
| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` |
|
||||
| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` |
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
|
||||
| Venice | `venice` | `VENICE_API_KEY` | — |
|
||||
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` |
|
||||
| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` |
|
||||
| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` |
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
|
||||
| Venice | `venice` | `VENICE_API_KEY` | — |
|
||||
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
|
||||
Варто знати такі особливості:
|
||||
|
||||
- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-шлях у стилі OpenAI-compatible, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` для Responses, підказки кешу prompt, сумісність reasoning OpenAI). Посилання, що використовують Gemini як бекенд, зберігають лише очищення thought-signature для проксі-Gemini.
|
||||
- **Kilo Gateway** для посилань із Gemini як бекендом дотримується того самого шляху очищення проксі-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning.
|
||||
- **MiniMax** під час онбордингу через API-ключ записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки цю конфігурацію не буде матеріалізовано.
|
||||
- **xAI** використовує шлях xAI Responses. `/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`.
|
||||
- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базова URL-адреса у форматі OpenAI-compatible — `https://api.cerebras.ai/v1`.
|
||||
- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-подібний OpenAI-сумісний шлях, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, Responses `store`, підказки кешу prompt, сумісність reasoning OpenAI). Посилання з бекендом Gemini зберігають лише санітизацію thought-signature для проксі-Gemini.
|
||||
- **Kilo Gateway** для посилань із бекендом Gemini дотримується того самого шляху санітизації проксі-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning.
|
||||
- **MiniMax** онбординг через API-ключ записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки ця конфігурація не буде матеріалізована.
|
||||
- **xAI** використовує шлях xAI Responses. `/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`.
|
||||
- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний базовий URL — `https://api.cerebras.ai/v1`.
|
||||
|
||||
## Постачальники через `models.providers` (custom/base URL)
|
||||
## Постачальники через `models.providers` (власний/base URL)
|
||||
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додавати **власних** постачальників або
|
||||
проксі, сумісні з OpenAI/Anthropic.
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або
|
||||
OpenAI/Anthropic‑сумісні проксі.
|
||||
|
||||
Багато з наведених нижче вбудованих Plugin постачальників уже публікують типовий каталог.
|
||||
Використовуйте явні записи `models.providers.<id>` лише тоді, коли хочете перевизначити
|
||||
типову базову URL-адресу, заголовки або список моделей.
|
||||
типовий base URL, заголовки або список моделей.
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
|
||||
Moonshot постачається як вбудований Plugin постачальника. Використовуйте вбудованого постачальника
|
||||
типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли
|
||||
потрібно перевизначити базову URL-адресу або метадані моделі:
|
||||
Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте
|
||||
вбудованого постачальника, а явний запис `models.providers.moonshot` додавайте лише тоді, коли
|
||||
потрібно перевизначити base URL або метадані моделі:
|
||||
|
||||
- Постачальник: `moonshot`
|
||||
- Auth: `MOONSHOT_API_KEY`
|
||||
- Приклад моделі: `moonshot/kimi-k2.6`
|
||||
- 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"
|
||||
|
||||
@ -306,7 +310,7 @@ Moonshot постачається як вбудований Plugin постач
|
||||
|
||||
### Kimi Coding
|
||||
|
||||
Kimi Coding використовує Anthropic-compatible endpoint від Moonshot AI:
|
||||
Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI:
|
||||
|
||||
- Постачальник: `kimi`
|
||||
- Auth: `KIMI_API_KEY`
|
||||
@ -321,7 +325,7 @@ Kimi Coding використовує Anthropic-compatible endpoint від Moonsh
|
||||
}
|
||||
```
|
||||
|
||||
Застарілий `kimi/k2p5` і далі приймається як сумісний ідентифікатор моделі.
|
||||
Застарілий `kimi/k2p5` як і раніше приймається як id моделі для сумісності.
|
||||
|
||||
### Volcano Engine (Doubao)
|
||||
|
||||
@ -340,13 +344,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
}
|
||||
```
|
||||
|
||||
Під час онбордингу типовою є поверхня coding, але загальний каталог `volcengine/*`
|
||||
Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*`
|
||||
реєструється одночасно.
|
||||
|
||||
У засобах вибору моделі для онбордингу/налаштування варіант auth для Volcengine надає перевагу рядкам
|
||||
`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено,
|
||||
OpenClaw повертається до нефільтрованого каталогу замість показу порожнього
|
||||
засобу вибору, обмеженого постачальником.
|
||||
У засобах вибору моделей onboarding/configure варіант auth для Volcengine надає перевагу рядкам
|
||||
`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw повертається до нефільтрованого каталогу, а не показує порожній
|
||||
засіб вибору в межах постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -381,13 +385,13 @@ BytePlus ARK надає міжнародним користувачам дост
|
||||
}
|
||||
```
|
||||
|
||||
Під час онбордингу типовою є поверхня coding, але загальний каталог `byteplus/*`
|
||||
Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*`
|
||||
реєструється одночасно.
|
||||
|
||||
У засобах вибору моделі для онбордингу/налаштування варіант auth для BytePlus надає перевагу обом
|
||||
рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено,
|
||||
OpenClaw повертається до нефільтрованого каталогу замість показу порожнього
|
||||
засобу вибору, обмеженого постачальником.
|
||||
У засобах вибору моделей onboarding/configure варіант auth для BytePlus надає перевагу рядкам
|
||||
`byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw повертається до нефільтрованого каталогу, а не показує порожній
|
||||
засіб вибору в межах постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -405,7 +409,7 @@ OpenClaw повертається до нефільтрованого катал
|
||||
|
||||
### Synthetic
|
||||
|
||||
Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`:
|
||||
Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`:
|
||||
|
||||
- Постачальник: `synthetic`
|
||||
- Auth: `SYNTHETIC_API_KEY`
|
||||
@ -433,26 +437,26 @@ Synthetic надає Anthropic-compatible моделі через постача
|
||||
|
||||
### MiniMax
|
||||
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint:
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує власні кінцеві точки:
|
||||
|
||||
- MiniMax OAuth (Global): `--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`
|
||||
- MiniMax API key (Global): `--auth-choice minimax-global-api`
|
||||
- MiniMax API key (CN): `--auth-choice minimax-cn-api`
|
||||
- Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або
|
||||
`MINIMAX_API_KEY` для `minimax-portal`
|
||||
|
||||
Деталі налаштування, варіанти моделей і фрагменти конфігурації дивіться в [/providers/minimax](/uk/providers/minimax).
|
||||
Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax).
|
||||
|
||||
На Anthropic-compatible streaming-шляху MiniMax OpenClaw типово вимикає thinking,
|
||||
У Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking,
|
||||
якщо ви явно його не задасте, а `/fast on` переписує
|
||||
`MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
|
||||
Розподіл capability, що належить Plugin:
|
||||
Розділення можливостей, що належить Plugin:
|
||||
|
||||
- Типові значення для text/chat залишаються на `minimax/MiniMax-M2.7`
|
||||
- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7`
|
||||
- Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01`
|
||||
- Розуміння зображень — це керований Plugin `MiniMax-VL-01` на обох auth-шляхах MiniMax
|
||||
- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, на обох шляхах auth MiniMax
|
||||
- Вебпошук залишається на id постачальника `minimax`
|
||||
|
||||
### LM Studio
|
||||
@ -461,9 +465,9 @@ LM Studio постачається як вбудований Plugin постач
|
||||
|
||||
- Постачальник: `lmstudio`
|
||||
- Auth: `LM_API_TOKEN`
|
||||
- Типова базова URL-адреса інференсу: `http://localhost:1234/v1`
|
||||
- Типовий базовий URL inference: `http://localhost:1234/v1`
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернутих `http://localhost:1234/api/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -473,16 +477,16 @@ LM Studio постачається як вбудований Plugin постач
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio
|
||||
для виявлення й автозавантаження, а `/v1/chat/completions` — типово для інференсу.
|
||||
Налаштування та усунення несправностей дивіться в [/providers/lmstudio](/uk/providers/lmstudio).
|
||||
OpenClaw використовує нативні для LM Studio `/api/v1/models` і `/api/v1/models/load`
|
||||
для виявлення й автозавантаження, а `/v1/chat/completions` типово — для inference.
|
||||
Деталі налаштування та усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio).
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama постачається як вбудований Plugin постачальника і використовує нативний API Ollama:
|
||||
Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama:
|
||||
|
||||
- Постачальник: `ollama`
|
||||
- Auth: не потрібна (локальний сервер)
|
||||
- Auth: не потрібен (локальний сервер)
|
||||
- Приклад моделі: `ollama/llama3.3`
|
||||
- Встановлення: [https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
@ -499,27 +503,27 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через
|
||||
Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через
|
||||
`OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до
|
||||
`openclaw onboard` і засобу вибору моделі. Дивіться [/providers/ollama](/uk/providers/ollama)
|
||||
для онбордингу, хмарного/локального режиму та власної конфігурації.
|
||||
`openclaw onboard` і засобу вибору моделі. Див. [/providers/ollama](/uk/providers/ollama)
|
||||
щодо онбордингу, хмарного/локального режиму та власної конфігурації.
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM постачається як вбудований Plugin постачальника для локальних/самостійно розміщених
|
||||
серверів, сумісних з OpenAI:
|
||||
vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-сумісних
|
||||
серверів:
|
||||
|
||||
- Постачальник: `vllm`
|
||||
- Auth: необов’язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:8000/v1`
|
||||
- Auth: необов’язковий (залежить від вашого сервера)
|
||||
- Типовий базовий URL: `http://127.0.0.1:8000/v1`
|
||||
|
||||
Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth):
|
||||
Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth):
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернутих `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -529,25 +533,25 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
Деталі дивіться в [/providers/vllm](/uk/providers/vllm).
|
||||
Деталі див. у [/providers/vllm](/uk/providers/vllm).
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang постачається як вбудований Plugin постачальника для швидких самостійно розміщених
|
||||
серверів, сумісних з OpenAI:
|
||||
SGLang постачається як вбудований Plugin постачальника для швидких self-hosted
|
||||
OpenAI-сумісних серверів:
|
||||
|
||||
- Постачальник: `sglang`
|
||||
- Auth: необов’язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:30000/v1`
|
||||
- Auth: необов’язковий (залежить від вашого сервера)
|
||||
- Типовий базовий URL: `http://127.0.0.1:30000/v1`
|
||||
|
||||
Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не
|
||||
Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не
|
||||
вимагає auth):
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернутих `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -557,11 +561,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
|
||||
{
|
||||
@ -596,18 +600,18 @@ export SGLANG_API_KEY="sglang-local"
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для custom постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими.
|
||||
Якщо їх пропущено, OpenClaw типово використовує:
|
||||
- Для власних постачальників `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"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`.
|
||||
- Маршрути у стилі проксі, сумісні з OpenAI, також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без `store` для Responses, без підказок кешу prompt, без формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw.
|
||||
- Якщо `baseUrl` порожній або пропущений, OpenClaw зберігає типову поведінку OpenAI (яка зводиться до `api.openai.com`).
|
||||
- Для безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`.
|
||||
- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі.
|
||||
- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 для непідтримуваних ролей `developer`.
|
||||
- Проксі-подібні OpenAI-сумісні маршрути також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без Responses `store`, без підказок кешу prompt, без формування payload для сумісності reasoning OpenAI та без прихованих заголовків атрибуції OpenClaw.
|
||||
- Якщо `baseUrl` порожній/не заданий, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`).
|
||||
- Для безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`.
|
||||
|
||||
## Приклади CLI
|
||||
|
||||
@ -617,11 +621,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) — конфігурація моделей і псевдоніми
|
||||
- [Models](/uk/concepts/models) — конфігурація моделей і аліаси
|
||||
- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб
|
||||
- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
- [Providers](/uk/providers) — окремі посібники з налаштування постачальників
|
||||
- [Providers](/uk/providers) — інструкції з налаштування для кожного постачальника
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills)
|
||||
- Налаштування маршрутизації між кількома агентами та прив’язок
|
||||
- Налаштування сеансу, доставки повідомлень і поведінки режиму talk
|
||||
summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk
|
||||
- Налаштування типових параметрів агента (моделі, мислення, робочий простір, Heartbeat, медіа, Skills)
|
||||
- Налаштування маршрутизації та прив’язок між кількома агентами
|
||||
- Налаштування сесії, доставки повідомлень і поведінки режиму розмови
|
||||
summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація розмови
|
||||
title: Конфігурація — агенти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T21:43:38Z"
|
||||
generated_at: "2026-04-25T00:01:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6c74f7d730fa4380acdd2af7b6dd8f3db635d901151826ce8c80993fedd70365
|
||||
source_hash: fe9405429df108dd6a745102e03ad1dea29cf9559ad534bba202c767db047a75
|
||||
source_path: gateway/config-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`,
|
||||
Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`,
|
||||
`messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших
|
||||
ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
@ -32,7 +32,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.repoRoot`
|
||||
|
||||
Необов’язковий корінь репозиторію, який відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору.
|
||||
Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись вгору від робочого простору.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -58,11 +58,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills.
|
||||
- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення.
|
||||
- Установіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills.
|
||||
- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він
|
||||
не об’єднується з типовими значеннями.
|
||||
- Пропустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills.
|
||||
- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення.
|
||||
- Установіть `agents.list[].skills: []`, щоб не було Skills.
|
||||
- Непорожній список `agents.list[].skills` є кінцевим набором для цього агента;
|
||||
він не об’єднується з типовими значеннями.
|
||||
|
||||
### `agents.defaults.skipBootstrap`
|
||||
|
||||
@ -76,9 +76,9 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.contextInjection`
|
||||
|
||||
Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`.
|
||||
Керує тим, коли bootstrap-файли робочого простору впроваджуються в системний запит. Типове значення: `"always"`.
|
||||
|
||||
- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-контексту робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст.
|
||||
- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне впровадження bootstrap-даних робочого простору, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -98,7 +98,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapTotalMaxChars`
|
||||
|
||||
Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`.
|
||||
Максимальна загальна кількість символів, що впроваджуються через всі bootstrap-файли робочого простору. Типове значення: `60000`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -111,9 +111,9 @@ x-i18n:
|
||||
Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано.
|
||||
Типове значення: `"once"`.
|
||||
|
||||
- `"off"`: ніколи не додавати текст попередження до системного запиту.
|
||||
- `"once"`: додавати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано).
|
||||
- `"always"`: додавати попередження під час кожного запуску, якщо є обрізання.
|
||||
- `"off"`: ніколи не впроваджувати текст попередження в системний запит.
|
||||
- `"once"`: впроваджувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано).
|
||||
- `"always"`: впроваджувати попередження при кожному запуску, коли є обрізання.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -121,24 +121,24 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### Карта володіння бюджетом контексту
|
||||
### Мапа відповідальності за бюджет контексту
|
||||
|
||||
OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони
|
||||
навмисно розділені між підсистемами, а не проходять через один універсальний
|
||||
параметр.
|
||||
навмисно розділені між підсистемами, а не зведені до одного загального
|
||||
параметра.
|
||||
|
||||
- `agents.defaults.bootstrapMaxChars` /
|
||||
`agents.defaults.bootstrapTotalMaxChars`:
|
||||
звичайне додавання bootstrap-контексту робочого простору.
|
||||
звичайне впровадження bootstrap-даних робочого простору.
|
||||
- `agents.defaults.startupContext.*`:
|
||||
одноразова стартова преамбула для `/new` і `/reset`, зокрема нещодавні щоденні
|
||||
файли `memory/*.md`.
|
||||
одноразова стартова преамбула для `/new` і `/reset`, включно з нещодавніми
|
||||
щоденними файлами `memory/*.md`.
|
||||
- `skills.limits.*`:
|
||||
компактний список Skills, який додається до системного запиту.
|
||||
компактний список Skills, що впроваджується в системний запит.
|
||||
- `agents.defaults.contextLimits.*`:
|
||||
обмежені витяги середовища виконання та додані блоки, якими керує runtime.
|
||||
обмежені фрагменти середовища виконання та впроваджені блоки, що належать середовищу виконання.
|
||||
- `memory.qmd.limits.*`:
|
||||
індексований фрагмент пошуку пам’яті та параметри додавання.
|
||||
розмір фрагментів індексованого пошуку в пам’яті та їх впровадження.
|
||||
|
||||
Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли
|
||||
одному агенту потрібен інший бюджет:
|
||||
@ -148,7 +148,7 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
|
||||
#### `agents.defaults.startupContext`
|
||||
|
||||
Керує стартовою преамбулою першого ходу, яка додається під час порожніх запусків `/new` і `/reset`.
|
||||
Керує стартовою преамбулою першого ходу, що впроваджується під час простих запусків `/new` і `/reset`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -186,16 +186,16 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
}
|
||||
```
|
||||
|
||||
- `memoryGetMaxChars`: типове обмеження розміру витягу `memory_get` перед додаванням
|
||||
- `memoryGetMaxChars`: типове обмеження фрагмента `memory_get` перед додаванням
|
||||
метаданих обрізання та повідомлення про продовження.
|
||||
- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines`
|
||||
не вказано.
|
||||
- `toolResultMaxChars`: поточне обмеження розміру результату інструмента, що використовується для збережених результатів і відновлення після переповнення.
|
||||
- `postCompactionMaxChars`: обмеження розміру витягу AGENTS.md, що використовується під час додавання оновлення після Compaction.
|
||||
- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines`
|
||||
пропущено.
|
||||
- `toolResultMaxChars`: обмеження результату інструмента в реальному часі, що використовується для збережених результатів і відновлення після переповнення.
|
||||
- `postCompactionMaxChars`: обмеження фрагмента AGENTS.md, що використовується під час впровадження оновлення після Compaction.
|
||||
|
||||
#### `agents.list[].contextLimits`
|
||||
|
||||
Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються
|
||||
Перевизначення на рівні агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються
|
||||
з `agents.defaults.contextLimits`.
|
||||
|
||||
```json5
|
||||
@ -222,7 +222,7 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
|
||||
#### `skills.limits.maxSkillsPromptChars`
|
||||
|
||||
Глобальне обмеження для компактного списку Skills, який додається до системного запиту. Це
|
||||
Глобальне обмеження для компактного списку Skills, що впроваджується в системний запит. Це
|
||||
не впливає на читання файлів `SKILL.md` на вимогу.
|
||||
|
||||
```json5
|
||||
@ -237,7 +237,7 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
|
||||
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Перевизначення бюджету запиту Skills для конкретного агента.
|
||||
Перевизначення бюджету запиту Skills на рівні агента.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,11 +256,11 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
|
||||
### `agents.defaults.imageMaxDimensionPx`
|
||||
|
||||
Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень стенограми/інструментів перед викликами провайдера.
|
||||
Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера.
|
||||
Типове значення: `1200`.
|
||||
|
||||
Менші значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту в сценаріях із великою кількістю знімків екрана.
|
||||
Більші значення зберігають більше візуальних деталей.
|
||||
Нижчі значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю скриншотів.
|
||||
Вищі значення зберігають більше візуальних деталей.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -320,7 +320,7 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
},
|
||||
params: { cacheRetention: "long" }, // глобальні типові параметри провайдера
|
||||
embeddedHarness: {
|
||||
runtime: "auto", // auto | pi | зареєстрований ідентифікатор harness, наприклад codex
|
||||
runtime: "pi", // pi | auto | ідентифікатор зареєстрованого harness, наприклад codex
|
||||
fallback: "pi", // pi | none
|
||||
},
|
||||
pdfMaxBytesMb: 10,
|
||||
@ -339,50 +339,50 @@ OpenClaw має кілька високонавантажених бюджеті
|
||||
|
||||
- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Форма рядка задає лише основну модель.
|
||||
- Форма об’єкта задає основну модель плюс впорядкований список моделей для аварійного перемикання.
|
||||
- Форма об’єкта задає основну модель і впорядкований список резервних моделей для перемикання при відмові.
|
||||
- `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Використовується шляхом інструмента `image` як конфігурація його vision-моделі.
|
||||
- Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення.
|
||||
- Використовується шляхом інструмента `image` як його конфігурація vision-моделі.
|
||||
- Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення.
|
||||
- `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення.
|
||||
- Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images.
|
||||
- Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`).
|
||||
- Якщо не вказано, `image_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів.
|
||||
- Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`).
|
||||
- Якщо параметр пропущено, `image_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів.
|
||||
- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`.
|
||||
- Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`.
|
||||
- Якщо не вказано, `music_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів.
|
||||
- Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ.
|
||||
- Якщо параметр пропущено, `music_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів.
|
||||
- Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера/API-ключ.
|
||||
- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`.
|
||||
- Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`.
|
||||
- Якщо не вказано, `video_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів.
|
||||
- Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ.
|
||||
- Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`.
|
||||
- Якщо параметр пропущено, `video_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів.
|
||||
- Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера/API-ключ.
|
||||
- Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`.
|
||||
- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
|
||||
- Використовується інструментом `pdf` для маршрутизації моделі.
|
||||
- Якщо не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сеансу/типову модель.
|
||||
- Якщо параметр пропущено, інструмент PDF використовує `imageModel`, а потім — визначену модель сесії/типову модель.
|
||||
- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику.
|
||||
- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується режимом резервного витягування в інструменті `pdf`.
|
||||
- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`.
|
||||
- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`.
|
||||
- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спершу пробує псевдонім, потім — однозначний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тож краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера.
|
||||
- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`).
|
||||
- Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених значень, якщо не передати `--replace`.
|
||||
- Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих нерелевантних провайдерів.
|
||||
- Для прямих моделей OpenAI Responses компактування на стороні сервера вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Compaction на стороні сервера OpenAI](/uk/providers/openai#server-side-compaction-responses-api).
|
||||
- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного витягування в інструменті `pdf`.
|
||||
- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`.
|
||||
- `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`.
|
||||
- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера.
|
||||
- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`).
|
||||
- Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених, якщо не передати `--replace`.
|
||||
- Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих інших, не пов’язаних провайдерів.
|
||||
- Для прямих моделей OpenAI Responses автоматично вмикається серверний Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити впровадження `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api).
|
||||
- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`).
|
||||
- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключами. Докладніше див. у [Кешування запитів](/uk/reference/prompt-caching).
|
||||
- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Автоматичне резервне перемикання на PI типово дорівнює `"pi"` лише в режимі `auto`. Явні середовища виконання Plugin, такі як `codex`, типово мають `"none"`, якщо ви не задасте `fallback: "pi"`. Нові конфігурації harness Codex мають зберігати посилання на моделі в канонічному вигляді `openai/*` і вибирати harness тут, а не використовувати застарілі посилання на моделі `codex/*`.
|
||||
- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних варіантів.
|
||||
- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізується). Типове значення: 4.
|
||||
- Порядок об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає значення за ключами. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching).
|
||||
- `embeddedHarness`: типова політика низькорівневого середовища виконання для вбудованого агента. Якщо `runtime` пропущено, типовим є OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово застосовувати вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness у Plugin перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси провайдера runtime.
|
||||
- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних моделей.
|
||||
- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно виконується послідовно). Типове значення: 4.
|
||||
|
||||
### `agents.defaults.embeddedHarness`
|
||||
|
||||
`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента.
|
||||
У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`.
|
||||
Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований
|
||||
harness app-server Codex.
|
||||
`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента.
|
||||
У більшості розгортань слід залишити типовий runtime OpenClaw Pi.
|
||||
Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований
|
||||
harness app-server для Codex.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -398,14 +398,14 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого Plugin harness. Вбудований Plugin Codex реєструє `codex`.
|
||||
- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений fallback типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не бере запуск на себе. У режимі явного Plugin runtime, наприклад `runtime: "codex"`, пропущений fallback типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість мовчазного використання PI. Перевизначення runtime не успадковують fallback із ширшої області; задайте `fallback: "pi"` разом із явним runtime, коли вам свідомо потрібен цей сумісний резервний варіант. Збої вибраного Plugin harness завжди відображаються безпосередньо.
|
||||
- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу.
|
||||
- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності також можна явно задати `embeddedHarness.fallback: "none"`; це типове значення для явних Plugin runtime.
|
||||
- Вибір harness фіксується для кожного ідентифікатора сеансу після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сеанси, а не на наявну стенограму. Застарілі сеанси з історією стенограми, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує не-PI ідентифікатори harness, такі як `codex`, поруч із `Fast`.
|
||||
- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS усе ще використовують свої параметри провайдера/моделі.
|
||||
- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness у Plugin. Вбудований Plugin Codex реєструє `codex`.
|
||||
- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене значення `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й надалі використовувати PI, коли жоден harness у Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущене значення `fallback` типово дорівнює `"none"`, щоб відсутність harness спричиняла помилку, а не тихе використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` поруч із явним `runtime`, якщо вам навмисно потрібна така сумісність. Помилки вибраного harness Plugin завжди показуються безпосередньо.
|
||||
- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу.
|
||||
- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності ви також можете явно встановити `embeddedHarness.fallback: "none"`; це типове значення для явних runtime Plugin.
|
||||
- Вибір harness закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, а не на наявну транскрипцію. Застарілі сесії з історією транскрипції, але без зафіксованого закріплення, вважаються закріпленими за PI. `/status` показує ідентифікатори harness, відмінні від PI, наприклад `codex`, поруч із `Fast`.
|
||||
- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують власні налаштування провайдера/моделі.
|
||||
|
||||
**Вбудовані скорочення-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
|
||||
**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
|
||||
|
||||
| Псевдонім | Модель |
|
||||
| ------------------- | -------------------------------------------------- |
|
||||
@ -420,13 +420,13 @@ harness app-server Codex.
|
||||
|
||||
Ваші налаштовані псевдоніми завжди мають пріоритет над типовими.
|
||||
|
||||
Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/<model>"].params.thinking`.
|
||||
Для моделей Z.AI типово вмикається `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/<model>"].params.tool_stream` у `false`, щоб вимкнути це.
|
||||
Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо явний рівень thinking не задано.
|
||||
Для моделей Z.AI GLM-4.x режим мислення автоматично вмикається, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/<model>"].params.thinking`.
|
||||
Для моделей Z.AI типово ввімкнено `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/<model>"].params.tool_stream` у `false`, щоб вимкнути це.
|
||||
Для моделей Anthropic Claude 4.6 типовим є режим мислення `adaptive`, якщо явний рівень мислення не задано.
|
||||
|
||||
### `agents.defaults.cliBackends`
|
||||
|
||||
Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні.
|
||||
Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери відмовляють.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -454,13 +454,13 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені.
|
||||
- Сеанси підтримуються, коли задано `sessionArg`.
|
||||
- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів.
|
||||
- CLI-бекенди насамперед орієнтовані на текст; інструменти завжди вимкнені.
|
||||
- Сесії підтримуються, коли задано `sessionArg`.
|
||||
- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів.
|
||||
|
||||
### `agents.defaults.systemPromptOverride`
|
||||
|
||||
Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами.
|
||||
Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -474,7 +474,7 @@ harness app-server Codex.
|
||||
|
||||
### `agents.defaults.promptOverlays`
|
||||
|
||||
Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії.
|
||||
Незалежні від провайдера накладки запитів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -490,9 +490,9 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії.
|
||||
- `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії.
|
||||
- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим.
|
||||
- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано.
|
||||
- Застаріле `plugins.entries.openai.config.personality` усе ще читається, якщо цей спільний параметр не задано.
|
||||
|
||||
### `agents.defaults.heartbeat`
|
||||
|
||||
@ -506,9 +506,9 @@ harness app-server Codex.
|
||||
every: "30m", // 0m вимикає
|
||||
model: "openai/gpt-5.4-mini",
|
||||
includeReasoning: false,
|
||||
includeSystemPromptSection: true, // типово: true; false не додає розділ Heartbeat до системного запиту
|
||||
includeSystemPromptSection: true, // типово: true; false пропускає секцію Heartbeat у системному запиті
|
||||
lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору
|
||||
isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмови)
|
||||
isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмови)
|
||||
session: "main",
|
||||
to: "+15555550123",
|
||||
directPolicy: "allow", // allow (типово) | block
|
||||
@ -523,15 +523,15 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути.
|
||||
- `includeSystemPromptSection`: коли `false`, не додає розділ Heartbeat до системного запиту та пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`.
|
||||
- `suppressToolErrorWarnings`: коли `true`, пригнічує корисні навантаження з попередженнями про помилки інструментів під час запусків heartbeat.
|
||||
- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`.
|
||||
- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та генерує `reason=dm-blocked`.
|
||||
- `lightContext`: коли `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору.
|
||||
- `isolatedSession`: коли `true`, кожен heartbeat запускається в новому сеансі без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів.
|
||||
- Для конкретного агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**.
|
||||
- Heartbeat виконують повноцінні ходи агента — коротші інтервали спалюють більше токенів.
|
||||
- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути.
|
||||
- `includeSystemPromptSection`: якщо `false`, пропускає секцію Heartbeat у системному запиті та не впроваджує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`.
|
||||
- `suppressToolErrorWarnings`: якщо `true`, приглушує вміст попереджень про помилки інструментів під час запусків heartbeat.
|
||||
- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після якого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`.
|
||||
- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` приглушує доставку до прямої цілі та видає `reason=dm-blocked`.
|
||||
- `lightContext`: якщо `true`, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору.
|
||||
- `isolatedSession`: якщо `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Така сама схема ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість одного heartbeat у токенах приблизно зі ~100K до ~2-5K токенів.
|
||||
- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**.
|
||||
- Heartbeat запускає повноцінні ходи агента — коротші інтервали витрачають більше токенів.
|
||||
|
||||
### `agents.defaults.compaction`
|
||||
|
||||
@ -541,14 +541,14 @@ harness app-server Codex.
|
||||
defaults: {
|
||||
compaction: {
|
||||
mode: "safeguard", // default | safeguard
|
||||
provider: "my-provider", // id зареєстрованого Plugin-провайдера compaction (необов’язково)
|
||||
provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково)
|
||||
timeoutSeconds: 900,
|
||||
reserveTokensFloor: 24000,
|
||||
identifierPolicy: "strict", // strict | off | custom
|
||||
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom
|
||||
postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання
|
||||
postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне впровадження
|
||||
model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction
|
||||
notifyUser: true, // надсилати короткі сповіщення, коли compaction починається і завершується (типово: false)
|
||||
notifyUser: true, // надсилати короткі сповіщення користувачу на початку і після завершення compaction (типово: false)
|
||||
memoryFlush: {
|
||||
enabled: true,
|
||||
softThresholdTokens: 6000,
|
||||
@ -562,18 +562,18 @@ harness app-server Codex.
|
||||
```
|
||||
|
||||
- `mode`: `default` або `safeguard` (підсумовування довгої історії частинами). Див. [Compaction](/uk/concepts/compaction).
|
||||
- `provider`: id зареєстрованого Plugin-провайдера compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` провайдера. У разі збою повертається до вбудованого варіанта. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
|
||||
- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки повертається до вбудованого варіанта. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
|
||||
- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`.
|
||||
- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані інструкції щодо збереження непрозорих ідентифікаторів під час підсумовування compaction.
|
||||
- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`.
|
||||
- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які потрібно повторно додати після compaction. Типове значення — `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне додавання. Якщо не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант.
|
||||
- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки compaction мають створюватися на іншій; якщо не задано, compaction використовує основну модель сеансу.
|
||||
- `notifyUser`: коли `true`, надсилає користувачеві короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction відбувався безшумно.
|
||||
- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження тривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання.
|
||||
- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction.
|
||||
- `identifierInstructions`: необов’язковий власний текст інструкцій зі збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`.
|
||||
- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md для повторного впровадження після compaction. Типово: `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне впровадження. Якщо значення не задано або явно встановлено в цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності.
|
||||
- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має лишатися на одній моделі, а підсумки compaction — виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії.
|
||||
- `notifyUser`: якщо `true`, надсилає короткі сповіщення користувачу на початку і після завершення compaction (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction залишався безшумним.
|
||||
- `memoryFlush`: безшумний хід агента перед авто-compaction для збереження довготривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання.
|
||||
|
||||
### `agents.defaults.contextPruning`
|
||||
|
||||
Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску.
|
||||
Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -598,7 +598,7 @@ harness app-server Codex.
|
||||
<Accordion title="Поведінка режиму cache-ttl">
|
||||
|
||||
- `mode: "cache-ttl"` вмикає проходи обрізання.
|
||||
- `ttl` визначає, як часто обрізання можна запускати знову (після останнього торкання кешу).
|
||||
- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу).
|
||||
- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів.
|
||||
|
||||
**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині.
|
||||
@ -607,13 +607,13 @@ harness app-server Codex.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Блоки зображень ніколи не обрізаються й не очищаються.
|
||||
- Блоки зображень ніколи не обрізаються і не очищаються.
|
||||
- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів.
|
||||
- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається.
|
||||
|
||||
</Accordion>
|
||||
|
||||
Докладніше про поведінку див. у [Обрізання сеансу](/uk/concepts/session-pruning).
|
||||
Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning).
|
||||
|
||||
### Блокове потокове передавання
|
||||
|
||||
@ -632,10 +632,10 @@ harness app-server Codex.
|
||||
```
|
||||
|
||||
- Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді.
|
||||
- Перевизначення каналу: `channels.<channel>.blockStreamingCoalesce` (і варіанти для конкретних облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`.
|
||||
- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для конкретного агента: `agents.list[].humanDelay`.
|
||||
- Перевизначення для каналів: `channels.<channel>.blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`.
|
||||
- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`.
|
||||
|
||||
Докладніше про поведінку й розбиття на фрагменти див. у [Потокове передавання](/uk/concepts/streaming).
|
||||
Докладніше про поведінку та розбиття на частини див. у [Потокове передавання](/uk/concepts/streaming).
|
||||
|
||||
### Індикатори набору тексту
|
||||
|
||||
@ -650,16 +650,16 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки.
|
||||
- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`.
|
||||
- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадки.
|
||||
- Перевизначення на рівні сесії: `session.typingMode`, `session.typingIntervalSeconds`.
|
||||
|
||||
Див. [Індикатори набору тексту](/uk/concepts/typing-indicators).
|
||||
Докладніше див. у [Індикатори набору тексту](/uk/concepts/typing-indicators).
|
||||
|
||||
<a id="agentsdefaultssandbox"></a>
|
||||
|
||||
### `agents.defaults.sandbox`
|
||||
|
||||
Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing).
|
||||
Необов’язкова пісочниця для вбудованого агента. Повний посібник див. у [Пісочниця](/uk/gateway/sandboxing).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -754,7 +754,7 @@ harness app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Докладно про sandbox">
|
||||
<Accordion title="Деталі пісочниці">
|
||||
|
||||
**Бекенд:**
|
||||
|
||||
@ -762,16 +762,16 @@ harness app-server Codex.
|
||||
- `ssh`: універсальне віддалене середовище виконання на основі SSH
|
||||
- `openshell`: середовище виконання OpenShell
|
||||
|
||||
Коли вибрано `backend: "openshell"`, налаштування, специфічні для середовища виконання, переміщуються до
|
||||
Коли вибрано `backend: "openshell"`, специфічні для цього runtime налаштування переносяться до
|
||||
`plugins.entries.openshell.config`.
|
||||
|
||||
**Конфігурація SSH-бекенда:**
|
||||
|
||||
- `target`: SSH-ціль у форматі `user@host[:port]`
|
||||
- `command`: команда SSH-клієнта (типово: `ssh`)
|
||||
- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області
|
||||
- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH
|
||||
- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час виконання
|
||||
- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області дії
|
||||
- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються до OpenSSH
|
||||
- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання
|
||||
- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH
|
||||
|
||||
**Пріоритет автентифікації SSH:**
|
||||
@ -779,27 +779,27 @@ harness app-server Codex.
|
||||
- `identityData` має пріоритет над `identityFile`
|
||||
- `certificateData` має пріоритет над `certificateFile`
|
||||
- `knownHostsData` має пріоритет над `knownHostsFile`
|
||||
- Значення `*Data`, що базуються на SecretRef, визначаються з активного знімка середовища виконання секретів до початку сеансу sandbox
|
||||
- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії пісочниці
|
||||
|
||||
**Поведінка SSH-бекенда:**
|
||||
|
||||
- один раз ініціалізує віддалений робочий простір після створення або повторного створення
|
||||
- потім підтримує віддалений робочий простір SSH як канонічний
|
||||
- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH
|
||||
- не синхронізує віддалені зміни назад на хост автоматично
|
||||
- потім зберігає віддалений робочий простір як канонічний
|
||||
- маршрутизує `exec`, файлові інструменти та шляхи медіафайлів через SSH
|
||||
- не синхронізує зміни з віддаленого середовища назад на хост автоматично
|
||||
- не підтримує браузерні контейнери sandbox
|
||||
|
||||
**Доступ до робочого простору:**
|
||||
|
||||
- `none`: робочий простір sandbox у межах області під `~/.openclaw/sandboxes`
|
||||
- `none`: робочий простір sandbox у межах області дії під `~/.openclaw/sandboxes`
|
||||
- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent`
|
||||
- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace`
|
||||
|
||||
**Область:**
|
||||
**Область дії:**
|
||||
|
||||
- `session`: окремий контейнер і робочий простір для кожного сеансу
|
||||
- `agent`: один контейнер і робочий простір на агента (типово)
|
||||
- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами)
|
||||
- `session`: окремий контейнер і робочий простір для кожної сесії
|
||||
- `agent`: один контейнер і робочий простір для кожного агента (типово)
|
||||
- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями)
|
||||
|
||||
**Конфігурація Plugin OpenShell:**
|
||||
|
||||
@ -829,29 +829,29 @@ harness app-server Codex.
|
||||
|
||||
**Режим OpenShell:**
|
||||
|
||||
- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним
|
||||
- `remote`: один раз ініціалізує віддалене середовище, коли створюється sandbox, після чого віддалений робочий простір залишається канонічним
|
||||
- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним
|
||||
- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, а потім зберігає віддалений робочий простір як канонічний
|
||||
|
||||
У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації.
|
||||
Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою синхронізацією mirror керує Plugin.
|
||||
У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації.
|
||||
Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією в режимі mirror.
|
||||
|
||||
**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореневої файлової системи з можливістю запису та користувача root.
|
||||
**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує мережевого виходу, доступного для запису кореня та користувача root.
|
||||
|
||||
**Типово контейнери мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ.
|
||||
`"host"` заблоковано. `"container:<id>"` типово заблоковано, якщо ви явно не задасте
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант).
|
||||
**Для контейнерів типовим є `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ.
|
||||
`"host"` заблоковано. `"container:<id>"` типово заблоковано, якщо ви явно не встановите
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний обхід).
|
||||
|
||||
**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі.
|
||||
**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі.
|
||||
|
||||
**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для конкретного агента об’єднуються.
|
||||
**`docker.binds`** монтує додаткові каталоги хоста; глобальні та прив’язки для окремого агента об’єднуються.
|
||||
|
||||
**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` у `openclaw.json`.
|
||||
Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw генерує URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL).
|
||||
**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC впроваджується в системний запит. Не потребує `browser.enabled` у `openclaw.json`.
|
||||
Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість показу пароля у спільному URL).
|
||||
|
||||
- `allowHostControl: false` (типово) блокує для sandbox-сеансів націлення на браузер хоста.
|
||||
- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна загальна bridge-зв’язність.
|
||||
- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`).
|
||||
- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), замінює `docker.binds` для контейнера браузера.
|
||||
- `allowHostControl: false` (типово) блокує націлювання сеансів sandbox на браузер хоста.
|
||||
- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge`, лише якщо вам явно потрібне глобальне підключення через bridge.
|
||||
- `cdpSourceRange` за потреби обмежує вхід до CDP на межі контейнера діапазоном CIDR (наприклад, `172.21.0.1/32`).
|
||||
- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в браузерний контейнер sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для браузерного контейнера.
|
||||
- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів:
|
||||
- `--remote-debugging-address=127.0.0.1`
|
||||
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
|
||||
@ -871,29 +871,29 @@ harness app-server Codex.
|
||||
- `--metrics-recording-only`
|
||||
- `--disable-extensions` (типово ввімкнено)
|
||||
- `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu`
|
||||
типово ввімкнені й можуть бути вимкнені за допомогою
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо це потрібно для WebGL/3D.
|
||||
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони потрібні
|
||||
вашому робочому процесу.
|
||||
типово ввімкнені й можуть бути вимкнені через
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D.
|
||||
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони
|
||||
потрібні вашому робочому процесу.
|
||||
- `--renderer-process-limit=2` можна змінити через
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; установіть `0`, щоб використовувати
|
||||
типове обмеження процесів Chromium.
|
||||
- а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`.
|
||||
- Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний
|
||||
образ браузера з власним entrypoint.
|
||||
- Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний браузерний образ із власним
|
||||
entrypoint.
|
||||
|
||||
</Accordion>
|
||||
|
||||
Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker.
|
||||
Пісочниця браузера та `sandbox.docker.binds` підтримуються лише для Docker.
|
||||
|
||||
Збірка образів:
|
||||
Зібрати образи:
|
||||
|
||||
```bash
|
||||
scripts/sandbox-setup.sh # основний образ sandbox
|
||||
scripts/sandbox-browser-setup.sh # необов’язковий образ браузера
|
||||
```
|
||||
|
||||
### `agents.list` (перевизначення для конкретного агента)
|
||||
### `agents.list` (перевизначення для окремого агента)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -906,11 +906,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
workspace: "~/.openclaw/workspace",
|
||||
agentDir: "~/.openclaw/agents/main/agent",
|
||||
model: "anthropic/claude-opus-4-6", // або { primary, fallbacks }
|
||||
thinkingDefault: "high", // перевизначення рівня thinking для конкретного агента
|
||||
reasoningDefault: "on", // перевизначення видимості reasoning для конкретного агента
|
||||
fastModeDefault: false, // перевизначення fast mode для конкретного агента
|
||||
thinkingDefault: "high", // перевизначення типового рівня мислення для окремого агента
|
||||
reasoningDefault: "on", // перевизначення типової видимості міркувань для окремого агента
|
||||
fastModeDefault: false, // перевизначення типового швидкого режиму для окремого агента
|
||||
embeddedHarness: { runtime: "auto", fallback: "pi" },
|
||||
params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params
|
||||
params: { cacheRetention: "none" }, // перевизначає ключі відповідних params у defaults.models
|
||||
skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано
|
||||
identity: {
|
||||
name: "Samantha",
|
||||
@ -943,26 +943,26 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
```
|
||||
|
||||
- `id`: стабільний ідентифікатор агента (обов’язково).
|
||||
- `default`: якщо задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим буде перший елемент списку.
|
||||
- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні варіанти). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо не задати `fallbacks: []`.
|
||||
- `params`: параметри потоку для конкретного агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
|
||||
- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли він заданий; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills.
|
||||
- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення на рівні повідомлення або сеансу.
|
||||
- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning на рівні повідомлення або сеансу.
|
||||
- `fastModeDefault`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення fast mode на рівні повідомлення або сеансу.
|
||||
- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI в режимі `auto`.
|
||||
- `runtime`: необов’язковий дескриптор середовища виконання для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сеанси harness ACP.
|
||||
- `default`: якщо задано для кількох, перемагає перший (записується попередження). Якщо не задано жодного, типовим є перший запис у списку.
|
||||
- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо не встановити `fallbacks: []`.
|
||||
- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей.
|
||||
- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо їх задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills.
|
||||
- `thinkingDefault`: необов’язковий типовий рівень мислення для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для конкретного повідомлення або сесії.
|
||||
- `reasoningDefault`: необов’язкове типове значення видимості міркувань для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення міркувань для конкретного повідомлення або сесії.
|
||||
- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для конкретного повідомлення або сесії.
|
||||
- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`.
|
||||
- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент повинен типово працювати із сесіями harness ACP.
|
||||
- `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`.
|
||||
- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`.
|
||||
- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент).
|
||||
- Захист успадкування sandbox: якщо сеанс-ініціатор працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
|
||||
- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false).
|
||||
- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
|
||||
- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: false).
|
||||
|
||||
---
|
||||
|
||||
## Маршрутизація між кількома агентами
|
||||
|
||||
Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Багатоагентність](/uk/concepts/multi-agent).
|
||||
Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -979,29 +979,29 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
}
|
||||
```
|
||||
|
||||
### Поля зіставлення прив’язки
|
||||
### Поля відповідності binding
|
||||
|
||||
- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP.
|
||||
- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, типовим є route), `acp` для постійних binding розмов ACP.
|
||||
- `match.channel` (обов’язково)
|
||||
- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис)
|
||||
- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис)
|
||||
- `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`)
|
||||
- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу)
|
||||
- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу)
|
||||
- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }`
|
||||
|
||||
**Детермінований порядок зіставлення:**
|
||||
**Детермінований порядок відповідності:**
|
||||
|
||||
1. `match.peer`
|
||||
2. `match.guildId`
|
||||
3. `match.teamId`
|
||||
4. `match.accountId` (точний збіг, без peer/guild/team)
|
||||
5. `match.accountId: "*"` (на рівні всього каналу)
|
||||
5. `match.accountId: "*"` (на весь канал)
|
||||
6. Типовий агент
|
||||
|
||||
У межах кожного рівня перший відповідний запис у `bindings` має пріоритет.
|
||||
У межах кожного рівня перемагає перший відповідний запис `bindings`.
|
||||
|
||||
Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route.
|
||||
Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding.
|
||||
|
||||
### Профілі доступу для конкретних агентів
|
||||
### Профілі доступу для окремих агентів
|
||||
|
||||
<Accordion title="Повний доступ (без sandbox)">
|
||||
|
||||
@ -1096,7 +1096,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
|
||||
</Accordion>
|
||||
|
||||
Докладніше про пріоритети див. у [Sandbox і інструменти в багатоагентному режимі](/uk/tools/multi-agent-sandbox-tools).
|
||||
Докладніше про пріоритети див. у [Пісочниця й інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools).
|
||||
|
||||
---
|
||||
|
||||
@ -1122,22 +1122,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
},
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
|
||||
parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
|
||||
parentForkMaxTokens: 100000, // пропускати відгалуження від батьківської гілки вище цієї кількості токенів (0 вимикає)
|
||||
maintenance: {
|
||||
mode: "warn", // warn | enforce
|
||||
pruneAfter: "30d",
|
||||
maxEntries: 500,
|
||||
rotateBytes: "10mb",
|
||||
resetArchiveRetention: "30d", // duration or false
|
||||
maxDiskBytes: "500mb", // optional hard budget
|
||||
highWaterBytes: "400mb", // optional cleanup target
|
||||
resetArchiveRetention: "30d", // тривалість або false
|
||||
maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет
|
||||
highWaterBytes: "400mb", // необов’язкова ціль очищення
|
||||
},
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
|
||||
maxAgeHours: 0, // default hard max age in hours (`0` disables)
|
||||
idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає)
|
||||
maxAgeHours: 0, // типова жорстка максимальна давність у годинах (`0` вимикає)
|
||||
},
|
||||
mainKey: "main", // legacy (runtime always uses "main")
|
||||
mainKey: "main", // застаріле поле (runtime завжди використовує "main")
|
||||
agentToAgent: { maxPingPongTurns: 5 },
|
||||
sendPolicy: {
|
||||
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
|
||||
@ -1147,37 +1147,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Докладно про поля session">
|
||||
<Accordion title="Деталі полів session">
|
||||
|
||||
- **`scope`**: базова стратегія групування сеансів для контекстів групового чату.
|
||||
- `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу.
|
||||
- `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст).
|
||||
- **`dmScope`**: як групуються особисті повідомлення.
|
||||
- `main`: усі особисті повідомлення використовують головний сеанс.
|
||||
- **`scope`**: базова стратегія групування сесій для контекстів групового чату.
|
||||
- `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу.
|
||||
- `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст).
|
||||
- **`dmScope`**: спосіб групування DM.
|
||||
- `main`: усі DM використовують спільну основну сесію.
|
||||
- `per-peer`: ізоляція за ідентифікатором відправника між каналами.
|
||||
- `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних вхідних).
|
||||
- `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких вхідних скриньок).
|
||||
- `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів).
|
||||
- **`identityLinks`**: мапа канонічних ідентифікаторів на peer-ідентифікатори з префіксом провайдера для спільного використання сеансів між каналами.
|
||||
- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше.
|
||||
- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`.
|
||||
- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу потоку (типово `100000`).
|
||||
- Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії стенограми батьківського сеансу.
|
||||
- Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківського сеансу.
|
||||
- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного сегмента особистого чату.
|
||||
- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у зворотному ланцюжку між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок.
|
||||
- **`identityLinks`**: мапа канонічних ідентифікаторів до peer із префіксом провайдера для спільного використання сесій між каналами.
|
||||
- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що настає раніше.
|
||||
- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`.
|
||||
- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, дозволена під час створення відгалуженої сесії потоку (типово `100000`).
|
||||
- Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипції батьківської сесії.
|
||||
- Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії.
|
||||
- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів.
|
||||
- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час взаємодії агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong.
|
||||
- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет.
|
||||
- **`maintenance`**: очищення сховища сеансів + параметри зберігання.
|
||||
- **`maintenance`**: очищення сховища сесій і керування збереженням.
|
||||
- `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення.
|
||||
- `pruneAfter`: поріг давності для застарілих записів (типово `30d`).
|
||||
- `pruneAfter`: граничний вік для застарілих записів (типово `30d`).
|
||||
- `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`).
|
||||
- `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`).
|
||||
- `resetArchiveRetention`: термін зберігання архівів стенограм `*.reset.<timestamp>`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
|
||||
- `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси.
|
||||
- `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`.
|
||||
- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до потоків.
|
||||
- `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`).
|
||||
- `resetArchiveRetention`: термін зберігання архівів транскрипцій `*.reset.<timestamp>`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
|
||||
- `maxDiskBytes`: необов’язковий дисковий бюджет для каталогу сесій. У режимі `warn` це записує попередження в журнал; у режимі `enforce` спочатку видаляються найстаріші артефакти/сесії.
|
||||
- `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`.
|
||||
- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до потоків.
|
||||
- `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`)
|
||||
- `idleHours`: типове автоматичне зняття фокусу після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати)
|
||||
- `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати)
|
||||
- `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати)
|
||||
- `maxAgeHours`: типова жорстка максимальна давність у годинах (`0` вимикає; провайдери можуть перевизначати)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -1188,7 +1188,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
responsePrefix: "🦞", // or "auto"
|
||||
responsePrefix: "🦞", // або "auto"
|
||||
ackReaction: "👀",
|
||||
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
|
||||
removeAckAfterReply: false,
|
||||
@ -1203,7 +1203,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
},
|
||||
},
|
||||
inbound: {
|
||||
debounceMs: 2000, // 0 disables
|
||||
debounceMs: 2000, // 0 вимикає
|
||||
byChannel: {
|
||||
whatsapp: 5000,
|
||||
slack: 1500,
|
||||
@ -1217,7 +1217,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
|
||||
Перевизначення для каналу/облікового запису: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
|
||||
|
||||
Порядок визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` формує `[{identity.name}]`.
|
||||
Визначення значення (найспецифічніше перемагає): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`.
|
||||
|
||||
**Змінні шаблону:**
|
||||
|
||||
@ -1226,27 +1226,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
| `{model}` | Коротка назва моделі | `claude-opus-4-6` |
|
||||
| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` |
|
||||
| `{provider}` | Назва провайдера | `anthropic` |
|
||||
| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
|
||||
| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) |
|
||||
| `{thinkingLevel}` | Поточний рівень мислення | `high`, `low`, `off` |
|
||||
| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) |
|
||||
|
||||
Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`.
|
||||
Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`.
|
||||
|
||||
### Реакція-підтвердження
|
||||
### Реакція підтвердження
|
||||
|
||||
- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути.
|
||||
- Типово використовує `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути.
|
||||
- Перевизначення для каналу: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
|
||||
- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity.
|
||||
- Область: `group-mentions` (типово), `group-all`, `direct`, `all`.
|
||||
- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram.
|
||||
- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`.
|
||||
- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram.
|
||||
- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram.
|
||||
У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження.
|
||||
У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження.
|
||||
У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу.
|
||||
|
||||
### Inbound debounce
|
||||
### Debounce для вхідних повідомлень
|
||||
|
||||
Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди оминають debounce.
|
||||
Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce.
|
||||
|
||||
### TTS (перетворення тексту на мовлення)
|
||||
### TTS (синтез мовлення)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1289,16 +1289,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
|
||||
- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан.
|
||||
- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку.
|
||||
- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (лише за явної згоди).
|
||||
- Для API-ключів резервно використовуються `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
|
||||
- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (лише за явного ввімкнення).
|
||||
- API-ключі беруться з резервних значень `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
|
||||
- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
|
||||
- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як сумісний із OpenAI TTS сервер і послаблює перевірку моделі/голосу.
|
||||
- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу.
|
||||
|
||||
---
|
||||
|
||||
## Talk
|
||||
## Розмова
|
||||
|
||||
Типові значення для режиму Talk (macOS/iOS/Android).
|
||||
Типові значення для режиму розмови (macOS/iOS/Android).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1322,18 +1322,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
|
||||
}
|
||||
```
|
||||
|
||||
- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk.
|
||||
- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються до `talk.providers.<provider>`.
|
||||
- Для ідентифікаторів голосу резервно використовуються `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
|
||||
- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef.
|
||||
- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API-ключ Talk.
|
||||
- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви.
|
||||
- `silenceTimeoutMs` визначає, скільки режим Talk чекає після тиші користувача, перш ніж надсилати стенограму. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`).
|
||||
- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів режиму розмови.
|
||||
- Застарілі пласкі ключі режиму розмови (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються в `talk.providers.<provider>`.
|
||||
- Ідентифікатори голосів беруться з резервних значень `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
|
||||
- `providers.*.apiKey` приймає текстові рядки або об’єкти SecretRef.
|
||||
- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ режиму розмови не налаштовано.
|
||||
- `providers.*.voiceAliases` дозволяє директивам режиму розмови використовувати дружні назви.
|
||||
- `silenceTimeoutMs` визначає, скільки часу режим розмови чекає після тиші користувача, перш ніж надіслати транскрипцію. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`).
|
||||
|
||||
---
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації
|
||||
- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування
|
||||
- [Конфігурація](/uk/gateway/configuration) — типові завдання та швидке налаштування
|
||||
- [Приклади конфігурації](/uk/gateway/configuration-examples)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -2,54 +2,54 @@
|
||||
read_when:
|
||||
- Проєктування або рефакторинг розуміння медіа
|
||||
- Налаштування попередньої обробки вхідного аудіо/відео/зображень
|
||||
summary: Вхідне розуміння зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера та CLI
|
||||
summary: Розуміння вхідних зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера + CLI
|
||||
title: Розуміння медіа
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T01:43:33Z"
|
||||
generated_at: "2026-04-25T00:01:29Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a9eb9449fbc1bed170bbef213aa43d71d4146edbc0dd626ef50af9e044a8e299
|
||||
source_hash: 108a90f15f7c86539d01a880e601d2c43305029a2e29330778c60fddf79a4d32
|
||||
source_path: nodes/media-understanding.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Розуміння медіа — вхідне (2026-01-17)
|
||||
# Розуміння медіа — вхідні дані (2026-01-17)
|
||||
|
||||
OpenClaw може **узагальнювати вхідні медіа** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдерів, і цю функцію можна вимкнути або налаштувати. Якщо розуміння вимкнено, моделі, як і раніше, отримують оригінальні файли/URL.
|
||||
OpenClaw може **узагальнювати вхідні медіафайли** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдера, і цю функцію можна вимкнути або налаштувати. Якщо розуміння вимкнено, моделі, як і раніше, отримують оригінальні файли/URL.
|
||||
|
||||
Поведінка медіа, специфічна для вендора, реєструється плагінами вендорів, тоді як ядро OpenClaw володіє спільною конфігурацією `tools.media`, порядком резервного переходу та інтеграцією з конвеєром відповіді.
|
||||
Поведінка медіа, специфічна для постачальника, реєструється через plugin постачальника, тоді як ядро OpenClaw керує спільною конфігурацією `tools.media`, порядком резервного перемикання та інтеграцією з конвеєром відповіді.
|
||||
|
||||
## Цілі
|
||||
|
||||
- Необов’язково: попередньо перетворювати вхідні медіа на короткий текст для швидшої маршрутизації та кращого розбору команд.
|
||||
- Завжди зберігати доставку оригінальних медіа до моделі.
|
||||
- Підтримувати **API провайдерів** і **резервні варіанти через CLI**.
|
||||
- Дозволяти кілька моделей з упорядкованим резервним переходом (помилка/розмір/тайм-аут).
|
||||
- Необов’язково: попередньо зводити вхідні медіафайли до короткого тексту для швидшої маршрутизації + кращого розбору команд.
|
||||
- Завжди зберігати доставку оригінального медіа до моделі.
|
||||
- Підтримувати **API провайдерів** і **резервні варіанти CLI**.
|
||||
- Дозволяти кілька моделей з упорядкованим резервним перемиканням (помилка/розмір/тайм-аут).
|
||||
|
||||
## Поведінка на високому рівні
|
||||
|
||||
1. Зібрати вхідні вкладення (`MediaPaths`, `MediaUrls`, `MediaTypes`).
|
||||
2. Для кожної увімкненої можливості (зображення/аудіо/відео) вибрати вкладення згідно з політикою (типово: **перше**).
|
||||
3. Вибрати перший придатний запис моделі (розмір + можливість + автентифікація).
|
||||
4. Якщо модель не спрацювала або медіа надто велике, **перейти до наступного запису**.
|
||||
2. Для кожної ввімкненої можливості (зображення/аудіо/відео) вибрати вкладення відповідно до політики (типово: **перше**).
|
||||
3. Вибрати перший допустимий запис моделі (розмір + можливість + автентифікація).
|
||||
4. Якщо модель не спрацьовує або медіафайл надто великий, **переключитися на наступний запис**.
|
||||
5. У разі успіху:
|
||||
- `Body` стає блоком `[Image]`, `[Audio]` або `[Video]`.
|
||||
- Для аудіо встановлюється `{{Transcript}}`; розбір команд використовує текст підпису, якщо він є, інакше — транскрипт.
|
||||
- Підписи зберігаються як `User text:` усередині блоку.
|
||||
|
||||
Якщо розуміння не вдалося або його вимкнено, **потік відповіді продовжується** з оригінальним тілом і вкладеннями.
|
||||
Якщо розуміння не спрацювало або вимкнене, **потік відповіді продовжується** з оригінальним тілом + вкладеннями.
|
||||
|
||||
## Огляд конфігурації
|
||||
|
||||
`tools.media` підтримує **спільні моделі** та перевизначення для окремих можливостей:
|
||||
`tools.media` підтримує **спільні моделі** плюс перевизначення для кожної можливості окремо:
|
||||
|
||||
- `tools.media.models`: список спільних моделей (використовуйте `capabilities` для обмеження).
|
||||
- `tools.media.models`: спільний список моделей (використовуйте `capabilities` для обмеження).
|
||||
- `tools.media.image` / `tools.media.audio` / `tools.media.video`:
|
||||
- типові значення (`prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`)
|
||||
- перевизначення провайдера (`baseUrl`, `headers`, `providerOptions`)
|
||||
- аудіоопції Deepgram через `tools.media.audio.providerOptions.deepgram`
|
||||
- елементи керування відображенням транскрипту аудіо (`echoTranscript`, типово `false`; `echoFormat`)
|
||||
- необов’язковий список `models` **для окремої можливості** (має пріоритет над спільними моделями)
|
||||
- параметри аудіо Deepgram через `tools.media.audio.providerOptions.deepgram`
|
||||
- елементи керування ехо транскрипту аудіо (`echoTranscript`, типово `false`; `echoFormat`)
|
||||
- необов’язковий список `models` **для конкретної можливості** (має пріоритет над спільними моделями)
|
||||
- політика `attachments` (`mode`, `maxAttachments`, `prefer`)
|
||||
- `scope` (необов’язкове обмеження за channel/chatType/session key)
|
||||
- `tools.media.concurrency`: максимальна кількість одночасних запусків можливостей (типово **2**).
|
||||
@ -117,8 +117,8 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
Шаблони CLI також можуть використовувати:
|
||||
|
||||
- `{{MediaDir}}` (каталог, що містить медіафайл)
|
||||
- `{{OutputDir}}` (робочий каталог, створений для цього запуску)
|
||||
- `{{OutputBase}}` (базовий шлях робочого файла без розширення)
|
||||
- `{{OutputDir}}` (тимчасовий каталог, створений для цього запуску)
|
||||
- `{{OutputBase}}` (базовий шлях до тимчасового файла, без розширення)
|
||||
|
||||
## Типові значення та обмеження
|
||||
|
||||
@ -133,18 +133,18 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
|
||||
Правила:
|
||||
|
||||
- Якщо медіа перевищує `maxBytes`, ця модель пропускається і **робиться спроба з наступною моделлю**.
|
||||
- Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через провайдера/CLI.
|
||||
- Якщо модель повертає більше ніж `maxChars`, вивід обрізається.
|
||||
- `prompt` типово має простий вигляд “Describe the {media}.” плюс підказка щодо `maxChars` (лише для зображень/відео).
|
||||
- Якщо активна основна модель зображень уже нативно підтримує vision, OpenClaw пропускає блок підсумку `[Image]` і натомість передає оригінальне зображення в модель.
|
||||
- Якщо основна модель Gateway/WebChat підтримує лише текст, вкладення зображень зберігаються як вивантажені посилання `media://inbound/*`, щоб інструмент зображень або налаштована модель зображень усе ще могли їх перевірити замість втрати вкладення.
|
||||
- Явні запити `openclaw infer image describe --model <provider/model>` відрізняються: вони запускають цей provider/model з підтримкою зображень напряму, зокрема посилання Ollama на кшталт `ollama/qwen2.5vl:7b`.
|
||||
- Якщо `<capability>.enabled: true`, але моделі не налаштовано, OpenClaw пробує **активну модель відповіді**, якщо її провайдер підтримує цю можливість.
|
||||
- Якщо медіафайл перевищує `maxBytes`, ця модель пропускається і **пробується наступна модель**.
|
||||
- Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через provider/CLI.
|
||||
- Якщо модель повертає більше, ніж `maxChars`, вивід обрізається.
|
||||
- Типове значення `prompt` — просте “Describe the {media}.” плюс вказівка щодо `maxChars` (лише для зображення/відео).
|
||||
- Якщо активна основна модель для зображень уже нативно підтримує зір, OpenClaw пропускає блок узагальнення `[Image]` і натомість передає оригінальне зображення в модель.
|
||||
- Якщо основна модель Gateway/WebChat є лише текстовою, вкладення зображень зберігаються як винесені посилання `media://inbound/*`, щоб інструменти для зображень/PDF або налаштована модель для зображень усе ще могли їх аналізувати замість втрати вкладення.
|
||||
- Явні запити `openclaw infer image describe --model <provider/model>` відрізняються: вони напряму запускають указаного provider/model із підтримкою зображень, включно з посиланнями Ollama, такими як `ollama/qwen2.5vl:7b`.
|
||||
- Якщо `<capability>.enabled: true`, але моделі не налаштовано, OpenClaw намагається використати **активну модель відповіді**, якщо її провайдер підтримує цю можливість.
|
||||
|
||||
### Автовизначення розуміння медіа (типово)
|
||||
|
||||
Якщо `tools.media.<capability>.enabled` **не** встановлено в `false` і ви не налаштували моделі, OpenClaw виконує автовизначення в такому порядку і **зупиняється на першому робочому варіанті**:
|
||||
Якщо `tools.media.<capability>.enabled` **не** встановлено в `false` і ви не налаштували моделі, OpenClaw автоматично визначає у такому порядку і **зупиняється на першому робочому варіанті**:
|
||||
|
||||
1. **Активна модель відповіді**, якщо її провайдер підтримує цю можливість.
|
||||
2. Основні/резервні посилання **`agents.defaults.imageModel`** (лише для зображень).
|
||||
@ -154,10 +154,10 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
- `whisper` (Python CLI; автоматично завантажує моделі)
|
||||
4. **Gemini CLI** (`gemini`) з використанням `read_many_files`
|
||||
5. **Автентифікація провайдера**
|
||||
- Налаштовані записи `models.providers.*`, які підтримують цю можливість, пробуються до вбудованого порядку резервного переходу.
|
||||
- Провайдери з конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим плагіном вендора.
|
||||
- Розуміння зображень через Ollama доступне за явного вибору, наприклад через `agents.defaults.imageModel` або `openclaw infer image describe --model ollama/<vision-model>`.
|
||||
- Вбудований порядок резервного переходу:
|
||||
- Налаштовані записи `models.providers.*`, що підтримують цю можливість, пробуються до вбудованого порядку резервного перемикання.
|
||||
- Провайдери конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим vendor plugin.
|
||||
- Розуміння зображень Ollama доступне за явного вибору, наприклад через `agents.defaults.imageModel` або `openclaw infer image describe --model ollama/<vision-model>`.
|
||||
- Вбудований порядок резервного перемикання:
|
||||
- Аудіо: OpenAI → Groq → xAI → Deepgram → Google → Mistral
|
||||
- Зображення: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
|
||||
- Відео: Google → Qwen → Moonshot
|
||||
@ -176,19 +176,19 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
}
|
||||
```
|
||||
|
||||
Примітка: визначення бінарних файлів є best-effort у macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну CLI-модель з повним шляхом до команди.
|
||||
Примітка: виявлення бінарних файлів є best-effort на macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну модель CLI з повним шляхом до команди.
|
||||
|
||||
### Підтримка середовища проксі (моделі провайдерів)
|
||||
### Підтримка проксі через середовище (моделі provider)
|
||||
|
||||
Коли увімкнено розуміння медіа **audio** і **video** на основі провайдера, OpenClaw враховує стандартні змінні середовища вихідного проксі для HTTP-викликів провайдера:
|
||||
Коли ввімкнено розуміння медіа **аудіо** та **відео** на основі провайдера, OpenClaw враховує стандартні змінні середовища вихідного проксі для HTTP-викликів провайдера:
|
||||
|
||||
- `HTTPS_PROXY`
|
||||
- `HTTP_PROXY`
|
||||
- `https_proxy`
|
||||
- `http_proxy`
|
||||
|
||||
Якщо змінні середовища проксі не задані, розуміння медіа використовує прямий вихідний трафік.
|
||||
Якщо значення проксі некоректне, OpenClaw записує попередження в журнал і повертається до прямого отримання.
|
||||
Якщо змінні середовища проксі не задано, розуміння медіа використовує прямий вихідний трафік.
|
||||
Якщо значення проксі має неправильний формат, OpenClaw записує попередження в журнал і повертається до прямого отримання.
|
||||
|
||||
## Можливості (необов’язково)
|
||||
|
||||
@ -207,33 +207,33 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
- `deepgram`: **audio**
|
||||
- Будь-який каталог `models.providers.<id>.models[]` з моделлю, що підтримує зображення: **image**
|
||||
|
||||
Для записів CLI **задавайте `capabilities` явно**, щоб уникнути неочікуваних збігів.
|
||||
Якщо ви пропускаєте `capabilities`, запис придатний для списку, у якому він з’являється.
|
||||
Для записів CLI **явно задавайте `capabilities`**, щоб уникнути неочікуваних збігів.
|
||||
Якщо ви опускаєте `capabilities`, запис вважається допустимим для того списку, в якому він з’являється.
|
||||
|
||||
## Матриця підтримки провайдерів (інтеграції OpenClaw)
|
||||
|
||||
| Можливість | Інтеграція провайдера | Примітки |
|
||||
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Зображення | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Плагіни вендорів реєструють підтримку зображень; `openai-codex/*` використовує механізм OAuth-провайдера; `codex/*` використовує обмежений хід Codex app-server; MiniMax і MiniMax OAuth обидва використовують `MiniMax-VL-01`; провайдери конфігурації з підтримкою зображень реєструються автоматично. |
|
||||
| Аудіо | OpenAI, Groq, Deepgram, Google, Mistral | Транскрибування через провайдера (Whisper/Deepgram/Gemini/Voxtral). |
|
||||
| Відео | Google, Qwen, Moonshot | Розуміння відео через провайдера за допомогою плагінів вендорів; розуміння відео Qwen використовує Standard DashScope endpoints. |
|
||||
| Capability | Provider integration | Notes |
|
||||
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Image | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Vendor plugins register image support; `openai-codex/*` uses OAuth provider plumbing; `codex/*` uses a bounded Codex app-server turn; MiniMax and MiniMax OAuth both use `MiniMax-VL-01`; image-capable config providers auto-register. |
|
||||
| Audio | OpenAI, Groq, Deepgram, Google, Mistral | Provider transcription (Whisper/Deepgram/Gemini/Voxtral). |
|
||||
| Video | Google, Qwen, Moonshot | Provider video understanding via vendor plugins; Qwen video understanding uses the Standard DashScope endpoints. |
|
||||
|
||||
Примітка щодо MiniMax:
|
||||
|
||||
- Розуміння зображень через `minimax` і `minimax-portal` походить із провайдера медіа `MiniMax-VL-01`, що належить плагіну.
|
||||
- Вбудований текстовий каталог MiniMax, як і раніше, починається з режиму лише тексту; явні записи `models.providers.minimax` матеріалізують посилання чату M2.7 з підтримкою зображень.
|
||||
- `minimax` і `minimax-portal` для розуміння зображень походять із media provider `MiniMax-VL-01`, яким керує plugin.
|
||||
- Вбудований текстовий каталог MiniMax, як і раніше, спочатку є лише текстовим; явні записи `models.providers.minimax` матеріалізують chat-посилання M2.7 із підтримкою зображень.
|
||||
|
||||
## Рекомендації щодо вибору моделі
|
||||
|
||||
- Віддавайте перевагу найсильнішій моделі останнього покоління, доступній для кожної медіаможливості, коли важливі якість і безпека.
|
||||
- Для агентів з увімкненими інструментами, які працюють із недовіреними вхідними даними, уникайте старіших/слабших медіамоделей.
|
||||
- Тримайте принаймні один резервний варіант для кожної можливості з міркувань доступності (якісна модель + швидша/дешевша модель).
|
||||
- Надавайте перевагу найсильнішій моделі останнього покоління, доступній для кожної медіаможливості, коли важливі якість і безпека.
|
||||
- Для агентів з увімкненими інструментами, які обробляють недовірені вхідні дані, уникайте старіших/слабших медіамоделей.
|
||||
- Тримайте принаймні один резервний варіант для кожної можливості на випадок недоступності (якісна модель + швидша/дешевша модель).
|
||||
- Резервні варіанти CLI (`whisper-cli`, `whisper`, `gemini`) корисні, коли API провайдерів недоступні.
|
||||
- Примітка щодо `parakeet-mlx`: із `--output-dir` OpenClaw читає `<output-dir>/<media-basename>.txt`, коли формат виводу — `txt` (або не заданий); для форматів, відмінних від `txt`, використовується stdout.
|
||||
- Примітка щодо `parakeet-mlx`: з `--output-dir` OpenClaw читає `<output-dir>/<media-basename>.txt`, коли формат виводу — `txt` (або не вказаний); формати, відмінні від `txt`, повертаються до stdout.
|
||||
|
||||
## Політика вкладень
|
||||
|
||||
Параметр `attachments` для окремої можливості керує тим, які вкладення обробляються:
|
||||
`attachments` для конкретної можливості керує тим, які вкладення обробляються:
|
||||
|
||||
- `mode`: `first` (типово) або `all`
|
||||
- `maxAttachments`: обмеження кількості оброблюваних вкладень (типово **1**)
|
||||
@ -241,18 +241,18 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
|
||||
Коли `mode: "all"`, результати позначаються як `[Image 1/2]`, `[Audio 2/2]` тощо.
|
||||
|
||||
Поведінка витягування з файлових вкладень:
|
||||
Поведінка вилучення тексту з файлових вкладень:
|
||||
|
||||
- Витягнутий текст файлу обгортається як **недовірений зовнішній вміст** перед додаванням до підказки медіа.
|
||||
- Вставлений блок використовує явні маркери меж на кшталт `<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>` /
|
||||
`<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>` і містить рядок метаданих `Source: External`.
|
||||
- Цей шлях витягування вкладень навмисно пропускає довгий банер `SECURITY NOTICE:`, щоб не роздувати підказку медіа; маркери меж і метадані при цьому все одно зберігаються.
|
||||
- Якщо файл не містить тексту, який можна витягнути, OpenClaw вставляє `[No extractable text]`.
|
||||
- Якщо PDF у цьому шляху повертається до відтворених зображень сторінок, підказка медіа зберігає заповнювач `[PDF content rendered to images; images not forwarded to model]`, тому що цей крок витягування вкладень пересилає текстові блоки, а не відтворені зображення PDF.
|
||||
- Вилучений текст файла обгортається як **недовірений зовнішній вміст**, перш ніж його буде додано до media prompt.
|
||||
- Вставлений блок використовує явні маркери меж, такі як `<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>` /
|
||||
`<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>`, і містить рядок метаданих `Source: External`.
|
||||
- Цей шлях вилучення вкладень навмисно опускає довгий банер `SECURITY NOTICE:`, щоб не роздувати media prompt; маркери меж і метадані при цьому все одно зберігаються.
|
||||
- Якщо файл не містить тексту, який можна вилучити, OpenClaw вставляє `[No extractable text]`.
|
||||
- Якщо PDF у цьому шляху повертається до рендерингу сторінок як зображень, media prompt зберігає заповнювач `[PDF content rendered to images; images not forwarded to model]`, оскільки цей крок вилучення вкладень передає текстові блоки, а не відрендерені PDF-зображення.
|
||||
|
||||
## Приклади конфігурації
|
||||
|
||||
### 1) Список спільних моделей + перевизначення
|
||||
### 1) Спільний список моделей + перевизначення
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -360,7 +360,7 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
}
|
||||
```
|
||||
|
||||
### 4) Один мультимодальний запис (явно вказані можливості)
|
||||
### 4) Один multimodal-запис (явні можливості)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -398,23 +398,23 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб
|
||||
}
|
||||
```
|
||||
|
||||
## Вивід статусу
|
||||
## Вивід стану
|
||||
|
||||
Коли виконується розуміння медіа, `/status` містить короткий рядок підсумку:
|
||||
Коли запускається розуміння медіа, `/status` містить короткий підсумковий рядок:
|
||||
|
||||
```
|
||||
📎 Медіа: зображення ok (openai/gpt-5.4) · аудіо пропущено (maxBytes)
|
||||
📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)
|
||||
```
|
||||
|
||||
Тут показуються результати для кожної можливості та вибраний provider/model, якщо застосовно.
|
||||
Це показує результати для кожної можливості та вибраного provider/model, якщо застосовно.
|
||||
|
||||
## Примітки
|
||||
|
||||
- Розуміння є **best-effort**. Помилки не блокують відповіді.
|
||||
- Вкладення все одно передаються моделям, навіть коли розуміння вимкнено.
|
||||
- Використовуйте `scope`, щоб обмежити, де запускається розуміння (наприклад, лише в особистих повідомленнях).
|
||||
- Використовуйте `scope`, щоб обмежити, де запускається розуміння (наприклад, лише в DM).
|
||||
|
||||
## Пов’язана документація
|
||||
## Пов’язані документи
|
||||
|
||||
- [Конфігурація](/uk/gateway/configuration)
|
||||
- [Підтримка зображень і медіа](/uk/nodes/images)
|
||||
|
||||
@ -1,60 +1,49 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете створити новий Plugin для OpenClaw
|
||||
- Вам потрібен швидкий старт для розробки Plugin-ів
|
||||
- Вам потрібен швидкий старт для розробки Plugin
|
||||
- Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw
|
||||
sidebarTitle: Getting Started
|
||||
summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини
|
||||
title: Створення Plugin-ів
|
||||
title: Створення плагінів
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:32:17Z"
|
||||
generated_at: "2026-04-25T00:01:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fc6a4b97c403d7d381fae13e3815737a4b21144755e924bdf9d63c22d4cac844
|
||||
source_hash: 69c7ffb65750fd0c1fa786600c55a371dace790b8b1034fa42f4b80f5f7146df
|
||||
source_path: plugins/building-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Plugin-и розширюють OpenClaw новими можливостями: канали, провайдери моделей,
|
||||
мовлення, транскрибування в реальному часі, голос у реальному часі, розуміння медіа, генерація
|
||||
зображень, генерація відео, отримання вебданих, вебпошук, інструменти агентів або
|
||||
будь-яка комбінація.
|
||||
Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, web fetch, web search, інструменти агента або будь-яка їх комбінація.
|
||||
|
||||
Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в
|
||||
[ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою
|
||||
`openclaw plugins install <package-name>`. OpenClaw спочатку намагається використати ClawHub, а
|
||||
потім автоматично переходить до npm.
|
||||
Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub) або npm, а користувачі встановлять його за допомогою `openclaw plugins install <package-name>`. OpenClaw спочатку намагається використати ClawHub і автоматично переходить на npm, якщо це потрібно.
|
||||
|
||||
## Передумови
|
||||
|
||||
- Node >= 22 і менеджер пакетів (npm або pnpm)
|
||||
- Знайомство з TypeScript (ESM)
|
||||
- Для Plugin-ів у репозиторії: клонований репозиторій і виконано `pnpm install`
|
||||
- Для Plugin у репозиторії: репозиторій клоновано і виконано `pnpm install`
|
||||
|
||||
## Який тип Plugin-а?
|
||||
## Який тип Plugin?
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Plugin каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
</Card>
|
||||
<Card title="Plugin провайдера" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Додайте провайдера моделей (LLM, проксі або власний endpoint)
|
||||
Додайте провайдера моделі (LLM, проксі або власну кінцеву точку)
|
||||
</Card>
|
||||
<Card title="Plugin інструмента / hook" icon="wrench" href="/uk/plugins/hooks">
|
||||
Зареєструйте інструменти агента, event hooks або сервіси — продовження нижче
|
||||
<Card title="Plugin інструменту / хука" icon="wrench" href="/uk/plugins/hooks">
|
||||
Зареєструйте інструменти агента, хуки подій або сервіси — продовження нижче
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Для Plugin-а каналу, який не гарантовано буде встановлений під час виконання
|
||||
onboarding/setup, використовуйте `createOptionalChannelSetupSurface(...)` з
|
||||
`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера setup + wizard,
|
||||
яка повідомляє про вимогу встановлення та блокує реальні записи конфігурації,
|
||||
доки Plugin не буде встановлено.
|
||||
Для Plugin каналу, який не гарантовано буде встановлений на момент запуску онбордингу/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з `openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування + майстра, яка повідомляє про вимогу встановлення та забороняє реальні записи конфігурації, доки Plugin не буде встановлено.
|
||||
|
||||
## Швидкий старт: Plugin інструмента
|
||||
## Швидкий старт: Plugin інструменту
|
||||
|
||||
Цей посібник створює мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів
|
||||
каналів і провайдерів є окремі посібники за посиланнями вище.
|
||||
У цьому покроковому прикладі створюється мінімальний Plugin, який реєструє інструмент агента. Для Plugin каналів і провайдерів є окремі посібники за посиланнями вище.
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть пакет і маніфест">
|
||||
@ -91,9 +80,7 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Кожному Plugin-у потрібен маніфест, навіть якщо в ньому немає конфігурації. Див.
|
||||
[Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти публікації в ClawHub
|
||||
містяться в `docs/snippets/plugin-publish/`.
|
||||
Кожному Plugin потрібен маніфест, навіть якщо конфігурації немає. Повну схему дивіться в [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub розміщено в `docs/snippets/plugin-publish/`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -121,15 +108,14 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac
|
||||
});
|
||||
```
|
||||
|
||||
`definePluginEntry` призначений для Plugin-ів, які не є каналами. Для каналів використовуйте
|
||||
`defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins).
|
||||
Повний список параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints).
|
||||
`definePluginEntry` призначений для Plugin, які не є каналами. Для каналів використовуйте `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins).
|
||||
Повний список параметрів точки входу дивіться в [Entry Points](/uk/plugins/sdk-entrypoints).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Протестуйте й опублікуйте">
|
||||
|
||||
**Зовнішні Plugin-и:** виконайте перевірку та опублікуйте через ClawHub, а потім встановіть:
|
||||
**Зовнішні Plugins:** перевірте й опублікуйте через ClawHub, а потім встановіть:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
@ -137,10 +123,9 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, таких як
|
||||
`@myorg/openclaw-my-plugin`.
|
||||
OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів, таких як `@myorg/openclaw-my-plugin`.
|
||||
|
||||
**Plugin-и в репозиторії:** розмістіть у дереві workspace вбудованих Plugin-ів — вони будуть виявлені автоматично.
|
||||
**Plugins у репозиторії:** розмістіть у дереві workspace вбудованих Plugin — їх буде виявлено автоматично.
|
||||
|
||||
```bash
|
||||
pnpm test -- <bundled-plugin-root>/my-plugin/
|
||||
@ -149,70 +134,59 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Можливості Plugin-а
|
||||
## Можливості Plugin
|
||||
|
||||
Один Plugin може реєструвати будь-яку кількість можливостей через об’єкт `api`:
|
||||
Один Plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`:
|
||||
|
||||
| Можливість | Метод реєстрації | Докладний посібник |
|
||||
| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| Текстова інференція (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
|
||||
| Backend інференції CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) |
|
||||
| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
|
||||
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Отримання вебданих | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) |
|
||||
| Інструменти агентів | `api.registerTool(...)` | Нижче |
|
||||
| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) |
|
||||
| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) |
|
||||
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Можливість | Метод реєстрації | Детальний посібник |
|
||||
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
|
||||
| Бекенд inference для CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) |
|
||||
| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
|
||||
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) |
|
||||
| Інструменти агента | `api.registerTool(...)` | Нижче |
|
||||
| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Хуки Plugin | `api.on(...)` | [Хуки Plugin](/uk/plugins/hooks) |
|
||||
| Внутрішні хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) |
|
||||
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
|
||||
Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api).
|
||||
Повний API реєстрації дивіться в [Огляд SDK](/uk/plugins/sdk-overview#registration-api).
|
||||
|
||||
Вбудовані Plugin-и можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм
|
||||
потрібне асинхронне переписування результатів інструментів до того, як модель побачить вивід. Вкажіть
|
||||
цільові harnesses у `contracts.agentToolResultMiddleware`, наприклад
|
||||
`["pi", "codex-app-server"]`. Це довірений механізм для вбудованих Plugin-ів; зовнішнім
|
||||
Plugin-ам варто надавати перевагу звичайним Plugin hooks OpenClaw, якщо тільки OpenClaw не отримає
|
||||
явну політику довіри для цієї можливості.
|
||||
Вбудовані Plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм потрібно асинхронно переписувати результати інструментів до того, як модель побачить вивід. Оголосіть цільові runtime у `contracts.agentToolResultMiddleware`, наприклад `["pi", "codex"]`. Це шов довіри для вбудованих Plugin; зовнішнім Plugins слід віддавати перевагу звичайним хукам Plugin OpenClaw, якщо тільки в OpenClaw не з’явиться явна політика довіри для цієї можливості.
|
||||
|
||||
Якщо ваш Plugin реєструє користувацькі методи gateway RPC, використовуйте
|
||||
префікс, специфічний для Plugin-а. Простори імен адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди відповідають
|
||||
`operator.admin`, навіть якщо Plugin запитує вужчу область доступу.
|
||||
Якщо ваш Plugin реєструє власні методи Gateway RPC, використовуйте префікс, специфічний для Plugin. Простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди зіставляються з `operator.admin`, навіть якщо Plugin запитує вужчу область видимості.
|
||||
|
||||
Семантика захисту hooks, про яку слід пам’ятати:
|
||||
Семантика guard-хуків, яку варто враховувати:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує у користувача підтвердження через overlay підтвердження exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` розглядається як відсутність рішення.
|
||||
- `message_sending`: `{ cancel: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення.
|
||||
- `message_received`: надавайте перевагу типізованому полю `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу.
|
||||
- `message_sending`: надавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId`, а не ключам metadata, специфічним для каналу.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` вважається відсутністю рішення.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` вважається відсутністю рішення.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` вважається відсутністю рішення.
|
||||
- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для специфічних для каналу доповнень.
|
||||
- `message_sending`: віддавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId`, а не специфічним для каналу ключам metadata.
|
||||
|
||||
Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin-ів з обмеженим fallback: якщо ідентифікатор підтвердження exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через підтвердження Plugin-ів. Переспрямування підтверджень Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації.
|
||||
Команда `/approve` обробляє як схвалення exec, так і схвалення Plugin, із обмеженим fallback: якщо ідентифікатор схвалення exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через схвалення Plugin. Переспрямування схвалень Plugin можна налаштувати окремо через `approvals.plugin` у конфігурації.
|
||||
|
||||
Якщо користувацька логіка підтвердження має визначати той самий випадок обмеженого fallback,
|
||||
використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime`
|
||||
замість ручного зіставлення рядків закінчення терміну підтвердження.
|
||||
Якщо власна логіка схвалення має визначати той самий випадок обмеженого fallback, використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків закінчення строку дії схвалення.
|
||||
|
||||
Приклади й довідник hooks див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
Приклади й довідку щодо хуків дивіться в [Хуки Plugin](/uk/plugins/hooks).
|
||||
|
||||
## Реєстрація інструментів агентів
|
||||
## Реєстрація інструментів агента
|
||||
|
||||
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди
|
||||
доступні) або необов’язковими (користувач сам вмикає їх):
|
||||
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди доступні) або необов’язковими (користувач вмикає їх окремо):
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -251,11 +225,11 @@ register(api) {
|
||||
|
||||
- Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються)
|
||||
- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів
|
||||
- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши ідентифікатор Plugin-а до `tools.allow`
|
||||
- Користувачі можуть увімкнути всі інструменти Plugin, додавши ідентифікатор Plugin до `tools.allow`
|
||||
|
||||
## Угоди щодо імпортів
|
||||
## Угоди щодо імпорту
|
||||
|
||||
Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/<subpath>`:
|
||||
Завжди імпортуйте з вузькоспрямованих шляхів `openclaw/plugin-sdk/<subpath>`:
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -265,72 +239,66 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { ... } from "openclaw/plugin-sdk";
|
||||
```
|
||||
|
||||
Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview).
|
||||
Повний довідник підшляхів дивіться в [Огляд SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
У межах вашого Plugin-а використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
|
||||
внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK.
|
||||
У межах вашого Plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK.
|
||||
|
||||
Для Plugin-ів провайдерів зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах
|
||||
кореня пакета, якщо тільки цей механізм не є справді загальним. Поточні вбудовані приклади:
|
||||
Для Plugin провайдерів тримайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах у корені пакета, якщо тільки цей шов не є справді загальним. Поточні вбудовані приклади:
|
||||
|
||||
- Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta
|
||||
- OpenAI: конструктори провайдерів, допоміжні засоби для моделей за замовчуванням, провайдери реального часу
|
||||
- OpenRouter: конструктор провайдера плюс допоміжні засоби onboarding/config
|
||||
- Anthropic: обгортки потоків Claude і допоміжні функції для `service_tier` / beta
|
||||
- OpenAI: конструктори провайдерів, допоміжні функції для моделей за замовчуванням, провайдери реального часу
|
||||
- OpenRouter: конструктор провайдера плюс допоміжні функції для онбордингу/конфігурації
|
||||
|
||||
Якщо допоміжний засіб корисний лише в межах одного пакета вбудованого провайдера, залишайте його
|
||||
на цьому рівні пакета замість перенесення до `openclaw/plugin-sdk/*`.
|
||||
Якщо допоміжна функція корисна лише всередині одного пакета вбудованого провайдера, залишайте її на шві кореня цього пакета замість перенесення в `openclaw/plugin-sdk/*`.
|
||||
|
||||
Деякі згенеровані механізми допоміжних засобів `openclaw/plugin-sdk/<bundled-id>` усе ще існують для
|
||||
підтримки вбудованих Plugin-ів і сумісності, наприклад
|
||||
`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані
|
||||
поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів.
|
||||
Деякі згенеровані шви допоміжних функцій `openclaw/plugin-sdk/<bundled-id>` усе ще існують для підтримки та сумісності вбудованих Plugin, наприклад `plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як зарезервовані поверхні, а не як типовий шаблон для нових сторонніх Plugin.
|
||||
|
||||
## Контрольний список перед поданням
|
||||
|
||||
<Check>**package.json** має коректні метадані `openclaw`</Check>
|
||||
<Check>**package.json** має правильні метадані `openclaw`</Check>
|
||||
<Check>Маніфест **openclaw.plugin.json** присутній і валідний</Check>
|
||||
<Check>Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry`</Check>
|
||||
<Check>Усі імпорти використовують цільові шляхи `plugin-sdk/<subpath>`</Check>
|
||||
<Check>Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/<subpath>`</Check>
|
||||
<Check>Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK</Check>
|
||||
<Check>Тести проходять (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` проходить (для Plugin-ів у репозиторії)</Check>
|
||||
<Check>`pnpm check` проходить (для Plugin у репозиторії)</Check>
|
||||
|
||||
## Тестування beta-релізів
|
||||
## Тестування beta-релізу
|
||||
|
||||
1. Слідкуйте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів.
|
||||
2. Протестуйте свій Plugin на beta-тегу щойно він з’явиться. Вікно до stable зазвичай становить лише кілька годин.
|
||||
3. Після тестування напишіть у гілці вашого Plugin-а в каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
|
||||
1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів.
|
||||
2. Протестуйте свій Plugin на beta-тезі щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин.
|
||||
3. Після тестування напишіть у гілці вашого Plugin у каналі Discord `plugin-forum`, вказавши або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
|
||||
4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue як у PR, так і у вашій гілці Discord. Учасники не можуть ставити мітки на PR, тому назва є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити в реліз. Під час beta-тестування мейнтейнери стежать за цими гілками.
|
||||
6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить уже в наступний цикл.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue як у PR, так і у вашій гілці Discord. Учасники не можуть ставити мітки PR, тому назва є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR буде змерджено; блокери без нього все одно можуть потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування.
|
||||
6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустите вікно, ваше виправлення, імовірно, потрапить до наступного циклу.
|
||||
|
||||
## Подальші кроки
|
||||
## Наступні кроки
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugins каналів" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Створіть Plugin каналу обміну повідомленнями
|
||||
<Card title="Channel Plugins" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Створіть Plugin каналу повідомлень
|
||||
</Card>
|
||||
<Card title="Plugins провайдерів" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Створіть Plugin провайдера моделей
|
||||
<Card title="Provider Plugins" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Створіть Plugin провайдера моделі
|
||||
</Card>
|
||||
<Card title="Огляд SDK" icon="book-open" href="/uk/plugins/sdk-overview">
|
||||
<Card title="SDK Overview" icon="book-open" href="/uk/plugins/sdk-overview">
|
||||
Карта імпортів і довідник API реєстрації
|
||||
</Card>
|
||||
<Card title="Допоміжні засоби runtime" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
<Card title="Runtime Helpers" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, пошук, subagent через api.runtime
|
||||
</Card>
|
||||
<Card title="Тестування" icon="test-tubes" href="/uk/plugins/sdk-testing">
|
||||
Утиліти та шаблони тестування
|
||||
<Card title="Testing" icon="test-tubes" href="/uk/plugins/sdk-testing">
|
||||
Утиліти й шаблони тестування
|
||||
</Card>
|
||||
<Card title="Маніфест Plugin-а" icon="file-json" href="/uk/plugins/manifest">
|
||||
<Card title="Plugin Manifest" icon="file-json" href="/uk/plugins/manifest">
|
||||
Повний довідник зі схеми маніфесту
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Plugin Architecture](/uk/plugins/architecture) — детальний огляд внутрішньої архітектури
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — довідник SDK Plugin-ів
|
||||
- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin-а
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — глибоке занурення у внутрішню архітектуру
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin
|
||||
- [Manifest](/uk/plugins/manifest) — формат маніфесту Plugin
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin каналів
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin провайдерів
|
||||
|
||||
@ -1,118 +1,87 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати комплектований harness app-server Codex
|
||||
- Вам потрібні приклади конфігурації harness Codex
|
||||
- Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi
|
||||
summary: Запустіть вбудовані ходи агента OpenClaw через комплектований harness app-server Codex
|
||||
title: harness Codex
|
||||
- Ви хочете використовувати вбудований app-server harness Codex
|
||||
- Вам потрібні приклади конфігурації Codex harness
|
||||
- Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу на PI
|
||||
summary: Запускайте вбудовані ходи агента OpenClaw через вбудований app-server harness Codex
|
||||
title: Codex harness
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T21:43:41Z"
|
||||
generated_at: "2026-04-25T00:02:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 674bc34552401d1a492b348ceb86fd513a894760987a0c6fef6e79fdb0b3ebfb
|
||||
source_hash: 366400f3d4018d6149e80b0b87b49ad7332c6164e8b3b70a0c4359068ee2685f
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Комплектований Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через
|
||||
app-server Codex замість вбудованого harness PI.
|
||||
Вбудований Plugin `codex` дає змогу OpenClaw виконувати вбудовані ходи агента через Codex app-server замість вбудованого harness PI.
|
||||
|
||||
Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням
|
||||
моделей, нативним відновленням потоку, нативною Compaction та виконанням app-server.
|
||||
OpenClaw і далі керує каналами чату, файлами сесії, вибором моделі, інструментами,
|
||||
погодженнями, доставкою медіа та видимим дзеркалом транскрипту.
|
||||
Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням thread, нативним Compaction і виконанням app-server.
|
||||
OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделі, tools,
|
||||
approvals, доставкою медіа та видимим дзеркалом transcript.
|
||||
|
||||
Нативні ходи Codex зберігають хука Plugin OpenClaw як публічний шар сумісності.
|
||||
Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`:
|
||||
Нативні ходи Codex зберігають plugin hooks OpenClaw як публічний шар сумісності.
|
||||
Це in-process hooks OpenClaw, а не command hooks Codex `hooks.json`:
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
- `llm_input`, `llm_output`
|
||||
- `after_tool_call`
|
||||
- `before_message_write` для дзеркальних записів транскрипту
|
||||
- `before_message_write` для дзеркальних записів transcript
|
||||
- `agent_end`
|
||||
|
||||
Plugins також можуть реєструвати нейтральне до harness middleware результатів інструментів, щоб переписувати
|
||||
динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того,
|
||||
як результат буде повернено до Codex. Це окремо від публічного
|
||||
хука Plugin `tool_result_persist`, який трансформує записи результатів
|
||||
інструментів у транскрипті, що належать OpenClaw.
|
||||
Plugins також можуть реєструвати runtime-neutral middleware результатів tools, щоб переписувати динамічні результати tools OpenClaw після того, як OpenClaw виконає tool, і до того, як результат буде повернуто до Codex. Це окремо від публічного plugin hook `tool_result_persist`, який перетворює записи результатів tools у transcript, що належать OpenClaw.
|
||||
|
||||
За замовчуванням harness вимкнено. У нових конфігураціях слід зберігати посилання на моделі OpenAI
|
||||
канонічними як `openai/gpt-*` і явно примусово вказувати
|
||||
Harness вимкнено за замовчуванням. Нові конфігурації повинні зберігати canonical ref-и моделей OpenAI як `openai/gpt-*` і явно примусово вказувати
|
||||
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли
|
||||
потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають
|
||||
harness для сумісності, але не показуються як звичайні варіанти моделі/провайдера.
|
||||
потрібне нативне виконання через app-server. Застарілі ref-и моделей `codex/*` і далі автоматично вибирають harness для сумісності, але застарілі provider prefixes, підкріплені runtime, не показуються як звичайні варіанти model/provider.
|
||||
|
||||
## Виберіть правильний префікс моделі
|
||||
|
||||
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете
|
||||
Codex OAuth через PI; використовуйте `openai/*`, коли хочете прямий доступ до OpenAI API або
|
||||
коли примусово використовуєте нативний harness app-server Codex:
|
||||
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібна авторизація Codex OAuth через PI; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або коли ви примусово вмикаєте нативний harness Codex app-server:
|
||||
|
||||
| Посилання на модель | Шлях runtime | Використовуйте, коли |
|
||||
| ---------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до API платформи OpenAI з `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація передплати ChatGPT/Codex із runner PI за замовчуванням. |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. |
|
||||
| Ref моделі | Шлях runtime | Коли використовувати |
|
||||
| ----------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | provider OpenAI через plumbing OpenClaw/PI | Вам потрібен поточний прямий доступ до API OpenAI Platform через `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна авторизація підписки ChatGPT/Codex із runner-ом PI за замовчуванням. |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. |
|
||||
|
||||
GPT-5.5 у OpenClaw наразі доступна лише через передплату/OAuth. Використовуйте
|
||||
`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness
|
||||
app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримуватиметься,
|
||||
щойно OpenAI увімкне GPT-5.5 у публічному API.
|
||||
GPT-5.5 наразі в OpenClaw доступна лише через підписку/OAuth. Використовуйте
|
||||
`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` разом із harness Codex
|
||||
app-server. Прямий доступ через API key для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API.
|
||||
|
||||
Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor
|
||||
міграція сумісності переписує застарілі основні посилання `codex/*` на `openai/*`
|
||||
і окремо записує політику harness Codex. Нові конфігурації PI Codex OAuth
|
||||
мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server
|
||||
мають використовувати `openai/gpt-*` плюс `embeddedHarness.runtime: "codex"`.
|
||||
Застарілі ref-и `codex/gpt-*` залишаються прийнятними як compatibility aliases. Міграція сумісності Doctor переписує застарілі primary runtime ref-и на canonical ref-и моделей і окремо записує policy runtime, тоді як застарілі ref-и лише для fallback залишаються без змін, оскільки runtime налаштовується для всього контейнера агента. Нові конфігурації PI Codex OAuth повинні використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server повинні використовувати `openai/gpt-*` разом із
|
||||
`embeddedHarness.runtime: "codex"`.
|
||||
|
||||
`agents.defaults.imageModel` дотримується такого самого поділу префіксів. Використовуйте
|
||||
`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI
|
||||
Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися
|
||||
через обмежений хід app-server Codex. Модель app-server Codex має
|
||||
оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою до початку
|
||||
медіа-ходу.
|
||||
`agents.defaults.imageModel` дотримується того самого поділу за префіксами. Використовуйте
|
||||
`openai-codex/gpt-*`, коли розпізнавання зображень має виконуватися через шлях provider OpenAI Codex OAuth. Використовуйте `codex/gpt-*`, коли розпізнавання зображень має виконуватися через обмежений хід Codex app-server. Модель Codex app-server повинна заявляти підтримку вхідних зображень; текстові моделі Codex без підтримки зображень завершуються помилкою до початку media turn.
|
||||
|
||||
Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо
|
||||
вибір виглядає несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness`
|
||||
і перегляньте структурований запис шлюзу `agent harness selected`. Він
|
||||
містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback, а також,
|
||||
у режимі `auto`, результат підтримки для кожного кандидата Plugin.
|
||||
Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір здається неочікуваним, увімкніть debug logging для підсистеми `agents/harness` і перегляньте структурований запис gateway `agent harness selected`. Він містить id вибраного harness, причину вибору, policy runtime/fallback і, у режимі `auto`, результат підтримки для кожного plugin-кандидата.
|
||||
|
||||
Вибір harness не є елементом керування живою сесією. Коли вбудований хід виконується,
|
||||
OpenClaw записує ідентифікатор вибраного harness у цій сесії та продовжує використовувати його для
|
||||
наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або
|
||||
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness;
|
||||
використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної
|
||||
розмови між PI та Codex. Це запобігає повторному відтворенню одного транскрипту через
|
||||
дві несумісні нативні системи сесій.
|
||||
Вибір harness не є елементом live-керування сесією. Коли виконується вбудований хід, OpenClaw записує id вибраного harness у цю сесію і продовжує використовувати його для наступних ходів із тим самим id сесії. Змінюйте конфігурацію `embeddedHarness` або
|
||||
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної розмови між PI і Codex. Це дає змогу уникнути повторного програвання одного transcript через дві несумісні нативні системи сесій.
|
||||
|
||||
Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них
|
||||
з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на
|
||||
Codex після зміни конфігурації.
|
||||
Застарілі сесії, створені до появи прив’язки harness, трактуються як прив’язані до PI, щойно вони мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на Codex після зміни конфігурації.
|
||||
|
||||
`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Типовий harness PI і далі відображається як `Runner: pi (embedded)` і
|
||||
не додає окремий бейдж harness.
|
||||
`/status` показує фактичний runtime моделі. Harness PI за замовчуванням відображається як
|
||||
`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як
|
||||
`Runtime: OpenAI Codex`.
|
||||
|
||||
## Вимоги
|
||||
|
||||
- OpenClaw із доступним комплектованим Plugin `codex`.
|
||||
- OpenClaw із доступним вбудованим Plugin `codex`.
|
||||
- Codex app-server `0.118.0` або новіший.
|
||||
- Автентифікація Codex, доступна для процесу app-server.
|
||||
- Авторизація Codex, доступна для процесу app-server.
|
||||
|
||||
Plugin блокує старіші або неверсіоновані handshake app-server. Це залишає
|
||||
OpenClaw на поверхні протоколу, з якою його було протестовано.
|
||||
Plugin блокує старі або неверсіоновані handshake app-server. Це утримує
|
||||
OpenClaw на тій поверхні protocol, з якою його було протестовано.
|
||||
|
||||
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також з
|
||||
необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і
|
||||
`~/.codex/config.toml`. Використовуйте той самий матеріал автентифікації, що й ваш локальний
|
||||
app-server Codex.
|
||||
Для live- і Docker smoke-тестів авторизація зазвичай надходить із `OPENAI_API_KEY`, а також, за потреби, з файлів Codex CLI, таких як `~/.codex/auth.json` і
|
||||
`~/.codex/config.toml`. Використовуйте ті самі матеріали авторизації, що й ваш локальний Codex app-server.
|
||||
|
||||
## Мінімальна конфігурація
|
||||
|
||||
Використовуйте `openai/gpt-5.5`, увімкніть комплектований Plugin і примусово вкажіть harness `codex`:
|
||||
Використовуйте `openai/gpt-5.5`, увімкніть вбудований plugin і примусово виберіть harness `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -135,7 +104,7 @@ app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ваша конфігурація використовує `plugins.allow`, включіть туди також `codex`:
|
||||
Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -150,15 +119,12 @@ app-server Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента на
|
||||
`codex/<model>`, усе ще автоматично вмикають комплектований Plugin `codex`. У нових конфігураціях слід
|
||||
надавати перевагу `openai/<model>` плюс явному запису `embeddedHarness`, наведеному вище.
|
||||
Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в
|
||||
`codex/<model>`, і далі автоматично вмикають вбудований plugin `codex`. Нові конфігурації повинні надавати перевагу `openai/<model>` разом із явним записом `embeddedHarness`, наведеним вище.
|
||||
|
||||
## Додайте Codex без заміни інших моделей
|
||||
|
||||
Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а
|
||||
PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для
|
||||
агентів, які мають використовувати harness.
|
||||
Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі ref-и `codex/*` вибирали Codex, а для всього іншого використовувався PI. Для нових конфігурацій краще явно задавати `runtime: "codex"` для агентів, які мають використовувати harness.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -188,16 +154,16 @@ PI — для всього іншого. Для нових конфігурац
|
||||
}
|
||||
```
|
||||
|
||||
За такої форми:
|
||||
У такій конфігурації:
|
||||
|
||||
- `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації.
|
||||
- `/model opus` використовує шлях провайдера Anthropic.
|
||||
- Якщо вибрано не-Codex модель, PI залишається harness сумісності.
|
||||
- `/model gpt` або `/model openai/gpt-5.5` використовує harness Codex app-server для цієї конфігурації.
|
||||
- `/model opus` використовує шлях provider Anthropic.
|
||||
- Якщо вибрано модель не з Codex, PI залишається harness сумісності.
|
||||
|
||||
## Розгортання лише з Codex
|
||||
|
||||
Примусово використовуйте harness Codex, коли потрібно довести, що кожен вбудований хід агента
|
||||
використовує Codex. Явні runtime Plugin за замовчуванням не мають fallback до PI, тому
|
||||
Примусово вмикайте harness Codex, коли потрібно довести, що кожен вбудований хід агента
|
||||
використовує Codex. Явно задані plugin runtime за замовчуванням не мають fallback до PI, тому
|
||||
`fallback: "none"` необов’язковий, але часто корисний як документація:
|
||||
|
||||
```json5
|
||||
@ -214,20 +180,18 @@ PI — для всього іншого. Для нових конфігурац
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення через середовище:
|
||||
Перевизначення через змінну середовища:
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
|
||||
```
|
||||
|
||||
Коли Codex примусово увімкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено,
|
||||
app-server застарий або app-server не може запуститися. Встановлюйте
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв
|
||||
відсутній вибір harness.
|
||||
Коли Codex примусово увімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо plugin Codex вимкнено, app-server надто старий або app-server не може запуститися. Установлюйте
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв відсутній вибір harness.
|
||||
|
||||
## Codex для окремого агента
|
||||
|
||||
Ви можете зробити одного агента лише-Codex, тоді як агент за замовчуванням зберігатиме звичайний
|
||||
Ви можете зробити один агент лише з Codex, тоді як агент за замовчуванням зберігатиме звичайний
|
||||
автовибір:
|
||||
|
||||
```json5
|
||||
@ -259,15 +223,12 @@ app-server застарий або app-server не може запуститис
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову
|
||||
сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server
|
||||
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку
|
||||
і дозволяє наступному ходу знову визначити harness з поточної конфігурації.
|
||||
Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову сесію OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього thread і дає змогу наступному ходу знову визначити harness із поточної конфігурації.
|
||||
|
||||
## Виявлення моделей
|
||||
|
||||
За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо
|
||||
виявлення не вдається або завершується за тайм-аутом, використовується комплектований резервний каталог для:
|
||||
За замовчуванням plugin Codex запитує в app-server список доступних моделей. Якщо
|
||||
виявлення завершується помилкою або спрацьовує timeout, використовується вбудований fallback catalog для:
|
||||
|
||||
- GPT-5.5
|
||||
- GPT-5.4 mini
|
||||
@ -293,8 +254,7 @@ app-server застарий або app-server не може запуститис
|
||||
}
|
||||
```
|
||||
|
||||
Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося зондування Codex і використовувався
|
||||
резервний каталог:
|
||||
Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося опитування Codex і використовувався лише fallback catalog:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -313,9 +273,9 @@ app-server застарий або app-server не може запуститис
|
||||
}
|
||||
```
|
||||
|
||||
## Підключення до app-server і політика
|
||||
## Підключення до app-server і policy
|
||||
|
||||
За замовчуванням Plugin запускає Codex локально так:
|
||||
За замовчуванням plugin локально запускає Codex так:
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
@ -323,11 +283,9 @@ codex app-server --listen stdio://
|
||||
|
||||
За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
|
||||
`approvalPolicy: "never"`, `approvalsReviewer: "user"` і
|
||||
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується
|
||||
для автономних Heartbeat: Codex може використовувати shell- і мережеві інструменти, не
|
||||
зупиняючись на нативних запитах погодження, коли нікому відповісти.
|
||||
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується для автономних Heartbeat: Codex може використовувати shell і network tools без зупинки на нативних approval prompts, на які нікому відповідати.
|
||||
|
||||
Щоб увімкнути погодження Codex, перевірені guardian, установіть `appServer.mode:
|
||||
Щоб увімкнути approvals Codex із перевіркою guardian, установіть `appServer.mode:
|
||||
"guardian"`:
|
||||
|
||||
```json5
|
||||
@ -348,9 +306,9 @@ codex app-server --listen stdio://
|
||||
}
|
||||
```
|
||||
|
||||
Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти за межі sandbox, записати поза межами workspace або додати дозволи, як-от мережевий доступ, Codex надсилає цей запит на погодження рецензенту-субагенту, а не людині через prompt. Рецензент застосовує модель ризиків Codex і погоджує або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але при цьому потрібно, щоб агенти без нагляду продовжували роботу.
|
||||
Guardian — це нативний reviewer approvals у Codex. Коли Codex просить вийти за межі sandbox, записати поза workspace або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на approval до subagent reviewer, а не до prompt для людини. Reviewer застосовує framework ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші запобіжники, ніж у режимі YOLO, але водночас потрібно, щоб unattended agents могли просуватися далі.
|
||||
|
||||
Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики й далі мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати пресет із явними налаштуваннями.
|
||||
Preset `guardian` розгортається до `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля policy і далі мають вищий пріоритет за `mode`, тому просунуті розгортання можуть поєднувати preset із явними налаштуваннями.
|
||||
|
||||
Для вже запущеного app-server використовуйте транспорт WebSocket:
|
||||
|
||||
@ -376,23 +334,23 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
|
||||
Підтримувані поля `appServer`:
|
||||
|
||||
| Поле | Типове значення | Значення |
|
||||
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
|
||||
| `command` | `"codex"` | Виконуваний файл для транспорту stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
|
||||
| `url` | не встановлено | URL WebSocket app-server. |
|
||||
| `authToken` | не встановлено | Bearer token для транспорту WebSocket. |
|
||||
| `headers` | `{}` | Додаткові заголовки WebSocket. |
|
||||
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. |
|
||||
| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. |
|
||||
| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час запуску/відновлення потоку/ходу. |
|
||||
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. |
|
||||
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти prompt. |
|
||||
| `serviceTier` | не встановлено | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Неприпустимі застарілі значення ігноруються. |
|
||||
| Поле | За замовчуванням | Значення |
|
||||
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
|
||||
| `command` | `"codex"` | Виконуваний файл для транспорту stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
|
||||
| `url` | не задано | URL WebSocket app-server. |
|
||||
| `authToken` | не задано | Bearer token для транспорту WebSocket. |
|
||||
| `headers` | `{}` | Додаткові заголовки WebSocket. |
|
||||
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. |
|
||||
| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з approvals, перевіреними guardian. |
|
||||
| `approvalPolicy` | `"never"` | Нативна policy approvals Codex, що надсилається під час start/resume/turn thread. |
|
||||
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час start/resume thread. |
|
||||
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти prompts. |
|
||||
| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
|
||||
|
||||
Старіші змінні середовища й далі працюють як fallback для локального тестування, коли
|
||||
відповідне поле конфігурації не встановлено:
|
||||
Старіші змінні середовища все ще працюють як fallback для локального тестування, коли
|
||||
відповідне поле конфігурації не задане:
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
|
||||
@ -400,15 +358,14 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
|
||||
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"` або
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурації
|
||||
надається перевага для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin в тому
|
||||
самому перевіреному файлі, що й решта налаштувань harness Codex.
|
||||
слід надавати перевагу для відтворюваних розгортань, оскільки вона зберігає поведінку plugin в тому самому перевіреному файлі, що й решта налаштувань harness Codex.
|
||||
|
||||
## Поширені рецепти
|
||||
## Типові рецепти
|
||||
|
||||
Локальний Codex із типовим транспортом stdio:
|
||||
Локальний Codex із transport stdio за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -422,7 +379,7 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Перевірка harness лише-Codex із вимкненим fallback до PI:
|
||||
Валідація harness лише для Codex, з вимкненим fallback до PI:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -439,7 +396,7 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Погодження Codex із перевіркою guardian:
|
||||
Approvals Codex із перевіркою guardian:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -461,7 +418,7 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Віддалений app-server з явними заголовками:
|
||||
Віддалений app-server із явними заголовками:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -484,100 +441,87 @@ Guardian — це нативний рецензент погоджень Codex.
|
||||
}
|
||||
```
|
||||
|
||||
Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw прив’язано
|
||||
до наявного потоку Codex, наступний хід знову надсилає до
|
||||
app-server поточну вибрану модель OpenAI, провайдера, політику погодження, sandbox і
|
||||
service tier. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає
|
||||
прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю.
|
||||
Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано
|
||||
до наявного thread Codex, наступний хід знову надсилає до
|
||||
app-server поточні вибрані модель OpenAI, provider, policy approvals, sandbox і service tier.
|
||||
Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до
|
||||
thread, але просить Codex продовжити з новою вибраною моделлю.
|
||||
|
||||
## Команда Codex
|
||||
|
||||
Комплектований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є
|
||||
загальною та працює в будь-якому каналі, який підтримує текстові команди OpenClaw.
|
||||
Вбудований plugin реєструє `/codex` як авторизовану slash-команду. Вона
|
||||
є загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw.
|
||||
|
||||
Поширені форми:
|
||||
|
||||
- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills.
|
||||
- `/codex models` показує список живих моделей app-server Codex.
|
||||
- `/codex threads [filter]` показує список нещодавніх потоків Codex.
|
||||
- `/codex resume <thread-id>` прив’язує поточну сесію OpenClaw до наявного потоку Codex.
|
||||
- `/codex compact` просить app-server Codex виконати compaction для прив’язаного потоку.
|
||||
- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку.
|
||||
- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP servers і skills.
|
||||
- `/codex models` показує список поточних моделей Codex app-server.
|
||||
- `/codex threads [filter]` показує список нещодавніх thread-ів Codex.
|
||||
- `/codex resume <thread-id>` приєднує поточну сесію OpenClaw до наявного thread Codex.
|
||||
- `/codex compact` просить Codex app-server виконати Compaction для приєднаного thread.
|
||||
- `/codex review` запускає нативний review Codex для приєднаного thread.
|
||||
- `/codex account` показує стан облікового запису та лімітів швидкості.
|
||||
- `/codex mcp` показує список станів MCP-серверів app-server Codex.
|
||||
- `/codex skills` показує список Skills app-server Codex.
|
||||
- `/codex mcp` показує список станів MCP server у Codex app-server.
|
||||
- `/codex skills` показує список skills Codex app-server.
|
||||
|
||||
`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для
|
||||
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає
|
||||
поточну вибрану модель OpenClaw до app-server і зберігає розширену історію
|
||||
увімкненою.
|
||||
`/codex resume` записує той самий sidecar binding file, який harness використовує для
|
||||
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає
|
||||
поточну вибрану модель OpenClaw до app-server і залишає розширену історію увімкненою.
|
||||
|
||||
Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі
|
||||
методи керування позначаються як `unsupported by this Codex app-server`, якщо
|
||||
майбутній або кастомний app-server не надає цей JSON-RPC метод.
|
||||
майбутній або кастомний app-server не надає цей метод JSON-RPC.
|
||||
|
||||
## Межі хуків
|
||||
## Межі hooks
|
||||
|
||||
Harness Codex має три шари хуків:
|
||||
Harness Codex має три шари hooks:
|
||||
|
||||
| Шар | Власник | Призначення |
|
||||
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
|
||||
| хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. |
|
||||
| middleware розширення app-server Codex | комплектовані Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. |
|
||||
| нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. |
|
||||
| Шар | Власник | Призначення |
|
||||
| ------------------------------------ | ------------------------ | ------------------------------------------------------------------- |
|
||||
| OpenClaw plugin hooks | OpenClaw | Сумісність продукту/plugin між harness PI та Codex. |
|
||||
| middleware розширення Codex app-server | Вбудовані plugins OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних tools OpenClaw. |
|
||||
| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і policy нативних tools з конфігурації Codex. |
|
||||
|
||||
OpenClaw не використовує файли проєктного або глобального Codex `hooks.json` для маршрутизації
|
||||
поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій,
|
||||
що належать Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та
|
||||
нативна Compaction/життєвий цикл моделі, але вони не є API Plugin OpenClaw.
|
||||
OpenClaw не використовує project або global файли Codex `hooks.json` для маршрутизації
|
||||
поведінки plugin OpenClaw. Нативні hooks Codex корисні для операцій, що належать Codex,
|
||||
як-от policy shell, перевірка результатів нативних tools, обробка зупинки та нативний життєвий цикл Compaction/моделі, але вони не є API plugin OpenClaw.
|
||||
|
||||
Для динамічних інструментів OpenClaw, OpenClaw виконує інструмент після того, як Codex запитує
|
||||
виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у
|
||||
адаптері harness. Для нативних інструментів Codex саме Codex володіє канонічним записом інструмента.
|
||||
OpenClaw може віддзеркалювати окремі події, але не може переписати нативний потік Codex,
|
||||
якщо тільки Codex не надає цю операцію через app-server або нативні callback-хуки.
|
||||
Для динамічних tools OpenClaw сам виконує tool після того, як Codex запитує
|
||||
виклик, тому OpenClaw запускає поведінку plugin і middleware, якою він володіє, у
|
||||
адаптері harness. Для нативних tools Codex саме Codex володіє canonical record tool.
|
||||
OpenClaw може дзеркалювати окремі події, але не може переписувати нативний thread Codex,
|
||||
якщо Codex не надає цю операцію через app-server або callbacks нативних hooks.
|
||||
|
||||
Коли новіші збірки app-server Codex надаватимуть події хуків нативної Compaction і життєвого циклу моделі,
|
||||
OpenClaw має з урахуванням версії протоколу вмикати цю підтримку та зіставляти
|
||||
події з наявним контрактом хуків OpenClaw там, де семантика є коректною.
|
||||
Коли новіші збірки Codex app-server почнуть надавати події hooks життєвого циклу нативних Compaction і моделі, OpenClaw має обмежувати підтримку цього protocol за версією та відображати ці події в наявний контракт hooks OpenClaw там, де семантика є чесною.
|
||||
До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і
|
||||
`llm_output` є спостереженнями на рівні адаптера, а не побайтними копіями
|
||||
`llm_output` є спостереженнями на рівні адаптера, а не побайтовими копіями
|
||||
внутрішнього запиту Codex або payload Compaction.
|
||||
|
||||
Нативні сповіщення app-server Codex `hook/started` і `hook/completed`
|
||||
проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження.
|
||||
Вони не викликають хуки Plugin OpenClaw.
|
||||
Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як
|
||||
події агента `codex_app_server.hook` для траєкторії та налагодження.
|
||||
Вони не викликають plugin hooks OpenClaw.
|
||||
|
||||
## Інструменти, медіа та Compaction
|
||||
## Tools, медіа та Compaction
|
||||
|
||||
Harness Codex змінює лише низькорівневий виконавець вбудованого агента.
|
||||
|
||||
OpenClaw і далі формує список інструментів і отримує результати динамічних інструментів від
|
||||
harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень
|
||||
OpenClaw, як і раніше, будує список tools і отримує динамічні результати tools від
|
||||
harness. Текст, зображення, відео, музика, TTS, approvals і вивід tools для повідомлень
|
||||
і далі проходять звичайним шляхом доставки OpenClaw.
|
||||
|
||||
Запити погодження інструментів Codex MCP маршрутизуються через потік погодження Plugin
|
||||
OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
|
||||
`"mcp_tool_call"`. Prompt Codex `request_user_input` надсилаються назад у
|
||||
початковий чат, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний
|
||||
запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP
|
||||
і далі завершуються за принципом fail closed.
|
||||
Запити на approvals для MCP tool у Codex маршрутизуються через flow approvals plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
|
||||
`"mcp_tool_call"`. Prompts Codex `request_user_input` надсилаються назад до
|
||||
початкового чату, а наступне повідомлення в черзі відповідає на цей нативний
|
||||
запит server, а не спрямовується як додатковий контекст. Інші запити MCP elicitation і далі завершуються в закритому режимі.
|
||||
|
||||
Коли вибрана модель використовує harness Codex, нативна Compaction потоку делегується
|
||||
app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу,
|
||||
пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало
|
||||
містить prompt користувача, фінальний текст помічника та полегшені записи міркувань або
|
||||
плану Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали
|
||||
початку та завершення нативної Compaction. Він ще не надає зрозумілого для людини
|
||||
зведення Compaction або придатного до аудиту списку того, які записи Codex
|
||||
зберіг після Compaction.
|
||||
Коли вибрана модель використовує harness Codex, нативний Compaction thread делегується Codex app-server. OpenClaw зберігає дзеркало transcript для історії каналів, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало містить prompt користувача, фінальний текст асистента та полегшені записи reasoning або plan Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали початку та завершення нативного Compaction. Він ще не показує зрозумілий для людини підсумок Compaction або список для аудиту, які саме записи Codex зберіг після Compaction.
|
||||
|
||||
Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не
|
||||
переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли
|
||||
OpenClaw записує результат інструмента в транскрипт сесії, що належить OpenClaw.
|
||||
Оскільки Codex володіє canonical нативним thread, `tool_result_persist` наразі не
|
||||
переписує записи результатів нативних tools Codex. Він застосовується лише тоді, коли
|
||||
OpenClaw записує результат tool у transcript сесії, що належить OpenClaw.
|
||||
|
||||
Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і
|
||||
розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як
|
||||
Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і
|
||||
розпізнавання медіа й далі використовують відповідні налаштування provider/моделі, як-от
|
||||
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і
|
||||
`messages.tts`.
|
||||
|
||||
@ -585,14 +529,14 @@ OpenClaw записує результат інструмента в транс
|
||||
|
||||
**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`,
|
||||
виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або
|
||||
застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`.
|
||||
застарілий ref `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`.
|
||||
|
||||
**OpenClaw використовує PI замість Codex:** `runtime: "auto"` усе ще може використовувати PI як
|
||||
бекенд сумісності, коли жоден harness Codex не бере виконання на себе. Установіть
|
||||
**OpenClaw використовує PI замість Codex:** `runtime: "auto"` все ще може використовувати PI як
|
||||
backend сумісності, коли жоден harness Codex не заявляє про цей запуск. Установіть
|
||||
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер
|
||||
примусовий runtime Codex завершується з помилкою замість fallback до PI, якщо ви
|
||||
явно не встановите `embeddedHarness.fallback: "pi"`. Щойно вибрано app-server Codex,
|
||||
його збої проявляються безпосередньо без додаткової конфігурації fallback.
|
||||
примусовий runtime Codex завершується помилкою замість fallback до PI, якщо ви
|
||||
явно не встановили `embeddedHarness.fallback: "pi"`. Щойно буде вибрано Codex app-server,
|
||||
його помилки надходитимуть безпосередньо без додаткової конфігурації fallback.
|
||||
|
||||
**app-server відхиляється:** оновіть Codex, щоб handshake app-server
|
||||
повідомляв версію `0.118.0` або новішу.
|
||||
@ -600,16 +544,16 @@ OpenClaw записує результат інструмента в транс
|
||||
**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
або вимкніть виявлення.
|
||||
|
||||
**Транспорт WebSocket відразу завершується з помилкою:** перевірте `appServer.url`, `authToken`,
|
||||
і що віддалений app-server використовує ту саму версію протоколу app-server Codex.
|
||||
**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken`
|
||||
і те, що віддалений app-server використовує ту саму версію protocol Codex app-server.
|
||||
|
||||
**Не-Codex модель використовує PI:** це очікувано, якщо ви не примусово встановили
|
||||
`embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні
|
||||
`openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному шляху провайдера.
|
||||
**Модель не з Codex використовує PI:** це очікувано, якщо ви не примусово задали
|
||||
`embeddedHarness.runtime: "codex"` (або не вибрали застарілий ref `codex/*`). Звичайні
|
||||
`openai/gpt-*` та ref-и інших provider залишаються на своєму звичайному шляху provider.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Plugins Harness агента](/uk/plugins/sdk-agent-harness)
|
||||
- [Провайдери моделей](/uk/concepts/model-providers)
|
||||
- [Providers моделей](/uk/concepts/model-providers)
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference)
|
||||
- [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,53 +1,53 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте Plugin для OpenClaw
|
||||
- Вам потрібно надати schema конфігурації Plugin або налагодити помилки валідації Plugin
|
||||
summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації)
|
||||
title: маніфест Plugin
|
||||
- Ви створюєте plugin для OpenClaw
|
||||
- Вам потрібно постачити схему конфігурації plugin або налагодити помилки валідації plugin
|
||||
summary: Маніфест Plugin + вимоги до схеми JSON (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T22:21:56Z"
|
||||
generated_at: "2026-04-25T00:02:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ddabd562db22a82ff9c46094248350ac30565c9c10c9d87d3c0e85d49e7044a9
|
||||
source_hash: 750878abda22dbc270483b2c6a32ba0918bce0beaf66f1d209bb226289ffd42a
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**.
|
||||
Ця сторінка стосується лише **рідного маніфесту plugin OpenClaw**.
|
||||
|
||||
Сумісні компонування bundle дивіться в [Plugin bundles](/uk/plugins/bundles).
|
||||
Сумісні макети пакетів див. у [Пакети plugin](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати bundle використовують інші файли маніфесту:
|
||||
Сумісні формати пакетів використовують інші файли маніфесту:
|
||||
|
||||
- Codex bundle: `.codex-plugin/plugin.json`
|
||||
- Claude bundle: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту
|
||||
- Cursor bundle: `.cursor-plugin/plugin.json`
|
||||
- Пакет Codex: `.codex-plugin/plugin.json`
|
||||
- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude без маніфесту
|
||||
- Пакет Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично визначає ці компонування bundle, але вони не проходять валідацію за schema `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені корені skills, корені команд Claude, типові значення `settings.json` для Claude bundle, типові значення LSP для Claude bundle і підтримувані набори hook, коли компонування відповідає очікуванням середовища виконання OpenClaw.
|
||||
Для сумісних пакетів OpenClaw наразі читає метадані пакета плюс оголошені корені skill, корені команд Claude, типові значення `settings.json` пакета Claude, типові значення LSP пакета Claude і підтримувані набори hook, коли макет відповідає очікуванням runtime OpenClaw.
|
||||
|
||||
Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються помилками Plugin і блокують валідацію конфігурації.
|
||||
Кожен рідний plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду plugin**. Відсутні або недійсні маніфести вважаються помилками plugin і блокують валідацію конфігурації.
|
||||
|
||||
Дивіться повний посібник по системі Plugin: [Plugins](/uk/tools/plugin).
|
||||
Щодо власної моделі capability та поточних рекомендацій із зовнішньої сумісності:
|
||||
[Модель capability](/uk/plugins/architecture#public-capability-model).
|
||||
Повний посібник із системи plugin див. у [Plugins](/uk/tools/plugin).
|
||||
Для рідної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску runtime Plugin.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду вашого plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску runtime plugin.
|
||||
|
||||
**Використовуйте його для:**
|
||||
|
||||
- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації
|
||||
- метаданих auth, onboarding і setup (alias, auto-enable, змінні середовища provider, варіанти auth)
|
||||
- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації
|
||||
- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації)
|
||||
- підказок активації для поверхонь control plane
|
||||
- скороченого володіння model-family
|
||||
- статичних знімків володіння capability (`contracts`)
|
||||
- скороченого володіння сімействами моделей
|
||||
- статичних знімків володіння можливостями (`contracts`)
|
||||
- метаданих QA runner, які може перевіряти спільний хост `openclaw qa`
|
||||
- метаданих конфігурації для конкретних channel, що об’єднуються в поверхні каталогу та валідації
|
||||
- метаданих конфігурації, специфічних для каналу, об’єднаних у каталог і поверхні валідації
|
||||
|
||||
**Не використовуйте його для:** реєстрації поведінки runtime, оголошення code entrypoint або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`.
|
||||
**Не використовуйте його для:** реєстрації поведінки runtime, оголошення точок входу коду або метаданих встановлення npm. Це належить вашому коду plugin і `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -62,7 +62,7 @@ OpenClaw також автоматично визначає ці компону
|
||||
}
|
||||
```
|
||||
|
||||
## Розширений приклад
|
||||
## Розгорнутий приклад
|
||||
|
||||
```json
|
||||
{
|
||||
@ -127,67 +127,67 @@ OpenClaw також автоматично визначає ці компону
|
||||
|
||||
## Довідник полів верхнього рівня
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний id Plugin. Це id, що використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Пропустіть його або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався типово вимкненим. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id provider, які повинні автоматично вмикати цей Plugin, коли auth, config або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | id channel, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | id provider, якими володіє цей Plugin. |
|
||||
| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагого модуля виявлення provider, відносно кореня Plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного runtime Plugin. |
|
||||
| `modelSupport` | Ні | `object` | Короткі метадані model-family, що належать маніфесту і використовуються для автозавантаження Plugin до запуску runtime. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl endpoint, що належать маніфесту, для маршрутів provider, які core має класифікувати до завантаження runtime provider. |
|
||||
| `cliBackends` | Ні | `string[]` | id backend CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у config. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook auth, що належить Plugin, під час cold discovery моделей до завантаження runtime. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential state. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які повинні формувати діагностику config та CLI з урахуванням Plugin до завантаження runtime. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Застарілі сумісні метадані env для пошуку auth/status provider. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом періоду deprecation. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | id provider, які повинні повторно використовувати інший id provider для пошуку auth, наприклад provider для кодування, що використовує той самий API key базового provider і профілі auth. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Легковагі метадані env для channel, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для setup channel на основі env або поверхонь auth, які мають бачити загальні helper запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Легковагі метадані варіантів auth для селекторів onboarding, визначення preferred provider і простого зв’язування прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Легковагі метадані планувальника активації для завантаження за тригерами provider, command, channel, route і capability. Лише метадані; фактичною поведінкою все ще володіє runtime Plugin. |
|
||||
| `setup` | Ні | `object` | Легковагі дескриптори setup/onboarding, які поверхні discovery та setup можуть перевіряти без завантаження runtime Plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Легковагі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime Plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок bundled capability для зовнішніх hook auth, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tool. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Легковагі типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації channel, що належать маніфесту і об’єднуються в поверхні discovery та валідації до завантаження runtime. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. |
|
||||
| `name` | Ні | `string` | Зрозуміла людині назва Plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія Plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | UI-мітки, placeholders і підказки щодо чутливості для полів конфігурації. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, що використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений типово. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin типово залишався вимкненим. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип plugin, що використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей plugin. |
|
||||
| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера відносно кореня plugin для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime plugin. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автозавантаження plugin до runtime. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів виведення CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску з явних посилань конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або бекенд CLI, для яких синтетичний hook автентифікації, яким володіє plugin, слід перевіряти під час холодного виявлення моделі до завантаження runtime. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення API-ключів-заповнювачів, якими володіє вбудований plugin і які позначають несекретний локальний стан, OAuth або стан ambient credential. |
|
||||
| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей plugin і які мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження runtime. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Застарілі сумісні метадані змінних середовища для пошуку автентифікації/стану провайдера. Для нових plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом періоду знецінення. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding provider, що ділить API-ключ і профілі автентифікації базового провайдера. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Полегшені метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити загальні helper. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для селекторів онбордингу, визначення бажаного провайдера та простого підключення прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою все ще керує runtime plugin. |
|
||||
| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження runtime plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого пакета для зовнішніх hook автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Полегшені типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження runtime. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження відносно кореня plugin. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант onboarding або auth.
|
||||
OpenClaw зчитує це до завантаження runtime provider.
|
||||
Потік setup provider надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard runtime і варіантів install-catalog.
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw читає це до завантаження runtime провайдера.
|
||||
Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard runtime і варіантів каталогу встановлення.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | id provider, до якого належить цей варіант. |
|
||||
| `method` | Так | `string` | id методу auth, до якого слід спрямувати. |
|
||||
| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується потоками onboarding і CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Видима для користувача мітка. Якщо пропущено, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які повинні перенаправляти користувачів до цього варіанта-замінника. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Видима для користувача мітка цієї групи. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. |
|
||||
| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. |
|
||||
| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. |
|
||||
| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей замінний варіант. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. |
|
||||
| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
|
||||
|
||||
## Довідник `commandAliases`
|
||||
|
||||
Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime Plugin.
|
||||
Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -201,22 +201,22 @@ OpenClaw зчитує це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, що належить цьому Plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, що належить цьому plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. |
|
||||
|
||||
## Довідник `activation`
|
||||
|
||||
Використовуйте `activation`, коли Plugin може з мінімальними витратами оголосити, які події control plane мають включати його до плану активації/завантаження.
|
||||
Використовуйте `activation`, коли plugin може дешево оголосити, які події control plane мають включати його в план активації/завантаження.
|
||||
|
||||
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не гарантує, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів Plugin, перш ніж повертатися до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hook.
|
||||
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не гарантує, що код plugin уже було виконано. Планувальник активації використовує ці поля, щоб звузити коло кандидатів plugin, перш ніж повертатися до наявних метаданих володіння маніфестом, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hook.
|
||||
|
||||
Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які неможливо подати через ці поля володіння.
|
||||
Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна подати через ці поля володіння.
|
||||
|
||||
Цей блок містить лише метадані. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` чи інші runtime/entrypoint Plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження кола перед ширшим завантаженням Plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі fallback-механізми володіння з маніфесту.
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тож відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі резервні варіанти володіння маніфестом.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -230,29 +230,29 @@ OpenClaw зчитує це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | id provider, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCommands` | Ні | `string[]` | id команд, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onChannels` | Ні | `string[]` | id channel, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи route, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin у плани активації/завантаження. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin у плани активації/завантаження. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей plugin у плани активації/завантаження. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin у плани активації/завантаження. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються під час планування активації control plane. За можливості надавайте перевагу вужчим полям. |
|
||||
|
||||
Поточні live-споживачі:
|
||||
Поточні живі споживачі:
|
||||
|
||||
- планування CLI, запущене командою, повертається до застарілих
|
||||
- CLI-планування, запущене командою, повертається до застарілих
|
||||
`commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- setup/channel planning, запущене channel, повертається до застарілого
|
||||
володіння `channels[]`, коли явні метадані активації channel відсутні
|
||||
- setup/runtime planning, запущене provider, повертається до застарілого
|
||||
володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні
|
||||
метадані активації provider відсутні
|
||||
- setup/channel-планування, запущене каналом, повертається до застарілого
|
||||
володіння `channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- setup/runtime-планування, запущене провайдером, повертається до застарілого
|
||||
володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані
|
||||
активації провайдера відсутні
|
||||
|
||||
Діагностика планувальника може розрізняти явні підказки активації та fallback за володінням у маніфесті. Наприклад, `activation-command-hint` означає, що спрацював збіг `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста і тестів; авторам Plugin слід і надалі оголошувати метадані, які найкраще описують володіння.
|
||||
Діагностика планувальника може розрізняти явні підказки активації та резервне використання володіння маніфестом. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста й тестів; авторам plugin слід і надалі оголошувати ті метадані, які найкраще описують володіння.
|
||||
|
||||
## Довідник `qaRunners`
|
||||
|
||||
Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner у спільному корені `openclaw qa`. Зберігайте ці метадані легковагими та статичними; фактичною реєстрацією CLI все ще володіє runtime Plugin через легковагу поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
Використовуйте `qaRunners`, коли plugin додає один або більше transport runner у межах спільного кореня `openclaw qa`. Зберігайте ці метадані дешевими та статичними; фактичною реєстрацією CLI все ще керує runtime plugin через полегшену поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -265,14 +265,14 @@ OpenClaw зчитує це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ------------- | ----------- | -------- | ------------------------------------------------------------------------------ |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна команда-заглушка. |
|
||||
|
||||
## Довідник `setup`
|
||||
|
||||
Використовуйте `setup`, коли поверхням setup і onboarding потрібні легковагі метадані Plugin до завантаження runtime.
|
||||
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, якими володіє plugin, до завантаження runtime.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -291,38 +291,42 @@ OpenClaw зчитує це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
`cliBackends` верхнього рівня залишається чинним і далі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які повинні залишатися лише метаданими.
|
||||
`cliBackends` верхнього рівня залишається чинним і надалі описує бекенди виведення CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими.
|
||||
|
||||
За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку setup у стилі descriptor-first для discovery setup. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших runtime-hook на етапі setup, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
|
||||
За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. Якщо дескриптор лише звужує plugin-кандидат, а setup все ще потребує багатших hook runtime під час налаштування, встановіть `requiresRuntime: true` і збережіть `setup-api` як резервний шлях виконання.
|
||||
|
||||
OpenClaw також включає `setup.providers[].envVars` у загальні пошуки auth provider і env var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду deprecation, але невбудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin повинні розміщувати метадані env для setup/status у `setup.providers[].envVars`.
|
||||
OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації провайдера та змінних середовища.
|
||||
`providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду знецінення, але plugin не з пакета, які все ще його використовують, отримують діагностику маніфесту. Нові plugin мають розміщувати метадані env для setup/status у `setup.providers[].envVars`.
|
||||
|
||||
Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що працює лише на дескрипторах, усе ж містить один із цих runtime-entry setup, OpenClaw повідомляє про додаткову діагностику і продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу fallback-поведінку, щоб не ламати наявні Plugin, які додали дескриптори без цього прапорця.
|
||||
OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` означає, що runtime setup не потрібен.
|
||||
Явні записи `providerAuthChoices` усе ще мають пріоритет для власних міток, прапорців CLI, області онбордингу та метаданих асистента.
|
||||
|
||||
Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених Plugin. Неоднозначне володіння закривається з відмовою, замість того щоб обирати переможця за порядком discovery.
|
||||
Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише з дескрипторами й не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо plugin, що працює лише через дескриптори, усе ж постачає одну з цих точок входу runtime setup, OpenClaw повідомляє додаткову діагностику і продовжує її ігнорувати. Пропущене `requiresRuntime` зберігає застарілу поведінку резервного варіанта, щоб наявні plugin, які додали дескриптори без цього прапорця, не ламалися.
|
||||
|
||||
Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження descriptor, якщо `setup-api` реєструє provider або backend CLI, який не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими й не призводять до відхилення застарілих Plugin.
|
||||
Оскільки пошук setup може виконувати код `setup-api`, яким володіє plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених plugin. Неоднозначне володіння завершується в закритому режимі замість вибору переможця за порядком виявлення.
|
||||
|
||||
Коли runtime setup таки виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено дескрипторами маніфесту, або якщо дескриптор не має відповідної реєстрації runtime. Ці діагностики є додатковими й не відхиляють застарілі plugin.
|
||||
|
||||
### Довідник `setup.providers`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | id provider, доступний під час setup або onboarding. Зберігайте нормалізовані id глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | id методів setup/auth, які цей provider підтримує без завантаження повного runtime. |
|
||||
| `envVars` | Ні | `string[]` | Env var, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або онбордингу. Нормалізовані ідентифікатори мають залишатися глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. |
|
||||
| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. |
|
||||
|
||||
### Поля `setup`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та onboarding. |
|
||||
| `cliBackends` | Ні | `string[]` | id backend, що використовуються під час setup для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані id глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | id міграцій config, якими володіє поверхня setup цього Plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
|
||||
| Поле | Обов’язкове | Тип | Що це означає |
|
||||
| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори setup провайдера, що відкриваються під час setup і онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Нормалізовані ідентифікатори мають залишатися глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи setup усе ще потребує виконання `setup-api` після пошуку за дескриптором. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
`uiHints` — це мапа від назв полів config до невеликих підказок для рендерингу.
|
||||
`uiHints` — це відображення імен полів конфігурації на невеликі підказки рендерингу.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -337,25 +341,25 @@ OpenClaw також включає `setup.providers[].envVars` у загальн
|
||||
}
|
||||
```
|
||||
|
||||
Кожна підказка для поля може містити:
|
||||
Кожна підказка поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | ---------------------------------------- |
|
||||
| `label` | `string` | Видима для користувача мітка поля. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові UI-теги. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст placeholder для полів форми. |
|
||||
| Поле | Тип | Що це означає |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може зчитати без імпорту runtime Plugin.
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту runtime plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"agentToolResultMiddleware": ["pi", "codex-app-server"],
|
||||
"agentToolResultMiddleware": ["pi", "codex"],
|
||||
"externalAuthProviders": ["acme-ai"],
|
||||
"speechProviders": ["openai"],
|
||||
"realtimeTranscriptionProviders": ["openai"],
|
||||
@ -371,33 +375,34 @@ OpenClaw також включає `setup.providers[].envVars` у загальн
|
||||
}
|
||||
```
|
||||
|
||||
Кожен список є необов’язковим:
|
||||
Кожен список необов’язковий:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ----------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Застарілі id embedded extension factory. |
|
||||
| `agentToolResultMiddleware` | `string[]` | id harness, для яких bundled Plugin може реєструвати middleware результатів tool. |
|
||||
| `externalAuthProviders` | `string[]` | id provider, hook зовнішніх профілів auth яких належить цьому Plugin. |
|
||||
| `speechProviders` | `string[]` | id provider speech, якими володіє цей Plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | id provider realtime-transcription, якими володіє цей Plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | id provider realtime-voice, якими володіє цей Plugin. |
|
||||
| `memoryEmbeddingProviders` | `string[]` | id provider memory embedding, якими володіє цей Plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | id provider media-understanding, якими володіє цей Plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | id provider image-generation, якими володіє цей Plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | id provider video-generation, якими володіє цей Plugin. |
|
||||
| `webFetchProviders` | `string[]` | id provider web-fetch, якими володіє цей Plugin. |
|
||||
| `webSearchProviders` | `string[]` | id provider web search, якими володіє цей Plugin. |
|
||||
| `tools` | `string[]` | Назви agent tool, якими володіє цей Plugin для bundled-перевірок contract. |
|
||||
| Поле | Тип | Що це означає |
|
||||
| -------------------------------- | ---------- | ---------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих extension. |
|
||||
| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований plugin може реєструвати middleware результатів інструментів. |
|
||||
| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, hook зовнішнього профілю автентифікації яких належить цьому plugin. |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-transcription, якими володіє цей plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime-voice, якими володіє цей plugin. |
|
||||
| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей plugin. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей plugin. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей plugin. |
|
||||
| `tools` | `string[]` | Назви агентських інструментів, якими володіє цей plugin, для перевірок контрактів у пакеті. |
|
||||
|
||||
`contracts.embeddedExtensionFactories` збережено для bundled-коду сумісності, якому все ще потрібні прямі події embedded-runner Pi. Нові bundled-перетворення результатів tool повинні оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть реєструвати middleware результатів tool, оскільки ця поверхня може переписувати high-trust-вивід tool до того, як модель його побачить.
|
||||
`contracts.embeddedExtensionFactories` збережено для коду сумісності пакетів, якому все ще потрібні прямі події вбудованого runner Pi. Нові перетворення результатів інструментів у пакеті мають оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`.
|
||||
Зовнішні plugin не можуть реєструвати middleware результатів інструментів, оскільки цей шов може переписувати високодовірений вивід інструментів до того, як його побачить модель.
|
||||
|
||||
Plugin provider, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде видалений після вікна міграції.
|
||||
Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але цей механізм повільніший і буде видалений після завершення вікна міграції.
|
||||
|
||||
Bundled provider memory embedding повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей contract маніфесту, щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway зареєструє provider.
|
||||
Вбудовані провайдери memory embedding мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише plugin-власник до того, як повний runtime Gateway зареєструє провайдерів.
|
||||
|
||||
## Довідник `mediaUnderstandingProviderMetadata`
|
||||
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має типові моделі, пріоритет fallback auto-auth або нативну підтримку документів, які потрібні загальним helper core до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має типові моделі, пріоритет резервного автовибору за автентифікацією або нативну підтримку документів, яка потрібна загальним helper ядра до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -420,18 +425,18 @@ Bundled provider memory embedding повинні оголошувати `contrac
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис provider може містити:
|
||||
Кожен запис провайдера може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості media, які надає цей provider. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення model для capability, які використовуються, коли config не задає model. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного fallback provider на основі credential. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні дані документів, які підтримує provider. |
|
||||
| Поле | Тип | Що це означає |
|
||||
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення відповідності можливість-модель, що використовуються, коли конфігурація не вказує модель. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли Plugin channel потребує легковагих метаданих config до завантаження runtime. Discovery setup/status channel лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх channel, коли запис setup недоступний або коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним.
|
||||
Використовуйте `channelConfigs`, коли plugin каналу потребує дешевих метаданих конфігурації до завантаження runtime. Виявлення setup/status каналу лише для читання може напряму використовувати ці метадані для налаштованих зовнішніх каналів, коли запис setup недоступний або коли `setup.requiresRuntime: false` означає, що runtime setup не потрібен.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -458,19 +463,19 @@ Bundled provider memory embedding повинні оголошувати `contrac
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис channel може містити:
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису config channel. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові UI-мітки/placeholders/підказки чутливості для цього розділу config channel. |
|
||||
| `label` | `string` | Мітка channel, що об’єднується в поверхнях вибору та inspect, коли метадані runtime ще не готові. |
|
||||
| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. |
|
||||
| `preferOver` | `string[]` | id застарілих або менш пріоритетних Plugin, які цей channel має перевершувати в поверхнях вибору. |
|
||||
| Поле | Тип | Що це означає |
|
||||
| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | Схема JSON для `channels.<id>`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та перевірки, коли метадані runtime ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних plugin, які цей канал має випереджати на поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin provider із скорочених id model, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime Plugin.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш plugin провайдера зі скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -483,70 +488,71 @@ Bundled provider memory embedding повинні оголошувати `contrac
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers` Plugin-власника
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin
|
||||
- решта неоднозначностей ігноруються, доки користувач або config не вкаже provider
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, яким належить модель
|
||||
- `modelPatterns` мають пріоритет над `modelPrefixes`
|
||||
- якщо збігаються один plugin не з пакета і один plugin з пакета, перемагає plugin не з пакета
|
||||
- інша неоднозначність ігнорується, доки користувач або конфігурація не вкаже провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| Поле | Тип | Що це означає |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id model. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id model після видалення суфікса profile. |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі ключі capability верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння capability.
|
||||
Застарілі ключі можливостей верхнього рівня знецінені. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як володіння можливостями.
|
||||
|
||||
## Маніфест проти package.json
|
||||
## Маніфест проти `package.json`
|
||||
|
||||
Ці два файли виконують різні завдання:
|
||||
Ці два файли виконують різні ролі:
|
||||
|
||||
| Файл | Використовуйте його для |
|
||||
| Файл | Використовуйте для |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Discovery, валідації config, метаданих варіантів auth і підказок UI, які мають існувати до запуску коду Plugin |
|
||||
| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для entrypoint, обмежень встановлення, setup або метаданих catalog |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмеження встановлення, setup або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило:
|
||||
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом:
|
||||
|
||||
- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, розміщуйте це в `package.json`
|
||||
- якщо OpenClaw має знати це до завантаження коду plugin, розміщуйте це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json`
|
||||
|
||||
### Поля `package.json`, що впливають на discovery
|
||||
### Поля `package.json`, які впливають на виявлення
|
||||
|
||||
Деякі метадані Plugin до запуску runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
Деякі метадані plugin до runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.extensions` | Оголошує entrypoint власного Plugin. Має залишатися в каталозі пакета Plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує entrypoint runtime built JavaScript для встановлених пакетів. Має залишатися в каталозі пакета Plugin. |
|
||||
| `openclaw.setupEntry` | Легковагий entrypoint лише для setup, який використовується під час onboarding, відкладеного запуску channel і discovery статусу channel/SecretRef лише для читання. Має залишатися в каталозі пакета Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint setup для встановлених пакетів. Має залишатися в каталозі пакета Plugin. |
|
||||
| `openclaw.channel` | Легковагі метадані каталогу channel, такі як мітки, шляхи до документації, alias і текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легковагі метадані перевірки configured-state, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного runtime channel. |
|
||||
| `openclaw.channel.persistedAuthState` | Легковагі метадані перевірки persisted-auth, які можуть відповісти на питання «чи вже є якийсь виконаний вхід?» без завантаження повного runtime channel. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих Plugin. |
|
||||
| Поле | Що це означає |
|
||||
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує рідні точки входу plugin. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу runtime JavaScript для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу setup JavaScript для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.channel` | Полегшені метадані каталогу каналу, такі як мітки, шляхи документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного runtime каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання «чи вже є хоч якийсь вхід у систему?» без завантаження повного runtime каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення для пакетних і зовнішньо опублікованих plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт відносно нього. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled Plugin, коли config некоректний. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного Plugin channel під час запуску. |
|
||||
| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw з нижньою межею semver на кшталт `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють отриманий артефакт із ним. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення пакетного plugin, коли конфігурація недійсна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналу лише для setup завантажуватися до повного plugin каналу під час запуску. |
|
||||
|
||||
Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач обирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення і завантаження реєстру маніфесту. Некоректні значення відхиляються; новіші, але коректні значення пропускають Plugin на старіших хостах.
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення пропускають plugin на старіших хостах.
|
||||
|
||||
Точне закріплення версії npm уже розміщується в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу.
|
||||
Інтерактивний onboarding усе ще пропонує npm-специфікації довіреного реєстру, зокрема прості назви пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без закріплення цілісності, з невідповідністю імені пакета та некоректні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає коректного джерела npm, яке можна ним закріпити.
|
||||
Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його пропущено, визначення реєстру записується без закріплення цілісності.
|
||||
Точне закріплення версії npm уже міститься в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися в закритому режимі, якщо отриманий npm-артефакт більше не відповідає закріпленому випуску.
|
||||
Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, включно з простими назвами пакетів і dist-tag. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та недійсні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає коректного npm-джерела, яке можна ним закріпити.
|
||||
Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру записується без закріплення за цілісністю.
|
||||
|
||||
Plugin channel повинні надавати `openclaw.setupEntry`, коли статус, список channel або сканування SecretRef мають визначати налаштовані акаунти без завантаження повного runtime. Запис setup повинен надавати метадані channel разом із безпечними для setup адаптерами config, status і secrets; мережеві клієнти, listener Gateway і transport runtime залишайте в основному entrypoint extension.
|
||||
Plugin каналів мають надавати `openclaw.setupEntry`, коли status, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного runtime. Точка входу setup має відкривати метадані каналу плюс безпечні для setup адаптери конфігурації, status і secrets; мережеві клієнти, слухачі Gateway і runtime транспорту слід тримати в основній точці входу extension.
|
||||
|
||||
Поля runtime entrypoint не перевизначають перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета.
|
||||
Поля точки входу runtime не перевизначають перевірки меж пакета для полів точки входу джерела.
|
||||
Наприклад, `openclaw.runtimeExtensions` не може зробити доступним шлях `openclaw.extensions`, що виходить за межі.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить довільні зламані config придатними до встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення bundled Plugin, наприклад відсутнього шляху bundled Plugin або застарілого запису `channels.<id>` для того самого bundled Plugin. Непов’язані помилки config усе ще блокують встановлення й спрямовують операторів до `openclaw doctor --fix`.
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення пакетного plugin, таких як відсутній шлях пакетного plugin або застарілий запис `channels.<id>` для того самого пакетного plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
|
||||
|
||||
@ -564,9 +570,9 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth типу так/ні до завантаження повного Plugin channel. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через широкий barrel повного runtime channel.
|
||||
Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого yes/no-пробника автентифікації до завантаження повного plugin каналу. Цільовий експорт має бути невеликою функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок configured-state лише через env:
|
||||
`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -582,64 +588,64 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли channel може визначити configured-state з env або інших невеликих нерuntime-вхідних даних. Якщо перевірка потребує повного визначення config або реального runtime channel, залишайте цю логіку в hook Plugin `config.hasConfiguredState`.
|
||||
Використовуйте це, коли канал може відповісти про налаштований стан з env або інших малих нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або справжнього runtime каналу, натомість зберігайте цю логіку в hook plugin `config.hasConfiguredState`.
|
||||
|
||||
## Пріоритет discovery (дублікати id Plugin)
|
||||
## Пріоритет виявлення (дублікати ідентифікаторів plugin)
|
||||
|
||||
OpenClaw виявляє Plugin з кількох коренів (bundled, global install, workspace, явно вибрані в config шляхи). Якщо два результати discovery мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч.
|
||||
OpenClaw виявляє plugin із кількох коренів (пакетні, глобальне встановлення, робочий простір, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч.
|
||||
|
||||
Пріоритет від найвищого до найнижчого:
|
||||
Пріоритет, від найвищого до найнижчого:
|
||||
|
||||
1. **Config-selected** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Bundled** — Plugin, що постачаються з OpenClaw
|
||||
3. **Global install** — Plugin, встановлені в глобальний корінь Plugin OpenClaw
|
||||
4. **Workspace** — Plugin, виявлені відносно поточного workspace
|
||||
1. **Вибрані в конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Пакетні** — plugin, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw
|
||||
4. **Робочий простір** — plugin, виявлені відносно поточного робочого простору
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Форк або застаріла копія bundled Plugin, що лежить у workspace, не затьмарить bundled-збірку.
|
||||
- Щоб справді перевизначити bundled Plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він виграв за пріоритетом, а не покладайтеся на discovery workspace.
|
||||
- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказувати на відкинуту копію.
|
||||
- Форк або застаріла копія пакетного plugin у робочому просторі не зможе затінити пакетну збірку.
|
||||
- Щоб справді перевизначити пакетний plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення робочого простору.
|
||||
- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
## Вимоги до схеми JSON
|
||||
|
||||
- **Кожен Plugin повинен містити JSON Schema**, навіть якщо він не приймає config.
|
||||
- Порожня schema допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Schema проходять валідацію під час читання/запису config, а не під час runtime.
|
||||
- **Кожен plugin має постачатися зі схемою JSON**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено в маніфесті Plugin.
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено маніфестом plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
повинні посилатися на **доступні для discovery** id Plugin. Невідомі id є **помилками**.
|
||||
- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи schema,
|
||||
валідація завершується помилкою, а Doctor повідомляє про помилку Plugin.
|
||||
- Якщо config Plugin існує, але Plugin **вимкнено**, config зберігається, а в Doctor і логах з’являється **попередження**.
|
||||
мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**.
|
||||
- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
|
||||
валідація не проходить, а Doctor повідомляє про помилку plugin.
|
||||
- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і в Doctor + логах показується **попередження**.
|
||||
|
||||
Дивіться [Довідник з конфігурації](/uk/gateway/configuration) для повної schema `plugins.*`.
|
||||
Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест є **обов’язковим для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime усе ще завантажує модуль Plugin окремо; маніфест використовується лише для discovery + валідації.
|
||||
- Власні маніфести розбираються через JSON5, тож коментарі, завершальні коми й ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом.
|
||||
- Завантажувач маніфесту зчитує лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня.
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує.
|
||||
- `providerDiscoveryEntry` має залишатися легковагим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів discovery, а не для виконання під час обробки запитів.
|
||||
- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
|
||||
- Метадані env var (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою.
|
||||
- Для метаданих runtime wizard, які потребують коду provider, дивіться [Runtime-hook provider](/uk/plugins/architecture-internals#provider-runtime-hooks).
|
||||
- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild <package>`).
|
||||
- Маніфест є **обов’язковим для рідних plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime усе одно завантажує модуль plugin окремо; маніфест призначений лише для виявлення + валідації.
|
||||
- Рідні маніфести аналізуються як JSON5, тому приймаються коментарі, кінцеві коми та ключі без лапок, якщо кінцеве значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня.
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна опускати, якщо plugin їх не потребує.
|
||||
- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту.
|
||||
- Виключні типи plugin обираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
|
||||
- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою.
|
||||
- Для метаданих wizard runtime, які потребують коду провайдера, див. [Hook runtime провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks).
|
||||
- Якщо ваш plugin залежить від native modules, задокументуйте кроки збірки й будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Створення Plugin" href="/uk/plugins/building-plugins" icon="rocket">
|
||||
Початок роботи з Plugin.
|
||||
<Card title="Створення plugin" href="/uk/plugins/building-plugins" icon="rocket">
|
||||
Початок роботи з plugin.
|
||||
</Card>
|
||||
<Card title="Архітектура Plugin" href="/uk/plugins/architecture" icon="diagram-project">
|
||||
Внутрішня архітектура та модель capability.
|
||||
<Card title="Архітектура plugin" href="/uk/plugins/architecture" icon="diagram-project">
|
||||
Внутрішня архітектура та модель можливостей.
|
||||
</Card>
|
||||
<Card title="Огляд SDK" href="/uk/plugins/sdk-overview" icon="book">
|
||||
Довідник SDK Plugin та імпорти підшляхів.
|
||||
Довідник SDK plugin і імпорти підшляхів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,57 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви змінюєте вбудований рантайм агента або реєстр каркаса агента
|
||||
- Ви реєструєте каркас агента з вбудованого або довіреного плагіна
|
||||
- Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей
|
||||
- Ви змінюєте вбудований runtime агента або реєстр каркасів
|
||||
- Ви реєструєте каркас агента з вбудованого або довіреного Plugin
|
||||
- Вам потрібно зрозуміти, як Plugin Codex пов’язаний із провайдерами моделей
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агентів
|
||||
title: Плагіни каркаса агентів
|
||||
summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневий вбудований виконавець агента
|
||||
title: Plugins каркаса агента
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:32:19Z"
|
||||
generated_at: "2026-04-25T00:02:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e73cbaaa239801ec5da18374cc1b2142c9cf7136f8d33d81d2fa04bc4dea3c11
|
||||
source_hash: 350dcfa9492ab30d14913a1f275747a5074f5d8651a96309f6002cdf9b8b2803
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів.
|
||||
**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не провайдер моделі, не канал і не реєстр інструментів.
|
||||
|
||||
Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт
|
||||
усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний
|
||||
вбудований раннер.
|
||||
Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований runner.
|
||||
|
||||
## Коли використовувати каркас
|
||||
|
||||
Реєструйте каркас агента, коли сімейство моделей має власний нативний рантайм сесії
|
||||
і звичайний транспорт постачальника OpenClaw є неправильною абстракцією.
|
||||
Реєструйте каркас агента, коли сімейство моделей має власний нативний runtime сеансу і звичайний транспорт провайдера OpenClaw є хибною абстракцією.
|
||||
|
||||
Приклади:
|
||||
|
||||
- нативний сервер coding-agent, який керує потоками й Compaction
|
||||
- локальний CLI або демон, який має стримити нативні події плану/міркування/інструментів
|
||||
- рантайм моделі, якому потрібен власний resume id на додачу до транскрипту
|
||||
сесії OpenClaw
|
||||
- нативний сервер coding-agent, який керує потоками та Compaction
|
||||
- локальний CLI або демон, який має потоково передавати нативні події plan/reasoning/tool
|
||||
- runtime моделі, якому потрібен власний resume id на додачу до транскрипту сеансу OpenClaw
|
||||
|
||||
**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або
|
||||
WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins).
|
||||
**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або WebSocket API моделей створіть [Plugin провайдера](/uk/plugins/sdk-provider-plugins).
|
||||
|
||||
## Що все ще належить core
|
||||
## Чим ядро все ще керує
|
||||
|
||||
Перш ніж буде вибрано каркас, OpenClaw уже визначив:
|
||||
До того, як буде вибрано каркас, OpenClaw уже визначив:
|
||||
|
||||
- постачальника й модель
|
||||
- стан автентифікації рантайму
|
||||
- провайдера і модель
|
||||
- стан автентифікації runtime
|
||||
- рівень thinking і бюджет контексту
|
||||
- файл транскрипту/сесії OpenClaw
|
||||
- робочий простір, sandbox і політику інструментів
|
||||
- колбеки відповіді каналу й колбеки стримінгу
|
||||
- політику резервного перемикання моделей і live-перемикання моделей
|
||||
- файл транскрипту/сеансу OpenClaw
|
||||
- workspace, sandbox і політику інструментів
|
||||
- callback-и відповідей каналу і callback-и потокової передачі
|
||||
- політику fallback моделі та live-перемикання моделі
|
||||
|
||||
Цей поділ навмисний. Каркас виконує підготовлену спробу; він не вибирає
|
||||
постачальників, не замінює доставку через канал і не перемикає моделі непомітно.
|
||||
Цей поділ навмисний. Каркас виконує підготовлену спробу; він не вибирає провайдерів, не замінює доставку каналу й не перемикає моделі непомітно.
|
||||
|
||||
## Зареєструвати каркас
|
||||
## Реєстрація каркаса
|
||||
|
||||
**Імпорт:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -89,111 +83,58 @@ export default definePluginEntry({
|
||||
|
||||
## Політика вибору
|
||||
|
||||
OpenClaw вибирає каркас після визначення постачальника/моделі:
|
||||
OpenClaw вибирає каркас після визначення провайдера/моделі:
|
||||
|
||||
1. Якщо в наявної сесії записано id каркаса, він має пріоритет, тому зміни config/env не
|
||||
перемикають цей транскрипт на інший рантайм на льоту.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово задає зареєстрований каркас із цим id для
|
||||
сесій, які ще не закріплені.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих каркасів, чи підтримують вони
|
||||
визначеного постачальника/модель.
|
||||
5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо
|
||||
резервний перехід на PI не вимкнено.
|
||||
1. Записаний id каркаса наявного сеансу має пріоритет, щоб зміни config/env не перемикали цей транскрипт на інший runtime на льоту.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово вказує зареєстрований каркас із цим id для сеансів, які ще не закріплені.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вказує вбудований каркас PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих каркасів, чи підтримують вони визначеного провайдера/модель.
|
||||
5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо fallback на PI не вимкнено.
|
||||
|
||||
Збої каркасів плагінів проявляються як збої виконання. У режимі `auto` резервний перехід на PI
|
||||
використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного
|
||||
постачальника/модель. Щойно каркас плагіна взяв виконання на себе, OpenClaw не
|
||||
переграє той самий хід через PI, оскільки це може змінити семантику автентифікації/рантайму
|
||||
або дублювати побічні ефекти.
|
||||
Збої каркаса Plugin відображаються як збої виконання. У режимі `auto` fallback на PI використовується лише тоді, коли жоден зареєстрований каркас Plugin не підтримує визначеного провайдера/модель. Щойно каркас Plugin узяв виконання на себе, OpenClaw не повторює той самий хід через PI, оскільки це може змінити семантику auth/runtime або дублювати побічні ефекти.
|
||||
|
||||
Вибраний id каркаса зберігається разом з id сесії після вбудованого виконання.
|
||||
Застарілі сесії, створені до появи закріплення каркасів, вважаються закріпленими за PI, щойно
|
||||
в них з’являється історія транскрипту. Використовуйте нову/скинуту сесію під час перемикання між PI і
|
||||
нативним каркасом плагіна. `/status` показує нестандартні id каркасів, як-от `codex`,
|
||||
поруч із `Fast`; PI залишається прихованим, бо це шлях сумісності за замовчуванням.
|
||||
Якщо вибраний каркас виглядає несподівано, увімкніть журналювання налагодження `agents/harness` і
|
||||
перегляньте структурований запис gateway `agent harness selected`. Він містить
|
||||
вибраний id каркаса, причину вибору, політику рантайму/резервного переходу, а також у режимі
|
||||
`auto` — результат підтримки для кожного кандидата-плагіна.
|
||||
Вибраний id каркаса зберігається разом з id сеансу після вбудованого виконання. Застарілі сеанси, створені до закріплення каркасів, вважаються закріпленими за PI, щойно в них з’являється історія транскрипту. Використовуйте новий/скинутий сеанс під час перемикання між PI і нативним каркасом Plugin. `/status` показує нетипові id каркасів, такі як `codex`, поруч із `Fast`; PI приховано, оскільки це типовий шлях сумісності. Якщо вибраний каркас виглядає неочікуваним, увімкніть логування налагодження `agents/harness` і перегляньте структурований запис Gateway `agent harness selected`. Він містить id вибраного каркаса, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата Plugin.
|
||||
|
||||
Вбудований плагін Codex реєструє `codex` як свій id каркаса. Core розглядає це
|
||||
як звичайний id каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну
|
||||
або config оператора, а не спільному селектору рантайму.
|
||||
Вбудований Plugin Codex реєструє `codex` як свій id каркаса. Ядро сприймає це як звичайний id каркаса Plugin; специфічні для Codex псевдоніми мають належати Plugin або конфігурації оператора, а не спільному селектору runtime.
|
||||
|
||||
## Поєднання постачальника й каркаса
|
||||
## Поєднання провайдера й каркаса
|
||||
|
||||
Більшість каркасів також мають реєструвати постачальника. Постачальник робить refs моделей,
|
||||
стан автентифікації, метадані моделі й вибір `/model` видимими для решти
|
||||
OpenClaw. Потім каркас заявляє цей постачальник у `supports(...)`.
|
||||
Більшість каркасів також мають реєструвати провайдера. Провайдер робить посилання на моделі, статус auth, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє підтримку цього провайдера в `supports(...)`.
|
||||
|
||||
Вбудований плагін Codex дотримується цього шаблону:
|
||||
Вбудований Plugin Codex дотримується цієї схеми:
|
||||
|
||||
- id постачальника: `codex`
|
||||
- refs моделей для користувача: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`;
|
||||
застарілі refs `codex/gpt-*` і далі приймаються для сумісності
|
||||
- id провайдера: `codex`
|
||||
- користувацькі посилання на моделі: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; застарілі посилання `codex/gpt-*` і далі підтримуються для сумісності
|
||||
- id каркаса: `codex`
|
||||
- auth: синтетична доступність постачальника, оскільки каркас Codex керує
|
||||
нативним входом/сесією Codex
|
||||
- запит до app-server: OpenClaw надсилає Codex «голий» id моделі й дозволяє
|
||||
каркасу працювати з нативним протоколом app-server
|
||||
- auth: синтетична доступність провайдера, оскільки каркас Codex керує нативним входом/сеансом Codex
|
||||
- запит app-server: OpenClaw надсилає Codex чистий id моделі й дозволяє каркасу працювати з нативним протоколом app-server
|
||||
|
||||
Плагін Codex є доповнювальним. Звичайні refs `openai/gpt-*` і далі використовують
|
||||
нормальний шлях постачальника OpenClaw, якщо ви не примусите каркас Codex через
|
||||
`embeddedHarness.runtime: "codex"`. Старіші refs `codex/gpt-*` усе ще вибирають
|
||||
постачальника й каркас Codex для сумісності.
|
||||
Plugin Codex є додатковим. Звичайні посилання `openai/gpt-*` і далі використовують стандартний шлях провайдера OpenClaw, якщо ви примусово не вкажете каркас Codex через `embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` і далі вибирають провайдера й каркас Codex для сумісності.
|
||||
|
||||
Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex, див.
|
||||
[Каркас Codex](/uk/plugins/codex-harness).
|
||||
Налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex дивіться в [Codex Harness](/uk/plugins/codex-harness).
|
||||
|
||||
OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Плагін Codex перевіряє
|
||||
initialize-handshake app-server і блокує старіші або безверсійні сервери, щоб
|
||||
OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано.
|
||||
OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Plugin Codex перевіряє initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб OpenClaw працював лише з тим протокольним інтерфейсом, який було протестовано.
|
||||
|
||||
### Middleware результатів інструментів
|
||||
|
||||
Вбудовані плагіни можуть додавати не прив’язане до каркаса middleware результатів інструментів через
|
||||
`api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує
|
||||
цільові id каркасів у `contracts.agentToolResultMiddleware`. Цей довірений шов
|
||||
призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex передадуть
|
||||
вивід інструмента назад у модель.
|
||||
Вбудовані Plugins можуть під’єднувати runtime-нейтральне middleware результатів інструментів через `api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує цільові id runtime у `contracts.agentToolResultMiddleware`. Цей довірений шов призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex поверне вивід інструмента назад у модель.
|
||||
|
||||
Застарілі вбудовані плагіни все ще можуть використовувати
|
||||
`api.registerCodexAppServerExtensionFactory(...)` для middleware лише для Codex app-server,
|
||||
але нові перетворення результатів мають використовувати API, не прив’язане до каркаса.
|
||||
Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` є застарілим для
|
||||
перетворень результатів інструментів; залишайте його лише для вбудованого коду сумісності, якому
|
||||
все ще потрібні прямі події вбудованого раннера Pi.
|
||||
Застарілі вбудовані Plugins і далі можуть використовувати `api.registerCodexAppServerExtensionFactory(...)` для middleware лише app-server Codex, але нові перетворення результатів слід реалізовувати через runtime-нейтральний API.
|
||||
Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` застарів для перетворень результатів інструментів; залишайте його лише для коду сумісності вбудованих Plugin, якому все ще потрібні прямі події вбудованого runner Pi.
|
||||
|
||||
### Режим нативного каркаса Codex
|
||||
|
||||
Вбудований каркас `codex` — це нативний режим Codex для вбудованих ходів
|
||||
агента OpenClaw. Спочатку увімкніть вбудований плагін `codex` і додайте `codex` до
|
||||
`plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Конфігурації нативного app-server
|
||||
мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`.
|
||||
Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі refs моделей `codex/*`
|
||||
залишаються псевдонімами сумісності для нативного каркаса.
|
||||
Вбудований каркас `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть вбудований Plugin `codex` і додайте `codex` до `plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Конфігурації нативного app-server мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Для Codex OAuth через PI використовуйте `openai-codex/*`. Застарілі посилання на моделі `codex/*` залишаються псевдонімами сумісності для нативного каркаса.
|
||||
|
||||
Коли цей режим виконується, Codex керує нативним id потоку, поведінкою відновлення,
|
||||
Compaction і виконанням app-server. OpenClaw усе ще керує чат-каналом,
|
||||
видимим дзеркалом транскрипту, політикою інструментів, погодженнями, доставкою медіа й
|
||||
вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із
|
||||
`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях
|
||||
Codex app-server може взяти виконання на себе. Ця конфігурація є лише запобіжником вибору:
|
||||
збої Codex app-server уже й так напряму завершуються помилкою без повторної спроби через PI.
|
||||
Коли цей режим працює, Codex керує нативним id потоку, поведінкою resume, Compaction і виконанням app-server. OpenClaw і далі керує чатом каналу, видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та вибором сеансу. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що виконання може взяти на себе лише шлях app-server Codex. Ця конфігурація є лише guard-вибором: збої app-server Codex уже безпосередньо завершуються помилкою без повторної спроби через PI.
|
||||
|
||||
## Вимкнення резервного переходу на PI
|
||||
## Вимкнення fallback на PI
|
||||
|
||||
За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`,
|
||||
встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані плагінні
|
||||
каркаси можуть заявити про підтримку пари постачальник/модель. Якщо жоден не підходить,
|
||||
OpenClaw переходить на PI.
|
||||
Типово OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим як `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси Plugin можуть заявити підтримку для пари провайдер/модель. Якщо жоден не підходить, OpenClaw переходить на PI.
|
||||
|
||||
Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору каркаса плагіна
|
||||
завершувалася помилкою замість використання PI. Збої вже вибраних каркасів плагінів і так завершуються помилкою. Це
|
||||
не блокує явне `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
Установіть `fallback: "none"`, коли потрібно, щоб відсутність відповідного каркаса Plugin спричиняла помилку замість використання PI. Збої вже вибраного каркаса Plugin і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Для вбудованих виконань лише з Codex:
|
||||
Для вбудованих запусків лише з Codex:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -209,9 +150,7 @@ OpenClaw переходить на PI.
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг заявити про відповідні моделі, але ніколи
|
||||
не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть
|
||||
резервний перехід:
|
||||
Якщо ви хочете, щоб будь-який зареєстрований каркас Plugin міг заявляти підтримку для відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть fallback:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -251,9 +190,7 @@ OpenClaw переходить на PI.
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований рантайм. Використовуйте
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через
|
||||
оточення.
|
||||
`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI через оточення.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -261,53 +198,40 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Коли резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний каркас не
|
||||
зареєстровано, він не підтримує визначеного постачальника/модель або завершується помилкою до
|
||||
появи побічних ефектів ходу. Це навмисно для розгортань лише з Codex і
|
||||
для live-тестів, які мають довести, що шлях Codex app-server справді використовується.
|
||||
Коли fallback вимкнено, сеанс завершується помилкою на ранньому етапі, якщо запитаний каркас не зареєстровано, не підтримує визначеного провайдера/модель або завершується помилкою до появи побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що насправді використовується шлях app-server Codex.
|
||||
|
||||
Цей параметр керує лише каркасом вбудованого агента. Він не вимикає маршрутизацію
|
||||
специфічних для постачальника моделей для зображень, відео, музики, TTS, PDF чи інших.
|
||||
Цей параметр керує лише вбудованим каркасом агента. Він не вимикає маршрутизацію моделей, специфічну для провайдерів, для зображень, відео, музики, TTS, PDF або інших типів.
|
||||
|
||||
## Нативні сесії та дзеркало транскрипту
|
||||
## Нативні сеанси й дзеркало транскрипту
|
||||
|
||||
Каркас може зберігати нативний id сесії, id потоку або токен відновлення на боці демона.
|
||||
Явно зберігайте цей зв’язок асоційованим із сесією OpenClaw і продовжуйте
|
||||
дзеркалити видимий користувачеві вивід асистента/інструментів у транскрипт OpenClaw.
|
||||
Каркас може зберігати нативний id сеансу, id потоку або токен resume на боці демона.
|
||||
Тримайте цей зв’язок явно пов’язаним із сеансом OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід помічника/інструментів у транскрипт OpenClaw.
|
||||
|
||||
Транскрипт OpenClaw залишається шаром сумісності для:
|
||||
|
||||
- видимої в каналі історії сесії
|
||||
- історії сеансу, видимої в каналі
|
||||
- пошуку та індексації транскрипту
|
||||
- перемикання назад на вбудований каркас PI на наступному ході
|
||||
- загальної поведінки `/new`, `/reset` і видалення сесії
|
||||
- повернення до вбудованого каркаса PI на наступному ході
|
||||
- універсальної поведінки `/new`, `/reset` і видалення сеансу
|
||||
|
||||
Якщо ваш каркас зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг
|
||||
очистити її, коли пов’язану сесію OpenClaw скинуто.
|
||||
Якщо ваш каркас зберігає sidecar-зв’язок, реалізуйте `reset(...)`, щоб OpenClaw міг очистити його під час скидання пов’язаного сеансу OpenClaw.
|
||||
|
||||
## Результати інструментів і медіа
|
||||
|
||||
Core формує список інструментів OpenClaw і передає його в підготовлену спробу.
|
||||
Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через
|
||||
форму результату каркаса, а не надсилайте медіа в канал самостійно.
|
||||
Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через форму результату каркаса замість того, щоб самостійно надсилати медіа в канал.
|
||||
|
||||
Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи
|
||||
інструментів для обміну повідомленнями на тому самому шляху доставки, що й виконання з підтримкою PI.
|
||||
Це зберігає текст, зображення, відео, музику, TTS, схвалення й результати інструментів повідомлень на тому самому шляху доставки, що й у запусках на основі PI.
|
||||
|
||||
## Поточні обмеження
|
||||
|
||||
- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроби/результату все ще
|
||||
містять назви `Pi` для сумісності.
|
||||
- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників,
|
||||
доки вам не знадобиться нативний рантайм сесії.
|
||||
- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред
|
||||
ходу після того, як уже почалися нативні інструменти, погодження, текст асистента або
|
||||
надсилання повідомлень.
|
||||
- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі містять назви `Pi` для сумісності.
|
||||
- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу Plugin провайдерів, доки вам не знадобиться нативний runtime сеансу.
|
||||
- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися нативні інструменти, схвалення, текст помічника або надсилання повідомлень.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview)
|
||||
- [Допоміжні засоби рантайму](/uk/plugins/sdk-runtime)
|
||||
- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins)
|
||||
- [Каркас Codex](/uk/plugins/codex-harness)
|
||||
- [Постачальники моделей](/uk/concepts/model-providers)
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime)
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/uk/plugins/codex-harness)
|
||||
- [Провайдери моделей](/uk/concepts/model-providers)
|
||||
|
||||
@ -3,36 +3,47 @@ read_when:
|
||||
- Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
|
||||
- Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED
|
||||
- Ви використовуєте `api.registerEmbeddedExtensionFactory`
|
||||
- Ви оновлюєте Plugin до сучасної архітектури Plugin
|
||||
- Ви оновлюєте Plugin до сучасної архітектури плагінів
|
||||
- Ви підтримуєте зовнішній Plugin OpenClaw
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK
|
||||
title: Міграція Plugin SDK
|
||||
summary: Перейти із застарілого шару зворотної сумісності на сучасний SDK Plugin
|
||||
title: Міграція SDK Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:32:19Z"
|
||||
generated_at: "2026-04-25T00:02:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fe4a2f78653c1eabd4295cd7ad9cdb7b60995f172b6018650dd8f570f9b47c8d
|
||||
source_hash: ccf6e736c2a7cb54f9249d92b27edcecfabda14c64d88a8932a69565e246c33c
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури Plugin із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію.
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів із цільовими, документованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію.
|
||||
|
||||
## Що змінюється
|
||||
|
||||
Стара система Plugin надавала дві надто широкі поверхні, які дозволяли Plugin імпортувати все, що їм було потрібно, з однієї точки входу:
|
||||
Стара система плагінів надавала дві широкі поверхні, які дозволяли Plugin імпортувати
|
||||
будь-що потрібне з однієї точки входу:
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші Plugin на основі хуків продовжували працювати під час створення нової архітектури Plugin.
|
||||
- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до допоміжних засобів на стороні хоста, таких як вбудований запускальник агентів.
|
||||
- **`api.registerEmbeddedExtensionFactory(...)`** — хук для вбудованих розширень лише для Pi, який міг спостерігати за подіями вбудованого запускальника, такими як `tool_result`.
|
||||
- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки
|
||||
допоміжних функцій. Його було запроваджено, щоб зберегти працездатність старіших
|
||||
плагінів на основі hook, поки будувалася нова архітектура плагінів.
|
||||
- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до
|
||||
допоміжних функцій на боці хоста, таких як вбудований runner агента.
|
||||
- **`api.registerEmbeddedExtensionFactory(...)`** — hook вбудованого extension
|
||||
лише для Pi, який міг спостерігати події вбудованого runner, такі як `tool_result`.
|
||||
|
||||
Тепер ці поверхні **застарілі**. Вони все ще працюють під час виконання, але нові Plugin не повинні їх використовувати, а наявні Plugin слід мігрувати до того, як у наступному мажорному релізі їх буде видалено.
|
||||
Ці поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові
|
||||
Plugin не повинні їх використовувати, а наявні мають перейти на новий підхід до того,
|
||||
як наступний мажорний випуск їх видалить.
|
||||
|
||||
OpenClaw не видаляє й не переосмислює задокументовану поведінку Plugin у тій самій зміні, яка запроваджує заміну. Зміни контракту з порушенням сумісності спершу мають пройти через адаптер сумісності, діагностику, документацію та період застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання.
|
||||
OpenClaw не видаляє і не переосмислює документовану поведінку Plugin у тій самій
|
||||
зміні, де вводиться заміна. Зміни контракту, що ламають сумісність, спочатку мають
|
||||
пройти через адаптер сумісності, діагностику, документацію та період застарівання.
|
||||
Це стосується імпортів SDK, полів manifest, API налаштування, hook і поведінки
|
||||
реєстрації під час виконання.
|
||||
|
||||
<Warning>
|
||||
Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів.
|
||||
Шар зворотної сумісності буде видалено в одному з майбутніх мажорних випусків.
|
||||
Plugin, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться.
|
||||
</Warning>
|
||||
|
||||
@ -40,40 +51,53 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
Старий підхід спричиняв проблеми:
|
||||
|
||||
- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти полегшували створення циклів імпорту
|
||||
- **Неочевидна поверхня API** — не було способу визначити, які експорти були стабільними, а які внутрішніми
|
||||
- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми
|
||||
|
||||
Сучасний Plugin SDK вирішує цю проблему: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`) — це невеликий самодостатній модуль із чітким призначенням і задокументованим контрактом.
|
||||
Сучасний SDK Plugin виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим, самодостатнім модулем із чітким призначенням і документованим контрактом.
|
||||
|
||||
Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, допоміжні шви з брендуванням каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями для монорепозиторію, а не стабільними контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать provider, у власному `api.ts` або `runtime-api.ts` цього Plugin.
|
||||
Застарілі зручні seams provider для вбудованих каналів також зникли. Імпорти
|
||||
на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
|
||||
допоміжні channel-branded seams і
|
||||
`openclaw/plugin-sdk/telegram-core` були приватними скороченнями monorepo, а не
|
||||
стабільними контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині
|
||||
робочого простору вбудованого Plugin зберігайте допоміжні функції, що належать provider, у власному
|
||||
`api.ts` або `runtime-api.ts` цього Plugin.
|
||||
|
||||
Поточні приклади вбудованих provider:
|
||||
|
||||
- Anthropic зберігає допоміжні засоби потокової передачі, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts`
|
||||
- OpenAI зберігає конструктори provider, допоміжні засоби для моделей за замовчуванням і конструктори realtime provider у власному `api.ts`
|
||||
- OpenRouter зберігає конструктор provider і допоміжні засоби онбордингу/конфігурації у власному `api.ts`
|
||||
- Anthropic зберігає допоміжні функції потокової передачі, специфічні для Claude, у власному seam `api.ts` /
|
||||
`contract-api.ts`
|
||||
- OpenAI зберігає builder-и provider, допоміжні функції типових моделей і builder-и provider
|
||||
реального часу у власному `api.ts`
|
||||
- OpenRouter зберігає builder provider і допоміжні функції onboarding/config у власному
|
||||
`api.ts`
|
||||
|
||||
## Політика сумісності
|
||||
|
||||
Для зовнішніх Plugin робота із сумісністю виконується в такому порядку:
|
||||
Для зовнішніх Plugin робота із сумісністю відбувається в такому порядку:
|
||||
|
||||
1. додати новий контракт
|
||||
2. зберегти стару поведінку, підключивши її через адаптер сумісності
|
||||
3. вивести діагностику або попередження, яке вказує старий шлях і заміну
|
||||
4. покрити тести для обох шляхів
|
||||
2. зберегти стару поведінку через адаптер сумісності
|
||||
3. вивести діагностичне повідомлення або попередження, яке вказує старий шлях і заміну
|
||||
4. покрити обидва шляхи в тестах
|
||||
5. задокументувати застарівання та шлях міграції
|
||||
6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному релізі
|
||||
6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному випуску
|
||||
|
||||
Якщо поле маніфесту все ще приймається, автори Plugin можуть і далі його використовувати, доки документація й діагностика не скажуть інакше. Новий код має надавати перевагу задокументованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних релізів.
|
||||
Якщо поле manifest усе ще приймається, автори Plugin можуть продовжувати його використовувати,
|
||||
доки документація та діагностика не скажуть інше. Новому коду слід віддавати перевагу
|
||||
документованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних
|
||||
випусків.
|
||||
|
||||
## Як мігрувати
|
||||
## Як виконати міграцію
|
||||
|
||||
<Steps>
|
||||
<Step title="Мігруйте розширення результатів інструментів Pi на middleware">
|
||||
Вбудовані Plugin повинні замінити обробники результатів інструментів лише для Pi через
|
||||
`api.registerEmbeddedExtensionFactory(...)` на
|
||||
middleware, нейтральне до harness.
|
||||
<Step title="Мігруйте розширення Pi tool-result на middleware">
|
||||
Вбудовані Plugin мають замінити обробники tool-result лише для Pi через
|
||||
`api.registerEmbeddedExtensionFactory(...)` на middleware, нейтральне до runtime.
|
||||
|
||||
```typescript
|
||||
// Before: Pi-only compatibility hook
|
||||
@ -83,50 +107,60 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
});
|
||||
});
|
||||
|
||||
// After: Pi and Codex app-server dynamic tools
|
||||
// After: Pi and Codex runtime dynamic tools
|
||||
api.registerAgentToolResultMiddleware(async (event) => {
|
||||
return compactToolResult(event);
|
||||
}, {
|
||||
harnesses: ["pi", "codex-app-server"],
|
||||
runtimes: ["pi", "codex"],
|
||||
});
|
||||
```
|
||||
|
||||
Одночасно оновіть маніфест Plugin:
|
||||
Одночасно оновіть manifest Plugin:
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"agentToolResultMiddleware": ["pi", "codex-app-server"]
|
||||
"agentToolResultMiddleware": ["pi", "codex"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності, якому все ще потрібні прямі події вбудованого запускальника Pi. Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки воно може переписувати вихід інструмента з високим рівнем довіри до того, як модель його побачить.
|
||||
Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності,
|
||||
якому все ще потрібні прямі події вбудованого runner Pi. Зовнішні Plugin
|
||||
не можуть реєструвати middleware tool-result, оскільки воно може переписувати високодовірений
|
||||
вивід інструмента до того, як його побачить модель.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Мігруйте нативні обробники approval на факти можливостей">
|
||||
Plugin каналів із підтримкою approval тепер надають нативну поведінку approval через
|
||||
`approvalCapability.nativeRuntime` разом зі спільним реєстром контексту runtime.
|
||||
<Step title="Мігруйте native-обробники підтвердження на capability facts">
|
||||
Channel Plugin із підтримкою підтверджень тепер надають нативну поведінку підтвердження через
|
||||
`approvalCapability.nativeRuntime` плюс спільний реєстр runtime-context.
|
||||
|
||||
Основні зміни:
|
||||
Ключові зміни:
|
||||
|
||||
- Замініть `approvalCapability.handler.loadRuntime(...)` на
|
||||
`approvalCapability.nativeRuntime`
|
||||
- Перенесіть auth/доставку, специфічні для approval, зі застарілого підключення `plugin.auth` /
|
||||
`plugin.approvals` на `approvalCapability`
|
||||
- `ChannelPlugin.approvals` було видалено з публічного контракту Plugin каналу; перенесіть поля delivery/native/render до `approvalCapability`
|
||||
- `plugin.auth` залишається лише для потоків входу/виходу з каналу; core більше не читає там хуки auth для approval
|
||||
- Реєструйте об’єкти runtime, що належать каналу, як-от клієнти, токени або застосунки Bolt, через `openclaw/plugin-sdk/channel-runtime-context`
|
||||
- Не надсилайте сповіщення про перенаправлення, що належать Plugin, із нативних обробників approval; тепер core відповідає за сповіщення «переспрямовано в інше місце» на основі фактичних результатів доставки
|
||||
- Під час передавання `channelRuntime` до `createChannelManager(...)` надавайте справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються.
|
||||
- Перенесіть auth/delivery, специфічні для підтверджень, зі застарілої прив’язки `plugin.auth` /
|
||||
`plugin.approvals` до `approvalCapability`
|
||||
- `ChannelPlugin.approvals` видалено з публічного контракту channel-plugin;
|
||||
перенесіть поля delivery/native/render до `approvalCapability`
|
||||
- `plugin.auth` залишається лише для потоків входу/виходу channel; hook авторизації підтверджень
|
||||
там більше не зчитуються core
|
||||
- Реєструйте об’єкти runtime, що належать channel, такі як клієнти, токени або Bolt
|
||||
apps, через `openclaw/plugin-sdk/channel-runtime-context`
|
||||
- Не надсилайте сповіщення про перенаправлення, що належать Plugin, з native-обробників підтвердження;
|
||||
тепер core керує сповіщеннями routed-elsewhere на основі фактичних результатів доставки
|
||||
- Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте
|
||||
реальну поверхню `createPluginRuntime().channel`. Часткові stub відхиляються.
|
||||
|
||||
Поточну структуру можливостей approval див. у `/plugins/sdk-channel-plugins`.
|
||||
Поточну структуру capability підтвердження див. у `/plugins/sdk-channel-plugins`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте резервну поведінку Windows wrapper">
|
||||
Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows-обгортки `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`.
|
||||
<Step title="Перевірте поведінку резервного варіанта wrapper у Windows">
|
||||
Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені wrapper `.cmd`/`.bat` у Windows
|
||||
тепер завершуються без резервного переходу, якщо ви явно не передасте
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -141,12 +175,13 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
});
|
||||
```
|
||||
|
||||
Якщо ваш виклик не покладається навмисно на резервний перехід через оболонку, не встановлюйте `allowShellFallback`, а натомість обробляйте викинуту помилку.
|
||||
Якщо ваш виклик не покладається навмисно на резервний перехід через shell, не задавайте
|
||||
`allowShellFallback` і натомість обробляйте викинуту помилку.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Знайдіть застарілі імпорти">
|
||||
Знайдіть у своєму Plugin імпорти з будь-якої із застарілих поверхонь:
|
||||
Виконайте пошук у своєму Plugin для імпортів із будь-якої із застарілих поверхонь:
|
||||
|
||||
```bash
|
||||
grep -r "plugin-sdk/compat" my-plugin/
|
||||
@ -155,8 +190,8 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Замініть на цільові імпорти">
|
||||
Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту:
|
||||
<Step title="Замініть цільовими імпортами">
|
||||
Кожен експорт зі старої поверхні зіставляється з конкретним сучасним шляхом імпорту:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated backwards-compatibility layer)
|
||||
@ -172,7 +207,8 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
|
||||
```
|
||||
|
||||
Для допоміжних засобів на стороні хоста використовуйте ін’єктований runtime Plugin замість прямого імпорту:
|
||||
Для допоміжних функцій на боці хоста використовуйте впроваджений runtime Plugin замість прямого
|
||||
імпорту:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated extension-api bridge)
|
||||
@ -183,7 +219,7 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
|
||||
```
|
||||
|
||||
Такий самий шаблон застосовується й до інших застарілих допоміжних засобів bridge:
|
||||
Той самий шаблон застосовується до інших допоміжних функцій застарілого bridge:
|
||||
|
||||
| Старий імпорт | Сучасний еквівалент |
|
||||
| --- | --- |
|
||||
@ -193,7 +229,7 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
|
||||
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
|
||||
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
|
||||
| допоміжні засоби сховища сесій | `api.runtime.agent.session.*` |
|
||||
| session store helpers | `api.runtime.agent.session.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
@ -208,183 +244,185 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
## Довідник шляхів імпорту
|
||||
|
||||
<Accordion title="Таблиця поширених шляхів імпорту">
|
||||
| Шлях імпорту | Призначення | Основні експорти |
|
||||
| Шлях імпорту | Призначення | Ключові експорти |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу Plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу Plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Застарілий парасольковий повторний експорт для визначень/builder-ів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Цільові визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори стану налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для етапу налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби для списку/конфігурації/контролю дій облікових записів |
|
||||
| `plugin-sdk/account-id` | Допоміжні засоби ідентифікатора облікового запису | `DEFAULT_ACCOUNT_ID`, нормалізація ідентифікатора облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + резервного значення за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби для списку облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного provider | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Цільові визначення та builder-и точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, builder-и стану налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні функції runtime під час налаштування | Безпечні для імпорту адаптери patch для налаштування, допоміжні функції для lookup note, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Допоміжні функції інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку облікових записів/конфігурації/action-gate |
|
||||
| `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервного типового значення |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні функції для облікових записів | Допоміжні функції списку облікових записів/дій облікового запису |
|
||||
| `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Примітиви DM-парування | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + індикатора набору | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-pairing` | Примітиви підключення DM | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + логіка typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів |
|
||||
| `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` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних відповідей | Спільні допоміжні засоби запису та диспетчеризації |
|
||||
| `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегата надсилання та планування payload |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби payload медіа агента | Конструктор payload медіа агента для застарілих макетів полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу |
|
||||
| `plugin-sdk/channel-lifecycle` | Допоміжні функції стану облікового запису та життєвого циклу чернеткового потоку | `createAccountStatusSink`, допоміжні функції фіналізації чернеткового попереднього перегляду |
|
||||
| `plugin-sdk/inbound-envelope` | Допоміжні функції вхідного envelope | Спільні допоміжні функції маршруту + builder-а envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції record-and-dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні функції вихідного runtime | Допоміжні функції вихідної ідентичності/send delegate і планування payload |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу та адаптера thread-binding |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder media payload агента для застарілих схем полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді |
|
||||
| `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення Plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Допоміжні засоби logger/середовища runtime, timeout, retry та backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime Plugin | Допоміжні засоби команд/хуків/http/інтерактивності Plugin |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра хуків | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Клієнт Gateway і допоміжні засоби патчів статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільною резервною поведінкою, коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби запитів approval | Допоміжні засоби payload approval exec/Plugin, можливостей/профілів approval, нативної маршрутизації/runtime approval |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілю/фільтра нативного approval exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери нативних можливостей/доставки approval |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway для approval | Спільний допоміжний засіб визначення Gateway для approval |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження адаптера нативного approval для гарячих точок входу каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби runtime обробника approval; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілей/облікових записів нативного approval |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval exec/Plugin |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні засоби контексту runtime каналу | Загальні допоміжні засоби register/get/watch для контексту runtime каналу |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби контролю діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/plugin-install |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Допоміжні функції logger/runtime env, timeout, retry і backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime Plugin | Допоміжні функції команд/hook/http/interactive для Plugin |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра hook | Спільні допоміжні функції конвеєра webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні функції runtime CLI | Форматування команд, очікування, допоміжні функції версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні функції Gateway | Допоміжні функції клієнта Gateway і patch стану каналів |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції запитів на підтвердження | Payload підтвердження exec/plugin, допоміжні функції capability/profile підтвердження, нативні допоміжні функції маршрутизації/runtime підтвердження |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції auth для підтвердження | Визначення користувача, що підтверджує, auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції клієнта підтвердження | Допоміжні функції profile/filter для нативного підтвердження exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки підтверджень | Адаптери capability/delivery нативного підтвердження |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Допоміжні функції Gateway для підтвердження | Спільна допоміжна функція визначення approval gateway |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні функції адаптера підтвердження | Легковагові допоміжні функції завантаження адаптера нативного підтвердження для гарячих точок входу каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Допоміжні функції обробника підтвердження | Ширші допоміжні функції runtime обробника підтвердження; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей підтвердження | Допоміжні функції нативного зв’язування цілі/облікового запису підтвердження |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції відповіді на підтвердження | Допоміжні функції payload відповіді на підтвердження exec/plugin |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні функції channel runtime-context | Загальні допоміжні функції register/get/watch для channel runtime-context |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції trust, обмеження DM, external-content і збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції runtime SSRF | Допоміжні функції pinned-dispatcher, guarded fetch, політики SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні функції обмеження діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні функції wrapped fetch/proxy | `resolveFetch`, допоміжні функції proxy |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, запускальники політик |
|
||||
| `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Допоміжні засоби контролю команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд |
|
||||
| `plugin-sdk/command-status` | Відображувачі стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
|
||||
| `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби guards для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Вхідна диспетчеризація, Heartbeat, планувальник відповідей, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Фіналізація, диспетчеризація provider і допоміжні засоби міток розмов |
|
||||
| `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні засоби чанків відповідей | Допоміжні засоби чанкінгу тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключів сесій | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації ключів сесій |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори підсумку статусу каналу/облікового запису, значення стану runtime за замовчуванням, допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілі | Спільні допоміжні засоби визначення цілі |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягання рядкових URL з вхідних даних, подібних до запиту |
|
||||
| `plugin-sdk/run-command` | Допоміжні засоби команд із timeout | Виконавець команд із timeout і нормалізованими stdout/stderr |
|
||||
| `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Обмеження команд і допоміжні функції поверхні команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд |
|
||||
| `plugin-sdk/command-status` | Рендерери стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
|
||||
| `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні функції запитів Webhook | Утиліти цілі Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції guard для тіла запиту Webhook | Допоміжні функції читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідний dispatch, Heartbeat, планувальник відповіді, розбиття на частини |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповіді | Фіналізація, dispatch provider і допоміжні функції міток розмов |
|
||||
| `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні функції частин відповіді | Допоміжні функції розбиття тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні функції сховища сесій | Допоміжні функції шляху сховища + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції каталогів стану та OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні функції маршрутизації/ключів сесій | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації ключів сесій |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні функції стану каналів | Builder-и підсумків стану каналу/облікового запису, типові значення 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` | Читачі параметрів | Загальні читачі параметрів інструментів/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягання payload інструмента | Витягання нормалізованих payload з об’єктів результатів інструментів |
|
||||
| `plugin-sdk/tool-send` | Витягання надсилання інструмента | Витягання канонічних полів цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистем і редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць |
|
||||
| `plugin-sdk/reply-payload` | Типи payload відповідей | Типи payload відповідей |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | Допоміжні засоби виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime provider | Допоміжні засоби визначення API-ключа runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа provider | Допоміжні засоби онбордингу/запису профілю API-ключа |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth provider | Стандартний конструктор результату auth OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу |
|
||||
| `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору provider | Вибір налаштованого або автоматичного provider і злиття сирої конфігурації provider |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби змінних середовища provider | Допоміжні засоби пошуку змінних середовища auth provider |
|
||||
| `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/повторного відтворення provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик replay, допоміжні засоби endpoint provider і нормалізації ідентифікаторів моделей |
|
||||
| `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Патчі онбордингу provider | Допоміжні засоби конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Загальні допоміжні засоби HTTP/можливостей endpoint provider, включно з допоміжними засобами multipart form для аудіотранскрипції |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/кешу web-fetch provider |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації вебпошуку provider | Вузькі допоміжні засоби конфігурації/облікових даних вебпошуку для provider, яким не потрібне підключення ввімкнення Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту вебпошуку provider | Вузькі допоміжні засоби контракту конфігурації/облікових даних вебпошуку, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-сетери/гетери облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби вебпошуку provider | Допоміжні засоби реєстрації/кешу/runtime вебпошуку provider |
|
||||
| `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Допоміжні засоби використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання provider |
|
||||
| `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту provider | Нативні допоміжні засоби транспорту provider, як-от guarded fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій |
|
||||
| `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload із об’єктів результату інструмента |
|
||||
| `plugin-sdk/tool-send` | Витягування send інструмента | Витягування канонічних полів цілі send з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції тимчасових шляхів для завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні функції logging | Допоміжні функції logger підсистеми та редагування конфіденційних даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні функції таблиць Markdown | Допоміжні функції режиму таблиць Markdown |
|
||||
| `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload відповіді |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локального/self-hosted provider | Допоміжні функції виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted provider |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime auth для provider | Допоміжні функції визначення API-ключа під час виконання |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування API-ключа provider | Допоміжні функції onboarding/запису profile для API-ключа |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні функції auth-result для provider | Стандартний builder auth-result OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу provider | Спільні допоміжні функції інтерактивного входу |
|
||||
| `plugin-sdk/provider-selection-runtime` | Допоміжні функції вибору provider | Вибір provider за конфігурацією або автоматично та злиття сирої конфігурації provider |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції env var для provider | Допоміжні функції пошуку env var auth для provider |
|
||||
| `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и політики replay, допоміжні функції endpoint provider і нормалізації model-id |
|
||||
| `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Патчі onboarding для provider | Допоміжні функції конфігурації onboarding |
|
||||
| `plugin-sdk/provider-http` | Допоміжні функції HTTP для provider | Загальні допоміжні функції HTTP/можливостей endpoint для provider, включно з допоміжними функціями multipart form для транскрибування аудіо |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch для provider | Допоміжні функції реєстрації/кешу provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Допоміжні функції конфігурації web-search для provider | Вузькі допоміжні функції конфігурації/облікових даних web-search для provider, яким не потрібна прив’язка вмикання Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search для provider | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні функції web-search для provider | Допоміжні функції реєстрації/кешу/runtime для provider web-search |
|
||||
| `plugin-sdk/provider-tools` | Допоміжні функції сумісності інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Допоміжні функції usage для provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції usage для provider |
|
||||
| `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні функції транспорту provider | Нативні допоміжні функції транспорту provider, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій writable transport |
|
||||
| `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/зберігання медіа, а також конструктори payload медіа |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні засоби розуміння медіа | Типи provider для розуміння медіа, а також експорти допоміжних засобів зображень/аудіо для provider |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, допоміжні засоби рендерингу/chunking/table markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні засоби чанкінгу тексту | Допоміжний засіб чанкінгу вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи provider мовлення, а також допоміжні засоби директив, реєстру та валідації для provider |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції отримання/перетворення/збереження медіа плюс builder-и media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні функції розуміння медіа | Типи provider для розуміння медіа плюс експорти допоміжних функцій зображень/аудіо для provider |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Вилучення видимого асистенту тексту, допоміжні функції рендерингу/розбиття/таблиць markdown, редагування конфіденційних даних, допоміжні функції тегів директив, утиліти безпечного тексту та пов’язані допоміжні функції тексту/logging |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні функції розбиття тексту | Допоміжна функція розбиття вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні функції мовлення | Типи provider мовлення плюс допоміжні функції директив, реєстру та перевірки для provider |
|
||||
| `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи provider мовлення, реєстр, директиви, нормалізація |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в realtime | Типи provider, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в realtime | Типи provider, допоміжні засоби реєстру/визначення та допоміжні засоби bridge-сесій |
|
||||
| `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, auth і допоміжні засоби реєстру |
|
||||
| `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи provider/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи provider/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні функції транскрибування в реальному часі | Типи provider, допоміжні функції реєстру та спільна допоміжна функція сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні функції голосу в реальному часі | Типи provider, допоміжні функції реєстру/визначення та допоміжні функції bridge session |
|
||||
| `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, допоміжні функції failover, auth і реєстру |
|
||||
| `plugin-sdk/music-generation` | Допоміжні функції генерації музики | Типи provider/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні функції failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Допоміжні функції генерації відео | Типи provider/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні функції failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/зменшення payload інтерактивних відповідей |
|
||||
| `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви config-schema каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude Plugin каналу |
|
||||
| `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо доступу до груп |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні засоби прямих DM | Спільні допоміжні засоби auth/guard для прямих DM |
|
||||
| `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів пасивного каналу/статусу та ambient proxy |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook та встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддаленого/локального медіа |
|
||||
| `plugin-sdk/zod` | Повторний експорт zod | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів менеджера/config/файлів/CLI пам’яті |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude channel plugin |
|
||||
| `plugin-sdk/channel-status` | Допоміжні функції стану каналу | Спільні допоміжні функції snapshot/summary стану каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні функції доступу до груп | Спільні допоміжні функції ухвалення рішень щодо доступу до груп |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні функції прямих DM | Спільні допоміжні функції auth/guard для прямих DM |
|
||||
| `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви допоміжних функцій passive-channel/status і ambient proxy |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні функції цілей Webhook | Реєстр цілей Webhook і допоміжні функції встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні функції шляху Webhook | Допоміжні функції нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні функції вебмедіа | Допоміжні функції завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для користувачів SDK Plugin |
|
||||
| `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` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і загальні допоміжні засоби batch/remote; конкретні remote provider містяться у Plugin, яким вони належать |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби мультимодального хоста пам’яті | Допоміжні засоби мультимодального хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні засоби core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Експорти рушія foundation хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і загальні допоміжні функції batch/remote; конкретні remote provider містяться у Plugin-власниках |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Рушій storage хоста пам’яті | Експорти рушія storage хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції 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 хоста пам’яті | Допоміжні функції runtime CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні функції core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | Допоміжні функції файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для Plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb |
|
||||
| `plugin-sdk/testing` | Тестові утиліти | Допоміжні засоби тестування та mocks |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім стану хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій стану хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Вбудовані допоміжні функції memory-lancedb | Поверхня допоміжних функцій memory-lancedb |
|
||||
| `plugin-sdk/testing` | Тестові утиліти | Допоміжні функції та mock-и для тестування |
|
||||
</Accordion>
|
||||
|
||||
Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною поверхнею SDK. Повний список із понад 200 точок входу міститься в
|
||||
Ця таблиця навмисно містить поширену підмножину для міграції, а не всю поверхню
|
||||
SDK. Повний список із понад 200 точок входу міститься в
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Цей список усе ще містить деякі шви допоміжних засобів вбудованих Plugin, як-от
|
||||
Цей список усе ще включає деякі допоміжні seams для вбудованих Plugin, такі як
|
||||
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
|
||||
`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для
|
||||
підтримки та сумісності вбудованих Plugin, але навмисно не включені до
|
||||
поширеної таблиці міграції та не є рекомендованою ціллю для нового коду Plugin.
|
||||
`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони залишаються експортованими для
|
||||
підтримки та сумісності вбудованих Plugin, але навмисно
|
||||
опущені з таблиці поширеної міграції й не є рекомендованою ціллю для
|
||||
нового коду Plugin.
|
||||
|
||||
Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як:
|
||||
Те саме правило застосовується до інших сімейств вбудованих допоміжних функцій, таких як:
|
||||
|
||||
- допоміжні засоби підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
|
||||
- допоміжні функції підтримки браузера: `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`,
|
||||
- поверхні вбудованих допоміжних функцій/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`,
|
||||
@ -393,7 +431,7 @@ 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` наразі надає вузьку поверхню допоміжних засобів токена:
|
||||
`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних функцій токенів
|
||||
`DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`.
|
||||
|
||||
@ -402,18 +440,18 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
## Активні застарівання
|
||||
|
||||
Вужчі застарівання, які застосовуються в усьому Plugin SDK, контракті provider,
|
||||
поверхні runtime і маніфесті. Кожен із них іще працює сьогодні, але буде видалений
|
||||
у майбутньому мажорному релізі. Запис під кожним елементом зіставляє старий API з його
|
||||
Вужчі застарівання, які застосовуються в SDK Plugin, контракті provider,
|
||||
поверхні runtime і manifest. Кожне з них усе ще працює сьогодні, але буде видалене
|
||||
в одному з майбутніх мажорних випусків. Запис під кожним елементом зіставляє старий API з його
|
||||
канонічною заміною.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Конструктори довідки command-auth → command-status">
|
||||
<Accordion title="builder-и довідки command-auth → command-status">
|
||||
**Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`,
|
||||
`buildCommandsMessagePaginated`, `buildHelpMessage`.
|
||||
|
||||
**Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі
|
||||
експорти — лише імпортовані з вужчого підшляху. `command-auth`
|
||||
експорти — просто імпортуються з вужчого підшляху. `command-auth`
|
||||
повторно експортує їх як compat-заглушки.
|
||||
|
||||
```typescript
|
||||
@ -426,96 +464,97 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Допоміжні засоби gating згадок → resolveInboundMentionDecision">
|
||||
<Accordion title="Допоміжні функції обмеження згадок → resolveInboundMentionDecision">
|
||||
**Старе**: `resolveInboundMentionRequirement({ facts, policy })` і
|
||||
`shouldDropInboundForMention(...)` з
|
||||
`openclaw/plugin-sdk/channel-inbound` або
|
||||
`openclaw/plugin-sdk/channel-mention-gating`.
|
||||
|
||||
**Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає
|
||||
єдиний об’єкт рішення замість двох розділених викликів.
|
||||
один об’єкт рішення замість двох розділених викликів.
|
||||
|
||||
Низхідні Plugin каналів (Slack, Discord, Matrix, MS Teams) уже
|
||||
перейшли на це.
|
||||
Downstream channel Plugin (Slack, Discord, Matrix, Microsoft Teams) уже
|
||||
перейшли.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Shim runtime каналу та допоміжні засоби дій каналу">
|
||||
<Accordion title="shim channel runtime і допоміжні функції дій каналу">
|
||||
`openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших
|
||||
Plugin каналів. Не імпортуйте його в новому коді; використовуйте
|
||||
`openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів
|
||||
runtime.
|
||||
channel Plugin. Не імпортуйте його в новому коді; використовуйте
|
||||
`openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів runtime.
|
||||
|
||||
Допоміжні засоби `channelActions*` у `openclaw/plugin-sdk/channel-actions` застаріли
|
||||
разом із сирими експортами дій каналу. Натомість надавайте можливості через
|
||||
семантичну поверхню `presentation` — Plugin каналів оголошують, що саме вони рендерять
|
||||
(картки, кнопки, списки вибору), а не які сирі назви дій вони приймають.
|
||||
Допоміжні функції `channelActions*` в `openclaw/plugin-sdk/channel-actions`
|
||||
застарівають разом із сирими експортами channel "actions". Натомість показуйте можливості
|
||||
через семантичну поверхню `presentation` — channel Plugin оголошують, що саме вони
|
||||
відображають (картки, кнопки, списки вибору), а не те, які сирі назви
|
||||
дій вони приймають.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Допоміжний засіб tool() provider вебпошуку → createTool() у Plugin">
|
||||
<Accordion title="Допоміжна функція tool() provider web search → createTool() у Plugin">
|
||||
**Старе**: фабрика `tool()` з `openclaw/plugin-sdk/provider-web-search`.
|
||||
|
||||
**Нове**: реалізуйте `createTool(...)` безпосередньо в Plugin provider.
|
||||
OpenClaw більше не потрібен допоміжний засіб SDK для реєстрації обгортки інструмента.
|
||||
OpenClaw більше не потребує допоміжної функції SDK для реєстрації обгортки інструмента.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Текстові channel envelope → BodyForAgent">
|
||||
<Accordion title="Текстові plaintext channel envelope → BodyForAgent">
|
||||
**Старе**: `formatInboundEnvelope(...)` (і
|
||||
`ChannelMessageForAgent.channelEnvelope`) для побудови плоского текстового prompt-envelope
|
||||
із вхідних повідомлень каналу.
|
||||
`ChannelMessageForAgent.channelEnvelope`) для побудови плоского plaintext prompt
|
||||
envelope із вхідних channel-повідомлень.
|
||||
|
||||
**Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Plugin
|
||||
каналів прикріплюють метадані маршрутизації (потік, тему, reply-to, реакції) як
|
||||
типізовані поля замість конкатенації їх у рядок prompt. Допоміжний засіб
|
||||
`formatAgentEnvelope(...)` і далі підтримується для синтезованих envelope,
|
||||
орієнтованих на асистента, але вхідні текстові envelope поступово виводяться з ужитку.
|
||||
**Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Channel
|
||||
Plugin додають метадані маршрутизації (гілка, тема, reply-to, реакції) як
|
||||
типізовані поля замість конкатенації їх у рядок prompt. Допоміжна функція
|
||||
`formatAgentEnvelope(...)` усе ще підтримується для синтезованих
|
||||
envelope, видимих асистенту, але вхідні plaintext envelope поступово
|
||||
виводяться з ужитку.
|
||||
|
||||
Зачеплені області: `inbound_claim`, `message_received` і будь-який користувацький
|
||||
Plugin каналу, який постобробляв текст `channelEnvelope`.
|
||||
Зачеплені області: `inbound_claim`, `message_received` і будь-який власний
|
||||
channel Plugin, який постобробляв текст `channelEnvelope`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Типи виявлення provider → типи каталогу provider">
|
||||
Чотири псевдоніми типів виявлення тепер є тонкими обгортками над типами
|
||||
ери каталогу:
|
||||
<Accordion title="Типи discovery provider → типи каталогу provider">
|
||||
Чотири псевдоніми типів discovery тепер є тонкими обгортками над типами
|
||||
епохи каталогу:
|
||||
|
||||
| Старий псевдонім | Новий тип |
|
||||
| --------------------------- | ------------------------- |
|
||||
| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
|
||||
| `ProviderDiscoveryContext` | `ProviderCatalogContext` |
|
||||
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
|
||||
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
|
||||
| Старий псевдонім | Новий тип |
|
||||
| -------------------------- | ----------------------- |
|
||||
| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
|
||||
| `ProviderDiscoveryContext` | `ProviderCatalogContext`|
|
||||
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
|
||||
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
|
||||
|
||||
Плюс застарілий статичний набір `ProviderCapabilities` — Plugin provider
|
||||
повинні прикріплювати факти можливостей через контракт runtime provider,
|
||||
мають прикріплювати capability facts через контракт runtime provider,
|
||||
а не через статичний об’єкт.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Хуки політики Thinking → resolveThinkingProfile">
|
||||
**Старе** (три окремі хуки в `ProviderThinkingPolicy`):
|
||||
<Accordion title="Hook політики thinking → resolveThinkingProfile">
|
||||
**Старе** (три окремі hook на `ProviderThinkingPolicy`):
|
||||
`isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і
|
||||
`resolveDefaultThinkingLevel(ctx)`.
|
||||
|
||||
**Нове**: один `resolveThinkingProfile(ctx)`, який повертає
|
||||
`ProviderThinkingProfile` з канонічним `id`, необов’язковим `label` і
|
||||
`ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і
|
||||
ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені значення
|
||||
за рангом профілю.
|
||||
|
||||
Реалізуйте один хук замість трьох. Застарілі хуки продовжують працювати впродовж
|
||||
вікна застарівання, але не комбінуються з результатом профілю.
|
||||
Реалізуйте один hook замість трьох. Застарілі hook продовжують працювати протягом
|
||||
періоду застарівання, але не поєднуються з результатом профілю.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Резервний шлях зовнішнього OAuth provider → contracts.externalAuthProviders">
|
||||
<Accordion title="Резервний варіант зовнішнього OAuth provider → contracts.externalAuthProviders">
|
||||
**Старе**: реалізація `resolveExternalOAuthProfiles(...)` без
|
||||
оголошення provider у маніфесті Plugin.
|
||||
оголошення provider у manifest Plugin.
|
||||
|
||||
**Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті Plugin
|
||||
**і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях
|
||||
«резервного auth» видає попередження під час виконання й буде видалений.
|
||||
**Нове**: оголосіть `contracts.externalAuthProviders` у manifest Plugin
|
||||
**і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях "auth
|
||||
fallback" виводить попередження під час виконання й буде видалений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -527,41 +566,41 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Пошук env vars provider → setup.providers[].envVars">
|
||||
**Старе** поле маніфесту: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`.
|
||||
<Accordion title="Пошук env var для provider → setup.providers[].envVars">
|
||||
**Старе** поле manifest: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`.
|
||||
|
||||
**Нове**: віддзеркальте той самий пошук env vars у `setup.providers[].envVars`
|
||||
в маніфесті. Це об’єднує метадані env налаштування/статусу в одному
|
||||
місці й дозволяє уникнути запуску runtime Plugin лише для того, щоб відповісти на
|
||||
запити щодо env vars.
|
||||
**Нове**: продублюйте той самий пошук env var у `setup.providers[].envVars`
|
||||
в manifest. Це об’єднує метадані env налаштування/стану в одному
|
||||
місці й дозволяє уникнути запуску runtime Plugin лише для відповіді на
|
||||
запити пошуку env var.
|
||||
|
||||
`providerAuthEnvVars` і далі підтримується через адаптер сумісності
|
||||
до завершення вікна застарівання.
|
||||
`providerAuthEnvVars` залишається підтримуваним через адаптер сумісності
|
||||
до завершення періоду застарівання.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Реєстрація Plugin пам’яті → registerMemoryCapability">
|
||||
<Accordion title="Реєстрація memory Plugin → registerMemoryCapability">
|
||||
**Старе**: три окремі виклики —
|
||||
`api.registerMemoryPromptSection(...)`,
|
||||
`api.registerMemoryFlushPlan(...)`,
|
||||
`api.registerMemoryRuntime(...)`.
|
||||
|
||||
**Нове**: один виклик у API стану пам’яті —
|
||||
**Нове**: один виклик до API memory-state —
|
||||
`registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`.
|
||||
|
||||
Ті самі слоти, один виклик реєстрації. Адитивні допоміжні засоби пам’яті
|
||||
Ті самі слоти, один виклик реєстрації. Додаткові допоміжні функції memory
|
||||
(`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`,
|
||||
`registerMemoryEmbeddingProvider`) це не зачіпає.
|
||||
`registerMemoryEmbeddingProvider`) не зачеплені.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Типи повідомлень сесії subagent перейменовано">
|
||||
Два застарілі псевдоніми типів і далі експортуються з `src/plugins/runtime/types.ts`:
|
||||
<Accordion title="Типи повідомлень сесії субагента перейменовано">
|
||||
Два застарілі псевдоніми типів усе ще експортуються з `src/plugins/runtime/types.ts`:
|
||||
|
||||
| Старе | Нове |
|
||||
| ---------------------------- | ------------------------------- |
|
||||
| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
|
||||
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
|
||||
| Старе | Нове |
|
||||
| --------------------------- | ------------------------------ |
|
||||
| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
|
||||
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
|
||||
|
||||
Метод runtime `readSession` застарів на користь
|
||||
`getSessionMessages`. Та сама сигнатура; старий метод викликає
|
||||
@ -570,10 +609,10 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="runtime.tasks.flow → runtime.tasks.flows">
|
||||
**Старе**: `runtime.tasks.flow` (в однині) повертав засіб доступу до live TaskFlow.
|
||||
**Старе**: `runtime.tasks.flow` (в однині) повертав accessor живого TaskFlow.
|
||||
|
||||
**Нове**: `runtime.tasks.flows` (у множині) повертає доступ до TaskFlow на основі DTO,
|
||||
який безпечний для імпорту й не потребує завантаження повного runtime завдань.
|
||||
який безпечний для імпорту та не вимагає завантаження повного runtime завдань.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -584,17 +623,17 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Фабрики вбудованих extension → middleware результатів інструментів агента">
|
||||
Розглянуто вище в розділі «Як мігрувати → Мігруйте розширення результатів інструментів Pi на
|
||||
middleware». Тут наведено для повноти: шлях лише для Pi
|
||||
<Accordion title="Embedded extension factories → middleware agent tool-result">
|
||||
Розглянуто вище в розділі "Як виконати міграцію → Мігруйте розширення Pi tool-result на
|
||||
middleware". Додано тут для повноти: шлях лише для Pi
|
||||
`api.registerEmbeddedExtensionFactory(...)` застарів на користь
|
||||
`api.registerAgentToolResultMiddleware(...)` з явним списком harness
|
||||
у `contracts.agentToolResultMiddleware`.
|
||||
`api.registerAgentToolResultMiddleware(...)` з явним списком runtime в
|
||||
`contracts.agentToolResultMiddleware`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Псевдонім OpenClawSchemaType → OpenClawConfig">
|
||||
`OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є
|
||||
однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу канонічній назві.
|
||||
`OpenClawSchemaType`, повторно експортований із `openclaw/plugin-sdk`, тепер є
|
||||
однорядковим псевдонімом для `OpenClawConfig`. Віддавайте перевагу канонічній назві.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -607,11 +646,11 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
Застарівання на рівні extension (усередині вбудованих Plugin каналів/provider у
|
||||
`extensions/`) відстежуються у власних barrel-файлах `api.ts` і `runtime-api.ts`.
|
||||
Застарівання на рівні extension (усередині вбудованих channel/provider Plugin у
|
||||
`extensions/`) відстежуються у власних barrels `api.ts` і `runtime-api.ts`.
|
||||
Вони не впливають на контракти сторонніх Plugin і тут не перелічені.
|
||||
Якщо ви напряму споживаєте локальний barrel вбудованого Plugin, прочитайте
|
||||
коментарі щодо застарівання в цьому barrel перед оновленням.
|
||||
Якщо ви споживаєте локальний barrel вбудованого Plugin напряму, прочитайте
|
||||
коментарі про застарівання в цьому barrel перед оновленням.
|
||||
</Note>
|
||||
|
||||
## Часова шкала видалення
|
||||
@ -619,12 +658,12 @@ OpenClaw не видаляє й не переосмислює задокумен
|
||||
| Коли | Що відбувається |
|
||||
| ---------------------- | ---------------------------------------------------------------------- |
|
||||
| **Зараз** | Застарілі поверхні виводять попередження під час виконання |
|
||||
| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; Plugin, які досі їх використовують, перестануть працювати |
|
||||
| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; Plugin, які все ще їх використовують, перестануть працювати |
|
||||
|
||||
Усі core Plugin уже мігровано. Зовнішнім Plugin слід виконати
|
||||
міграцію до наступного мажорного релізу.
|
||||
Усі core Plugin уже мігровані. Зовнішні Plugin мають виконати міграцію
|
||||
до наступного мажорного випуску.
|
||||
|
||||
## Тимчасове приглушення попереджень
|
||||
## Тимчасове придушення попереджень
|
||||
|
||||
Установіть ці змінні середовища, поки працюєте над міграцією:
|
||||
|
||||
@ -633,13 +672,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
|
||||
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
|
||||
```
|
||||
|
||||
Це тимчасовий обхідний механізм, а не постійне рішення.
|
||||
Це тимчасовий обхідний шлях, а не постійне рішення.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin
|
||||
- [Початок роботи](/uk/plugins/building-plugins) — створення вашого першого Plugin
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів
|
||||
- [Plugin каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin каналів
|
||||
- [Plugin provider](/uk/plugins/sdk-provider-plugins) — створення Plugin provider
|
||||
- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибоке занурення в архітектуру
|
||||
- [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту
|
||||
- [Channel Plugin](/uk/plugins/sdk-channel-plugins) — створення channel Plugin
|
||||
- [Provider Plugin](/uk/plugins/sdk-provider-plugins) — створення provider Plugin
|
||||
- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибокий огляд архітектури
|
||||
- [Manifest Plugin](/uk/plugins/manifest) — довідник зі схеми manifest
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Потрібно знати, з якого підшляху SDK імпортувати
|
||||
- Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Вам потрібно знати, з якого підшляху SDK імпортувати
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
sidebarTitle: SDK overview
|
||||
summary: Карта імпорту, довідник з API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд SDK Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:32:17Z"
|
||||
generated_at: "2026-04-25T00:02:50Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7b7b69a59c39d3abd5c70a1420e2f43da0470f66d283d76f069b0e77a5bf1551
|
||||
source_hash: ac8b101bc7a7c78a88311dc196ba5cacb78c5fe708f0749e47bde6b6d7f1c9df
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка —
|
||||
довідник про **що імпортувати** і **що можна реєструвати**.
|
||||
SDK Plugin — це типізований контракт між plugins і core. Ця сторінка —
|
||||
довідник про **що імпортувати** і **що можна зареєструвати**.
|
||||
|
||||
<Tip>
|
||||
Шукаєте натомість практичний посібник?
|
||||
|
||||
- Перший плагін? Почніть із [Створення плагінів](/uk/plugins/building-plugins).
|
||||
- Плагін каналу? Дивіться [Плагіни каналів](/uk/plugins/sdk-channel-plugins).
|
||||
- Плагін провайдера? Дивіться [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins).
|
||||
- Плагін інструмента або хука життєвого циклу? Дивіться [Хуки плагінів](/uk/plugins/hooks).
|
||||
- Перший Plugin? Почніть з [Building plugins](/uk/plugins/building-plugins).
|
||||
- Plugin каналу? Див. [Channel plugins](/uk/plugins/sdk-channel-plugins).
|
||||
- Plugin постачальника? Див. [Provider plugins](/uk/plugins/sdk-provider-plugins).
|
||||
- Plugin інструмента або lifecycle hook? Див. [Plugin hooks](/uk/plugins/hooks).
|
||||
</Tip>
|
||||
|
||||
## Угода щодо імпорту
|
||||
## Правило імпорту
|
||||
|
||||
Завжди імпортуйте з конкретного підшляху:
|
||||
|
||||
@ -38,112 +38,112 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і
|
||||
запобігає проблемам із циклічними залежностями. Для специфічних для каналу
|
||||
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
|
||||
ширшої поверхні-парасольки та спільних допоміжних засобів, таких як
|
||||
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для
|
||||
ширшої umbrella-поверхні та спільних допоміжних засобів, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
<Warning>
|
||||
Не імпортуйте branded convenience seams для провайдерів або каналів (наприклад
|
||||
Не імпортуйте branded convenience seams постачальника або каналу (наприклад
|
||||
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
|
||||
Вбудовані плагіни поєднують загальні підшляхи SDK у власних barrel-файлах `api.ts` /
|
||||
`runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для плагіна
|
||||
barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді
|
||||
Вбудовані plugins компонує загальні підшляхи SDK у власних barrel-файлах `api.ts` /
|
||||
`runtime-api.ts`; споживачі core мають або використовувати ці локальні для plugin
|
||||
barrel-файли, або додавати вузький загальний контракт SDK, коли потреба справді
|
||||
є міжканальною.
|
||||
|
||||
Невеликий набір helper seams для вбудованих плагінів (`plugin-sdk/feishu`,
|
||||
Невеликий набір допоміжних seams для вбудованих plugins (`plugin-sdk/feishu`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в
|
||||
згенерованій карті експортів. Вони існують лише для супроводу вбудованих плагінів і
|
||||
не рекомендуються як шляхи імпорту для нових сторонніх плагінів.
|
||||
згенерованій карті експорту. Вони існують лише для підтримки вбудованих plugins і
|
||||
не рекомендуються як шляхи імпорту для нових сторонніх plugins.
|
||||
</Warning>
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
Plugin SDK доступний як набір вузьких підшляхів, згрупованих за областями (entry
|
||||
плагіна, канал, провайдер, auth, runtime, capability, memory і зарезервовані
|
||||
helper-модулі для вбудованих плагінів). Повний каталог — згрупований і з посиланнями — дивіться в
|
||||
[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
|
||||
SDK Plugin доступний як набір вузьких підшляхів, згрупованих за областями (plugin
|
||||
entry, channel, provider, auth, runtime, capability, memory і зарезервовані
|
||||
допоміжні засоби для вбудованих plugins). Повний каталог — згрупований і з посиланнями — див. у
|
||||
[Plugin SDK subpaths](/uk/plugins/sdk-subpaths).
|
||||
|
||||
Згенерований список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
## API реєстрації
|
||||
|
||||
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` із такими
|
||||
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------------ | ----------------------------------- |
|
||||
| ----------------------------------------------- | ----------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
|
||||
| `api.registerCliBackend(...)` | Локальний backend inference для CLI |
|
||||
| `api.registerCliBackend(...)` | Локальний бекенд inference CLI |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Синтез мовлення / STT |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
|
||||
| `api.registerWebFetchProvider(...)` | Постачальник web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
|
||||
### Інструменти та команди
|
||||
### Інструменти й команди
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------- | ------------------------------------------- |
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------ | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
|
||||
### Інфраструктура
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ----------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Хук події |
|
||||
| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway |
|
||||
| ---------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Event hook |
|
||||
| `api.registerHttpRoute(params)` | HTTP-кінцева точка Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | Рекламування локального виявлення Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | Локальний сервіс анонсування виявлення Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фоновий сервіс |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструментів harness |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструментів під час виконання |
|
||||
| `api.registerEmbeddedExtensionFactory(factory)` | Застаріла фабрика розширень PI |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ промпта, суміжний із пам’яттю |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті |
|
||||
|
||||
<Note>
|
||||
Зарезервовані простори назв адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити
|
||||
вужчу область дії для методу gateway. Для методів, що належать плагіну, віддавайте перевагу
|
||||
префіксам, специфічним для плагіна.
|
||||
Зарезервовані простори назв адміністратора core (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити
|
||||
вужчу область для методу gateway. Віддавайте перевагу специфічним для plugin префіксам для
|
||||
методів, що належать plugin.
|
||||
</Note>
|
||||
|
||||
<Accordion title="Коли використовувати middleware результатів інструментів">
|
||||
Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
|
||||
їм потрібно переписати результат інструмента після виконання і до того, як harness
|
||||
передасть цей результат назад у модель. Це довірений, нейтральний щодо harness
|
||||
seam для асинхронних редукторів виводу, таких як tokenjuice.
|
||||
Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
|
||||
їм потрібно переписати результат інструмента після виконання і до того, як runtime
|
||||
поверне цей результат назад у модель. Це довірений, нейтральний до runtime seam для
|
||||
асинхронних редукторів виводу, таких як tokenjuice.
|
||||
|
||||
Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного
|
||||
цільового harness, наприклад `["pi", "codex-app-server"]`. Зовнішні плагіни
|
||||
не можуть реєструвати це middleware; для роботи, якій не потрібен час обробки
|
||||
результату інструмента до моделі, залишайте звичайні хуки плагінів OpenClaw.
|
||||
Вбудовані plugins мають оголошувати `contracts.agentToolResultMiddleware` для кожного
|
||||
цільового runtime, наприклад `["pi", "codex"]`. Зовнішні plugins
|
||||
не можуть реєструвати це middleware; для роботи, якій не потрібен момент
|
||||
до подачі результату інструмента в модель, використовуйте звичайні Plugin hooks OpenClaw.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Застарілі фабрики розширень Pi">
|
||||
`api.registerEmbeddedExtensionFactory(...)` є застарілим. Він залишається
|
||||
сумісним seam для вбудованих плагінів, яким усе ще потрібні прямі події
|
||||
embedded-runner Pi. Нові перетворення результатів інструментів натомість мають використовувати
|
||||
`api.registerAgentToolResultMiddleware(...)`.
|
||||
сумісним seam для вбудованих plugins, яким усе ще потрібні прямі події
|
||||
embedded-runner Pi. Нові трансформації результатів інструментів мають
|
||||
натомість використовувати `api.registerAgentToolResultMiddleware(...)`.
|
||||
</Accordion>
|
||||
|
||||
### Реєстрація виявлення Gateway
|
||||
|
||||
`api.registerGatewayDiscoveryService(...)` дозволяє плагіну рекламувати активний
|
||||
Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає сервіс
|
||||
під час запуску Gateway, коли локальне виявлення ввімкнене, передає поточні
|
||||
порти Gateway і несеκретні TXT-підказки, а під час завершення роботи Gateway
|
||||
викликає повернений обробник `stop`.
|
||||
`api.registerGatewayDiscoveryService(...)` дає Plugin змогу анонсувати активний
|
||||
Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає цей
|
||||
сервіс під час запуску Gateway, коли локальне виявлення ввімкнене, передає
|
||||
поточні порти Gateway і не секретні TXT-підказки, а потім викликає повернений
|
||||
обробник `stop` під час завершення роботи Gateway.
|
||||
|
||||
```typescript
|
||||
api.registerGatewayDiscoveryService({
|
||||
@ -159,21 +159,21 @@ api.registerGatewayDiscoveryService({
|
||||
});
|
||||
```
|
||||
|
||||
Плагіни виявлення Gateway не повинні розглядати рекламовані значення TXT як секрети або
|
||||
автентифікацію. Виявлення — це підказка для маршрутизації; довірою як і раніше керують
|
||||
автентифікація Gateway і pinning TLS.
|
||||
Plugins виявлення Gateway не повинні вважати опубліковані значення TXT секретами або
|
||||
автентифікацією. Виявлення — це підказка маршрутизації; довірою, auth Gateway і pinning TLS
|
||||
усе ще керують окремі механізми.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, що належать реєстратору
|
||||
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для довідки root CLI,
|
||||
маршрутизації та лінивої реєстрації CLI плагіна
|
||||
- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої допомоги CLI,
|
||||
маршрутизації та лінивої реєстрації CLI Plugin
|
||||
|
||||
Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному шляху root CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається
|
||||
цим реєстратором.
|
||||
Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному
|
||||
кореневому шляху CLI, надайте `descriptors`, що покривають кожен корінь команди верхнього рівня,
|
||||
який відкриває цей реєстратор.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -193,131 +193,129 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands`, тільки якщо вам не потрібна лінива реєстрація root CLI.
|
||||
Цей eager-сумісний шлях усе ще підтримується, але не встановлює
|
||||
плейсхолдери на основі дескрипторів для лінивого завантаження під час парсингу.
|
||||
Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореневого CLI.
|
||||
Цей eager-сумісний шлях залишається підтримуваним, але він не встановлює
|
||||
placeholder-елементи на основі descriptors для лінивого завантаження на етапі розбору.
|
||||
|
||||
### Реєстрація backend CLI
|
||||
### Реєстрація CLI-бекенду
|
||||
|
||||
`api.registerCliBackend(...)` дозволяє плагіну володіти конфігурацією за замовчуванням для локального
|
||||
backend AI CLI, такого як `codex-cli`.
|
||||
`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією локального
|
||||
AI CLI-бекенду, такого як `codex-cli`.
|
||||
|
||||
- `id` backend стає префіксом провайдера в посиланнях на моделі, таких як `codex-cli/gpt-5`.
|
||||
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
|
||||
стандартної конфігурації плагіна перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття
|
||||
(наприклад, нормалізації старих форм прапорців).
|
||||
- `id` бекенду стає префіксом постачальника в посиланнях на моделі, наприклад `codex-cli/gpt-5`.
|
||||
- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. Перед запуском CLI OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
|
||||
значень Plugin за замовчуванням.
|
||||
- Використовуйте `normalizeConfig`, якщо бекенду потрібні переписування сумісності після об’єднання
|
||||
(наприклад, нормалізація старих форм прапорців).
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до промпта. |
|
||||
| `api.registerMemoryCapability(capability)` | Єдина можливість пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу промпта пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
| Метод | Що він реєструє |
|
||||
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати додавання до prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt для пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для пам’яті |
|
||||
|
||||
### Адаптери embedding для пам’яті
|
||||
### Адаптери вбудовування пам’яті
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | -------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного плагіна |
|
||||
| --------------------------------------------- | -------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер вбудовування пам’яті для активного Plugin |
|
||||
|
||||
- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті.
|
||||
- `registerMemoryCapability` — це рекомендований API ексклюзивного Plugin для пам’яті.
|
||||
- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб плагіни-супутники могли споживати експортовані артефакти пам’яті через
|
||||
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури
|
||||
конкретного плагіна пам’яті.
|
||||
щоб супутні plugins могли споживати експортовані артефакти пам’яті через
|
||||
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватного
|
||||
макета конкретного Plugin пам’яті.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` — це сумісні зі старими версіями API ексклюзивного плагіна пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті реєструвати один
|
||||
або більше ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або
|
||||
користувацький ідентифікатор, визначений плагіном).
|
||||
- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і
|
||||
`registerMemoryRuntime` — це сумісні із застарілими версіями API ексклюзивного Plugin для пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дає активному Plugin пам’яті змогу реєструвати один
|
||||
або кілька id адаптерів вбудовування (наприклад `openai`, `gemini` або власний id, визначений plugin).
|
||||
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими
|
||||
ідентифікаторами адаптерів.
|
||||
id адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Метод | Що він робить |
|
||||
| -------------------------------------------- | --------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови |
|
||||
| Метод | Що він робить |
|
||||
| ------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook |
|
||||
| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови |
|
||||
|
||||
Дивіться [Хуки плагінів](/uk/plugins/hooks), щоб переглянути приклади, поширені назви хуків і
|
||||
семантику guard.
|
||||
Приклади, поширені назви hooks і семантику guard див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
|
||||
### Семантика рішень для хуків
|
||||
### Семантика рішень 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`), а не перевизначенням.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідного thread/topic. `metadata` залишайте для специфічних для каналу додаткових даних.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж повертатися до специфічного для каналу `metadata`.
|
||||
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні хуки `gateway:startup`.
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як якщо не вказувати `block`), а не перевизначенням.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як якщо не вказувати `block`), а не перевизначенням.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як якщо не вказувати `cancel`), а не перевизначенням.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для специфічних для каналу додаткових даних.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId` перед тим, як переходити до специфічного для каналу `metadata`.
|
||||
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить gateway, замість покладання на внутрішні hooks `gateway:startup`.
|
||||
|
||||
### Поля об’єкта API
|
||||
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Ідентифікатор плагіна |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія плагіна (необов’язково) |
|
||||
| `api.description` | `string?` | Опис плагіна (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела плагіна |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний внутрішній знімок runtime, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для плагіна, із `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна |
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Id Plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія Plugin (необов’язково) |
|
||||
| `api.description` | `string?` | Опис Plugin (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до вихідного коду Plugin |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Специфічна для Plugin конфігурація з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Розв’язання шляху відносно кореня plugin |
|
||||
|
||||
## Угода щодо внутрішніх модулів
|
||||
|
||||
Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Публічні експорти для зовнішніх споживачів
|
||||
runtime-api.ts # Експорти runtime лише для внутрішнього використання
|
||||
index.ts # Точка входу плагіна
|
||||
setup-entry.ts # Легка точка входу лише для setup (необов’язково)
|
||||
runtime-api.ts # Лише внутрішні експорти runtime
|
||||
index.ts # Точка входу Plugin
|
||||
setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Публічні поверхні вбудованих плагінів, завантажених через facade (`api.ts`, `runtime-api.ts`,
|
||||
Публічні поверхні вбудованих plugins, завантажуваних через facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу
|
||||
активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime
|
||||
ще не існує, вони повертаються до визначеного файлу конфігурації на диску.
|
||||
активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime
|
||||
ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску.
|
||||
|
||||
Плагіни провайдерів можуть надавати вузький локальний для плагіна контрактний barrel, коли
|
||||
допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK.
|
||||
Приклади вбудованих плагінів:
|
||||
Plugins постачальників можуть відкривати вузький barrel локального контракту plugin, коли
|
||||
допоміжний засіб навмисно є специфічним для постачальника й поки не належить до
|
||||
загального підшляху SDK. Приклади вбудованих plugins:
|
||||
|
||||
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для заголовка бета-функцій Claude
|
||||
та допоміжних засобів потоків `service_tier`.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` експортує builder-об’єкти провайдера,
|
||||
допоміжні засоби моделей за замовчуванням і builder-об’єкти провайдерів realtime.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера
|
||||
разом із допоміжними засобами onboarding/config.
|
||||
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для допоміжних засобів
|
||||
beta-header Claude і потоку `service_tier`.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` експортує конструктори постачальника,
|
||||
допоміжні засоби для типових моделей і конструктори постачальників realtime.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` експортує конструктор постачальника
|
||||
плюс допоміжні засоби onboarding/config.
|
||||
|
||||
<Warning>
|
||||
Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою.
|
||||
Якщо допоміжний засіб справді є спільним, підніміть його до нейтрального підшляху SDK,
|
||||
наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
@ -329,7 +327,7 @@ my-plugin/
|
||||
<Card title="Допоміжні засоби runtime" icon="gears" href="/uk/plugins/sdk-runtime">
|
||||
Повний довідник простору назв `api.runtime`.
|
||||
</Card>
|
||||
<Card title="Налаштування та конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
<Card title="Налаштування і конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
Пакування, маніфести та схеми конфігурації.
|
||||
</Card>
|
||||
<Card title="Тестування" icon="vial" href="/uk/plugins/sdk-testing">
|
||||
@ -338,7 +336,7 @@ my-plugin/
|
||||
<Card title="Міграція SDK" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
|
||||
Міграція із застарілих поверхонь.
|
||||
</Card>
|
||||
<Card title="Внутрішня будова плагінів" icon="diagram-project" href="/uk/plugins/architecture">
|
||||
<Card title="Внутрішня будова Plugin" icon="diagram-project" href="/uk/plugins/architecture">
|
||||
Поглиблена архітектура та модель можливостей.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,42 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі Google Gemini з OpenClaw
|
||||
- Вам потрібен ключ API або потік автентифікації OAuth
|
||||
summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук)
|
||||
- Вам потрібен процес автентифікації за допомогою ключа API або OAuth
|
||||
summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, web search)
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T08:40:13Z"
|
||||
generated_at: "2026-04-25T00:03:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7e66c9dd637e26976659d04b9b7e2452e6881945dab6011970f9e1c5e4a9a685
|
||||
source_hash: 6a3e8531d2cf58ac0f0c003d369be837576b4c2ff7d38e53cfb3f86ab8b44347
|
||||
source_path: providers/google.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до
|
||||
генерації зображень, розуміння медіа (зображення/аудіо/відео), text-to-speech і вебпошуку через
|
||||
Gemini Grounding.
|
||||
Plugin Google надає доступ до моделей Gemini через Google AI Studio, а також до генерації зображень, розуміння медіа (зображення/аудіо/відео), синтезу мовлення та web search через Gemini Grounding.
|
||||
|
||||
- Провайдер: `google`
|
||||
- Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
|
||||
- API: Google Gemini API
|
||||
- Альтернативний провайдер: `google-gemini-cli` (OAuth)
|
||||
- Параметр runtime: `agents.defaults.embeddedHarness.runtime: "google-gemini-cli"`
|
||||
повторно використовує OAuth Gemini CLI, зберігаючи канонічні посилання на моделі як `google/*`.
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key">
|
||||
<Tab title="Ключ API">
|
||||
**Найкраще для:** стандартного доступу до Gemini API через Google AI Studio.
|
||||
|
||||
<Steps>
|
||||
<Step title="Run onboarding">
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
|
||||
Або передайте ключ напряму:
|
||||
Або передайте ключ безпосередньо:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -45,7 +44,7 @@ Gemini Grounding.
|
||||
--gemini-api-key "$GEMINI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set a default model">
|
||||
<Step title="Установіть модель за замовчуванням">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -56,7 +55,7 @@ Gemini Grounding.
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify the model is available">
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
@ -64,7 +63,7 @@ Gemini Grounding.
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована.
|
||||
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка вже налаштована у вас.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
@ -74,37 +73,37 @@ Gemini Grounding.
|
||||
|
||||
<Warning>
|
||||
Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
|
||||
повідомляють про обмеження облікового запису при використанні OAuth у такий спосіб. Використовуйте на власний ризик.
|
||||
повідомляють про обмеження облікового запису при такому використанні OAuth. Використовуйте на власний ризик.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="Install the Gemini CLI">
|
||||
<Step title="Установіть Gemini CLI">
|
||||
Локальна команда `gemini` має бути доступною в `PATH`.
|
||||
|
||||
```bash
|
||||
# Homebrew
|
||||
brew install gemini-cli
|
||||
|
||||
# або npm
|
||||
# or npm
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, зокрема
|
||||
поширені схеми Windows/npm.
|
||||
OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, включно з поширеними схемами Windows/npm.
|
||||
</Step>
|
||||
<Step title="Log in via OAuth">
|
||||
<Step title="Увійдіть через OAuth">
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify the model is available">
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider google-gemini-cli
|
||||
openclaw models list --provider google
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
- Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- Модель за замовчуванням: `google/gemini-3.1-pro-preview`
|
||||
- Runtime: `google-gemini-cli`
|
||||
- Псевдонім: `gemini-cli`
|
||||
|
||||
**Змінні середовища:**
|
||||
@ -115,53 +114,53 @@ Gemini Grounding.
|
||||
(Або варіанти `GEMINI_CLI_*`.)
|
||||
|
||||
<Note>
|
||||
Якщо OAuth-запити Gemini CLI не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або
|
||||
`GOOGLE_CLOUD_PROJECT_ID` на хості gateway і повторіть спробу.
|
||||
Якщо OAuth-запити Gemini CLI завершуються помилкою після входу, установіть `GOOGLE_CLOUD_PROJECT` або
|
||||
`GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Якщо вхід не вдається ще до запуску потоку в браузері, переконайтеся, що локальна команда `gemini`
|
||||
встановлена й доступна в `PATH`.
|
||||
Якщо вхід завершується помилкою до початку браузерного потоку, переконайтеся, що локальну команду `gemini`
|
||||
встановлено і вона є в `PATH`.
|
||||
</Note>
|
||||
|
||||
Провайдер `google-gemini-cli`, який працює лише через OAuth, є окремою поверхнею
|
||||
текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на
|
||||
ідентифікаторі провайдера `google`.
|
||||
Посилання на моделі `google-gemini-cli/*` є застарілими псевдонімами сумісності. У нових
|
||||
конфігураціях слід використовувати посилання на моделі `google/*` разом із runtime `google-gemini-cli`,
|
||||
коли потрібне локальне виконання Gemini CLI.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Можливості
|
||||
|
||||
| Можливість | Підтримка |
|
||||
| --------------------- | ------------------------------ |
|
||||
| Завершення чату | Так |
|
||||
| Генерація зображень | Так |
|
||||
| Генерація музики | Так |
|
||||
| Text-to-speech | Так |
|
||||
| Голос у реальному часі| Так (Google Live API) |
|
||||
| Розуміння зображень | Так |
|
||||
| Транскрипція аудіо | Так |
|
||||
| Розуміння відео | Так |
|
||||
| Вебпошук (Grounding) | Так |
|
||||
| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) |
|
||||
| Моделі Gemma 4 | Так |
|
||||
| Можливість | Підтримка |
|
||||
| --------------------- | ----------------------------- |
|
||||
| Chat completions | Так |
|
||||
| Генерація зображень | Так |
|
||||
| Генерація музики | Так |
|
||||
| Синтез мовлення | Так |
|
||||
| Голос у реальному часі | Так (Google Live API) |
|
||||
| Розуміння зображень | Так |
|
||||
| Транскрипція аудіо | Так |
|
||||
| Розуміння відео | Так |
|
||||
| Web search (Grounding) | Так |
|
||||
| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) |
|
||||
| Моделі Gemma 4 | Так |
|
||||
|
||||
<Tip>
|
||||
Моделі Gemini 3 використовують `thinkingLevel` замість `thinkingBudget`. OpenClaw зіставляє
|
||||
керування міркуванням для Gemini 3, Gemini 3.1 і псевдоніма `gemini-*-latest` з
|
||||
елементи керування reasoning для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з
|
||||
`thinkingLevel`, щоб типові/низьколатентні запуски не надсилали вимкнені
|
||||
значення `thinkingBudget`.
|
||||
|
||||
Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw
|
||||
переписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4.
|
||||
Установлення thinking у `off` зберігає thinking вимкненим замість зіставлення з
|
||||
Моделі Gemma 4 (наприклад `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw
|
||||
переписує `thinkingBudget` на підтримуваний Google `thinkingLevel` для Gemma 4.
|
||||
Установлення thinking у `off` зберігає його вимкненим замість зіставлення з
|
||||
`MINIMAL`.
|
||||
</Tip>
|
||||
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований провайдер генерації зображень `google` за замовчуванням використовує
|
||||
Вбудований провайдер генерації зображень `google` типово використовує
|
||||
`google/gemini-3.1-flash-image-preview`.
|
||||
|
||||
- Також підтримує `google/gemini-3-pro-image-preview`
|
||||
@ -169,7 +168,7 @@ Gemini Grounding.
|
||||
- Режим редагування: увімкнено, до 5 вхідних зображень
|
||||
- Керування геометрією: `size`, `aspectRatio` і `resolution`
|
||||
|
||||
Щоб використовувати Google як провайдер зображень за замовчуванням:
|
||||
Щоб використовувати Google як провайдера зображень за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -184,7 +183,7 @@ Gemini Grounding.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація зображень](/uk/tools/image-generation).
|
||||
</Note>
|
||||
|
||||
## Генерація відео
|
||||
@ -193,11 +192,11 @@ Gemini Grounding.
|
||||
інструмент `video_generate`.
|
||||
|
||||
- Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview`
|
||||
- Режими: text-to-video, image-to-video і потоки з посиланням на одне відео
|
||||
- Режими: text-to-video, image-to-video і потоки з одним еталонним відео
|
||||
- Підтримує `aspectRatio`, `resolution` і `audio`
|
||||
- Поточне обмеження тривалості: **від 4 до 8 секунд**
|
||||
|
||||
Щоб використовувати Google як провайдер відео за замовчуванням:
|
||||
Щоб використовувати Google як провайдера відео за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -212,7 +211,7 @@ Gemini Grounding.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація відео](/uk/tools/video-generation).
|
||||
</Note>
|
||||
|
||||
## Генерація музики
|
||||
@ -222,12 +221,12 @@ Gemini Grounding.
|
||||
|
||||
- Модель музики за замовчуванням: `google/lyria-3-clip-preview`
|
||||
- Також підтримує `google/lyria-3-pro-preview`
|
||||
- Керування підказкою: `lyrics` і `instrumental`
|
||||
- Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview`
|
||||
- Опорні входи: до 10 зображень
|
||||
- Запуски з підтримкою сесій відокремлюються через спільний потік задач/статусу, зокрема `action: "status"`
|
||||
- Керування prompt: `lyrics` і `instrumental`
|
||||
- Формат виводу: `mp3` за замовчуванням, а також `wav` для `google/lyria-3-pro-preview`
|
||||
- Еталонні вхідні дані: до 10 зображень
|
||||
- Запуски з підтримкою сеансів від’єднуються через спільний потік задачі/статусу, включно з `action: "status"`
|
||||
|
||||
Щоб використовувати Google як провайдер музики за замовчуванням:
|
||||
Щоб використовувати Google як провайдера музики за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -242,12 +241,12 @@ Gemini Grounding.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація музики](/uk/tools/music-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація музики](/uk/tools/music-generation).
|
||||
</Note>
|
||||
|
||||
## Text-to-speech
|
||||
## Синтез мовлення
|
||||
|
||||
Вбудований мовний провайдер `google` використовує шлях Gemini API TTS з
|
||||
Вбудований провайдер мовлення `google` використовує шлях Gemini API TTS з
|
||||
`gemini-3.1-flash-tts-preview`.
|
||||
|
||||
- Голос за замовчуванням: `Kore`
|
||||
@ -255,7 +254,7 @@ Gemini Grounding.
|
||||
- Вивід: WAV для звичайних TTS-вкладень, PCM для Talk/телефонії
|
||||
- Нативний вивід голосових нотаток: не підтримується на цьому шляху Gemini API, оскільки API повертає PCM, а не Opus
|
||||
|
||||
Щоб використовувати Google як TTS-провайдер за замовчуванням:
|
||||
Щоб використовувати Google як провайдера TTS за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,14 +273,14 @@ Gemini Grounding.
|
||||
}
|
||||
```
|
||||
|
||||
Gemini API TTS приймає виразні аудіотеги в квадратних дужках у тексті, наприклад
|
||||
`[whispers]` або `[laughs]`. Щоб приховати теги з видимої відповіді чату, але
|
||||
Gemini API TTS приймає виразні квадратні аудіотеги в тексті, наприклад
|
||||
`[whispers]` або `[laughs]`. Щоб не показувати теги у видимій відповіді чату, але
|
||||
надсилати їх до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
|
||||
|
||||
```text
|
||||
Ось чистий текст відповіді.
|
||||
Here is the clean reply text.
|
||||
|
||||
[[tts:text]][whispers] Ось озвучена версія.[[/tts:text]]
|
||||
[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
|
||||
```
|
||||
|
||||
<Note>
|
||||
@ -294,17 +293,17 @@ Gemini API TTS приймає виразні аудіотеги в квадра
|
||||
Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на базі
|
||||
Gemini Live API для серверних аудіомостів, таких як Voice Call і Google Meet.
|
||||
|
||||
| Налаштування | Шлях конфігурації | За замовчуванням |
|
||||
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Голос | `...google.voice` | `Kore` |
|
||||
| Temperature | `...google.temperature` | (не задано) |
|
||||
| Чутливість початку VAD| `...google.startSensitivity` | (не задано) |
|
||||
| Чутливість кінця VAD | `...google.endSensitivity` | (не задано) |
|
||||
| Тривалість тиші | `...google.silenceDurationMs` | (не задано) |
|
||||
| Ключ API | `...google.apiKey` | Використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` як запасний варіант |
|
||||
| Параметр | Шлях конфігурації | Значення за замовчуванням |
|
||||
| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Голос | `...google.voice` | `Kore` |
|
||||
| Temperature | `...google.temperature` | (не встановлено) |
|
||||
| Чутливість початку VAD | `...google.startSensitivity` | (не встановлено) |
|
||||
| Чутливість завершення VAD | `...google.endSensitivity` | (не встановлено) |
|
||||
| Тривалість тиші | `...google.silenceDurationMs` | (не встановлено) |
|
||||
| Ключ API | `...google.apiKey` | Резервно використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
|
||||
Приклад конфігурації Voice Call для роботи в реальному часі:
|
||||
Приклад конфігурації Voice Call realtime:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -332,32 +331,32 @@ Gemini Live API для серверних аудіомостів, таких я
|
||||
|
||||
<Note>
|
||||
Google Live API використовує двоспрямоване аудіо та виклик функцій через WebSocket.
|
||||
OpenClaw адаптує аудіо телефонії/Meet-мосту до потоку PCM Live API Gemini і
|
||||
OpenClaw адаптує аудіо телефонії/мосту Meet до PCM Live API потоку Gemini і
|
||||
зберігає виклики інструментів у межах спільного контракту голосу в реальному часі. Залишайте `temperature`
|
||||
не заданим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає недодатні значення,
|
||||
не встановленим, якщо вам не потрібні зміни вибірки; OpenClaw пропускає непозитивні значення,
|
||||
оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`.
|
||||
Транскрипція Gemini API вмикається без `languageCodes`; поточний Google
|
||||
SDK відхиляє підказки кодів мов на цьому шляху API.
|
||||
Транскрипцію Gemini API увімкнено без `languageCodes`; поточний Google SDK
|
||||
відхиляє підказки кодів мов на цьому шляху API.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Сесії Talk у браузері в UI Control, як і раніше, потребують провайдера голосу в реальному часі з
|
||||
реалізацією сеансу браузерного WebRTC. Наразі цим шляхом є OpenAI Realtime; провайдер
|
||||
Google призначений для серверних мостів реального часу.
|
||||
Сеанси браузера Talk у Control UI і далі потребують провайдера голосу в реальному часі з
|
||||
реалізацією браузерного сеансу WebRTC. Наразі цей шлях — OpenAI Realtime; провайдер
|
||||
Google призначений для серверних realtime-мостів.
|
||||
</Note>
|
||||
|
||||
## Розширене налаштування
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Direct Gemini cache reuse">
|
||||
Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw
|
||||
передає налаштований дескриптор `cachedContent` у запити Gemini.
|
||||
<Accordion title="Пряме повторне використання кешу Gemini">
|
||||
Для прямих запусків Gemini API (`api: "google-generative-ai"`), OpenClaw
|
||||
передає налаштований дескриптор `cachedContent` до запитів Gemini.
|
||||
|
||||
- Налаштовуйте параметри для моделі або глобально за допомогою
|
||||
`cachedContent` або застарілого `cached_content`
|
||||
- Налаштуйте параметри для моделі або глобально через
|
||||
`cachedContent` або застарілий `cached_content`
|
||||
- Якщо присутні обидва, пріоритет має `cachedContent`
|
||||
- Приклад значення: `cachedContents/prebuilt-context`
|
||||
- Використання влучань кешу Gemini нормалізується в OpenClaw `cacheRead` з
|
||||
- Використання кеш-потрапляння Gemini нормалізується в OpenClaw `cacheRead` із
|
||||
висхідного `cachedContentTokenCount`
|
||||
|
||||
```json5
|
||||
@ -379,13 +378,13 @@ Google призначений для серверних мостів реаль
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Примітки щодо використання JSON у Gemini CLI">
|
||||
Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує
|
||||
JSON-вивід CLI таким чином:
|
||||
При використанні OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує
|
||||
JSON-вивід CLI так:
|
||||
|
||||
- Текст відповіді береться з поля CLI JSON `response`.
|
||||
- Використання бере `stats` як запасний варіант, якщо CLI залишає `usage` порожнім.
|
||||
- Використання резервно береться з `stats`, якщо CLI залишає `usage` порожнім.
|
||||
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутнє, OpenClaw обчислює вхідні токени з
|
||||
- Якщо `stats.input` відсутній, OpenClaw обчислює вхідні токени з
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -1,78 +1,79 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі OpenAI в OpenClaw
|
||||
- Ви хочете автентифікацію за підпискою Codex замість API-ключів
|
||||
- Вам потрібні суворіші правила виконання агента GPT-5
|
||||
- Ви хочете автентифікацію через підписку Codex замість API-ключів
|
||||
- Вам потрібна суворіша поведінка виконання агента GPT-5
|
||||
summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T16:58:35Z"
|
||||
generated_at: "2026-04-25T00:03:26Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bedc8975dae28e13d653494723ca0ee44cefdb63cbd4c6397658bd22fd8c3d80
|
||||
source_hash: 281ea7705763053b7038159035867b54e7255dc01136c54bfb7c68b5cc34cab1
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут:
|
||||
OpenAI надає API розробника для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут:
|
||||
|
||||
- **API-ключ** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` моделі)
|
||||
- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (`openai-codex/*` моделі)
|
||||
- **Обв’язка Codex app-server** — нативне виконання через Codex app-server (`openai/*` моделі плюс `agents.defaults.embeddedHarness.runtime: "codex"`)
|
||||
- **API key** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`)
|
||||
- **Підписка Codex через PI** — вхід через ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`)
|
||||
- **Harness app-server Codex** — власне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`)
|
||||
|
||||
OpenAI явно підтримує використання OAuth за підпискою в зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
|
||||
## Швидкий вибір
|
||||
|
||||
| Ціль | Використовуйте | Примітки |
|
||||
| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| Пряма тарифікація за API-ключем | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або виконайте онбординг OpenAI API-key. |
|
||||
| GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій із підпискою. |
|
||||
| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує обв’язку Codex app-server, а не публічний маршрут OpenAI API. |
|
||||
| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. |
|
||||
| Ціль | Використовуйте | Примітки |
|
||||
| --------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| Пряме виставлення рахунків за API key | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або запустіть онбординг OpenAI API key. |
|
||||
| GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для налаштувань із підпискою. |
|
||||
| GPT-5.5 із власною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує harness app-server Codex, а не публічний маршрут OpenAI API. |
|
||||
| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. |
|
||||
|
||||
<Note>
|
||||
GPT-5.5 наразі доступний в OpenClaw через маршрути підписки/OAuth:
|
||||
`openai-codex/gpt-5.5` з виконавцем PI або `openai/gpt-5.5` з
|
||||
обв’язкою Codex app-server. Прямий доступ за API-ключем до `openai/gpt-5.5`
|
||||
підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте
|
||||
модель із підтримкою API, наприклад `openai/gpt-5.4`, для конфігурацій із `OPENAI_API_KEY`.
|
||||
GPT-5.5 зараз доступна в OpenClaw через маршрути підписки/OAuth:
|
||||
`openai-codex/gpt-5.5` з runner PI або `openai/gpt-5.5` з
|
||||
harness app-server Codex. Прямий доступ через API key для `openai/gpt-5.5`
|
||||
підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу
|
||||
використовуйте модель із доступом через API, таку як `openai/gpt-5.4`, для
|
||||
налаштувань із `OPENAI_API_KEY`.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не
|
||||
вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише
|
||||
коли ви явно обираєте нативну обв’язку Codex за допомогою
|
||||
`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`.
|
||||
вмикає вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише
|
||||
коли ви явно вибираєте власний harness Codex через
|
||||
`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання моделі `codex/*`.
|
||||
</Note>
|
||||
|
||||
## Покриття можливостей OpenClaw
|
||||
## Покриття функцій OpenClaw
|
||||
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | постачальник моделей `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Обв’язка Codex app-server | `openai/<model>` з `embeddedHarness.runtime: codex` | Так |
|
||||
| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли ввімкнено вебпошук і не закріплено постачальника |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так |
|
||||
| Вбудовування | постачальник embedding для пам’яті | Так |
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| Чат / Responses | Провайдер моделей `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Harness app-server Codex | `openai/<model>` з `embeddedHarness.runtime: codex` | Так |
|
||||
| Пошук у вебі на стороні сервера | Власний інструмент OpenAI Responses | Так, коли вебпошук увімкнено й не закріплено провайдера |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Batch speech-to-text | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Streaming speech-to-text | Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Realtime voice | Voice Call `realtime.provider: "openai"` / розмова в Control UI | Так |
|
||||
| Embeddings | провайдер embedding для пам’яті | Так |
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API-ключ (OpenAI Platform)">
|
||||
**Найкраще для:** прямого доступу до API та тарифікації за використання.
|
||||
<Tab title="API key (OpenAI Platform)">
|
||||
**Найкраще для:** прямого доступу до API й виставлення рахунків за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте свій API-ключ">
|
||||
Створіть або скопіюйте API-ключ у [панелі керування OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
<Step title="Отримайте свій API key">
|
||||
Створіть або скопіюйте API key з [панелі OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
@ -85,7 +86,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai
|
||||
```
|
||||
@ -94,16 +95,16 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
| Model ref | Route | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | Майбутній прямий маршрут API, щойно OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
`openai/*` — це прямий маршрут OpenAI API-key, якщо ви явно не примусите
|
||||
обв’язку Codex app-server. Сам GPT-5.5 наразі доступний лише через підписку/OAuth;
|
||||
використовуйте `openai-codex/*` для Codex OAuth через типовий виконавець PI.
|
||||
`openai/*` — це прямий маршрут OpenAI API через API key, якщо ви явно не
|
||||
примусите використання harness app-server Codex. Сама GPT-5.5 зараз доступна
|
||||
лише через підписку/OAuth; використовуйте `openai-codex/*` для Codex OAuth через типовий runner PI.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -116,13 +117,13 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Підписка Codex">
|
||||
**Найкраще для:** використання підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT.
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud потребує входу через ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть Codex OAuth">
|
||||
@ -136,7 +137,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Для headless-конфігурацій або конфігурацій, де незручно використовувати callback, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість browser callback на localhost:
|
||||
Для headless-середовищ або налаштувань, де callback працює погано, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера на localhost:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
@ -147,7 +148,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
@ -156,15 +157,15 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
| Model ref | Route | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Обв’язка Codex app-server | автентифікація Codex app-server |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | автентифікація app-server Codex |
|
||||
|
||||
<Note>
|
||||
Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд
|
||||
автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth.
|
||||
Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server.
|
||||
Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд auth/profile. Префікс моделі
|
||||
`openai-codex/*` також є явним маршрутом PI для Codex OAuth.
|
||||
Він не вибирає і не автовмикає вбудований harness app-server Codex.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -176,29 +177,28 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
```
|
||||
|
||||
<Note>
|
||||
Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через browser OAuth (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів.
|
||||
Онбординг більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через OAuth у браузері (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента.
|
||||
</Note>
|
||||
|
||||
### Індикатор стану
|
||||
### Індикатор статусу
|
||||
|
||||
У чаті `/status` показує, яка вбудована обв’язка активна для поточної
|
||||
сесії. Типова обв’язка PI відображається як `Runner: pi (embedded)` і не
|
||||
додає окремий бейдж. Коли вибрано вбудовану обв’язку Codex app-server,
|
||||
`/status` додає ідентифікатор обв’язки не-PI поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Існуючі сесії зберігають зафіксований ідентифікатор обв’язки, тому використовуйте
|
||||
Чат `/status` показує, який runtime моделі активний для поточної сесії.
|
||||
Типовий harness PI відображається як `Runtime: OpenClaw Pi Default`. Коли
|
||||
вибрано вбудований harness app-server Codex, `/status` показує
|
||||
`Runtime: OpenAI Codex`. Наявні сесії зберігають записаний ідентифікатор harness, тому використайте
|
||||
`/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status`
|
||||
відображав новий вибір PI/Codex.
|
||||
|
||||
### Обмеження вікна контексту
|
||||
### Обмеження контекстного вікна
|
||||
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення.
|
||||
OpenClaw розглядає метадані моделі й обмеження контексту runtime як окремі значення.
|
||||
|
||||
Для `openai-codex/gpt-5.5` через Codex OAuth:
|
||||
|
||||
- Нативний `contextWindow`: `1000000`
|
||||
- Типове обмеження `contextTokens` під час виконання: `272000`
|
||||
- Власне `contextWindow`: `1000000`
|
||||
- Типове обмеження runtime `contextTokens`: `272000`
|
||||
|
||||
Менше типове обмеження на практиці має кращі характеристики затримки та якості. Ви можете перевизначити його через `contextTokens`:
|
||||
Менше типове обмеження на практиці дає кращу затримку та якість. Перевизначте його через `contextTokens`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,15 +213,15 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
Використовуйте `contextWindow`, щоб оголосити власні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime.
|
||||
</Note>
|
||||
|
||||
### Відновлення каталогу
|
||||
|
||||
OpenClaw використовує метадані вихідного каталогу Codex для `gpt-5.5`, коли вони
|
||||
присутні. Якщо під час реального виявлення Codex відсутній рядок `openai-codex/gpt-5.5`,
|
||||
а обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб
|
||||
Cron, субагент і запуски зі сконфігурованою типовою моделлю не завершувалися помилкою
|
||||
OpenClaw використовує метадані каталогу upstream Codex для `gpt-5.5`, коли вони
|
||||
присутні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, хоча
|
||||
обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб
|
||||
Cron, субагент і запуски з налаштованою типовою моделлю не завершувалися помилкою
|
||||
`Unknown model`.
|
||||
|
||||
</Tab>
|
||||
@ -230,18 +230,18 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`.
|
||||
Він підтримує і генерацію зображень OpenAI за API-ключем, і генерацію зображень
|
||||
через Codex OAuth з тим самим посиланням на модель `openai/gpt-image-2`.
|
||||
Він підтримує як генерацію зображень OpenAI через API key, так і генерацію зображень
|
||||
через Codex OAuth за тим самим посиланням моделі `openai/gpt-image-2`.
|
||||
|
||||
| Можливість | API-ключ OpenAI | Codex OAuth |
|
||||
| ------------------------- | ----------------------------------- | ------------------------------------ |
|
||||
| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth |
|
||||
| Транспорт | OpenAI Images API | бекенд Codex Responses |
|
||||
| Максимум зображень на запит | 4 | 4 |
|
||||
| Можливість | OpenAI API key | Codex OAuth |
|
||||
| ------------------------- | ---------------------------------- | ------------------------------------ |
|
||||
| Посилання моделі | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth |
|
||||
| Транспорт | OpenAI Images API | бекенд Codex Responses |
|
||||
| Максимум зображень на запит | 4 | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) |
|
||||
| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K |
|
||||
| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | За можливості безпечно зіставляється з підтримуваним розміром |
|
||||
| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Відображається на підтримуваний розмір, коли це безпечно |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -254,34 +254,31 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` є типовим для перетворення тексту на зображення та редагування зображень в OpenAI.
|
||||
`gpt-image-1` і надалі можна використовувати як явне перевизначення моделі, але для нових
|
||||
робочих процесів OpenAI із зображеннями слід використовувати `openai/gpt-image-2`.
|
||||
`gpt-image-2` є типовим значенням як для генерації текст-у-зображення OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`.
|
||||
|
||||
Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw знаходить збережений OAuth-токен
|
||||
доступу та надсилає запити на зображення через бекенд Codex Responses. Він
|
||||
не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихого fallback до API-ключа для цього
|
||||
запиту. Налаштуйте `models.providers.openai` явно з API-ключем,
|
||||
власним базовим URL або кінцевою точкою Azure, якщо хочете використовувати прямий маршрут OpenAI Images API
|
||||
замість цього.
|
||||
Якщо ця власна кінцева точка зображень розташована в довіреній LAN/приватній адресі, також установіть
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і далі
|
||||
блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо не задано цей явний дозвіл.
|
||||
Для встановлень із Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли
|
||||
налаштовано профіль OAuth `openai-codex`, OpenClaw визначає збережений токен
|
||||
доступу OAuth і надсилає запити на зображення через бекенд Codex Responses. Він
|
||||
не пробує спочатку `OPENAI_API_KEY` і не переходить мовчки на API key для цього
|
||||
запиту. Явно налаштуйте `models.providers.openai` з API key,
|
||||
власним base URL або кінцевою точкою Azure, якщо хочете використовувати прямий маршрут OpenAI Images API.
|
||||
Якщо ця власна кінцева точка зображень розміщена в довіреній LAN/приватній адресі, також установіть
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і далі блокує
|
||||
приватні/внутрішні сумісні з OpenAI кінцеві точки зображень, якщо немає цього явного дозволу.
|
||||
|
||||
Згенерувати:
|
||||
Генерація:
|
||||
|
||||
```text
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Вишуканий постер запуску OpenClaw на macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Редагувати:
|
||||
Редагування:
|
||||
|
||||
```text
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
## Генерація відео
|
||||
@ -292,7 +289,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| Типова модель | `openai/sora-2` |
|
||||
| Режими | Text-to-video, image-to-video, редагування одного відео |
|
||||
| Вхідні еталони | 1 зображення або 1 відео |
|
||||
| Еталонні входи | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента |
|
||||
|
||||
@ -307,22 +304,22 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Внесок у промпт GPT-5
|
||||
|
||||
OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні.
|
||||
OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ID моделі, тож `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий шар. Старіші моделі GPT-4.x — ні.
|
||||
|
||||
Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі правила доведення до кінця та проактивного Heartbeat, навіть якщо рештою промпту обв’язки керує Codex.
|
||||
Вбудований власний harness Codex використовує ту саму поведінку GPT-5 і шар Heartbeat через інструкції розробника app-server Codex, тож сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення до кінця й проактивного Heartbeat, хоча рештою промпта harness керує Codex.
|
||||
|
||||
Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Правила GPT-5 завжди ввімкнені для відповідних моделей. Дружній стиль взаємодії — окремий і налаштовуваний шар.
|
||||
Внесок GPT-5 додає контракт поведінки з тегами для збереження персони, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей для конкретних каналів і поведінка тихих повідомлень залишаються в спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним.
|
||||
|
||||
| Значення | Ефект |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише шар дружнього стилю |
|
||||
| Значення | Ефект |
|
||||
| ---------------------- | ---------------------------------------------- |
|
||||
| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише шар дружнього стилю |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Config">
|
||||
@ -346,11 +343,11 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Значення під час виконання нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю.
|
||||
Під час runtime значення не чутливі до регістру, тож і `"Off"`, і `"off"` вимикають шар дружнього стилю.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застаріле `plugins.entries.openai.config.personality` і далі зчитується як fallback для сумісності, якщо спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
Застаріле `plugins.entries.openai.config.personality` і далі читається як резервне значення для сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
@ -359,14 +356,14 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
<Accordion title="Синтез мовлення (TTS)">
|
||||
Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| Голос | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| Швидкість | `messages.tts.providers.openai.speed` | (не задано) |
|
||||
| Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових повідомлень, `mp3` для файлів |
|
||||
| API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
@ -384,23 +381,23 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку chat API.
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку чат-API.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Перетворення мовлення на текст">
|
||||
<Accordion title="Speech-to-text">
|
||||
Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через
|
||||
поверхню транскрибування для розуміння медіа в OpenClaw.
|
||||
поверхню транскрипції для розуміння медіа в OpenClaw.
|
||||
|
||||
- Типова модель: `gpt-4o-transcribe`
|
||||
- Кінцева точка: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Вхідний шлях: завантаження аудіофайлу multipart
|
||||
- Підтримується в OpenClaw всюди, де для транскрибування вхідного аудіо використовується
|
||||
- Шлях введення: multipart-завантаження аудіофайла
|
||||
- Підтримується в OpenClaw всюди, де транскрипція вхідного аудіо використовує
|
||||
`tools.media.audio`, включно з сегментами голосових каналів Discord і
|
||||
аудіовкладеннями каналів
|
||||
|
||||
Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо:
|
||||
Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -420,43 +417,43 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
}
|
||||
```
|
||||
|
||||
Підказки мови та промпту передаються в OpenAI, коли вони надані
|
||||
спільною конфігурацією аудіомедіа або запитом транскрибування для окремого виклику.
|
||||
Підказки мови та промпта пересилаються до OpenAI, коли їх задає
|
||||
спільна конфігурація аудіомедіа або запит на транскрипцію для конкретного виклику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Транскрибування в реальному часі">
|
||||
Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call.
|
||||
<Accordion title="Транскрипція в realtime">
|
||||
Вбудований Plugin `openai` реєструє транскрипцію в realtime для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| Мова | `...openai.language` | (не задано) |
|
||||
| Промпт | `...openai.prompt` | (не задано) |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `800` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
| API key | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
Використовує з’єднання WebSocket із `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей постачальник потокової обробки призначений для шляху транскрибування в реальному часі в Voice Call; голос у Discord наразі натомість записує короткі сегменти та використовує пакетний шлях транскрибування `tools.media.audio`.
|
||||
Використовує підключення WebSocket до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрипції в realtime у Voice Call; голос Discord наразі записує короткі сегменти та замість цього використовує пакетний шлях транскрипції `tools.media.audio`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Голос у реальному часі">
|
||||
Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call.
|
||||
<Accordion title="Голос у realtime">
|
||||
Вбудований Plugin `openai` реєструє голос у realtime для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
|
||||
| Голос | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `500` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
| API key | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує аудіоформат G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двосторонній виклик інструментів. Використовує формат аудіо G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -464,28 +461,27 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
|
||||
## Кінцеві точки Azure OpenAI
|
||||
|
||||
Вбудований постачальник `openai` може спрямовувати генерацію зображень на ресурс Azure OpenAI
|
||||
через перевизначення базового URL. На шляху генерації зображень OpenClaw
|
||||
виявляє імена хостів Azure у `models.providers.openai.baseUrl` і автоматично
|
||||
Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для
|
||||
генерації зображень через перевизначення base URL. На шляху генерації зображень OpenClaw
|
||||
визначає імена хостів Azure в `models.providers.openai.baseUrl` і автоматично
|
||||
перемикається на формат запиту Azure.
|
||||
|
||||
<Note>
|
||||
Голос у реальному часі використовує окремий шлях конфігурації
|
||||
Голос у realtime використовує окремий шлях конфігурації
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||||
і на нього не впливає `models.providers.openai.baseUrl`. Див. акордеон **Голос
|
||||
у реальному часі** в розділі [Голос і мовлення](#voice-and-speech), щоб дізнатися про налаштування Azure
|
||||
для нього.
|
||||
і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у realtime**
|
||||
в розділі [Голос і мовлення](#voice-and-speech) для його параметрів Azure.
|
||||
</Note>
|
||||
|
||||
Використовуйте Azure OpenAI, коли:
|
||||
|
||||
- У вас уже є підписка Azure OpenAI, квота або корпоративна угода
|
||||
- Вам потрібна регіональна резидентність даних або засоби відповідності вимогам, які надає Azure
|
||||
- Ви хочете залишити трафік у межах наявного tenancy Azure
|
||||
- У вас уже є підписка, квота або корпоративна угода Azure OpenAI
|
||||
- Вам потрібне регіональне розміщення даних або засоби відповідності, які надає Azure
|
||||
- Ви хочете зберігати трафік у межах наявного середовища Azure
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Для генерації зображень через Azure у вбудованому постачальнику `openai` укажіть
|
||||
Для генерації зображень Azure через вбудований провайдер `openai` вкажіть
|
||||
`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` як
|
||||
ключ Azure OpenAI (а не ключ OpenAI Platform):
|
||||
|
||||
@ -511,90 +507,89 @@ OpenClaw розпізнає такі суфікси хостів Azure для м
|
||||
Для запитів генерації зображень на розпізнаному хості Azure OpenClaw:
|
||||
|
||||
- Надсилає заголовок `api-key` замість `Authorization: Bearer`
|
||||
- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`)
|
||||
- Використовує шляхи, прив’язані до розгортання (`/openai/deployments/{deployment}/...`)
|
||||
- Додає `?api-version=...` до кожного запиту
|
||||
|
||||
Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний
|
||||
Інші base URL (публічний OpenAI, сумісні з OpenAI проксі) зберігають стандартний
|
||||
формат запиту зображень OpenAI.
|
||||
|
||||
<Note>
|
||||
Маршрутизація Azure для шляху генерації зображень постачальника `openai`
|
||||
потребує OpenClaw 2026.4.22 або новішої версії. Попередні версії трактують будь-який власний
|
||||
`openai.baseUrl` так само, як публічну кінцеву точку OpenAI, і не працюватимуть з deployment генерації
|
||||
зображень у Azure.
|
||||
Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує
|
||||
OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який власний
|
||||
`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із розгортаннями зображень Azure.
|
||||
</Note>
|
||||
|
||||
### Версія API
|
||||
|
||||
Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview або GA-версію Azure
|
||||
Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure
|
||||
для шляху генерації зображень Azure:
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
Типове значення — `2024-12-01-preview`, якщо змінну не задано.
|
||||
Типове значення — `2024-12-01-preview`, якщо змінну не встановлено.
|
||||
|
||||
### Назви моделей — це назви deployment
|
||||
### Назви моделей — це назви розгортань
|
||||
|
||||
Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure,
|
||||
спрямованих через вбудований постачальник `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не
|
||||
публічним ідентифікатором моделі OpenAI.
|
||||
Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure,
|
||||
маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою розгортання Azure**, яку ви налаштували в порталі Azure, а не
|
||||
публічним ID моделі OpenAI.
|
||||
|
||||
Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`:
|
||||
Якщо ви створили розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`:
|
||||
|
||||
```text
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
Те саме правило назви deployment застосовується до викликів генерації зображень, спрямованих через
|
||||
вбудований постачальник `openai`.
|
||||
Те саме правило назв розгортань застосовується до викликів генерації зображень,
|
||||
маршрутизованих через вбудований провайдер `openai`.
|
||||
|
||||
### Регіональна доступність
|
||||
|
||||
Генерація зображень у Azure зараз доступна лише в частині регіонів
|
||||
Генерація зображень Azure зараз доступна лише в частині регіонів
|
||||
(наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||||
`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням
|
||||
deployment і переконайтеся, що потрібна модель доступна у вашому регіоні.
|
||||
`uaenorth`). Перш ніж створювати розгортання, перевірте актуальний список регіонів Microsoft
|
||||
і підтвердьте, що конкретна модель доступна у вашому регіоні.
|
||||
|
||||
### Відмінності параметрів
|
||||
|
||||
Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень.
|
||||
Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні
|
||||
значення `background` для `gpt-image-2`), або надавати їх лише для певних версій
|
||||
моделі. Ці відмінності походять від Azure та базової моделі, а не від
|
||||
Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, деякі
|
||||
значення `background` для `gpt-image-2`) або надавати їх лише для певних
|
||||
версій моделей. Ці відмінності походять від Azure та базової моделі, а не від
|
||||
OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте
|
||||
набір параметрів, які підтримує саме ваш deployment і версія API, у
|
||||
набір параметрів, який підтримує саме ваше розгортання та версія API в
|
||||
порталі Azure.
|
||||
|
||||
<Note>
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує
|
||||
приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та OpenAI-сумісні
|
||||
маршрути** в розділі [Розширена конфігурація](#advanced-configuration).
|
||||
Azure OpenAI використовує власний транспорт і сумісну поведінку, але не отримує
|
||||
прихованих заголовків атрибуції OpenClaw — див. акордеон **Власні маршрути vs OpenAI-compatible
|
||||
routes** у розділі [Розширена конфігурація](#advanced-configuration).
|
||||
|
||||
Для трафіку chat або Responses на Azure (окрім генерації зображень) використовуйте
|
||||
потік онбордингу або окрему конфігурацію постачальника Azure — одного лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати форму API/автентифікації Azure. Існує
|
||||
окремий постачальник `azure-openai-responses/*`; див.
|
||||
акордеон про серверний Compaction нижче.
|
||||
Для трафіку чату або Responses в Azure (окрім генерації зображень) використовуйте
|
||||
процес онбордингу або окрему конфігурацію провайдера Azure — одного лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати формат API/автентифікації Azure. Існує окремий
|
||||
провайдер `azure-openai-responses/*`; див.
|
||||
акордеон Server-side Compaction нижче.
|
||||
</Note>
|
||||
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Транспорт (WebSocket vs SSE)">
|
||||
OpenClaw використовує WebSocket-first із fallback до SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
OpenClaw використовує спочатку WebSocket із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
|
||||
У режимі `"auto"` OpenClaw:
|
||||
- Повторює одну ранню помилку WebSocket перед переходом до SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час цього періоду охолодження
|
||||
- Додає стабільні заголовки ідентифікації сесії та ходу для повторних спроб і перепідключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як degraded приблизно на 60 секунд і використовує SSE під час періоду охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень
|
||||
- Нормалізує лічильники usage (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
|
||||
| Значення | Поведінка |
|
||||
|-------|----------|
|
||||
| `"auto"` (типово) | Спочатку WebSocket, fallback до SSE |
|
||||
| `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE |
|
||||
| `"sse"` | Примусово лише SSE |
|
||||
| `"websocket"` | Примусово лише WebSocket |
|
||||
|
||||
@ -621,11 +616,11 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Прогрівання WebSocket">
|
||||
OpenClaw типово вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу.
|
||||
<Accordion title="Попередній прогрів WebSocket">
|
||||
OpenClaw типово вмикає попередній прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу.
|
||||
|
||||
```json5
|
||||
// Вимкнути прогрівання
|
||||
// Disable warm-up
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
@ -644,8 +639,8 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
<Accordion title="Швидкий режим">
|
||||
OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`:
|
||||
|
||||
- **Chat/UI:** `/fast status|on|off`
|
||||
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
- **Чат/UI:** `/fast status|on|off`
|
||||
- **Конфігурація:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Коли його ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`.
|
||||
|
||||
@ -662,7 +657,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI сесій повертає сесію до типового налаштованого значення.
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI сесій повертає сесію до налаштованого типового значення.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -685,23 +680,23 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
Підтримувані значення: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих постачальників через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
`serviceTier` пересилається лише до власних кінцевих точок OpenAI (`api.openai.com`) і власних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Серверний Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає серверний Compaction:
|
||||
<Accordion title="Server-side Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) поточна обгортка stream Pi-harness Plugin OpenAI автоматично вмикає server-side Compaction:
|
||||
|
||||
- Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`)
|
||||
- Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Примусово встановлює `store: true` (якщо сумісність моделі не задає `supportsStore: false`)
|
||||
- Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне)
|
||||
|
||||
Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативна обв’язка Codex app-server керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`.
|
||||
Це застосовується до вбудованого шляху Pi harness і до hook провайдера OpenAI, які використовуються в embedded-запусках. Власний harness app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Явно ввімкнути">
|
||||
Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses:
|
||||
<Tab title="Явне ввімкнення">
|
||||
Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -735,7 +730,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Вимкнути">
|
||||
<Tab title="Вимкнення">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -753,13 +748,13 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо лише сумісність не задає `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Суворий агентний режим GPT">
|
||||
Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання:
|
||||
Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший embedded-контракт виконання:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -771,33 +766,33 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
|
||||
З `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія через інструмент
|
||||
Із `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента
|
||||
- Повторює хід із вказівкою діяти негайно
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дій
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дії
|
||||
|
||||
<Note>
|
||||
Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку.
|
||||
Обмежено лише запусками OpenAI та Codex сімейства GPT-5. Інші провайдери й старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні маршрути та OpenAI-сумісні маршрути">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`:
|
||||
<Accordion title="Власні маршрути vs OpenAI-compatible routes">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-compatible проксі `/v1`:
|
||||
|
||||
**Нативні маршрути** (`openai/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort
|
||||
**Власні маршрути** (`openai/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` для effort
|
||||
- Пропускають вимкнене reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово використовують строгий режим для схем інструментів
|
||||
- Додають приховані заголовки атрибуції лише на перевірених нативних хостах
|
||||
- Зберігають формування запитів, характерне лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки кешу промптів)
|
||||
- Типово використовують суворий режим для схем інструментів
|
||||
- Додають приховані заголовки атрибуції лише на перевірених власних хостах
|
||||
- Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів)
|
||||
|
||||
**Маршрути проксі/сумісності:**
|
||||
- Використовують менш строгі правила сумісності
|
||||
- Не примушують строгі схеми інструментів або заголовки, доступні лише для нативних маршрутів
|
||||
**Проксі/сумісні маршрути:**
|
||||
- Використовують м’якшу сумісну поведінку
|
||||
- Не примушують суворі схеми інструментів або заголовки лише для власних маршрутів
|
||||
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції.
|
||||
Azure OpenAI використовує власний транспорт і сумісну поведінку, але не отримує прихованих заголовків атрибуції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -806,15 +801,15 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір постачальників, посилань на моделі та поведінки failover.
|
||||
Вибір провайдерів, посилань моделей і поведінки failover.
|
||||
</Card>
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри інструмента зображень і вибір постачальника.
|
||||
Спільні параметри інструмента зображень і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри інструмента відео та вибір постачальника.
|
||||
Спільні параметри інструмента відео і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="OAuth і автентифікація" href="/uk/gateway/authentication" icon="key">
|
||||
Докладно про автентифікацію та правила повторного використання облікових даних.
|
||||
<Card title="OAuth і auth" href="/uk/gateway/authentication" icon="key">
|
||||
Подробиці auth і правила повторного використання облікових даних.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,51 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск або виправлення тестів
|
||||
summary: Як запускати тести локально (`vitest`) і коли використовувати режими force/coverage
|
||||
summary: Як локально запускати тести (vitest) і коли використовувати режими force/coverage
|
||||
title: Тести
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T22:51:37Z"
|
||||
generated_at: "2026-04-25T00:03:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f15e68a95d68dd076862aa168a836c4918876afa1f925ed183f7fde8ec75f24a
|
||||
source_hash: 91009b51cee872f542a9aed0f882359c763cfb88722860eb8ef7deae434a89e7
|
||||
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 coverage (через `vitest.unit.config.ts`). Це перевірка unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен файл вихідного коду з розбитих lane непокритим.
|
||||
- `pnpm test:force`: Завершує будь-який gateway process, що залишився і тримає стандартний control port, а потім запускає повний набір Vitest з ізольованим port gateway, щоб server-тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим port 18789.
|
||||
- `pnpm test:coverage`: Запускає unit-набір із V8 coverage (через `vitest.unit.config.ts`). Це gate unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, gate вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен source file із розділених lane-ів непокритим.
|
||||
- `pnpm test:coverage:changed`: Запускає unit coverage лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:changed`: розгортає змінені git-шляхи у scoped lane Vitest, коли diff зачіпає лише routable файли коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску root project, щоб за потреби правки wiring перезапускали ширший набір.
|
||||
- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`.
|
||||
- `pnpm check:changed`: запускає розумну changed-перевірку для diff відносно `origin/main`. Вона запускає core-роботи з lane core-тестів, extension-роботи з lane extension-тестів, test-only зміни лише з test typecheck/tests, розширює зміни публічного Plugin SDK або plugin-contract до одного проходу валідації extension і залишає підвищення версій лише в release metadata на цільових перевірках version/config/root-dependency.
|
||||
- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілей використовують фіксовані shard-групи та розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до per-extension shard config, а не до одного великого процесу root project.
|
||||
- Повні запуски та запуски shard extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard. Встановіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
|
||||
- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane, які зберігають лише `test/setup.ts`, залишаючи runtime-важкі випадки у наявних lane.
|
||||
- Вибрані допоміжні файли коду `plugin-sdk` і `commands` також відображають `pnpm test:changed` на явні сусідні тести в цих легких lane, тому невеликі правки helper не змушують перезапускати важкі набори з підтримкою runtime.
|
||||
- `auto-reply` тепер також розбивається на три окремі config (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper.
|
||||
- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнений у всіх конфігураціях репозиторію.
|
||||
- `pnpm test:changed`: розгортає змінені git paths у scoped Vitest lanes, коли diff зачіпає лише routable source/test files. Зміни config/setup і далі переходять до нативного запуску root projects, щоб зміни wiring за потреби повторно запускали ширший набір перевірок.
|
||||
- `pnpm changed:lanes`: показує архітектурні lanes, що спрацьовують для diff відносно `origin/main`.
|
||||
- `pnpm check:changed`: запускає розумний changed gate для diff відносно `origin/main`. Він запускає роботу core разом із core test lanes, роботу extension — з extension test lanes, зміни лише в тестах — лише з test typecheck/tests, розширює зміни в публічному Plugin SDK або plugin-contract до одного проходу валідації extension і залишає підвищення версії лише в release metadata на цільових перевірках version/config/root-dependency.
|
||||
- `pnpm test`: маршрутизує явно вказані цілі file/directory через scoped Vitest lanes. Запуски без цілей використовують фіксовані shard groups і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard configs для окремих extension, а не до одного гігантського процесу root-project.
|
||||
- Повні запуски і запуски shard-ів extension оновлюють локальні дані часу в `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги, щоб балансувати повільні й швидкі shard-и. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
|
||||
- Вибрані test files `plugin-sdk` і `commands` тепер маршрутизуються через спеціальні легкі lanes, які залишають лише `test/setup.ts`, а випадки з важчим runtime залишаються у своїх наявних lanes.
|
||||
- Вибрані helper source files `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми tests у цих легких lanes, щоб невеликі зміни helper-ів не спричиняли повторний запуск важких наборів, що залежать від runtime.
|
||||
- `auto-reply` тепер також розділяється на три окремі configs (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими tests верхнього рівня для status/token/helper.
|
||||
- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в усьому наборі configs репозиторію.
|
||||
- `pnpm test:channels` запускає `vitest.channels.config.ts`.
|
||||
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/<id>` для однієї bundled lane plugin.
|
||||
- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та деталізацію імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів.
|
||||
- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` виконує benchmark маршрутизованого шляху changed-mode проти нативного запуску root project для того самого закоміченого git diff.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту.
|
||||
- `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`).
|
||||
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extension/plugin. Важкі channel plugins, plugin browser і OpenAI запускаються як окремі shard-и; інші групи plugin-ів залишаються згрупованими. Використовуйте `pnpm test extensions/<id>` для одного lane bundled plugin.
|
||||
- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпортів і import-breakdown, при цьому й надалі використовує scoped lane routing для явно вказаних цілей file/directory.
|
||||
- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` порівнює у режимі benchmark маршрутизований шлях changed-mode з нативним запуском root-project для того самого закоміченого git diff.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` порівнює у режимі benchmark поточний набір змін у worktree без попереднього коміту.
|
||||
- `pnpm test:perf:profile:main`: записує CPU profile для main thread Vitest (`.artifacts/vitest-main-profile`).
|
||||
- `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner (`.artifacts/vitest-runner-profile`).
|
||||
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf config Vitest повного набору та записує згруповані дані тривалості разом з JSON/log-артефактами для кожної config. Агент продуктивності тестів використовує це як базову лінію перед спробами виправлення повільних тестів.
|
||||
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf config Vitest для повного набору і записує згруповані дані тривалості плюс JSON/log-артефакти для кожного config. Test Performance Agent використовує це як baseline перед спробою виправити повільні тести.
|
||||
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність.
|
||||
- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: Запускає smoke-тести gateway end-to-end (pairing кількох екземплярів WS/HTTP/node). За замовчуванням використовує `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:all`: Один раз збирає спільний образ live-тестів і образ Docker E2E, а потім запускає Docker smoke lane з `OPENCLAW_SKIP_DOCKER_BUILD=1` через зважений планувальник. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` керує кількістю слотів процесів і за замовчуванням дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` керує чутливим до провайдера tail pool і за замовчуванням теж дорівнює 10. Обмеження для важких lane за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`; використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` для більших хостів. Запуски lane за замовчуванням відтерміновуються на 2 секунди, щоб уникати локальних сплесків створення контейнерів у Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner за замовчуванням виконує попередню перевірку Docker, очищує застарілі контейнери OpenClaw E2E, виводить статус активних lane кожні 30 секунд і зберігає таймінги lane у `.artifacts/docker-tests/lane-timings.json` для впорядкування за принципом longest-first у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести manifest lane без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` для налаштування виводу статусу або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання таймінгів. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожна lane має резервний timeout у 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lane використовують жорсткіші ліміти для кожної lane. Логи для кожної lane записуються в `.artifacts/docker-tests/<run-id>/`.
|
||||
- `pnpm test:docker:openwebui`: Запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потрібен придатний ключ live-моделі (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і від цього не очікується стабільність у CI на рівні звичайних unit/e2e-наборів.
|
||||
- `pnpm test:docker:mcp-channels`: Запускає seeded контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed discovery розмов, читання transcript, metadata вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення каналу + дозволів у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає необроблені stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально надсилає.
|
||||
- Інтеграція gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: Запускає gateway end-to-end smoke-тести (pairing multi-instance WS/HTTP/node). За замовчуванням використовує `threads` + `isolate: false` з adaptive workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=<n>` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів.
|
||||
- `pnpm test:live`: Запускає live-тести provider-ів (minimax/zai). Потрібні API keys і `LIVE=1` (або специфічне для provider `*_LIVE_TEST=1`), щоб зняти пропуск.
|
||||
- `pnpm test:docker:all`: Один раз збирає спільний live-test image і Docker E2E image, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` через зважений scheduler. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` керує слотами process і за замовчуванням дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` керує tail pool, чутливим до provider, і також за замовчуванням дорівнює 10. Обмеження для важких lanes за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` для більших хостів. Запуски lanes за замовчуванням зсуваються на 2 секунди, щоб уникнути локальних сплесків create-операцій Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner за замовчуванням виконує preflight для Docker, очищає застарілі OpenClaw E2E containers, виводить status активних lanes кожні 30 секунд і зберігає таймінги lanes у `.artifacts/docker-tests/lane-timings.json` для впорядкування за принципом longest-first у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати маніфест lanes без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` для налаштування виводу status, або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання таймінгів. Runner припиняє планування нових pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, і кожен lane має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lanes використовують жорсткіші обмеження для кожного lane. Логи для кожного lane записуються в `.artifacts/docker-tests/<run-id>/`.
|
||||
- `pnpm test:docker:openwebui`: Запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній image Open WebUI і не вважається настільки стабільним для CI, як звичайні unit/e2e suites.
|
||||
- `pnpm test:docker:mcp-channels`: Запускає seeded Gateway container і другий client container, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, metadata вкладень, поведінку live event queue, маршрутизацію вихідного надсилання та сповіщення про channel + permissions у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально надсилає.
|
||||
|
||||
## Локальна PR-перевірка
|
||||
## Локальний PR gate
|
||||
|
||||
Для локальних перевірок перед злиттям/гейтом PR запустіть:
|
||||
Для локальних перевірок перед злиттям PR/gate запускайте:
|
||||
|
||||
- `pnpm check:changed`
|
||||
- `pnpm check`
|
||||
@ -54,12 +54,12 @@ x-i18n:
|
||||
- `pnpm test`
|
||||
- `pnpm check:docs`
|
||||
|
||||
Якщо `pnpm test` дає flaky-результат на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
|
||||
Якщо `pnpm test` дає flake на навантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test <path/to/test>`. Для хостів з обмеженнями пам’яті використовуйте:
|
||||
|
||||
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
|
||||
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
|
||||
|
||||
## Benchmark затримки моделі (локальні ключі)
|
||||
## Бенч затримки моделі (локальні ключі)
|
||||
|
||||
Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
|
||||
|
||||
@ -67,14 +67,14 @@ x-i18n:
|
||||
|
||||
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
|
||||
- Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
|
||||
- Типовий prompt: “Reply with a single word: ok. No punctuation or extra text.”
|
||||
- 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)
|
||||
- median для minimax: 1279ms (мін. 1114, макс. 2431)
|
||||
- median для opus: 2454ms (мін. 1224, макс. 3170)
|
||||
|
||||
## Benchmark запуску CLI
|
||||
## Бенч запуску CLI
|
||||
|
||||
Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
|
||||
|
||||
@ -95,41 +95,41 @@ x-i18n:
|
||||
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
|
||||
- `pnpm tsx scripts/bench-cli-startup.ts --json`
|
||||
|
||||
Набори preset:
|
||||
Preset-и:
|
||||
|
||||
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
|
||||
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
|
||||
- `all`: обидва набори preset
|
||||
- `all`: обидва 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 profiles для кожного запуску, щоб вимірювання часу й збирання profile використовували той самий harness.
|
||||
|
||||
Умовні позначення для збереженого виводу:
|
||||
Домовленості щодо збереженого виводу:
|
||||
|
||||
- `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json`
|
||||
- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з використанням `runs=5` і `warmup=1`
|
||||
- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json` з використанням `runs=5` і `warmup=1`
|
||||
- `pnpm test:startup:bench:save` записує артефакт повного набору в `.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`
|
||||
|
||||
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`
|
||||
|
||||
## E2E онбордингу (Docker)
|
||||
|
||||
Docker необов’язковий; це потрібно лише для containerized smoke-тестів онбордингу.
|
||||
|
||||
Повний потік cold-start у чистому Linux-контейнері:
|
||||
Повний cold-start flow у чистому Linux container:
|
||||
|
||||
```bash
|
||||
scripts/e2e/onboard-docker.sh
|
||||
```
|
||||
|
||||
Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`.
|
||||
Цей скрипт проводить інтерактивний wizard через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`.
|
||||
|
||||
## Smoke для QR import (Docker)
|
||||
## QR import smoke (Docker)
|
||||
|
||||
Переконується, що підтримуваний helper runtime для QR завантажується в підтримуваних Node runtime у Docker (Node 24 за замовчуванням, Node 22 сумісний):
|
||||
Гарантує, що підтримуваний helper QR runtime завантажується в підтримуваних Docker Node runtimes (Node 24 за замовчуванням, Node 22 сумісний):
|
||||
|
||||
```bash
|
||||
pnpm test:docker:qr
|
||||
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Написання сценаріїв або налагодження браузера агента через локальний API керування
|
||||
- Скриптування або налагодження браузера агента через локальний API керування
|
||||
- Шукаєте довідник CLI `openclaw browser`
|
||||
- Додавання власної автоматизації браузера зі знімками та refs
|
||||
summary: API керування браузером OpenClaw, довідник CLI та дії для сценаріїв
|
||||
- Додавання власної автоматизації браузера зі snapshot і ref
|
||||
summary: API керування браузером OpenClaw, довідник CLI та дії для скриптування
|
||||
title: API керування браузером
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T02:43:41Z"
|
||||
generated_at: "2026-04-25T00:03:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e29ad295085e2c36a6c2ce01366a4186e45a7ecfe1d3c3072353c55794b05b5f
|
||||
source_hash: ec7b6e83b231fefc9c4a63fabde9bdaeb2ea2b2a8ab64943e179a7af5ed4badc
|
||||
source_path: tools/browser-control.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Для налаштування, конфігурації та усунення несправностей див. [Browser](/uk/tools/browser).
|
||||
Ця сторінка є довідником для локального HTTP API керування, CLI `openclaw browser`
|
||||
і шаблонів написання сценаріїв (знімки, refs, очікування, потоки налагодження).
|
||||
Ця сторінка — довідник для локального HTTP API керування, CLI `openclaw browser`
|
||||
і шаблонів скриптування (snapshot, ref, очікування, потоки налагодження).
|
||||
|
||||
## API керування (необов’язково)
|
||||
|
||||
Лише для локальних інтеграцій Gateway надає невеликий loopback HTTP API:
|
||||
|
||||
- Стан/запуск/зупинка: `GET /`, `POST /start`, `POST /stop`
|
||||
- Статус/запуск/зупинка: `GET /`, `POST /start`, `POST /stop`
|
||||
- Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
|
||||
- Знімок/скриншот: `GET /snapshot`, `POST /screenshot`
|
||||
- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`
|
||||
- Дії: `POST /navigate`, `POST /act`
|
||||
- Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog`
|
||||
- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`
|
||||
- Завантаження: `POST /download`, `POST /wait/download`
|
||||
- Налагодження: `GET /console`, `POST /pdf`
|
||||
- Налагодження: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
|
||||
@ -37,19 +37,22 @@ x-i18n:
|
||||
|
||||
Усі кінцеві точки приймають `?profile=<name>`.
|
||||
|
||||
Якщо налаштовано автентифікацію Gateway зі спільним секретом, HTTP-маршрути браузера також потребують автентифікації:
|
||||
Якщо налаштовано auth gateway зі спільним секретом, HTTP-маршрути браузера також потребують auth:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` або HTTP Basic auth із цим паролем
|
||||
|
||||
Примітки:
|
||||
|
||||
- Цей окремий loopback API браузера **не** використовує заголовки ідентифікації trusted-proxy або Tailscale Serve.
|
||||
- Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback.
|
||||
- Цей окремий loopback API браузера **не** використовує заголовки ідентичності trusted-proxy або
|
||||
Tailscale Serve.
|
||||
- Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера
|
||||
не успадковують ці режими з ідентифікаційними даними; залишайте їх лише для loopback.
|
||||
|
||||
### Контракт помилок `/act`
|
||||
|
||||
`POST /act` використовує структуровану відповідь про помилку для перевірки на рівні маршруту та збоїв політик:
|
||||
`POST /act` використовує структуровану відповідь помилки для перевірки на рівні маршруту і
|
||||
збоїв політики:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
@ -58,43 +61,44 @@ x-i18n:
|
||||
Поточні значення `code`:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): корисне навантаження дії не пройшло нормалізацію або перевірку.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з типом дії, який не підтримується.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або перевірку.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з непідтримуваним типом дії.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено конфігурацією.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з цільовим об’єктом запиту.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з ціллю запиту.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session.
|
||||
|
||||
Інші збої під час виконання все ще можуть повертати `{ "error": "<message>" }` без поля `code`.
|
||||
Інші збої під час виконання все ще можуть повертати `{ "error": "<message>" }` без
|
||||
поля `code`.
|
||||
|
||||
### Вимога Playwright
|
||||
|
||||
Для деяких можливостей (navigate/act/AI snapshot/role snapshot, скриншоти елементів,
|
||||
PDF) потрібен Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають
|
||||
Деякі функції (navigate/act/AI snapshot/role snapshot, screenshot елемента,
|
||||
PDF) потребують Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають
|
||||
зрозумілу помилку 501.
|
||||
|
||||
Що все ще працює без Playwright:
|
||||
|
||||
- ARIA-знімки
|
||||
- Скриншоти сторінки для керованого браузера `openclaw`, коли доступний WebSocket
|
||||
CDP для окремої вкладки
|
||||
- Скриншоти сторінки для профілів `existing-session` / Chrome MCP
|
||||
- Скриншоти на основі refs для `existing-session` (`--ref`) із виводу snapshot
|
||||
- ARIA snapshot
|
||||
- Screenshot сторінки для керованого браузера `openclaw`, коли доступний CDP
|
||||
WebSocket для кожної вкладки
|
||||
- Screenshot сторінки для профілів `existing-session` / Chrome MCP
|
||||
- Screenshot на основі ref для `existing-session` (`--ref`) з виводу snapshot
|
||||
|
||||
Що все ще потребує Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- AI-знімки / role snapshots
|
||||
- Скриншоти елементів за CSS-селектором (`--element`)
|
||||
- AI snapshot / role snapshot
|
||||
- Screenshot елемента за CSS-selector (`--element`)
|
||||
- повний експорт PDF браузера
|
||||
|
||||
Скриншоти елементів також не приймають `--full-page`; маршрут повертає `fullPage is
|
||||
Screenshot елемента також відхиляють `--full-page`; маршрут повертає `fullPage is
|
||||
not supported for element screenshots`.
|
||||
|
||||
Якщо ви бачите `Playwright is not available in this gateway build`, відновіть
|
||||
залежності середовища виконання вбудованого browser Plugin, щоб було встановлено
|
||||
`playwright-core`, а потім перезапустіть Gateway. Для пакетних встановлень виконайте `openclaw doctor --fix`.
|
||||
Для Docker також встановіть двійкові файли браузера Chromium, як показано нижче.
|
||||
залежності runtime вбудованого Plugin браузера, щоб було встановлено `playwright-core`,
|
||||
а потім перезапустіть gateway. Для пакетних встановлень виконайте `openclaw doctor --fix`.
|
||||
Для Docker також встановіть бінарні файли браузера Chromium, як показано нижче.
|
||||
|
||||
#### Встановлення Playwright у Docker
|
||||
|
||||
@ -106,13 +110,13 @@ docker compose run --rm openclaw-cli \
|
||||
node /app/node_modules/playwright-core/cli.js install chromium
|
||||
```
|
||||
|
||||
Щоб зберігати завантаження браузера, встановіть `PLAYWRIGHT_BROWSERS_PATH` (наприклад,
|
||||
Щоб зберігати завантаження браузера, задайте `PLAYWRIGHT_BROWSERS_PATH` (наприклад,
|
||||
`/home/node/.cache/ms-playwright`) і переконайтеся, що `/home/node` зберігається через
|
||||
`OPENCLAW_HOME_VOLUME` або bind mount. Див. [Docker](/uk/install/docker).
|
||||
|
||||
## Як це працює (внутрішньо)
|
||||
|
||||
Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери та профілі вільно змінюються під ним.
|
||||
Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери й профілі можуть вільно змінюватися під ним.
|
||||
|
||||
## Короткий довідник CLI
|
||||
|
||||
@ -120,14 +124,14 @@ docker compose run --rm openclaw-cli \
|
||||
|
||||
<AccordionGroup>
|
||||
|
||||
<Accordion title="Основи: стан, вкладки, open/focus/close">
|
||||
<Accordion title="Основи: статус, вкладки, open/focus/close">
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
openclaw browser start
|
||||
openclaw browser stop # також очищає емуляцію для attach-only/remote CDP
|
||||
openclaw browser stop # also clears emulation on attach-only/remote CDP
|
||||
openclaw browser tabs
|
||||
openclaw browser tab # скорочення для поточної вкладки
|
||||
openclaw browser tab # shortcut for current tab
|
||||
openclaw browser tab new
|
||||
openclaw browser tab select 2
|
||||
openclaw browser tab close 2
|
||||
@ -143,12 +147,14 @@ openclaw browser close abcd1234
|
||||
```bash
|
||||
openclaw browser screenshot
|
||||
openclaw browser screenshot --full-page
|
||||
openclaw browser screenshot --ref 12 # або --ref e12
|
||||
openclaw browser screenshot --ref 12 # or --ref e12
|
||||
openclaw browser screenshot --labels
|
||||
openclaw browser snapshot
|
||||
openclaw browser snapshot --format aria --limit 200
|
||||
openclaw browser snapshot --interactive --compact --depth 6
|
||||
openclaw browser snapshot --efficient
|
||||
openclaw browser snapshot --labels
|
||||
openclaw browser snapshot --urls
|
||||
openclaw browser snapshot --selector "#main" --interactive
|
||||
openclaw browser snapshot --frame "iframe#main" --interactive
|
||||
openclaw browser console --level error
|
||||
@ -165,7 +171,7 @@ openclaw browser responsebody "**/api" --max-chars 5000
|
||||
```bash
|
||||
openclaw browser navigate https://example.com
|
||||
openclaw browser resize 1280 720
|
||||
openclaw browser click 12 --double # або e12 для role refs
|
||||
openclaw browser click 12 --double # or e12 for role refs
|
||||
openclaw browser type 23 "hello" --submit
|
||||
openclaw browser press Enter
|
||||
openclaw browser hover 44
|
||||
@ -198,7 +204,7 @@ openclaw browser storage local set theme dark
|
||||
openclaw browser storage session clear
|
||||
openclaw browser set offline on
|
||||
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
|
||||
openclaw browser set credentials user pass # --clear для видалення
|
||||
openclaw browser set credentials user pass # --clear to remove
|
||||
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
|
||||
openclaw browser set media dark
|
||||
openclaw browser set timezone America/New_York
|
||||
@ -212,53 +218,56 @@ openclaw browser set device "iPhone 14"
|
||||
|
||||
Примітки:
|
||||
|
||||
- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед click/press, що викликає вибір файлу або діалог.
|
||||
- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12` або role ref `e12`). CSS-селектори навмисно не підтримуються для дій.
|
||||
- Шляхи download, trace і upload обмежені тимчасовими кореневими каталогами OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`).
|
||||
- `upload` і `dialog` — це виклики **arming**; запускайте їх перед click/press, що запускає вибір файлу/діалог.
|
||||
- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12` або role ref `e12`). CSS selectors навмисно не підтримуються для дій.
|
||||
- Шляхи download, trace і upload обмежені тимчасовими коренями OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`).
|
||||
- `upload` також може напряму встановлювати file input через `--input-ref` або `--element`.
|
||||
|
||||
Прапорці snapshot коротко:
|
||||
Коротко про прапорці snapshot:
|
||||
|
||||
- `--format ai` (типово з Playwright): AI-знімок із числовими refs (`aria-ref="<n>"`).
|
||||
- `--format aria`: дерево доступності, без refs; лише для інспекції.
|
||||
- `--efficient` (або `--mode efficient`): компактний preset role snapshot. Установіть `browser.snapshotDefaults.mode: "efficient"`, щоб зробити це типовим значенням (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)).
|
||||
- `--interactive`, `--compact`, `--depth`, `--selector` примусово вмикають role snapshot із refs `ref=e12`. `--frame "<iframe>"` обмежує role snapshots цим iframe.
|
||||
- `--labels` додає скриншот лише видимої області з накладеними мітками ref (виводить `MEDIA:<path>`).
|
||||
- `--format ai` (типово з Playwright): AI snapshot із числовими ref (`aria-ref="<n>"`).
|
||||
- `--format aria`: дерево доступності, без ref; лише для інспекції.
|
||||
- `--efficient` (або `--mode efficient`): компактний preset role snapshot. Задайте `browser.snapshotDefaults.mode: "efficient"`, щоб зробити це типовим значенням (див. [Gateway configuration](/uk/gateway/configuration-reference#browser)).
|
||||
- `--interactive`, `--compact`, `--depth`, `--selector` примусово вмикають role snapshot із ref виду `ref=e12`. `--frame "<iframe>"` обмежує role snapshot вказаним iframe.
|
||||
- `--labels` додає screenshot лише видимої області з накладеними позначками ref (виводить `MEDIA:<path>`).
|
||||
- `--urls` додає виявлені адреси посилань до AI snapshot.
|
||||
|
||||
## Знімки та refs
|
||||
## Snapshot і ref
|
||||
|
||||
OpenClaw підтримує два стилі “snapshot”:
|
||||
|
||||
- **AI snapshot (числові refs)**: `openclaw browser snapshot` (типово; `--format ai`)
|
||||
- Вивід: текстовий знімок, що містить числові refs.
|
||||
- **AI snapshot (числові ref)**: `openclaw browser snapshot` (типово; `--format ai`)
|
||||
- Вивід: текстовий snapshot, який містить числові ref.
|
||||
- Дії: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Внутрішньо ref визначається через `aria-ref` у Playwright.
|
||||
- Внутрішньо ref розв’язується через `aria-ref` у Playwright.
|
||||
|
||||
- **Role snapshot (role refs на кшталт `e12`)**: `openclaw browser snapshot --interactive` (або `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- **Role snapshot (role ref на кшталт `e12`)**: `openclaw browser snapshot --interactive` (або `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Вивід: список/дерево на основі ролей із `[ref=e12]` (і необов’язковим `[nth=1]`).
|
||||
- Дії: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Внутрішньо ref визначається через `getByRole(...)` (плюс `nth()` для дублікатів).
|
||||
- Додайте `--labels`, щоб включити скриншот видимої області з накладеними мітками `e12`.
|
||||
- Внутрішньо ref розв’язується через `getByRole(...)` (плюс `nth()` для дублікатів).
|
||||
- Додайте `--labels`, щоб включити screenshot видимої області з накладеними позначками `e12`.
|
||||
- Додайте `--urls`, коли текст посилання неоднозначний і агенту потрібні конкретні
|
||||
цілі навігації.
|
||||
|
||||
Поведінка ref:
|
||||
|
||||
- Refs **не є стабільними між переходами навігації**; якщо щось не спрацювало, повторно виконайте `snapshot` і використайте новий ref.
|
||||
- Якщо role snapshot було зроблено з `--frame`, role refs обмежуються цим iframe до наступного role snapshot.
|
||||
- Ref **не є стабільними між переходами**; якщо щось не спрацювало, знову виконайте `snapshot` і використайте новий ref.
|
||||
- Якщо role snapshot було зроблено з `--frame`, role ref обмежуються цим iframe до наступного role snapshot.
|
||||
|
||||
## Розширені можливості wait
|
||||
## Розширені можливості очікування
|
||||
|
||||
Можна чекати не лише на час/текст:
|
||||
Можна очікувати не лише час/текст:
|
||||
|
||||
- Очікування URL (glob-маски підтримуються Playwright):
|
||||
- Очікування URL (glob-шаблони підтримуються Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- Очікування стану завантаження:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- Очікування предиката JS:
|
||||
- Очікування JS-предиката:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- Очікування, поки селектор стане видимим:
|
||||
- Очікування, поки selector стане видимим:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Їх можна поєднувати:
|
||||
Їх можна комбінувати:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -270,11 +279,11 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Потоки налагодження
|
||||
|
||||
Коли дія завершується помилкою (наприклад, “not visible”, “strict mode violation”, “covered”):
|
||||
Коли дія не спрацьовує (наприклад, “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Використайте `click <ref>` / `type <ref>` (віддавайте перевагу role refs в interactive mode)
|
||||
3. Якщо все одно не працює: `openclaw browser highlight <ref>`, щоб побачити, на що націлюється Playwright
|
||||
2. Використайте `click <ref>` / `type <ref>` (у інтерактивному режимі віддавайте перевагу role ref)
|
||||
3. Якщо все одно не спрацьовує: `openclaw browser highlight <ref>`, щоб побачити, на що націлений Playwright
|
||||
4. Якщо сторінка поводиться дивно:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
@ -285,7 +294,7 @@ openclaw browser wait "#main" \
|
||||
|
||||
## JSON-вивід
|
||||
|
||||
`--json` призначено для сценаріїв і структурованих інструментів.
|
||||
`--json` призначений для скриптування й структурованих інструментів.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -296,35 +305,35 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Role snapshots у JSON містять `refs` і невеликий блок `stats` (lines/chars/refs/interactive), щоб інструменти могли оцінювати розмір і щільність корисного навантаження.
|
||||
Role snapshot у JSON включають `refs` плюс невеликий блок `stats` (рядки/символи/ref/interactive), щоб інструменти могли оцінювати розмір і щільність payload.
|
||||
|
||||
## Параметри стану та середовища
|
||||
|
||||
Вони корисні для сценаріїв на кшталт “змусити сайт поводитися як X”:
|
||||
Вони корисні для потоків на кшталт “змусити сайт поводитися як X”:
|
||||
|
||||
- Cookies: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Офлайн: `set offline on|off`
|
||||
- Заголовки: `set headers --headers-json '{"X-Debug":"1"}'` (застарілий варіант `set headers --json '{"X-Debug":"1"}'` і далі підтримується)
|
||||
- HTTP Basic auth: `set credentials user pass` (або `--clear`)
|
||||
- Offline: `set offline on|off`
|
||||
- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (застарілий `set headers --json '{"X-Debug":"1"}'` усе ще підтримується)
|
||||
- HTTP basic auth: `set credentials user pass` (або `--clear`)
|
||||
- Геолокація: `set geo <lat> <lon> --origin "https://example.com"` (або `--clear`)
|
||||
- Медіа: `set media dark|light|no-preference|none`
|
||||
- Часовий пояс / locale: `set timezone ...`, `set locale ...`
|
||||
- Media: `set media dark|light|no-preference|none`
|
||||
- Часовий пояс / локаль: `set timezone ...`, `set locale ...`
|
||||
- Пристрій / viewport:
|
||||
- `set device "iPhone 14"` (preset-и пристроїв Playwright)
|
||||
- `set device "iPhone 14"` (preset пристроїв Playwright)
|
||||
- `set viewport 1280 720`
|
||||
|
||||
## Безпека та конфіденційність
|
||||
## Безпека та приватність
|
||||
|
||||
- Профіль браузера openclaw може містити сеанси з виконаним входом; ставтеся до нього як до чутливих даних.
|
||||
- Профіль браузера openclaw може містити активні сеанси входу; вважайте його чутливим.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` і `wait --fn`
|
||||
виконують довільний JavaScript у контексті сторінки. Prompt injection може
|
||||
спрямувати це. Вимкніть це за допомогою `browser.evaluateEnabled=false`, якщо воно вам не потрібне.
|
||||
- Щодо входу на сайти та приміток про anti-bot (X/Twitter тощо), див. [Browser login + X/Twitter posting](/uk/tools/browser-login).
|
||||
спрямувати це. Вимкніть його через `browser.evaluateEnabled=false`, якщо він вам не потрібен.
|
||||
- Для входу на сайти та приміток щодо антибот-захисту (X/Twitter тощо) див. [Browser login + X/Twitter posting](/uk/tools/browser-login).
|
||||
- Тримайте хост Gateway/node приватним (лише loopback або лише tailnet).
|
||||
- Віддалені кінцеві точки CDP мають широкі можливості; використовуйте тунелювання та захищайте їх.
|
||||
- Віддалені кінцеві точки CDP мають широкі можливості; тунелюйте й захищайте їх.
|
||||
|
||||
Приклад strict-mode (типово блокує приватні/внутрішні адреси призначення):
|
||||
Приклад strict-mode (типово блокує приватні/внутрішні цілі призначення):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -332,7 +341,7 @@ Role snapshots у JSON містять `refs` і невеликий блок `sta
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // необов’язковий точний дозвіл
|
||||
allowedHostnames: ["localhost"], // optional exact allow
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -342,5 +351,5 @@ Role snapshots у JSON містять `refs` і невеликий блок `sta
|
||||
|
||||
- [Browser](/uk/tools/browser) — огляд, конфігурація, профілі, безпека
|
||||
- [Browser login](/uk/tools/browser-login) — вхід на сайти
|
||||
- [Browser Linux troubleshooting](/uk/tools/browser-linux-troubleshooting)
|
||||
- [Browser WSL2 troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
- [Усунення несправностей Browser на Linux](/uk/tools/browser-linux-troubleshooting)
|
||||
- [Усунення несправностей Browser у WSL2](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання автоматизації браузера, керованої агентом
|
||||
- Налагодження, чому openclaw заважає вашому власному Chrome
|
||||
- Реалізація налаштувань браузера + життєвого циклу в додатку macOS
|
||||
- Додавання автоматизації браузера під керуванням агента
|
||||
- Налагодження причин, чому openclaw втручається у роботу вашого власного Chrome
|
||||
- Реалізація налаштувань Browser + життєвого циклу в застосунку macOS
|
||||
summary: Інтегрований сервіс керування браузером + команди дій
|
||||
title: Браузер (керований OpenClaw)
|
||||
title: Browser (керований OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T23:39:04Z"
|
||||
generated_at: "2026-04-25T00:04:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d804015e89f68541c0bf3149a91d4f38618bfc3b9e13ca8cffc8b9ca4d5025c6
|
||||
source_hash: ba8f0233c787ba03b9dd9349918367b9a2ec08ef4fac2367e100aa2b42c311ff
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,43 +18,44 @@ OpenClaw може запускати **окремий профіль Chrome/Brav
|
||||
Він ізольований від вашого особистого браузера та керується через невеликий локальний
|
||||
сервіс керування всередині Gateway (лише loopback).
|
||||
|
||||
Погляд для початківців:
|
||||
Пояснення для початківців:
|
||||
|
||||
- Думайте про це як про **окремий браузер лише для агента**.
|
||||
- Профіль `openclaw` **не** торкається профілю вашого особистого браузера.
|
||||
- Агент може **відкривати вкладки, читати сторінки, натискати й вводити текст** у безпечному середовищі.
|
||||
- Вбудований профіль `user` підключається до вашої реальної авторизованої сесії Chrome через Chrome MCP.
|
||||
- Вбудований профіль `user` під’єднується до вашого справжнього сеансу Chrome, у якому виконано вхід, через Chrome MCP.
|
||||
|
||||
## Що ви отримуєте
|
||||
|
||||
- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом).
|
||||
- Детерміноване керування вкладками (список/відкрити/фокус/закрити).
|
||||
- Дії агента (клік/введення/перетягування/вибір), знімки стану, знімки екрана, PDF.
|
||||
- Дії агента (click/type/drag/select), знімки, скриншоти, PDF.
|
||||
- Вбудований skill `browser-automation`, який навчає агентів циклу відновлення snapshot,
|
||||
stable-tab, stale-ref і manual-blocker, коли увімкнено browser plugin.
|
||||
stable-tab, stale-ref і manual-blocker, коли Plugin браузера увімкнено.
|
||||
- Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Цей браузер **не** призначений для вашого щоденного використання. Це безпечна, ізольована поверхня для
|
||||
Цей браузер — **не** ваш щоденний основний браузер. Це безпечна, ізольована поверхня для
|
||||
автоматизації та перевірки агентом.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw doctor
|
||||
openclaw browser --browser-profile openclaw status
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
Якщо ви отримуєте “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть
|
||||
Якщо ви бачите “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть
|
||||
Gateway.
|
||||
|
||||
Якщо `openclaw browser` повністю відсутня або агент каже, що browser tool
|
||||
недоступний, перейдіть до [Відсутня команда browser або tool](/uk/tools/browser#missing-browser-command-or-tool).
|
||||
Якщо `openclaw browser` узагалі відсутній або агент каже, що інструмент Browser
|
||||
недоступний, перейдіть до [Відсутня команда browser або інструмент](/uk/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Керування Plugin
|
||||
|
||||
Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим plugin, який реєструє ту саму назву інструмента `browser`:
|
||||
Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє той самий інструмент `browser`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -68,29 +69,29 @@ Gateway.
|
||||
}
|
||||
```
|
||||
|
||||
Для типових значень потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Вимкнення лише plugin прибирає CLI `openclaw browser`, gateway-метод `browser.request`, інструмент агента та сервіс керування як єдине ціле; ваша конфігурація `browser.*` залишається недоторканою для заміни.
|
||||
Для типових налаштувань потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Вимкнення лише Plugin прибирає CLI `openclaw browser`, метод gateway `browser.request`, інструмент агента та сервіс керування як єдине ціле; ваша конфігурація `browser.*` залишається недоторканою для заміни.
|
||||
|
||||
Зміни конфігурації браузера потребують перезапуску Gateway, щоб plugin міг повторно зареєструвати свій сервіс.
|
||||
Зміни конфігурації Browser вимагають перезапуску Gateway, щоб Plugin міг знову зареєструвати свій сервіс.
|
||||
|
||||
## Вказівки для агента
|
||||
|
||||
Browser plugin постачається з двома рівнями вказівок для агента:
|
||||
Plugin браузера постачається з двома рівнями вказівок для агента:
|
||||
|
||||
- Опис інструмента `browser` містить компактний завжди активний контракт: вибирати
|
||||
правильний профіль, зберігати ref в межах тієї самої вкладки, використовувати `tabId`/мітки для
|
||||
націлювання на вкладки та завантажувати browser skill для багатокрокової роботи.
|
||||
правильний профіль, тримати ref в межах тієї самої вкладки, використовувати
|
||||
`tabId`/мітки для націлювання на вкладки та завантажувати skill браузера для багатокрокової роботи.
|
||||
- Вбудований skill `browser-automation` містить довший робочий цикл:
|
||||
спочатку перевіряти статус/вкладки, позначати мітками вкладки завдання, робити snapshot перед дією,
|
||||
повторно знімати snapshot після змін інтерфейсу, один раз відновлювати stale refs і повідомляти про блокування через login/2FA/captcha або
|
||||
камеру/мікрофон як про ручну дію, замість того щоб вгадувати.
|
||||
спочатку перевіряти статус/вкладки, позначати вкладки завдань, робити snapshot перед дією,
|
||||
повторно робити snapshot після змін UI, один раз відновлюватися після stale ref і
|
||||
повідомляти про login/2FA/captcha або блокування camera/microphone як про ручну дію, а не вгадувати.
|
||||
|
||||
Skills, вбудовані в plugin, перелічуються серед доступних skill агента, коли
|
||||
plugin увімкнено. Повні інструкції skill завантажуються за потреби, тому звичайні
|
||||
ходи не оплачують повну вартість у токенах.
|
||||
Skills, що постачаються разом із Plugin, перелічено в доступних skills агента, коли
|
||||
Plugin увімкнено. Повні інструкції skill завантажуються на вимогу, тому звичайні
|
||||
ходи не оплачують повну вартість токенів.
|
||||
|
||||
## Відсутня команда browser або tool
|
||||
## Відсутня команда browser або інструмент
|
||||
|
||||
Якщо `openclaw browser` невідома після оновлення, відсутній `browser.request` або агент повідомляє, що browser tool недоступний, звичайна причина — список `plugins.allow`, у якому немає `browser`. Додайте його:
|
||||
Якщо після оновлення `openclaw browser` невідомий, `browser.request` відсутній або агент повідомляє, що інструмент browser недоступний, звичайною причиною є список `plugins.allow`, у якому немає `browser`. Додайте його:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -100,25 +101,25 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
}
|
||||
```
|
||||
|
||||
`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist керує завантаженням plugin, а політика інструментів застосовується лише після завантаження. Видалення `plugins.allow` повністю також відновлює типову поведінку.
|
||||
`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist керує завантаженням Plugin, а політика інструментів застосовується лише після завантаження. Повне видалення `plugins.allow` також відновлює типову поведінку.
|
||||
|
||||
## Профілі: `openclaw` проти `user`
|
||||
|
||||
- `openclaw`: керований, ізольований браузер (розширення не потрібне).
|
||||
- `user`: вбудований профіль підключення Chrome MCP до вашої **реальної авторизованої сесії Chrome**.
|
||||
- `openclaw`: керований, ізольований Browser (розширення не потрібне).
|
||||
- `user`: вбудований профіль під’єднання Chrome MCP до вашого **справжнього Chrome із виконаним входом**.
|
||||
|
||||
Для викликів browser tool агентом:
|
||||
Для викликів інструмента Browser агентом:
|
||||
|
||||
- Типово: використовуйте ізольований браузер `openclaw`.
|
||||
- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії та користувач
|
||||
перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення.
|
||||
- Типово: використовуйте ізольований Browser `openclaw`.
|
||||
- Надавайте перевагу `profile="user"`, коли важливі наявні сеанси з виконаним входом і користувач
|
||||
перебуває за комп’ютером, щоб натиснути/схвалити будь-який запит на під’єднання.
|
||||
- `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера.
|
||||
|
||||
Установіть `browser.defaultProfile: "openclaw"`, якщо хочете типово використовувати керований режим.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`.
|
||||
Налаштування Browser розміщено в `~/.openclaw/openclaw.json`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -163,29 +164,29 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
|
||||
<Accordion title="Порти та доступність">
|
||||
|
||||
- Сервіс керування прив’язується до local loopback на порті, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зміщує похідні порти в межах тієї самої групи.
|
||||
- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується локальний керований порт CDP.
|
||||
- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP для віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до handshake WebSocket для віддаленого CDP.
|
||||
- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тому самому сімействі.
|
||||
- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, він типово вказує на локальний керований порт CDP.
|
||||
- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP для віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до WebSocket-handshake віддаленого CDP.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Політика SSRF">
|
||||
|
||||
- Навігація браузера та open-tab захищені від SSRF перед переходом і повторно перевіряються в режимі best-effort для фінального URL `http(s)` після нього.
|
||||
- У строгому режимі SSRF також перевіряються виявлення віддаленої CDP endpoint і запити `/json/version` (`cdpUrl`).
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі навмисно довірений.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як legacy alias.
|
||||
- Навігація Browser і відкриття вкладки захищені від SSRF до навігації та повторно перевіряються за найкращої можливості на фінальному URL `http(s)` після неї.
|
||||
- У строгому режимі SSRF також перевіряються виявлення віддаленої кінцевої точки CDP і проби `/json/version` (`cdpUrl`).
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ Browser до приватної мережі навмисно довірений.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка профілю">
|
||||
<Accordion title="Поведінка профілів">
|
||||
|
||||
- `attachOnly: true` означає ніколи не запускати локальний браузер; підключатися лише якщо він уже працює.
|
||||
- `color` (на верхньому рівні та для кожного профілю) тонує інтерфейс браузера, щоб ви могли бачити, який профіль активний.
|
||||
- Типовий профіль — `openclaw` (керований автономний). Використайте `defaultProfile: "user"`, щоб перейти на авторизований браузер користувача.
|
||||
- Порядок автовиявлення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не задавайте `cdpUrl` для цього driver.
|
||||
- Задайте `browser.profiles.<name>.userDataDir`, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium (Brave, Edge тощо).
|
||||
- `attachOnly: true` означає ніколи не запускати локальний Browser; лише під’єднуватися, якщо він уже працює.
|
||||
- `color` (на верхньому рівні та для кожного профілю) підфарбовує UI браузера, щоб ви могли бачити, який профіль активний.
|
||||
- Типовий профіль — `openclaw` (керований автономний). Використовуйте `defaultProfile: "user"`, щоб типово перейти на браузер користувача з виконаним входом.
|
||||
- Порядок автовиявлення: системний типовий браузер, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не задавайте `cdpUrl` для цього драйвера.
|
||||
- Установіть `browser.profiles.<name>.userDataDir`, коли профіль existing-session має під’єднуватися до нетипового користувацького профілю Chromium (Brave, Edge тощо).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -193,15 +194,15 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
|
||||
## Використання Brave (або іншого браузера на базі Chromium)
|
||||
|
||||
Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо),
|
||||
OpenClaw використовує його автоматично. Задайте `browser.executablePath`, щоб перевизначити
|
||||
Якщо вашим **системним типовим** браузером є браузер на базі Chromium (Chrome/Brave/Edge тощо),
|
||||
OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити
|
||||
автовиявлення:
|
||||
|
||||
```bash
|
||||
openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
```
|
||||
|
||||
Або задайте це в конфігурації для кожної платформи:
|
||||
Або задайте це в конфігурації, окремо для кожної платформи:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS">
|
||||
@ -235,51 +236,51 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
|
||||
## Локальне та віддалене керування
|
||||
|
||||
- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування й може запускати локальний браузер.
|
||||
- **Віддалене керування (host node):** запустіть host node на машині, де є браузер; Gateway проксуватиме до нього дії браузера.
|
||||
- **Віддалений CDP:** задайте `browser.profiles.<name>.cdpUrl` (або `browser.cdpUrl`), щоб
|
||||
підключитися до віддаленого браузера на базі Chromium. У цьому разі OpenClaw не запускатиме локальний браузер.
|
||||
- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування та може запускати локальний Browser.
|
||||
- **Віддалене керування (хост вузла):** запустіть хост вузла на машині, де є браузер; Gateway проксуватиме до нього дії Browser.
|
||||
- **Віддалений CDP:** установіть `browser.profiles.<name>.cdpUrl` (або `browser.cdpUrl`), щоб
|
||||
під’єднатися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний Browser.
|
||||
|
||||
Поведінка зупинки відрізняється залежно від режиму профілю:
|
||||
|
||||
- локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який
|
||||
запустив OpenClaw
|
||||
- профілі attach-only та віддаленого CDP: `openclaw browser stop` закриває активну
|
||||
сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport,
|
||||
color scheme, locale, timezone, offline mode та подібний стан), навіть
|
||||
- профілі attach-only і віддалені профілі CDP: `openclaw browser stop` закриває активний
|
||||
сеанс керування та скидає перевизначення емуляції Playwright/CDP (viewport,
|
||||
колірна схема, locale, timezone, offline mode та подібний стан), навіть
|
||||
якщо OpenClaw не запускав жодного процесу браузера
|
||||
|
||||
URL віддаленого CDP можуть містити автентифікацію:
|
||||
Віддалені URL CDP можуть містити auth:
|
||||
|
||||
- Query-токени (наприклад, `https://provider.example?token=<token>`)
|
||||
- токени в query (наприклад, `https://provider.example?token=<token>`)
|
||||
- HTTP Basic auth (наприклад, `https://user:pass@provider.example`)
|
||||
|
||||
OpenClaw зберігає автентифікацію під час виклику endpoint `/json/*` і під час підключення
|
||||
до WebSocket CDP. Віддавайте перевагу змінним середовища або менеджерам секретів для
|
||||
токенів замість того, щоб комітити їх у файли конфігурації.
|
||||
OpenClaw зберігає auth під час викликів кінцевих точок `/json/*` і під час під’єднання
|
||||
до WebSocket CDP. Для токенів надавайте перевагу змінним середовища або менеджерам секретів
|
||||
замість коміту їх у файли конфігурації.
|
||||
|
||||
## Node browser proxy (типова поведінка без додаткового налаштування)
|
||||
## Проксі Browser вузла (типова поведінка без конфігурації)
|
||||
|
||||
Якщо ви запускаєте **host node** на машині, де є ваш браузер, OpenClaw може
|
||||
автоматично маршрутизувати виклики browser tool до цього node без будь-якої додаткової конфігурації браузера.
|
||||
Це типовий шлях для віддалених gateway.
|
||||
Якщо ви запускаєте **хост вузла** на машині, де є ваш браузер, OpenClaw може
|
||||
автоматично маршрутизувати виклики інструмента Browser до цього вузла без жодної додаткової конфігурації Browser.
|
||||
Це типовий шлях для віддалених Gateway.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Host node відкриває свій локальний сервер керування браузером через **proxy command**.
|
||||
- Профілі беруться з власної конфігурації `browser.profiles` цього node (так само, як локально).
|
||||
- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для legacy/типової поведінки: усі налаштовані профілі залишаються доступними через proxy, включно з маршрутами створення/видалення профілів.
|
||||
- Якщо ви задасте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядатиме це як межу найменших привілеїв: лише профілі з allowlist можна буде використовувати, а маршрути створення/видалення постійних профілів буде заблоковано на поверхні proxy.
|
||||
- Вимкніть це, якщо воно вам не потрібне:
|
||||
- На node: `nodeHost.browserProxy.enabled=false`
|
||||
- Хост вузла надає свій локальний сервер керування браузером через **проксі-команду**.
|
||||
- Профілі беруться з власної конфігурації `browser.profiles` вузла (так само, як локально).
|
||||
- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів.
|
||||
- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядає це як межу мінімальних привілеїв: лише профілі з allowlist можуть бути ціллю, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі.
|
||||
- Вимкніть, якщо не хочете це використовувати:
|
||||
- На вузлі: `nodeHost.browserProxy.enabled=false`
|
||||
- На gateway: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless (хостинговий віддалений CDP)
|
||||
## Browserless (розміщений віддалений CDP)
|
||||
|
||||
[Browserless](https://browserless.io) — це хостинговий сервіс Chromium, який відкриває
|
||||
URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але
|
||||
для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket
|
||||
з документації Browserless щодо підключення.
|
||||
[Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає
|
||||
URL під’єднання CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але
|
||||
для профілю віддаленого браузера найпростішим варіантом є прямий URL WebSocket
|
||||
із документації Browserless щодо під’єднання.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -302,40 +303,40 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може
|
||||
|
||||
Примітки:
|
||||
|
||||
- Замініть `<BROWSERLESS_API_KEY>` на ваш справжній токен Browserless.
|
||||
- Виберіть endpoint регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію).
|
||||
- Замініть `<BROWSERLESS_API_KEY>` своїм справжнім токеном Browserless.
|
||||
- Виберіть регіональну кінцеву точку, яка відповідає вашому обліковому запису Browserless (див. їхню документацію).
|
||||
- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на
|
||||
`wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw
|
||||
`wss://` для прямого під’єднання CDP, або залишити URL HTTPS і дозволити OpenClaw
|
||||
виявити `/json/version`.
|
||||
|
||||
## Прямі провайдери WebSocket CDP
|
||||
|
||||
Деякі хостингові сервіси браузера надають **пряму endpoint WebSocket**, а не
|
||||
стандартне HTTP-виявлення CDP (`/json/version`). OpenClaw приймає три форми
|
||||
URL CDP і автоматично вибирає правильну стратегію підключення:
|
||||
Деякі розміщені сервіси браузерів надають **пряму кінцеву точку WebSocket** замість
|
||||
стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три
|
||||
форми URL CDP і автоматично вибирає правильну стратегію під’єднання:
|
||||
|
||||
- **HTTP(S) виявлення** — `http://host[:port]` або `https://host[:port]`.
|
||||
OpenClaw викликає `/json/version`, щоб виявити URL налагодження WebSocket, а потім
|
||||
підключається. Резервного переходу на WebSocket немає.
|
||||
- **Прямі endpoint WebSocket** — `ws://host[:port]/devtools/<kind>/<id>` або
|
||||
- **Виявлення HTTP(S)** — `http://host[:port]` або `https://host[:port]`.
|
||||
OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім
|
||||
під’єднується. Fallback на WebSocket немає.
|
||||
- **Прямі кінцеві точки WebSocket** — `ws://host[:port]/devtools/<kind>/<id>` або
|
||||
`wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
|
||||
OpenClaw підключається напряму через handshake WebSocket і повністю пропускає
|
||||
OpenClaw під’єднується безпосередньо через WebSocket handshake і повністю пропускає
|
||||
`/json/version`.
|
||||
- **Кореневі bare WebSocket** — `ws://host[:port]` або `wss://host[:port]` без
|
||||
- **Кореневі URL WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без
|
||||
шляху `/devtools/...` (наприклад, [Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP-виявлення
|
||||
`/json/version` (нормалізуючи схему до `http`/`https`);
|
||||
якщо виявлення повертає `webSocketDebuggerUrl`, він використовується, інакше OpenClaw
|
||||
переходить до прямого handshake WebSocket на bare root. Це дозволяє
|
||||
bare `ws://`, спрямованому на локальний Chrome, усе одно підключатися, оскільки Chrome
|
||||
приймає WebSocket upgrades лише на конкретному шляху для цілі з
|
||||
через `/json/version` (нормалізуючи схему до `http`/`https`);
|
||||
якщо виявлення повертає `webSocketDebuggerUrl`, використовується він, інакше OpenClaw
|
||||
переходить до прямого WebSocket handshake на корені без шляху. Це дозволяє
|
||||
bare `ws://`, спрямованому на локальний Chrome, усе ж під’єднатися, оскільки Chrome приймає
|
||||
WebSocket upgrade лише на конкретному шляху для цілі з
|
||||
`/json/version`.
|
||||
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску
|
||||
headless браузерів із вбудованим розв’язанням CAPTCHA, stealth mode і residential
|
||||
proxies.
|
||||
headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode і residential
|
||||
proxy.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -358,61 +359,60 @@ proxies.
|
||||
|
||||
- [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key**
|
||||
з [панелі Overview](https://www.browserbase.com/overview).
|
||||
- Замініть `<BROWSERBASE_API_KEY>` на ваш справжній API key Browserbase.
|
||||
- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому
|
||||
ручний крок створення сесії не потрібен.
|
||||
- Безкоштовний тариф дозволяє одну одночасну сесію та одну browser hour на місяць.
|
||||
Див. [ціни](https://www.browserbase.com/pricing) для лімітів платних планів.
|
||||
- Див. [документацію Browserbase](https://docs.browserbase.com) для повного API
|
||||
reference, посібників SDK та прикладів інтеграції.
|
||||
- Замініть `<BROWSERBASE_API_KEY>` на свій справжній ключ API Browserbase.
|
||||
- Browserbase автоматично створює сеанс браузера під час WebSocket-під’єднання, тому
|
||||
окремий крок ручного створення сеансу не потрібен.
|
||||
- Безкоштовний тариф дозволяє один одночасний сеанс і одну браузерну годину на місяць.
|
||||
Обмеження платних тарифів дивіться в [pricing](https://www.browserbase.com/pricing).
|
||||
- Повний довідник API, посібники з SDK і приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com).
|
||||
|
||||
## Безпека
|
||||
|
||||
Ключові ідеї:
|
||||
|
||||
- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairинг node.
|
||||
- Окремий loopback HTTP API браузера використовує **лише автентифікацію shared-secret**:
|
||||
bearer auth токена gateway, `x-openclaw-password` або HTTP Basic auth із
|
||||
- Керування Browser доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing вузла.
|
||||
- Окремий loopback HTTP API Browser використовує **лише автентифікацію через shared secret**:
|
||||
bearer auth через токен gateway, `x-openclaw-password` або HTTP Basic auth із
|
||||
налаштованим паролем gateway.
|
||||
- Заголовки ідентичності Tailscale Serve і `gateway.auth.mode: "trusted-proxy"`
|
||||
**не** автентифікують цей окремий loopback API браузера.
|
||||
- Якщо керування браузером увімкнено і не налаштовано shared-secret auth, OpenClaw
|
||||
**не** автентифікують цей окремий loopback API Browser.
|
||||
- Якщо керування Browser увімкнено й не налаштовано жодної автентифікації через shared secret, OpenClaw
|
||||
автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації.
|
||||
- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже має значення
|
||||
- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення
|
||||
`password`, `none` або `trusted-proxy`.
|
||||
- Тримайте Gateway і будь-які node hosts у приватній мережі (Tailscale); уникайте публічного доступу.
|
||||
- Вважайте URL/токени віддаленого CDP секретами; віддавайте перевагу env vars або менеджеру секретів.
|
||||
- Тримайте Gateway і будь-які хости вузлів у приватній мережі (Tailscale); уникайте публічного доступу.
|
||||
- Сприймайте віддалені URL/токени CDP як секрети; надавайте перевагу змінним середовища або менеджеру секретів.
|
||||
|
||||
Поради для віддаленого CDP:
|
||||
Поради щодо віддаленого CDP:
|
||||
|
||||
- За можливості віддавайте перевагу зашифрованим endpoint (HTTPS або WSS) і короткоживучим токенам.
|
||||
- За можливості використовуйте шифровані кінцеві точки (HTTPS або WSS) і короткоживучі токени.
|
||||
- Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації.
|
||||
|
||||
## Профілі (кілька браузерів)
|
||||
|
||||
OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути:
|
||||
|
||||
- **керовані OpenClaw**: окремий екземпляр браузера на базі Chromium із власною директорією даних користувача + портом CDP
|
||||
- **віддалені**: явний URL CDP (браузер на базі Chromium працює деінде)
|
||||
- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP
|
||||
- **керованими OpenClaw**: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних і портом CDP
|
||||
- **віддаленими**: явний URL CDP (браузер на базі Chromium працює деінде)
|
||||
- **наявним сеансом**: ваш наявний профіль Chrome через автопід’єднання Chrome DevTools MCP
|
||||
|
||||
Типові значення:
|
||||
Типова поведінка:
|
||||
|
||||
- Профіль `openclaw` створюється автоматично, якщо його немає.
|
||||
- Профіль `user` вбудований для підключення Chrome MCP existing-session.
|
||||
- Профілі existing-session, окрім `user`, вмикаються явно; створюйте їх через `--driver existing-session`.
|
||||
- Профіль `user` вбудований для existing-session attach через Chrome MCP.
|
||||
- Профілі existing-session, окрім `user`, створюються за бажанням; створюйте їх через `--driver existing-session`.
|
||||
- Локальні порти CDP типово виділяються з діапазону **18800–18899**.
|
||||
- Видалення профілю переміщує його локальну директорію даних до Trash.
|
||||
- Видалення профілю переміщує його локальний каталог даних до Trash.
|
||||
|
||||
Усі endpoint керування приймають `?profile=<name>`; CLI використовує `--browser-profile`.
|
||||
Усі кінцеві точки керування приймають `?profile=<name>`; CLI використовує `--browser-profile`.
|
||||
|
||||
## Existing-session через Chrome DevTools MCP
|
||||
|
||||
OpenClaw також може підключатися до запущеного профілю браузера на базі Chromium через
|
||||
офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу,
|
||||
OpenClaw також може під’єднатися до профілю браузера на базі Chromium, що вже працює, через
|
||||
офіційний сервер Chrome DevTools MCP. Це дозволяє повторно використовувати вкладки та стан входу,
|
||||
які вже відкриті в цьому профілі браузера.
|
||||
|
||||
Офіційні довідкові матеріали та посилання на налаштування:
|
||||
Офіційні довідкові матеріали та посилання для налаштування:
|
||||
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
@ -421,12 +421,12 @@ OpenClaw також може підключатися до запущеного
|
||||
|
||||
- `user`
|
||||
|
||||
Необов’язково: створіть власний кастомний профіль existing-session, якщо хочете
|
||||
іншу назву, колір або директорію даних браузера.
|
||||
Необов’язково: створіть власний профіль existing-session, якщо хочете
|
||||
іншу назву, колір або каталог даних браузера.
|
||||
|
||||
Типова поведінка:
|
||||
|
||||
- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на
|
||||
- Вбудований профіль `user` використовує автопід’єднання Chrome MCP, яке націлюється на
|
||||
типовий локальний профіль Google Chrome.
|
||||
|
||||
Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome:
|
||||
@ -450,7 +450,7 @@ OpenClaw також може підключатися до запущеного
|
||||
|
||||
1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження.
|
||||
2. Увімкніть віддалене налагодження.
|
||||
3. Не закривайте браузер і підтвердьте запит на підключення, коли OpenClaw підключатиметься.
|
||||
3. Залиште браузер запущеним і схваліть запит на під’єднання, коли OpenClaw під’єднається.
|
||||
|
||||
Поширені сторінки inspect:
|
||||
|
||||
@ -458,7 +458,7 @@ OpenClaw також може підключатися до запущеного
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Live smoke test підключення:
|
||||
Smoke-тест live attach:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -467,65 +467,65 @@ openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot --format ai
|
||||
```
|
||||
|
||||
Як виглядає успіх:
|
||||
Ознаки успіху:
|
||||
|
||||
- `status` показує `driver: existing-session`
|
||||
- `status` показує `transport: chrome-mcp`
|
||||
- `status` показує `running: true`
|
||||
- `tabs` перелічує вже відкриті вкладки вашого браузера
|
||||
- `snapshot` повертає refs із вибраної live вкладки
|
||||
- `snapshot` повертає ref із вибраної live-вкладки
|
||||
|
||||
Що перевірити, якщо підключення не працює:
|
||||
Що перевірити, якщо під’єднання не працює:
|
||||
|
||||
- цільовий браузер на базі Chromium має версію `144+`
|
||||
- у сторінці inspect цього браузера увімкнено віддалене налагодження
|
||||
- браузер показав запит на згоду на підключення, і ви його підтвердили
|
||||
- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, що
|
||||
Chrome локально встановлено для типових профілів автопідключення, але він не може
|
||||
увімкнути віддалене налагодження у браузері за вас
|
||||
- браузер показав запит на згоду на під’єднання, і ви його схвалили
|
||||
- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення й перевіряє, що
|
||||
Chrome локально встановлено для типових профілів автопід’єднання, але він не може
|
||||
увімкнути віддалене налагодження з боку браузера за вас
|
||||
|
||||
Використання агентом:
|
||||
|
||||
- Використовуйте `profile="user"`, коли потрібен стан авторизованого браузера користувача.
|
||||
- Якщо ви використовуєте кастомний профіль existing-session, передайте явну назву цього профілю.
|
||||
- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити
|
||||
запит на підключення.
|
||||
- Gateway або node host може запускати `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
- Використовуйте `profile="user"`, коли потрібен стан браузера користувача з виконаним входом.
|
||||
- Якщо ви використовуєте власний профіль existing-session, передавайте явну назву цього профілю.
|
||||
- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб схвалити
|
||||
запит на під’єднання.
|
||||
- Gateway або хост вузла може запускати `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Примітки:
|
||||
|
||||
- Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може
|
||||
виконувати дії у вашій авторизованій сесії браузера.
|
||||
- OpenClaw не запускає браузер для цього driver; він лише підключається.
|
||||
- Цей шлях є ризикованішим, ніж ізольований профіль `openclaw`, оскільки він може
|
||||
діяти всередині вашого браузера із виконаним входом.
|
||||
- OpenClaw не запускає браузер для цього драйвера; він лише під’єднується.
|
||||
- Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо
|
||||
задано `userDataDir`, його буде передано далі для націлювання на цю директорію даних користувача.
|
||||
- Existing-session може підключатися на вибраному host або через підключений
|
||||
browser node. Якщо Chrome працює деінде і жоден browser node не підключено, використовуйте
|
||||
натомість віддалений CDP або node host.
|
||||
задано `userDataDir`, він передається далі для націлювання на цей каталог користувацьких даних.
|
||||
- Existing-session може під’єднуватися на вибраному хості або через під’єднаний
|
||||
вузол Browser. Якщо Chrome працює деінде й жоден вузол Browser не під’єднано, використовуйте
|
||||
віддалений CDP або хост вузла.
|
||||
|
||||
<Accordion title="Обмеження можливостей existing-session">
|
||||
|
||||
Порівняно з керованим профілем `openclaw`, драйвери existing-session мають більше обмежень:
|
||||
|
||||
- **Знімки екрана** — працюють захоплення сторінки й захоплення елемента через `--ref`; CSS-селектори `--element` не підтримуються. `--full-page` не можна поєднувати з `--ref` або `--element`. Для знімків екрана сторінки або елемента за ref Playwright не потрібен.
|
||||
- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують snapshot refs (без CSS-селекторів). `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують окремі тайм-аути для кожного виклику. `select` приймає одне значення.
|
||||
- **Очікування / завантаження / діалог** — `wait --url` підтримує точні, підрядкові та glob-шаблони; `wait --load networkidle` не підтримується. Hooks для завантаження потребують `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Hooks для діалогів не підтримують перевизначення тайм-ауту.
|
||||
- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще потребують шляху керованого браузера.
|
||||
- **Скриншоти** — захоплення сторінки і захоплення елементів через `--ref` працюють; CSS-селектори `--element` — ні. `--full-page` не можна поєднувати з `--ref` або `--element`. Для скриншотів сторінки або елементів на основі ref Playwright не потрібен.
|
||||
- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` вимагають snapshot ref (без CSS-селекторів). `click` підтримує лише ліву кнопку. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують тайм-аути для окремого виклику. `select` приймає одне значення.
|
||||
- **Очікування / upload / dialog** — `wait --url` підтримує точний збіг, підрядок і glob-шаблони; `wait --load networkidle` не підтримується. Хуки upload вимагають `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки dialog не підтримують перевизначення тайм-ауту.
|
||||
- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` і далі потребують шляху керованого браузера.
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Гарантії ізоляції
|
||||
|
||||
- **Окрема директорія даних користувача**: ніколи не торкається профілю вашого особистого браузера.
|
||||
- **Окремі порти**: уникає `9222`, щоб не створювати конфліктів із робочими процесами розробки.
|
||||
- **Детерміноване керування вкладками**: `tabs` повертає спочатку `suggestedTargetId`, а потім
|
||||
стабільні дескриптори `tabId`, як-от `t1`, необов’язкові мітки та сирий `targetId`.
|
||||
Агентам слід повторно використовувати `suggestedTargetId`; сирі id залишаються доступними для
|
||||
- **Окремий каталог користувацьких даних**: ніколи не торкається профілю вашого особистого браузера.
|
||||
- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки.
|
||||
- **Детерміноване керування вкладками**: `tabs` спочатку повертає `suggestedTargetId`, потім
|
||||
стабільні дескриптори `tabId`, такі як `t1`, необов’язкові мітки та сирий `targetId`.
|
||||
Агенти мають повторно використовувати `suggestedTargetId`; сирі id залишаються доступними для
|
||||
налагодження та сумісності.
|
||||
|
||||
## Вибір браузера
|
||||
|
||||
Під час локального запуску OpenClaw вибирає перший доступний:
|
||||
Під час локального запуску OpenClaw вибирає перший доступний браузер:
|
||||
|
||||
1. Chrome
|
||||
2. Brave
|
||||
@ -539,39 +539,39 @@ openclaw browser --browser-profile user snapshot --format ai
|
||||
|
||||
- macOS: перевіряє `/Applications` і `~/Applications`.
|
||||
- Linux: шукає `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо.
|
||||
- Windows: перевіряє типові місця встановлення.
|
||||
- Windows: перевіряє поширені шляхи встановлення.
|
||||
|
||||
## API керування (необов’язково)
|
||||
|
||||
Для сценаріїв і налагодження Gateway надає невеликий **HTTP API керування
|
||||
лише через loopback** плюс відповідний CLI `openclaw browser` (snapshot, refs, wait
|
||||
power-ups, вивід JSON, робочі процеси налагодження). Див.
|
||||
[API керування браузером](/uk/tools/browser-control) для повного reference.
|
||||
Для скриптів і налагодження Gateway надає невеликий **HTTP API керування лише для loopback**
|
||||
та відповідний CLI `openclaw browser` (знімки, ref, розширені можливості wait,
|
||||
JSON-вивід, робочі процеси налагодження). Повний довідник дивіться в
|
||||
[API керування Browser](/uk/tools/browser-control).
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
Для проблем, специфічних для Linux (особливо snap Chromium), див.
|
||||
[Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting).
|
||||
Проблеми, специфічні для Linux (особливо snap Chromium), див. у
|
||||
[усуненні несправностей Browser](/uk/tools/browser-linux-troubleshooting).
|
||||
|
||||
Для конфігурацій із розділеними host WSL2 Gateway + Windows Chrome див.
|
||||
[WSL2 + Windows + усунення несправностей віддаленого Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
Для сценаріїв із розділеними хостами WSL2 Gateway + Windows Chrome див.:
|
||||
[усунення несправностей WSL2 + Windows + віддалений Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
### Помилка запуску CDP проти SSRF-блокування навігації
|
||||
### Збій запуску CDP проти блокування SSRF навігації
|
||||
|
||||
Це різні класи помилок, і вони вказують на різні шляхи в коді.
|
||||
Це різні класи збоїв, і вони вказують на різні шляхи коду.
|
||||
|
||||
- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити справність площини керування браузером.
|
||||
- **SSRF-блокування навігації** означає, що площина керування браузером справна, але ціль навігації сторінки відхилена політикою.
|
||||
- **Збій запуску CDP або готовності** означає, що OpenClaw не може підтвердити, що площина керування браузером справна.
|
||||
- **Блокування SSRF навігації** означає, що площина керування браузером справна, але ціль переходу на сторінку відхиляється політикою.
|
||||
|
||||
Поширені приклади:
|
||||
|
||||
- Помилка запуску або готовності CDP:
|
||||
- Збій запуску CDP або готовності:
|
||||
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
|
||||
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
|
||||
- SSRF-блокування навігації:
|
||||
- потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються помилкою політики браузера/мережі, тоді як `start` і `tabs` усе ще працюють
|
||||
- Блокування SSRF навігації:
|
||||
- `open`, `navigate`, snapshot або потоки відкриття вкладок завершуються помилкою browser/network policy, тоді як `start` і `tabs` і далі працюють
|
||||
|
||||
Використайте цю мінімальну послідовність, щоб відрізнити одне від іншого:
|
||||
Скористайтеся цією мінімальною послідовністю, щоб відрізнити одне від іншого:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw start
|
||||
@ -581,45 +581,46 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
|
||||
Як читати результати:
|
||||
|
||||
- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте несправність готовності CDP.
|
||||
- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не проблему навігації сторінки.
|
||||
- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, і проблема в політиці навігації або цільовій сторінці.
|
||||
- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблему готовності CDP.
|
||||
- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не навігації сторінкою.
|
||||
- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, а збій пов’язаний із політикою навігації або цільовою сторінкою.
|
||||
- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером справний.
|
||||
|
||||
Важливі деталі поведінки:
|
||||
Важливі подробиці поведінки:
|
||||
|
||||
- Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`.
|
||||
- Для локального loopback-профілю `openclaw`, яким керує OpenClaw, перевірки справності CDP навмисно пропускають застосування SSRF-перевірки доступності браузера для власної локальної площини керування OpenClaw.
|
||||
- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` дозволена.
|
||||
- Конфігурація Browser типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`.
|
||||
- Для локального керованого профілю `openclaw` на loopback перевірки справності CDP навмисно пропускають перевірку доступності SSRF Browser для власної локальної площини керування OpenClaw.
|
||||
- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` буде дозволена.
|
||||
|
||||
Рекомендації з безпеки:
|
||||
Рекомендації щодо безпеки:
|
||||
|
||||
- **Не** послаблюйте політику SSRF браузера типово.
|
||||
- Віддавайте перевагу вузьким виняткам для host, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі.
|
||||
- Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і перевірений.
|
||||
- **Не** послаблюйте політику SSRF Browser типово.
|
||||
- Надавайте перевагу вузьким виняткам для хостів, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі.
|
||||
- Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ Browser до приватної мережі потрібен і пройшов перевірку.
|
||||
|
||||
## Інструменти агента + як працює керування
|
||||
|
||||
Агент отримує **один інструмент** для автоматизації браузера:
|
||||
Агент отримує **один інструмент** для автоматизації Browser:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Як це зіставляється:
|
||||
|
||||
- `browser snapshot` повертає стабільне дерево UI (AI або ARIA).
|
||||
- `browser act` використовує ID `ref` зі snapshot для click/type/drag/select.
|
||||
- `browser screenshot` захоплює пікселі (усю сторінку або елемент).
|
||||
- `browser act` використовує `ref` id зі snapshot для click/type/drag/select.
|
||||
- `browser screenshot` захоплює пікселі (повна сторінка, елемент або ref із мітками).
|
||||
- `browser doctor` перевіряє готовність Gateway, Plugin, профілю, браузера та вкладки.
|
||||
- `browser` приймає:
|
||||
- `profile` для вибору іменованого профілю браузера (openclaw, chrome або віддалений CDP).
|
||||
- `target` (`sandbox` | `host` | `node`) для вибору місця, де працює браузер.
|
||||
- У sandbox-сесіях `target: "host"` потребує `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Якщо `target` не вказано: sandbox-сесії типово використовують `sandbox`, а не-sandbox сесії — `host`.
|
||||
- Якщо підключено node із підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви явно не зафіксуєте `target="host"` або `target="node"`.
|
||||
- У sandbox-сеансах `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Якщо `target` не вказано: sandbox-сеанси типово використовують `sandbox`, сеанси без sandbox — `host`.
|
||||
- Якщо під’єднано вузол із підтримкою Browser, інструмент може автоматично маршрутизуватися до нього, якщо ви явно не закріпите `target="host"` або `target="node"`.
|
||||
|
||||
Це робить роботу агента детермінованою та допомагає уникати крихких селекторів.
|
||||
Це забезпечує детерміновану роботу агента й дає змогу уникати крихких селекторів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
|
||||
- [Пісочниця](/uk/gateway/sandboxing) — керування браузером у sandbox-середовищах
|
||||
- [Безпека](/uk/gateway/security) — ризики керування браузером і посилення захисту
|
||||
- [Sandboxing](/uk/gateway/sandboxing) — керування Browser у sandbox-середовищах
|
||||
- [Безпека](/uk/gateway/security) — ризики керування Browser і заходи захисту
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете аналізувати PDF з агентів
|
||||
- Вам потрібні точні параметри й обмеження інструмента pdf
|
||||
- Ви налагоджуєте нативний режим PDF проти резервного витягування
|
||||
summary: Аналізуйте один або кілька PDF-документів із нативною підтримкою провайдера та резервним витягуванням
|
||||
- Ви хочете аналізувати PDF-файли від агентів
|
||||
- Вам потрібні точні параметри та обмеження інструмента PDF
|
||||
- Ви налагоджуєте нативний режим PDF і резервний режим витягування даних
|
||||
summary: Аналіз одного або кількох PDF-документів із нативною підтримкою провайдера та резервним витягуванням даних
|
||||
title: Інструмент PDF
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:49:41Z"
|
||||
generated_at: "2026-04-25T00:04:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 945838d1e1164a15720ca76eb156f9f299bf7f603f4591c8fa557b43e4cc93a8
|
||||
source_hash: c9b26e6e3e0dacafff3091b4976a3d183b75dbfe9e8a8be635c1c8cf45633c5d
|
||||
source_path: tools/pdf.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,40 +19,40 @@ x-i18n:
|
||||
Коротко про поведінку:
|
||||
|
||||
- Нативний режим провайдера для провайдерів моделей Anthropic і Google.
|
||||
- Режим резервного витягування для інших провайдерів (спочатку витягується текст, а потім, за потреби, зображення сторінок).
|
||||
- Підтримує один (`pdf`) або кілька (`pdfs`) входів, максимум 10 PDF за виклик.
|
||||
- Режим резервного витягування даних для інших провайдерів (спочатку витягується текст, потім за потреби додаються зображення сторінок).
|
||||
- Підтримує один вхід (`pdf`) або кілька (`pdfs`), максимум 10 PDF за один виклик.
|
||||
|
||||
## Доступність
|
||||
|
||||
Інструмент реєструється лише тоді, коли OpenClaw може визначити конфігурацію моделі з підтримкою PDF для агента:
|
||||
|
||||
1. `agents.defaults.pdfModel`
|
||||
2. резервно `agents.defaults.imageModel`
|
||||
3. резервно до визначеної моделі сесії/типової моделі агента
|
||||
4. якщо нативні PDF-провайдери використовують auth, віддавати перевагу їм перед загальними резервними кандидатами image
|
||||
2. резервне значення — `agents.defaults.imageModel`
|
||||
3. резервне значення — визначена модель сесії/типова модель агента
|
||||
4. якщо нативні PDF-провайдери мають автентифікацію, вони мають пріоритет над загальними резервними кандидатами image
|
||||
|
||||
Якщо не вдається визначити придатну модель, інструмент `pdf` не буде доступний.
|
||||
Якщо не вдається визначити жодної придатної моделі, інструмент `pdf` не буде доступний.
|
||||
|
||||
Примітки щодо доступності:
|
||||
|
||||
- Ланцюжок резервного вибору враховує auth. Налаштований `provider/model` зараховується, лише якщо
|
||||
- Ланцюжок резервних значень враховує автентифікацію. Налаштований `provider/model` враховується лише тоді, коли
|
||||
OpenClaw справді може автентифікувати цього провайдера для агента.
|
||||
- Нативні PDF-провайдери наразі — **Anthropic** і **Google**.
|
||||
- Якщо визначений провайдер сесії/типовий провайдер уже має налаштовану vision/PDF
|
||||
модель, інструмент PDF повторно використовує її перед переходом до інших провайдерів з auth.
|
||||
- Нативними PDF-провайдерами наразі є **Anthropic** і **Google**.
|
||||
- Якщо визначений провайдер сесії/типовий провайдер уже має налаштовану vision/PDF-модель,
|
||||
інструмент PDF повторно використовує її, перш ніж переходити до інших провайдерів з автентифікацією.
|
||||
|
||||
## Довідник параметрів входу
|
||||
## Довідник вхідних параметрів
|
||||
|
||||
<ParamField path="pdf" type="string">
|
||||
Один шлях до PDF або URL.
|
||||
Шлях або URL одного PDF.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="pdfs" type="string[]">
|
||||
Кілька шляхів до PDF або URL, загалом до 10.
|
||||
Кілька шляхів або URL PDF, до 10 загалом.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="prompt" type="string" default="Analyze this PDF document.">
|
||||
Prompt для аналізу.
|
||||
Запит для аналізу.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="pages" type="string">
|
||||
@ -64,14 +64,14 @@ Prompt для аналізу.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="maxBytesMb" type="number">
|
||||
Обмеження розміру на один PDF у МБ. Типово `agents.defaults.pdfMaxBytesMb` або `10`.
|
||||
Обмеження розміру на один PDF у МБ. Типове значення береться з `agents.defaults.pdfMaxBytesMb` або `10`.
|
||||
</ParamField>
|
||||
|
||||
Примітки щодо входу:
|
||||
Примітки щодо вхідних параметрів:
|
||||
|
||||
- `pdf` і `pdfs` об’єднуються та дедуплікуються перед завантаженням.
|
||||
- Якщо не передано жодного PDF, інструмент повертає помилку.
|
||||
- `pages` розбирається як номери сторінок з базою 1, дедуплікується, сортується та обрізається до налаштованого максимуму сторінок.
|
||||
- `pages` розбирається як номери сторінок з індексацією від 1, дедуплікується, сортується та обмежується налаштованим максимумом сторінок.
|
||||
- `maxBytesMb` типово дорівнює `agents.defaults.pdfMaxBytesMb` або `10`.
|
||||
|
||||
## Підтримувані посилання на PDF
|
||||
@ -79,42 +79,45 @@ Prompt для аналізу.
|
||||
- локальний шлях до файлу (включно з розгортанням `~`)
|
||||
- URL `file://`
|
||||
- URL `http://` і `https://`
|
||||
- керовані OpenClaw вхідні посилання, як-от `media://inbound/<id>`
|
||||
|
||||
Примітки щодо посилань:
|
||||
|
||||
- Інші URI-схеми (наприклад `ftp://`) відхиляються з `unsupported_pdf_reference`.
|
||||
- Інші схеми URI (наприклад, `ftp://`) відхиляються з помилкою `unsupported_pdf_reference`.
|
||||
- У режимі sandbox віддалені URL `http(s)` відхиляються.
|
||||
- Якщо ввімкнено політику файлів лише в workspace, локальні шляхи за межами дозволених коренів відхиляються.
|
||||
- Якщо ввімкнено політику доступу лише до файлів робочого простору, локальні шляхи поза дозволеними коренями відхиляються.
|
||||
- Керовані вхідні посилання та відтворені шляхи в сховищі вхідних медіафайлів OpenClaw дозволені навіть за політики доступу лише до файлів робочого простору.
|
||||
|
||||
## Режими виконання
|
||||
|
||||
### Нативний режим провайдера
|
||||
|
||||
Нативний режим використовується для провайдерів `anthropic` і `google`.
|
||||
Нативний режим використовується для провайдера `anthropic` і `google`.
|
||||
Інструмент надсилає сирі байти PDF безпосередньо до API провайдера.
|
||||
|
||||
Обмеження нативного режиму:
|
||||
|
||||
- `pages` не підтримується. Якщо його задано, інструмент повертає помилку.
|
||||
- Підтримується кілька PDF на вхід; кожен PDF надсилається як нативний document block /
|
||||
inline PDF part перед prompt.
|
||||
- Підтримується вхід із кількома PDF; кожен PDF надсилається як нативний блок документа /
|
||||
вбудована PDF-частина перед запитом.
|
||||
|
||||
### Режим резервного витягування
|
||||
### Режим резервного витягування даних
|
||||
|
||||
Резервний режим використовується для ненативних провайдерів.
|
||||
Режим резервного витягування використовується для ненативних провайдерів.
|
||||
|
||||
Потік:
|
||||
|
||||
1. Витягнути текст з вибраних сторінок (до `agents.defaults.pdfMaxPages`, типово `20`).
|
||||
2. Якщо довжина витягнутого тексту менша за `200` символів, вибрані сторінки рендеряться в PNG-зображення і додаються.
|
||||
3. Надіслати витягнутий вміст плюс prompt до вибраної моделі.
|
||||
1. Витягнути текст із вибраних сторінок (до `agents.defaults.pdfMaxPages`, типово `20`).
|
||||
2. Якщо довжина витягнутого тексту менша за `200` символів, відрендерити вибрані сторінки у PNG-зображення та додати їх.
|
||||
3. Надіслати витягнутий вміст разом із запитом до вибраної моделі.
|
||||
|
||||
Деталі резервного витягування:
|
||||
|
||||
- Витягування зображень сторінок використовує бюджет пікселів `4,000,000`.
|
||||
- Якщо цільова модель не підтримує вхідні зображення й немає тексту, який можна витягнути, інструмент повертає помилку.
|
||||
- Якщо витягування тексту вдалося, але для витягування зображень потрібна vision у
|
||||
текстовій моделі, OpenClaw відкидає зрендерені зображення і продовжує з витягнутим текстом.
|
||||
- Витягування зображень сторінок використовує піксельний бюджет `4,000,000`.
|
||||
- Якщо цільова модель не підтримує вхідні зображення і немає тексту, який можна витягнути, інструмент повертає помилку.
|
||||
- Якщо витягування тексту успішне, але витягування зображень вимагало б vision для
|
||||
моделі лише з текстом, OpenClaw відкидає відрендерені зображення й продовжує роботу з
|
||||
витягнутим текстом.
|
||||
- Резервне витягування потребує `pdfjs-dist` (і `@napi-rs/canvas` для рендерингу зображень).
|
||||
|
||||
## Конфігурація
|
||||
@ -134,7 +137,7 @@ Prompt для аналізу.
|
||||
}
|
||||
```
|
||||
|
||||
Повні відомості про поля див. у [Configuration Reference](/uk/gateway/configuration-reference).
|
||||
Повний опис полів див. у [Довіднику з конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
## Деталі виводу
|
||||
|
||||
@ -144,20 +147,20 @@ Prompt для аналізу.
|
||||
|
||||
- `model`: визначене посилання на модель (`provider/model`)
|
||||
- `native`: `true` для нативного режиму провайдера, `false` для резервного режиму
|
||||
- `attempts`: резервні спроби, що зазнали невдачі до успішного виконання
|
||||
- `attempts`: спроби резервного режиму, які завершилися невдачею перед успішною
|
||||
|
||||
Поля шляхів:
|
||||
Поля шляху:
|
||||
|
||||
- один PDF на вхід: `details.pdf`
|
||||
- кілька PDF на вхід: `details.pdfs[]` із записами `pdf`
|
||||
- метадані переписування шляху sandbox (де застосовується): `rewrittenFrom`
|
||||
- вхід із одним PDF: `details.pdf`
|
||||
- вхід із кількома PDF: `details.pdfs[]` із записами `pdf`
|
||||
- метадані переписування шляху для sandbox (за потреби): `rewrittenFrom`
|
||||
|
||||
## Поведінка при помилках
|
||||
|
||||
- Відсутній вхід PDF: викидає `pdf required: provide a path or URL to a PDF document`
|
||||
- Відсутній PDF на вході: генерує помилку `pdf required: provide a path or URL to a PDF document`
|
||||
- Забагато PDF: повертає структуровану помилку в `details.error = "too_many_pdfs"`
|
||||
- Непідтримувана схема посилання: повертає `details.error = "unsupported_pdf_reference"`
|
||||
- Нативний режим з `pages`: викидає зрозумілу помилку `pages is not supported with native PDF providers`
|
||||
- Нативний режим із `pages`: генерує зрозумілу помилку `pages is not supported with native PDF providers`
|
||||
|
||||
## Приклади
|
||||
|
||||
@ -179,7 +182,7 @@ Prompt для аналізу.
|
||||
}
|
||||
```
|
||||
|
||||
Резервна модель із фільтром сторінок:
|
||||
Модель резервного режиму з фільтрацією сторінок:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -193,4 +196,4 @@ Prompt для аналізу.
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
|
||||
- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — конфігурація pdfMaxBytesMb і pdfMaxPages
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `pdfMaxBytesMb` і `pdfMaxPages`
|
||||
|
||||
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Використання або налаштування чат-команд
|
||||
- Використання або налаштування chat-команд
|
||||
- Налагодження маршрутизації команд або дозволів
|
||||
summary: 'Slash-команди: текстові та native, config і підтримувані команди'
|
||||
title: Slash-команди
|
||||
summary: 'Слеш-команди: текстові vs native, config і підтримувані команди'
|
||||
title: Слеш-команди
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T23:08:44Z"
|
||||
generated_at: "2026-04-25T00:04:16Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f708cb3c4c22dc7a97b62ce5e2283b4ecfa5c44f72eb501934e80f80181953b7
|
||||
source_hash: 01d8c7a30f9a7bf9ea08ec6372bf47feb5d6153859f616cb0531cb910557d17e
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Команди обробляються Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, яке починається з `/`.
|
||||
Чат-команда bash, доступна лише на хості, використовує `! <cmd>` (із `/bash <cmd>` як alias).
|
||||
Команди обробляються Gateway. Більшість команд мають надсилатися як **окреме** повідомлення, що починається з `/`.
|
||||
Чат-команда bash лише для хоста використовує `! <cmd>` (з псевдонімом `/bash <cmd>`).
|
||||
|
||||
Є дві пов’язані системи:
|
||||
|
||||
- **Команди**: окремі повідомлення `/...`.
|
||||
- **Директиви**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- Директиви видаляються з повідомлення до того, як його побачить модель.
|
||||
- У звичайних чат-повідомленнях (не лише з директивами) вони розглядаються як «вбудовані підказки» і **не** зберігають налаштування сесії.
|
||||
- У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії й повертають підтвердження.
|
||||
- Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, це єдиний
|
||||
allowlist, який використовується; інакше авторизація походить від allowlist/pairing каналу плюс `commands.useAccessGroups`.
|
||||
Для неавторизованих відправників директиви обробляються як звичайний текст.
|
||||
- Директиви видаляються з повідомлення до того, як модель його побачить.
|
||||
- У звичайних чат-повідомленнях (не лише з директивами) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії.
|
||||
- У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження.
|
||||
- Директиви застосовуються лише для **авторизованих відправників**. Якщо встановлено `commands.allowFrom`, використовується лише цей
|
||||
allowlist; інакше авторизація походить із allowlist каналу/пейрингу плюс `commands.useAccessGroups`.
|
||||
Для неавторизованих відправників директиви трактуються як звичайний текст.
|
||||
|
||||
Також є кілька **вбудованих скорочень** (лише для allowlisted/авторизованих відправників): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Вони запускаються негайно, видаляються до того, як модель побачить повідомлення, а решта тексту проходить звичайним потоком.
|
||||
Є також кілька **вбудованих shortcut** (лише для allowlisted/авторизованих відправників): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Вони запускаються негайно, видаляються до того, як модель побачить повідомлення, а решта тексту проходить звичайний потік.
|
||||
|
||||
## Config
|
||||
|
||||
@ -57,111 +57,111 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
- `commands.text` (типово `true`) вмикає розбір `/...` у чат-повідомленнях.
|
||||
- На поверхнях без native-команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо ви задасте тут `false`.
|
||||
- `commands.native` (типово `"auto"`) реєструє native-команди.
|
||||
- `commands.text` (за замовчуванням `true`) вмикає парсинг `/...` у чат-повідомленнях.
|
||||
- На поверхнях без native-команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення в `false`.
|
||||
- `commands.native` (за замовчуванням `"auto"`) реєструє native-команди.
|
||||
- Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash-команди); ігнорується для провайдерів без native-підтримки.
|
||||
- Задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити це для конкретного провайдера (bool або `"auto"`).
|
||||
- Установіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити значення для окремого провайдера (bool або `"auto"`).
|
||||
- `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і не видаляються автоматично.
|
||||
- `commands.nativeSkills` (типово `"auto"`) реєструє native-команди **Skills**, коли це підтримується.
|
||||
- Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати окрему slash-команду для кожної skill).
|
||||
- Задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити це для конкретного провайдера (bool або `"auto"`).
|
||||
- `commands.bash` (типово `false`) вмикає `! <cmd>` для запуску shell-команд хоста (`/bash <cmd>` — alias; потрібні allowlist `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (типово `2000`) керує тим, скільки часу bash чекає перед переходом у режим background (`0` одразу переводить у background).
|
||||
- `commands.config` (типово `false`) вмикає `/config` (читання/запис `openclaw.json`).
|
||||
- `commands.mcp` (типово `false`) вмикає `/mcp` (читання/запис керованого OpenClaw MCP config у `mcp.servers`).
|
||||
- `commands.plugins` (типово `false`) вмикає `/plugins` (виявлення/status Plugin плюс керування install + enable/disable).
|
||||
- `commands.debug` (типово `false`) вмикає `/debug` (перевизначення лише для runtime).
|
||||
- `commands.restart` (типово `true`) вмикає `/restart` плюс дії інструмента перезапуску gateway.
|
||||
- `commands.ownerAllowFrom` (необов’язково) задає явний allowlist власника для поверхонь команд/інструментів, доступних лише власнику. Це окремо від `commands.allowFrom`.
|
||||
- Значення для каналу `channels.<channel>.commands.enforceOwnerForCommands` (необов’язкове, типово `false`) змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Якщо `true`, відправник має або відповідати розв’язаному кандидату власника (наприклад запису в `commands.ownerAllowFrom` або native-метаданим власника провайдера), або мати внутрішню область `operator.admin` на внутрішньому каналі повідомлень. Запис wildcard у канальному `allowFrom`, або порожній/нерозв’язаний список кандидатів власника, **не** є достатнім — команди лише для власника завершуються в fail-closed на цьому каналі. Залишайте це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися лише `ownerAllowFrom` і стандартними allowlist команд.
|
||||
- `commands.nativeSkills` (за замовчуванням `"auto"`) реєструє native-команди **skill**, коли це підтримується.
|
||||
- Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати окрему slash-команду для кожного skill).
|
||||
- Установіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити значення для окремого провайдера (bool або `"auto"`).
|
||||
- `commands.bash` (за замовчуванням `false`) вмикає `! <cmd>` для виконання shell-команд хоста (`/bash <cmd>` — псевдонім; потрібні allowlist `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (за замовчуванням `2000`) керує тим, скільки часу bash чекає перед переходом у фоновий режим (`0` одразу переводить у фон).
|
||||
- `commands.config` (за замовчуванням `false`) вмикає `/config` (читання/запис `openclaw.json`).
|
||||
- `commands.mcp` (за замовчуванням `false`) вмикає `/mcp` (читання/запис конфігурації MCP під керуванням OpenClaw у `mcp.servers`).
|
||||
- `commands.plugins` (за замовчуванням `false`) вмикає `/plugins` (виявлення/стан plugin плюс керування install + enable/disable).
|
||||
- `commands.debug` (за замовчуванням `false`) вмикає `/debug` (лише runtime overrides).
|
||||
- `commands.restart` (за замовчуванням `true`) вмикає `/restart` плюс tool actions перезапуску gateway.
|
||||
- `commands.ownerAllowFrom` (необов’язково) задає явний allowlist власника для поверхонь команд/tool лише для власника. Це окремо від `commands.allowFrom`.
|
||||
- Поканальний `channels.<channel>.commands.enforceOwnerForCommands` (необов’язково, за замовчуванням `false`) змушує команди лише для власника вимагати **ідентичність власника** для виконання на цій поверхні. Якщо значення `true`, відправник має або відповідати знайденому кандидату власника (наприклад, запису в `commands.ownerAllowFrom` або native-метаданим власника провайдера), або мати внутрішню область `operator.admin` на внутрішньому каналі повідомлень. Wildcard-запис у channel `allowFrom` або порожній/нерозв’язаний список кандидатів власника **не** є достатнім — команди лише для власника для цього каналу завершуються за принципом fail closed. Залишайте це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися лише `ownerAllowFrom` і стандартними command allowlist.
|
||||
- `commands.ownerDisplay` керує тим, як id власника з’являються в system prompt: `raw` або `hash`.
|
||||
- `commands.ownerDisplaySecret` необов’язково задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`.
|
||||
- `commands.allowFrom` (необов’язково) задає allowlist для конкретного провайдера для авторизації команд. Якщо його налаштовано, це
|
||||
єдине джерело авторизації для команд і директив (allowlist/pairing каналу та `commands.useAccessGroups`
|
||||
ігноруються). Використовуйте `"*"` для глобального типового значення; ключі конкретних провайдерів мають пріоритет над ним.
|
||||
- `commands.useAccessGroups` (типово `true`) примусово застосовує allowlist/policy до команд, коли `commands.allowFrom` не задано.
|
||||
- `commands.allowFrom` (необов’язково) задає allowlist для окремих провайдерів для авторизації команд. Якщо його налаштовано, це
|
||||
єдине джерело авторизації для команд і директив (allowlist каналу/пейринг і `commands.useAccessGroups`
|
||||
ігноруються). Використовуйте `"*"` для глобального значення за замовчуванням; ключі окремих провайдерів мають пріоритет.
|
||||
- `commands.useAccessGroups` (за замовчуванням `true`) застосовує allowlist/політики для команд, коли `commands.allowFrom` не задано.
|
||||
|
||||
## Список команд
|
||||
|
||||
Поточне джерело істини:
|
||||
Поточне єдине джерело істини:
|
||||
|
||||
- вбудовані команди ядра походять із `src/auto-reply/commands-registry.shared.ts`
|
||||
- згенеровані команди dock походять із `src/auto-reply/commands-registry.data.ts`
|
||||
- команди Plugin походять із викликів Plugin `registerCommand()`
|
||||
- фактична доступність на вашому gateway усе одно залежить від прапорців config, поверхні каналу та встановлених/увімкнених Plugin
|
||||
- вбудовані команди core надходять із `src/auto-reply/commands-registry.shared.ts`
|
||||
- згенеровані dock-команди надходять із `src/auto-reply/commands-registry.data.ts`
|
||||
- команди plugin надходять із викликів `registerCommand()` у plugin
|
||||
- фактична доступність на вашому gateway усе одно залежить від прапорців config, поверхні каналу та встановлених/увімкнених plugin
|
||||
|
||||
### Вбудовані команди ядра
|
||||
### Вбудовані команди core
|
||||
|
||||
Вбудовані команди, доступні сьогодні:
|
||||
Доступні сьогодні вбудовані команди:
|
||||
|
||||
- `/new [model]` починає нову сесію; `/reset` — це alias скидання.
|
||||
- `/reset soft [message]` зберігає поточний транскрипт, відкидає повторно використані id сесій CLI backend і повторно запускає завантаження startup/system-prompt на місці.
|
||||
- `/compact [instructions]` виконує Compaction контексту сесії. Див. [/concepts/compaction](/uk/concepts/compaction).
|
||||
- `/new [model]` починає нову сесію; `/reset` — це псевдонім скидання.
|
||||
- `/reset soft [message]` зберігає поточний транскрипт, відкидає повторно використані id сесій бекенда CLI і повторно запускає завантаження startup/system-prompt на місці.
|
||||
- `/compact [instructions]` ущільнює контекст сесії. Див. [/concepts/compaction](/uk/concepts/compaction).
|
||||
- `/stop` перериває поточний запуск.
|
||||
- `/session idle <duration|off>` і `/session max-age <duration|off>` керують завершенням терміну дії прив’язки до thread.
|
||||
- `/think <level>` задає рівень thinking. Варіанти походять із профілю провайдера активної моделі; поширені рівні — `off`, `minimal`, `low`, `medium` і `high`, а власні рівні на кшталт `xhigh`, `adaptive`, `max` або двійковий `on` — лише там, де це підтримується. Alias: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` перемикає докладний вивід. Alias: `/v`.
|
||||
- `/trace on|off` перемикає вивід trace Plugin для поточної сесії.
|
||||
- `/fast [status|on|off]` показує або задає fast mode.
|
||||
- `/reasoning [on|off|stream]` перемикає видимість reasoning. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` перемикає elevated mode. Alias: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` показує або задає типові значення exec.
|
||||
- `/session idle <duration|off>` і `/session max-age <duration|off>` керують строком дії прив’язки треда.
|
||||
- `/think <level>` задає рівень мислення. Варіанти надходять із профілю провайдера активної моделі; типовими рівнями є `off`, `minimal`, `low`, `medium` і `high`, із користувацькими рівнями, як-от `xhigh`, `adaptive`, `max`, або двійковим `on` лише там, де це підтримується. Псевдоніми: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`.
|
||||
- `/trace on|off` перемикає вивід trace plugin для поточної сесії.
|
||||
- `/fast [status|on|off]` показує або задає швидкий режим.
|
||||
- `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` перемикає elevated-режим. Псевдонім: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` показує або задає значення exec за замовчуванням.
|
||||
- `/model [name|#|status]` показує або задає модель.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` перелічує провайдерів або моделі для провайдера.
|
||||
- `/queue <mode>` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) плюс параметрами на кшталт `debounce:2s cap:25 drop:summarize`.
|
||||
- `/help` показує короткий підсумок довідки.
|
||||
- `/commands` показує згенерований catalog команд.
|
||||
- `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз.
|
||||
- `/status` показує status runtime, включно з мітками `Runtime`/`Runner` і використанням/квотою провайдера, коли доступно.
|
||||
- `/tasks` показує список активних/недавніх background-завдань для поточної сесії.
|
||||
- `/queue <mode>` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) плюс параметрами, як-от `debounce:2s cap:25 drop:summarize`.
|
||||
- `/help` показує коротке резюме довідки.
|
||||
- `/commands` показує згенерований каталог команд.
|
||||
- `/tools [compact|verbose]` показує, що поточний агент може використовувати прямо зараз.
|
||||
- `/status` показує стан виконання/runtime, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, коли доступно.
|
||||
- `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії.
|
||||
- `/context [list|detail|json]` пояснює, як збирається контекст.
|
||||
- `/export-session [path]` експортує поточну сесію в HTML. Alias: `/export`.
|
||||
- `/export-trajectory [path]` експортує JSONL [trajectory bundle](/uk/tools/trajectory) для поточної сесії. Alias: `/trajectory`.
|
||||
- `/whoami` показує ваш id відправника. Alias: `/id`.
|
||||
- `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`.
|
||||
- `/export-trajectory [path]` експортує JSONL [trajectory bundle](/uk/tools/trajectory) для поточної сесії. Псевдонім: `/trajectory`.
|
||||
- `/whoami` показує ваш id відправника. Псевдонім: `/id`.
|
||||
- `/skill <name> [input]` запускає skill за назвою.
|
||||
- `/allowlist [list|add|remove] ...` керує записами allowlist. Лише текстова.
|
||||
- `/approve <id> <decision>` розв’язує запити погодження exec.
|
||||
- `/allowlist [list|add|remove] ...` керує записами allowlist. Лише текстова команда.
|
||||
- `/approve <id> <decision>` розв’язує запити на схвалення exec.
|
||||
- `/btw <question>` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [/tools/btw](/uk/tools/btw).
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` керує запусками sub-agent для поточної сесії.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP та параметрами runtime.
|
||||
- `/focus <target>` прив’язує поточний Discord thread або Telegram topic/conversation до цілі сесії.
|
||||
- `/unfocus` прибирає поточну прив’язку.
|
||||
- `/agents` показує список агентів, прив’язаних до thread, для поточної сесії.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами runtime.
|
||||
- `/focus <target>` прив’язує поточний тред Discord або topic/conversation Telegram до цілі сесії.
|
||||
- `/unfocus` видаляє поточну прив’язку.
|
||||
- `/agents` перелічує агентів, прив’язаних до треда, для поточної сесії.
|
||||
- `/kill <id|#|all>` перериває один або всі запущені sub-agent.
|
||||
- `/steer <id|#> <message>` надсилає керування запущеному sub-agent. Alias: `/tell`.
|
||||
- `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` читає або записує керований OpenClaw config MCP server у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан Plugin. `/plugin` — alias. Запис лише для власника. Потребує `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` керує перевизначеннями config лише для runtime. Лише для власника. Потребує `commands.debug: true`.
|
||||
- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний підсумок вартості.
|
||||
- `/steer <id|#> <message>` надсилає керування запущеному sub-agent. Псевдонім: `/tell`.
|
||||
- `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потрібно `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера під керуванням OpenClaw у `mcp.servers`. Лише для власника. Потрібно `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` інспектує або змінює стан plugin. `/plugin` — псевдонім. Запис лише для власника. Потрібно `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` керує overrides config лише на runtime. Лише для власника. Потрібно `commands.debug: true`.
|
||||
- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальне зведення вартості.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` керує TTS. Див. [/tools/tts](/uk/tools/tts).
|
||||
- `/restart` перезапускає OpenClaw, коли це ввімкнено. Типово: увімкнено; задайте `commands.restart: false`, щоб вимкнути.
|
||||
- `/restart` перезапускає OpenClaw, коли це дозволено. За замовчуванням: увімкнено; установіть `commands.restart: false`, щоб вимкнути.
|
||||
- `/activation mention|always` задає режим активації групи.
|
||||
- `/send on|off|inherit` задає policy надсилання. Лише для власника.
|
||||
- `/bash <command>` запускає shell-команду хоста. Лише текстова. Alias: `! <command>`. Потребує `commands.bash: true` плюс allowlist `tools.elevated`.
|
||||
- `!poll [sessionId]` перевіряє background-завдання bash.
|
||||
- `!stop [sessionId]` зупиняє background-завдання bash.
|
||||
- `/send on|off|inherit` задає політику надсилання. Лише для власника.
|
||||
- `/bash <command>` запускає shell-команду хоста. Лише текстова команда. Псевдонім: `! <command>`. Потрібно `commands.bash: true` плюс allowlist `tools.elevated`.
|
||||
- `!poll [sessionId]` перевіряє фонове завдання bash.
|
||||
- `!stop [sessionId]` зупиняє фонове завдання bash.
|
||||
|
||||
### Згенеровані dock-команди
|
||||
|
||||
Dock-команди генеруються з channel Plugin із підтримкою native-команд. Поточний вбудований набір:
|
||||
Dock-команди генеруються з channel plugin із підтримкою native-команд. Поточний вбудований набір:
|
||||
|
||||
- `/dock-discord` (alias: `/dock_discord`)
|
||||
- `/dock-mattermost` (alias: `/dock_mattermost`)
|
||||
- `/dock-slack` (alias: `/dock_slack`)
|
||||
- `/dock-telegram` (alias: `/dock_telegram`)
|
||||
- `/dock-discord` (псевдонім: `/dock_discord`)
|
||||
- `/dock-mattermost` (псевдонім: `/dock_mattermost`)
|
||||
- `/dock-slack` (псевдонім: `/dock_slack`)
|
||||
- `/dock-telegram` (псевдонім: `/dock_telegram`)
|
||||
|
||||
### Команди вбудованих Plugin
|
||||
### Команди вбудованих plugin
|
||||
|
||||
Вбудовані Plugin можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії:
|
||||
Вбудовані plugin можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії:
|
||||
|
||||
- `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком pairing/setup пристрою. Див. [Pairing](/uk/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` тимчасово вмикає високоризикові команди phone Node.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` керує config голосу Talk. У Discord назва native-команди — `/talkvoice`.
|
||||
- `/card ...` надсилає пресети LINE rich card. Див. [LINE](/uk/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє й керує вбудованим app-server harness Codex. Див. [Codex Harness](/uk/plugins/codex-harness).
|
||||
- `/dreaming [on|off|status|help]` перемикає memory dreaming. Див. [Dreaming](/uk/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком пейрингу/налаштування пристрою. Див. [Pairing](/uk/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` тимчасово вмикає високоризикові команди phone node.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` керує конфігурацією голосу Talk. У Discord назва native-команди — `/talkvoice`.
|
||||
- `/card ...` надсилає preset rich card для LINE. Див. [LINE](/uk/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` інспектує і керує вбудованим harness app-server Codex. Див. [Codex Harness](/uk/plugins/codex-harness).
|
||||
- Команди лише для QQBot:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
@ -169,73 +169,73 @@ Dock-команди генеруються з channel Plugin із підтрим
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### Динамічні skill-команди
|
||||
### Динамічні команди skill
|
||||
|
||||
Skills, які може викликати користувач, також відкриваються як slash-команди:
|
||||
Skills, які може викликати користувач, також доступні як slash-команди:
|
||||
|
||||
- `/skill <name> [input]` завжди працює як універсальна точка входу.
|
||||
- skills також можуть з’являтися як прямі команди на кшталт `/prose`, коли skill/Plugin їх реєструє.
|
||||
- Реєстрацією native skill-команд керують `commands.nativeSkills` і `channels.<provider>.commands.nativeSkills`.
|
||||
- `/skill <name> [input]` завжди працює як загальна точка входу.
|
||||
- skills також можуть з’являтися як прямі команди на кшталт `/prose`, коли skill/plugin їх реєструє.
|
||||
- Реєстрація native skill-команд керується `commands.nativeSkills` і `channels.<provider>.commands.nativeSkills`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Команди приймають необов’язковий `:` між командою та аргументами (наприклад `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` приймає alias моделі, `provider/model` або назву провайдера (fuzzy match); якщо збігу немає, текст обробляється як тіло повідомлення.
|
||||
- Для повної розбивки використання за провайдерами використовуйте `openclaw status --usage`.
|
||||
- `/allowlist add|remove` потребує `commands.config=true` і враховує канал `configWrites`.
|
||||
- У multi-account каналах орієнтовані на config команди `/allowlist --account <id>` і `/config set channels.<provider>.accounts.<id>...` також враховують `configWrites` цільового облікового запису.
|
||||
- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний підсумок вартості з журналів сесій OpenClaw.
|
||||
- `/restart` типово увімкнено; задайте `commands.restart: false`, щоб вимкнути його.
|
||||
- `/plugins install <spec>` приймає ті самі специфікації Plugin, що й `openclaw plugins install`: локальний шлях/архів, npm package або `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` оновлює config Plugin і може запропонувати перезапуск.
|
||||
- Native-команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (потребує `channels.discord.voice` і native-команд; недоступна як текстова).
|
||||
- Команди прив’язки Discord thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують, щоб ефективні прив’язки thread були ввімкнені (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`).
|
||||
- Команди приймають необов’язковий `:` між командою та args (наприклад, `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст обробляється як тіло повідомлення.
|
||||
- Для повної деталізації використання провайдера використовуйте `openclaw status --usage`.
|
||||
- `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу.
|
||||
- У каналах із кількома обліковими записами config-орієнтовані `/allowlist --account <id>` і `/config set channels.<provider>.accounts.<id>...` також враховують `configWrites` цільового облікового запису.
|
||||
- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальне зведення вартості з журналів сесій OpenClaw.
|
||||
- `/restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб вимкнути його.
|
||||
- `/plugins install <spec>` приймає ті самі специфікації plugin, що й `openclaw plugins install`: локальний path/archive, npm package або `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` оновлює config plugin і може запросити перезапуск.
|
||||
- Native-команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (потребує `channels.discord.voice` і native-команд; недоступна як текстова команда).
|
||||
- Команди прив’язування тредів Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують, щоб ефективні прив’язки тредів були увімкнені (`session.threadBindings.enabled` і/або `channels.discord.threadBindings.enabled`).
|
||||
- Довідник команд ACP і поведінка runtime: [ACP Agents](/uk/tools/acp-agents).
|
||||
- `/verbose` призначена для налагодження та додаткової видимості; у звичайному використанні тримайте її **вимкненою**.
|
||||
- `/trace` вужча за `/verbose`: вона показує лише trace/debug-рядки, що належать Plugin, і не вмикає звичайний докладний вивід інструментів.
|
||||
- `/fast on|off` зберігає перевизначення для сесії. Використовуйте опцію `inherit` у Sessions UI, щоб очистити його й повернутися до типових значень config.
|
||||
- `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють її з `service_tier=priority` на власних endpoint Responses, тоді як прямі публічні запити Anthropic, включно з OAuth-автентифікованим трафіком, надісланим на `api.anthropic.com`, зіставляють її з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic).
|
||||
- Підсумки збоїв інструментів усе одно показуються, коли це доречно, але докладний текст помилки включається лише тоді, коли `/verbose` має значення `on` або `full`.
|
||||
- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику Plugin, яку ви не планували показувати. Краще залишати їх вимкненими, особливо в групових чатах.
|
||||
- `/model` одразу зберігає нову модель сесії.
|
||||
- Якщо агент неактивний, наступний запуск використає її відразу.
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене й перезапускає з новою моделлю лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до наступної нагоди для повторної спроби або наступного ходу користувача.
|
||||
- **Швидкий шлях:** повідомлення лише з командами від allowlisted-відправників обробляються негайно (обхід черги + моделі).
|
||||
- **Обмеження за згадкою в групі:** повідомлення лише з командами від allowlisted-відправників обходять вимоги згадки.
|
||||
- **Вбудовані скорочення (лише allowlisted-відправники):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту тексту.
|
||||
- Приклад: `hey /status` викликає відповідь status, а решта тексту проходить звичайним потоком.
|
||||
- `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**.
|
||||
- `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin, і не вмикає звичайний докладний шум від tool.
|
||||
- `/fast on|off` зберігає override сесії. Використовуйте параметр `inherit` в інтерфейсі Sessions, щоб очистити його і повернутися до значень config за замовчуванням.
|
||||
- `/fast` залежить від провайдера: OpenAI/OpenAI Codex відображають його як `service_tier=priority` у native endpoint Responses, тоді як прямі публічні запити Anthropic, зокрема OAuth-автентифікований трафік до `api.anthropic.com`, відображають його як `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic).
|
||||
- Підсумки збоїв tool усе ще показуються, коли це доречно, але детальний текст збоїв включається лише тоді, коли `/verbose` має значення `on` або `full`.
|
||||
- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід tool або діагностику plugin, яку ви не збиралися показувати. Краще залишати їх вимкненими, особливо в групових чатах.
|
||||
- `/model` негайно зберігає нову модель сесії.
|
||||
- Якщо агент неактивний, наступний запуск одразу її використовує.
|
||||
- Якщо запуск уже активний, OpenClaw позначає live-перемикання як відкладене і перезапускає з новою моделлю лише в чистій точці повторної спроби.
|
||||
- Якщо активність tool або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача.
|
||||
- **Швидкий шлях:** повідомлення лише з командою від allowlisted-відправників обробляються негайно (в обхід черги + моделі).
|
||||
- **Обмеження згадок у групах:** повідомлення лише з командою від allowlisted-відправників обходять вимоги згадок.
|
||||
- **Вбудовані shortcut (лише для allowlisted-відправників):** певні команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту тексту.
|
||||
- Приклад: `hey /status` викликає відповідь зі статусом, а решта тексту продовжує проходити звичайний потік.
|
||||
- Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- Неавторизовані повідомлення лише з командами мовчки ігноруються, а вбудовані токени `/...` обробляються як звичайний текст.
|
||||
- **Skill-команди:** Skills із можливістю виклику користувачем відкриваються як slash-команди. Назви санітизуються до `a-z0-9_` (максимум 32 символи); колізії отримують числові суфікси (наприклад `_2`).
|
||||
- `/skill <name> [input]` запускає skill за назвою (корисно, коли обмеження native-команд не дозволяють команди для кожної skill окремо).
|
||||
- Типово skill-команди пересилаються моделі як звичайний запит.
|
||||
- Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі).
|
||||
- Приклад: `/prose` (Plugin OpenProse) — див. [OpenProse](/uk/prose).
|
||||
- **Аргументи native-команд:** Discord використовує autocomplete для динамічних параметрів (і меню кнопок, якщо ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти, а ви пропускаєте аргумент.
|
||||
- Неавторизовані повідомлення лише з командою тихо ігноруються, а вбудовані токени `/...` трактуються як звичайний текст.
|
||||
- **Команди skill:** Skills з `user-invocable` доступні як slash-команди. Назви очищаються до `a-z0-9_` (максимум 32 символи); у разі колізій додаються числові суфікси (наприклад, `_2`).
|
||||
- `/skill <name> [input]` запускає skill за назвою (це зручно, коли обмеження native-команд не дозволяють мати окремі команди для кожного skill).
|
||||
- За замовчуванням команди skill пересилаються моделі як звичайний запит.
|
||||
- Skills можуть необов’язково оголосити `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до tool (детерміновано, без моделі).
|
||||
- Приклад: `/prose` (plugin OpenProse) — див. [OpenProse](/uk/prose).
|
||||
- **Args native-команд:** Discord використовує autocomplete для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові args). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте arg.
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` відповідає на питання runtime, а не config: **що цей агент може використовувати просто зараз у
|
||||
`/tools` відповідає на питання runtime, а не config: **що цей агент може використовувати прямо зараз у
|
||||
цій розмові**.
|
||||
|
||||
- Типова `/tools` — компактна й оптимізована для швидкого перегляду.
|
||||
- `/tools` за замовчуванням компактний і оптимізований для швидкого перегляду.
|
||||
- `/tools verbose` додає короткі описи.
|
||||
- Поверхні native-команд, що підтримують аргументи, відкривають той самий перемикач режиму `compact|verbose`.
|
||||
- Результати мають область дії сесії, тому зміна агента, каналу, thread, авторизації відправника або моделі може
|
||||
- Поверхні native-команд, які підтримують аргументи, мають той самий перемикач режимів `compact|verbose`.
|
||||
- Результати прив’язані до сесії, тому зміна агента, каналу, треда, авторизації відправника або моделі може
|
||||
змінити вивід.
|
||||
- `/tools` включає інструменти, які реально доступні під час runtime, включно з інструментами ядра, підключеними
|
||||
інструментами Plugin та інструментами, що належать каналу.
|
||||
- `/tools` включає tool, які реально доступні в runtime, зокрема core tool, підключені
|
||||
tool plugin і tool, що належать каналу.
|
||||
|
||||
Для редагування профілю й перевизначень використовуйте панель Tools у Control UI або поверхні config/catalog, а не
|
||||
ставтеся до `/tools` як до статичного catalog.
|
||||
Для редагування профілів та overrides використовуйте панель Tools у Control UI або поверхні config/catalog, а не
|
||||
сприймайте `/tools` як статичний каталог.
|
||||
|
||||
## Поверхні використання (що де показується)
|
||||
|
||||
- **Використання/квота провайдера** (наприклад: “Claude 80% left”) з’являється в `/status` для поточного провайдера моделі, коли ввімкнено відстеження використання. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля percent лише з залишком інвертуються перед показом, а відповіді `model_remains` надають перевагу запису chat-model плюс мітці plan із тегом моделі.
|
||||
- **Рядки токенів/кешу** в `/status` можуть використовувати останній запис використання з транскрипту як запасний варіант, коли live snapshot сесії є неповним. Наявні ненульові live-значення все одно мають пріоритет, а запасний варіант із транскрипту також може відновити мітку активної моделі runtime плюс більше загальне значення, орієнтоване на prompt, коли збережені загальні значення відсутні або менші.
|
||||
- **Runtime vs runner:** `/status` повідомляє `Runtime` для ефективного шляху виконання і стану sandbox, а `Runner` — хто фактично запускає сесію: вбудований Pi, провайдер на базі CLI чи harness/backend ACP.
|
||||
- **Токени/вартість для кожної відповіді** керуються через `/usage off|tokens|full` (додаються до звичайних відповідей).
|
||||
- **Використання/квота провайдера** (приклад: «Claude 80% left») показується в `/status` для поточного провайдера моделі, коли відстеження використання ввімкнене. OpenClaw нормалізує вікна провайдера до `% left`; для MiniMax поля відсотків лише для залишку інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису chat-model плюс мітці плану з тегом моделі.
|
||||
- **Рядки token/cache** у `/status` можуть повертатися до останнього запису використання в транскрипті, коли live-знімок сесії бідний на дані. Наявні ненульові live-значення все одно мають пріоритет, а fallback до транскрипту також може відновити мітку активної runtime-моделі плюс більше загальне значення, орієнтоване на prompt, коли збережені підсумки відсутні або менші.
|
||||
- **Execution vs runtime:** `/status` показує `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично виконує сесію: `OpenClaw Pi Default`, `OpenAI Codex`, бекенд CLI або бекенд ACP.
|
||||
- **Кількість token/вартість на відповідь** контролюється через `/usage off|tokens|full` (додається до звичайних відповідей).
|
||||
- `/model status` стосується **моделей/auth/endpoint**, а не використання.
|
||||
|
||||
## Вибір моделі (`/model`)
|
||||
@ -244,7 +244,7 @@ Skills, які може викликати користувач, також ві
|
||||
|
||||
Приклади:
|
||||
|
||||
```
|
||||
```text
|
||||
/model
|
||||
/model list
|
||||
/model 3
|
||||
@ -256,17 +256,17 @@ Skills, які може викликати користувач, також ві
|
||||
Примітки:
|
||||
|
||||
- `/model` і `/model list` показують компактний нумерований picker (сімейство моделей + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний picker зі списками провайдерів і моделей плюс кроком Submit.
|
||||
- `/model <#>` вибирає зі списку цього picker (і за можливості надає перевагу поточному провайдеру).
|
||||
- `/model status` показує докладне подання, включно з налаштованим endpoint провайдера (`baseUrl`) і режимом API (`api`), коли вони доступні.
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний picker із випадаючими списками провайдера та моделі плюс кроком Submit.
|
||||
- `/model <#>` вибирає з цього picker (і, якщо можливо, віддає перевагу поточному провайдеру).
|
||||
- `/model status` показує детальний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні.
|
||||
|
||||
## Debug-перевизначення
|
||||
## Debug overrides
|
||||
|
||||
`/debug` дає змогу задавати перевизначення config **лише для runtime** (пам’ять, не диск). Лише для власника. Типово вимкнено; увімкніть через `commands.debug: true`.
|
||||
`/debug` дає змогу задавати overrides config **лише для runtime** (у пам’яті, не на диску). Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.debug: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
```
|
||||
```text
|
||||
/debug show
|
||||
/debug set messages.responsePrefix="[openclaw]"
|
||||
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
|
||||
@ -276,12 +276,12 @@ Skills, які може викликати користувач, також ві
|
||||
|
||||
Примітки:
|
||||
|
||||
- Перевизначення застосовуються одразу до нових читань config, але **не** записуються в `openclaw.json`.
|
||||
- Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до config на диску.
|
||||
- Overrides застосовуються негайно до нових читань config, але **не** записуються в `openclaw.json`.
|
||||
- Використовуйте `/debug reset`, щоб очистити всі overrides і повернутися до config на диску.
|
||||
|
||||
## Trace-вивід Plugin
|
||||
## Вивід trace plugin
|
||||
|
||||
`/trace` дає змогу перемикати **trace/debug-рядки Plugin в межах сесії** без увімкнення повного verbose mode.
|
||||
`/trace` дає змогу вмикати **trace/debug-рядки plugin у межах сесії** без увімкнення повного verbose-режиму.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -294,19 +294,19 @@ Skills, які може викликати користувач, також ві
|
||||
Примітки:
|
||||
|
||||
- `/trace` без аргументу показує поточний стан trace для сесії.
|
||||
- `/trace on` вмикає trace-рядки Plugin для поточної сесії.
|
||||
- `/trace off` знову вимикає їх.
|
||||
- Trace-рядки Plugin можуть з’являтися в `/status` і як діагностичне повідомлення після звичайної відповіді assistant.
|
||||
- `/trace` не замінює `/debug`; `/debug` як і раніше керує перевизначеннями config лише для runtime.
|
||||
- `/trace` не замінює `/verbose`; звичайний verbose-вивід інструментів/status як і раніше належить `/verbose`.
|
||||
- `/trace on` вмикає рядки trace plugin для поточної сесії.
|
||||
- `/trace off` знову їх вимикає.
|
||||
- Рядки trace plugin можуть з’являтися в `/status` і як діагностичне follow-up повідомлення після звичайної відповіді асистента.
|
||||
- `/trace` не замінює `/debug`; `/debug` і далі керує overrides config лише для runtime.
|
||||
- `/trace` не замінює `/verbose`; звичайний докладний вивід tool/status і далі належить `/verbose`.
|
||||
|
||||
## Оновлення config
|
||||
## Оновлення Config
|
||||
|
||||
`/config` записує ваш on-disk config (`openclaw.json`). Лише для власника. Типово вимкнено; увімкніть через `commands.config: true`.
|
||||
`/config` записує в config на диску (`openclaw.json`). Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.config: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
```
|
||||
```text
|
||||
/config show
|
||||
/config show messages.responsePrefix
|
||||
/config get messages.responsePrefix
|
||||
@ -316,12 +316,12 @@ Skills, які може викликати користувач, також ві
|
||||
|
||||
Примітки:
|
||||
|
||||
- Config проходить валідацію перед записом; невалідні зміни відхиляються.
|
||||
- Оновлення через `/config` зберігаються після перезапуску.
|
||||
- Перед записом config проходить валідацію; некоректні зміни відхиляються.
|
||||
- Оновлення `/config` зберігаються після перезапусків.
|
||||
|
||||
## Оновлення MCP
|
||||
|
||||
`/mcp` записує визначення MCP server, якими керує OpenClaw, у `mcp.servers`. Лише для власника. Типово вимкнено; увімкніть через `commands.mcp: true`.
|
||||
`/mcp` записує визначення MCP-серверів під керуванням OpenClaw у `mcp.servers`. Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.mcp: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -335,11 +335,11 @@ Skills, які може викликати користувач, також ві
|
||||
Примітки:
|
||||
|
||||
- `/mcp` зберігає config у config OpenClaw, а не в налаштуваннях проєкту, якими володіє Pi.
|
||||
- Адаптери runtime визначають, які transport фактично можуть виконуватися.
|
||||
- Runtime-адаптери вирішують, які транспорти реально можна виконувати.
|
||||
|
||||
## Оновлення Plugin
|
||||
|
||||
`/plugins` дає змогу операторам перевіряти виявлені Plugin і перемикати їх увімкнення в config. Потоки лише для читання можуть використовувати `/plugin` як alias. Типово вимкнено; увімкніть через `commands.plugins: true`.
|
||||
`/plugins` дозволяє операторам інспектувати виявлені plugin і перемикати стан увімкнення в config. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. За замовчуванням вимкнено; увімкніть через `commands.plugins: true`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -353,8 +353,8 @@ Skills, які може викликати користувач, також ві
|
||||
|
||||
Примітки:
|
||||
|
||||
- `/plugins list` і `/plugins show` використовують реальне виявлення Plugin відносно поточного workspace плюс on-disk config.
|
||||
- `/plugins enable|disable` оновлює лише config Plugin; це не встановлює і не видаляє Plugin.
|
||||
- `/plugins list` і `/plugins show` використовують реальне виявлення plugin у поточному workspace плюс config на диску.
|
||||
- `/plugins enable|disable` оновлює лише config plugin; він не встановлює і не видаляє plugin.
|
||||
- Після змін enable/disable перезапустіть gateway, щоб застосувати їх.
|
||||
|
||||
## Примітки щодо поверхонь
|
||||
@ -362,26 +362,26 @@ Skills, які може викликати користувач, також ві
|
||||
- **Текстові команди** працюють у звичайній чат-сесії (DM використовують `main`, групи мають власну сесію).
|
||||
- **Native-команди** використовують ізольовані сесії:
|
||||
- Discord: `agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (префікс можна налаштувати через `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (націлюється на чат-сесію через `CommandTargetSessionKey`)
|
||||
- **`/stop`** націлюється на активну чат-сесію, щоб перервати поточний запуск.
|
||||
- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди в стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, ви маєте створити по одній Slack slash-команді для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ephemeral-кнопки Block Kit.
|
||||
- Виняток native-команд Slack: реєструйте `/agentstatus` (не `/status`), тому що `/status` зарезервовано Slack. Текстова `/status` у повідомленнях Slack все одно працює.
|
||||
- **`/stop`** націлюється на активну чат-сесію, щоб можна було перервати поточний запуск.
|
||||
- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди в стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit.
|
||||
- Виняток native для Slack: реєструйте `/agentstatus` (а не `/status`), оскільки Slack резервує `/status`. Текстова `/status` у повідомленнях Slack усе ще працює.
|
||||
|
||||
## Побічні запитання BTW
|
||||
## BTW side questions
|
||||
|
||||
`/btw` — це швидке **побічне запитання** щодо поточної сесії.
|
||||
|
||||
На відміну від звичайного чату:
|
||||
|
||||
- воно використовує поточну сесію як фоновий контекст,
|
||||
- виконується як окремий **одноразовий виклик без інструментів**,
|
||||
- виконується як окремий **одноразовий** виклик без tool,
|
||||
- не змінює майбутній контекст сесії,
|
||||
- не записується в історію транскрипту,
|
||||
- доставляється як live-побічний результат, а не як звичайне повідомлення assistant.
|
||||
- доставляється як живий побічний результат, а не як звичайне повідомлення асистента.
|
||||
|
||||
Це робить `/btw` корисним, коли вам потрібно тимчасове уточнення, а основне
|
||||
завдання має продовжуватися.
|
||||
Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне
|
||||
завдання триває.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -389,10 +389,11 @@ Skills, які може викликати користувач, також ві
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
Повну поведінку й подробиці UX клієнта див. в [Побічних запитаннях BTW](/uk/tools/btw).
|
||||
Див. [BTW Side Questions](/uk/tools/btw) для повного опису поведінки та деталей UX
|
||||
клієнта.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Skills](/uk/tools/skills)
|
||||
- [Config Skills](/uk/tools/skills-config)
|
||||
- [Створення Skills](/uk/tools/creating-skills)
|
||||
- [Skills config](/uk/tools/skills-config)
|
||||
- [Creating skills](/uk/tools/creating-skills)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user