chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
dbd7e38a11
commit
64ae379100
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Зміна маршрутизації каналів або поведінки вхідних повідомлень
|
||||
- Зміна маршрутизації каналу або поведінки вхідних повідомлень
|
||||
summary: Правила маршрутизації для кожного каналу (WhatsApp, Telegram, Discord, Slack) і спільний контекст
|
||||
title: Маршрутизація каналів
|
||||
title: Маршрутизація каналу
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T17:57:18Z"
|
||||
generated_at: "2026-04-22T22:50:17Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537
|
||||
source_hash: 3296ab8428cb815d0cc297d0c6e7479c5554ec45e1d90eef89a68833f5979d8d
|
||||
source_path: channels/channel-routing.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,26 +19,30 @@ OpenClaw маршрутизує відповіді **назад до канал
|
||||
## Ключові терміни
|
||||
|
||||
- **Канал**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, а також канали розширень. `webchat` — це внутрішній канал інтерфейсу WebChat і не є налаштовуваним вихідним каналом.
|
||||
- **AccountId**: екземпляр облікового запису для каналу (коли підтримується).
|
||||
- Необов’язковий типовий обліковий запис каналу: `channels.<channel>.defaultAccount` визначає, який обліковий запис використовується, коли вихідний шлях не задає `accountId`.
|
||||
- У конфігураціях із кількома обліковими записами задайте явний типовий обліковий запис (`defaultAccount` або `accounts.default`), коли налаштовано два або більше облікових записів. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису.
|
||||
- **AgentId**: ізольований робочий простір + сховище сесій («мозок»).
|
||||
- **SessionKey**: ключ контейнера, який використовується для збереження контексту та керування паралельністю.
|
||||
- **AccountId**: екземпляр облікового запису для каналу (якщо підтримується).
|
||||
- Необов’язковий обліковий запис каналу за замовчуванням: `channels.<channel>.defaultAccount` визначає, який обліковий запис використовується, коли вихідний шлях не вказує `accountId`.
|
||||
- У конфігураціях із кількома обліковими записами встановіть явне значення за замовчуванням (`defaultAccount` або `accounts.default`), коли налаштовано два або більше облікових записів. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису.
|
||||
- **AgentId**: ізольоване робоче середовище + сховище сесій («мозок»).
|
||||
- **SessionKey**: ключ бакета, який використовується для зберігання контексту та керування конкурентністю.
|
||||
|
||||
## Форми ключів сесії (приклади)
|
||||
## Форми ключів сесій (приклади)
|
||||
|
||||
Особисті повідомлення згортаються до **основної** сесії агента:
|
||||
Більшість прямих повідомлень зводяться до **основної** сесії агента:
|
||||
|
||||
- `agent:<agentId>:<mainKey>` (типово: `agent:main:main`)
|
||||
- `agent:<agentId>:<mainKey>` (за замовчуванням: `agent:main:main`)
|
||||
|
||||
Групи та канали залишаються ізольованими для кожного каналу:
|
||||
Прямі повідомлення Telegram-бота ізолюються за обліковим записом бота та відправником, навіть коли `session.dmScope` дорівнює `main`, щоб рішення щодо sandbox і політики інструментів могли розрізняти DM, що походять із каналу, від основної сесії агента:
|
||||
|
||||
- `agent:<agentId>:telegram:<accountId>:direct:<senderId>`
|
||||
|
||||
Групи й канали залишаються ізольованими для кожного каналу:
|
||||
|
||||
- Групи: `agent:<agentId>:<channel>:group:<id>`
|
||||
- Канали/кімнати: `agent:<agentId>:<channel>:channel:<id>`
|
||||
|
||||
Треди:
|
||||
Потоки:
|
||||
|
||||
- Треди Slack/Discord додають `:thread:<threadId>` до базового ключа.
|
||||
- Потоки Slack/Discord додають `:thread:<threadId>` до базового ключа.
|
||||
- Теми форуму Telegram вбудовують `:topic:<topicId>` у ключ групи.
|
||||
|
||||
Приклади:
|
||||
@ -46,15 +50,15 @@ OpenClaw маршрутизує відповіді **назад до канал
|
||||
- `agent:main:telegram:group:-1001234567890:topic:42`
|
||||
- `agent:main:discord:channel:123456:thread:987654`
|
||||
|
||||
## Закріплення основного маршруту особистих повідомлень
|
||||
## Закріплення маршруту основних DM
|
||||
|
||||
Коли `session.dmScope` має значення `main`, особисті повідомлення можуть використовувати спільну основну сесію.
|
||||
Щоб `lastRoute` сесії не перезаписувався особистими повідомленнями не від власника,
|
||||
OpenClaw визначає закріпленого власника з `allowFrom`, якщо виконуються всі ці умови:
|
||||
Коли `session.dmScope` дорівнює `main`, прямі повідомлення можуть використовувати одну спільну основну сесію.
|
||||
Щоб запобігти перезапису `lastRoute` сесії прямими повідомленнями від не-власника,
|
||||
OpenClaw визначає закріпленого власника з `allowFrom`, якщо виконуються всі такі умови:
|
||||
|
||||
- `allowFrom` має рівно один запис без wildcard.
|
||||
- Цей запис можна нормалізувати до конкретного ідентифікатора відправника для цього каналу.
|
||||
- Відправник вхідного особистого повідомлення не збігається з цим закріпленим власником.
|
||||
- `allowFrom` містить рівно один запис без wildcard.
|
||||
- Запис можна нормалізувати до конкретного ID відправника для цього каналу.
|
||||
- Відправник вхідного DM не збігається з цим закріпленим власником.
|
||||
|
||||
У разі такої невідповідності OpenClaw усе одно записує метадані вхідної сесії, але
|
||||
пропускає оновлення `lastRoute` основної сесії.
|
||||
@ -63,22 +67,22 @@ OpenClaw визначає закріпленого власника з `allowFro
|
||||
|
||||
Маршрутизація вибирає **одного агента** для кожного вхідного повідомлення:
|
||||
|
||||
1. **Точний збіг вузла** (`bindings` з `peer.kind` + `peer.id`).
|
||||
2. **Збіг батьківського вузла** (успадкування треду).
|
||||
3. **Збіг сервера + ролей** (Discord) через `guildId` + `roles`.
|
||||
4. **Збіг сервера** (Discord) через `guildId`.
|
||||
5. **Збіг команди** (Slack) через `teamId`.
|
||||
1. **Точний збіг peer** (`bindings` з `peer.kind` + `peer.id`).
|
||||
2. **Збіг батьківського peer** (успадкування потоку).
|
||||
3. **Збіг guild + ролей** (Discord) через `guildId` + `roles`.
|
||||
4. **Збіг guild** (Discord) через `guildId`.
|
||||
5. **Збіг team** (Slack) через `teamId`.
|
||||
6. **Збіг облікового запису** (`accountId` у каналі).
|
||||
7. **Збіг каналу** (будь-який обліковий запис у цьому каналі, `accountId: "*"`).
|
||||
8. **Типовий агент** (`agents.list[].default`, інакше перший запис списку, резервно — `main`).
|
||||
8. **Агент за замовчуванням** (`agents.list[].default`, інакше перший запис у списку, резервно — `main`).
|
||||
|
||||
Коли прив’язка містить кілька полів збігу (`peer`, `guildId`, `teamId`, `roles`), **усі вказані поля мають збігатися**, щоб ця прив’язка застосувалася.
|
||||
Коли binding містить кілька полів збігу (`peer`, `guildId`, `teamId`, `roles`), **усі надані поля мають збігатися**, щоб цей binding було застосовано.
|
||||
|
||||
Вибраний агент визначає, який робочий простір і сховище сесій використовуються.
|
||||
Вибраний агент визначає, яке робоче середовище та сховище сесій використовуються.
|
||||
|
||||
## Broadcast groups (запуск кількох агентів)
|
||||
## Групи широкомовлення (запуск кількох агентів)
|
||||
|
||||
Broadcast groups дають змогу запускати **кількох агентів** для одного й того самого вузла **коли OpenClaw зазвичай відповідає** (наприклад, у групах WhatsApp після проходження згадки/активаційного шлюзу).
|
||||
Групи широкомовлення дають змогу запускати **кількох агентів** для одного й того самого peer **коли OpenClaw зазвичай відповідав би** (наприклад, у групах WhatsApp після згадки/активаційного фільтра).
|
||||
|
||||
Конфігурація:
|
||||
|
||||
@ -92,19 +96,19 @@ Broadcast groups дають змогу запускати **кількох аг
|
||||
}
|
||||
```
|
||||
|
||||
Див.: [Broadcast Groups](/channels/broadcast-groups).
|
||||
Див.: [Групи широкомовлення](/uk/channels/broadcast-groups).
|
||||
|
||||
## Огляд конфігурації
|
||||
|
||||
- `agents.list`: іменовані визначення агентів (робочий простір, модель тощо).
|
||||
- `bindings`: зіставлення вхідних каналів/облікових записів/вузлів з агентами.
|
||||
- `agents.list`: іменовані визначення агентів (робоче середовище, модель тощо).
|
||||
- `bindings`: зіставляє вхідні канали/облікові записи/peer з агентами.
|
||||
|
||||
Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
|
||||
list: [{ id: "support", name: "Підтримка", workspace: "~/.openclaw/workspace-support" }],
|
||||
},
|
||||
bindings: [
|
||||
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
|
||||
@ -115,29 +119,29 @@ Broadcast groups дають змогу запускати **кількох аг
|
||||
|
||||
## Зберігання сесій
|
||||
|
||||
Сховища сесій розміщуються в каталозі стану (типово `~/.openclaw`):
|
||||
Сховища сесій розміщуються в каталозі стану (за замовчуванням `~/.openclaw`):
|
||||
|
||||
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
|
||||
- Транскрипти JSONL розміщуються поруч зі сховищем
|
||||
- JSONL-транскрипти зберігаються поруч зі сховищем
|
||||
|
||||
Ви можете перевизначити шлях до сховища через `session.store` і шаблонізацію `{agentId}`.
|
||||
|
||||
Виявлення сесій Gateway і ACP також сканує дискові сховища агентів у типовому
|
||||
корені `agents/` і в коренях `session.store`, побудованих за шаблоном. Виявлені
|
||||
сховища мають залишатися в межах цього обчисленого кореня агента та використовувати звичайний файл
|
||||
`sessions.json`. Символічні посилання та шляхи поза коренем ігноруються.
|
||||
Gateway та ACP під час виявлення сесій також сканують дискові сховища агентів під
|
||||
коренем `agents/` за замовчуванням і під коренями `session.store` з шаблонами. Виявлені
|
||||
сховища мають залишатися в межах цього обчисленого кореня агента й використовувати звичайний
|
||||
файл `sessions.json`. Символічні посилання та шляхи поза коренем ігноруються.
|
||||
|
||||
## Поведінка WebChat
|
||||
|
||||
WebChat підключається до **вибраного агента** і типово використовує основну
|
||||
сесію агента. Через це WebChat дає змогу бачити міжканальний контекст для цього
|
||||
агента в одному місці.
|
||||
WebChat прив’язується до **вибраного агента** і за замовчуванням використовує
|
||||
основну сесію агента. Завдяки цьому WebChat дає змогу бачити міжканальний контекст
|
||||
для цього агента в одному місці.
|
||||
|
||||
## Контекст відповіді
|
||||
|
||||
Вхідні відповіді включають:
|
||||
Вхідні відповіді містять:
|
||||
|
||||
- `ReplyToId`, `ReplyToBody` і `ReplyToSender`, коли доступні.
|
||||
- `ReplyToId`, `ReplyToBody` і `ReplyToSender`, якщо доступні.
|
||||
- Цитований контекст додається до `Body` як блок `[Replying to ...]`.
|
||||
|
||||
Це узгоджено в усіх каналах.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -2,32 +2,37 @@
|
||||
read_when:
|
||||
- Налаштування OpenClaw уперше
|
||||
- Шукаєте поширені шаблони конфігурації
|
||||
- Перехід до певних розділів конфігурації
|
||||
- Перехід до конкретних розділів конфігурації
|
||||
summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник'
|
||||
title: Конфігурація
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T22:37:31Z"
|
||||
generated_at: "2026-04-22T22:50:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 966f6a6500fc2f649ee4612404092fd70305065544807c1d8bbc80aa840f9e97
|
||||
source_hash: 7b8fccabd04e075f3a59c3b94fe11eca19ddffa2e405d76a9fe92be38ea5a8da
|
||||
source_path: gateway/configuration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Конфігурація
|
||||
|
||||
OpenClaw зчитує необов’язкову конфігурацію <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
|
||||
OpenClaw зчитує необов’язкову конфігурацію <Tooltip tip="JSON5 підтримує коментарі та завертальні коми">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
|
||||
Активний шлях до конфігурації має вказувати на звичайний файл. Схеми
|
||||
`openclaw.json` із символічними посиланнями не підтримуються для записів,
|
||||
якими керує OpenClaw; атомарний запис може замінити шлях замість збереження
|
||||
символічного посилання. Якщо ви зберігаєте конфігурацію поза типовим
|
||||
каталогом стану, вкажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
|
||||
|
||||
Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію:
|
||||
|
||||
- Підключити канали та керувати тим, хто може надсилати повідомлення боту
|
||||
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, hooks)
|
||||
- Тонко налаштувати сесії, медіа, мережу або UI
|
||||
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks)
|
||||
- Налаштувати сесії, медіа, мережу або UI
|
||||
|
||||
Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля.
|
||||
|
||||
<Tip>
|
||||
**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання.
|
||||
**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання та вставлення.
|
||||
</Tip>
|
||||
|
||||
## Мінімальна конфігурація
|
||||
@ -58,11 +63,12 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
|
||||
</Tab>
|
||||
<Tab title="Control UI">
|
||||
Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**.
|
||||
Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів
|
||||
`title` / `description`, а також схемами plugin і каналів, коли вони
|
||||
доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих
|
||||
UI та інших інструментів Gateway також надає `config.schema.lookup`, щоб
|
||||
отримати один вузол схеми для вказаного шляху разом зі зведеннями про безпосередніх дочірніх елементів.
|
||||
Control UI відображає форму на основі живої схеми конфігурації, включно з
|
||||
метаданими документації полів `title` / `description`, а також схемами plugin і каналів,
|
||||
коли вони доступні, з редактором **Raw JSON** як запасним варіантом. Для
|
||||
деталізованих UI та інших інструментів gateway також надає `config.schema.lookup` для
|
||||
отримання одного вузла схеми, обмеженого шляхом, разом із підсумками
|
||||
безпосередніх дочірніх елементів.
|
||||
</Tab>
|
||||
<Tab title="Пряме редагування">
|
||||
Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
|
||||
@ -72,60 +78,61 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
|
||||
## Сувора валідація
|
||||
|
||||
<Warning>
|
||||
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema.
|
||||
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призведуть до того, що Gateway **відмовиться запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо інструментів схеми:
|
||||
Нотатки щодо інструментів схем:
|
||||
|
||||
- `openclaw config schema` виводить те саме сімейство JSON Schema, яке використовується в Control UI
|
||||
і для валідації конфігурації.
|
||||
- Вважайте цей вивід схеми канонічним машиночитним контрактом для
|
||||
- `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI
|
||||
і валідація конфігурації.
|
||||
- Розглядайте цей вивід схеми як канонічний машиночитаний контракт для
|
||||
`openclaw.json`; цей огляд і довідник з конфігурації його узагальнюють.
|
||||
- Значення полів `title` і `description` переносяться до виводу схеми для
|
||||
редакторів і інструментів форм.
|
||||
- Вкладені об’єкти, записи wildcard (`*`) та елементи масиву (`[]`) успадковують ті самі
|
||||
метадані документації там, де існує відповідна документація поля.
|
||||
- Значення полів `title` і `description` переносяться у вивід схеми для
|
||||
редакторів і інструментів побудови форм.
|
||||
- Вкладені об’єкти, записи з шаблоном (`*`) і елементи масиву (`[]`) успадковують ті самі
|
||||
метадані документації, де існує відповідна документація поля.
|
||||
- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі
|
||||
метадані документації, тож варіанти union/intersection зберігають ту саму довідку полів.
|
||||
- `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим
|
||||
вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження
|
||||
та подібні поля валідації), відповідні метадані UI-підказок і зведення про безпосередніх дочірніх елементів
|
||||
для інструментів детального перегляду.
|
||||
- Схеми plugin/каналів під час виконання об’єднуються, коли gateway може завантажити
|
||||
вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові обмеження
|
||||
та схожі поля валідації), відповідними метаданими підказок UI і підсумками
|
||||
безпосередніх дочірніх елементів для інструментів деталізації.
|
||||
- Схеми runtime plugin/каналів об’єднуються, коли gateway може завантажити
|
||||
поточний реєстр маніфестів.
|
||||
- `pnpm config:docs:check` виявляє розходження між базовими артефактами конфігурації для документації
|
||||
і поточною поверхнею схеми.
|
||||
- `pnpm config:docs:check` виявляє розбіжності між артефактами базових конфігурацій
|
||||
для документації та поточною поверхнею схеми.
|
||||
|
||||
Коли валідація не проходить:
|
||||
|
||||
- Gateway не запускається
|
||||
- Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
|
||||
- Запустіть `openclaw doctor`, щоб побачити точні проблеми
|
||||
- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
|
||||
- Виконайте `openclaw doctor`, щоб побачити точні проблеми
|
||||
- Виконайте `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
|
||||
|
||||
Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо
|
||||
`openclaw.json` пізніше змінюється поза OpenClaw і більше не проходить валідацію, під час запуску
|
||||
та гарячого перезавантаження зламаний файл зберігається як `.clobbered.*`-знімок із часовою позначкою,
|
||||
відновлюється остання відома коректна копія, а в журнал записується помітне попередження з причиною відновлення.
|
||||
Відновлення під час читання на старті також вважає критичними ознаками пошкодження різке зменшення розміру,
|
||||
відсутні метадані конфігурації та відсутність `gateway.mode`, коли в останній відомій коректній
|
||||
копії ці поля були.
|
||||
Якщо перед інакше коректною конфігурацією JSON випадково додається рядок статусу/журналу,
|
||||
запуск gateway і `openclaw doctor --fix` можуть прибрати цей префікс,
|
||||
зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим
|
||||
JSON.
|
||||
Наступний хід головного агента також отримує попередження системної події про те, що
|
||||
конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу останньої відомої коректної копії
|
||||
оновлюється після валідованого запуску і після прийнятих гарячих перезавантажень, включно з
|
||||
записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим
|
||||
записом. Підвищення пропускається, коли кандидат містить замасковані заповнювачі секретів,
|
||||
такі як `***` або скорочені значення токенів.
|
||||
Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо
|
||||
`openclaw.json` пізніше змінено поза OpenClaw і він більше не проходить валідацію, під час запуску
|
||||
та гарячого перезавантаження пошкоджений файл зберігається як знімок `.clobbered.*` із часовою
|
||||
міткою, відновлюється остання відома справна копія, а в журнали записується
|
||||
помітне попередження з причиною відновлення. Відновлення під час читання на
|
||||
запуску також розглядає різке зменшення розміру, відсутність метаданих
|
||||
конфігурації та відсутність `gateway.mode` як критичні ознаки пошкодження, якщо
|
||||
в останній відомій справній копії ці поля були.
|
||||
Якщо рядок статусу/журналу випадково додається на початку перед інакше
|
||||
коректною JSON-конфігурацією, запуск gateway і `openclaw doctor --fix` можуть
|
||||
видалити цей префікс, зберегти забруднений файл як `.clobbered.*` і продовжити
|
||||
роботу з відновленим JSON.
|
||||
Наступний хід основного агента також отримує попередження про системну подію, яке повідомляє,
|
||||
що конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу
|
||||
останньої відомої справної копії оновлюється після валідованого запуску та після прийнятих
|
||||
гарячих перезавантажень, включно із записами конфігурації, якими керує OpenClaw, коли хеш
|
||||
збереженого файла все ще збігається з прийнятим записом. Підвищення статусу пропускається,
|
||||
якщо кандидат містить замасковані заповнювачі секретів, такі як `***` або скорочені значення токенів.
|
||||
|
||||
## Поширені завдання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Налаштувати канал (WhatsApp, Telegram, Discord тощо)">
|
||||
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Дивіться окрему сторінку каналу для кроків налаштування:
|
||||
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Перегляньте окрему сторінку каналу для кроків налаштування:
|
||||
|
||||
- [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/uk/channels/telegram) — `channels.telegram`
|
||||
@ -138,7 +145,7 @@ JSON.
|
||||
- [iMessage](/uk/channels/imessage) — `channels.imessage`
|
||||
- [Mattermost](/uk/channels/mattermost) — `channels.mattermost`
|
||||
|
||||
Усі канали використовують однаковий шаблон політики DM:
|
||||
Усі канали мають спільний шаблон політики DM:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -156,7 +163,7 @@ JSON.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вибрати та налаштувати моделі">
|
||||
Задайте основну модель і необов’язкові резервні варіанти:
|
||||
Установіть основну модель і необов’язкові резервні:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -176,30 +183,30 @@ JSON.
|
||||
```
|
||||
|
||||
- `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`.
|
||||
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видаляють записи, відхиляються, якщо не передати `--replace`.
|
||||
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо не передати `--replace`.
|
||||
- Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`).
|
||||
- `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у transcript/tool (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів.
|
||||
- Дивіться [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації авторизації та поведінки резервних моделей.
|
||||
- Для власних/self-hosted provider див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику.
|
||||
- `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскрипті/інструментах (типове значення `1200`); нижчі значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю скриншотів.
|
||||
- Перегляньте [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover), щоб дізнатися про ротацію автентифікації та поведінку резервного перемикання.
|
||||
- Для користувацьких/self-hosted provider перегляньте [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Керувати тим, хто може надсилати повідомлення боту">
|
||||
Доступ до DM керується окремо для кожного каналу через `dmPolicy`:
|
||||
|
||||
- `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження
|
||||
- `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження
|
||||
- `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow)
|
||||
- `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`)
|
||||
- `"disabled"`: ігнорувати всі DM
|
||||
|
||||
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу.
|
||||
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або списки дозволених, специфічні для каналу.
|
||||
|
||||
Дивіться [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу.
|
||||
Перегляньте [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access), щоб дізнатися деталі для кожного каналу.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати фільтрацію згадок у групових чатах">
|
||||
Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента:
|
||||
<Accordion title="Налаштувати gating згадувань у груповому чаті">
|
||||
Для групових повідомлень типовим є режим **вимагати згадування**. Налаштуйте шаблони для кожного агента:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -221,13 +228,13 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
- **Згадки в метаданих**: нативні @-згадки (tap-to-mention у WhatsApp, @bot у Telegram тощо)
|
||||
- **Згадування в метаданих**: нативні @-згадування (WhatsApp tap-to-mention, Telegram @bot тощо)
|
||||
- **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns`
|
||||
- Дивіться [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для по-канальних перевизначень і режиму self-chat.
|
||||
- Перегляньте [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating), щоб дізнатися про перевизначення для окремих каналів і режим self-chat.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмежити Skills для агента">
|
||||
<Accordion title="Обмежити Skills для кожного агента">
|
||||
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних
|
||||
агентів через `agents.list[].skills`:
|
||||
|
||||
@ -238,18 +245,18 @@ JSON.
|
||||
skills: ["github", "weather"],
|
||||
},
|
||||
list: [
|
||||
{ id: "writer" }, // успадковує github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням
|
||||
{ id: "locked-down", skills: [] }, // без Skills
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- Не вказуйте `agents.defaults.skills`, якщо типово Skills не мають бути обмежені.
|
||||
- Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
|
||||
- Встановіть `agents.list[].skills: []`, щоб не дозволити жодних Skills.
|
||||
- Дивіться [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і
|
||||
- Опустіть `agents.defaults.skills`, щоб за замовчуванням Skills не були обмежені.
|
||||
- Опустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
|
||||
- Установіть `agents.list[].skills: []`, щоб не використовувати Skills.
|
||||
- Перегляньте [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і
|
||||
[Довідник з конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills).
|
||||
|
||||
</Accordion>
|
||||
@ -277,10 +284,10 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
- Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски через моніторинг стану.
|
||||
- `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки.
|
||||
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора.
|
||||
- Дивіться [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану.
|
||||
- `channelStaleEventThresholdMinutes` має бути більшим або рівним інтервалу перевірки.
|
||||
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального моніторингу.
|
||||
- Перегляньте [Health Checks](/uk/gateway/health) для операційного налагодження і [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -290,7 +297,7 @@ JSON.
|
||||
```json5
|
||||
{
|
||||
session: {
|
||||
dmScope: "per-channel-peer", // рекомендовано для багатьох користувачів
|
||||
dmScope: "per-channel-peer", // recommended for multi-user
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24,
|
||||
@ -305,15 +312,15 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
- `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до thread (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
|
||||
- Дивіться [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання.
|
||||
- Дивіться [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів.
|
||||
- `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до тредів (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
|
||||
- Перегляньте [Керування сесіями](/uk/concepts/session), щоб дізнатися про область дії, зв’язки ідентичностей і політику надсилання.
|
||||
- Перегляньте [повний довідник](/uk/gateway/configuration-reference#session), щоб побачити всі поля.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнути ізоляцію">
|
||||
Запускайте сесії агентів в ізольованих runtime ізолятора:
|
||||
Запускайте сесії агентів в ізольованих runtime ізоляції:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -330,14 +337,14 @@ JSON.
|
||||
|
||||
Спочатку зберіть образ: `scripts/sandbox-setup.sh`
|
||||
|
||||
Дивіться [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів.
|
||||
Перегляньте [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнути relay-backed push для офіційних збірок iOS">
|
||||
Relay-backed push налаштовується в `openclaw.json`.
|
||||
<Accordion title="Увімкнути push через relay для офіційних збірок iOS">
|
||||
Push через relay налаштовується в `openclaw.json`.
|
||||
|
||||
Укажіть це в конфігурації gateway:
|
||||
Установіть це в конфігурації gateway:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -355,7 +362,7 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
Еквівалент через CLI:
|
||||
Еквівалент у CLI:
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
|
||||
@ -363,31 +370,31 @@ JSON.
|
||||
|
||||
Що це робить:
|
||||
|
||||
- Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay.
|
||||
- Використовує grant на надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання.
|
||||
- Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію.
|
||||
- Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційно розповсюджених збірок, які зареєструвалися через relay.
|
||||
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до одного й того самого розгортання relay.
|
||||
- Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для перепідключення через зовнішній relay.
|
||||
- Використовує право надсилання, обмежене реєстрацією, яке пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання.
|
||||
- Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою був спарений застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію.
|
||||
- Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовуються лише до офіційно розповсюджуваних збірок, які зареєструвалися через relay.
|
||||
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay.
|
||||
|
||||
Повний потік end-to-end:
|
||||
Повний потік роботи:
|
||||
|
||||
1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay.
|
||||
2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway.
|
||||
3. Спарте застосунок iOS із gateway і дочекайтеся підключення як node-, так і operator-сесій.
|
||||
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway.
|
||||
5. Gateway зберігає relay handle і send grant, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення.
|
||||
3. Спарте застосунок iOS із gateway і дозвольте підключитися як сесіям node, так і сесіям оператора.
|
||||
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay до спареного gateway.
|
||||
5. Gateway зберігає relay handle і право надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для перепідключення.
|
||||
|
||||
Операційні примітки:
|
||||
|
||||
- Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway.
|
||||
- Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює кешовану relay-реєстрацію замість повторного використання старого relay-origin.
|
||||
- Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway.
|
||||
- Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює кешовану реєстрацію relay замість повторного використання старого relay origin.
|
||||
|
||||
Примітка щодо сумісності:
|
||||
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` лишається запасним варіантом для розробки лише в local loopback; не зберігайте HTTP relay URL у конфігурації.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається доступним лише для loopback аварійним варіантом розробки; не зберігайте HTTP URL relay у конфігурації.
|
||||
|
||||
Дивіться [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного end-to-end потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay.
|
||||
Перегляньте [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного потоку та [Потік автентифікації й довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -408,7 +415,7 @@ JSON.
|
||||
- `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути.
|
||||
- `target`: `last` | `none` | `<channel-id>` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`)
|
||||
- `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM
|
||||
- Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
|
||||
- Перегляньте [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -427,14 +434,14 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: очищати завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
|
||||
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI.
|
||||
- `sessionRetention`: очищення завершених ізольованих сесій запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
|
||||
- `runLog`: очищення `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Перегляньте [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати Webhook (hooks)">
|
||||
Увімкніть HTTP-ендпоїнти Webhook на Gateway:
|
||||
<Accordion title="Налаштувати Webhook-и (hooks)">
|
||||
Увімкніть HTTP endpoint-и Webhook на Gateway:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -458,20 +465,20 @@ JSON.
|
||||
```
|
||||
|
||||
Примітка щодо безпеки:
|
||||
- Увесь вміст payload hook/Webhook слід вважати недовіреним введенням.
|
||||
- Вважайте весь вміст payload hook/Webhook ненадійним введенням.
|
||||
- Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway.
|
||||
- Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query-рядку відхиляються.
|
||||
- `hooks.path` не може бути `/`; використовуйте для входу Webhook окремий підшлях, наприклад `/hooks`.
|
||||
- Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження.
|
||||
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити session key, які може вибрати викликач.
|
||||
- Для агентів, керованих hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо).
|
||||
- Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються.
|
||||
- `hooks.path` не може бути `/`; використовуйте для вхідних Webhook окремий підшлях, наприклад `/hooks`.
|
||||
- Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте строго обмежене налагодження.
|
||||
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які може вибирати викликач.
|
||||
- Для агентів, що працюють через hooks, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо).
|
||||
|
||||
Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mappings та інтеграції Gmail.
|
||||
Перегляньте [повний довідник](/uk/gateway/configuration-reference#hooks), щоб побачити всі параметри mapping і інтеграцію з Gmail.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати маршрутизацію між кількома агентами">
|
||||
Запускайте кілька ізольованих агентів з окремими workspace і сесіями:
|
||||
<Accordion title="Налаштувати маршрутизацію кількох агентів">
|
||||
Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -488,12 +495,12 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил bindings і профілів доступу для кожного агента.
|
||||
Перегляньте [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing), щоб дізнатися про правила binding і профілі доступу для кожного агента.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Розділити конфігурацію на кілька файлів ($include)">
|
||||
Використовуйте `$include` для організації великих конфігурацій:
|
||||
Використовуйте `$include`, щоб упорядкувати великі конфігурації:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
@ -506,12 +513,12 @@ JSON.
|
||||
}
|
||||
```
|
||||
|
||||
- **Один файл**: замінює об’єкт, що його містить
|
||||
- **Масив файлів**: глибоко об’єднується за порядком (пізніші значення мають пріоритет)
|
||||
- **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення)
|
||||
- **Вкладені includes**: підтримуються до 10 рівнів вкладеності
|
||||
- **Відносні шляхи**: обчислюються відносно файлу, який виконує включення
|
||||
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes
|
||||
- **Один файл**: замінює об’єкт, у якому міститься
|
||||
- **Масив файлів**: глибоко об’єднується за порядком (пізніший має пріоритет)
|
||||
- **Сусідні ключі**: об’єднуються після include-ів (перевизначають включені значення)
|
||||
- **Вкладені include-и**: підтримуються до 10 рівнів вкладеності
|
||||
- **Відносні шляхи**: обчислюються відносно файла, який виконує включення
|
||||
- **Обробка помилок**: чіткі помилки для відсутніх файлів, помилок парсингу та циклічних include-ів
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -520,26 +527,26 @@ JSON.
|
||||
|
||||
Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен.
|
||||
|
||||
Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає,
|
||||
поки завершаться тимчасові записи/перейменування редактора, читає підсумковий файл і відхиляє
|
||||
некоректні зовнішні редагування, відновлюючи останню відому коректну конфігурацію. Власні записи конфігурації OpenClaw
|
||||
використовують той самий контроль схеми перед записом; руйнівні пошкодження, такі
|
||||
Прямі зміни файлу вважаються ненадійними, доки не пройдуть валідацію. Спостерігач
|
||||
чекає, поки завершиться тимчасовий запис/перейменування редактора, зчитує
|
||||
фінальний файл і відхиляє недійсні зовнішні зміни, відновлюючи останню відому
|
||||
справну конфігурацію. Записи конфігурації, якими керує OpenClaw, проходять ту саму перевірку схемою перед записом; руйнівні пошкодження, такі
|
||||
як видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються
|
||||
і зберігаються як `.rejected.*` для перевірки.
|
||||
|
||||
Якщо ви бачите `Config auto-restored from last-known-good` або
|
||||
`config reload restored last-known-good config` у журналах, перевірте відповідний
|
||||
файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім запустіть
|
||||
`openclaw config validate`. Дивіться [усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config)
|
||||
для контрольного списку відновлення.
|
||||
Якщо ви бачите в журналах `Config auto-restored from last-known-good` або
|
||||
`config reload restored last-known-good config`, перевірте відповідний
|
||||
файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте
|
||||
`openclaw config validate`. Перегляньте [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config),
|
||||
щоб ознайомитися з контрольним списком відновлення.
|
||||
|
||||
### Режими перезавантаження
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. |
|
||||
| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. |
|
||||
| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
|
||||
| Режим | Поведінка |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Для критичних змін автоматично перезапускає. |
|
||||
| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви обробляєте це самі. |
|
||||
| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
|
||||
| **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. |
|
||||
|
||||
```json5
|
||||
@ -554,42 +561,42 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично
|
||||
|
||||
Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично.
|
||||
|
||||
| Категорія | Поля | Потрібен перезапуск? |
|
||||
| ------------------ | ----------------------------------------------------------------- | -------------------- |
|
||||
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали й канали plugin | Ні |
|
||||
| Агенти й моделі | `agent`, `agents`, `models`, `routing` | Ні |
|
||||
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
|
||||
| Сесії та повідомлення | `session`, `messages` | Ні |
|
||||
| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні |
|
||||
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
|
||||
| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** |
|
||||
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
|
||||
| Категорія | Поля | Потрібен перезапуск? |
|
||||
| -------------------- | ----------------------------------------------------------------- | -------------------- |
|
||||
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали plugin | Ні |
|
||||
| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні |
|
||||
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
|
||||
| Сесії та повідомлення | `session`, `messages` | Ні |
|
||||
| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні |
|
||||
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
|
||||
| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** |
|
||||
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` і `gateway.remote` — винятки; їх зміна **не** спричиняє перезапуск.
|
||||
`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** спричиняє перезапуск.
|
||||
</Note>
|
||||
|
||||
## RPC конфігурації (програмні оновлення)
|
||||
|
||||
<Note>
|
||||
RPC керуючої площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості — **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`.
|
||||
RPC керувальної площини для запису (`config.apply`, `config.patch`, `update.run`) обмежуються до **3 запитів за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`.
|
||||
</Note>
|
||||
|
||||
Безпечний/типовий потік:
|
||||
|
||||
- `config.schema.lookup`: переглянути одне піддерево конфігурації для вказаного шляху з поверхневим
|
||||
вузлом схеми, відповідними метаданими підказок і зведеннями про безпосередніх дочірніх елементів
|
||||
- `config.get`: отримати поточний знімок + хеш
|
||||
- `config.patch`: бажаний шлях для часткового оновлення
|
||||
- `config.schema.lookup`: перевірка одного піддерева конфігурації, обмеженого шляхом, з поверхневим
|
||||
вузлом схеми, відповідними метаданими підказок і підсумками безпосередніх дочірніх елементів
|
||||
- `config.get`: отримання поточного знімка + hash
|
||||
- `config.patch`: бажаний шлях часткового оновлення
|
||||
- `config.apply`: лише повна заміна конфігурації
|
||||
- `update.run`: явне self-update + перезапуск
|
||||
- `update.run`: явне самооновлення + перезапуск
|
||||
|
||||
Якщо ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`,
|
||||
Коли ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup`,
|
||||
а потім `config.patch`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="config.apply (повна заміна)">
|
||||
Виконує валідацію + записує повну конфігурацію та перезапускає Gateway одним кроком.
|
||||
Виконує валідацію + записує повну конфігурацію та перезапускає Gateway за один крок.
|
||||
|
||||
<Warning>
|
||||
`config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів.
|
||||
@ -598,15 +605,15 @@ RPC керуючої площини для запису (`config.apply`, `config
|
||||
Параметри:
|
||||
|
||||
- `raw` (string) — payload JSON5 для всієї конфігурації
|
||||
- `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує)
|
||||
- `sessionKey` (необов’язково) — session key для wake-up ping після перезапуску
|
||||
- `note` (необов’язково) — примітка для sentinel перезапуску
|
||||
- `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000)
|
||||
- `baseHash` (optional) — hash конфігурації з `config.get` (обов’язковий, якщо конфігурація існує)
|
||||
- `sessionKey` (optional) — ключ сесії для wake-up ping після перезапуску
|
||||
- `note` (optional) — примітка для restart sentinel
|
||||
- `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000)
|
||||
|
||||
Запити на перезапуск об’єднуються, якщо один уже очікує або виконується, і між циклами перезапуску діє 30-секундний період охолодження.
|
||||
Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний cooldown.
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.get --params '{}' # зафіксувати payload.hash
|
||||
openclaw gateway call config.get --params '{}' # capture payload.hash
|
||||
openclaw gateway call config.apply --params '{
|
||||
"raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
|
||||
"baseHash": "<hash>",
|
||||
@ -626,10 +633,10 @@ RPC керуючої площини для запису (`config.apply`, `config
|
||||
Параметри:
|
||||
|
||||
- `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити
|
||||
- `baseHash` (обов’язково) — хеш конфігурації з `config.get`
|
||||
- `sessionKey`, `note`, `restartDelayMs` — так само, як у `config.apply`
|
||||
- `baseHash` (required) — hash конфігурації з `config.get`
|
||||
- `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply`
|
||||
|
||||
Поведінка перезапуску відповідає `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундний період охолодження між циклами перезапуску.
|
||||
Поведінка перезапуску збігається з `config.apply`: об’єднання відкладених перезапусків плюс 30-секундний cooldown між циклами перезапуску.
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.patch --params '{
|
||||
@ -643,12 +650,12 @@ RPC керуючої площини для запису (`config.apply`, `config
|
||||
|
||||
## Змінні середовища
|
||||
|
||||
OpenClaw зчитує env vars із батьківського процесу, а також з:
|
||||
OpenClaw зчитує env vars з батьківського процесу, а також із:
|
||||
|
||||
- `.env` у поточному робочому каталозі (якщо є)
|
||||
- `~/.openclaw/.env` (глобальний запасний варіант)
|
||||
|
||||
Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації:
|
||||
Жоден із цих файлів не перевизначає наявні env vars. Ви також можете встановлювати вбудовані env vars у конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -659,8 +666,8 @@ OpenClaw зчитує env vars із батьківського процесу,
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Імпорт env оболонки (необов’язково)">
|
||||
Якщо його ввімкнено і очікувані ключі не встановлені, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
|
||||
<Accordion title="Імпорт shell env (необов’язково)">
|
||||
Якщо ввімкнено і очікувані ключі не встановлено, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -670,11 +677,11 @@ OpenClaw зчитує env vars із батьківського процесу,
|
||||
}
|
||||
```
|
||||
|
||||
Еквівалент через env var: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підстановка env var у значеннях конфігурації">
|
||||
Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`:
|
||||
Посилайтеся на env vars у будь-якому рядковому значенні конфігурації через `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -687,14 +694,14 @@ OpenClaw зчитує env vars із батьківського процесу,
|
||||
|
||||
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
|
||||
- Відсутні/порожні змінні спричиняють помилку під час завантаження
|
||||
- Екрануйте через `$${VAR}` для буквального виводу
|
||||
- Використовуйте `$${VAR}` для буквального виводу
|
||||
- Працює всередині файлів `$include`
|
||||
- Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Посилання на секрети (env, file, exec)">
|
||||
Для полів, що підтримують об’єкти SecretRef, можна використовувати:
|
||||
Для полів, які підтримують об’єкти SecretRef, можна використовувати:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -726,15 +733,15 @@ OpenClaw зчитує env vars із батьківського процесу,
|
||||
}
|
||||
```
|
||||
|
||||
Подробиці про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведені в [Керуванні секретами](/uk/gateway/secrets).
|
||||
Підтримувані шляхи облікових даних наведені в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Докладно про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) можна прочитати в [Керування секретами](/uk/gateway/secrets).
|
||||
Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Accordion>
|
||||
|
||||
Дивіться [Середовище](/uk/help/environment) для повного порядку пріоритетів і джерел.
|
||||
Перегляньте [Середовище](/uk/help/environment), щоб дізнатися про повний пріоритет і джерела.
|
||||
|
||||
## Повний довідник
|
||||
|
||||
Повний довідник по всіх полях див. у **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**.
|
||||
Повний довідник по полях дивіться в **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**.
|
||||
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,41 +1,41 @@
|
||||
---
|
||||
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-22T13:02:14Z"
|
||||
generated_at: "2026-04-22T22:50:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7b0035cb879563a169294269e2fb39884194ec219373bc6e3edb1a8b47660b29
|
||||
source_hash: 1ef9aaacd585acd098163468880761270936a05bbf79dd54b4f4d45068eeeaf1
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI
|
||||
|
||||
OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два шляхи автентифікації:
|
||||
OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два способи автентифікації:
|
||||
|
||||
- **API key** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` моделі)
|
||||
- **API key** — прямий доступ до OpenAI Platform з оплатою за використання (`openai/*` моделі)
|
||||
- **Codex subscription** — вхід через ChatGPT/Codex з доступом за підпискою (`openai-codex/*` моделі)
|
||||
|
||||
OpenAI явно підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
OpenAI прямо підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key (OpenAI Platform)">
|
||||
**Найкраще підходить для:** прямого доступу до API та тарифікації за використання.
|
||||
**Найкраще підходить для:** прямого доступу до API та оплати за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте свій API key">
|
||||
Створіть або скопіюйте API key з [панелі керування OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
Створіть або скопіюйте API key на [панелі OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть початкове налаштування">
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
@ -46,7 +46,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai
|
||||
```
|
||||
@ -55,13 +55,13 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
|
||||
### Підсумок маршрутів
|
||||
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
| Model ref | Route | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-pro` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
Вхід через ChatGPT/Codex спрямовується через `openai-codex/*`, а не `openai/*`.
|
||||
Вхід через ChatGPT/Codex маршрутизується через `openai-codex/*`, а не `openai/*`.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -74,7 +74,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark` у прямому шляху API. Реальні запити до OpenAI API відхиляють цю модель. Spark доступний лише в Codex.
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху прямого API. Живі запити до OpenAI API відхиляють цю модель. Spark доступний лише в Codex.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -99,7 +99,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
@ -108,13 +108,13 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
|
||||
### Підсумок маршрутів
|
||||
|
||||
| Посилання на модель | Маршрут | Автентифікація |
|
||||
| Model ref | Route | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Вхід через Codex |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Вхід через Codex (залежить від entitlement) |
|
||||
| `openai-codex/gpt-5.4` | OAuth ChatGPT/Codex | Вхід через Codex |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | OAuth ChatGPT/Codex | Вхід через Codex (залежить від entitlement) |
|
||||
|
||||
<Note>
|
||||
Цей маршрут навмисно відокремлений від `openai/gpt-5.4`. Використовуйте `openai/*` з API key для прямого доступу до Platform, а `openai-codex/*` — для доступу через підписку Codex.
|
||||
Цей маршрут навмисно відокремлений від `openai/gpt-5.4`. Використовуйте `openai/*` з API key для прямого доступу до Platform, а `openai-codex/*` — для доступу за підпискою Codex.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -126,7 +126,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Якщо початкове налаштування повторно використовує наявний вхід Codex CLI, цими обліковими даними надалі керує Codex CLI. Після завершення строку дії OpenClaw спочатку повторно зчитує зовнішнє джерело Codex і записує оновлені облікові дані назад у сховище Codex.
|
||||
Якщо онбординг повторно використовує наявний вхід Codex CLI, цими обліковими даними й надалі керує Codex CLI. Після завершення строку дії OpenClaw спочатку повторно зчитує зовнішнє джерело Codex, а потім записує оновлені облікові дані назад у сховище Codex.
|
||||
</Tip>
|
||||
|
||||
### Обмеження вікна контексту
|
||||
@ -135,10 +135,10 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
|
||||
Для `openai-codex/gpt-5.4`:
|
||||
|
||||
- Рідний `contextWindow`: `1050000`
|
||||
- Нативний `contextWindow`: `1050000`
|
||||
- Типове обмеження `contextTokens` під час виконання: `272000`
|
||||
|
||||
Менше типове обмеження на практиці забезпечує кращі характеристики затримки й якості. Перевизначте його за допомогою `contextTokens`:
|
||||
Менше типове обмеження на практиці дає кращі характеристики затримки й якості. Перевизначте його за допомогою `contextTokens`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -153,7 +153,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити рідні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -163,9 +163,9 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`.
|
||||
|
||||
| Можливість | Значення |
|
||||
| ------------------------- | ------------------------------------ |
|
||||
| Модель за замовчуванням | `openai/gpt-image-2` |
|
||||
| Можливість | Значення |
|
||||
| ------------------------- | ---------------------------------- |
|
||||
| Модель за замовчуванням | `openai/gpt-image-2` |
|
||||
| Макс. кількість зображень на запит | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 еталонних зображень) |
|
||||
| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K |
|
||||
@ -182,10 +182,10 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб ознайомитися зі спільними параметрами інструмента, вибором провайдера та поведінкою failover.
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` є типовою моделлю як для генерації зображень з тексту в OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`.
|
||||
`gpt-image-2` є моделлю за замовчуванням як для генерації зображень з тексту в OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`.
|
||||
|
||||
Генерація:
|
||||
|
||||
@ -196,7 +196,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
Редагування:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на прозоре скло" image=/path/to/reference.png size=1024x1536
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
## Генерація відео
|
||||
@ -204,10 +204,10 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`.
|
||||
|
||||
| Можливість | Значення |
|
||||
| ---------------- | -------------------------------------------------------------------------------- |
|
||||
| --------------- | ------------------------------------------------------------------------------- |
|
||||
| Модель за замовчуванням | `openai/sora-2` |
|
||||
| Режими | Текст у відео, зображення у відео, редагування одного відео |
|
||||
| Еталонні вхідні дані | 1 зображення або 1 відео |
|
||||
| Режими | Текст у відео, зображення у відео, редагування одного відео |
|
||||
| Еталонні вхідні дані | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента |
|
||||
|
||||
@ -222,30 +222,32 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб ознайомитися зі спільними параметрами інструмента, вибором провайдера та поведінкою failover.
|
||||
</Note>
|
||||
|
||||
## Внесок у prompt GPT-5
|
||||
|
||||
OpenClaw додає специфічний для OpenAI внесок у prompt GPT-5 для запусків сімейства GPT-5 через `openai/*` і `openai-codex/*`. Він міститься у вбудованому Plugin OpenAI, застосовується до ідентифікаторів моделей, таких як `gpt-5`, `gpt-5.2`, `gpt-5.4` і `gpt-5.4-mini`, і не застосовується до старіших моделей GPT-4.x.
|
||||
OpenClaw додає спільний внесок у prompt GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai/gpt-5.4`, `openai-codex/gpt-5.4`, `openrouter/openai/gpt-5.4`, `opencode/gpt-5.4` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні.
|
||||
|
||||
Вбудований провайдер нативного harness Codex (`codex/*`) застосовує ту саму поведінку GPT-5 і накладення Heartbeat через інструкції розробника app-server Codex, тому сесії `codex/gpt-5.x` зберігають ту саму наполегливість у доведенні справ до кінця та проактивні вказівки Heartbeat, навіть попри те, що рештою prompt harness керує Codex.
|
||||
Вбудований рідний провайдер harness Codex (`codex/*`) використовує таку саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника Codex app-server, тому сесії `codex/gpt-5.x` зберігають ту саму послідовність виконання і проактивні вказівки Heartbeat, хоча рештою prompt harness керує Codex.
|
||||
|
||||
Внесок GPT-5 додає позначений контракт поведінки для збереження персонажу, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповіді та тихих повідомлень, специфічна для каналу, залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди увімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним.
|
||||
Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей і тихих повідомлень, специфічна для каналів, залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди увімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним.
|
||||
|
||||
| Значення | Ефект |
|
||||
| --------------------- | -------------------------------------------- |
|
||||
| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише рівень дружнього стилю |
|
||||
| Значення | Ефект |
|
||||
| -------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише рівень дружнього стилю |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Config">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
openai: { config: { personality: "friendly" } },
|
||||
agents: {
|
||||
defaults: {
|
||||
promptOverlays: {
|
||||
gpt5: { personality: "friendly" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -253,29 +255,33 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
</Tab>
|
||||
<Tab title="CLI">
|
||||
```bash
|
||||
openclaw config set plugins.entries.openai.config.personality off
|
||||
openclaw config set agents.defaults.promptOverlays.gpt5.personality off
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Під час виконання значення нечутливі до регістру, тож і `"Off"`, і `"off"` вимикають рівень дружнього стилю.
|
||||
Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають рівень дружнього стилю.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застаріле `plugins.entries.openai.config.personality` і далі зчитується як сумісний запасний варіант, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Синтез мовлення (TTS)">
|
||||
Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Налаштування | Шлях конфігурації | Значення за замовчуванням |
|
||||
|---------|------------|---------|
|
||||
| Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| Голос | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| Швидкість | `messages.tts.providers.openai.speed` | (не задано) |
|
||||
| Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
@ -293,23 +299,23 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
```
|
||||
|
||||
<Note>
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку chat API.
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити Base URL для TTS без впливу на endpoint chat API.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Транскрипція в реальному часі">
|
||||
Вбудований Plugin `openai` реєструє транскрипцію в реальному часі для Plugin Voice Call.
|
||||
<Accordion title="Транскрибування в реальному часі">
|
||||
Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Налаштування | Шлях конфігурації | Значення за замовчуванням |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `800` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` |
|
||||
| API key | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант |
|
||||
|
||||
<Note>
|
||||
Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law.
|
||||
Використовує з’єднання WebSocket з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -317,17 +323,17 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
<Accordion title="Голос у реальному часі">
|
||||
Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
| Налаштування | Шлях конфігурації | Значення за замовчуванням |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
|
||||
| Голос | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `500` |
|
||||
| API key | `...openai.apiKey` | З резервним поверненням до `OPENAI_API_KEY` |
|
||||
| API key | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує формат аудіо G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -337,17 +343,17 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Транспорт (WebSocket vs SSE)">
|
||||
OpenClaw використовує WebSocket-first із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
OpenClaw використовує WebSocket-first із запасним переходом на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`.
|
||||
|
||||
У режимі `"auto"` OpenClaw:
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
- Після збою позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) у різних варіантах транспорту
|
||||
|
||||
| Значення | Поведінка |
|
||||
|-------|----------|
|
||||
| `"auto"` (типово) | WebSocket first, резервний перехід на SSE |
|
||||
| `"auto"` (типово) | Спочатку WebSocket, запасний перехід на SSE |
|
||||
| `"sse"` | Примусово лише SSE |
|
||||
| `"websocket"` | Примусово лише WebSocket |
|
||||
|
||||
@ -371,11 +377,11 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Розігрів WebSocket">
|
||||
OpenClaw типово вмикає розігрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу.
|
||||
<Accordion title="Прогрів WebSocket">
|
||||
OpenClaw типово вмикає прогрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу.
|
||||
|
||||
```json5
|
||||
// Вимкнути розігрів
|
||||
// Вимкнути прогрів
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
@ -413,7 +419,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення.
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого значення за замовчуванням.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -437,7 +443,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
Підтримувані значення: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
`serviceTier` передається лише до нативних endpoint OpenAI (`api.openai.com`) і нативних endpoint Codex (`chatgpt.com/backend-api`). Якщо ви спрямовуєте будь-якого з цих провайдерів через proxy, OpenClaw залишає `service_tier` без змін.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -445,13 +451,13 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
<Accordion title="Server-side Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) OpenClaw автоматично вмикає server-side Compaction:
|
||||
|
||||
- Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `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`, якщо він недоступний)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Увімкнути явно">
|
||||
Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses:
|
||||
<Tab title="Явно ввімкнути">
|
||||
Корисно для сумісних endpoint, як-от Azure OpenAI Responses:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -503,7 +509,7 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses однаково примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -522,30 +528,30 @@ OpenClaw додає специфічний для OpenAI внесок у prompt
|
||||
```
|
||||
|
||||
Із `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія з інструментом
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента
|
||||
- Повторює хід із вказівкою діяти зараз
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дії
|
||||
|
||||
<Note>
|
||||
Обмежено лише запуском сімейства GPT-5 для OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку.
|
||||
Поширюється лише на запускі сімейства OpenAI та Codex GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні маршрути та маршрути, сумісні з OpenAI">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI порівняно із загальними проксі `/v1`, сумісними з OpenAI:
|
||||
<Accordion title="Нативні маршрути та маршрути OpenAI-compatible">
|
||||
OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-compatible proxy `/v1`:
|
||||
|
||||
**Нативні маршрути** (`openai/*`, `openai-codex/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort
|
||||
- Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово встановлюють суворий режим для схем інструментів
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують `none` effort в OpenAI
|
||||
- Пропускають вимкнений reasoning для моделей або proxy, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово використовують строгий режим для схем інструментів
|
||||
- Додають приховані заголовки атрибуції лише на перевірених нативних хостах
|
||||
- Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки prompt-cache)
|
||||
- Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache)
|
||||
|
||||
**Проксі/сумісні маршрути:**
|
||||
**Маршрути proxy/compatible:**
|
||||
- Використовують м’якшу поведінку сумісності
|
||||
- Не примусово встановлюють суворі схеми інструментів або заголовки, специфічні для нативних маршрутів
|
||||
- Не примушують до строгих схем інструментів або нативних заголовків
|
||||
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user