chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
04dfff11ec
commit
336258df80
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете вибрати чат-канал для OpenClaw
|
||||
- Ви хочете вибрати канал чату для OpenClaw
|
||||
- Вам потрібен короткий огляд підтримуваних платформ обміну повідомленнями
|
||||
summary: Платформи обміну повідомленнями, до яких може підключатися OpenClaw
|
||||
title: Чат-канали
|
||||
title: Канали чату
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:44:14Z"
|
||||
generated_at: "2026-04-24T16:58:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c016b78b16724e73b21946d6bed0009f4cbebd1f887620431b9b4bff70f2b1ff
|
||||
source_hash: e97818dce89ea06a60f2cccd0cc8a78cba48d66ea39e4769f2b583690a4f75d0
|
||||
source_path: channels/index.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,6 +16,16 @@ x-i18n:
|
||||
OpenClaw може спілкуватися з вами в будь-якому чат-застосунку, яким ви вже користуєтеся. Кожен канал підключається через Gateway.
|
||||
Текст підтримується всюди; підтримка медіа та реакцій залежить від каналу.
|
||||
|
||||
## Примітки щодо доставки
|
||||
|
||||
- Відповіді Telegram, що містять синтаксис зображень markdown, наприклад ``,
|
||||
за можливості перетворюються на медіавідповіді на фінальному вихідному етапі.
|
||||
- Групові приватні повідомлення Slack маршрутизуються як групові чати, тому для розмов MPIM застосовуються
|
||||
політика груп, поведінка згадок і правила групових сесій.
|
||||
- Налаштування WhatsApp виконується за потреби під час інсталяції: онбординг може показати потік налаштування до того,
|
||||
як буде підготовлено залежності середовища виконання Baileys, а Gateway завантажує середовище виконання WhatsApp
|
||||
лише тоді, коли канал справді активний.
|
||||
|
||||
## Підтримувані канали
|
||||
|
||||
- [BlueBubbles](/uk/channels/bluebubbles) — **Рекомендовано для iMessage**; використовує REST API сервера BlueBubbles для macOS із повною підтримкою функцій (вбудований Plugin; редагування, скасування надсилання, ефекти, реакції, керування групами — редагування наразі не працює в macOS 26 Tahoe).
|
||||
@ -23,33 +33,33 @@ OpenClaw може спілкуватися з вами в будь-якому ч
|
||||
- [Feishu](/uk/channels/feishu) — бот Feishu/Lark через WebSocket (вбудований Plugin).
|
||||
- [Google Chat](/uk/channels/googlechat) — застосунок Google Chat API через HTTP Webhook.
|
||||
- [iMessage (legacy)](/uk/channels/imessage) — застаріла інтеграція з macOS через CLI imsg (застаріло, для нових налаштувань використовуйте BlueBubbles).
|
||||
- [IRC](/uk/channels/irc) — класичні IRC-сервери; канали та DM з керуванням pairing/allowlist.
|
||||
- [IRC](/uk/channels/irc) — класичні IRC-сервери; канали й DM з елементами керування сполученням/списком дозволених.
|
||||
- [LINE](/uk/channels/line) — бот LINE Messaging API (вбудований Plugin).
|
||||
- [Matrix](/uk/channels/matrix) — протокол Matrix (вбудований Plugin).
|
||||
- [Mattermost](/uk/channels/mattermost) — Bot API + WebSocket; канали, групи, DM (вбудований Plugin).
|
||||
- [Microsoft Teams](/uk/channels/msteams) — Bot Framework; підтримка для підприємств (вбудований Plugin).
|
||||
- [Nextcloud Talk](/uk/channels/nextcloud-talk) — self-hosted чат через Nextcloud Talk (вбудований Plugin).
|
||||
- [Microsoft Teams](/uk/channels/msteams) — Bot Framework; корпоративна підтримка (вбудований Plugin).
|
||||
- [Nextcloud Talk](/uk/channels/nextcloud-talk) — самостійно розміщений чат через Nextcloud Talk (вбудований Plugin).
|
||||
- [Nostr](/uk/channels/nostr) — децентралізовані DM через NIP-04 (вбудований Plugin).
|
||||
- [QQ Bot](/uk/channels/qqbot) — QQ Bot API; приватний чат, груповий чат і багаті медіа (вбудований Plugin).
|
||||
- [QQ Bot](/uk/channels/qqbot) — QQ Bot API; приватний чат, груповий чат і насичені медіа (вбудований Plugin).
|
||||
- [Signal](/uk/channels/signal) — signal-cli; орієнтований на приватність.
|
||||
- [Slack](/uk/channels/slack) — Bolt SDK; застосунки робочого простору.
|
||||
- [Synology Chat](/uk/channels/synology-chat) — Synology NAS Chat через вихідні та вхідні Webhook (вбудований Plugin).
|
||||
- [Telegram](/uk/channels/telegram) — Bot API через grammY; підтримує групи.
|
||||
- [Tlon](/uk/channels/tlon) — месенджер на базі Urbit (вбудований Plugin).
|
||||
- [Twitch](/uk/channels/twitch) — чат Twitch через IRC-з’єднання (вбудований Plugin).
|
||||
- [Twitch](/uk/channels/twitch) — чат Twitch через IRC-підключення (вбудований Plugin).
|
||||
- [Voice Call](/uk/plugins/voice-call) — телефонія через Plivo або Twilio (Plugin, встановлюється окремо).
|
||||
- [WebChat](/uk/web/webchat) — інтерфейс Gateway WebChat через WebSocket.
|
||||
- [WeChat](/uk/channels/wechat) — Plugin Tencent iLink Bot через вхід за QR-кодом; лише приватні чати (зовнішній Plugin).
|
||||
- [WhatsApp](/uk/channels/whatsapp) — найпопулярніший; використовує Baileys і потребує pairing через QR-код.
|
||||
- [Zalo](/uk/channels/zalo) — Zalo Bot API; популярний месенджер у В’єтнамі (вбудований Plugin).
|
||||
- [WhatsApp](/uk/channels/whatsapp) — найпопулярніший; використовує Baileys і потребує сполучення через QR-код.
|
||||
- [Zalo](/uk/channels/zalo) — Zalo Bot API; популярний месенджер у Вʼєтнамі (вбудований Plugin).
|
||||
- [Zalo Personal](/uk/channels/zalouser) — особистий обліковий запис Zalo через вхід за QR-кодом (вбудований Plugin).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Канали можуть працювати одночасно; налаштуйте кілька, і OpenClaw виконуватиме маршрутизацію для кожного чату.
|
||||
- Найшвидше зазвичай налаштовується **Telegram** (простий токен бота). WhatsApp вимагає pairing через QR-код і
|
||||
- Найшвидше зазвичай налаштовується **Telegram** (простий токен бота). WhatsApp потребує сполучення через QR-код і
|
||||
зберігає більше стану на диску.
|
||||
- Поведінка груп залежить від каналу; див. [Groups](/uk/channels/groups).
|
||||
- DM pairing і allowlist застосовуються з міркувань безпеки; див. [Security](/uk/gateway/security).
|
||||
- Усунення проблем: [Channel troubleshooting](/uk/channels/troubleshooting).
|
||||
- Постачальники моделей задокументовані окремо; див. [Model Providers](/uk/providers/models).
|
||||
- Для безпеки застосовуються сполучення DM і списки дозволених; див. [Security](/uk/gateway/security).
|
||||
- Усунення несправностей: [Усунення несправностей каналів](/uk/channels/troubleshooting).
|
||||
- Постачальники моделей документовані окремо; див. [Model Providers](/uk/providers/models).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -2,13 +2,13 @@
|
||||
read_when:
|
||||
- Оновлення OpenClaw
|
||||
- Щось ламається після оновлення
|
||||
summary: Безпечне оновлення OpenClaw (глобальне встановлення або вихідний код), а також стратегія відкату
|
||||
summary: Безпечне оновлення OpenClaw (глобальне встановлення або з вихідного коду), а також стратегія відкату
|
||||
title: Оновлення
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:58:12Z"
|
||||
generated_at: "2026-04-24T16:58:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 04ed583916ce64c9f60639c8145a46ce5b27ebf5a6dfd09924312d7acfefe1ab
|
||||
source_hash: f57c5f4d4988eabb62a2c836c07f56e329149b1f9290baa0568ef1d86f66e0ad
|
||||
source_path: install/updating.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,13 +17,13 @@ x-i18n:
|
||||
|
||||
## Рекомендовано: `openclaw update`
|
||||
|
||||
Найшвидший спосіб оновлення. Він визначає тип вашого встановлення (npm або git), отримує найновішу версію, запускає `openclaw doctor` і перезапускає gateway.
|
||||
Найшвидший спосіб оновлення. Він визначає ваш тип встановлення (npm або git), отримує останню версію, запускає `openclaw doctor` і перезапускає Gateway.
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
Щоб змінити канал або націлитися на конкретну версію:
|
||||
Щоб перемкнути канали або вибрати конкретну версію:
|
||||
|
||||
```bash
|
||||
openclaw update --channel beta
|
||||
@ -31,11 +31,9 @@ openclaw update --tag main
|
||||
openclaw update --dry-run # попередній перегляд без застосування
|
||||
```
|
||||
|
||||
`--channel beta` надає перевагу beta, але runtime повертається до stable/latest, коли
|
||||
beta tag відсутній або старіший за останній stable release. Використовуйте `--tag beta`,
|
||||
якщо вам потрібен сирий npm beta dist-tag для одноразового оновлення пакета.
|
||||
`--channel beta` надає перевагу beta, але середовище виконання повертається до stable/latest, якщо тег beta відсутній або старіший за останній стабільний реліз. Використовуйте `--tag beta`, якщо вам потрібен сирий npm dist-tag beta для разового оновлення пакета.
|
||||
|
||||
Див. [Development channels](/uk/install/development-channels) щодо семантики каналів.
|
||||
Див. [Канали розробки](/uk/install/development-channels), щоб ознайомитися із семантикою каналів.
|
||||
|
||||
## Альтернатива: повторно запустити інсталятор
|
||||
|
||||
@ -43,7 +41,7 @@ beta tag відсутній або старіший за останній stable
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Додайте `--no-onboard`, щоб пропустити onboarding. Для встановлень із вихідного коду передайте `--install-method git --no-onboard`.
|
||||
Додайте `--no-onboard`, щоб пропустити онбординг. Для встановлень із вихідного коду передайте `--install-method git --no-onboard`.
|
||||
|
||||
## Альтернатива: вручну через npm, pnpm або bun
|
||||
|
||||
@ -61,26 +59,26 @@ bun add -g openclaw@latest
|
||||
|
||||
### Глобальні встановлення npm, що належать root
|
||||
|
||||
Деякі конфігурації npm на Linux встановлюють глобальні пакети в каталоги, що належать root, наприклад
|
||||
`/usr/lib/node_modules/openclaw`. OpenClaw підтримує таке розміщення: встановлений
|
||||
пакет розглядається як доступний лише для читання під час runtime, а runtime-залежності bundled Plugin
|
||||
розміщуються в каталозі runtime, доступному для запису, замість зміни
|
||||
дерева пакета.
|
||||
У деяких конфігураціях npm на Linux глобальні пакети встановлюються в каталоги, що належать root, наприклад `/usr/lib/node_modules/openclaw`. OpenClaw підтримує таку схему: встановлений пакет розглядається як доступний лише для читання під час виконання, а залежності середовища виконання вбудованих Plugin розміщуються в доступному для запису каталозі середовища виконання замість зміни дерева пакета.
|
||||
|
||||
Для захищених systemd units задайте каталог staging, доступний для запису, який входить до
|
||||
`ReadWritePaths`:
|
||||
Для захищених systemd units задайте доступний для запису каталог staging, який включено до `ReadWritePaths`:
|
||||
|
||||
```ini
|
||||
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
Якщо `OPENCLAW_PLUGIN_STAGE_DIR` не задано, OpenClaw використовує `$STATE_DIRECTORY`, коли
|
||||
його надає systemd, а потім повертається до `~/.openclaw/plugin-runtime-deps`.
|
||||
Якщо `OPENCLAW_PLUGIN_STAGE_DIR` не задано, OpenClaw використовує `$STATE_DIRECTORY`, якщо його надає systemd, а потім повертається до `~/.openclaw/plugin-runtime-deps`.
|
||||
|
||||
## Auto-updater
|
||||
### Залежності середовища виконання вбудованих Plugin
|
||||
|
||||
Auto-updater типово вимкнено. Увімкніть його в `~/.openclaw/openclaw.json`:
|
||||
Пакетні встановлення зберігають залежності середовища виконання вбудованих Plugin поза деревом пакета, доступним лише для читання. Під час запуску та під час `openclaw doctor --fix` OpenClaw відновлює залежності середовища виконання лише для тих вбудованих Plugin, які активні в конфігурації, активні через застарілу конфігурацію каналу або увімкнені типовим значенням їхнього вбудованого маніфесту.
|
||||
|
||||
Явне вимкнення має пріоритет. Для вимкненого Plugin або каналу залежності його середовища виконання не відновлюються лише через те, що він існує в пакеті. Зовнішні Plugin і користувацькі шляхи завантаження, як і раніше, використовують `openclaw plugins install` або `openclaw plugins update`.
|
||||
|
||||
## Автооновлювач
|
||||
|
||||
Автооновлювач вимкнено за замовчуванням. Увімкніть його в `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -96,13 +94,13 @@ Auto-updater типово вимкнено. Увімкніть його в `~/.o
|
||||
}
|
||||
```
|
||||
|
||||
| Channel | Behavior |
|
||||
| -------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Чекає `stableDelayHours`, а потім застосовує оновлення з детермінованим jitter у межах `stableJitterHours` (розподілене розгортання). |
|
||||
| `beta` | Перевіряє кожні `betaCheckIntervalHours` (типово: щогодини) і застосовує негайно. |
|
||||
| `dev` | Автоматичне застосування відсутнє. Використовуйте `openclaw update` вручну. |
|
||||
| Канал | Поведінка |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Очікує `stableDelayHours`, потім застосовує з детермінованим джитером у межах `stableJitterHours` (поетапне розгортання). |
|
||||
| `beta` | Перевіряє кожні `betaCheckIntervalHours` (типово: щогодини) і застосовує негайно. |
|
||||
| `dev` | Автоматичне застосування відсутнє. Використовуйте `openclaw update` вручну. |
|
||||
|
||||
Gateway також журналює підказку про оновлення під час запуску (вимикається через `update.checkOnStart: false`).
|
||||
Gateway також записує підказку про оновлення під час запуску (вимикається через `update.checkOnStart: false`).
|
||||
|
||||
## Після оновлення
|
||||
|
||||
@ -114,9 +112,9 @@ Gateway також журналює підказку про оновлення
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Мігрує конфігурацію, виконує аудит політик DM і перевіряє стан gateway. Докладніше: [Doctor](/uk/gateway/doctor)
|
||||
Мігрує конфігурацію, перевіряє політики DM і перевіряє стан Gateway. Подробиці: [Doctor](/uk/gateway/doctor)
|
||||
|
||||
### Перезапустіть gateway
|
||||
### Перезапустіть Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
@ -142,7 +140,7 @@ openclaw gateway restart
|
||||
|
||||
Порада: `npm view openclaw version` показує поточну опубліковану версію.
|
||||
|
||||
### Зафіксувати commit (вихідний код)
|
||||
### Зафіксувати коміт (вихідний код)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
@ -151,17 +149,17 @@ pnpm install && pnpm build
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Щоб повернутися до latest: `git checkout main && git pull`.
|
||||
Щоб повернутися до останньої версії: `git checkout main && git pull`.
|
||||
|
||||
## Якщо ви застрягли
|
||||
## Якщо ви зайшли в глухий кут
|
||||
|
||||
- Знову запустіть `openclaw doctor` і уважно прочитайте вивід.
|
||||
- Для `openclaw update --channel dev` у source checkout updater автоматично виконує bootstrap `pnpm`, коли це потрібно. Якщо ви бачите помилку bootstrap pnpm/corepack, установіть `pnpm` вручну (або знову ввімкніть `corepack`) і повторно запустіть оновлення.
|
||||
- Перевірте: [Troubleshooting](/uk/gateway/troubleshooting)
|
||||
- Ще раз запустіть `openclaw doctor` і уважно прочитайте вивід.
|
||||
- Для `openclaw update --channel dev` у checkout із вихідного коду оновлювач автоматично завантажує `pnpm`, якщо це потрібно. Якщо ви бачите помилку bootstrap `pnpm`/`corepack`, установіть `pnpm` вручну (або знову ввімкніть `corepack`) і повторно запустіть оновлення.
|
||||
- Перевірте: [Усунення несправностей](/uk/gateway/troubleshooting)
|
||||
- Запитайте в Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Install Overview](/uk/install) — усі способи встановлення
|
||||
- [Огляд встановлення](/uk/install) — усі способи встановлення
|
||||
- [Doctor](/uk/gateway/doctor) — перевірки стану після оновлень
|
||||
- [Migrating](/uk/install/migrating) — посібники з міграції між основними версіями
|
||||
- [Міграція](/uk/install/migrating) — посібники з міграції між основними версіями
|
||||
|
||||
@ -1,40 +1,48 @@
|
||||
---
|
||||
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-24T05:42:20Z"
|
||||
generated_at: "2026-04-24T16:58:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3d533338fa15d866bb69584706162ce099bb4a1edc9851183fb5442730ebdd9b
|
||||
source_hash: bedc8975dae28e13d653494723ca0ee44cefdb63cbd4c6397658bd22fd8c3d80
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут:
|
||||
|
||||
- **API key** — прямий доступ до платформи OpenAI з оплатою за використання (моделі `openai/*`)
|
||||
- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`)
|
||||
- **Обв’язка app-server Codex** — нативне виконання через app-server Codex (`openai/*` моделі плюс `agents.defaults.embeddedHarness.runtime: "codex"`)
|
||||
- **API-ключ** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` моделі)
|
||||
- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (`openai-codex/*` моделі)
|
||||
- **Обв’язка Codex app-server** — нативне виконання через Codex app-server (`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. |
|
||||
|
||||
<Note>
|
||||
GPT-5.5 наразі доступна в OpenClaw через маршрути підписки/OAuth:
|
||||
`openai-codex/gpt-5.5` із виконавцем PI або `openai/gpt-5.5` з
|
||||
обв’язкою app-server Codex. Прямий доступ за 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` з виконавцем 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`.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не
|
||||
увімкне вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише
|
||||
коли ви явно вибираєте нативну обв’язку Codex через
|
||||
вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише
|
||||
коли ви явно обираєте нативну обв’язку Codex за допомогою
|
||||
`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`.
|
||||
</Note>
|
||||
|
||||
@ -42,31 +50,31 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | постачальник моделі `openai/<model>` | Так |
|
||||
| Chat / Responses | постачальник моделей `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Обв’язка app-server Codex | `openai/<model>` з `embeddedHarness.runtime: codex` | Так |
|
||||
| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і постачальник не закріплений |
|
||||
| Обв’язка 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"` | Так |
|
||||
| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так |
|
||||
| Embeddings | постачальник embedding для пам’яті | Так |
|
||||
| Вбудовування | постачальник embedding для пам’яті | Так |
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key (платформа OpenAI)">
|
||||
**Найкраще для:** прямого доступу до API та оплати за використання.
|
||||
<Tab title="API-ключ (OpenAI Platform)">
|
||||
**Найкраще для:** прямого доступу до API та тарифікації за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте свій API key">
|
||||
Створіть або скопіюйте API key з [інформаційної панелі платформи OpenAI](https://platform.openai.com/api-keys).
|
||||
<Step title="Отримайте свій API-ключ">
|
||||
Створіть або скопіюйте API-ключ у [панелі керування OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть первинне налаштування">
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
@ -86,16 +94,16 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Model ref | Маршрут | Автентифікація |
|
||||
|-----------|---------|----------------|
|
||||
| `openai/gpt-5.4` | Прямий API платформи OpenAI | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | Прямий API платформи OpenAI | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | Майбутній прямий маршрут API, коли OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` |
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
|-----------|-------|------|
|
||||
| `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-ключем, якщо ви явно не примусите
|
||||
обв’язку app-server Codex. Сама GPT-5.5 наразі доступна лише через підписку/OAuth;
|
||||
використовуйте `openai-codex/*` для OAuth Codex через виконавець PI за замовчуванням.
|
||||
`openai/*` — це прямий маршрут OpenAI API-key, якщо ви явно не примусите
|
||||
обв’язку Codex app-server. Сам GPT-5.5 наразі доступний лише через підписку/OAuth;
|
||||
використовуйте `openai-codex/*` для Codex OAuth через типовий виконавець PI.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -108,16 +116,16 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Активні запити до API OpenAI відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Підписка Codex">
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud потребує входу через ChatGPT.
|
||||
**Найкраще для:** використання підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть OAuth Codex">
|
||||
<Step title="Запустіть Codex OAuth">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
```
|
||||
@ -128,13 +136,13 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Для безголових середовищ або конфігурацій, де зворотний виклик незручний, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість зворотного виклику браузера localhost:
|
||||
Для headless-конфігурацій або конфігурацій, де незручно використовувати callback, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість browser callback на localhost:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
```
|
||||
</Step>
|
||||
<Step title="Встановіть модель за замовчуванням">
|
||||
<Step title="Установіть типову модель">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
|
||||
```
|
||||
@ -148,15 +156,15 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Model ref | Маршрут | Автентифікація |
|
||||
|-----------|---------|----------------|
|
||||
| `openai-codex/gpt-5.5` | OAuth ChatGPT/Codex через PI | Вхід Codex |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Обв’язка app-server Codex | Автентифікація app-server Codex |
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Обв’язка Codex app-server | автентифікація Codex app-server |
|
||||
|
||||
<Note>
|
||||
Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд автентифікації/профілю. Префікс моделі
|
||||
`openai-codex/*` також є явним маршрутом PI для OAuth Codex.
|
||||
Він не вибирає і не автовмикає вбудовану обв’язку app-server Codex.
|
||||
Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд
|
||||
автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth.
|
||||
Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -168,29 +176,29 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Первинне налаштування більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента.
|
||||
Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через browser OAuth (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів.
|
||||
</Note>
|
||||
|
||||
### Індикатор стану
|
||||
|
||||
У чаті `/status` показує, яка вбудована обв’язка активна для поточної
|
||||
сесії. Обв’язка PI за замовчуванням відображається як `Runner: pi (embedded)` і
|
||||
не додає окремого значка. Коли вибрано вбудовану обв’язку app-server Codex,
|
||||
сесії. Типова обв’язка PI відображається як `Runner: pi (embedded)` і не
|
||||
додає окремий бейдж. Коли вибрано вбудовану обв’язку Codex app-server,
|
||||
`/status` додає ідентифікатор обв’язки не-PI поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Наявні сесії зберігають записаний для них ідентифікатор обв’язки, тому використовуйте
|
||||
`Fast · codex`. Існуючі сесії зберігають зафіксований ідентифікатор обв’язки, тому використовуйте
|
||||
`/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status`
|
||||
відображав новий вибір PI/Codex.
|
||||
|
||||
### Обмеження вікна контексту
|
||||
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення.
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення.
|
||||
|
||||
Для `openai-codex/gpt-5.5` через OAuth Codex:
|
||||
Для `openai-codex/gpt-5.5` через Codex OAuth:
|
||||
|
||||
- Нативний `contextWindow`: `1000000`
|
||||
- Обмеження `contextTokens` середовища виконання за замовчуванням: `272000`
|
||||
- Типове обмеження `contextTokens` під час виконання: `272000`
|
||||
|
||||
Менше обмеження за замовчуванням на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`:
|
||||
Менше типове обмеження на практиці має кращі характеристики затримки та якості. Ви можете перевизначити його через `contextTokens`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -205,27 +213,35 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання.
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
</Note>
|
||||
|
||||
### Відновлення каталогу
|
||||
|
||||
OpenClaw використовує метадані вихідного каталогу Codex для `gpt-5.5`, коли вони
|
||||
присутні. Якщо під час реального виявлення Codex відсутній рядок `openai-codex/gpt-5.5`,
|
||||
а обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб
|
||||
Cron, субагент і запуски зі сконфігурованою типовою моделлю не завершувалися помилкою
|
||||
`Unknown model`.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`.
|
||||
Він підтримує і генерацію зображень OpenAI за API-ключем, і генерацію зображень через OAuth Codex
|
||||
через те саме посилання на модель `openai/gpt-image-2`.
|
||||
Він підтримує і генерацію зображень OpenAI за API-ключем, і генерацію зображень
|
||||
через Codex OAuth з тим самим посиланням на модель `openai/gpt-image-2`.
|
||||
|
||||
| Можливість | API key OpenAI | OAuth Codex |
|
||||
| ------------------------ | ---------------------------------- | ----------------------------------- |
|
||||
| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Автентифікація | `OPENAI_API_KEY` | Вхід через OAuth OpenAI Codex |
|
||||
| Транспорт | API зображень OpenAI | бекенд Codex Responses |
|
||||
| Макс. зображень на запит | 4 | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) |
|
||||
| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K |
|
||||
| Співвідношення сторін / роздільна здатність | Не передається до API зображень OpenAI | Відображається у підтримуваний розмір, коли це безпечно |
|
||||
| Можливість | 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 |
|
||||
| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) |
|
||||
| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K |
|
||||
| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | За можливості безпечно зіставляється з підтримуваним розміром |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -238,35 +254,34 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант.
|
||||
Див. [Генерація зображень](/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`.
|
||||
|
||||
Для інсталяцій із OAuth Codex зберігайте те саме посилання `openai/gpt-image-2`. Коли
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен доступу OAuth
|
||||
і надсилає запити на зображення через бекенд Codex Responses. Він
|
||||
не спочатку пробує `OPENAI_API_KEY` і не виконує безшумний перехід на API key для цього
|
||||
запиту. Явно налаштуйте `models.providers.openai` з API key,
|
||||
власним базовим URL або кінцевою точкою Azure, якщо ви хочете використовувати
|
||||
прямий маршрут API зображень OpenAI.
|
||||
Якщо ця власна кінцева точка зображень розташована в довіреній LAN/приватній адресі, також встановіть
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і надалі
|
||||
блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо цей явний дозвіл
|
||||
не задано.
|
||||
Для інсталяцій із 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-сумісні кінцеві точки зображень, якщо не задано цей явний дозвіл.
|
||||
|
||||
Генерація:
|
||||
Згенерувати:
|
||||
|
||||
```
|
||||
/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="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Редагування:
|
||||
Редагувати:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Збережіть форму об’єкта, змініть матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536
|
||||
```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
|
||||
```
|
||||
|
||||
## Генерація відео
|
||||
@ -275,10 +290,10 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
|
||||
| Можливість | Значення |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| Модель за замовчуванням | `openai/sora-2` |
|
||||
| Режими | Перетворення тексту на відео, зображення на відео, редагування одного відео |
|
||||
| Еталонні вхідні дані | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Типова модель | `openai/sora-2` |
|
||||
| Режими | Text-to-video, image-to-video, редагування одного відео |
|
||||
| Вхідні еталони | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента |
|
||||
|
||||
```json5
|
||||
@ -292,25 +307,25 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант.
|
||||
Див. [Генерація відео](/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 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `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 через інструкції розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення справ до кінця та проактивного Heartbeat, навіть попри те, що рештою промпта обв’язки керує Codex.
|
||||
Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі правила доведення до кінця та проактивного Heartbeat, навіть якщо рештою промпту обв’язки керує Codex.
|
||||
|
||||
Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналів поведінка відповіді та тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним.
|
||||
Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Правила GPT-5 завжди ввімкнені для відповідних моделей. Дружній стиль взаємодії — окремий і налаштовуваний шар.
|
||||
|
||||
| Значення | Ефект |
|
||||
| ---------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише шар дружнього стилю |
|
||||
| Значення | Ефект |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише шар дружнього стилю |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Конфігурація">
|
||||
<Tab title="Config">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -331,11 +346,11 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю.
|
||||
Значення під час виконання нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застаріле `plugins.entries.openai.config.personality` усе ще зчитується як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задане.
|
||||
Застаріле `plugins.entries.openai.config.personality` і далі зчитується як fallback для сумісності, якщо спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
@ -350,8 +365,8 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
| Голос | `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 key | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових повідомлень, `mp3` для файлів |
|
||||
| API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
| 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`.
|
||||
@ -369,19 +384,19 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS, не впливаючи на кінцеву точку API чату.
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку chat API.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Перетворення мовлення на текст">
|
||||
Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через
|
||||
поверхню транскрибування розуміння медіа в OpenClaw.
|
||||
поверхню транскрибування для розуміння медіа в OpenClaw.
|
||||
|
||||
- Типова модель: `gpt-4o-transcribe`
|
||||
- Кінцева точка: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Шлях введення: multipart-вивантаження аудіофайлу
|
||||
- Підтримується в OpenClaw всюди, де вхідне транскрибування аудіо використовує
|
||||
- Вхідний шлях: завантаження аудіофайлу multipart
|
||||
- Підтримується в OpenClaw всюди, де для транскрибування вхідного аудіо використовується
|
||||
`tools.media.audio`, включно з сегментами голосових каналів Discord і
|
||||
аудіовкладеннями каналів
|
||||
|
||||
@ -405,7 +420,7 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
}
|
||||
```
|
||||
|
||||
Підказки щодо мови та промпта передаються до OpenAI, коли вони надаються
|
||||
Підказки мови та промпту передаються в OpenAI, коли вони надані
|
||||
спільною конфігурацією аудіомедіа або запитом транскрибування для окремого виклику.
|
||||
|
||||
</Accordion>
|
||||
@ -420,10 +435,10 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
| Промпт | `...openai.prompt` | (не задано) |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `800` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
|
||||
<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`). Цей постачальник потокової обробки призначений для шляху транскрибування в реальному часі в Voice Call; голос у Discord наразі натомість записує короткі сегменти та використовує пакетний шлях транскрибування `tools.media.audio`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -438,10 +453,10 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `500` |
|
||||
| API key | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує аудіоформат G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -449,29 +464,30 @@ OpenClaw додає спільний внесок у промпт GPT-5 для
|
||||
|
||||
## Кінцеві точки Azure OpenAI
|
||||
|
||||
Вбудований постачальник `openai` може спрямовувати генерацію зображень до ресурсу Azure OpenAI
|
||||
шляхом перевизначення базового URL. На шляху генерації зображень OpenClaw
|
||||
визначає імена хостів Azure у `models.providers.openai.baseUrl` і автоматично
|
||||
перемикається на формат запитів Azure.
|
||||
Вбудований постачальник `openai` може спрямовувати генерацію зображень на ресурс Azure OpenAI
|
||||
через перевизначення базового URL. На шляху генерації зображень OpenClaw
|
||||
виявляє імена хостів Azure у `models.providers.openai.baseUrl` і автоматично
|
||||
перемикається на формат запиту Azure.
|
||||
|
||||
<Note>
|
||||
Голос у реальному часі використовує окремий шлях конфігурації
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||||
і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному
|
||||
часі** в розділі [Голос і мовлення](#voice-and-speech) для його налаштувань Azure.
|
||||
і на нього не впливає `models.providers.openai.baseUrl`. Див. акордеон **Голос
|
||||
у реальному часі** в розділі [Голос і мовлення](#voice-and-speech), щоб дізнатися про налаштування Azure
|
||||
для нього.
|
||||
</Note>
|
||||
|
||||
Використовуйте Azure OpenAI, якщо:
|
||||
Використовуйте Azure OpenAI, коли:
|
||||
|
||||
- У вас уже є підписка Azure OpenAI, квота або корпоративна угода
|
||||
- Вам потрібна регіональна локалізація даних або засоби відповідності вимогам, які надає Azure
|
||||
- Ви хочете зберігати трафік у межах наявного середовища Azure
|
||||
- Вам потрібна регіональна резидентність даних або засоби відповідності вимогам, які надає Azure
|
||||
- Ви хочете залишити трафік у межах наявного tenancy Azure
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Для генерації зображень через Azure за допомогою вбудованого постачальника `openai` вкажіть
|
||||
`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` у значення
|
||||
ключа Azure OpenAI (а не ключа платформи OpenAI):
|
||||
Для генерації зображень через Azure у вбудованому постачальнику `openai` укажіть
|
||||
`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` як
|
||||
ключ Azure OpenAI (а не ключ OpenAI Platform):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -495,90 +511,90 @@ OpenClaw розпізнає такі суфікси хостів Azure для м
|
||||
Для запитів генерації зображень на розпізнаному хості Azure OpenClaw:
|
||||
|
||||
- Надсилає заголовок `api-key` замість `Authorization: Bearer`
|
||||
- Використовує шляхи, прив’язані до розгортання (`/openai/deployments/{deployment}/...`)
|
||||
- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`)
|
||||
- Додає `?api-version=...` до кожного запиту
|
||||
|
||||
Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний
|
||||
формат запиту зображень OpenAI.
|
||||
|
||||
<Note>
|
||||
Маршрутизація Azure для шляху генерації зображень постачальника `openai` вимагає
|
||||
OpenClaw 2026.4.22 або новішої версії. У раніших версіях будь-який користувацький
|
||||
`openai.baseUrl` обробляється як публічна кінцева точка OpenAI і не працюватиме з розгортаннями
|
||||
зображень Azure.
|
||||
Маршрутизація Azure для шляху генерації зображень постачальника `openai`
|
||||
потребує OpenClaw 2026.4.22 або новішої версії. Попередні версії трактують будь-який власний
|
||||
`openai.baseUrl` так само, як публічну кінцеву точку OpenAI, і не працюватимуть з deployment генерації
|
||||
зображень у 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 прив’язує моделі до розгортань. Для запитів генерації зображень Azure,
|
||||
спрямованих через вбудованого постачальника `openai`, поле `model` в OpenClaw
|
||||
має бути **іменем розгортання Azure**, яке ви налаштували в порталі Azure, а не
|
||||
ідентифікатором публічної моделі OpenAI.
|
||||
Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure,
|
||||
спрямованих через вбудований постачальник `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не
|
||||
публічним ідентифікатором моделі OpenAI.
|
||||
|
||||
Якщо ви створили розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`:
|
||||
Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1
|
||||
```text
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
Те саме правило імені розгортання застосовується до викликів генерації зображень,
|
||||
спрямованих через вбудованого постачальника `openai`.
|
||||
Те саме правило назви deployment застосовується до викликів генерації зображень, спрямованих через
|
||||
вбудований постачальник `openai`.
|
||||
|
||||
### Регіональна доступність
|
||||
|
||||
Генерація зображень Azure наразі доступна лише в підмножині регіонів
|
||||
Генерація зображень у Azure зараз доступна лише в частині регіонів
|
||||
(наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||||
`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням
|
||||
розгортання, а також підтвердьте, що конкретна модель доступна у вашому регіоні.
|
||||
deployment і переконайтеся, що потрібна модель доступна у вашому регіоні.
|
||||
|
||||
### Відмінності параметрів
|
||||
|
||||
Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень.
|
||||
Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні
|
||||
значення `background` для `gpt-image-2`), або надавати їх лише для певних версій
|
||||
моделі. Ці відмінності походять від Azure і базової моделі, а не від
|
||||
моделі. Ці відмінності походять від Azure та базової моделі, а не від
|
||||
OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте
|
||||
набір параметрів, який підтримується вашим конкретним розгортанням і версією API в
|
||||
набір параметрів, які підтримує саме ваш deployment і версія API, у
|
||||
порталі Azure.
|
||||
|
||||
<Note>
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує
|
||||
приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні
|
||||
приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та OpenAI-сумісні
|
||||
маршрути** в розділі [Розширена конфігурація](#advanced-configuration).
|
||||
|
||||
Для трафіку чату або Responses в Azure (поза генерацією зображень) використовуйте
|
||||
потік первинного налаштування або окрему конфігурацію постачальника Azure — одного лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати формат API/автентифікації Azure. Існує
|
||||
Для трафіку chat або Responses на Azure (окрім генерації зображень) використовуйте
|
||||
потік онбордингу або окрему конфігурацію постачальника Azure — одного лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати форму API/автентифікації Azure. Існує
|
||||
окремий постачальник `azure-openai-responses/*`; див.
|
||||
акордеон Server-side Compaction нижче.
|
||||
акордеон про серверний Compaction нижче.
|
||||
</Note>
|
||||
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Транспорт (WebSocket проти SSE)">
|
||||
OpenClaw використовує пріоритет WebSocket із резервним переходом на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`.
|
||||
<Accordion title="Транспорт (WebSocket vs SSE)">
|
||||
OpenClaw використовує WebSocket-first із fallback до SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
|
||||
У режимі `"auto"` OpenClaw:
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час періоду охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень
|
||||
- Повторює одну ранню помилку WebSocket перед переходом до SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час цього періоду охолодження
|
||||
- Додає стабільні заголовки ідентифікації сесії та ходу для повторних спроб і перепідключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
|
||||
| Значення | Поведінка |
|
||||
|-------|----------|
|
||||
| `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE |
|
||||
| `"auto"` (типово) | Спочатку WebSocket, fallback до SSE |
|
||||
| `"sse"` | Примусово лише SSE |
|
||||
| `"websocket"` | Примусово лише WebSocket |
|
||||
|
||||
@ -599,7 +615,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
|
||||
Пов’язані документи OpenAI:
|
||||
Пов’язана документація OpenAI:
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
@ -628,8 +644,8 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
<Accordion title="Швидкий режим">
|
||||
OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`:
|
||||
|
||||
- **Чат/UI:** `/fast status|on|off`
|
||||
- **Конфігурація:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
- **Chat/UI:** `/fast status|on|off`
|
||||
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Коли його ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`.
|
||||
|
||||
@ -646,13 +662,13 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI сесій повертає сесію до налаштованого типового значення.
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI сесій повертає сесію до типового налаштованого значення.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Пріоритетна обробка (service_tier)">
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Налаштуйте її для кожної моделі в OpenClaw:
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Установіть її для кожної моделі в OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -674,18 +690,18 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Server-side Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає Server-side Compaction:
|
||||
<Accordion title="Серверний Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає серверний Compaction:
|
||||
|
||||
- Примусово встановлює `store: true` (якщо лише compat моделі не задає `supportsStore: false`)
|
||||
- Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо недоступне)
|
||||
- Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`)
|
||||
- Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне)
|
||||
|
||||
Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативна обв’язка app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`.
|
||||
Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативна обв’язка Codex app-server керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Явно ввімкнути">
|
||||
Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses:
|
||||
Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -737,7 +753,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо лише сумісність не задає `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -755,33 +771,33 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
|
||||
Із `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента
|
||||
З `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія через інструмент
|
||||
- Повторює хід із вказівкою діяти негайно
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дій
|
||||
|
||||
<Note>
|
||||
Обмежено лише запуском сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку.
|
||||
Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні та OpenAI-сумісні маршрути">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-сумісними проксі `/v1`:
|
||||
<Accordion title="Нативні маршрути та OpenAI-сумісні маршрути">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`:
|
||||
|
||||
**Нативні маршрути** (`openai/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort
|
||||
- Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово використовують суворий режим для схем інструментів
|
||||
- Пропускають вимкнене reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово використовують строгий режим для схем інструментів
|
||||
- Додають приховані заголовки атрибуції лише на перевірених нативних хостах
|
||||
- Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, compat reasoning, підказки кешу промптів)
|
||||
- Зберігають формування запитів, характерне лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки кешу промптів)
|
||||
|
||||
**Проксі/сумісні маршрути:**
|
||||
- Використовують м’якшу compat-поведінку
|
||||
- Не примушують до суворих схем інструментів або нативних заголовків
|
||||
**Маршрути проксі/сумісності:**
|
||||
- Використовують менш строгі правила сумісності
|
||||
- Не примушують строгі схеми інструментів або заголовки, доступні лише для нативних маршрутів
|
||||
|
||||
Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує прихованих заголовків атрибуції.
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -790,15 +806,15 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір постачальників, посилань на моделі та поведінки резервного перемикання.
|
||||
Вибір постачальників, посилань на моделі та поведінки 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>
|
||||
</CardGroup>
|
||||
|
||||
@ -6,24 +6,24 @@ read_when:
|
||||
summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, OpenRouter, fal, MiniMax, ComfyUI, Vydra, xAI)
|
||||
title: Генерація зображень
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:49:14Z"
|
||||
generated_at: "2026-04-24T16:58:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 51ffc32165c5e25925460f95f3a6e674a004e6640b7a4b9e88d025eb40943b4b
|
||||
source_hash: 3a8e721918f5d610163894f33fbfd39ade6694be8bf4ad47c7c691d780d49637
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Інструмент `image_generate` дозволяє агенту створювати й редагувати зображення за допомогою налаштованих вами провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
|
||||
Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою ваших налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
|
||||
|
||||
<Note>
|
||||
Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth.
|
||||
Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
1. Задайте API-ключ принаймні для одного провайдера (наприклад `OPENAI_API_KEY`, `GEMINI_API_KEY` або `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth.
|
||||
2. За бажанням задайте бажану модель:
|
||||
1. Установіть API-ключ щонайменше для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY` або `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth.
|
||||
2. За бажанням укажіть бажану модель:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -38,33 +38,49 @@ x-i18n:
|
||||
```
|
||||
|
||||
Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw маршрутизує запити на зображення
|
||||
через цей самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`.
|
||||
Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API-ключ або
|
||||
користувацький/Azure base URL, повертає використання прямого маршруту OpenAI Images API.
|
||||
Для OpenAI-сумісних LAN-ендпоїнтів, таких як LocalAI, збережіть користувацький
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на
|
||||
зображення через той самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`.
|
||||
Явна власна конфігурація зображень `models.providers.openai`, наприклад API-ключ або
|
||||
власний/Azure базовий URL, знову перемикає на прямий маршрут OpenAI Images API.
|
||||
Для OpenAI-сумісних LAN-ендпоінтів, таких як LocalAI, збережіть власний
|
||||
`models.providers.openai.baseUrl` і явно ввімкніть
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні
|
||||
ендпоїнти зображень за замовчуванням залишаються заблокованими.
|
||||
ендпоінти зображень за замовчуванням залишаються заблокованими.
|
||||
|
||||
3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_
|
||||
|
||||
Агент викличе `image_generate` автоматично. Додавати інструмент до allowlist не потрібно — він увімкнений за замовчуванням, коли доступний провайдер.
|
||||
Агент автоматично викликає `image_generate`. Жодного списку дозволених інструментів не потрібно — він увімкнений за замовчуванням, коли доступний провайдер.
|
||||
|
||||
## Поширені маршрути
|
||||
|
||||
| Ціль | Посилання на модель | Автентифікація |
|
||||
| ---------------------------------------------------- | ------------------------------------------------- | ----------------------------------- |
|
||||
| Генерація зображень OpenAI з білінгом API | `openai/gpt-image-2` | `OPENAI_API_KEY` |
|
||||
| Генерація зображень OpenAI з автентифікацією підписки Codex | `openai/gpt-image-2` | OpenAI Codex OAuth |
|
||||
| Генерація зображень OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` |
|
||||
| Генерація зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
|
||||
Той самий інструмент `image_generate` обробляє як генерацію з тексту в зображення,
|
||||
так і редагування з еталонними зображеннями. Використовуйте `image` для одного еталона
|
||||
або `images` для кількох еталонів.
|
||||
Підказки для виводу, які підтримує провайдер, наприклад `quality`, `outputFormat` і
|
||||
специфічний для OpenAI `background`, передаються далі, коли це можливо, і позначаються як
|
||||
проігноровані, якщо провайдер їх не підтримує.
|
||||
|
||||
## Підтримувані провайдери
|
||||
|
||||
| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація |
|
||||
| --------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Так (референс суб’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, визначене workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація |
|
||||
| --------- | -------------------------------------- | ---------------------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Так (еталон об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, визначене workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
|
||||
Використовуйте `action: "list"`, щоб перевірити доступні провайдери й моделі під час виконання:
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання:
|
||||
|
||||
```
|
||||
/tool image_generate action=list
|
||||
@ -73,11 +89,11 @@ Codex OAuth використовує те саме посилання на мо
|
||||
## Параметри інструмента
|
||||
|
||||
<ParamField path="prompt" type="string" required>
|
||||
Промпт для генерації зображення. Обов’язковий для `action: "generate"`.
|
||||
Підказка для генерації зображення. Обов’язкова для `action: "generate"`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="action" type="'generate' | 'list'" default="generate">
|
||||
Використовуйте `"list"`, щоб перевірити доступні провайдери й моделі під час виконання.
|
||||
Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="model" type="string">
|
||||
@ -85,11 +101,11 @@ Codex OAuth використовує те саме посилання на мо
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="image" type="string">
|
||||
Шлях або URL одного референсного зображення для режиму редагування.
|
||||
Шлях або URL одного еталонного зображення для режиму редагування.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="images" type="string[]">
|
||||
Кілька референсних зображень для режиму редагування (до 5).
|
||||
Кілька еталонних зображень для режиму редагування (до 5).
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="size" type="string">
|
||||
@ -105,11 +121,11 @@ Codex OAuth використовує те саме посилання на мо
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="quality" type="'low' | 'medium' | 'high' | 'auto'">
|
||||
Підказка якості, якщо провайдер це підтримує.
|
||||
Підказка якості, якщо провайдер її підтримує.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="outputFormat" type="'png' | 'jpeg' | 'webp'">
|
||||
Підказка формату виводу, якщо провайдер це підтримує.
|
||||
Підказка формату виводу, якщо провайдер її підтримує.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="count" type="number">
|
||||
@ -117,7 +133,7 @@ Codex OAuth використовує те саме посилання на мо
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="timeoutMs" type="number">
|
||||
Необов’язковий timeout запиту до провайдера в мілісекундах.
|
||||
Необов’язковий тайм-аут запиту до провайдера в мілісекундах.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="filename" type="string">
|
||||
@ -128,9 +144,9 @@ Codex OAuth використовує те саме посилання на мо
|
||||
Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`.
|
||||
</ParamField>
|
||||
|
||||
Не всі провайдери підтримують усі параметри. Коли запасний провайдер підтримує близький геометричний варіант замість точно запитаного, OpenClaw перемаповує запит до найближчого підтримуваного `size`, `aspectRatio` або `resolution` перед надсиланням. Непідтримувані підказки виводу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не декларують підтримку, і повідомляються в результаті інструмента.
|
||||
Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед відправленням переналаштовує на найближчий підтримуваний розмір, співвідношення сторін або роздільну здатність. Непідтримувані підказки виводу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не оголошують їхню підтримку, і відображаються в результаті інструмента.
|
||||
|
||||
Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw перемаповує геометрію під час переходу до запасного провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
|
||||
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час переходу до резервного провайдера, повернені значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -157,38 +173,38 @@ Codex OAuth використовує те саме посилання на мо
|
||||
|
||||
Під час генерації зображення OpenClaw пробує провайдерів у такому порядку:
|
||||
|
||||
1. **Параметр `model`** із виклику інструмента (якщо агент його задає)
|
||||
1. Параметр **`model`** із виклику інструмента (якщо агент його вказує)
|
||||
2. **`imageGenerationModel.primary`** із конфігурації
|
||||
3. **`imageGenerationModel.fallbacks`** по порядку
|
||||
4. **Автовизначення** — використовує лише значення за замовчуванням провайдерів, підкріплені автентифікацією:
|
||||
4. **Автовизначення** — використовує лише типові налаштування провайдерів із підтримкою автентифікації:
|
||||
- спочатку поточний провайдер за замовчуванням
|
||||
- потім решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`
|
||||
- потім решта зареєстрованих провайдерів генерації зображень у порядку provider-id
|
||||
|
||||
Якщо провайдер завершується помилкою (помилка автентифікації, rate limit тощо), автоматично пробується наступний кандидат. Якщо не спрацюють усі, помилка міститиме подробиці кожної спроби.
|
||||
Якщо провайдер завершується невдачею (помилка автентифікації, ліміт запитів тощо), автоматично пробується наступний кандидат. Якщо всі завершуються невдачею, помилка містить деталі кожної спроби.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Автовизначення враховує автентифікацію. Значення провайдера за замовчуванням потрапляє до списку кандидатів
|
||||
- Автовизначення враховує автентифікацію. Типовий провайдер потрапляє до списку кандидатів
|
||||
лише тоді, коли OpenClaw справді може автентифікувати цього провайдера.
|
||||
- Автовизначення ввімкнено за замовчуванням. Установіть
|
||||
- Автовизначення увімкнене за замовчуванням. Установіть
|
||||
`agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень
|
||||
використовувала лише явні записи `model`, `primary` і `fallbacks`.
|
||||
- Використовуйте `action: "list"`, щоб перевірити поточно зареєстрованих провайдерів, їхні
|
||||
моделі за замовчуванням і підказки щодо env vars для автентифікації.
|
||||
- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні
|
||||
моделі за замовчуванням і підказки щодо auth env vars.
|
||||
|
||||
### Редагування зображень
|
||||
|
||||
OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування референсних зображень. Передайте шлях або URL референсного зображення:
|
||||
OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування еталонних зображень. Передайте шлях або URL еталонного зображення:
|
||||
|
||||
```
|
||||
"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
OpenAI, OpenRouter, Google і xAI підтримують до 5 референсних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
OpenAI, OpenRouter, Google і xAI підтримують до 5 еталонних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
|
||||
### Моделі зображень OpenRouter
|
||||
|
||||
Генерація зображень через OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через API зображень chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом `openrouter/`:
|
||||
Генерація зображень OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через API зображень chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом `openrouter/`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -202,28 +218,28 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 референс
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw пересилає в OpenRouter `prompt`, `count`, референсні зображення та сумісні з Gemini підказки `aspectRatio` / `resolution`. Наразі вбудовані скорочення для моделей зображень OpenRouter включають `google/gemini-3.1-flash-image-preview`, `google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`; використовуйте `action: "list"`, щоб побачити, що надає ваш налаштований Plugin.
|
||||
OpenClaw передає в OpenRouter `prompt`, `count`, еталонні зображення та сумісні з Gemini підказки `aspectRatio` / `resolution`. Поточні вбудовані скорочення моделей зображень OpenRouter включають `google/gemini-3.1-flash-image-preview`, `google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`; використовуйте `action: "list"`, щоб побачити, що надає ваш налаштований Plugin.
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано
|
||||
OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль,
|
||||
який використовується моделями чату підписки Codex, і надсилає запит на зображення
|
||||
через бекенд Codex Responses; він не переходить тихо до
|
||||
`OPENAI_API_KEY` для цього запиту. Щоб примусово маршрутизувати через прямий OpenAI Images API,
|
||||
явно налаштуйте `models.providers.openai` з API-ключем, користувацьким base URL
|
||||
або ендпоїнтом Azure. Старішу
|
||||
модель `openai/gpt-image-1` і далі можна явно вибрати, але нові запити OpenAI
|
||||
на генерацію й редагування зображень мають використовувати `gpt-image-2`.
|
||||
Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль,
|
||||
що використовується моделями чату підписки Codex, і надсилає запит на зображення
|
||||
через бекенд Codex Responses; для цього запиту він не переходить непомітно на
|
||||
`OPENAI_API_KEY`. Щоб примусово використовувати пряму маршрутизацію через OpenAI Images API,
|
||||
явно налаштуйте `models.providers.openai` з API-ключем, власним base URL
|
||||
або ендпоінтом Azure. Старішу модель
|
||||
`openai/gpt-image-1` усе ще можна вибрати явно, але нові запити OpenAI
|
||||
на генерацію та редагування зображень мають використовувати `gpt-image-2`.
|
||||
|
||||
`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування
|
||||
референсних зображень через той самий інструмент `image_generate`. OpenClaw пересилає в OpenAI
|
||||
`prompt`, `count`, `size`, `quality`, `outputFormat` і референсні зображення.
|
||||
OpenAI не отримує `aspectRatio` або `resolution` напряму; коли це можливо,
|
||||
OpenClaw мапує їх у підтримуваний `size`, інакше інструмент повідомляє про них як
|
||||
про проігноровані перевизначення.
|
||||
`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування з
|
||||
еталонними зображеннями через той самий інструмент `image_generate`. OpenClaw передає в OpenAI `prompt`,
|
||||
`count`, `size`, `quality`, `outputFormat` і еталонні зображення.
|
||||
OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли це можливо,
|
||||
OpenClaw відображає їх у підтримуваний `size`, інакше інструмент повідомляє про них як про
|
||||
проігноровані перевизначення.
|
||||
|
||||
Параметри, специфічні для OpenAI, розміщені в об’єкті `openai`:
|
||||
Параметри, специфічні для OpenAI, містяться в об’єкті `openai`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -238,11 +254,11 @@ OpenClaw мапує їх у підтримуваний `size`, інакше ін
|
||||
}
|
||||
```
|
||||
|
||||
`openai.background` приймає `transparent`, `opaque` або `auto`; прозорий
|
||||
вивід потребує `outputFormat` `png` або `webp`. `openai.outputCompression`
|
||||
застосовується до виводу JPEG/WebP.
|
||||
`openai.background` приймає `transparent`, `opaque` або `auto`; прозорі
|
||||
результати вимагають `outputFormat` `png` або `webp`. `openai.outputCompression`
|
||||
застосовується до результатів JPEG/WebP.
|
||||
|
||||
Згенерувати одне горизонтальне зображення 4K:
|
||||
Згенерувати одне горизонтальне 4K-зображення:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
@ -254,50 +270,50 @@ OpenClaw мапує їх у підтримуваний `size`, інакше ін
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
|
||||
```
|
||||
|
||||
Відредагувати одне локальне референсне зображення:
|
||||
Відредагувати одне локальне еталонне зображення:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Редагування з кількома референсами:
|
||||
Відредагувати з кількома еталонами:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
```
|
||||
|
||||
Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість
|
||||
`api.openai.com`, див. [ендпоїнти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints)
|
||||
`api.openai.com`, див. [Ендпоінти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints)
|
||||
у документації провайдера OpenAI.
|
||||
|
||||
Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax:
|
||||
|
||||
- `minimax/image-01` для конфігурацій з API-ключем
|
||||
- `minimax-portal/image-01` для конфігурацій із OAuth
|
||||
- `minimax/image-01` для налаштувань з API-ключем
|
||||
- `minimax-portal/image-01` для налаштувань з OAuth
|
||||
|
||||
## Можливості провайдерів
|
||||
|
||||
| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
|
||||
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виводи визначає workflow) | Так (1) | Так (до 4) |
|
||||
| Редагування/референс | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, референс суб’єкта) | Так (1 зображення, визначене workflow) | Ні | Так (до 5 зображень) |
|
||||
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виводи визначаються workflow) | Так (1) | Так (до 4) |
|
||||
| Редагування/еталон | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, еталон об’єкта) | Так (1 зображення, визначене workflow) | Ні | Так (до 5 зображень) |
|
||||
| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні |
|
||||
| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так |
|
||||
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
|
||||
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
|
||||
|
||||
### xAI `grok-imagine-image`
|
||||
|
||||
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з промптом
|
||||
і `/v1/images/edits`, коли присутній `image` або `images`.
|
||||
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів
|
||||
лише з підказкою і `/v1/images/edits`, коли присутній `image` або `images`.
|
||||
|
||||
- Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
|
||||
- Кількість: до 4
|
||||
- Референси: один `image` або до п’яти `images`
|
||||
- Еталони: один `image` або до п’яти `images`
|
||||
- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Роздільні здатності: `1K`, `2K`
|
||||
- Вивід: повертається як вкладення зображень під керуванням OpenClaw
|
||||
- Результати: повертаються як вкладення зображень, якими керує OpenClaw
|
||||
|
||||
OpenClaw навмисно не надає нативні для xAI параметри `quality`, `mask`, `user` або
|
||||
OpenClaw навмисно не відкриває специфічні для xAI `quality`, `mask`, `user` або
|
||||
додаткові співвідношення сторін, доступні лише нативно, доки ці елементи керування не з’являться в спільному
|
||||
міжпровайдерному контракті `image_generate`.
|
||||
|
||||
@ -310,6 +326,6 @@ OpenClaw навмисно не надає нативні для xAI параме
|
||||
- [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax
|
||||
- [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images
|
||||
- [Vydra](/uk/providers/vydra) — налаштування зображень, відео й мовлення Vydra
|
||||
- [xAI](/uk/providers/xai) — налаштування зображень, відео, пошуку, виконання коду та TTS Grok
|
||||
- [xAI](/uk/providers/xai) — налаштування зображень, відео, пошуку, виконання коду й TTS Grok
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel`
|
||||
- [Models](/uk/concepts/models) — конфігурація моделей і failover
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання на резервні варіанти
|
||||
|
||||
@ -2,24 +2,24 @@
|
||||
read_when:
|
||||
- Встановлення або налаштування плагінів
|
||||
- Розуміння правил виявлення та завантаження плагінів
|
||||
- Робота з наборами плагінів, сумісними з Codex/Claude
|
||||
- Робота з сумісними з Codex/Claude наборами плагінів
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Встановлення, налаштування та керування плагінами OpenClaw
|
||||
title: Плагіни
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T16:35:11Z"
|
||||
generated_at: "2026-04-24T16:58:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d7db42c0c8d7d8b3bddda46a8a42fc19b39b093863b1730b8ca66528a95ecb50
|
||||
source_hash: 1f4968e70dc215dc50916f2d180121ce2afbe90e6bb2a85d3fe0bd8d989244fd
|
||||
source_path: tools/plugin.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
|
||||
середовища агентів, інструменти, Skills, мовлення, транскрибування в реальному часі, голос у реальному
|
||||
часі, розуміння медіа, генерація зображень, генерація відео, веботримання, вебпошук
|
||||
та інше. Деякі плагіни є **core** (постачаються з OpenClaw), інші
|
||||
є **external** (опубліковані в npm спільнотою).
|
||||
agent harnesses, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному
|
||||
часі, розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук
|
||||
та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші
|
||||
є **external** (опубліковані спільнотою в npm).
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -60,34 +60,38 @@ x-i18n:
|
||||
/plugin enable voice-call
|
||||
```
|
||||
|
||||
Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний
|
||||
шлях/архів, явний `clawhub:<pkg>` або проста специфікація пакета (спочатку ClawHub, потім резервний варіант npm).
|
||||
Шлях встановлення використовує той самий механізм резолюції, що й CLI: локальний
|
||||
шлях/архів, явний `clawhub:<pkg>` або специфікація пакета без префікса (спочатку
|
||||
ClawHub, потім резервний варіант npm).
|
||||
|
||||
Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується з помилкою та
|
||||
вказує вам на `openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях
|
||||
перевстановлення вбудованого плагіна для плагінів, які погоджуються на
|
||||
Якщо конфігурація некоректна, встановлення зазвичай завершується із захистом від помилок і пропонує
|
||||
скористатися `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях
|
||||
перевстановлення вбудованого плагіна для плагінів, які підтримують
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
Пакетні інсталяції OpenClaw не встановлюють завчасно все дерево залежностей
|
||||
середовища виконання кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через
|
||||
Пакетні встановлення OpenClaw не виконують завчасне встановлення всього дерева залежностей
|
||||
середовища виконання для кожного вбудованого плагіна. Коли вбудований плагін OpenClaw є активним через
|
||||
конфігурацію плагіна, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням,
|
||||
під час запуску відновлюються лише оголошені цим плагіном залежності середовища виконання перед його імпортом.
|
||||
Зовнішні плагіни та власні шляхи завантаження, як і раніше, потрібно встановлювати через
|
||||
під час запуску відновлюються лише оголошені цим плагіном залежності середовища виконання
|
||||
перед його імпортом. Явне вимкнення все одно має пріоритет: `plugins.entries.<id>.enabled: false`,
|
||||
`plugins.deny`, `plugins.enabled: false` і `channels.<id>.enabled: false`
|
||||
запобігають автоматичному відновленню залежностей середовища виконання для цього вбудованого плагіна/каналу.
|
||||
External плагіни та власні шляхи завантаження, як і раніше, потрібно встановлювати через
|
||||
`openclaw plugins install`.
|
||||
|
||||
## Типи плагінів
|
||||
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, пакети npm спільноти |
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, npm-пакети спільноти |
|
||||
| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Докладніше про набори див. у [Plugin Bundles](/uk/plugins/bundles).
|
||||
Обидва відображаються в `openclaw plugins list`. Докладніше про набори див. в [Набори плагінів](/uk/plugins/bundles).
|
||||
|
||||
Якщо ви пишете native-плагін, почніть із [Building Plugins](/uk/plugins/building-plugins)
|
||||
та [Plugin SDK Overview](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете native плагін, почніть з [Створення плагінів](/uk/plugins/building-plugins)
|
||||
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Офіційні плагіни
|
||||
|
||||
@ -95,17 +99,17 @@ OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Плагін | Пакет | Документація |
|
||||
| --------------- | --------------------- | ------------------------------------ |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
|
||||
### Core (постачаються з OpenClaw)
|
||||
### Core (постачаються разом з OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнені за замовчуванням)">
|
||||
<Accordion title="Постачальники моделей (увімкнено за замовчуванням)">
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
@ -115,20 +119,20 @@ OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять із автоматичним пригадуванням/захопленням, що встановлюється за потреби (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
- `memory-lancedb` — довготривала пам’ять із встановленням за потреби, автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
<Accordion title="Постачальники мовлення (увімкнено за замовчуванням)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — вбудований browser-плагін для інструмента browser, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання browser і типового сервісу керування browser (увімкнений за замовчуванням; вимкніть його перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
|
||||
- `browser` — вбудований browser плагін для browser tool, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime і типового сервісу керування browser (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (типово вимкнено)
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community).
|
||||
Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -155,33 +159,33 @@ OpenClaw розпізнає два формати плагінів:
|
||||
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі та конфігурація для окремого плагіна |
|
||||
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з
|
||||
відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`),
|
||||
цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
|
||||
Підтримуваного шляху гарячого перезавантаження для native-коду середовища виконання плагінів або хуків
|
||||
життєвого циклу немає; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
|
||||
Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з
|
||||
відстеженням конфігурації та увімкненим перезапуском у межах процесу (типовий шлях `openclaw gateway`),
|
||||
цей перезапуск зазвичай виконується автоматично невдовзі після застосування запису конфігурації.
|
||||
Підтримуваного шляху гарячого перезавантаження для native коду середовища виконання плагінів або lifecycle
|
||||
hooks немає; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
|
||||
очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, сервіси або
|
||||
хуки постачальника/середовища виконання почнуть працювати.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок CLI/конфігурації. Плагін зі станом `loaded`
|
||||
там означає, що плагін можна виявити та завантажити з конфігурації/файлів, які бачить це
|
||||
виконання CLI. Це не доводить, що вже запущений дочірній процес віддаленого Gateway
|
||||
перезапустився з тим самим кодом плагіна. У налаштуваннях VPS/контейнерів із процесами-обгортками
|
||||
надсилайте перезапуск фактичному процесу `openclaw gateway run` або використовуйте
|
||||
`openclaw gateway restart` для запущеного Gateway.
|
||||
`openclaw plugins list` — це локальний знімок CLI/конфігурації. Позначка `loaded` для плагіна там
|
||||
означає, що плагін можна виявити та завантажити з конфігурації/файлів, які бачить
|
||||
цей виклик CLI. Це не доводить, що вже запущений віддалений дочірній процес Gateway
|
||||
було перезапущено в той самий код плагіна. У налаштуваннях VPS/контейнерів з процесами-обгортками
|
||||
надсилайте перезапуски фактичному процесу `openclaw gateway run` або
|
||||
використовуйте `openclaw gateway restart` для запущеного Gateway.
|
||||
|
||||
<Accordion title="Стани плагінів: вимкнений, відсутній, недійсний">
|
||||
- **Disabled**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Missing**: конфігурація посилається на ідентифікатор плагіна, який виявлення не знайшло.
|
||||
- **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній або некоректний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
|
||||
- **Некоректний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
</Accordion>
|
||||
|
||||
## Виявлення та пріоритет
|
||||
## Виявлення та пріоритетність
|
||||
|
||||
OpenClaw сканує плагіни в такому порядку (перше знайдене збігання має пріоритет):
|
||||
OpenClaw сканує плагіни в такому порядку (перше співпадіння має пріоритет):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи конфігурації">
|
||||
<Step title="Шляхи з конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів.
|
||||
</Step>
|
||||
|
||||
@ -194,8 +198,8 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
</Step>
|
||||
|
||||
<Step title="Вбудовані плагіни">
|
||||
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
Постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
|
||||
Для інших потрібне явне ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -204,41 +208,41 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
- `plugins.enabled: false` вимикає всі плагіни
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей плагін
|
||||
- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані плагіни дотримуються вбудованого набору типово ввімкнених, якщо це не перевизначено
|
||||
- Плагіни з робочого простору **типово вимкнені** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота
|
||||
- Деякі вбудовані плагіни з опціональним ввімкненням вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або
|
||||
середовище виконання harness
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів:
|
||||
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін
|
||||
app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
|
||||
- Деякі вбудовані opt-in плагіни вмикаються автоматично, коли конфігурація задає
|
||||
surface, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або harness
|
||||
runtime
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі між плагінами:
|
||||
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін Codex
|
||||
app-server вибирається через `embeddedHarness.runtime: "codex"` або застарілі
|
||||
посилання на модель `codex/*`
|
||||
|
||||
## Усунення несправностей хуків середовища виконання
|
||||
## Усунення проблем із хуками середовища виконання
|
||||
|
||||
Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки
|
||||
не працюють у живому трафіку чату, спочатку перевірте таке:
|
||||
Якщо плагін відображається в `plugins list`, але побічні ефекти `register(api)` або hooks
|
||||
не спрацьовують у живому чат-трафіку, спочатку перевірте таке:
|
||||
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і переконайтеся, що активні
|
||||
URL Gateway, профіль, шлях до конфігурації та процес — це саме ті, які ви редагуєте.
|
||||
- Перезапустіть активний Gateway після змін у встановленні/конфігурації/коді плагіна. У контейнерах
|
||||
з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
з обгортками процес PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використовуйте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації хуків і
|
||||
діагностику. Для невбудованих хуків розмови, таких як `llm_input`,
|
||||
`llm_output` і `agent_end`, потрібен
|
||||
- Використайте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Невбудовані conversation hooks, такі як `llm_input`,
|
||||
`llm_output` і `agent_end`, потребують
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується до
|
||||
розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить вивід помічника.
|
||||
- Для підтвердження фактичної моделі сеансу використовуйте `openclaw sessions` або
|
||||
поверхні сеансу/стану Gateway, а під час налагодження корисного навантаження постачальника запускайте
|
||||
- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він запускається до
|
||||
визначення моделі для ходів агента; `llm_output` запускається лише після того, як спроба моделі
|
||||
створить вивід асистента.
|
||||
- Щоб підтвердити фактичну модель сесії, використовуйте `openclaw sessions` або
|
||||
поверхні Gateway session/status, а під час налагодження payloads постачальника запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
## Слоти плагінів (ексклюзивні категорії)
|
||||
|
||||
Деякі категорії є ексклюзивними (одночасно може бути активною лише одна):
|
||||
Деякі категорії є ексклюзивними (одночасно може бути активним лише один плагін):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -251,32 +255,32 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що він контролює | Типове значення |
|
||||
| --------------- | ---------------------- | ------------------- |
|
||||
| `memory` | Active Memory plugin | `memory-core` |
|
||||
| Слот | Що він контролює | Типове значення |
|
||||
| --------------- | ----------------------- | ------------------- |
|
||||
| `memory` | Active Memory плагін | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
|
||||
## Довідка CLI
|
||||
## Довідник CLI
|
||||
|
||||
```bash
|
||||
openclaw plugins list # компактний перелік
|
||||
openclaw plugins list --enabled # лише завантажені плагіни
|
||||
openclaw plugins list --verbose # детальні рядки для кожного плагіна
|
||||
openclaw plugins list --json # машиночитний перелік
|
||||
openclaw plugins inspect <id> # докладні відомості
|
||||
openclaw plugins inspect <id> --json # машиночитно
|
||||
openclaw plugins inspect --all # таблиця для всього набору
|
||||
openclaw plugins info <id> # псевдонім inspect
|
||||
openclaw plugins list --verbose # докладні рядки для кожного плагіна
|
||||
openclaw plugins list --json # машиночитаний перелік
|
||||
openclaw plugins inspect <id> # докладна інформація
|
||||
openclaw plugins inspect <id> --json # машиночитаний формат
|
||||
openclaw plugins inspect --all # таблиця для всіх
|
||||
openclaw plugins info <id> # псевдонім для inspect
|
||||
openclaw plugins doctor # діагностика
|
||||
|
||||
openclaw plugins install <package> # встановлення (спочатку ClawHub, потім npm)
|
||||
openclaw plugins install clawhub:<pkg> # встановлення лише з ClawHub
|
||||
openclaw plugins install <spec> --force # перезаписати наявне встановлення
|
||||
openclaw plugins install <path> # встановлення з локального шляху
|
||||
openclaw plugins install -l <path> # посилання (без копіювання) для розробки
|
||||
openclaw plugins install -l <path> # підключення (без копіювання) для розробки
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # записати точну розв’язану специфікацію npm
|
||||
openclaw plugins install <spec> --pin # зафіксувати точну розв’язану npm-специфікацію
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # оновити один плагін
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
@ -290,61 +294,59 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований
|
||||
browser-плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable <id>`.
|
||||
browser плагін). Інші вбудовані плагіни все одно потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm-
|
||||
плагінів. Це не підтримується з `--link`, який повторно використовує шлях до джерела замість
|
||||
копіювання в керовану ціль встановлення.
|
||||
`--force` перезаписує наявний встановлений плагін або набір hooks на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
плагінів. Це не підтримується разом із `--link`, який повторно використовує вихідний шлях
|
||||
замість копіювання в кероване місце встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, тож установлені плагіни
|
||||
можна завантажувати одразу після перезапуску.
|
||||
ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, щоб установлені плагіни
|
||||
можна було одразу завантажити після перезапуску.
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних установлень. Передавання
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад до запису відстежуваного плагіна й записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переводить точно зафіксоване встановлення назад на
|
||||
типову лінію випуску реєстру. Якщо встановлений npm-плагін уже відповідає розв’язаній
|
||||
версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення без завантаження,
|
||||
перевстановлення чи перезапису конфігурації.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
npm-специфікації пакета з dist-tag або точною версією зводить назву пакета
|
||||
назад до запису відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії повертає точно зафіксоване встановлення до
|
||||
типової лінії випусків реєстру. Якщо встановлений npm плагін уже відповідає
|
||||
розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або перезапису конфігурації.
|
||||
|
||||
`--pin` доступний лише для npm. Він не підтримується з `--marketplace`, оскільки
|
||||
встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
|
||||
`--pin` працює лише для npm. Він не підтримується разом із `--marketplace`, оскільки
|
||||
встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації.
|
||||
|
||||
`--dangerously-force-unsafe-install` — це аварійний обхід для хибнопозитивних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення
|
||||
та оновлення плагінів попри вбудовані критичні (`critical`) знахідки, але все одно
|
||||
не обходить блокування політики плагіна `before_install` або блокування через збій сканування.
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє продовжити встановлення
|
||||
та оновлення плагінів попри вбудовані результати рівня `critical`, але все одно
|
||||
не обходить блокування політики плагіна `before_install` або блокування через помилку сканування.
|
||||
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Установлення
|
||||
залежностей Skills через Gateway натомість використовують відповідне перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком
|
||||
завантаження/встановлення Skills з ClawHub.
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills
|
||||
через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як
|
||||
`openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub.
|
||||
|
||||
Сумісні набори беруть участь у тому самому потоці list/inspect/enable/disable для плагінів.
|
||||
Поточна підтримка середовища виконання включає bundle Skills, command-skills Claude,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
|
||||
`lspServers`, оголошені в маніфесті, command-skills Cursor, а також сумісні каталоги
|
||||
хуків Codex.
|
||||
оголошених у маніфесті `lspServers`, command-skills Cursor та сумісні каталоги hooks Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості набору, а також
|
||||
підтримувані чи непідтримувані записи серверів MCP і LSP для плагінів, що працюють на основі наборів.
|
||||
підтримувані й непідтримувані записи серверів MCP і LSP для плагінів на основі наборів.
|
||||
|
||||
Джерелами marketplace можуть бути відома назва marketplace Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до
|
||||
`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах
|
||||
клонованого репозиторію marketplace і використовувати лише відносні шляхи джерел.
|
||||
або URL git. Для віддалених marketplace записи плагінів мають залишатися в межах
|
||||
клонованого репозиторію marketplace та використовувати лише відносні джерела шляхів.
|
||||
|
||||
Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
|
||||
## Огляд Plugin API
|
||||
## Огляд API плагінів
|
||||
|
||||
Native-плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають
|
||||
Native плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні
|
||||
використовувати `register`.
|
||||
|
||||
```typescript
|
||||
@ -365,9 +367,9 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw завантажує об’єкт входу й викликає `register(api)` під час активації
|
||||
плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів,
|
||||
але вбудовані плагіни та нові зовнішні плагіни мають вважати `register` публічним контрактом.
|
||||
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
|
||||
активації плагіна. Завантажувач усе ще використовує резервний перехід до `activate(api)` для старіших плагінів,
|
||||
але вбудовані плагіни та нові external плагіни повинні вважати `register` публічним контрактом.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
@ -376,42 +378,42 @@ OpenClaw завантажує об’єкт входу й викликає `regi
|
||||
| `registerProvider` | Постачальник моделей (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider`| Потокове STT |
|
||||
| `registerHook` / `on(...)` | Lifecycle hooks |
|
||||
| `registerSpeechProvider` | Синтез мовлення / STT |
|
||||
| `registerRealtimeTranscriptionProvider`| Потоковий STT |
|
||||
| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Постачальник веботримання / скрапінгу |
|
||||
| `registerWebFetchProvider` | Постачальник веб-отримання / збирання |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP-ендпойнт |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фоновий сервіс |
|
||||
|
||||
Поведінка захисту хуків для типізованих хуків життєвого циклу:
|
||||
Поведінка guard hooks для типізованих lifecycle hooks:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` нічого не змінює й не скасовує раніше встановлене блокування.
|
||||
- `before_tool_call`: `{ block: false }` не має ефекту та не скасовує раніше встановлене блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` нічого не змінює й не скасовує раніше встановлене блокування.
|
||||
- `before_install`: `{ block: false }` не має ефекту та не скасовує раніше встановлене блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` нічого не змінює й не скасовує раніше встановлене скасування.
|
||||
- `message_sending`: `{ cancel: false }` не має ефекту та не скасовує раніше встановлене скасування.
|
||||
|
||||
Native Codex app-server повертає події інструментів Codex-native через цей
|
||||
інтерфейс хуків. Плагіни можуть блокувати native-інструменти Codex через `before_tool_call`,
|
||||
Native Codex app-server повертає події інструментів, нативних для Codex, назад у цю
|
||||
поверхню hooks через міст. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
спостерігати за результатами через `after_tool_call` і брати участь у погодженнях
|
||||
`PermissionRequest` Codex. Міст поки що не переписує аргументи native-інструментів Codex.
|
||||
`PermissionRequest` Codex. Міст поки що не переписує аргументи інструментів, нативних для Codex.
|
||||
|
||||
Повний опис поведінки типізованих хуків див. у [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
Повну поведінку типізованих hooks див. в [Огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Building Plugins](/uk/plugins/building-plugins) — створення власного плагіна
|
||||
- [Plugin Bundles](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor
|
||||
- [Plugin Manifest](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін
|
||||
- [Plugin Internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Community Plugins](/uk/plugins/community) — сторонні добірки
|
||||
- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
|
||||
- [Набори плагінів](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor
|
||||
- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін
|
||||
- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Плагіни спільноти](/uk/plugins/community) — сторонні добірки
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете фонову/паралельну роботу через агента
|
||||
- Ви змінюєте `sessions_spawn` або політику інструментів субагента
|
||||
- Ви реалізуєте або усуваєте несправності прив’язаних до тредів сесій субагента
|
||||
summary: 'Субагенти: запуск ізольованих агентських процесів, які повідомляють результати назад у чат запитувача'
|
||||
title: Субагенти
|
||||
- Вам потрібна фонова/паралельна робота через агента
|
||||
- Ви змінюєте sessions_spawn або політику інструмента підлеглих агентів
|
||||
- Ви реалізуєте або налагоджуєте прив’язані до потоку сеанси підлеглих агентів
|
||||
summary: 'Підлеглі агенти: запуск ізольованих сеансів агентів, які повідомляють про результати назад у чат запитувача'
|
||||
title: Підлеглі агенти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T23:08:51Z"
|
||||
generated_at: "2026-04-24T16:58:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 23202b1761e372e547b02183cb68056043aed04b5620db8b222cbfc7e6cd97ab
|
||||
source_hash: 471b01c1e6bf689f097e67a7037f35348ac7e8a8a334a83778c6593073332274
|
||||
source_path: tools/subagents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Субагенти — це фонові агентські процеси, запущені з наявного агентського запуску. Вони працюють у власній сесії (`agent:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск субагента відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Підлеглі агенти — це фонові сеанси агентів, запущені з наявного сеансу агента. Вони працюють у власній сесії (`agent:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у канал чату запитувача. Кожен сеанс підлеглого агента відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
## Команда зі скісною рискою
|
||||
## Слеш-команда
|
||||
|
||||
Використовуйте `/subagents`, щоб переглядати або керувати запуском субагентів для **поточної сесії**:
|
||||
Використовуйте `/subagents`, щоб переглядати або керувати сеансами підлеглих агентів для **поточної сесії**:
|
||||
|
||||
- `/subagents list`
|
||||
- `/subagents kill <id|#|all>`
|
||||
@ -28,9 +28,9 @@ x-i18n:
|
||||
- `/subagents steer <id|#> <message>`
|
||||
- `/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]`
|
||||
|
||||
Керування прив’язкою тредів:
|
||||
Елементи керування прив’язкою до потоку:
|
||||
|
||||
Ці команди працюють на каналах, які підтримують постійні прив’язки тредів. Див. **Канали з підтримкою тредів** нижче.
|
||||
Ці команди працюють на каналах, які підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче.
|
||||
|
||||
- `/focus <subagent-label|session-key|session-id|session-label>`
|
||||
- `/unfocus`
|
||||
@ -38,117 +38,130 @@ x-i18n:
|
||||
- `/session idle <duration|off>`
|
||||
- `/session max-age <duration|off>`
|
||||
|
||||
`/subagents info` показує метадані запуску (стан, часові мітки, id сесії, шлях до транскрипту, очищення).
|
||||
Використовуйте `sessions_history` для обмеженого, відфільтрованого з погляду безпеки перегляду; перевіряйте
|
||||
`/subagents info` показує метадані сеансу (статус, часові мітки, id сесії, шлях до транскрипту, очищення).
|
||||
Використовуйте `sessions_history` для обмеженого, відфільтрованого з міркувань безпеки перегляду історії; перевіряйте
|
||||
шлях до транскрипту на диску, коли вам потрібен сирий повний транскрипт.
|
||||
|
||||
### Поведінка spawn
|
||||
### Поведінка запуску
|
||||
|
||||
`/subagents spawn` запускає фонового субагента як команду користувача, а не як внутрішню relay-операцію, і надсилає одне фінальне повідомлення про завершення назад у чат запитувача, коли запуск завершується.
|
||||
`/subagents spawn` запускає фоновий підлеглий агент як команду користувача, а не як внутрішню ретрансляцію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли сеанс завершується.
|
||||
|
||||
- Команда spawn не блокує виконання; вона одразу повертає id запуску.
|
||||
- Після завершення субагент повідомляє назад у чат-канал запитувача зведення/результат.
|
||||
- Доставка завершення є push-орієнтованою. Після запуску не опитуйте циклічно `/subagents list`,
|
||||
`sessions_list` або `sessions_history` лише для очікування
|
||||
завершення; перевіряйте стан лише за потреби для налагодження або втручання.
|
||||
- Після завершення OpenClaw у режимі best-effort закриває відстежувані вкладки браузера/процеси, відкриті цією сесією субагента, перш ніж продовжити потік очищення announce.
|
||||
- Для ручних spawn доставка є стійкою:
|
||||
- OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем idempotency.
|
||||
- Команда запуску не блокує виконання; вона одразу повертає id сеансу.
|
||||
- Після завершення підлеглий агент повідомляє повідомлення з підсумком/результатом назад у канал чату запитувача.
|
||||
- Доставка завершення є push-орієнтованою. Після запуску не опитуйте `/subagents list`,
|
||||
`sessions_list` або `sessions_history` у циклі лише для того, щоб дочекатися
|
||||
завершення; перевіряйте статус лише за потреби для налагодження або втручання.
|
||||
- Після завершення OpenClaw у межах best-effort закриває відстежувані вкладки/процеси браузера, відкриті цим сеансом підлеглого агента, перш ніж продовжити потік очищення після повідомлення.
|
||||
- Для ручних запусків доставка є стійкою:
|
||||
- OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем ідемпотентності.
|
||||
- Якщо пряма доставка не вдається, використовується резервний маршрут через чергу.
|
||||
- Якщо й маршрут через чергу недоступний, announce повторно надсилається з коротким експоненційним backoff перед остаточною відмовою.
|
||||
- Якщо маршрутизація через чергу все ще недоступна, спроба повідомлення повторюється з короткою експоненційною затримкою перед остаточною відмовою.
|
||||
- Доставка завершення зберігає визначений маршрут запитувача:
|
||||
- прив’язані до треду або до розмови маршрути завершення мають пріоритет, коли доступні
|
||||
- якщо походження завершення надає лише канал, OpenClaw заповнює відсутню ціль/обліковий запис із визначеного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
|
||||
- Передача завершення до сесії запитувача — це внутрішній контекст, згенерований під час runtime (а не текст, створений користувачем), і він містить:
|
||||
- `Result` (останній видимий текст відповіді `assistant`, інакше очищений останній текст `tool`/`toolResult`; завершені з помилкою фінальні запуски не використовують повторно захоплений текст відповіді)
|
||||
- маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні
|
||||
- якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
|
||||
- Передавання завершення до сесії запитувача є внутрішнім контекстом, згенерованим під час виконання (а не текстом, створеним користувачем), і містить:
|
||||
- `Result` (останній видимий текст відповіді `assistant`, або, якщо його немає, очищений останній текст `tool`/`toolResult`; термінальні невдалі сеанси не використовують повторно захоплений текст відповіді)
|
||||
- `Status` (`completed successfully` / `failed` / `timed out` / `unknown`)
|
||||
- компактну статистику runtime/токенів
|
||||
- інструкцію доставки, яка вказує агенту запитувача переписати це нормальним голосом помічника (а не пересилати сирі внутрішні метадані)
|
||||
- `--model` і `--thinking` перевизначають значення за замовчуванням для цього конкретного запуску.
|
||||
- Використовуйте `info`/`log`, щоб переглядати деталі та вивід після завершення.
|
||||
- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до тредів, використовуйте `sessions_spawn` з `thread: true` і `mode: "session"`.
|
||||
- компактну статистику виконання/токенів
|
||||
- інструкцію з доставки, яка повідомляє агенту запитувача переписати відповідь звичайним голосом помічника (а не пересилати сирі внутрішні метадані)
|
||||
- `--model` і `--thinking` перевизначають типові значення для цього конкретного сеансу.
|
||||
- Використовуйте `info`/`log`, щоб переглянути деталі та вивід після завершення.
|
||||
- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до потоку, використовуйте `sessions_spawn` з `thread: true` і `mode: "session"`.
|
||||
- Для сесій ACP harness (Codex, Claude Code, Gemini CLI) використовуйте `sessions_spawn` з `runtime: "acp"` і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model), коли налагоджуєте завершення або цикли агент-до-агента.
|
||||
|
||||
Основні цілі:
|
||||
|
||||
- Розпаралелити роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного запуску.
|
||||
- Ізолювати субагентів за замовчуванням (розділення сесій + необов’язкова пісочниця).
|
||||
- Зробити поверхню інструментів важкою для зловживання: субагенти **не** отримують інструменти сесій за замовчуванням.
|
||||
- Підтримувати налаштовувану глибину вкладеності для orchestrator-шаблонів.
|
||||
- Розпаралелити роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного сеансу.
|
||||
- За замовчуванням зберігати ізоляцію підлеглих агентів (розділення сесій + додаткове пісочницьке середовище).
|
||||
- Зробити поверхню інструментів складною для неправильного використання: підлеглі агенти **не** отримують інструменти сесії за замовчуванням.
|
||||
- Підтримувати налаштовувану глибину вкладеності для шаблонів оркестрації.
|
||||
|
||||
Примітка про вартість: кожен субагент за замовчуванням має **власний** контекст і споживання токенів. Для важких або
|
||||
повторюваних завдань установіть дешевшу модель для субагентів і залиште основного агента на
|
||||
якіснішій моделі. Це можна налаштувати через `agents.defaults.subagents.model` або перевизначення
|
||||
для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запитати
|
||||
`context: "fork"` лише для цього конкретного spawn.
|
||||
Примітка щодо вартості: кожен підлеглий агент за замовчуванням має **власний** контекст і споживання токенів. Для важких або
|
||||
повторюваних завдань задайте для підлеглих агентів дешевшу модель, а основний агент залиште на
|
||||
якіснішій моделі. Ви можете налаштувати це через `agents.defaults.subagents.model` або перевизначення
|
||||
для конкретного агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запитати
|
||||
`context: "fork"` під час саме цього запуску.
|
||||
|
||||
## Режими контексту
|
||||
|
||||
Вбудовані підлеглі агенти запускаються ізольовано, якщо тільки викликач явно не попросить розгалужити
|
||||
поточний транскрипт.
|
||||
|
||||
| Режим | Коли використовувати | Поведінка |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | Нове дослідження, незалежна реалізація, повільна робота інструмента або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це типове значення і воно зменшує використання токенів. |
|
||||
| `fork` | Робота, яка залежить від поточної розмови, попередніх результатів інструментів або тонких інструкцій, уже наявних у транскрипті запитувача | Розгалужує транскрипт запитувача в дочірню сесію до початку роботи дочірнього агента. |
|
||||
|
||||
Використовуйте `fork` ощадливо. Це для делегування, чутливого до контексту, а не заміна
|
||||
написанню чіткого запиту на завдання.
|
||||
|
||||
## Інструмент
|
||||
|
||||
Використовуйте `sessions_spawn`:
|
||||
|
||||
- Запускає процес субагента (`deliver: false`, глобальна смуга: `subagent`)
|
||||
- Потім виконує announce-крок і публікує announce-відповідь у чат-канал запитувача
|
||||
- Модель за замовчуванням: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого агента); явне `sessions_spawn.model` усе одно має пріоритет.
|
||||
- Thinking за замовчуванням: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого агента); явне `sessions_spawn.thinking` усе одно має пріоритет.
|
||||
- Тайм-аут запуску за замовчуванням: якщо `sessions_spawn.runTimeoutSeconds` пропущено, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано; інакше використовується `0` (без тайм-ауту).
|
||||
- Запускає сеанс підлеглого агента (`deliver: false`, глобальна смуга: `subagent`)
|
||||
- Потім виконує крок повідомлення і публікує відповідь-повідомлення в канал чату запитувача
|
||||
- Типова модель: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для конкретного агента); явне значення `sessions_spawn.model` усе одно має пріоритет.
|
||||
- Типовий рівень thinking: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для конкретного агента); явне значення `sessions_spawn.thinking` усе одно має пріоритет.
|
||||
- Типовий тайм-аут сеансу: якщо `sessions_spawn.runTimeoutSeconds` пропущено, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його встановлено; інакше повертається до `0` (без тайм-ауту).
|
||||
|
||||
Параметри інструмента:
|
||||
|
||||
- `task` (обов’язково)
|
||||
- `label?` (необов’язково)
|
||||
- `agentId?` (необов’язково; запускати під іншим id агента, якщо це дозволено)
|
||||
- `model?` (необов’язково; перевизначає модель субагента; некоректні значення пропускаються, і субагент запускається на моделі за замовчуванням із попередженням у результаті інструмента)
|
||||
- `thinking?` (необов’язково; перевизначає рівень thinking для запуску субагента)
|
||||
- `runTimeoutSeconds?` (типово дорівнює `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано, інакше `0`; якщо встановлено, запуск субагента переривається через N секунд)
|
||||
- `thread?` (типово `false`; якщо `true`, запитує прив’язку канального треду для цієї сесії субагента)
|
||||
- `task` (обов’язковий)
|
||||
- `label?` (необов’язковий)
|
||||
- `agentId?` (необов’язковий; запуск під іншим id агента, якщо це дозволено)
|
||||
- `model?` (необов’язковий; перевизначає модель підлеглого агента; некоректні значення пропускаються, і підлеглий агент запускається на типовій моделі з попередженням у результаті інструмента)
|
||||
- `thinking?` (необов’язковий; перевизначає рівень thinking для сеансу підлеглого агента)
|
||||
- `runTimeoutSeconds?` (типово: `agents.defaults.subagents.runTimeoutSeconds`, якщо встановлено, інакше `0`; якщо встановлено, сеанс підлеглого агента переривається через N секунд)
|
||||
- `thread?` (типово `false`; якщо `true`, запитує прив’язку до потоку каналу для цієї сесії підлеглого агента)
|
||||
- `mode?` (`run|session`)
|
||||
- за замовчуванням `run`
|
||||
- типове значення — `run`
|
||||
- якщо `thread: true` і `mode` пропущено, типовим стає `session`
|
||||
- `mode: "session"` вимагає `thread: true`
|
||||
- `cleanup?` (`delete|keep`, типово `keep`)
|
||||
- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє spawn, якщо цільовий дочірній runtime не ізольований у пісочниці)
|
||||
- `context?` (`isolated|fork`, типово `isolated`; лише для нативних субагентів)
|
||||
- `isolated` створює чистий дочірній транскрипт і є значенням за замовчуванням.
|
||||
- `fork` відгалужує поточний транскрипт запитувача в дочірню сесію, тож дочірня сесія починає з того самого контексту розмови.
|
||||
- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільове дочірнє середовище виконання не є пісочницею)
|
||||
- `context?` (`isolated|fork`, типово `isolated`; лише для вбудованих підлеглих агентів)
|
||||
- `isolated` створює чистий дочірній транскрипт і є типовим значенням.
|
||||
- `fork` розгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній агент починав із тим самим контекстом розмови.
|
||||
- Використовуйте `fork` лише тоді, коли дочірньому агенту потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`.
|
||||
- `sessions_spawn` **не** приймає параметри доставки каналом (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного процесу.
|
||||
- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного сеансу.
|
||||
|
||||
## Сесії, прив’язані до тредів
|
||||
## Сесії, прив’язані до потоку
|
||||
|
||||
Коли для каналу ввімкнено прив’язки тредів, субагент може залишатися прив’язаним до треду, щоб подальші повідомлення користувача в цьому треді продовжували маршрутизуватися до тієї самої сесії субагента.
|
||||
Коли для каналу ввімкнені прив’язки до потоку, підлеглий агент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці й далі маршрутизувалися до тієї самої сесії підлеглого агента.
|
||||
|
||||
### Канали з підтримкою тредів
|
||||
### Канали з підтримкою потоків
|
||||
|
||||
- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії субагентів, прив’язані до тредів (`sessions_spawn` з `thread: true`), ручне керування тредами (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`.
|
||||
- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії підлеглих агентів, прив’язані до потоку (`sessions_spawn` з `thread: true`), ручні елементи керування потоком (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`.
|
||||
|
||||
Швидкий процес:
|
||||
Швидкий сценарій:
|
||||
|
||||
1. Запустіть через `sessions_spawn`, використовуючи `thread: true` (і, за бажанням, `mode: "session"`).
|
||||
2. OpenClaw створює тред або прив’язує його до цієї цільової сесії в активному каналі.
|
||||
3. Відповіді та подальші повідомлення в цьому треді маршрутизуються до прив’язаної сесії.
|
||||
4. Використовуйте `/session idle`, щоб переглянути/оновити автоматичне зняття фокусу через неактивність, і `/session max-age`, щоб керувати жорстким лімітом.
|
||||
5. Використовуйте `/unfocus`, щоб вручну від’єднати тред.
|
||||
1. Запустіть через `sessions_spawn`, використовуючи `thread: true` (і за потреби `mode: "session"`).
|
||||
2. OpenClaw створює потік або прив’язує його до цілі цієї сесії в активному каналі.
|
||||
3. Відповіді та подальші повідомлення в цьому потоці маршрутизуються до прив’язаної сесії.
|
||||
4. Використовуйте `/session idle`, щоб переглянути/оновити автоматичне зняття фокусу через неактивність, а `/session max-age` — щоб керувати жорстким обмеженням часу.
|
||||
5. Використовуйте `/unfocus`, щоб від’єднати вручну.
|
||||
|
||||
Ручне керування:
|
||||
|
||||
- `/focus <target>` прив’язує поточний тред (або створює його) до цільової сесії/субагента.
|
||||
- `/unfocus` видаляє прив’язку для поточного прив’язаного треду.
|
||||
- `/agents` перелічує активні запуски та стан прив’язки (`thread:<id>` або `unbound`).
|
||||
- `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних тредів.
|
||||
- `/focus <target>` прив’язує поточний потік (або створює його) до цілі підлеглого агента/сесії.
|
||||
- `/unfocus` видаляє прив’язку для поточного прив’язаного потоку.
|
||||
- `/agents` показує список активних сеансів і стан прив’язки (`thread:<id>` або `unbound`).
|
||||
- `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних потоків.
|
||||
|
||||
Перемикачі конфігурації:
|
||||
|
||||
- Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
|
||||
- Перевизначення для каналу та ключі автоприв’язки spawn є специфічними для адаптера. Див. **Канали з підтримкою тредів** вище.
|
||||
- Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
|
||||
- Перевизначення каналу та ключі автоматичної прив’язки під час запуску залежать від адаптера. Див. **Канали з підтримкою потоків** вище.
|
||||
|
||||
Див. [Довідник із конфігурації](/uk/gateway/configuration-reference) і [Команди зі скісною рискою](/uk/tools/slash-commands) для поточних подробиць адаптера.
|
||||
Див. [Довідник з конфігурації](/uk/gateway/configuration-reference) і [Слеш-команди](/uk/tools/slash-commands) для актуальних відомостей про адаптери.
|
||||
|
||||
Allowlist:
|
||||
Список дозволених значень:
|
||||
|
||||
- `agents.list[].subagents.allowAgents`: список id агентів, на які можна націлюватися через `agentId` (`["*"]` — дозволити будь-який). Типово: лише агент запитувача.
|
||||
- `agents.defaults.subagents.allowAgents`: allowlist цільових агентів за замовчуванням, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`.
|
||||
- Захист успадкування пісочниці: якщо сесія запитувача ізольована в пісочниці, `sessions_spawn` відхиляє цілі, які запускалися б без пісочниці.
|
||||
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: якщо `true`, блокуються виклики `sessions_spawn`, які не містять `agentId` (примушує до явного вибору профілю). Типово: false.
|
||||
- `agents.list[].subagents.allowAgents`: список id агентів, які можна використовувати через `agentId` (`["*"]` дозволяє будь-який). Типово: лише агент запитувача.
|
||||
- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових агентів, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`.
|
||||
- Захист успадкування пісочниці: якщо сесія запитувача працює в пісочниці, `sessions_spawn` відхиляє цілі, які запускалися б без пісочниці.
|
||||
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: якщо `true`, блокують виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю). Типово: false.
|
||||
|
||||
Виявлення:
|
||||
|
||||
@ -156,17 +169,17 @@ Allowlist:
|
||||
|
||||
Автоархівація:
|
||||
|
||||
- Сесії субагентів автоматично архівуються через `agents.defaults.subagents.archiveAfterMinutes` (типово: 60).
|
||||
- Сесії підлеглих агентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60).
|
||||
- Архівація використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.<timestamp>` (та сама папка).
|
||||
- `cleanup: "delete"` архівує одразу після announce (але все одно зберігає транскрипт через перейменування).
|
||||
- Автоархівація працює в режимі best-effort; очікувані таймери втрачаються, якщо gateway перезапускається.
|
||||
- `runTimeoutSeconds` **не** викликає автоархівацію; він лише зупиняє запуск. Сесія залишається, доки не спрацює автоархівація.
|
||||
- `cleanup: "delete"` архівує одразу після повідомлення (транскрипт усе ще зберігається через перейменування).
|
||||
- Автоархівація працює в режимі best-effort; заплановані таймери втрачаються, якщо Gateway перезапускається.
|
||||
- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє сеанс. Сесія залишається до автоархівації.
|
||||
- Автоархівація однаково застосовується до сесій глибини 1 і глибини 2.
|
||||
- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються в режимі best-effort після завершення запуску, навіть якщо запис транскрипту/сесії зберігається.
|
||||
- Очищення браузера є окремим від очищення архіву: відстежувані вкладки/процеси браузера в межах best-effort закриваються, коли сеанс завершується, навіть якщо запис транскрипту/сесії зберігається.
|
||||
|
||||
## Вкладені субагенти
|
||||
## Вкладені підлеглі агенти
|
||||
|
||||
За замовчуванням субагенти не можуть запускати власних субагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **orchestrator-шаблон**: main → субагент-оркестратор → дочірні суб-субагенти.
|
||||
Типово підлеглі агенти не можуть запускати власних підлеглих агентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестрації**: основний → підлеглий агент-оркестратор → дочірні підлеглі агенти-працівники.
|
||||
|
||||
### Як увімкнути
|
||||
|
||||
@ -175,10 +188,10 @@ Allowlist:
|
||||
agents: {
|
||||
defaults: {
|
||||
subagents: {
|
||||
maxSpawnDepth: 2, // дозволити субагентам запускати дочірніх агентів (типово: 1)
|
||||
maxChildrenPerAgent: 5, // макс. кількість активних дочірніх агентів на сесію агента (типово: 5)
|
||||
maxConcurrent: 8, // глобальне обмеження одночасності смуги (типово: 8)
|
||||
runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, коли значення пропущено (0 = без тайм-ауту)
|
||||
maxSpawnDepth: 2, // дозволити підлеглим агентам запускати дочірніх агентів (типово: 1)
|
||||
maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на сесію агента (типово: 5)
|
||||
maxConcurrent: 8, // глобальне обмеження паралельності смуги (типово: 8)
|
||||
runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, якщо параметр пропущено (0 = без тайм-ауту)
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -187,124 +200,124 @@ Allowlist:
|
||||
|
||||
### Рівні глибини
|
||||
|
||||
| Глибина | Форма ключа сесії | Роль | Може запускати? |
|
||||
| ----- | -------------------------------------------- | --------------------------------------------- | ----------------------------- |
|
||||
| 0 | `agent:<id>:main` | Основний агент | Завжди |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Субагент (оркестратор, коли дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Суб-субагент (кінцевий worker) | Ніколи |
|
||||
| Глибина | Форма ключа сесії | Роль | Може запускати? |
|
||||
| ------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | Основний агент | Завжди |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Підлеглий агент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Підпідлеглий агент (кінцевий виконавець) | Ніколи |
|
||||
|
||||
### Ланцюжок announce
|
||||
### Ланцюжок повідомлень
|
||||
|
||||
Результати проходять ланцюжком угору:
|
||||
Результати повертаються вгору ланцюжком:
|
||||
|
||||
1. Worker глибини 2 завершується → повідомляє свого батька (оркестратора глибини 1)
|
||||
2. Оркестратор глибини 1 отримує announce, синтезує результати, завершується → повідомляє основного агента
|
||||
3. Основний агент отримує announce і доставляє його користувачеві
|
||||
1. Виконавець глибини 2 завершується → повідомляє своєму батьківському агенту (оркестратору глибини 1)
|
||||
2. Оркестратор глибини 1 отримує повідомлення, синтезує результати, завершується → повідомляє основному агенту
|
||||
3. Основний агент отримує повідомлення і доставляє його користувачу
|
||||
|
||||
Кожен рівень бачить announce лише від своїх безпосередніх дочірніх агентів.
|
||||
Кожен рівень бачить повідомлення лише від своїх безпосередніх дочірніх агентів.
|
||||
|
||||
Операційні рекомендації:
|
||||
|
||||
- Запускайте дочірню роботу один раз і чекайте подій завершення замість побудови циклів
|
||||
- Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів
|
||||
опитування навколо `sessions_list`, `sessions_history`, `/subagents list` або
|
||||
команд `exec` зі sleep.
|
||||
- Якщо подія завершення дочірнього агента надійшла після того, як ви вже надіслали фінальну відповідь,
|
||||
команд `exec` зі сном.
|
||||
- Якщо подія завершення дочірнього агента надходить після того, як ви вже надіслали фінальну відповідь,
|
||||
правильна подальша дія — точний тихий токен `NO_REPLY` / `no_reply`.
|
||||
|
||||
### Політика інструментів за глибиною
|
||||
|
||||
- Роль і область керування записуються в метадані сесії під час spawn. Це не дозволяє пласким або відновленим ключам сесій випадково знову отримати привілеї оркестратора.
|
||||
- Роль і область керування записуються в метадані сесії під час запуску. Це не дає плоским або відновленим ключам сесії випадково знову отримати привілеї оркестратора.
|
||||
- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми агентами. Інші інструменти сесії/системи залишаються забороненими.
|
||||
- **Глибина 1 (листок, коли `maxSpawnDepth == 1`)**: без інструментів сесії (поточна типова поведінка).
|
||||
- **Глибина 2 (worker-листок)**: без інструментів сесії — `sessions_spawn` завжди заборонено на глибині 2. Не може запускати подальших дочірніх агентів.
|
||||
- **Глибина 1 (кінцевий виконавець, коли `maxSpawnDepth == 1`)**: без інструментів сесії (поточна типова поведінка).
|
||||
- **Глибина 2 (кінцевий виконавець)**: без інструментів сесії — `sessions_spawn` завжди заборонений на глибині 2. Не може запускати подальших дочірніх агентів.
|
||||
|
||||
### Ліміт spawn для окремого агента
|
||||
### Ліміт запуску для агента
|
||||
|
||||
Кожна сесія агента (на будь-якій глибині) може мати не більше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів одночасно. Це запобігає неконтрольованому fan-out від одного оркестратора.
|
||||
Кожна сесія агента (на будь-якій глибині) може мати щонайбільше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів одночасно. Це запобігає неконтрольованому розгалуженню від одного оркестратора.
|
||||
|
||||
### Каскадна зупинка
|
||||
|
||||
Зупинка оркестратора глибини 1 автоматично зупиняє всіх його дочірніх агентів глибини 2:
|
||||
|
||||
- `/stop` в основному чаті зупиняє всіх агентів глибини 1 і каскадно — їхніх дочірніх агентів глибини 2.
|
||||
- `/subagents kill <id>` зупиняє конкретного субагента і каскадно — його дочірніх агентів.
|
||||
- `/subagents kill all` зупиняє всіх субагентів для запитувача і виконує каскадну зупинку.
|
||||
- `/stop` в основному чаті зупиняє всіх агентів глибини 1 і каскадно зупиняє їхніх дочірніх агентів глибини 2.
|
||||
- `/subagents kill <id>` зупиняє конкретного підлеглого агента і каскадно зупиняє його дочірніх агентів.
|
||||
- `/subagents kill all` зупиняє всіх підлеглих агентів для запитувача і виконує каскадну зупинку.
|
||||
|
||||
## Автентифікація
|
||||
|
||||
Автентифікація субагента визначається за **id агента**, а не за типом сесії:
|
||||
Автентифікація підлеглого агента визначається за **id агента**, а не за типом сесії:
|
||||
|
||||
- Ключ сесії субагента — `agent:<agentId>:subagent:<uuid>`.
|
||||
- Ключ сесії підлеглого агента — `agent:<agentId>:subagent:<uuid>`.
|
||||
- Сховище автентифікації завантажується з `agentDir` цього агента.
|
||||
- Профілі автентифікації основного агента об’єднуються як **резервний варіант**; профілі агента мають пріоритет над профілями основного агента у разі конфліктів.
|
||||
- Профілі автентифікації основного агента додаються як **резервні**; у разі конфліктів профілі агента мають пріоритет над профілями основного агента.
|
||||
|
||||
Примітка: об’єднання є адитивним, тому профілі основного агента завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки не підтримується.
|
||||
Примітка: об’єднання є адитивним, тому профілі основного агента завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки що не підтримується.
|
||||
|
||||
## Announce
|
||||
## Повідомлення
|
||||
|
||||
Субагенти звітують назад через крок announce:
|
||||
Підлеглі агенти звітують назад через крок повідомлення:
|
||||
|
||||
- Крок announce виконується всередині сесії субагента (а не в сесії запитувача).
|
||||
- Якщо субагент відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується.
|
||||
- Якщо останній текст помічника — це точний тихий токен `NO_REPLY` / `no_reply`,
|
||||
вивід announce пригнічується, навіть якщо раніше був видимий прогрес.
|
||||
- Інакше доставка залежить від глибини запитувача:
|
||||
- сесії запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
|
||||
- вкладені сесії субагента-запитувача отримують внутрішнє подальше вбудовування (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії
|
||||
- якщо вкладена сесія субагента-запитувача зникла, OpenClaw, якщо можливо, повертається до запитувача цієї сесії
|
||||
- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/треду і перевизначення hook, а потім заповнює відсутні поля цілі каналу із збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли походження завершення ідентифікує лише канал.
|
||||
- Агрегація завершення дочірніх агентів обмежується поточним запуском запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виходів дочірніх агентів з попередніх запусків у поточний announce.
|
||||
- Відповіді announce зберігають маршрутизацію треду/теми, коли це доступно в адаптерах каналів.
|
||||
- Контекст announce нормалізується до стабільного внутрішнього блоку подій:
|
||||
- Крок повідомлення виконується всередині сесії підлеглого агента (а не сесії запитувача).
|
||||
- Якщо підлеглий агент відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується.
|
||||
- Якщо останній текст помічника є точним тихим токеном `NO_REPLY` / `no_reply`,
|
||||
вивід повідомлення пригнічується, навіть якщо раніше був видимий прогрес.
|
||||
- В іншому разі доставка залежить від глибини запитувача:
|
||||
- для запитувачів верхнього рівня використовується подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
|
||||
- вкладені сесії підлеглих агентів запитувача отримують внутрішнє подальше впровадження (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії
|
||||
- якщо вкладена сесія підлеглого агента запитувача вже відсутня, OpenClaw за можливості повертається до запитувача цієї сесії
|
||||
- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target із збереженого маршруту сесії запитувача. Це зберігає завершення в правильному чаті/темі, навіть коли джерело завершення вказує лише канал.
|
||||
- Агрегація завершень дочірніх агентів обмежується поточним сеансом запитувача під час побудови вкладених результатів завершення, що запобігає потраплянню застарілих виводів дочірніх агентів із попередніх сеансів у поточне повідомлення.
|
||||
- Відповіді-повідомлення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.
|
||||
- Контекст повідомлення нормалізується до стабільного внутрішнього блоку події:
|
||||
- джерело (`subagent` або `cron`)
|
||||
- ключ/id дочірньої сесії
|
||||
- тип announce + мітка завдання
|
||||
- рядок стану, отриманий із сигналів результату runtime (`success`, `error`, `timeout` або `unknown`)
|
||||
- вміст результату, вибраний з останнього видимого тексту помічника, інакше — очищений останній текст `tool`/`toolResult`; завершені з помилкою фінальні запуски повідомляють про стан помилки без повторного відтворення захопленого тексту відповіді
|
||||
- інструкція для подальших дій, яка описує, коли потрібно відповісти, а коли залишитися тихим
|
||||
- `Status` не виводиться з результату моделі; він надходить із сигналів результату runtime.
|
||||
- У разі тайм-ауту, якщо дочірній агент встиг дійти лише до викликів інструментів, announce може згорнути цю історію до короткого зведення часткового прогресу замість відтворення сирого виводу інструментів.
|
||||
- тип повідомлення + мітка завдання
|
||||
- рядок статусу, похідний від результату виконання (`success`, `error`, `timeout` або `unknown`)
|
||||
- вміст результату, вибраний з останнього видимого тексту помічника, або, якщо його немає, очищений останній текст `tool`/`toolResult`; термінальні невдалі сеанси повідомляють про статус помилки без повторення захопленого тексту відповіді
|
||||
- подальша інструкція, яка описує, коли відповідати, а коли зберігати тишу
|
||||
- `Status` не виводиться з результату моделі; він походить із сигналів результату виконання.
|
||||
- У разі тайм-ауту, якщо дочірній агент встиг пройти лише виклики інструментів, повідомлення може згорнути цю історію в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів.
|
||||
|
||||
Payload announce містить рядок статистики наприкінці (навіть якщо він загорнутий):
|
||||
Корисне навантаження повідомлень містить рядок статистики наприкінці (навіть якщо воно обгорнуте):
|
||||
|
||||
- Runtime (наприклад, `runtime 5m12s`)
|
||||
- Час виконання (наприклад, `runtime 5m12s`)
|
||||
- Використання токенів (вхідні/вихідні/загалом)
|
||||
- Оцінена вартість, коли налаштовано ціноутворення моделей (`models.providers.*.models[].cost`)
|
||||
- Оцінена вартість, якщо налаштовано ціни моделей (`models.providers.*.models[].cost`)
|
||||
- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або перевірити файл на диску)
|
||||
- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача мають бути переписані звичайним голосом помічника.
|
||||
- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом помічника.
|
||||
|
||||
`sessions_history` — безпечніший шлях оркестрації:
|
||||
|
||||
- відновлення помічника спочатку нормалізується:
|
||||
- thinking-теги прибираються
|
||||
- блоки шаблонів `<relevant-memories>` / `<relevant_memories>` прибираються
|
||||
- блоки XML-пейлоаду викликів інструментів у відкритому тексті, такі як `<tool_call>...</tool_call>`,
|
||||
- історія помічника спочатку нормалізується:
|
||||
- теги thinking видаляються
|
||||
- блоки каркаса `<relevant-memories>` / `<relevant_memories>` видаляються
|
||||
- блоки XML-корисного навантаження plain-text викликів інструментів, як-от `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` і
|
||||
`<function_calls>...</function_calls>`, прибираються, включно з обрізаними
|
||||
payload, які так і не закрилися коректно
|
||||
- понижений шаблон викликів/результатів інструментів та маркери історичного контексту прибираються
|
||||
- витеклі керівні токени моделі, такі як `<|assistant|>`, інші ASCII-токени
|
||||
`<|...|>` та повноширинні варіанти `<｜...｜>`, прибираються
|
||||
- некоректний XML викликів інструментів MiniMax прибирається
|
||||
`<function_calls>...</function_calls>`, видаляються, включно з обрізаними
|
||||
корисними навантаженнями, які так і не закрилися коректно
|
||||
- знижені до тексту каркаси викликів/результатів інструментів і маркери історичного контексту видаляються
|
||||
- витеклі службові токени моделі, як-от `<|assistant|>`, інші ASCII
|
||||
токени `<|...|>` і їхні full-width варіанти `<｜...｜>`, видаляються
|
||||
- некоректний XML викликів інструментів MiniMax видаляється
|
||||
- текст, схожий на облікові дані/токени, редагується
|
||||
- довгі блоки можуть обрізатися
|
||||
- у дуже великих історіях можуть відкидатися старіші рядки або надто великий рядок може бути замінено на
|
||||
- довгі блоки можуть бути обрізані
|
||||
- у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на
|
||||
`[sessions_history omitted: message too large]`
|
||||
- перевірка сирого транскрипту на диску — це резервний варіант, коли вам потрібен повний побайтний транскрипт
|
||||
|
||||
## Політика інструментів (інструменти субагента)
|
||||
## Політика інструментів (інструменти підлеглих агентів)
|
||||
|
||||
За замовчуванням субагенти отримують **усі інструменти, крім інструментів сесії** та системних інструментів:
|
||||
Типово підлеглі агенти отримують **усі інструменти, крім інструментів сесії** та системних інструментів:
|
||||
|
||||
- `sessions_list`
|
||||
- `sessions_history`
|
||||
- `sessions_send`
|
||||
- `sessions_spawn`
|
||||
|
||||
`sessions_history` і тут залишається обмеженим, очищеним поданням для відновлення; це
|
||||
не сирий дамп транскрипту.
|
||||
Тут `sessions_history` також залишається обмеженим, очищеним поданням історії; це не
|
||||
сирий дамп транскрипту.
|
||||
|
||||
Коли `maxSpawnDepth >= 2`, субагенти-оркестратори глибини 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб могли керувати своїми дочірніми агентами.
|
||||
Коли `maxSpawnDepth >= 2`, підлеглі агенти-оркестратори глибини 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми агентами.
|
||||
|
||||
Перевизначення через конфігурацію:
|
||||
|
||||
@ -322,7 +335,7 @@ Payload announce містить рядок статистики наприкін
|
||||
tools: {
|
||||
// deny має пріоритет
|
||||
deny: ["gateway", "cron"],
|
||||
// якщо задано allow, він стає списком лише дозволених (deny усе одно має пріоритет)
|
||||
// якщо встановлено allow, список стає лише allow-only (deny усе одно має пріоритет)
|
||||
// allow: ["read", "exec", "process"]
|
||||
},
|
||||
},
|
||||
@ -330,29 +343,29 @@ Payload announce містить рядок статистики наприкін
|
||||
}
|
||||
```
|
||||
|
||||
## Одночасність
|
||||
## Паралельність
|
||||
|
||||
Субагенти використовують окрему внутрішньопроцесну смугу черги:
|
||||
Підлеглі агенти використовують окрему внутрішньопроцесну смугу черги:
|
||||
|
||||
- Назва смуги: `subagent`
|
||||
- Одночасність: `agents.defaults.subagents.maxConcurrent` (типово `8`)
|
||||
- Паралельність: `agents.defaults.subagents.maxConcurrent` (типово `8`)
|
||||
|
||||
## Зупинка
|
||||
|
||||
- Надсилання `/stop` у чаті запитувача перериває сесію запитувача й зупиняє всі активні запуски субагентів, породжені нею, з каскадним поширенням на вкладених дочірніх агентів.
|
||||
- `/subagents kill <id>` зупиняє конкретного субагента і каскадно — його дочірніх агентів.
|
||||
- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні сеанси підлеглих агентів, запущені з неї, з каскадним поширенням на вкладених дочірніх агентів.
|
||||
- `/subagents kill <id>` зупиняє конкретного підлеглого агента і каскадно зупиняє його дочірніх агентів.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- Announce субагента працює в режимі **best-effort**. Якщо gateway перезапуститься, незавершена робота з «announce back» буде втрачена.
|
||||
- Субагенти все ще спільно використовують ресурси того самого процесу gateway; розглядайте `maxConcurrent` як запобіжний клапан.
|
||||
- `sessions_spawn` завжди неблокувальний: він одразу повертає `{ status: "accepted", runId, childSessionKey }`.
|
||||
- Контекст субагента вбудовує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`).
|
||||
- Максимальна глибина вкладеності — 5 (діапазон `maxSpawnDepth`: 1–5). Для більшості сценаріїв рекомендується глибина 2.
|
||||
- Повідомлення підлеглого агента — у режимі **best-effort**. Якщо Gateway перезапуститься, незавершена робота з «повідомлення назад» буде втрачена.
|
||||
- Підлеглі агенти все ще спільно використовують ресурси того самого процесу Gateway; розглядайте `maxConcurrent` як запобіжник.
|
||||
- `sessions_spawn` завжди не блокує виконання: він одразу повертає `{ status: "accepted", runId, childSessionKey }`.
|
||||
- Контекст підлеглого агента впроваджує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`).
|
||||
- Максимальна глибина вкладеності — 5 (`maxSpawnDepth` у діапазоні 1–5). Для більшості випадків використання рекомендується глибина 2.
|
||||
- `maxChildrenPerAgent` обмежує кількість активних дочірніх агентів на сесію (типово: 5, діапазон: 1–20).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [ACP agents](/uk/tools/acp-agents)
|
||||
- [Інструменти пісочниці мультиагентності](/uk/tools/multi-agent-sandbox-tools)
|
||||
- [Надсилання агентом](/uk/tools/agent-send)
|
||||
- [Інструменти пісочниці для мультиагентної роботи](/uk/tools/multi-agent-sandbox-tools)
|
||||
- [Надсилання агенту](/uk/tools/agent-send)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user