From 235a2123bfe14428afa815c5162ab11a26d340f6 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 02:00:53 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/config-agents.md | 469 +++++++++--------- .../reference/secretref-credential-surface.md | 37 +- docs/uk/tools/tts.md | 420 +++++++++------- 3 files changed, 489 insertions(+), 437 deletions(-) diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index cea3229fd..6fe40e772 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -2,19 +2,19 @@ read_when: - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування поведінки сесії, доставки повідомлень і режиму talk -summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk + - Налаштування сесії, доставки повідомлень і поведінки режиму розмови +summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація розмови title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-26T01:42:40Z" + generated_at: "2026-04-26T01:57:30Z" model: gpt-5.4 provider: openai - source_hash: 2c2027d1abd522c88ad91b2f9596a1aa27da3af8d87fddf42919119c75490060 + source_hash: 3a8f81a33185cd98dd3623cbd676806918937880db57cc36ae34292c0891d4f0 source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`, `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, рухаючись угору від робочого простору. +Необов’язковий кореневий каталог репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. ```json5 { @@ -42,7 +42,7 @@ x-i18n: ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, які не задають +Необов’язковий типовий allowlist Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -52,7 +52,7 @@ x-i18n: list: [ { id: "writer" }, // успадковує github, weather { id: "docs", skills: ["docs-search"] }, // замінює типові значення - { id: "locked-down", skills: [] }, // без Skills + { id: "locked-down", skills: [] }, // без skills ], }, } @@ -60,9 +60,9 @@ x-i18n: - Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. - Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Укажіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. -- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він - не об’єднується з типовими значеннями. +- Установіть `agents.list[].skills: []`, щоб не було Skills. +- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; + він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -78,8 +78,8 @@ x-i18n: Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне додавання bootstrap-контексту робочого простору, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. -- `"never"`: вимикає додавання bootstrap-файлів робочого простору та контекстних файлів на кожному ході. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, що самі формують контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають додавання контексту. +- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-даних робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"never"`: вимикає додавання bootstrap-даних робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, що самі формують свій контекст, або спеціалізовані bootstrap-free сценарії). Ходи Heartbeat і відновлення після Compaction також пропускають додавання. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів для кожного bootstrap-файлу робочого простору перед обрізанням. Типове значення: `12000`. +Максимальна кількість символів для одного bootstrap-файлу робочого простору до обрізання. Типове значення: `12000`. ```json5 { @@ -109,12 +109,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. +Керує текстом попередження, видимим агенту, коли bootstrap-контекст обрізається. Типове значення: `"once"`. - `"off"`: ніколи не додає текст попередження до системного запиту. -- `"once"`: додає попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). -- `"always"`: додає попередження під час кожного запуску, якщо є обрізання. +- `"once"`: додає попередження один раз для кожного унікального сигнатурного варіанта обрізання (рекомендовано). +- `"always"`: додає попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -122,7 +122,7 @@ x-i18n: } ``` -### Карта власності бюджетів контексту +### Карта володіння бюджетом контексту OpenClaw має кілька великих бюджетів запиту/контексту, і вони навмисно розділені за підсистемами, а не проходять через один загальний @@ -130,16 +130,16 @@ OpenClaw має кілька великих бюджетів запиту/кон - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне додавання bootstrap-контексту робочого простору. + звичайне додавання bootstrap-даних робочого простору. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, включно з нещодавніми - файлами `memory/*.md`. + одноразова стартова преамбула для `/new` і `/reset`, зокрема нещодавні щоденні + файли `memory/*.md`. - `skills.limits.*`: компактний список Skills, що додається до системного запиту. - `agents.defaults.contextLimits.*`: - обмежені уривки середовища виконання та додані блоки, що належать середовищу виконання. + обмежені витяги середовища виконання та додані блоки, що належать середовищу виконання. - `memory.qmd.limits.*`: - розмір фрагментів і додавання під час пошуку в індексованій пам’яті. + розмір фрагментів індексованого пошуку в пам’яті та їх додавання. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -149,7 +149,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, яка додається під час звичайних запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, що додається під час звичайних запусків `/new` і `/reset`. ```json5 { @@ -187,14 +187,13 @@ OpenClaw має кілька великих бюджетів запиту/кон } ``` -- `memoryGetMaxChars`: типове обмеження уривка `memory_get` перед додаванням - метаданих обрізання та сповіщення про продовження. +- `memoryGetMaxChars`: типове обмеження витягу `memory_get` до додавання метаданих + обрізання та сповіщення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` не вказано. -- `toolResultMaxChars`: поточне обмеження результату інструмента, що використовується для збережених результатів і +- `toolResultMaxChars`: активне обмеження результату інструмента, яке використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: обмеження уривка `AGENTS.md`, що використовується під час додавання - оновлення після Compaction. +- `postCompactionMaxChars`: обмеження витягу `AGENTS.md`, що використовується під час оновлення з додаванням після Compaction. #### `agents.list[].contextLimits` @@ -240,7 +239,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету запиту Skills. +Перевизначення бюджету запиту Skills для окремого агента. ```json5 { @@ -259,10 +258,10 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. +Максимальний розмір у пікселях для довшого боку зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для сценаріїв із великою кількістю скриншотів. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір тіла запиту в сценаріях із великою кількістю знімків екрана. Вищі значення зберігають більше візуальних деталей. ```json5 @@ -273,7 +272,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -323,7 +322,7 @@ OpenClaw має кілька великих бюджетів запиту/кон }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | зареєстрований ідентифікатор harness, наприклад codex + runtime: "pi", // pi | auto | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -342,52 +341,52 @@ OpenClaw має кілька великих бюджетів запиту/кон - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей. + - Форма об’єкта задає основну модель і впорядкований список моделей для failover. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструментів/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `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` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. + - Якщо ви вибираєте `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` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.6`. - - Якщо параметр не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API key. + - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації музики в порядку `provider-id`. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо параметр не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API key. + - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації відео в порядку `provider-id`. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделей. - - Якщо параметр не вказано, інструмент PDF використовує резервний перехід до `imageModel`, а потім до визначеної моделі сесії/типової моделі. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, якщо `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного вилучення в інструменті `pdf`. -- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. + - Використовується інструментом `pdf` для маршрутизації моделі. + - Якщо не вказано, інструмент PDF спочатку використовує `imageModel`, а потім — визначену модель сесії/типову модель. +- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в резервному режимі витягування інструмента `pdf`. +- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API key або `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-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг серед налаштованих провайдерів для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель, а не показує застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відхиляє заміни, які видалили б наявні записи allowlist, якщо не передати `--replace`. + - Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштовані, але не пов’язані провайдери. + - Для прямих моделей OpenAI Responses автоматично вмикається серверний Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавати `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Порядок пріоритету об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений pass-through JSON, який об’єднується з тілами запитів `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`, типово працюють у режимі 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` (для відповідного `agent id`) перевизначає за ключем. Подробиці див. у [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений pass-through JSON, який об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, пріоритет має додаткове тіло; не нативні маршрути completions після цього все одно видаляють OpenAI-специфічний `store`. +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` не вказано, за замовчуванням використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Явні runtime Plugin, такі як `codex`, за замовчуванням завершуються помилкою без резервного переходу, якщо ви не задасте `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси провайдера runtime. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. +- Засоби запису конфігурації, що змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів у всіх сесіях (кожна окрема сесія все одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. У більшості розгортань слід залишати типове середовище виконання OpenClaw Pi. Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований -harness сервера застосунку Codex. Для розуміння моделі див. -[Середовища виконання агента](/uk/concepts/agent-runtimes). +Codex app-server harness. Для розуміння моделі див. +[Середовища виконання агентів](/uk/concepts/agent-runtimes). ```json5 { @@ -403,12 +402,12 @@ 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 завжди відображаються безпосередньо. +- `runtime`: `"auto"`, `"pi"` або зареєстрований ідентифікатор Plugin harness. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. Для `runtime: "auto"` пропущений `fallback` за замовчуванням дорівнює `"pi"`, щоб старі конфігурації й далі могли використовувати PI, коли жоден Plugin harness не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущений `fallback` за замовчуванням дорівнює `"none"`, щоб відсутність harness призводила до помилки, а не до непомітного використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` поруч із явним runtime, якщо вам свідомо потрібна така сумісність. Помилки вибраного Plugin harness завжди повертаються напряму. - Перевизначення через змінні середовища: `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 закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без зафіксованого pin, вважаються закріпленими за PI. `/status` повідомляє ефективний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS, як і раніше, використовують свої налаштування провайдера/моделі. +- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності ви також можете явно задати `embeddedHarness.fallback: "none"`; це типове значення для явних runtime Plugin. +- Вибір harness фіксується для кожного ідентифікатора сесії після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує фактичний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео і TTS, як і раніше, використовують власні налаштування провайдера/моделі. **Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): @@ -423,15 +422,15 @@ harness сервера застосунку Codex. Для розуміння м | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Налаштовані вами alias завжди мають пріоритет над типовими. +Ваші налаштовані 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 типово використовується thinking `adaptive`, якщо явний рівень 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 за замовчуванням використовується `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові бекенди CLI для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. +Необов’язкові CLI-бекенди для резервних текстових запусків (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -449,7 +448,7 @@ harness сервера застосунку Codex. Для розуміння м sessionArg: "--session", sessionMode: "existing", systemPromptArg: "--system", - // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець для файла запиту. + // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець для файлу запиту. systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -460,13 +459,13 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- Бекенди CLI орієнтовані насамперед на текст; інструменти завжди вимкнені. +- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. - Сесії підтримуються, якщо задано `sessionArg`. -- Передавання зображень підтримується, якщо `imageArg` приймає шляхи до файлів. +- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -496,9 +495,9 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `"friendly"` (типове значення) і `"on"` вмикають дружній шар стилю взаємодії. +- `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. - `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано. +- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо це спільне налаштування не задано. ### `agents.defaults.heartbeat` @@ -512,12 +511,12 @@ harness сервера застосунку Codex. Для розуміння м every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типове значення: true; false не додає розділ Heartbeat до системного запиту - lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору + includeSystemPromptSection: true, // типове значення: true; false прибирає розділ Heartbeat із системного запиту + lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md з bootstrap-файлів робочого простору isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (типово) | block + directPolicy: "allow", // allow (типове значення) | block target: "none", // типове значення: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, @@ -529,15 +528,15 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо `false`, не додає розділ Heartbeat до системного запиту й пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. -- `suppressToolErrorWarnings`: якщо `true`, приховує payload-и попереджень про помилки інструментів під час запусків 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 виконує повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: коли `false`, прибирає розділ Heartbeat із системного запиту та пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли `true`, пригнічує попередження про помилки інструментів під час запусків heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (типове значення) дозволяє доставку на пряму ціль. `block` блокує доставку на пряму ціль і генерує `reason=dm-blocked`. +- `lightContext`: коли `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: коли `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**. +- Heartbeat запускають повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -547,7 +546,7 @@ harness сервера застосунку Codex. Для розуміння м defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id зареєстрованого Plugin провайдера Compaction (необов’язково) + provider: "my-provider", // id зареєстрованого Plugin-провайдера Compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, @@ -556,7 +555,7 @@ harness сервера застосунку Codex. Для розуміння м qualityGuard: { enabled: true, maxRetries: 1 }, postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction - notifyUser: true, // надсилати короткі сповіщення користувачу, коли Compaction починається і завершується (типове значення: false) + notifyUser: true, // надсилати короткі сповіщення, коли Compaction починається і завершується (типове значення: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -569,21 +568,21 @@ 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`: перевірки з повторною спробою для malformed output у підсумках 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`: 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 для збереження довготривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Очищає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -607,25 +606,25 @@ harness сервера застосунку Codex. Для розуміння м -- `mode: "cache-ttl"` вмикає проходи очищення. -- `ttl` керує тим, як часто очищення може запускатися знову (після останнього торкання кешу). -- Очищення спочатку м’яко обрізає завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. +- `mode: "cache-ttl"` вмикає проходи обрізання. +- `ttl` керує тим, як часто обрізання може виконуватися повторно (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента заповнювачем. +**Повне очищення** замінює весь результат інструмента на placeholder. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, очищення пропускається. +- Блоки зображень ніколи не обрізаються і не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Докладніше про поведінку див. [Очищення сесії](/uk/concepts/session-pruning). +Подробиці поведінки див. у [Обрізання сесії](/uk/concepts/session-pruning). -### Потокове передавання блоками +### Блокове потокове передавання ```json5 { @@ -641,11 +640,11 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- Для каналів, відмінних від 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–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку й розбиття на блоки див. [Streaming](/uk/concepts/streaming). +Подробиці поведінки й порціювання див. у [Потокове передавання](/uk/concepts/streaming). ### Індикатори набору тексту @@ -663,13 +662,13 @@ harness сервера застосунку Codex. Для розуміння м - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. - Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Докладніше див. [Індикатори набору тексту](/uk/concepts/typing-indicators). +Див. [Індикатори набору тексту](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язковий sandbox для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкове sandbox-ізолювання для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -715,7 +714,7 @@ harness сервера застосунку Codex. Для розуміння м identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Також підтримуються SecretRefs / inline contents: + // Також підтримуються SecretRefs / вбудований вміст: // 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,51 +763,51 @@ harness сервера застосунку Codex. Для розуміння м } ``` - + -**Бекенд:** +**Backend:** -- `docker`: локальне середовище виконання Docker (типово) -- `ssh`: загальне віддалене середовище виконання на основі SSH +- `docker`: локальне середовище виконання Docker (типове) +- `ssh`: універсальне віддалене середовище виконання через SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, специфічні для runtime налаштування переносяться до +Коли вибрано `backend: "openshell"`, специфічні для середовища виконання налаштування переносяться до `plugins.entries.openshell.config`. -**Конфігурація бекенда SSH:** +**Конфігурація backend SSH:** - `target`: ціль SSH у форматі `user@host[:port]` - `command`: команда клієнта SSH (типове значення: `ssh`) - `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах кожної області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Порядок пріоритету автентифікації SSH:** +**Пріоритет автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data`, що базуються на SecretRef, визначаються з активного snapshot середовища виконання секретів до запуску сесії sandbox +- Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання секретів до запуску sandbox-сесії -**Поведінка бекенда SSH:** +**Поведінка backend SSH:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений SSH-робочий простір як канонічний +- потім вважає віддалений робочий простір канонічним - маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично - не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox для кожної області в `~/.openclaw/sandboxes` +- `none`: робочий простір sandbox для кожної області під `~/.openclaw/sandboxes` - `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent` - `rw`: робочий простір агента монтується для читання й запису в `/workspace` **Область:** -- `session`: окремий контейнер + робочий простір для кожної сесії -- `agent`: один контейнер + робочий простір для кожного агента (типово) +- `session`: окремий контейнер і робочий простір для кожної сесії +- `agent`: один контейнер і робочий простір на агента (типове значення) - `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -839,30 +838,30 @@ harness сервера застосунку Codex. Для розуміння м **Режим OpenShell:** -- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: ініціалізує віддалений простір з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалений простір, коли sandbox створюється, а потім вважає віддалений робочий простір канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією керує Plugin. +У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після етапу початкової ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, доступного для запису кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, записуваного кореня та користувача root. -**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +**Контейнери за замовчуванням мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` за замовчуванням також заблоковано, якщо ви явно не задасте `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні та для окремого агента `binds` об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача через noVNC за замовчуванням використовує автентифікацію VNC, і OpenClaw генерує URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). -- `allowHostControl: false` (типове значення) блокує націлювання із sandbox-сесій на браузер хоста. -- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність через bridge. -- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо параметр задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначені в `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,25 +880,25 @@ 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_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. Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Збірка образів: +Збирання образів: ```bash -scripts/sandbox-setup.sh # головний образ sandbox +scripts/sandbox-setup.sh # основний образ sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` @@ -920,7 +919,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента fastModeDefault: false, // перевизначення швидкого режиму для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params + params: { cacheRetention: "none" }, // перевизначає ключі з matching defaults.models params + tts: { + providers: { + elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" }, + }, + }, skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -953,26 +957,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ``` - `id`: стабільний ідентифікатор агента (обов’язково). -- `default`: якщо задано для кількох агентів, використовується перший (записується попередження). Якщо не задано для жодного, типовим є перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва значення (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе ще успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли його встановлено; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є допустимими; для 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. +- `default`: якщо задано для кількох агентів, перший має пріоритет (записується попередження). Якщо не задано ні для кого, типовим є перший елемент списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва поля (`[]` вимикає глобальні fallback). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо не задати `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних перевизначень агента, таких як `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `tts`: необов’язкові перевизначення text-to-speech для окремого агента. Цей блок глибоко об’єднується з `messages.tts`, тому зберігайте спільні облікові дані провайдера та політику fallback у `messages.tts`, а тут задавайте лише значення, специфічні для персони, як-от провайдер, голос, модель, стиль або автоматичний режим. +- `skills`: необов’язковий allowlist 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, тоді як інші агенти зберігатимуть типовий fallback до PI в режимі `auto`. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати ACP harness-сесії. - `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`: allowlist ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типове значення: лише той самий агент). +- Запобіжник успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типове значення: false). --- ## Маршрутизація між кількома агентами -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Кілька агентів](/uk/concepts/multi-agent). +Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -989,13 +994,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля збігу binding +### Поля збігу прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо `type` відсутній, типово використовується route), `acp` для постійних binding розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` за замовчуванням означає `route`), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `match.guildId` / `match.teamId` (необов’язково; специфічні для каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок збігу:** @@ -1007,9 +1012,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б 5. `match.accountId: "*"` (на рівні всього каналу) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис у `bindings`. +У межах кожного рівня перемагає перший запис `bindings`, що збігся. -Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язок маршруту. ### Профілі доступу для окремого агента @@ -1031,7 +1036,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1060,7 +1065,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1106,7 +1111,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Докладніше про пріоритети див. [Sandbox і інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools). +Подробиці щодо пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- @@ -1132,7 +1137,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського треду вище цього ліміту токенів (0 вимикає) + parentForkMaxTokens: 100000, // пропускати форк батьківського потоку вище цього числа токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1157,34 +1162,34 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групових чатів. +- **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типове значення): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). -- **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують основну сесію. - - `per-peer`: ізоляція за ідентифікатором відправника між каналами. - - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для скриньок із багатьма користувачами). - - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних id до peer-ідентифікаторів із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає те, що спливає раніше. Актуальність щоденного скидання використовує `sessionStartedAt` у рядку сесії; актуальність скидання через неактивність використовує `lastInteractionAt`. Фонові/системні записи, такі як Heartbeat, пробудження Cron, сповіщення exec і службові записи Gateway, можуть оновлювати `updatedAt`, але вони не підтримують актуальність щоденних/неактивних сесій. + - `global`: усі учасники в контексті каналу використовують одну спільну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`dmScope`**: як групуються особисті повідомлення. + - `main`: усі особисті повідомлення використовують основну сесію. + - `per-peer`: ізоляція за id відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких inbox). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). +- **`identityLinks`**: мапа канонічних id до peer з префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує той, чий термін закінчиться раніше. Актуальність щоденного скидання визначається за `sessionStartedAt` рядка сесії; актуальність скидання за неактивністю — за `lastInteractionAt`. Фонові/системні записи, як-от Heartbeat, пробудження Cron, сповіщення `exec` та службові записи gateway, можуть оновлювати `updatedAt`, але вони не підтримують актуальність щоденних/неактивних сесій. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення відгалуженої сесії треду (типове значення `100000`). - - Якщо значення `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію треду замість успадкування історії транскрипту батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення сесії форкнутого потоку (типове значення `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. + - Установіть `0`, щоб вимкнути цей запобіжник і завжди дозволяти форк від батьківської сесії. - **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + контроль утримання. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у відповідь між агентами під час обміну між агентами (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: керування очищенням сховища сесій і термінами зберігання. + - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. - `pruneAfter`: віковий поріг для застарілих записів (типове значення `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типове значення `500`). - - `rotateBytes`: ротує `sessions.json`, коли файл перевищує цей розмір (типове значення `10mb`). - - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` він записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово — `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. + - `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` вимикає; провайдери можуть перевизначати) @@ -1227,36 +1232,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскад. `"auto"` формує `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ----------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — це alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` є alias для `{thinkingLevel}`. ### Реакція підтвердження -- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- За замовчуванням береться `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → fallback identity. - Область: `group-mentions` (типове значення), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає статусні реакції життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не задано, статусні реакції залишаються ввімкненими, коли активні реакції підтвердження. - У Telegram, щоб увімкнути статусні реакції життєвого циклу, явно встановіть `true`. +- `removeAckAfterReply`: прибирає ack після відповіді в Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. + У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні ack-реакції. + У Telegram потрібно явно встановити `true`, щоб увімкнути реакції статусу життєвого циклу. -### Inbound debounce +### Вхідний debounce -Групує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди оминають debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидають буфер негайно. Керівні команди обходять debounce. -### TTS (синтез мовлення) +### TTS (text-to-speech) ```json5 { @@ -1304,17 +1309,17 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим автоматичним режимом TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (увімкнення за бажанням). -- API key резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані мовні провайдери належать Plugin. Якщо задано `plugins.allow`, додайте кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як alias для `microsoft`. -- `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. +- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням має значення `false` (лише за явної згоди). +- API-ключі мають fallback до `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як alias для `microsoft`. +- `providers.openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. - Коли `providers.openai.baseUrl` вказує на не-OpenAI endpoint, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. --- -## Talk +## Розмова Типові значення для режиму Talk (macOS/iOS/Android). @@ -1345,16 +1350,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, якщо налаштовано кілька провайдерів 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`. +- Для voice ID використовується fallback до `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` перевизначає шлях до помічника для розробки. -- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується для розпізнавання мовлення Talk в iOS/macOS. Якщо не вказано, використовується типова локаль пристрою. -- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо параметр не вказано, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). +- Fallback до `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. +- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовується локальним помічником MLX у macOS. Якщо не вказано, macOS використовує `mlx-community/Soprano-80M-bf16`. +- Відтворення MLX у macOS працює через вбудований помічник `openclaw-mlx-tts`, якщо він наявний, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. +- `speechLocale` задає ідентифікатор локалі BCP 47, що використовується розпізнаванням мовлення Talk в iOS/macOS. Залиште незаданим, щоб використовувати локаль пристрою за замовчуванням. +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після мовчання користувача перед надсиланням транскрипту. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms` у macOS і Android, `900 ms` в iOS). --- diff --git a/docs/uk/reference/secretref-credential-surface.md b/docs/uk/reference/secretref-credential-surface.md index 25964b6a9..773556a86 100644 --- a/docs/uk/reference/secretref-credential-surface.md +++ b/docs/uk/reference/secretref-credential-surface.md @@ -1,25 +1,25 @@ --- read_when: - Перевірка покриття облікових даних SecretRef - - Аудит того, чи облікові дані відповідають вимогам для `secrets configure` або `secrets apply` + - Аудит того, чи облікові дані придатні для `secrets configure` або `secrets apply` - Перевірка того, чому облікові дані перебувають поза підтримуваною поверхнею summary: Канонічна підтримувана та непідтримувана поверхня облікових даних SecretRef title: поверхня облікових даних SecretRef x-i18n: - generated_at: "2026-04-25T02:56:18Z" + generated_at: "2026-04-26T01:57:29Z" model: gpt-5.4 provider: openai - source_hash: 50a4602939970d92831c0de9339e84b0f42b119c2e25ea30375925282f55d237 + source_hash: 6ffdf545e954f8d73d18adfeb196d9092bf346bd86648f09314bad2a0f40bb6c source_path: reference/secretref-credential-surface.md workflow: 15 --- Ця сторінка визначає канонічну поверхню облікових даних SecretRef. -Намір щодо сфери охоплення: +Призначення області: -- У сфері охоплення: виключно надані користувачем облікові дані, які OpenClaw не створює та не ротирує. -- Поза сферою охоплення: облікові дані, створені під час виконання або такі, що ротуються, матеріали оновлення OAuth і артефакти, подібні до сесій. +- В області: суворо лише надані користувачем облікові дані, які OpenClaw не випускає і не ротує. +- Поза областю: облікові дані, що випускаються або ротуються під час виконання, матеріали оновлення OAuth та артефакти на кшталт сесій. ## Підтримувані облікові дані @@ -42,6 +42,7 @@ x-i18n: - `models.providers.*.request.tls.passphrase` - `skills.entries.*.apiKey` - `agents.defaults.memorySearch.remote.apiKey` +- `agents.list[].tts.providers.*.apiKey` - `agents.list[].memorySearch.remote.apiKey` - `talk.providers.*.apiKey` - `messages.tts.providers.*.apiKey` @@ -118,22 +119,22 @@ x-i18n: Примітки: -- Цілі плану auth-profile потребують `agentId`. +- Цілі плану профілю автентифікації потребують `agentId`. - Записи плану націлюються на `profiles.*.key` / `profiles.*.token` і записують сусідні посилання (`keyRef` / `tokenRef`). -- Посилання auth-profile включено до покриття розв’язання під час виконання та аудиту. -- У `openclaw.json` SecretRef має використовувати структуровані об’єкти, як-от `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`. Застарілі рядки-маркери `secretref-env:` відхиляються на шляхах облікових даних SecretRef; запустіть `openclaw doctor --fix`, щоб мігрувати дійсні маркери. -- Захист політики OAuth: `auth.profiles..mode = "oauth"` не можна поєднувати з вхідними даними SecretRef для цього профілю. Під час запуску/перезавантаження та розв’язання auth-profile відбувається швидке завершення з помилкою, якщо цю політику порушено. -- Для постачальників моделей, якими керує SecretRef, згенеровані записи `agents/*/agent/models.json` зберігають несекретні маркери (а не розв’язані секретні значення) для поверхонь `apiKey`/заголовків. -- Збереження маркерів є авторитетним на рівні джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних секретних значень під час виконання. +- Посилання профілю автентифікації включені до покриття під час виконання та аудиту. +- У `openclaw.json` SecretRef мають використовувати структуровані об’єкти, такі як `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`. Застарілі рядки-маркери `secretref-env:` відхиляються на шляхах облікових даних SecretRef; запустіть `openclaw doctor --fix`, щоб мігрувати дійсні маркери. +- Захист політики OAuth: `auth.profiles..mode = "oauth"` не можна поєднувати з вхідними даними SecretRef для цього профілю. Під час запуску/перезавантаження та розв’язання профілю автентифікації відбувається негайне завершення з помилкою, якщо цю політику порушено. +- Для модельних провайдерів, керованих SecretRef, згенеровані записи `agents/*/agent/models.json` зберігають несекретні маркери (а не розв’язані секретні значення) для поверхонь `apiKey`/заголовків. +- Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання. - Для вебпошуку: - - У режимі явного постачальника (`tools.web.search.provider` задано) активний лише ключ вибраного постачальника. - - В автоматичному режимі (`tools.web.search.provider` не задано) активний лише перший ключ постачальника, який розв’язується за пріоритетом. - - В автоматичному режимі посилання невибраних постачальників вважаються неактивними, доки їх не буде вибрано. - - Застарілі шляхи постачальників `tools.web.search.*` і далі розв’язуються протягом вікна сумісності, але канонічною поверхнею SecretRef є `plugins.entries..config.webSearch.*`. + - У режимі явного провайдера (`tools.web.search.provider` встановлено) активний лише ключ вибраного провайдера. + - В автоматичному режимі (`tools.web.search.provider` не встановлено) активний лише перший ключ провайдера, який розв’язується за пріоритетом. + - В автоматичному режимі посилання невибраних провайдерів вважаються неактивними, доки їх не буде вибрано. + - Застарілі шляхи провайдерів `tools.web.search.*` усе ще розв’язуються протягом вікна сумісності, але канонічною поверхнею SecretRef є `plugins.entries..config.webSearch.*`. ## Непідтримувані облікові дані -Облікові дані поза сферою охоплення включають: +До облікових даних поза областю належать: [//]: # "secretref-unsupported-list-start" @@ -151,7 +152,7 @@ x-i18n: Обґрунтування: -- Ці облікові дані належать до класів, які створюються, ротуються, несуть стан сесії або є довготривалими для OAuth, і не підходять для зовнішнього розв’язання SecretRef лише для читання. +- Ці облікові дані належать до класів, які випускаються, ротуються, пов’язані із сесіями або є довготривалими для OAuth, і не відповідають моделі зовнішнього розв’язання SecretRef лише для читання. ## Пов’язане diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index 6b9edd996..3d635f7f6 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,15 +1,15 @@ --- read_when: - - Увімкнення синтезу мовлення для відповідей - - Налаштування провайдерів TTS або обмежень + - Увімкнення перетворення тексту на мовлення для відповідей + - Налаштування постачальників TTS або обмежень - Використання команд `/tts` -summary: Синтез мовлення (TTS) для вихідних відповідей -title: Синтез мовлення +summary: Перетворення тексту на мовлення (TTS) для вихідних відповідей +title: Перетворення тексту на мовлення x-i18n: - generated_at: "2026-04-26T00:46:18Z" + generated_at: "2026-04-26T01:57:28Z" model: gpt-5.4 provider: openai - source_hash: fb8c84b87b4a92f3ddc68ce8caa4a911ca353343a6a7f3c23e5ba7777861dabb + source_hash: 5af402a06e82554b4ed6956681fb78415d4d605ae75cc24aff16c1432ff730d8 source_path: tools/tts.md workflow: 15 --- @@ -19,38 +19,39 @@ OpenClaw може перетворювати вихідні відповіді ## Підтримувані сервіси -- **Azure Speech** (основний або резервний провайдер; використовує Azure AI Speech REST API) -- **ElevenLabs** (основний або резервний провайдер) -- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS) -- **Gradium** (основний або резервний провайдер; підтримує вивід голосових нотаток і телефонії) -- **Inworld** (основний або резервний провайдер; використовує потоковий TTS API Inworld) -- **Local CLI** (основний або резервний провайдер; запускає налаштовану локальну команду TTS) -- **Microsoft** (основний або резервний провайдер; поточна вбудована реалізація використовує `node-edge-tts`) -- **MiniMax** (основний або резервний провайдер; використовує T2A v2 API) -- **OpenAI** (основний або резервний провайдер; також використовується для підсумків) -- **Volcengine** (основний або резервний провайдер; використовує BytePlus Seed Speech HTTP API) -- **Vydra** (основний або резервний провайдер; спільний провайдер зображень, відео та мовлення) -- **xAI** (основний або резервний провайдер; використовує xAI TTS API) -- **Xiaomi MiMo** (основний або резервний провайдер; використовує MiMo TTS через Xiaomi chat completions) +- **Azure Speech** (основний або резервний постачальник; використовує REST API Azure AI Speech) +- **ElevenLabs** (основний або резервний постачальник) +- **Google Gemini** (основний або резервний постачальник; використовує Gemini API TTS) +- **Gradium** (основний або резервний постачальник; підтримує вихід voice-note і telephony) +- **Inworld** (основний або резервний постачальник; використовує потоковий TTS API Inworld) +- **Local CLI** (основний або резервний постачальник; запускає налаштовану локальну TTS-команду) +- **Microsoft** (основний або резервний постачальник; поточна вбудована реалізація використовує `node-edge-tts`) +- **MiniMax** (основний або резервний постачальник; використовує API T2A v2) +- **OpenAI** (основний або резервний постачальник; також використовується для зведень) +- **Volcengine** (основний або резервний постачальник; використовує HTTP API BytePlus Seed Speech) +- **Vydra** (основний або резервний постачальник; спільний постачальник зображень, відео та мовлення) +- **xAI** (основний або резервний постачальник; використовує xAI TTS API) +- **Xiaomi MiMo** (основний або резервний постачальник; використовує MiMo TTS через chat completions Xiaomi) ### Примітки щодо мовлення Microsoft -Поточний вбудований провайдер мовлення Microsoft використовує онлайн-сервіс -нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостинговий сервіс (не -локальний), він використовує кінцеві точки Microsoft і не вимагає API-ключа. +Поточний вбудований постачальник мовлення Microsoft використовує онлайн-сервіс +нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостований сервіс (не +локальний), він використовує кінцеві точки Microsoft і не потребує API-ключа. `node-edge-tts` надає параметри конфігурації мовлення та формати виводу, але -не всі параметри підтримуються сервісом. Застаріла конфігурація та вхідні директиви -з використанням `edge` усе ще працюють і нормалізуються до `microsoft`. +не всі параметри підтримуються сервісом. Застаріла конфігурація та вхідні директиви, +що використовують `edge`, усе ще працюють і нормалізуються до `microsoft`. -Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квоти, -його слід вважати best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI +Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA чи квоти, +ставтеся до нього як до найкращого можливого варіанта без гарантій. Якщо вам потрібні гарантовані +ліміти та підтримка, використовуйте OpenAI або ElevenLabs. ## Необов’язкові ключі Якщо ви хочете використовувати Azure Speech, ElevenLabs, Google Gemini, Gradium, Inworld, MiniMax, OpenAI, Volcengine, Vydra, xAI або Xiaomi MiMo: -- `AZURE_SPEECH_KEY` плюс `AZURE_SPEECH_REGION` (також приймає +- `AZURE_SPEECH_KEY` разом із `AZURE_SPEECH_REGION` (також приймаються `AZURE_SPEECH_API_KEY`, `SPEECH_KEY` і `SPEECH_REGION`) - `ELEVENLABS_API_KEY` (або `XI_API_KEY`) - `GEMINI_API_KEY` (або `GOOGLE_API_KEY`) @@ -61,24 +62,24 @@ OpenClaw може перетворювати вихідні відповіді `MINIMAX_CODING_API_KEY` - `OPENAI_API_KEY` - `VOLCENGINE_TTS_API_KEY` (або `BYTEPLUS_SEED_SPEECH_API_KEY`); - застаріла автентифікація через AppID/token також приймає `VOLCENGINE_TTS_APPID` і + застаріла автентифікація AppID/token також приймає `VOLCENGINE_TTS_APPID` і `VOLCENGINE_TTS_TOKEN` - `VYDRA_API_KEY` - `XAI_API_KEY` - `XIAOMI_API_KEY` -Local CLI і мовлення Microsoft **не** вимагають API-ключа. +Local CLI і мовлення Microsoft **не** потребують API-ключа. -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші — як резервні варіанти. -Автоматичний підсумок використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), -тому якщо ви вмикаєте підсумки, цей провайдер також має бути автентифікований. +Якщо налаштовано кілька постачальників, спочатку використовується вибраний постачальник, а інші стають резервними варіантами. +Автоматичне зведення використовує налаштовану `summaryModel` (або `agents.defaults.model.primary`), +тому якщо ви вмикаєте зведення, цей постачальник також має бути автентифікований. ## Посилання на сервіси - [Посібник OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) - [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) - [Azure Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) -- [Провайдер Azure Speech](/uk/providers/azure-speech) +- [Постачальник Azure Speech](/uk/providers/azure-speech) - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/uk/providers/gradium) @@ -87,23 +88,23 @@ Local CLI і мовлення Microsoft **не** вимагають API-ключ - [Volcengine TTS HTTP API](/uk/providers/volcengine#text-to-speech) - [Синтез мовлення Xiaomi MiMo](/uk/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Формати виводу мовлення Microsoft](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## Чи ввімкнено це за замовчуванням? -Ні. Auto‑TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через +Ні. Авто‑TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через `messages.tts.auto` або локально через `/tts on`. -Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований -провайдер мовлення в порядку автоматичного вибору реєстру. +Коли `messages.tts.provider` не задано, OpenClaw вибирає першого налаштованого +постачальника мовлення в порядку автоматичного вибору з реєстру. ## Конфігурація Конфігурація TTS розташована в `messages.tts` у `openclaw.json`. -Повна схема наведена в [Конфігурації Gateway](/uk/gateway/configuration). +Повна схема наведена в [конфігурації Gateway](/uk/gateway/configuration). -### Мінімальна конфігурація (увімкнення + провайдер) +### Мінімальна конфігурація (увімкнення + постачальник) ```json5 { @@ -116,6 +117,50 @@ Local CLI і мовлення Microsoft **не** вимагають API-ключ } ``` +### Перевизначення голосу для окремих агентів + +Використовуйте `agents.list[].tts`, коли один агент має говорити з іншим постачальником, +голосом, моделлю, стилем або режимом auto-TTS. Блок агента виконує глибоке злиття поверх +`messages.tts`, тому облікові дані постачальника можуть залишатися в глобальній конфігурації постачальника. + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "elevenlabs", + providers: { + elevenlabs: { + apiKey: "${ELEVENLABS_API_KEY}", + model: "eleven_multilingual_v2", + }, + }, + }, + }, + agents: { + list: [ + { + id: "reader", + tts: { + providers: { + elevenlabs: { + voiceId: "EXAVITQu4vr4xnSDxMaL", + }, + }, + }, + }, + ], + }, +} +``` + +Пріоритет для автоматичних відповідей: + +1. `messages.tts` +2. активний `agents.list[].tts` +3. локальні налаштування `/tts` для цього хоста +4. вбудовані директиви `[[tts:...]]`, коли увімкнені перевизначення моделі + ### OpenAI як основний із резервним ElevenLabs ```json5 @@ -167,8 +212,8 @@ Local CLI і мовлення Microsoft **не** вимагають API-ключ provider: "azure-speech", providers: { "azure-speech": { - // apiKey використовує резервне значення з AZURE_SPEECH_KEY. - // region використовує резервне значення з AZURE_SPEECH_REGION. + // apiKey falls back to AZURE_SPEECH_KEY. + // region falls back to AZURE_SPEECH_REGION. voice: "en-US-JennyNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", @@ -185,7 +230,7 @@ Azure Speech використовує ключ ресурсу Speech, а не к `AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`, а також `messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> `SPEECH_REGION` для регіону. У новій конфігурації слід використовувати `azure-speech`; `azure` -приймається як псевдонім провайдера. +приймається як псевдонім постачальника. ### Microsoft як основний (без API-ключа) @@ -234,11 +279,11 @@ Azure Speech використовує ключ ресурсу Speech, а не к } ``` -Порядок визначення автентифікації MiniMax TTS: `messages.tts.providers.minimax.apiKey`, потім -збережені профілі OAuth/token `minimax-portal`, потім ключі середовища Token Plan +Порядок визначення автентифікації MiniMax TTS: спочатку `messages.tts.providers.minimax.apiKey`, потім +збережені OAuth/token-профілі `minimax-portal`, далі ключі середовища Token Plan (`MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, -`MINIMAX_CODING_API_KEY`), потім `MINIMAX_API_KEY`. Якщо явний `baseUrl` TTS -не задано, OpenClaw може повторно використати налаштований хост OAuth +`MINIMAX_CODING_API_KEY`), а потім `MINIMAX_API_KEY`. Якщо явний TTS +`baseUrl` не задано, OpenClaw може повторно використати налаштований OAuth-хост `minimax-portal` для мовлення Token Plan. ### Google Gemini як основний @@ -261,9 +306,9 @@ Azure Speech використовує ключ ресурсу Speech, а не к } ``` -Google Gemini TTS використовує шлях API-ключа Gemini. Тут також підходить API-ключ -Google Cloud Console, обмежений Gemini API, і це той самий тип ключа, -який використовується вбудованим провайдером генерації зображень Google. Порядок визначення: +Google Gemini TTS використовує шлях API-ключа Gemini. API-ключ Google Cloud Console, +обмежений Gemini API, тут є дійсним, і це той самий тип ключа, що використовується +вбудованим постачальником генерації зображень Google. Порядок визначення: `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`. @@ -290,11 +335,11 @@ Google Cloud Console, обмежений Gemini API, і це той самий ``` Значення `apiKey` має бути рядком облікових даних у Base64, скопійованим -дослівно з панелі керування Inworld (Workspace > API Keys). Провайдер -надсилає його як `Authorization: Basic ` без будь-якого додаткового -кодування, тому не передавайте необроблений bearer token і не кодуйте його -в Base64 самостійно. Ключ використовує резервне значення зі змінної середовища `INWORLD_API_KEY`. Див. -[Провайдер Inworld](/uk/providers/inworld) для повного налаштування. +без змін із панелі Inworld (Workspace > API Keys). Постачальник +надсилає його як `Authorization: Basic ` без жодного додаткового +кодування, тому не передавайте сирий bearer token і не кодуйте його в Base64 +самостійно. Ключ резервно береться зі змінної середовища `INWORLD_API_KEY`. Див. +[постачальник Inworld](/uk/providers/inworld) для повного налаштування. ### Volcengine як основний @@ -318,12 +363,12 @@ Google Cloud Console, обмежений Gemini API, і це той самий ``` Volcengine TTS використовує API-ключ BytePlus Seed Speech із Speech Console, -а не сумісний з OpenAI `VOLCANO_ENGINE_API_KEY`, який використовується для провайдерів +а не сумісний з OpenAI `VOLCANO_ENGINE_API_KEY`, який використовується для постачальників моделей Doubao. Порядок визначення: `messages.tts.providers.volcengine.apiKey` -> -`VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`. Застаріла автентифікація через AppID/token +`VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`. Застаріла автентифікація AppID/token усе ще працює через `messages.tts.providers.volcengine.appId` / `token` або -`VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN`. Для цілей голосових нотаток запитується -власний для провайдера формат `ogg_opus`; для звичайних цілей аудіофайлів запитується `mp3`. +`VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN`. Цілі voice-note запитують +власний для постачальника формат `ogg_opus`; звичайні цілі аудіофайлів запитують `mp3`. ### xAI як основний @@ -347,10 +392,10 @@ Volcengine TTS використовує API-ключ BytePlus Seed Speech із S } ``` -xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований провайдер моделей Grok. +xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований постачальник моделей Grok. Порядок визначення: `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`. Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; `eve` — -типовий. `language` приймає тег BCP-47 або `auto`. +значення за замовчуванням. `language` приймає тег BCP-47 або `auto`. ### Xiaomi MiMo як основний @@ -375,10 +420,10 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_KEY`, що й вбудований провайдер моделей Xiaomi. -Ідентифікатор провайдера мовлення — `xiaomi`; `mimo` приймається як псевдонім. -Цільовий текст надсилається як повідомлення помічника, що відповідає контракту TTS Xiaomi. -Необов’язковий `style` надсилається як інструкція користувача і не озвучується. +Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_KEY`, що й вбудований постачальник +моделей Xiaomi. Ідентифікатор постачальника мовлення — `xiaomi`; `mimo` приймається як псевдонім. +Цільовий текст надсилається як повідомлення асистента, відповідно до TTS-контракту +Xiaomi. Необов’язковий `style` надсилається як інструкція користувача і не озвучується. ### OpenRouter як основний @@ -402,7 +447,7 @@ Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_ ``` OpenRouter TTS використовує той самий шлях `OPENROUTER_API_KEY`, що й вбудований -провайдер моделей OpenRouter. Порядок визначення: +постачальник моделей OpenRouter. Порядок визначення: `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`. @@ -430,9 +475,9 @@ OpenRouter TTS використовує той самий шлях `OPENROUTER_A Local CLI TTS запускає налаштовану команду на хості Gateway. Заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}` і `{{OutputBase}}` розгортаються в `args`; якщо заповнювач `{{Text}}` відсутній, OpenClaw записує -текст для озвучення до stdin. `outputFormat` приймає `mp3`, `opus` або `wav`. -Цілі голосових нотаток транскодуються в Ogg/Opus, а вивід для телефонії -транскодується в необроблений моно PCM 16 кГц за допомогою `ffmpeg`. Застарілий псевдонім провайдера +озвучуваний текст у stdin. `outputFormat` приймає `mp3`, `opus` або `wav`. +Цілі voice-note перекодовуються в Ogg/Opus, а вихід для telephony +перекодовується в сирий моно PCM 16 кГц за допомогою `ffmpeg`. Застарілий псевдонім постачальника `cli` усе ще працює, але в новій конфігурації слід використовувати `tts-local-cli`. ### Gradium як основний @@ -498,7 +543,7 @@ Local CLI TTS запускає налаштовану команду на хос } ``` -### Вимкнення автоматичного підсумку для довгих відповідей +### Вимкнення автоматичного зведення для довгих відповідей ```json5 { @@ -518,29 +563,29 @@ Local CLI TTS запускає налаштовану команду на хос ### Примітки щодо полів -- `auto`: режим auto‑TTS (`off`, `always`, `inbound`, `tagged`). +- `auto`: режим auto-TTS (`off`, `always`, `inbound`, `tagged`). - `inbound` надсилає аудіо лише після вхідного голосового повідомлення. - `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:key=value]]` або блок `[[tts:text]]...[[/tts:text]]`. -- `enabled`: застарілий перемикач (doctor переносить це до `auto`). -- `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). -- `provider`: ідентифікатор провайдера мовлення, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"inworld"`, `"microsoft"`, `"minimax"`, `"openai"`, `"volcengine"`, `"vydra"`, `"xai"` або `"xiaomi"` (резервний варіант вибирається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований провайдер мовлення в порядку автоматичного вибору реєстру. +- `enabled`: застарілий перемикач (doctor мігрує його до `auto`). +- `mode`: `"final"` (типово) або `"all"` (включає відповіді tool/block). +- `provider`: ідентифікатор постачальника мовлення, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"inworld"`, `"microsoft"`, `"minimax"`, `"openai"`, `"volcengine"`, `"vydra"`, `"xai"` або `"xiaomi"` (резервне перемикання відбувається автоматично). +- Якщо `provider` **не задано**, OpenClaw використовує першого налаштованого постачальника мовлення в порядку автоматичного вибору з реєстру. - Застаріла конфігурація `provider: "edge"` виправляється командою `openclaw doctor --fix` і переписується на `provider: "microsoft"`. -- `summaryModel`: необов’язкова дешева модель для автоматичного підсумку; типово використовується `agents.defaults.model.primary`. - - Приймає `provider/model` або псевдонім налаштованої моделі. -- `modelOverrides`: дозволяє моделі генерувати директиви TTS (увімкнено за замовчуванням). - - `allowProvider` типово має значення `false` (перемикання провайдера вмикається окремо). -- `providers.`: налаштування провайдера, що належать провайдеру, з ключем за ідентифікатором провайдера мовлення. -- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) виправляються командою `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.`. -- Застарілий `messages.tts.providers.edge` також виправляється командою `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.microsoft`. -- `maxTextLength`: жорстке обмеження для вхідних даних TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. -- `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначає локальний шлях JSON для prefs (провайдер/ліміт/підсумок). -- Значення `apiKey` використовують резервні значення зі змінних середовища (`AZURE_SPEECH_KEY`/`AZURE_SPEECH_API_KEY`/`SPEECH_KEY`, `ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GRADIUM_API_KEY`, `INWORLD_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`, `VYDRA_API_KEY`, `XAI_API_KEY`, `XIAOMI_API_KEY`). Volcengine натомість використовує `appId`/`token`. -- `providers.azure-speech.apiKey`: ключ ресурсу Azure Speech (змінні середовища: +- `summaryModel`: необов’язкова недорога модель для автоматичного зведення; типово використовується `agents.defaults.model.primary`. + - Приймає `provider/model` або налаштований псевдонім моделі. +- `modelOverrides`: дозволяє моделі виводити директиви TTS (увімкнено за замовчуванням). + - `allowProvider` типово має значення `false` (перемикання постачальника вмикається явно). +- `providers.`: налаштування, що належать постачальнику, з ключем за ідентифікатором постачальника мовлення. +- Застарілі прямі блоки постачальників (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `messages.tts.providers.`. +- Застарілий `messages.tts.providers.edge` також виправляється командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `messages.tts.providers.microsoft`. +- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. +- `timeoutMs`: час очікування запиту (мс). +- `prefsPath`: перевизначення локального шляху до JSON-файла prefs (постачальник/ліміт/зведення). +- Значення `apiKey` резервно беруться зі змінних середовища (`AZURE_SPEECH_KEY`/`AZURE_SPEECH_API_KEY`/`SPEECH_KEY`, `ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GRADIUM_API_KEY`, `INWORLD_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`, `VYDRA_API_KEY`, `XAI_API_KEY`, `XIAOMI_API_KEY`). Volcengine натомість використовує `appId`/`token`. +- `providers.azure-speech.apiKey`: ключ ресурсу Azure Speech (env: `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` або `SPEECH_KEY`). -- `providers.azure-speech.region`: регіон Azure Speech, наприклад `eastus` (змінні середовища: +- `providers.azure-speech.region`: регіон Azure Speech, наприклад `eastus` (env: `AZURE_SPEECH_REGION` або `SPEECH_REGION`). - `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`: необов’язкове перевизначення endpoint/base URL Azure Speech. @@ -548,83 +593,83 @@ Local CLI TTS запускає налаштовану команду на хос `en-US-JennyNeural`). - `providers.azure-speech.lang`: код мови SSML (типово `en-US`). - `providers.azure-speech.outputFormat`: Azure `X-Microsoft-OutputFormat` для - стандартного виводу аудіо (типово `audio-24khz-48kbitrate-mono-mp3`). + стандартного аудіовиходу (типово `audio-24khz-48kbitrate-mono-mp3`). - `providers.azure-speech.voiceNoteOutputFormat`: Azure - `X-Microsoft-OutputFormat` для виводу голосових нотаток (типово + `X-Microsoft-OutputFormat` для виходу voice-note (типово `ogg-24khz-16bit-mono-opus`). -- `providers.elevenlabs.baseUrl`: перевизначає базовий URL API ElevenLabs. -- `providers.openai.baseUrl`: перевизначає endpoint OpenAI TTS. +- `providers.elevenlabs.baseUrl`: перевизначення базового URL API ElevenLabs. +- `providers.openai.baseUrl`: перевизначення endpoint TTS OpenAI. - Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Значення, відмінні від типового, вважаються сумісними з OpenAI TTS endpoint, тому допускаються власні назви моделей і голосів. + - Нестандартні значення трактуються як сумісні з OpenAI TTS endpoints, тому приймаються власні назви моделей і голосів. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - `speed`: `0.5..2.0` (1.0 = звичайна швидкість) - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` - `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`) -- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінізм) -- `providers.minimax.baseUrl`: перевизначає базовий URL API MiniMax (типово `https://api.minimax.io`, змінна середовища: `MINIMAX_API_HOST`). -- `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, змінна середовища: `MINIMAX_TTS_MODEL`). -- `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, змінна середовища: `MINIMAX_TTS_VOICE_ID`). +- `providers.elevenlabs.seed`: ціле число `0..4294967295` (детермінованість у межах найкращих зусиль) +- `providers.minimax.baseUrl`: перевизначення базового URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). +- `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). +- `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). - `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0). - `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0). -- `providers.minimax.pitch`: цілочисельне зміщення висоти тону `-12..12` (типово 0). Дробові значення усікаються перед викликом MiniMax T2A, оскільки API відхиляє нецілі значення висоти тону. +- `providers.minimax.pitch`: ціле зміщення висоти тону `-12..12` (типово 0). Дробові значення відсікаються перед викликом MiniMax T2A, оскільки API відхиляє нецілі значення pitch. - `providers.tts-local-cli.command`: локальний виконуваний файл або рядок команди для CLI TTS. - `providers.tts-local-cli.args`: аргументи команди; підтримує заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}` і `{{OutputBase}}`. - `providers.tts-local-cli.outputFormat`: очікуваний формат виводу CLI (`mp3`, `opus` або `wav`; типово `mp3` для аудіовкладень). - `providers.tts-local-cli.timeoutMs`: тайм-аут команди в мілісекундах (типово `120000`). - `providers.tts-local-cli.cwd`: необов’язковий робочий каталог команди. -- `providers.tts-local-cli.env`: необов’язкові рядкові перевизначення змінних середовища для команди. -- `providers.inworld.baseUrl`: перевизначає базовий URL API Inworld (типово `https://api.inworld.ai`). +- `providers.tts-local-cli.env`: необов’язкові перевизначення змінних середовища рядками для команди. +- `providers.inworld.baseUrl`: перевизначення базового URL API Inworld (типово `https://api.inworld.ai`). - `providers.inworld.voiceId`: ідентифікатор голосу Inworld (типово `Sarah`). -- `providers.inworld.modelId`: модель TTS Inworld (типово `inworld-tts-1.5-max`; також підтримує `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`). -- `providers.inworld.temperature`: температура семплювання `0..2` (необов’язково). +- `providers.inworld.modelId`: модель TTS Inworld (типово `inworld-tts-1.5-max`; також підтримуються `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`). +- `providers.inworld.temperature`: температура семплування `0..2` (необов’язково). - `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`). - `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`). -- `providers.google.audioProfile`: промпт стилю природною мовою, що додається перед озвучуваним текстом. +- `providers.google.audioProfile`: стилістична підказка природною мовою, що додається перед озвучуваним текстом. - `providers.google.speakerName`: необов’язкова мітка мовця, що додається перед озвучуваним текстом, коли ваш TTS-промпт використовує іменованого мовця. -- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Дозволено лише `https://generativelanguage.googleapis.com`. - - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використовувати `models.providers.google.apiKey` до переходу на резервні значення зі змінних середовища. -- `providers.gradium.baseUrl`: перевизначає базовий URL API Gradium (типово `https://api.gradium.ai`). +- `providers.google.baseUrl`: перевизначення базового URL Gemini API. Приймається лише `https://generativelanguage.googleapis.com`. + - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використати `models.providers.google.apiKey` до переходу на резервне значення з env. +- `providers.gradium.baseUrl`: перевизначення базового URL API Gradium (типово `https://api.gradium.ai`). - `providers.gradium.voiceId`: ідентифікатор голосу Gradium (типово Emma, `YTpq7expH9539ERJ`). -- `providers.volcengine.apiKey`: API-ключ BytePlus Seed Speech (змінні середовища: +- `providers.volcengine.apiKey`: API-ключ BytePlus Seed Speech (env: `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY`). -- `providers.volcengine.resourceId`: ідентифікатор ресурсу BytePlus Seed Speech (типово - `seed-tts-1.0`, змінна середовища: `VOLCENGINE_TTS_RESOURCE_ID`; використовуйте `seed-tts-2.0`, коли +- `providers.volcengine.resourceId`: resource id BytePlus Seed Speech (типово + `seed-tts-1.0`, env: `VOLCENGINE_TTS_RESOURCE_ID`; використовуйте `seed-tts-2.0`, коли ваш проєкт BytePlus має entitlement для TTS 2.0). - `providers.volcengine.appKey`: заголовок app key BytePlus Seed Speech (типово - `aGjiRDfUWi`, змінна середовища: `VOLCENGINE_TTS_APP_KEY`). -- `providers.volcengine.baseUrl`: перевизначає HTTP endpoint Seed Speech TTS - (змінна середовища: `VOLCENGINE_TTS_BASE_URL`). -- `providers.volcengine.appId`: застарілий ідентифікатор застосунку Volcengine Speech Console (змінна середовища: `VOLCENGINE_TTS_APPID`). -- `providers.volcengine.token`: застарілий токен доступу Volcengine Speech Console (змінна середовища: `VOLCENGINE_TTS_TOKEN`). -- `providers.volcengine.cluster`: застарілий кластер Volcengine TTS (типово `volcano_tts`, змінна середовища: `VOLCENGINE_TTS_CLUSTER`). -- `providers.volcengine.voice`: тип голосу (типово `en_female_anna_mars_bigtts`, змінна середовища: `VOLCENGINE_TTS_VOICE`). -- `providers.volcengine.speedRatio`: власний для провайдера коефіцієнт швидкості. -- `providers.volcengine.emotion`: власний для провайдера тег емоції. -- `providers.xai.apiKey`: API-ключ xAI TTS (змінна середовища: `XAI_API_KEY`). -- `providers.xai.baseUrl`: перевизначає базовий URL xAI TTS (типово `https://api.x.ai/v1`, змінна середовища: `XAI_BASE_URL`). + `aGjiRDfUWi`, env: `VOLCENGINE_TTS_APP_KEY`). +- `providers.volcengine.baseUrl`: перевизначення HTTP endpoint TTS Seed Speech + (env: `VOLCENGINE_TTS_BASE_URL`). +- `providers.volcengine.appId`: застарілий ідентифікатор застосунку Volcengine Speech Console (env: `VOLCENGINE_TTS_APPID`). +- `providers.volcengine.token`: застарілий токен доступу Volcengine Speech Console (env: `VOLCENGINE_TTS_TOKEN`). +- `providers.volcengine.cluster`: застарілий кластер Volcengine TTS (типово `volcano_tts`, env: `VOLCENGINE_TTS_CLUSTER`). +- `providers.volcengine.voice`: тип голосу (типово `en_female_anna_mars_bigtts`, env: `VOLCENGINE_TTS_VOICE`). +- `providers.volcengine.speedRatio`: власне для постачальника співвідношення швидкості. +- `providers.volcengine.emotion`: власний для постачальника тег емоції. +- `providers.xai.apiKey`: API-ключ xAI TTS (env: `XAI_API_KEY`). +- `providers.xai.baseUrl`: перевизначення базового URL xAI TTS (типово `https://api.x.ai/v1`, env: `XAI_BASE_URL`). - `providers.xai.voiceId`: ідентифікатор голосу xAI (типово `eve`; поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`). - `providers.xai.language`: код мови BCP-47 або `auto` (типово `en`). - `providers.xai.responseFormat`: `mp3`, `wav`, `pcm`, `mulaw` або `alaw` (типово `mp3`). -- `providers.xai.speed`: власне для провайдера перевизначення швидкості. -- `providers.xiaomi.apiKey`: API-ключ Xiaomi MiMo (змінна середовища: `XIAOMI_API_KEY`). -- `providers.xiaomi.baseUrl`: перевизначає базовий URL API Xiaomi MiMo (типово `https://api.xiaomimimo.com/v1`, змінна середовища: `XIAOMI_BASE_URL`). -- `providers.xiaomi.model`: модель TTS (типово `mimo-v2.5-tts`, змінна середовища: `XIAOMI_TTS_MODEL`; також підтримується `mimo-v2-tts`). -- `providers.xiaomi.voice`: ідентифікатор голосу MiMo (типово `mimo_default`, змінна середовища: `XIAOMI_TTS_VOICE`). -- `providers.xiaomi.format`: `mp3` або `wav` (типово `mp3`, змінна середовища: `XIAOMI_TTS_FORMAT`). -- `providers.xiaomi.style`: необов’язкова інструкція стилю природною мовою, що надсилається як повідомлення користувача; вона не озвучується. -- `providers.openrouter.apiKey`: API-ключ OpenRouter (змінна середовища: `OPENROUTER_API_KEY`; може повторно використовувати `models.providers.openrouter.apiKey`). -- `providers.openrouter.baseUrl`: перевизначає базовий URL OpenRouter TTS (типово `https://openrouter.ai/api/v1`; застарілий `https://openrouter.ai/v1` нормалізується). +- `providers.xai.speed`: власне для постачальника перевизначення швидкості. +- `providers.xiaomi.apiKey`: API-ключ Xiaomi MiMo (env: `XIAOMI_API_KEY`). +- `providers.xiaomi.baseUrl`: перевизначення базового URL API Xiaomi MiMo (типово `https://api.xiaomimimo.com/v1`, env: `XIAOMI_BASE_URL`). +- `providers.xiaomi.model`: модель TTS (типово `mimo-v2.5-tts`, env: `XIAOMI_TTS_MODEL`; також підтримується `mimo-v2-tts`). +- `providers.xiaomi.voice`: ідентифікатор голосу MiMo (типово `mimo_default`, env: `XIAOMI_TTS_VOICE`). +- `providers.xiaomi.format`: `mp3` або `wav` (типово `mp3`, env: `XIAOMI_TTS_FORMAT`). +- `providers.xiaomi.style`: необов’язкова стилістична інструкція природною мовою, що надсилається як повідомлення користувача; вона не озвучується. +- `providers.openrouter.apiKey`: API-ключ OpenRouter (env: `OPENROUTER_API_KEY`; може повторно використовувати `models.providers.openrouter.apiKey`). +- `providers.openrouter.baseUrl`: перевизначення базового URL OpenRouter TTS (типово `https://openrouter.ai/api/v1`; застарілий `https://openrouter.ai/v1` нормалізується). - `providers.openrouter.model`: ідентифікатор моделі OpenRouter TTS (типово `hexgrad/kokoro-82m`; також приймається `modelId`). -- `providers.openrouter.voice`: власний для провайдера ідентифікатор голосу (типово `af_alloy`; також приймається `voiceId`). +- `providers.openrouter.voice`: специфічний для постачальника ідентифікатор голосу (типово `af_alloy`; також приймається `voiceId`). - `providers.openrouter.responseFormat`: `mp3` або `pcm` (типово `mp3`). -- `providers.openrouter.speed`: власне для провайдера перевизначення швидкості. +- `providers.openrouter.speed`: власне для постачальника перевизначення швидкості. - `providers.microsoft.enabled`: дозволяє використання мовлення Microsoft (типово `true`; без API-ключа). - `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). - `providers.microsoft.lang`: код мови (наприклад, `en-US`). - `providers.microsoft.outputFormat`: формат виводу Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`). - - Див. формати виводу Microsoft Speech для припустимих значень; не всі формати підтримуються вбудованим транспортом на базі Edge. + - Див. формати виводу Microsoft Speech для допустимих значень; не всі формати підтримуються вбудованим transport на основі Edge. - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки відсотків (наприклад, `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: записує JSON-субтитри поруч з аудіофайлом. - `providers.microsoft.proxy`: URL проксі для запитів мовлення Microsoft. @@ -632,15 +677,15 @@ Local CLI TTS запускає налаштовану команду на хос - `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. Виконайте `openclaw doctor --fix`, щоб переписати збережену конфігурацію на `providers.microsoft`. -## Керовані моделлю перевизначення (увімкнено за замовчуванням) +## Перевизначення, керовані моделлю (увімкнено за замовчуванням) -За замовчуванням модель **може** генерувати директиви TTS для однієї відповіді. -Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо. +За замовчуванням модель **може** виводити директиви TTS для однієї відповіді. +Коли `messages.tts.auto` має значення `tagged`, ці директиви є обов’язковими для запуску аудіо. -Коли це ввімкнено, модель може генерувати директиви `[[tts:...]]`, щоб перевизначити голос -для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, -щоб надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише -в аудіо. +Коли це ввімкнено, модель може виводити директиви `[[tts:...]]` для перевизначення голосу +для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб +надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише в +аудіо. Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`. @@ -655,12 +700,12 @@ Here you go. Доступні ключі директив (коли ввімкнено): -- `provider` (ідентифікатор зареєстрованого провайдера мовлення, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `volcengine`, `vydra`, `xai` або `xiaomi`; потребує `allowProvider: true`) +- `provider` (ідентифікатор зареєстрованого постачальника мовлення, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `volcengine`, `vydra`, `xai` або `xiaomi`; потребує `allowProvider: true`) - `voice` (голос OpenAI, Gradium, Volcengine або Xiaomi), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / Gradium / MiniMax / xAI) - `model` (модель OpenAI TTS, ідентифікатор моделі ElevenLabs, модель MiniMax або модель Xiaomi MiMo TTS) або `google_model` (модель Google TTS) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (цілочисельна висота тону MiniMax, від -12 до 12; дробові значення усікаються перед запитом до MiniMax) +- `pitch` (ціле значення висоти тону MiniMax, від -12 до 12; дробові значення відсікаються перед запитом до MiniMax) - `emotion` (тег емоції Volcengine) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) @@ -680,7 +725,7 @@ Here you go. } ``` -Необов’язковий список дозволів (увімкнення перемикання провайдера, зберігаючи можливість налаштовувати інші параметри): +Необов’язковий allowlist (увімкнути перемикання постачальника, зберігаючи можливість налаштовувати інші параметри): ```json5 { @@ -696,84 +741,85 @@ Here you go. } ``` -## Налаштування для кожного користувача +## Налаштування для окремих користувачів Slash-команди записують локальні перевизначення в `prefsPath` (типово: `~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`). -Збережені поля: +Поля, що зберігаються: - `enabled` - `provider` -- `maxLength` (поріг для підсумку; типово 1500 символів) +- `maxLength` (поріг для зведення; типово 1500 символів) - `summarize` (типово `true`) -Вони перевизначають `messages.tts.*` для цього хоста. +Вони перевизначають ефективну конфігурацію з `messages.tts` разом з активним +блоком `agents.list[].tts` для цього хоста. ## Формати виводу (фіксовані) -- **Feishu / Matrix / Telegram / WhatsApp**: відповіді у форматі голосових нотаток надають перевагу Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). +- **Feishu / Matrix / Telegram / WhatsApp**: відповіді voice-note переважно використовують Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень. -- **Feishu**: коли відповідь у форматі голосової нотатки створюється як MP3/WAV/M4A або інший - імовірний аудіофайл, Plugin Feishu транскодує її у 48 кГц Ogg/Opus за допомогою +- **Feishu**: коли відповідь voice-note створюється як MP3/WAV/M4A або в іншому + імовірному форматі аудіофайлу, Plugin Feishu перекодовує її у 48 кГц Ogg/Opus за допомогою `ffmpeg` перед надсиланням нативної бульбашки `audio`. Якщо перетворення не вдається, Feishu - отримує оригінальний файл як вкладення. + отримує початковий файл як вкладення. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. -- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для цілей голосових нотаток, таких як Feishu і Telegram, OpenClaw транскодує MP3 MiniMax у 48 кГц Opus за допомогою `ffmpeg` перед доставкою. -- **Xiaomi MiMo**: типово MP3 або WAV, якщо налаштовано. Для цілей голосових нотаток, таких як Feishu і Telegram, OpenClaw транскодує вивід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставкою. -- **Local CLI**: використовує налаштований `outputFormat`. Цілі голосових нотаток - перетворюються на Ogg/Opus, а вивід для телефонії перетворюється на необроблений моно PCM 16 кГц +- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для цілей voice-note, таких як Feishu і Telegram, OpenClaw перекодовує MP3 від MiniMax у 48 кГц Opus за допомогою `ffmpeg` перед доставкою. +- **Xiaomi MiMo**: типово MP3 або WAV, якщо налаштовано. Для цілей voice-note, таких як Feishu і Telegram, OpenClaw перекодовує вихід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставкою. +- **Local CLI**: використовує налаштований `outputFormat`. Цілі voice-note + перетворюються в Ogg/Opus, а вихід для telephony перетворюється в сирий моно PCM 16 кГц за допомогою `ffmpeg`. -- **Google Gemini**: Gemini API TTS повертає необроблений PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень, транскодує у 48 кГц Opus для цілей голосових нотаток і повертає PCM безпосередньо для Talk/телефонії. -- **Gradium**: WAV для аудіовкладень, Opus для цілей голосових нотаток і `ulaw_8000` на 8 кГц для телефонії. -- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей голосових нотаток і необроблений `PCM` на 22050 Гц для Talk/телефонії. -- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST TTS endpoint xAI і повертає готове аудіовкладення; потоковий TTS WebSocket xAI не використовується цим шляхом провайдера. Нативний формат голосових нотаток Opus цим шляхом не підтримується. +- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw загортає його у WAV для аудіовкладень, перекодовує у 48 кГц Opus для цілей voice-note і повертає PCM напряму для Talk/telephony. +- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 кГц для telephony. +- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей voice-note і сирий `PCM` на 22050 Гц для Talk/telephony. +- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST TTS endpoint xAI і повертає повне аудіовкладення; потоковий TTS WebSocket xAI не використовується в цьому шляху постачальника. Нативний формат voice-note Opus у цьому шляху не підтримується. - **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні від сервісу. - - Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). + - Вбудований transport приймає `outputFormat`, але не всі формати доступні в сервісі. + - Значення форматів виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. - - Якщо налаштований формат виводу Microsoft не працює, OpenClaw повторює спробу з MP3. + - Якщо налаштований формат виводу Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). ## Поведінка auto-TTS -Коли це ввімкнено, OpenClaw: +Коли ввімкнено, OpenClaw: - пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - пропускає дуже короткі відповіді (< 10 символів). -- створює підсумок довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). +- робить зведення довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). - додає згенероване аудіо до відповіді. -Якщо відповідь перевищує `maxLength` і підсумок вимкнено (або немає API-ключа для -моделі підсумку), аудіо +Якщо відповідь перевищує `maxLength` і зведення вимкнене (або немає API-ключа для +моделі зведення), аудіо пропускається і надсилається звичайна текстова відповідь. -## Діаграма потоку +## Схема потоку ``` -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio +Відповідь -> TTS увімкнено? + ні -> надіслати текст + так -> є медіа / MEDIA: / коротка? + так -> надіслати текст + ні -> довжина > ліміту? + ні -> TTS -> додати аудіо + так -> зведення ввімкнено? + ні -> надіслати текст + так -> зробити зведення (summaryModel або agents.defaults.model.primary) + -> TTS -> додати аудіо ``` -## Використання Slash-команди +## Використання Slash-команд Є одна команда: `/tts`. Докладніше про ввімкнення див. у [Slash-командах](/uk/tools/slash-commands). Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -там `/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює. +`/voice` як нативну команду там. Текстовий `/tts ...` усе ще працює. ``` /tts off @@ -787,29 +833,29 @@ Reply -> TTS enabled? Примітки: -- Команди потребують авторизованого відправника (правила allowlist/owner як і раніше застосовуються). +- Команди потребують авторизованого відправника (правила allowlist/owner усе ще застосовуються). - Має бути ввімкнено `commands.text` або реєстрацію нативних команд. - Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`. - `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. -- Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`. +- Використовуйте конфігурацію, коли вам потрібні типові значення `inbound` або `tagged`. - `limit` і `summary` зберігаються в локальних prefs, а не в основній конфігурації. - `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS). -- `/tts status` містить видимість резервних варіантів для останньої спроби: - - успішний резервний варіант: `Fallback: -> ` плюс `Attempts: ...` +- `/tts status` включає видимість резервного перемикання для останньої спроби: + - успішне резервне перемикання: `Fallback: -> ` плюс `Attempts: ...` - помилка: `Error: ...` плюс `Attempts: ...` - детальна діагностика: `Attempt details: provider:outcome(reasonCode) latency` -- Помилки API OpenAI і ElevenLabs тепер містять розібрані деталі помилки провайдера та request id (коли їх повертає провайдер), що відображається в помилках/журналах TTS. +- Збої API OpenAI та ElevenLabs тепер містять розібрані деталі помилки постачальника та request id (коли постачальник його повертає), що відображається в помилках/логах TTS. ## Інструмент агента Інструмент `tts` перетворює текст на мовлення і повертає аудіовкладення для -доставки у відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, +доставки відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, аудіо доставляється як голосове повідомлення, а не як файлове вкладення. -Feishu може транскодувати не-Opus вивід TTS на цьому шляху, коли доступний `ffmpeg`. -WhatsApp надсилає видимий текст окремо від PTT-аудіо голосової нотатки, оскільки клієнти +Feishu може перекодовувати не-Opus вихід TTS у цьому шляху, коли доступний `ffmpeg`. +WhatsApp надсилає видимий текст окремо від голосового PTT-аудіо voice-note, оскільки клієнти не завжди коректно відображають підписи до голосових нотаток. -Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — -це тайм-аут запиту до провайдера для конкретного виклику в мілісекундах. +Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це +тайм-аут запиту до постачальника для окремого виклику в мілісекундах. ## Gateway RPC