From 0df99629d3ce6b8ebb4cf766591368b637bc4604 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 18:37:26 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/config-agents.md | 532 +++++++++++++++--------------- docs/uk/providers/openai.md | 438 ++++++++++++------------ docs/uk/tools/image-generation.md | 220 ++++++------ 3 files changed, 595 insertions(+), 595 deletions(-) diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index 2f545b418..dd087ff63 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,21 +1,21 @@ --- read_when: - - Налаштування типових параметрів агента (моделі, мислення, робочий простір, Heartbeat, медіа, Skills) + - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування поведінки сесії, доставки повідомлень і режиму розмови -summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація розмови + - Налаштування сесії, доставки повідомлень і поведінки режиму talk +summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-25T17:32:14Z" + generated_at: "2026-04-25T18:33:43Z" model: gpt-5.4 provider: openai - source_hash: cb090bad584cab0d22bc4788652f0fd6d7f2931be1fe40d3907f8ef2123a433b + source_hash: d017648f522fe7be7cfca2691735132f60888c8c1ac6d84689ab327e9187e965 source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації в межах агента у `agents.*`, `multiAgent.*`, `session.*`, -`messages.*` та `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших +Ключі конфігурації в області дії агента в `agents.*`, `multiAgent.*`, `session.*`, +`messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). ## Типові параметри агента @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий кореневий каталог репозиторію, що показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. ```json5 { @@ -42,7 +42,7 @@ x-i18n: ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, у яких не задано +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -58,9 +58,9 @@ x-i18n: } ``` -- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. -- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Встановіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. +- Опустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. +- Опустіть `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб не було Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -76,10 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вставляються до системного запиту. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: на безпечних ходах продовження (після завершеної відповіді помічника) повторна вставка bootstrap-контексту робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. -- `"never"`: вимикає вставку bootstrap-файлів робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують власним життєвим циклом запиту (власні рушії контексту, нативні середовища виконання, що самі формують контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вставку. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap-файлів робочого простору, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"never"`: вимикає вбудовування bootstrap-файлів робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують власним життєвим циклом запиту (власні рушії контексту, нативні середовища виконання, що самі формують свій контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вбудовування. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл робочого простору перед обрізанням. Типове значення: `12000`. +Максимальна кількість символів у кожному bootstrap-файлі робочого простору до обрізання. Типове значення: `12000`. ```json5 { @@ -99,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -112,9 +112,9 @@ x-i18n: Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типове значення: `"once"`. -- `"off"`: ніколи не вставляти текст попередження до системного запиту. -- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). -- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в системний запит. +- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано). +- `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -124,24 +124,24 @@ x-i18n: ### Карта відповідальності за бюджет контексту -OpenClaw має кілька великих бюджетів для запиту/контексту, і вони -навмисно розділені між підсистемами, а не зведені до одного загального -параметра. +OpenClaw має кілька великих бюджетів запиту/контексту, і вони +навмисно розділені за підсистемами замість того, щоб усе проходило через +один загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайна вставка bootstrap-контексту робочого простору. + звичайне вбудовування bootstrap робочого простору. - `agents.defaults.startupContext.*`: - одноразова початкова преамбула для `/new` і `/reset`, включно з недавніми - файлами `memory/*.md` за день. + одноразова стартова преамбула для `/new` і `/reset`, включно з нещодавніми + файлами `memory/*.md` за днями. - `skills.limits.*`: - компактний список Skills, вставлений до системного запиту. + стиснутий список Skills, вбудований у системний запит. - `agents.defaults.contextLimits.*`: - обмежені витяги середовища виконання та вставлені блоки, якими володіє середовище виконання. + обмежені фрагменти середовища виконання та вбудовані блоки, що належать середовищу виконання. - `memory.qmd.limits.*`: - фрагмент індексованого пошуку в пам’яті та налаштування розміру вставки. + розмір фрагментів і вбудовування для індексованого пошуку в пам’яті. -Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший +Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -149,7 +149,7 @@ OpenClaw має кілька великих бюджетів для запиту #### `agents.defaults.startupContext` -Керує початковою преамбулою першого ходу, що вставляється під час простих запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, яка вбудовується в порожні запуски `/new` і `/reset`. ```json5 { @@ -187,18 +187,18 @@ OpenClaw має кілька великих бюджетів для запиту } ``` -- `memoryGetMaxChars`: типове обмеження витягу `memory_get` перед додаванням - метаданих обрізання та сповіщення про продовження. +- `memoryGetMaxChars`: типове обмеження фрагмента `memory_get` до додавання + метаданих обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, якщо `lines` не вказано. -- `toolResultMaxChars`: поточне обмеження результату інструмента, що використовується для збережених результатів і +- `toolResultMaxChars`: обмеження результату інструмента в реальному часі, що використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вставки +- `postCompactionMaxChars`: обмеження фрагмента AGENTS.md, що використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -225,7 +225,7 @@ OpenClaw має кілька великих бюджетів для запиту #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, вставленого до системного запиту. Це +Глобальне обмеження для стиснутого списку Skills, вбудованого в системний запит. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -240,7 +240,7 @@ OpenClaw має кілька великих бюджетів для запиту #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення бюджету запиту Skills для конкретного агента. +Перевизначення бюджету запиту Skills для окремого агента. ```json5 { @@ -259,11 +259,11 @@ OpenClaw має кілька великих бюджетів для запиту ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. +Максимальний розмір у пікселях для довшого боку зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю знімків екрана. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для сценаріїв із великою кількістю знімків екрана. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -283,7 +283,7 @@ OpenClaw має кілька великих бюджетів для запиту ### `agents.defaults.timeFormat` -Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). +Формат часу в системному запиті. Типове значення: `auto` (параметри ОС). ```json5 { @@ -323,7 +323,7 @@ OpenClaw має кілька великих бюджетів для запиту }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | зареєстрований ідентифікатор harness, наприклад codex + runtime: "pi", // pi | auto | ідентифікатор зареєстрованого harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -342,52 +342,52 @@ OpenClaw має кілька великих бюджетів для запиту - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей для відмовостійкості. + - Форма об’єкта задає основну модель плюс упорядковані резервні моделі для failover. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). - - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку їхніх ідентифікаторів провайдерів. + - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для прозорого PNG/WebP-виводу OpenAI. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` для `fal/*`). + - Якщо це поле опущено, `image_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку їхніх ідентифікаторів провайдерів. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.6`. - - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку їхніх ідентифікаторів провайдерів. - - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо це поле опущено, `music_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку їхніх ідентифікаторів провайдерів. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку їхніх ідентифікаторів провайдерів. - - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. + - Якщо це поле опущено, `video_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку їхніх ідентифікаторів провайдерів. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. + - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо не вказано, інструмент PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель. + - Якщо це поле опущено, інструмент PDF спочатку використовує `imageModel`, а потім — визначену для сесії/типову модель. - `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується режимом резервного вилучення в інструменті `pdf`. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується в режимі резервного вилучення інструмента `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви не вказуєте провайдера, OpenClaw спочатку намагається знайти alias, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). - - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які прибрали б наявні записи зі списку дозволених значень, якщо ви не передасте `--replace`. - - Потоки налаштування/онбордингу на рівні провайдера об’єднують вибрані моделі провайдера в цю карту та зберігають уже налаштованих, не пов’язаних із цим, провайдерів. - - Для прямих моделей OpenAI Responses серверний Compaction вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити вставку `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу за API key або `openai-codex/gpt-5.5` для Codex OAuth). Якщо опустити провайдера, OpenClaw спочатку намагається використати alias, потім — унікальний збіг точного ідентифікатора моделі серед налаштованих провайдерів, і лише після цього повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тож краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари provider/model замість показу застарілого типового значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи списку дозволених значень, якщо не передати `--replace`. + - Потоки configure/onboarding в області провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають уже налаштованих, але не пов’язаних провайдерів. + - Для прямих моделей OpenAI Responses автоматично вмикається server-side Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити вбудовування `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверна Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, які застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Кешування запитів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений JSON passthrough, що об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, додаткове тіло має пріоритет; не нативні маршрути completions після цього все одно видаляють специфічний для OpenAI `store`. -- `embeddedHarness`: типова політика низькорівневого середовища виконання для вбудованого агента. Якщо runtime не вказано, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб зареєстровані harness-и Plugin могли брати на себе підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні runtime-и Plugin, як-от `codex`, типово працюють у режимі fail-closed, якщо ви не встановите `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічній формі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime-провайдерів. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та за можливості зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно виконується послідовно). Типове значення: 4. +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), після чого `agents.list[].params` (відповідний ідентифікатор агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений JSON passthrough, який зливається з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, додаткове тіло має пріоритет; не нативні маршрути completions усе одно потім видаляють специфічний для OpenAI параметр `store`. +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` опущено, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin перехоплювати підтримувані моделі, або ідентифікатор зареєстрованого harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні середовища виконання Plugin, такі як `codex`, типово завершуються з помилкою без переходу до резервного варіанта, якщо ви не задасте `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію середовища виконання, а не через застарілі префікси провайдера середовища виконання. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору provider/model. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, за можливості, зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. -У більшості розгортань варто залишити типове середовище виконання OpenClaw Pi. -Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований -harness сервера застосунку Codex. Для загального розуміння див. -[Середовища виконання агентів](/uk/concepts/agent-runtimes). +`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +У більшості розгортань слід зберігати типове середовище виконання OpenClaw Pi. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад +вбудований harness сервера застосунку Codex. Для концептуальної моделі див. +[Середовища виконання агента](/uk/concepts/agent-runtimes). ```json5 { @@ -404,11 +404,11 @@ harness сервера застосунку Codex. Для загального ``` - `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness Plugin. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене значення `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден harness Plugin не бере запуск на себе. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущене значення `fallback` типово дорівнює `"none"`, щоб відсутній harness завершувався помилкою замість тихого використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задавайте `fallback: "pi"` поруч з явним runtime, коли свідомо хочете таку сумісність. Помилки вибраного harness Plugin завжди показуються безпосередньо. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. -- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно задати `embeddedHarness.fallback: "none"` для читабельності; це типове значення для явних runtime-ів Plugin. -- Вибір harness прив’язується до id сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, а не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без записаної прив’язки, вважаються прив’язаними до PI. `/status` показує фактичне середовище виконання, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише вбудованим chat-harness. Генерація медіа, vision, PDF, музика, відео та TTS, як і раніше, використовують свої налаштування провайдера/моделі. +- `fallback`: `"pi"` або `"none"`. Для `runtime: "auto"` пропущене значення fallback типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден harness Plugin не перехоплює запуск. У режимі явного середовища виконання Plugin, наприклад `runtime: "codex"`, пропущене значення fallback типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість тихого використання PI. Перевизначення середовища виконання не успадковують fallback із ширшої області; установлюйте `fallback: "pi"` разом з явним середовищем виконання, коли вам навмисно потрібен такий сумісний резервний варіант. Помилки вибраного harness Plugin завжди показуються напряму. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу. +- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно встановити `embeddedHarness.fallback: "none"` для читабельності; це типове значення для явних середовищ виконання Plugin. +- Вибір harness фіксується для кожного ідентифікатора сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує фактичне середовище виконання, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS усе одно використовують свої параметри provider/model. **Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): @@ -416,7 +416,7 @@ harness сервера застосунку Codex. Для загального | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` | +| `gpt` | `openai/gpt-5.5` або `openai-codex/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -425,13 +425,13 @@ harness сервера застосунку Codex. Для загального Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. -Для моделей Z.AI типово ввімкнено `tool_stream` для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, якщо явний рівень thinking не задано. +Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. +Для моделей Z.AI типово вмикається `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо не задано явний рівень thinking. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери дають збій. ```json5 { @@ -449,7 +449,7 @@ harness сервера застосунку Codex. Для загального sessionArg: "--session", sessionMode: "existing", systemPromptArg: "--system", - // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець файла запиту. + // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець для файла запиту. systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -460,13 +460,13 @@ harness сервера застосунку Codex. Для загального } ``` -- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, якщо задано `sessionArg`. -- Передавання зображень підтримується, якщо `imageArg` приймає шляхи до файлів. +- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнено. +- Сесії підтримуються, коли задано `sessionArg`. +- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -480,7 +480,7 @@ harness сервера застосунку Codex. Для загального ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладення запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -498,7 +498,7 @@ harness сервера застосунку Codex. Для загального - `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. - `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще читається, коли цей спільний параметр не задано. +- Застаріле `plugins.entries.openai.config.personality` усе ще читається, якщо цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -509,16 +509,16 @@ harness сервера застосунку Codex. Для загального agents: { defaults: { heartbeat: { - every: "30m", // 0m вимикає + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типове значення: true; false прибирає розділ Heartbeat із системного запиту - lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору - isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новій сесії (без історії розмови) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (типове значення) | block - target: "none", // типове значення: none | варіанти: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -529,15 +529,15 @@ harness сервера застосунку Codex. Для загального } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо false, прибирає розділ Heartbeat із системного запиту та пропускає вставку `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: якщо true, пригнічує корисні навантаження попереджень про помилки інструментів під час запусків heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типове значення) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та видає `reason=dm-blocked`. -- `lightContext`: якщо true, запуски heartbeat використовують полегшений bootstrap-контекст і з bootstrap-файлів робочого простору залишають лише `HEARTBEAT.md`. -- `isolatedSession`: якщо true, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для конкретного агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**. -- Heartbeat виконують повні ходи агента — коротші інтервали витрачають більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: коли `false`, прибирає розділ Heartbeat із системного запиту та пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли `true`, пригнічує корисні навантаження попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/DM. `allow` (типове значення) дозволяє доставку в прямі цілі. `block` пригнічує доставку в прямі цілі та видає `reason=dm-blocked`. +- `lightContext`: коли `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: коли `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Така сама схема ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. +- Heartbeat запускає повні ходи агента — коротші інтервали витрачають більше токенів. ### `agents.defaults.compaction` @@ -547,16 +547,16 @@ harness сервера застосунку Codex. Для загального defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково) + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну вставку - model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction - notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається й завершується (типове значення: false) + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -569,17 +569,17 @@ harness сервера застосунку Codex. Для загального } ``` -- `mode`: `default` або `safeguard` (узагальнення частинами для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого узагальнення LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого механізму. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` враховує це, якщо параметр явно задано; інакше ручний compaction є жорсткою контрольною точкою. -- `identifierPolicy`: `strict` (типове значення), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час узагальнення compaction. -- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки повторної спроби при некоректному виводі для підсумків safeguard. Типово ввімкнено в режимі safeguard; установіть `enabled: false`, щоб пропустити перевірку. -- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md для повторної вставки після compaction. Типово: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторну вставку. Якщо параметр не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. -- `model`: необов’язкове перевизначення `provider/model-id` лише для узагальнення compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction повинні виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії. -- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction залишався безшумним. -- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. +- `mode`: `default` або `safeguard` (підсумовування частинами для довгої історії). Див. [Compaction](/uk/concepts/compaction). +- `provider`: ідентифікатор зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. +- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` дотримується цього, якщо значення явно задано; інакше ручна Compaction є жорсткою контрольною точкою. +- `identifierPolicy`: `strict` (типове значення), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. +- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки з повторною спробою для некоректного виводу в підсумках safeguard. Типово ввімкнено в режимі safeguard; установіть `enabled: false`, щоб пропустити аудит. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md для повторного вбудовування після Compaction. Типове значення: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вбудовування. Якщо не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction повинні виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії. +- `notifyUser`: коли `true`, надсилає користувачеві короткі сповіщення на початку та після завершення Compaction (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишалася безшумною. +- `memoryFlush`: тихий агентний хід перед автоматичною Compaction для збереження довготривалих спогадів. Пропускається, коли робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` @@ -591,7 +591,7 @@ harness сервера застосунку Codex. Для загального defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -608,22 +608,22 @@ harness сервера застосунку Codex. Для загального - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього дотику до кешу). -- Обрізання спочатку м’яко скорочує надто великі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього дотику до кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. -**М’яке скорочення** зберігає початок і кінець та вставляє посередині `...`. +**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. **Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не скорочуються й не очищаються. -- Співвідношення обчислюються за символами (приблизно), а не за точними кількостями токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається. +- Блоки зображень ніколи не обрізаються і не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. +- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. -Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning). +Докладніше про поведінку див. [Обрізання сесії](/uk/concepts/session-pruning). ### Блокове потокове передавання @@ -635,17 +635,17 @@ harness сервера застосунку Codex. Для загального blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` -- Для каналів, відмінних від Telegram, щоб увімкнути блочні відповіді, потрібно явно задати `*.blockStreaming: true`. -- Перевизначення каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типовим є `minChars: 1500`. -- `humanDelay`: випадкова пауза між блочними відповідями. `natural` = 800–2500 мс. Перевизначення для конкретного агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типовим є `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку та деталі поділу на частини див. у [Потокове передавання](/uk/concepts/streaming). +Докладніше про поведінку та поділ на фрагменти див. [Потокове передавання](/uk/concepts/streaming). ### Індикатори набору @@ -660,8 +660,8 @@ harness сервера застосунку Codex. Для загального } ``` -- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадування. -- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. +- Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Індикатори набору](/uk/concepts/typing-indicators). @@ -669,7 +669,7 @@ harness сервера застосунку Codex. Для загального ### `agents.defaults.sandbox` -Необов’язкова ізоляція sandbox для вбудованого агента. Повний посібник див. у [Ізоляція sandbox](/uk/gateway/sandboxing). +Необов’язкова ізоляція sandbox для вбудованого агента. Повний посібник див. в [Ізоляція sandbox](/uk/gateway/sandboxing). ```json5 { @@ -715,7 +715,7 @@ harness сервера застосунку Codex. Для загального identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Також підтримуються SecretRefs / вбудований вміст: + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -764,7 +764,7 @@ harness сервера застосунку Codex. Для загального } ``` - + **Бекенд:** @@ -772,16 +772,16 @@ harness сервера застосунку Codex. Для загального - `ssh`: універсальне віддалене середовище виконання на основі SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, специфічні для цього середовища виконання параметри переміщуються до +Коли вибрано `backend: "openshell"`, параметри, специфічні для середовища виконання, переносяться до `plugins.entries.openshell.config`. -**Конфігурація бекенда SSH:** +**Конфігурація SSH-бекенда:** -- `target`: SSH-ціль у форматі `user@host[:port]` -- `command`: команда SSH-клієнта (типове значення: `ssh`) +- `target`: ціль SSH у форматі `user@host[:port]` +- `command`: команда SSH-клієнта (типово: `ssh`) - `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах кожної області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** @@ -791,24 +791,24 @@ harness сервера застосунку Codex. Для загального - `knownHostsData` має пріоритет над `knownHostsFile` - Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання секретів до початку сесії sandbox -**Поведінка бекенда SSH:** +**Поведінка SSH-бекенда:** -- один раз заповнює віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений SSH-робочий простір як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH +- один раз ініціалізує віддалений робочий простір після створення або повторного створення +- потім зберігає віддалений робочий простір SSH як канонічний +- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує контейнери браузера в sandbox +- не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox для кожної області в `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent` -- `rw`: робочий простір агента монтується для читання і запису в `/workspace` +- `none`: робочий простір sandbox у межах області в `~/.openclaw/sandboxes` +- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` +- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` **Область:** -- `session`: окремий контейнер і робочий простір для кожної сесії -- `agent`: один контейнер і робочий простір на агента (типове значення) +- `session`: окремий контейнер + робочий простір для кожної сесії +- `agent`: один контейнер + робочий простір на агента (типово) - `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -824,10 +824,10 @@ harness сервера застосунку Codex. Для загального from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // необов’язково - gatewayEndpoint: "https://lab.example", // необов’язково - policy: "strict", // необов’язковий id політики OpenShell - providers: ["openai"], // необов’язково + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -839,30 +839,30 @@ harness сервера застосунку Codex. Для загального **Режим OpenShell:** -- `mirror`: заповнює віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз заповнює віддалене середовище під час створення sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, потім зберігає віддалений робочий простір канонічним -У режимі `remote` зміни, внесені локально на хості поза OpenClaw, не синхронізуються до sandbox автоматично після етапу початкового заповнення. +У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, доступного для запису кореня та користувача root. -**Для контейнерів типовим є `network: "none"`** — установіть `"bridge"` (або власну мережу bridge), якщо агенту потрібен вихід назовні. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний виняток). +**Для контейнерів типовим є `network: "none"`** — установіть `"bridge"` (або власну мережу bridge), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не задасте +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант). -**Вхідні вкладення** розміщуються в `media/inbound/*` активного робочого простору. +**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки й прив’язки для конкретного агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні монтування й монтування для окремих агентів об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється до системного запиту. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, і OpenClaw видає URL із короткоживучим токеном (замість відкриття пароля в спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість показу пароля у спільному URL). -- `allowHostControl: false` (типове значення) блокує для ізольованих сесій націлювання на браузер хоста. -- `network` типово дорівнює `openclaw-sandbox-browser` (окрема мережа bridge). Установлюйте `bridge` лише тоді, коли вам явно потрібне глобальне з’єднання через bridge. -- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера діапазоном CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо параметр задано (зокрема як `[]`), він замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: +- `allowHostControl: false` (типове значення) блокує sandbox-сесії від націлювання на браузер хоста. +- Для `network` типово використовується `openclaw-sandbox-browser` (окрема мережа bridge). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. +- `cdpSourceRange` за потреби обмежує вхідні підключення CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -881,29 +881,29 @@ harness сервера застосунку Codex. Для загального - `--metrics-recording-only` - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнені, і їх можна вимкнути за допомогою + типово ввімкнені й можуть бути вимкнені через `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використати + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - - а також `--no-sandbox`, коли ввімкнено `noSandbox`. - - Типові параметри є базовими для образу контейнера; щоб змінити типові значення контейнера, - використовуйте власний браузерний образ із власним entrypoint. + - плюс `--no-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; використовуйте власний образ браузера з власною + точкою входу, щоб змінити типові параметри контейнера. -Ізоляція браузера в sandbox і `sandbox.docker.binds` підтримуються лише для Docker. +Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Збірка образів: +Зібрати образи: ```bash -scripts/sandbox-setup.sh # основний образ sandbox -scripts/sandbox-browser-setup.sh # необов’язковий образ браузера +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` -### `agents.list` (перевизначення для конкретного агента) +### `agents.list` (перевизначення для окремих агентів) ```json5 { @@ -915,13 +915,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } - thinkingDefault: "high", // перевизначення рівня thinking для конкретного агента - reasoningDefault: "on", // перевизначення видимості reasoning для конкретного агента - fastModeDefault: false, // перевизначення швидкого режиму для конкретного агента + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params - skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -952,27 +952,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний id агента (обов’язково). -- `default`: якщо задано для кількох агентів, перший має пріоритет (записується попередження). Якщо не задано ні для кого, типовим стає перший елемент списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для конкретного агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо його не вказано, агент успадковує `agents.defaults.skills`, якщо той задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення допустимі; для Google Gemini `adaptive` зберігає динамічний thinking під контролем провайдера (`thinkingLevel` не задається в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення швидкого режиму для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення швидкого режиму для повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex" }`, щоб зробити одного агента лише для Codex, тоді як інші агенти зберігатимуть типовий резервний перехід на PI в режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент за замовчуванням має працювати з сесіями harness ACP. +- `id`: стабільний ідентифікатор агента (обов’язково). +- `default`: якщо задано для кількох, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим є перший елемент списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо не встановити `fallbacks: []`. +- `params`: параметри потоку для окремого агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, якщо воно визначене; явний список замінює типові значення, а не зливається з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення допустимі; для Google Gemini `adaptive` зберігає динамічний thinking, яким керує провайдер (`thinkingLevel` опущено для Gemini 3/3.1, `thinkingBudget: -1` для Gemini 2.5). +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, коли не задано перевизначення швидкого режиму для окремого повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI в режимі `auto`. +- `runtime`: необов’язковий дескриптор середовища виконання для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент повинен типово використовувати сесії harness ACP. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. -- Для `identity` типові значення виводяться автоматично: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. -- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типове значення: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує явно вибирати профіль; типове значення: false). +- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типове значення: false). --- ## Маршрутизація між кількома агентами -Запускайте кілька ізольованих агентів у межах одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кількох ізольованих агентів в одному Gateway. Див. [Кілька агентів](/uk/concepts/multi-agent). ```json5 { @@ -991,27 +991,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Поля збігу прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типовим є route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо опущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) -- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок збігу:** +**Детермінований порядок збігів:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (на рівні всього каналу) +4. `match.accountId` (точний, без peer/guild/team) +5. `match.accountId: "*"` (на весь канал) 6. Типовий агент -У межах кожного рівня перемагає перший запис `bindings`, що збігся. +У межах кожного рівня перший відповідний запис `bindings` має пріоритет. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route. +Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки маршруту. -### Профілі доступу для конкретного агента +### Профілі доступу для окремих агентів @@ -1031,7 +1031,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1106,7 +1106,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Деталі пріоритету див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритет див. в [Sandbox та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools). --- @@ -1132,22 +1132,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати відгалуження батьківського потоку вище цього ліміту токенів (0 вимикає) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // тривалість або false - maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет - highWaterBytes: "400mb", // необов’язкова ціль очищення + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) - maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // застаріле поле (середовище виконання завжди використовує "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1157,37 +1157,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типове значення): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст справді потрібен). + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - `main`: усі DM використовують спільну основну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких вхідних). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: карта канонічних id до peer-ів із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, перемагає той, що спливає раніше. + - `per-peer`: ізоляція за ідентифікатором відправника між каналами. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для вхідних скриньок із кількома користувачами). + - `per-account-channel-peer`: ізоляція для кожної комбінації обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). +- **`identityLinks`**: мапа канонічних ідентифікаторів до peer із префіксами провайдерів для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальний дозволений `totalTokens` батьківської сесії під час створення відгалуженої сесії потоку (типове значення `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії потоку (типове значення `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. - **`mainKey`**: застаріле поле. Середовище виконання завжди використовує `"main"` для основного кошика прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у відповідь між агентами під час обмінів agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. -- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший збіг deny перемагає. -- **`maintenance`**: елементи керування очищенням сховища сесій і зберіганням. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший збіг deny має пріоритет. +- **`maintenance`**: очищення сховища сесій і керування утриманням. - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - `pruneAfter`: віковий поріг для застарілих записів (типове значення `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типове значення `500`). - - `rotateBytes`: обертає `sessions.json`, коли його розмір перевищує це значення (типове значення `10mb`). - - `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `rotateBytes`: обертати `sessions.json`, коли він перевищує цей розмір (типове значення `10mb`). + - `resetArchiveRetention`: термін зберігання архівів транскрипту `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сесій. У режимі `warn` записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`. - **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1198,7 +1198,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ```json5 { messages: { - responsePrefix: "🦞", // або "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1213,7 +1213,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, }, inbound: { - debounceMs: 2000, // 0 вимикає + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1225,7 +1225,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Префікс відповіді -Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. @@ -1244,19 +1244,19 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. -- Область: `group-mentions` (типове значення), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає статусні реакції життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо параметр не задано, статусні реакції залишаються ввімкненими, коли активні реакції підтвердження. - У Telegram потрібно явно встановити `true`, щоб увімкнути статусні реакції життєвого циклу. +- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. +- Область дії: `group-mentions` (типове значення), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: прибирає підтвердження після відповіді у Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. + У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram установіть це явно в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Вхідне затримування +### Вхідний debounce -Об’єднує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять затримування. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди оминають debounce. -### TTS (перетворення тексту на мовлення) +### TTS (озвучення тексту) ```json5 { @@ -1304,19 +1304,19 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `auto` керує типовим режимом авто-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (потрібне явне ввімкнення). -- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який ви хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як alias для `microsoft`. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне ввімкнення). +- Для API key використовуються резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий ідентифікатор провайдера `edge` приймається як alias для `microsoft`. - `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `providers.openai.baseUrl` вказує на кінцеву точку, відмінну від OpenAI, OpenClaw розглядає її як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. +- Коли `providers.openai.baseUrl` вказує на кінцеву точку, відмінну від OpenAI, OpenClaw трактує її як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. --- -## Розмова +## Talk -Типові значення для режиму розмови (macOS/iOS/Android). +Типові значення для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1344,15 +1344,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів розмови. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності й автоматично мігруються до `talk.providers.`. -- Ідентифікатори голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API-ключ Talk. +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності та автоматично мігрують у `talk.providers.`. +- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key для Talk. - `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. -- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовується локальним помічником macOS MLX. Якщо не вказано, macOS використовує `mlx-community/Soprano-80M-bf16`. -- Відтворення MLX на macOS запускається через вбудований помічник `openclaw-mlx-tts`, якщо він присутній, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. -- `silenceTimeoutMs` керує тим, як довго режим розмови чекає після мовчання користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). +- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний помічник MLX на macOS. Якщо не задано, macOS використовує `mlx-community/Soprano-80M-bf16`. +- Відтворення MLX на macOS виконується через вбудований помічник `openclaw-mlx-tts`, якщо він присутній, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача перед надсиланням транскрипту. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms` на macOS і Android, `900 ms` на iOS). --- diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 472be9322..4cfc1f847 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,111 +1,112 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете автентифікацію через підписку Codex замість ключів API - - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використовуйте OpenAI через ключі API або підписку Codex в OpenClaw + - Ви хочете використовувати автентифікацію підписки Codex замість API-ключів + - Вам потрібні суворіші правила виконання для агента GPT-5 +summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-25T17:33:09Z" + generated_at: "2026-04-25T18:33:43Z" model: gpt-5.4 provider: openai - source_hash: 4f099227b8c8be3a4e919ea286fcede1e4e47be60c7593eb63b4cbbe85aa8389 + source_hash: da975a05e7dad86f4da8d85ff6a7915233321485854e927e3687c06ee1cf7b99 source_path: providers/openai.md workflow: 15 --- OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут: -- **Ключ API** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) +- **API-ключ** — прямий доступ до платформи OpenAI з тарифікацією за використанням (моделі `openai/*`) - **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`) -- **Harness app-server Codex** — нативне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`) +- **Каркас app-server Codex** — нативне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`) -OpenAI явно підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах на кшталт OpenClaw. +OpenAI прямо підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw. -Провайдер, модель, runtime і канал — це окремі шари. Якщо ці мітки -плутаються між собою, прочитайте [Agent runtimes](/uk/concepts/agent-runtimes), перш ніж +Провайдер, модель, runtime і канал — це окремі рівні. Якщо ці позначення +плутаються між собою, прочитайте [Runtime агентів](/uk/concepts/agent-runtimes), перш ніж змінювати конфігурацію. ## Швидкий вибір | Ціль | Використовуйте | Примітки | | --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | -| Пряма оплата через ключ API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть onboarding ключа API OpenAI. | +| Пряма тарифікація через API-ключ | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть онбординг OpenAI API-key. | | GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Стандартний маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій із підпискою. | -| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Примусово використовує harness app-server Codex для цього посилання моделі. | -| Генерація або редагування зображень | `openai/gpt-image-2` | Працює або з `OPENAI_API_KEY`, або з OpenAI Codex OAuth. | +| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Примусово вмикає каркас app-server Codex для цього посилання на модель. | +| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. | +| Зображення з прозорим фоном | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | -GPT-5.5 доступна як через прямий доступ до OpenAI Platform API за ключем, -так і через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку +GPT-5.5 доступна як через прямий доступ до OpenAI Platform API за API-ключем, так і +через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку через `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для Codex OAuth через PI, або -`openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` для нативного harness +`openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` для нативного каркаса app-server Codex. -Увімкнення плагіна OpenAI або вибір моделі `openai-codex/*` не -вмикає вбудований плагін app-server Codex. OpenClaw вмикає цей плагін лише -коли ви явно вибираєте нативний harness Codex через -`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання моделі `codex/*`. +Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не +вмикає вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише +коли ви явно вибираєте нативний каркас Codex через +`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`. ## Покриття можливостей OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Статус | -| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | -| Chat / Responses | провайдер моделі `openai/` | Так | -| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Harness app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | -| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і не закріплено провайдера | -| Зображення | `image_generate` | Так | -| Відео | `video_generate` | Так | -| Перетворення тексту в мовлення | `messages.tts.provider: "openai"` / `tts` | Так | -| Пакетне перетворення мовлення в текст | `tools.media.audio` / розуміння медіа | Так | -| Потокове перетворення мовлення в текст | Voice Call `streaming.provider: "openai"` | Так | -| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Embeddings | провайдер embedding для памʼяті | Так | +| Можливість OpenAI | Поверхня OpenClaw | Стан | +| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | +| Chat / Responses | провайдер моделей `openai/` | Так | +| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | +| Каркас app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | +| Серверний вебпошук | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдер не закріплено | +| Зображення | `image_generate` | Так | +| Відео | `video_generate` | Так | +| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | +| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | +| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | +| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | +| Embeddings | провайдер embedding для пам’яті | Так | ## Початок роботи -Виберіть бажаний метод автентифікації та виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - - **Найкраще для:** прямого доступу до API та оплати за використання. + + **Найкраще для:** прямого доступу до API та тарифікації за використанням. - - Створіть або скопіюйте ключ API з [панелі OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API-ключ на [панелі OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` - Або передайте ключ напряму: + Або передайте ключ безпосередньо: ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### Зведення маршрутів + ### Підсумок маршрутів - | Посилання моделі | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| - | `openai/gpt-5.5` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | Прямий OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | Прямий OpenAI Platform API | `OPENAI_API_KEY` | - `openai/*` — це прямий маршрут OpenAI за ключем API, якщо ви явно не - примусите harness app-server Codex. Використовуйте `openai-codex/*` для Codex OAuth через + `openai/*` — це прямий маршрут OpenAI API-key, якщо ви явно не примусите + використання каркаса app-server Codex. Використовуйте `openai-codex/*` для Codex OAuth через стандартний runner PI, або використовуйте `openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` для нативного виконання через app-server Codex. @@ -120,13 +121,13 @@ app-server Codex. ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не містить. - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Codex cloud вимагає входу через ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Хмарний Codex потребує входу через ChatGPT. @@ -134,13 +135,13 @@ app-server Codex. openclaw onboard --auth-choice openai-codex ``` - Або запустіть OAuth напряму: + Або запустіть OAuth безпосередньо: ```bash openclaw models auth login --provider openai-codex ``` - Для headless або несприятливих до callback конфігурацій додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера localhost: + Для headless або конфігурацій із проблемним callback-хостом додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера через localhost: ```bash openclaw models auth login --provider openai-codex --device-code @@ -151,24 +152,24 @@ app-server Codex. openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### Зведення маршрутів + ### Підсумок маршрутів - | Посилання моделі | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| - | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | Вхід Codex | - | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harness app-server Codex | Автентифікація app-server Codex | + | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex | + | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Каркас app-server Codex | автентифікація app-server Codex | - Продовжуйте використовувати id провайдера `openai-codex` для команд auth/profile. Префікс моделі + Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth. - Він не вибирає і не вмикає автоматично вбудований harness app-server Codex. + Він не вибирає і не вмикає автоматично вбудований каркас app-server Codex. ### Приклад конфігурації @@ -180,28 +181,28 @@ app-server Codex. ``` - Onboarding більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через наведений вище потік device-code — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента. + Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через наведений вище потік device-code — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. - ### Індикатор статусу + ### Індикатор стану - Chat `/status` показує, який runtime моделі активний для поточної сесії. - Стандартний harness PI відображається як `Runtime: OpenClaw Pi Default`. Коли - вибрано вбудований harness app-server Codex, `/status` показує - `Runtime: OpenAI Codex`. Наявні сесії зберігають записаний для них id harness, тож використовуйте + У чаті `/status` показує, який runtime моделі активний для поточної сесії. + Стандартний каркас PI відображається як `Runtime: OpenClaw Pi Default`. Коли + вибрано вбудований каркас app-server Codex, `/status` показує + `Runtime: OpenAI Codex`. Наявні сесії зберігають записаний для них ідентифікатор каркаса, тому використовуйте `/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. - ### Обмеження контекстного вікна + ### Обмеження вікна контексту - OpenClaw розглядає метадані моделі та обмеження контексту runtime як окремі значення. + OpenClaw розглядає метадані моделі й обмеження контексту runtime як окремі значення. Для `openai-codex/gpt-5.5` через Codex OAuth: - - Нативний `contextWindow`: `1000000` + - Нативне `contextWindow`: `1000000` - Стандартне обмеження runtime `contextTokens`: `272000` - Менше стандартне обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: + Менше стандартне обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: ```json5 { @@ -221,10 +222,10 @@ app-server Codex. ### Відновлення каталогу - OpenClaw використовує метадані каталогу Codex з upstream для `gpt-5.5`, коли вони - присутні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, поки - обліковий запис автентифіковано, OpenClaw синтезує цей рядок моделі OAuth, щоб - Cron, субагент і запуски налаштованої моделі за замовчуванням не завершувалися з + OpenClaw використовує метадані з вихідного каталогу Codex для `gpt-5.5`, коли вони + наявні. Якщо під час живого виявлення Codex пропускається рядок `openai-codex/gpt-5.5`, поки + обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб + Cron, субагент і запуски з налаштованою моделлю за замовчуванням не завершувалися помилкою `Unknown model`. @@ -232,19 +233,19 @@ app-server Codex. ## Генерація зображень -Вбудований плагін `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує як генерацію зображень OpenAI за ключем API, так і генерацію зображень -через Codex OAuth через те саме посилання моделі `openai/gpt-image-2`. +Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. +Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію зображень +через Codex OAuth із тим самим посиланням на модель `openai/gpt-image-2`. -| Можливість | Ключ API OpenAI | Codex OAuth | -| ------------------------- | ---------------------------------- | ------------------------------------ | -| Посилання моделі | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | Вхід через OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | backend Codex Responses | -| Максимум зображень на запит | 4 | 4 | -| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | -| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | -| Співвідношення сторін / роздільна здатність | Не передається в OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | +| Можливість | 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 { @@ -257,31 +258,47 @@ app-server Codex. ``` -Див. [Image Generation](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. -`gpt-image-2` є стандартною моделлю як для генерації зображень з тексту OpenAI, так і для -редагування зображень. `gpt-image-1` залишається доступною як явне перевизначення моделі, але нові -робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. +`gpt-image-2` є стандартним варіантом як для генерації зображень за текстом OpenAI, так і для +редагування зображень. `gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються доступними як +явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу PNG/WebP +із прозорим фоном; поточний API `gpt-image-2` відхиляє +`background: "transparent"`. + +Для запиту на прозорий фон агенти мають викликати `image_generate` з +`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` або `"webp"`, і +`openai.background: "transparent"`. OpenClaw також захищає публічні маршрути OpenAI та +OpenAI Codex OAuth, переписуючи стандартні прозорі запити `openai/gpt-image-2` +на `gpt-image-1.5`; Azure і користувацькі OpenAI-сумісні endpoints зберігають +налаштовані назви deployment/model. Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw знаходить цей збережений OAuth -access token і надсилає запити на зображення через backend Codex Responses. Він -не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихий перехід на ключ API для цього -запиту. Налаштуйте `models.providers.openai` явно з ключем API, -власним base URL або endpoint Azure, якщо хочете використовувати прямий маршрут OpenAI Images API +налаштовано OAuth-профіль `openai-codex`, OpenClaw знаходить збережений OAuth-токен доступу +та надсилає запити на зображення через бекенд Codex Responses. Він +не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихий fallback на API-ключ для цього +запиту. Явно налаштуйте `models.providers.openai` з API-ключем, +користувацькою базовою URL-адресою або endpoint Azure, якщо ви хочете використовувати прямий маршрут OpenAI Images API замість цього. -Якщо цей власний endpoint для зображень розміщено в довіреній LAN/приватній адресі, також установіть +Якщо цей користувацький endpoint зображень розташований у довіреній LAN/приватній адресі, також встановіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw залишає -приватні/внутрішні OpenAI-сумісні endpoint для зображень заблокованими, якщо немає цього явного дозволу. +приватні/внутрішні OpenAI-сумісні endpoints зображень заблокованими, якщо цей opt-in +не задано. -Генерація: +Згенерувати: ``` /tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` -Редагування: +Згенерувати прозорий PNG: + +``` +/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png openai='{"background":"transparent"}' +``` + +Редагувати: ``` /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 @@ -289,14 +306,14 @@ access token і надсилає запити на зображення чере ## Генерація відео -Вбудований плагін `openai` реєструє генерацію відео через інструмент `video_generate`. +Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. | Можливість | Значення | | --------------- | --------------------------------------------------------------------------------- | | Стандартна модель | `openai/sora-2` | | Режими | Текст у відео, зображення у відео, редагування одного відео | | Вхідні еталони | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -310,25 +327,25 @@ access token і надсилає запити на зображення чере ``` -Див. [Video Generation](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover. +Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. -## Внесок у prompt GPT-5 +## Внесок у промпт GPT-5 -OpenClaw додає спільний внесок у prompt GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за id моделі, тож `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні. -Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції для розробника в app-server Codex, тож сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі настанови щодо доведення до кінця та проактивного Heartbeat, навіть якщо рештою prompt harness керує Codex. +Вбудований нативний каркас Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі настанови щодо доведення задач до кінця та проактивного Heartbeat, навіть попри те, що Codex керує рештою промпта каркаса. -Внесок GPT-5 додає контракт поведінки з тегами для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей і тихих повідомлень, специфічна для каналу, залишається у спільному системному prompt OpenClaw та політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповіді й тихих повідомлень, специфічна для каналу, залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| ---------------------- | --------------------------------------------- | -| `"friendly"` (стандартно) | Увімкнути шар дружнього стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише шар дружнього стилю | +| Значення | Ефект | +| ---------------------- | ------------------------------------------ | +| `"friendly"` (стандартно) | Увімкнути рівень дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише рівень дружнього стилю | - + ```json5 { agents: { @@ -349,18 +366,18 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап -Значення нечутливі до регістру під час runtime, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю. +Під час виконання значення нечутливі до регістру, тому `"Off"` і `"off"` обидва вимикають рівень дружнього стилю. -Застаріле `plugins.entries.openai.config.personality` усе ще читається як резервний варіант для сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застаріле `plugins.entries.openai.config.personality` усе ще зчитується як сумісний fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення - Вбудований плагін `openai` реєструє синтез мовлення для поверхні `messages.tts`. + Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. | Параметр | Шлях конфігурації | Стандартно | |---------|------------|---------| @@ -369,7 +386,7 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | Ключ API | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | 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`. @@ -387,19 +404,19 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS без впливу на endpoint Chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS без впливу на endpoint chat API. - - Вбудований плагін `openai` реєструє пакетне перетворення мовлення в текст через - поверхню транскрибування розуміння медіа OpenClaw. + + Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через + поверхню транскрибування для розуміння медіа в OpenClaw. - Стандартна модель: `gpt-4o-transcribe` - - Endpoint: REST `OpenAI` `/v1/audio/transcriptions` - - Шлях введення: multipart-завантаження аудіофайлу - - Підтримується в OpenClaw всюди, де вхідне транскрибування аудіо використовує + - Endpoint: OpenAI REST `/v1/audio/transcriptions` + - Вхідний шлях: multipart-вивантаження аудіофайлу + - Підтримується в OpenClaw всюди, де транскрибування вхідного аудіо використовує `tools.media.audio`, зокрема для сегментів голосових каналів Discord і аудіовкладень каналів @@ -423,31 +440,31 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап } ``` - Підказки щодо мови та prompt передаються в OpenAI, коли вони задаються - спільною конфігурацією аудіомедіа або запитом на транскрибування для окремого виклику. + Підказки мови та промпта передаються до OpenAI, коли їх надає + спільна конфігурація аудіомедіа або запит транскрибування для окремого виклику. - Вбудований плагін `openai` реєструє транскрибування в реальному часі для плагіна Voice Call. + Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. | Параметр | Шлях конфігурації | Стандартно | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | - | Prompt | `...openai.prompt` | (не задано) | + | Промпт | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | Ключ API | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | - Використовує зʼєднання WebSocket із `wss://api.openai.com/v1/realtime` з аудіо формату G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі плагіна Voice Call; Discord voice наразі записує короткі сегменти й натомість використовує шлях пакетного транскрибування `tools.media.audio`. + Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі у Voice Call; голос Discord наразі записує короткі сегменти та натомість використовує пакетний шлях транскрибування `tools.media.audio`. - Вбудований плагін `openai` реєструє голос у реальному часі для плагіна Voice Call. + Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. | Параметр | Шлях конфігурації | Стандартно | |---------|------------|---------| @@ -456,40 +473,41 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | Ключ API | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law. -## Endpoint Azure OpenAI +## Endpoint-и Azure OpenAI -Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для генерації -зображень через перевизначення base URL. На шляху генерації зображень OpenClaw -виявляє імена хостів Azure в `models.providers.openai.baseUrl` і автоматично -перемикається на формат запиту Azure. +Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для +генерації зображень шляхом перевизначення базової URL-адреси. На шляху генерації зображень OpenClaw +визначає хостнейми Azure у `models.providers.openai.baseUrl` і автоматично перемикається на +форму запиту Azure. Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і на нього не впливає `models.providers.openai.baseUrl`. Див. accordion **Голос у реальному -часі** в розділі [Голос і мовлення](#voice-and-speech), щоб дізнатися про його налаштування Azure. +і на нього не впливає `models.providers.openai.baseUrl`. Див. акордеон **Голос +у реальному часі** в розділі [Голос і мовлення](#voice-and-speech) для його параметрів +Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка, квота або корпоративна угода Azure OpenAI -- Вам потрібне регіональне зберігання даних або засоби контролю відповідності, які надає Azure -- Ви хочете зберігати трафік у межах наявного tenancy Azure +- У вас уже є підписка Azure OpenAI, квота або корпоративна угода +- Вам потрібна регіональна резидентність даних або механізми відповідності, які надає Azure +- Ви хочете зберегти трафік у межах наявного tenancy Azure ### Конфігурація -Для генерації зображень через Azure у вбудованому провайдері `openai` укажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` як -ключ Azure OpenAI (а не ключ OpenAI Platform): +Для генерації зображень через Azure за допомогою вбудованого провайдера `openai` укажіть +`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` у значення +ключа Azure OpenAI (не ключа OpenAI Platform): ```json5 { @@ -504,7 +522,7 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап } ``` -OpenClaw розпізнає ці суфікси хостів Azure для маршруту генерації зображень Azure: +OpenClaw розпізнає такі суфікси хостів Azure для маршруту Azure генерації зображень: - `*.openai.azure.com` - `*.services.ai.azure.com` @@ -513,16 +531,16 @@ OpenClaw розпізнає ці суфікси хостів Azure для мар Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи з областю deployment (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Інші base URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний -формат запиту OpenAI для зображень. +Інші base URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну +форму запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень у провайдері `openai` -потребує OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який власний -`openai.baseUrl` як публічний endpoint OpenAI і завершаться помилкою при роботі з deployment +Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує +OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який користувацький +`openai.baseUrl` як публічний endpoint OpenAI і не працюватимуть з deployment-ами зображень Azure. @@ -535,68 +553,68 @@ OpenClaw розпізнає ці суфікси хостів Azure для мар export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Стандартне значення — `2024-12-01-preview`, коли змінну не встановлено. +Стандартне значення — `2024-12-01-preview`, якщо змінну не задано. ### Назви моделей — це назви deployment -Azure OpenAI привʼязує моделі до deployment. Для запитів генерації зображень Azure, +Azure OpenAI прив’язує моделі до deployment-ів. Для запитів генерації зображень Azure, маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не -публічним id моделі OpenAI. +публічним ідентифікатором моделі OpenAI. -Якщо ви створили deployment із назвою `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="A clean poster" size=1024x1024 count=1 ``` -Те саме правило назв deployment застосовується до викликів генерації зображень, -маршрутизованих через вбудований провайдер `openai`. +Те саме правило назв deployment застосовується до викликів генерації зображень, маршрутизованих через +вбудований провайдер `openai`. ### Регіональна доступність -Генерація зображень Azure наразі доступна лише в підмножині регіонів +Наразі генерація зображень Azure доступна лише в частині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, `uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням -deployment і підтвердьте, що конкретна модель доступна у вашому регіоні. +deployment, а також підтвердьте, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. -Azure може відхиляти опції, які дозволяє публічний OpenAI (наприклад певні -значення `background` у `gpt-image-2`) або надавати їх лише для певних версій -моделей. Ці відмінності походять від Azure і базової моделі, а не від -OpenClaw. Якщо запит до Azure завершується помилкою валідації, перевірте +Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні +значення `background` у `gpt-image-2`) або надавати їх лише в конкретних +версіях моделей. Ці відмінності походять від Azure і базової моделі, а не від +OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте набір параметрів, який підтримується вашим конкретним deployment і версією API в порталі Azure. -Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує -прихованих заголовків attribution від OpenClaw — див. accordion **Нативні vs OpenAI-compatible -маршрути** в розділі [Розширена конфігурація](#advanced-configuration). +Azure OpenAI використовує нативну транспортну та сумісну поведінку, але не отримує +приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні +маршрути** у розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses в Azure (крім генерації зображень) використовуйте -потік onboarding або окрему конфігурацію провайдера Azure — одного лише -`openai.baseUrl` недостатньо, щоб застосувати формат API/автентифікації Azure. Існує окремий +Для трафіку chat або Responses на Azure (поза генерацією зображень) використовуйте +потік онбордингу або окрему конфігурацію провайдера Azure — одного лише `openai.baseUrl` +недостатньо, щоб підхопити форму API/автентифікації Azure. Існує окремий провайдер `azure-openai-responses/*`; див. -accordion про server-side Compaction нижче. +акордеон Server-side compaction нижче. ## Розширена конфігурація - - OpenClaw використовує WebSocket-first із резервним переходом на SSE (`"auto"`) для `openai/*` і `openai-codex/*`. + + OpenClaw використовує спочатку WebSocket із fallback на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - Повторює одну ранню помилку WebSocket перед переходом на SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час періоду охолодження + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - Додає стабільні заголовки ідентичності сесії та ходу для повторів і перепідключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (стандартно) | Спочатку WebSocket, резервно SSE | + | `"auto"` (стандартно) | Спочатку WebSocket, fallback на SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -617,17 +635,17 @@ accordion про server-side Compaction нижче. } ``` - Повʼязані docs 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) - - OpenClaw за замовчуванням вмикає прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. + + OpenClaw за замовчуванням вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. ```json5 - // Disable warm-up + // Вимкнути прогрівання { agents: { defaults: { @@ -643,13 +661,13 @@ accordion про server-side Compaction нижче. - - OpenClaw надає спільний перемикач fast mode для `openai/*` і `openai-codex/*`: + + OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - **Chat/UI:** `/fast status|on|off` - - **Config:** `agents.defaults.models["/"].params.fastMode` + - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли він увімкнений, OpenClaw зіставляє fast mode з пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а fast mode не переписує `reasoning` або `text.verbosity`. + Коли його ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. ```json5 { @@ -664,13 +682,13 @@ accordion про server-side Compaction нижче. ``` - Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до стандартного налаштування з конфігурації. + Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до стандартного налаштованого значення. - API OpenAI надає пріоритетну обробку через `service_tier`. Задавайте її для кожної моделі в OpenClaw: + API OpenAI надає пріоритетну обробку через `service_tier`. Установлюйте її для кожної моделі в OpenClaw: ```json5 { @@ -687,23 +705,23 @@ accordion про server-side Compaction нижче. Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних endpoint OpenAI (`api.openai.com`) і нативних endpoint Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних endpoint-ів OpenAI (`api.openai.com`) і нативних endpoint-ів Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. - - Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) stream wrapper Pi-harness плагіна OpenAI автоматично вмикає server-side Compaction: + + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness плагіна OpenAI автоматично вмикає Server-side 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`, коли він недоступний) - Це застосовується до вбудованого шляху harness Pi і до хуків провайдера OpenAI, які використовуються в embedded-запусках. Нативний harness app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. + Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, які використовуються в embedded-запусках. Нативний каркас app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. - Корисно для сумісних endpoint, таких як Azure OpenAI Responses: + Корисно для сумісних endpoint-ів, таких як Azure OpenAI Responses: ```json5 { @@ -719,7 +737,7 @@ accordion про server-side Compaction нижче. } ``` - + ```json5 { agents: { @@ -755,7 +773,7 @@ accordion про server-side Compaction нижче. - `responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses усе одно примусово встановлюють `store: true`, якщо compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. @@ -773,44 +791,44 @@ accordion про server-side Compaction нижче. } ``` - Із `strict-agentic` OpenClaw: + З `strict-agentic` OpenClaw: - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - - Повторює хід зі спрямуванням діяти негайно + - Повторює хід із настановою діяти зараз - Автоматично вмикає `update_plan` для суттєвої роботи - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Застосовується лише до OpenAI і Codex запусків сімейства GPT-5. Інші провайдери та старіші сімейства моделей зберігають стандартну поведінку. + Поширюється лише на запуски сімейства GPT-5 OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають стандартну поведінку. - - OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI порівняно з загальними OpenAI-compatible проксі `/v1`: + + OpenClaw по-різному обробляє прямі endpoints OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують `none` effort у OpenAI + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - За замовчуванням використовують strict mode для схем інструментів - - Додають приховані заголовки attribution лише на перевірених нативних хостах - - Зберігають формування запитів, властиве лише OpenAI (`service_tier`, `store`, compat reasoning, підказки кешу prompt) + - За замовчуванням встановлюють строгий режим для схем інструментів + - Додають приховані заголовки атрибуції лише на перевірених нативних хостах + - Зберігають форму запитів, специфічну для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів) **Проксі/сумісні маршрути:** - - Використовують мʼякшу поведінку compat - - Видаляють Completions `store` із ненативних payload `openai-completions` - - Приймають наскрізний JSON `params.extra_body`/`params.extraBody` для розширених параметрів OpenAI-compatible проксі Completions - - Не примушують strict-схеми інструментів або нативні заголовки + - Використовують м’якшу сумісну поведінку + - Видаляють Completions `store` з ненативних payload `openai-completions` + - Приймають розширену наскрізну JSON-передачу `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions + - Не примушують до строгих схем інструментів або заголовків лише для нативних маршрутів - Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує прихованих заголовків attribution. + Azure OpenAI використовує нативну транспортну та сумісну поведінку, але не отримує приховані заголовки атрибуції. -## Повʼязане +## Пов’язане - Вибір провайдерів, посилань моделей і поведінки failover. + Вибір провайдерів, посилань на моделі та поведінки failover. Спільні параметри інструмента зображень і вибір провайдера. @@ -819,6 +837,6 @@ accordion про server-side Compaction нижче. Спільні параметри інструмента відео і вибір провайдера. - Деталі автентифікації та правила повторного використання облікових даних. + Докладно про автентифікацію та правила повторного використання облікових даних. diff --git a/docs/uk/tools/image-generation.md b/docs/uk/tools/image-generation.md index eb769e9b5..76c22c356 100644 --- a/docs/uk/tools/image-generation.md +++ b/docs/uk/tools/image-generation.md @@ -1,29 +1,29 @@ --- read_when: - - Генерування зображень через агента - - Налаштування провайдерів і моделей для генерування зображень + - Генерація зображень через агента + - Налаштування провайдерів і моделей для генерації зображень - Розуміння параметрів інструмента `image_generate` summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, OpenRouter, LiteLLM, fal, MiniMax, ComfyUI, Vydra, xAI) title: Генерація зображень x-i18n: - generated_at: "2026-04-25T18:14:47Z" + generated_at: "2026-04-25T18:33:42Z" model: gpt-5.4 provider: openai - source_hash: 40ec0e9a004e769b3db8b98b1a687097cb4bc6aa78dc903e4f6a17c3731156c0 + source_hash: 787624476525ff5b8ed7d62a7cb0bac473cc9671136daf10f41d668ef2ddf3c5 source_path: tools/image-generation.md workflow: 15 --- -Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента. +Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою ваших налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента. -Інструмент з’являється лише тоді, коли доступний щонайменше один провайдер генерування зображень. Якщо ви не бачите `image_generate` у списку інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth. +Інструмент з’являється лише тоді, коли доступний щонайменше один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, укажіть API-ключ провайдера або увійдіть через OpenAI Codex OAuth. ## Швидкий старт -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 { @@ -31,7 +31,7 @@ x-i18n: defaults: { imageGenerationModel: { primary: "openai/gpt-image-2", - // Необов’язковий типовий тайм-аут запиту провайдера для image_generate. + // Необов’язковий типовий тайм-аут запиту до провайдера для image_generate. timeoutMs: 180_000, }, }, @@ -39,51 +39,40 @@ 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, збережіть користувацький -`models.providers.openai.baseUrl` і явно ввімкніть -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні -ендпоінти зображень типово залишаються заблокованими. +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, зберігайте власний `models.providers.openai.baseUrl` і явно вмикайте це через `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні ендпойнти зображень за замовчуванням залишаються заблокованими. 3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_ -Агент автоматично викликає `image_generate`. Жодного allow-list для інструментів не потрібно — він увімкнений типово, коли провайдер доступний. +Агент автоматично викликає `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` | -| Генерування зображень LiteLLM | `litellm/gpt-image-2` | `LITELLM_API_KEY` | -| Генерування зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | +| Ціль | Посилання на модель | Автентифікація | +| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------- | +| Генерація зображень OpenAI з оплатою через API | `openai/gpt-image-2` | `OPENAI_API_KEY` | +| Генерація зображень OpenAI з автентифікацією за підпискою Codex | `openai/gpt-image-2` | OpenAI Codex OAuth | +| OpenAI PNG/WebP із прозорим тлом | `openai/gpt-image-1.5` | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| Генерація зображень OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | +| Генерація зображень LiteLLM | `litellm/gpt-image-2` | `LITELLM_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`, передаються далі, коли це можливо, і позначаються як -проігноровані, якщо провайдер їх не підтримує. +Той самий інструмент `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` | -| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_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` | +| Провайдер | Типова модель | Підтримка редагування | Автентифікація | +| --------- | -------------------------------------- | ----------------------------------- | ----------------------------------------------------- | +| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` | +| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_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 @@ -92,19 +81,19 @@ Codex OAuth використовує те саме посилання на мо ## Параметри інструмента -Промпт для генерування зображення. Обов’язковий для `action: "generate"`. +Підказка для генерації зображення. Обов’язкова для `action: "generate"`. -Використовуйте `"list"`, щоб переглянути доступні провайдери й моделі під час виконання. +Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання. -Перевизначення провайдера/моделі, наприклад `openai/gpt-image-2`. +Перевизначення провайдера/моделі, наприклад `openai/gpt-image-2`; використовуйте `openai/gpt-image-1.5` для прозорого тла OpenAI. -Шлях або URL одного еталонного зображення для режиму редагування. +Шлях до одного еталонного зображення або URL для режиму редагування. @@ -112,7 +101,7 @@ Codex OAuth використовує те саме посилання на мо -Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. +Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. @@ -120,36 +109,36 @@ Codex OAuth використовує те саме посилання на мо -Підказка роздільної здатності. +Підказка щодо роздільної здатності. -Підказка якості, якщо провайдер її підтримує. +Підказка щодо якості, якщо провайдер її підтримує. -Підказка формату виходу, якщо провайдер її підтримує. +Підказка щодо формату виводу, якщо провайдер її підтримує. -Кількість зображень для генерування (1–4). +Кількість зображень для генерації (1–4). -Необов’язковий тайм-аут запиту провайдера в мілісекундах. +Необов’язковий тайм-аут запиту до провайдера в мілісекундах. -Підказка імені вихідного файлу. +Підказка щодо імені вихідного файла. Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`. -Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед відправленням переналаштовує запит до найближчого підтримуваного розміру, співвідношення сторін або роздільної здатності. Непідтримувані підказки виходу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не заявляють такої підтримки, і зазначаються в результаті інструмента. +Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед відправленням зіставляє його з найближчим підтримуваним `size`, `aspectRatio` або `resolution`. Непідтримувані підказки виводу, як-от `quality` або `outputFormat`, відкидаються для провайдерів, які не декларують їх підтримку, і відображаються в результаті інструмента. -Результати інструмента показують застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час резервного переходу між провайдерами, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. +Результати інструмента показують застосовані налаштування. Коли OpenClaw змінює геометрію під час резервного переходу між провайдерами, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. ## Конфігурація @@ -175,35 +164,29 @@ Codex OAuth використовує те саме посилання на мо ### Порядок вибору провайдера -Під час генерування зображення OpenClaw пробує провайдерів у такому порядку: +Під час генерації зображення OpenClaw пробує провайдерів у такому порядку: 1. **Параметр `model`** з виклику інструмента (якщо агент його вказує) 2. **`imageGenerationModel.primary`** з конфігурації 3. **`imageGenerationModel.fallbacks`** у заданому порядку 4. **Автовизначення** — використовує лише типові значення провайдерів, підкріплені автентифікацією: - спочатку поточний типовий провайдер - - потім решта зареєстрованих провайдерів генерування зображень у порядку provider-id + - далі решта зареєстрованих провайдерів генерації зображень у порядку `provider-id` -Якщо провайдер не спрацьовує (помилка автентифікації, обмеження швидкості тощо), автоматично пробується наступний налаштований кандидат. Якщо не спрацьовують усі, помилка містить деталі кожної спроби. +Якщо провайдер завершується помилкою (помилка автентифікації, обмеження швидкості тощо), автоматично пробується наступний налаштований кандидат. Якщо всі завершаться помилкою, помилка міститиме подробиці кожної спроби. Примітки: -- Перевизначення `model` для окремого виклику є точним: OpenClaw пробує лише цю пару провайдер/модель - і не переходить далі до налаштованих primary/fallback або автовизначених - провайдерів. -- Автовизначення враховує автентифікацію. Типове значення провайдера потрапляє до списку кандидатів - лише тоді, коли OpenClaw справді може автентифікувати цей провайдер. -- Автовизначення типово ввімкнене. Установіть - `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень - використовувала лише явні записи `model`, `primary` і `fallbacks`. +- Перевизначення `model` для окремого виклику є точним: OpenClaw пробує лише цього провайдера/цю модель і не переходить далі до налаштованого primary/fallback або автовизначених провайдерів. +- Автовизначення враховує автентифікацію. Типовий провайдер потрапляє до списку кандидатів лише тоді, коли OpenClaw справді може автентифікуватися в цього провайдера. +- Автовизначення ввімкнено за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`. - Установіть `agents.defaults.imageGenerationModel.timeoutMs` для повільних бекендів зображень. - Параметр інструмента `timeoutMs` для окремого виклику перевизначає налаштоване типове значення. -- Використовуйте `action: "list"`, щоб переглянути наразі зареєстрованих провайдерів, їхні - типові моделі та підказки щодо env var для автентифікації. + Параметр інструмента `timeoutMs` для окремого виклику перевизначає налаштоване значення за замовчуванням. +- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні типові моделі та підказки щодо env-змінних для автентифікації. ### Редагування зображень -OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування еталонних зображень. Передайте шлях або URL еталонного зображення: +OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування еталонних зображень. Передайте шлях до еталонного зображення або URL: ``` "Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg" @@ -213,7 +196,7 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 еталонни ### Моделі зображень OpenRouter -Генерування зображень OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через image API chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом `openrouter/`: +Генерація зображень OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через image API chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом `openrouter/`: ```json5 { @@ -231,26 +214,11 @@ OpenClaw передає до OpenRouter `prompt`, `count`, еталонні зо ### OpenAI `gpt-image-2` -Генерування зображень OpenAI типово використовує `openai/gpt-image-2`. Якщо -налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, -що й для чат-моделей за підпискою Codex, і надсилає запит на зображення -через бекенд Codex Responses. Застарілі base URL Codex, такі як -`https://chatgpt.com/backend-api`, канонікалізуються до -`https://chatgpt.com/backend-api/codex` для запитів на зображення. Для такого запиту він не -переходить мовчки до `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. Застарілі базові URL Codex, як-от `https://chatgpt.com/backend-api`, канонізуються до `https://chatgpt.com/backend-api/codex` для запитів на зображення. Для такого запиту немає безшумного резервного переходу на `OPENAI_API_KEY`. Щоб примусово використовувати пряме маршрутизування через OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, власним base URL або ендпойнтом Azure. Моделі `openai/gpt-image-1.5`, `openai/gpt-image-1` і `openai/gpt-image-1-mini` усе ще можна явно вибрати. Використовуйте `gpt-image-1.5` для виводу PNG/WebP із прозорим тлом; поточний API `gpt-image-2` відхиляє `background: "transparent"`. -`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 { @@ -265,78 +233,92 @@ OpenClaw відображає їх у підтримуваний `size`, іна } ``` -`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорі -вихідні дані потребують `outputFormat` `png` або `webp`. `openai.outputCompression` -застосовується до виходів JPEG/WebP. +`openai.background` приймає значення `transparent`, `opaque` або `auto`; для прозорого виводу потрібні `outputFormat` `png` або `webp` і модель зображень OpenAI з підтримкою прозорості. OpenClaw спрямовує запити на прозоре тло для типового `gpt-image-2` до `gpt-image-1.5`. `openai.outputCompression` застосовується до виводу JPEG/WebP. + +Коли ви просите агента створити зображення OpenAI з прозорим тлом, очікуваний виклик інструмента має такий вигляд: + +```json +{ + "model": "openai/gpt-image-1.5", + "prompt": "Проста червона кругла наліпка на прозорому тлі", + "outputFormat": "png", + "openai": { + "background": "transparent" + } +} +``` + +Явна модель `openai/gpt-image-1.5` зберігає переносимість запиту між зведеннями інструментів і harnesses. Якщо агент натомість використовує типовий `openai/gpt-image-2` з `openai.background: "transparent"` у публічному маршруті OpenAI або OpenAI Codex OAuth, OpenClaw переписує запит до провайдера на `gpt-image-1.5`. Azure та користувацькі OpenAI-сумісні ендпойнти зберігають свої налаштовані назви deployment/model. Згенерувати одне ландшафтне зображення 4K: ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Чистий редакційний постер для генерації зображень OpenClaw" size=3840x2160 count=1 +``` + +Згенерувати прозорий PNG: + +``` +/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="Проста червона кругла наліпка на прозорому тлі" outputFormat=png openai='{"background":"transparent"}' ``` Згенерувати два квадратні зображення: ``` -/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="Два візуальні напрями для іконки спокійного застосунку продуктивності" 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="Зберегти об’єкт, замінити тло на яскраву студійну постановку" 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 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Поєднати ідентичність персонажа з першого зображення з палітрою кольорів із другого" 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) -у документації провайдера OpenAI. +Щоб спрямувати генерацію зображень OpenAI через deployment Azure OpenAI замість `api.openai.com`, див. [ендпойнти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) у документації провайдера OpenAI. -Генерування зображень MiniMax доступне через обидва вбудовані шляхи автентифікації MiniMax: +Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax: - `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 зображень) | -| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | -| Співвідношення сторін | Ні | Так | Так (лише генерування) | Так | Ні | Ні | Так | +| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | +| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | +| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виводи, визначені workflow) | Так (1) | Так (до 4) | +| Редагування/еталон | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, еталон об’єкта) | Так (1 зображення, налаштоване у workflow) | Ні | Так (до 5 зображень) | +| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | +| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так | | Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | ### xAI `grok-imagine-image` -Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з промптом -і `/v1/images/edits`, коли присутній `image` або `images`. +Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`. - Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro` - Кількість: до 4 - Еталони: один `image` або до п’яти `images` - Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` -- Роздільна здатність: `1K`, `2K` -- Виходи: повертаються як вкладення зображень, керовані OpenClaw +- Роздільні здатності: `1K`, `2K` +- Вивід: повертається як вкладення зображень, керовані OpenClaw -OpenClaw навмисно не відкриває нативні для xAI `quality`, `mask`, `user` або -додаткові співвідношення сторін, доступні лише нативно, доки ці елементи керування не з’являться у спільному -міжпровайдерному контракті `image_generate`. +OpenClaw навмисно не відкриває специфічні для xAI параметри `quality`, `mask`, `user` або додаткові власні співвідношення сторін, доки ці елементи керування не з’являться у спільному міжпровайдерному контракті `image_generate`. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента - [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal -- [ComfyUI](/uk/providers/comfy) — налаштування локального workflow ComfyUI і Comfy Cloud +- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та Comfy Cloud workflow - [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini - [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax - [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images - [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra -- [xAI](/uk/providers/xai) — налаштування зображень, відео, пошуку, виконання коду та TTS Grok -- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel` -- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання на резервні варіанти +- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS +- [Довідник з конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel` +- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання на резервний варіант