From b8c9ec50b1cdfcec71c0ffd8bf4a440cb6071434 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 11:12:33 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/automation/hooks.md | 142 ++++++++++++------------ docs/uk/gateway/config-tools.md | 186 ++++++++++++++++---------------- docs/uk/nodes/audio.md | 107 +++++++++--------- 3 files changed, 220 insertions(+), 215 deletions(-) diff --git a/docs/uk/automation/hooks.md b/docs/uk/automation/hooks.md index 3fadaef97..61886794e 100644 --- a/docs/uk/automation/hooks.md +++ b/docs/uk/automation/hooks.md @@ -1,31 +1,31 @@ --- read_when: - - Ви хочете автоматизацію на основі подій для `/new`, `/reset`, `/stop` і подій життєвого циклу агента + - Вам потрібна автоматизація на основі подій для `/new`, `/reset`, `/stop` і подій життєвого циклу агента - Ви хочете створювати, встановлювати або налагоджувати хуки summary: 'Хуки: автоматизація на основі подій для команд і подій життєвого циклу' title: Хуки x-i18n: - generated_at: "2026-04-26T23:10:41Z" + generated_at: "2026-04-27T11:10:52Z" model: gpt-5.4 provider: openai - source_hash: f1f9b1dc0c470502f782758e1542435f1e593750ff69a39f7f966c7d42e29c1e + source_hash: f5e63700c90456dfc26de8545ad4382d6d34bcfd8896966d88e008da5c690255 source_path: automation/hooks.md workflow: 15 --- -Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з директорій та переглядати за допомогою `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник або додаткову директорію хуків. +Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з директорій та переглядати за допомогою `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пак хука, застарілий обробник або додаткову директорію хуків. В OpenClaw є два типи хуків: -- **Внутрішні хуки** (ця сторінка): виконуються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. -- **Webhooks**: зовнішні HTTP-ендпойнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Webhooks](/uk/automation/cron-jobs#webhooks). +- **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. +- **Webhooks**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Webhooks](/uk/automation/cron-jobs#webhooks). -Хуки також можуть постачатися всередині плагінів. `openclaw hooks list` показує як окремі хуки, так і хуки, керовані плагінами. +Хуки також можуть постачатися всередині плагінів. `openclaw hooks list` показує як окремі хуки, так і хуки, якими керують плагіни. ## Швидкий старт ```bash -# Показати доступні хуки +# Перелічити доступні хуки openclaw hooks list # Увімкнути хук @@ -42,18 +42,20 @@ openclaw hooks info session-memory | Подія | Коли спрацьовує | | ------------------------ | ----------------------------------------------- | -| `command:new` | Надіслано команду `/new` | -| `command:reset` | Надіслано команду `/reset` | -| `command:stop` | Надіслано команду `/stop` | +| `command:new` | Видано команду `/new` | +| `command:reset` | Видано команду `/reset` | +| `command:stop` | Видано команду `/stop` | | `command` | Будь-яка подія команди (загальний слухач) | | `session:compact:before` | Перед тим, як Compaction підсумує історію | | `session:compact:after` | Після завершення Compaction | -| `session:patch` | Коли змінюються властивості сесії | -| `agent:bootstrap` | Перед додаванням bootstrap-файлів робочої папки | +| `session:patch` | Коли властивості сесії змінено | +| `agent:bootstrap` | Перед інʼєкцією bootstrap-файлів робочої області | | `gateway:startup` | Після запуску каналів і завантаження хуків | +| `gateway:shutdown` | Коли починається завершення роботи gateway | +| `gateway:pre-restart` | Перед очікуваним перезапуском gateway | | `message:received` | Вхідне повідомлення з будь-якого каналу | | `message:transcribed` | Після завершення транскрибування аудіо | -| `message:preprocessed` | Після завершення обробки медіа та посилань | +| `message:preprocessed` | Після завершення обробки всіх медіа та посилань | | `message:sent` | Вихідне повідомлення доставлено | ## Написання хуків @@ -80,20 +82,20 @@ metadata: # My Hook -Тут розміщується детальна документація. +Детальна документація наведена тут. ``` **Поля метаданих** (`metadata.openclaw`): -| Поле | Опис | -| --------- | --------------------------------------------------------- | -| `emoji` | Емодзі для відображення в CLI | -| `events` | Масив подій, які потрібно відстежувати | -| `export` | Іменований експорт для використання (типово `"default"`) | -| `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) | -| `requires` | Потрібні шляхи `bins`, `anyBins`, `env` або `config` | -| `always` | Обійти перевірки відповідності (boolean) | -| `install` | Методи встановлення | +| Поле | Опис | +| ---------- | ----------------------------------------------------- | +| `emoji` | Emoji для відображення в CLI | +| `events` | Масив подій, які потрібно слухати | +| `export` | Іменований експорт для використання (типово `"default"`) | +| `os` | Обовʼязкові платформи (наприклад, `["darwin", "linux"]`) | +| `requires` | Обовʼязкові шляхи `bins`, `anyBins`, `env` або `config` | +| `always` | Обійти перевірки придатності (boolean) | +| `install` | Методи встановлення | ### Реалізація обробника @@ -113,59 +115,61 @@ const handler = async (event) => { export default handler; ``` -Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте сюди, щоб надіслати користувачу), і `context` (специфічні для події дані). Контексти хуків агентів і плагінів інструментів також можуть містити `trace` — лише для читання, сумісний із W3C діагностичний контекст трасування, який плагіни можуть передавати в структуровані логи для кореляції OTEL. +Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте через push, щоб надіслати користувачеві), і `context` (дані, специфічні для події). Контексти хуків агентів і tool plugin також можуть містити `trace` — контекст діагностичного трасування лише для читання, сумісний із W3C, який плагіни можуть передавати в структуровані логи для кореляції OTEL. ### Основні моменти контексту подій **Події команд** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. -**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (специфічні для провайдера дані, зокрема `senderId`, `senderName`, `guildId`). +**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (дані, специфічні для провайдера, включно з `senderId`, `senderName`, `guildId`). **Події повідомлень** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`. **Події повідомлень** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. -**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточне збагачене тіло), `context.from`, `context.channelId`. +**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (фінальне збагачене тіло), `context.from`, `context.channelId`. **Події bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`. -**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати події patch. +**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть ініціювати події patch. **Події Compaction**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додатково містить `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. -`command:stop` фіксує, коли користувач надсилає `/stop`; це життєвий цикл скасування/команди, а не бар’єр фіналізації агента. Плагіни, яким потрібно перевірити природну фінальну відповідь і попросити агента зробити ще один прохід, повинні використовувати типізований хук плагіна `before_agent_finalize`. Див. [Plugin hooks](/uk/plugins/hooks). +`command:stop` спостерігає за тим, як користувач видає `/stop`; це життєвий цикл скасування/команди, а не фінальний барʼєр завершення агента. Плагіни, яким потрібно перевірити природну фінальну відповідь і попросити агента зробити ще один прохід, мають використовувати типізований хук плагіна `before_agent_finalize`. Див. [Plugin hooks](/uk/plugins/hooks). + +**Події життєвого циклу Gateway**: `gateway:shutdown` містить `reason` і `restartExpectedMs` та спрацьовує, коли починається завершення роботи gateway. `gateway:pre-restart` містить той самий контекст, але спрацьовує лише тоді, коли завершення роботи є частиною очікуваного перезапуску й передано скінченне значення `restartExpectedMs`. Під час завершення роботи очікування кожного хука життєвого циклу є best-effort і обмежується, щоб завершення роботи продовжувалося, навіть якщо обробник зависає. ## Виявлення хуків -Хуки виявляються з таких директорій у порядку зростання пріоритету перевизначення: +Хуки виявляються в таких директоріях у порядку зростання пріоритету перевизначення: 1. **Вбудовані хуки**: постачаються разом з OpenClaw -2. **Хуки плагінів**: постачаються всередині встановлених плагінів -3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих папок). Додаткові директорії з `hooks.internal.load.extraDirs` мають такий самий пріоритет. -4. **Хуки робочої папки**: `/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути) +2. **Хуки плагінів**: хуки, що постачаються всередині встановлених плагінів +3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих областей). Додаткові директорії з `hooks.internal.load.extraDirs` мають такий самий пріоритет. +4. **Хуки робочої області**: `/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути) -Хуки робочої папки можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою. +Хуки робочої області можуть додавати нові імена хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою. -Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовані. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable `, встановіть пакет хуків або задайте `hooks.internal.enabled=true`, щоб дозволити їх. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові директорії хуків і застарілі обробники вмикають широке виявлення. +Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовано. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable `, установіть пак хука або задайте `hooks.internal.enabled=true`, щоб виконати opt-in. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові директорії хуків і застарілі обробники виконують opt-in до широкого виявлення. -### Пакети хуків +### Паки хуків -Пакети хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: +Паки хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: ```bash openclaw plugins install ``` -Npm-специфікації підтримуються лише для реєстру (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. +Специфікації npm підтримують лише реєстр (назва пакета + необовʼязкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. ## Вбудовані хуки -| Хук | Події | Що робить | -| -------------------- | ----------------------------- | ------------------------------------------------------ | -| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | Додає додаткові bootstrap-файли за glob-шаблонами | -| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли запускається gateway | +| Хук | Події | Що він робить | +| -------------------- | ------------------------------ | ---------------------------------------------------- | +| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | Інʼєктує додаткові bootstrap-файли з glob-шаблонів | +| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` | +| boot-md | `gateway:startup` | Запускає `BOOT.md` під час старту gateway | Увімкнути будь-який вбудований хук: @@ -175,13 +179,13 @@ openclaw hooks enable -### Деталі session-memory +### Докладніше про session-memory -Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає його в `/memory/YYYY-MM-DD-slug.md`, використовуючи локальну дату хоста. Потрібно, щоб був налаштований `workspace.dir`. +Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає в `/memory/YYYY-MM-DD-slug.md`, використовуючи локальну дату хоста. Потрібно, щоб було налаштовано `workspace.dir`. -### Конфігурація bootstrap-extra-files +### Налаштування bootstrap-extra-files ```json { @@ -198,28 +202,28 @@ openclaw hooks enable } ``` -Шляхи обчислюються відносно робочої папки. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). +Шляхи обчислюються відносно робочої області. Завантажуються лише розпізнані базові імена bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). -### Деталі command-logger +### Докладніше про command-logger Логує кожну slash-команду в `~/.openclaw/logs/commands.log`. -### Деталі boot-md +### Докладніше про boot-md -Запускає `BOOT.md` з активної робочої папки під час запуску gateway. +Запускає `BOOT.md` з активної робочої області під час старту gateway. ## Хуки плагінів Плагіни можуть реєструвати типізовані хуки через Plugin SDK для глибшої інтеграції: -перехоплення викликів інструментів, модифікації промптів, керування потоком повідомлень тощо. +перехоплення викликів інструментів, зміни промптів, керування потоком повідомлень тощо. Використовуйте хуки плагінів, коли вам потрібні `before_tool_call`, `before_agent_reply`, `before_install` або інші in-process хуки життєвого циклу. -Повний довідник із хуків плагінів див. у [Plugin hooks](/uk/plugins/hooks). +Повний довідник з хуків плагінів див. у [Plugin hooks](/uk/plugins/hooks). ## Конфігурація @@ -269,19 +273,19 @@ openclaw hooks enable ``` -Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки повинні використовувати систему на основі виявлення. +Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення. ## Довідник CLI ```bash -# Показати всі хуки (додайте --eligible, --verbose або --json) +# Перелічити всі хуки (додайте --eligible, --verbose або --json) openclaw hooks list # Показати детальну інформацію про хук openclaw hooks info -# Показати зведення відповідності +# Показати зведення щодо придатності openclaw hooks check # Увімкнути/вимкнути @@ -289,27 +293,27 @@ openclaw hooks enable openclaw hooks disable ``` -## Найкращі практики +## Рекомендовані практики -- **Робіть обробники швидкими.** Хуки виконуються під час обробки команд. Запускайте важку роботу у фоновому режимі через `void processInBackground(event)`. -- **Коректно обробляйте помилки.** Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники могли виконатися. -- **Фільтруйте події рано.** Одразу повертайтеся, якщо тип/дія події не є релевантними. -- **Використовуйте конкретні ключі подій.** Надавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. +- **Робіть обробники швидкими.** Хуки виконуються під час обробки команд. Для важкої роботи використовуйте fire-and-forget через `void processInBackground(event)`. +- **Обробляйте помилки коректно.** Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники могли виконатися. +- **Фільтруйте події на ранньому етапі.** Одразу повертайтеся, якщо тип/дія події не є релевантними. +- **Використовуйте конкретні ключі подій.** Віддавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. -## Усунення проблем +## Усунення несправностей -### Хук не виявлено +### Хук не виявляється ```bash # Перевірити структуру директорії ls -la ~/.openclaw/hooks/my-hook/ # Має показати: HOOK.md, handler.ts -# Показати всі виявлені хуки +# Перелічити всі виявлені хуки openclaw hooks list ``` -### Хук не відповідає вимогам +### Хук непридатний ```bash openclaw hooks info my-hook @@ -319,13 +323,13 @@ openclaw hooks info my-hook ### Хук не виконується -1. Переконайтеся, що хук увімкнений: `openclaw hooks list` +1. Переконайтеся, що хук увімкнено: `openclaw hooks list` 2. Перезапустіть процес gateway, щоб хуки перезавантажилися. 3. Перевірте логи gateway: `./scripts/clawlog.sh | grep hook` -## Пов’язане +## Повʼязане -- [Довідник CLI: hooks](/uk/cli/hooks) +- [CLI Reference: hooks](/uk/cli/hooks) - [Webhooks](/uk/automation/cron-jobs#webhooks) - [Plugin hooks](/uk/plugins/hooks) — in-process хуки життєвого циклу плагінів -- [Конфігурація](/uk/gateway/configuration-reference#hooks) +- [Configuration](/uk/gateway/configuration-reference#hooks) diff --git a/docs/uk/gateway/config-tools.md b/docs/uk/gateway/config-tools.md index 9da2eff2e..59131c554 100644 --- a/docs/uk/gateway/config-tools.md +++ b/docs/uk/gateway/config-tools.md @@ -1,59 +1,59 @@ --- read_when: - - Налаштування політики, списків дозволених елементів або експериментальних функцій `tools.*` + - Налаштування політики, списків дозволеного або експериментальних функцій для `tools.*` - Реєстрація користувацьких провайдерів або перевизначення базових URL-адрес - Налаштування самостійно розміщених кінцевих точок, сумісних з OpenAI sidebarTitle: Tools and custom providers -summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти з підтримкою провайдера) і налаштування користувацького провайдера/base-URL +summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти на базі провайдера) та налаштування користувацького провайдера/base-URL title: Конфігурація — інструменти та користувацькі провайдери x-i18n: - generated_at: "2026-04-27T09:29:53Z" + generated_at: "2026-04-27T11:10:54Z" model: gpt-5.4 provider: openai - source_hash: 1dd86212954d2f5c11b3cf376a3a18655a657814d267cea38b42ea40a33617a4 + source_hash: 4cb18ee1b2d16309ba2eedb0408f63df58ae7f319dfe8c4cb3bf2a868415463a source_path: gateway/config-tools.md workflow: 15 --- -Ключі конфігурації `tools.*` і налаштування користувацького провайдера / base-URL. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). +Ключі конфігурації `tools.*` та налаштування користувацького провайдера / base-URL. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). ## Інструменти ### Профілі інструментів -`tools.profile` задає базовий список дозволених елементів перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволеного перед `tools.allow`/`tools.deny`: -Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно вказані профілі зберігаються). +Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно задані профілі зберігаються). -| Профіль | Містить | +| Профіль | Включає | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (так само, як якщо не задано) | +| `full` | Без обмежень (те саме, що й без значення) | ### Групи інструментів -| Група | Інструменти | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Група | Інструменти | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (не включає плагіни провайдерів) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (не включає плагіни провайдерів) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується, навіть коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Без урахування регістру, підтримує шаблони `*`. Застосовується, навіть коли Docker sandbox вимкнено. ```json5 { @@ -79,7 +79,7 @@ x-i18n: ### `tools.elevated` -Керує розширеним доступом `exec` поза межами sandbox: +Керує підвищеним доступом `exec` поза sandbox: ```json5 { @@ -97,7 +97,7 @@ x-i18n: - Перевизначення на рівні агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Розширений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль `exec` — це `node`). +- Підвищений `exec` обходить ізоляцію sandbox і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціллю `exec` є `node`). ### `tools.exec` @@ -121,7 +121,7 @@ x-i18n: ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Щоб увімкнути виявлення, встановіть `enabled: true`. Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для кожного агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Щоб увімкнути виявлення, встановіть `enabled: true`. Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремих агентів у `agents.list[].tools.loopDetection`. ```json5 { @@ -143,7 +143,7 @@ x-i18n: ``` - Максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. + Максимальна історія викликів інструментів, що зберігається для аналізу циклів. Поріг повторюваного шаблону без прогресу для попереджень. @@ -152,7 +152,7 @@ x-i18n: Вищий поріг повторення для блокування критичних циклів. - Поріг жорсткої зупинки для будь-якої послідовності без прогресу. + Поріг жорсткої зупинки для будь-якого виконання без прогресу. Попереджати про повторні виклики того самого інструмента з тими самими аргументами. @@ -165,7 +165,7 @@ x-i18n: -Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не пройде. +Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. ### `tools.web` @@ -176,14 +176,14 @@ x-i18n: web: { search: { enabled: true, - apiKey: "brave_api_key", // або змінна середовища BRAVE_API_KEY + apiKey: "brave_api_key", // або BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // необов’язково; пропустіть для авто-визначення + provider: "firecrawl", // необов’язково; не вказуйте для авто-виявлення maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -208,7 +208,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // опційно: надсилати завершені асинхронні музичні/відеозавдання безпосередньо в канал + directSend: false, // опційно: надсилати завершені асинхронні завдання музики/відео безпосередньо в канал }, audio: { enabled: true, @@ -239,7 +239,7 @@ x-i18n: - **Запис провайдера** (`type: "provider"` або пропущено): + **Запис провайдера** (`type: "provider"` або не вказано): - `provider`: ідентифікатор API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) - `model`: перевизначення ідентифікатора моделі @@ -248,20 +248,20 @@ x-i18n: **CLI-запис** (`type: "cli"`): - `command`: виконуваний файл для запуску - - `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) + - `args`: аргументи з шаблонами (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо; застарілий `{input}` приймається як псевдонім для `{{MediaPath}}`) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Значення за замовчуванням: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. - - `tools.media.image.timeoutSeconds` і відповідні записи `timeoutSeconds` для моделі зображень також застосовуються, коли агент викликає явний інструмент `image`. + - `tools.media.image.timeoutSeconds` і відповідні записи `timeoutSeconds` для моделей зображень також застосовуються, коли агент викликає явний інструмент `image`. - У разі помилки використовується наступний запис. - Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. + Автентифікація провайдера виконується у стандартному порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` і `video_generate` спочатку намагаються доставити безпосередньо в канал. Значення за замовчуванням: `false` (застарілий шлях пробудження сесії запитувача/доставки моделі). + - `asyncCompletion.directSend`: коли значення `true`, завершені асинхронні завдання `music_generate` і `video_generate` спочатку намагаються доставлятися безпосередньо в канал. Значення за замовчуванням: `false` (застарілий шлях пробудження сесії запитувача/доставки моделлю). @@ -281,9 +281,9 @@ x-i18n: ### `tools.sessions` -Керує тим, які сесії можуть бути ціллю для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можуть націлюватися інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). -За замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Значення за замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). ```json5 { @@ -301,8 +301,8 @@ x-i18n: - `self`: лише ключ поточної сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). - `agent`: будь-яка сесія, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сесії для кожного відправника під тим самим ідентифікатором агента). - - `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. - - Обмеження sandbox: коли поточна сесія ізольована в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. + - `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. + - Обмеження sandbox: коли поточна сесія ізольована в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. @@ -316,7 +316,7 @@ x-i18n: sessions_spawn: { attachments: { enabled: false, // опційно: встановіть true, щоб дозволити вбудовані файлові вкладення - maxTotalBytes: 5242880, // 5 МБ загалом для всіх файлів + maxTotalBytes: 5242880, // загалом 5 МБ для всіх файлів maxFiles: 50, maxFileBytes: 1048576, // 1 МБ на файл retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep" @@ -327,13 +327,13 @@ x-i18n: ``` - - - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. - - Файли матеріалізуються в дочірньому робочому просторі за шляхом `.openclaw/attachments//` із `.manifest.json`. - - Вміст вкладень автоматично редагується в збереженні транскрипту. - - Входи Base64 перевіряються суворими перевірками алфавіту/заповнення та захистом від розміру до декодування. - - Права доступу до файлів: `0700` для директорій і `0600` для файлів. - - Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. + + - Вкладення підтримуються лише для `runtime: "subagent"`. Середовище ACP їх відхиляє. + - Файли матеріалізуються в дочірньому робочому просторі в `.openclaw/attachments//` із `.manifest.json`. + - Вміст вкладень автоматично редагується під час збереження транскрипту. + - Входи base64 перевіряються суворими перевірками алфавіту/заповнення та захистом від розміру до декодування. + - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. + - Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. @@ -341,7 +341,7 @@ x-i18n: ### `tools.experimental` -Експериментальні прапорці вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. +Прапорці експериментальних вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -354,8 +354,8 @@ x-i18n: ``` - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- За замовчуванням: `false`, якщо лише `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цими межами, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. -- Коли ввімкнено, системний промпт також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й підтримувала не більше одного кроку `in_progress`. +- За замовчуванням: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Встановіть `true`, щоб примусово ввімкнути інструмент поза цими межами, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. +- Коли інструмент увімкнено, системний промпт також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й підтримувала не більше одного кроку `in_progress`. ### `agents.defaults.subagents` @@ -375,9 +375,9 @@ x-i18n: } ``` -- `model`: модель за замовчуванням для запущених субагентів. Якщо не вказано, субагенти успадковують модель викликувача. -- `allowAgents`: список дозволених цільових ідентифікаторів агентів за замовчуванням для `sessions_spawn`, якщо агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). -- `runTimeoutSeconds`: час очікування за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність обмеження часу. +- `model`: модель за замовчуванням для породжених субагентів. Якщо не вказано, субагенти успадковують модель викликача. +- `allowAgents`: список дозволених ідентифікаторів цільових агентів за замовчуванням для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). +- `runTimeoutSeconds`: тайм-аут за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. - Політика інструментів для окремого субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -414,19 +414,19 @@ OpenClaw використовує вбудований каталог модел ``` - - - Використовуйте `authHeader: true` + `headers` для особливих потреб автентифікації. - - Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). - - Пріоритет злиття для провайдерів з однаковими ідентифікаторами: - - Непорожні значення `baseUrl` у `models.json` агента мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації. - - Значення `apiKey` провайдера, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань file/exec) замість збереження розкритих секретів. - - Значення заголовків провайдера, керовані SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань file/exec). - - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. - - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явне обмеження часу виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + + - Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. + - Перевизначайте корінь конфігурації агента за допомогою `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілого псевдоніма змінної середовища). + - Пріоритет злиття для однакових ідентифікаторів провайдерів: + - Непорожні значення `baseUrl` в агентському `models.json` мають пріоритет. + - Непорожні значення агентського `apiKey` мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації. + - Значення `apiKey` для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань на env, `secretref-managed` для file/exec-посилань) замість збереження розкритих секретів. + - Значення заголовків для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань на env, `secretref-managed` для file/exec-посилань). + - Порожні або відсутні агентські `apiKey`/`baseUrl` повертаються до `models.providers` у конфігурації. + - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу. + - Для однакових моделей `contextTokens` зберігає явне обмеження середовища виконання, якщо воно присутнє; використовуйте це, щоб обмежити ефективний контекст без зміни рідних метаданих моделі. - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів є авторитетним від джерела: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів під час виконання. + - Збереження маркерів є джерельно-авторитетним: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів середовища виконання. @@ -435,38 +435,38 @@ OpenClaw використовує вбудований каталог модел - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). - - `models.providers`: мапа користувацьких провайдерів верхнього рівня за ідентифікатором провайдера. - - Безпечне редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відмовляє в руйнівних замінах, якщо ви не передасте `--replace`. + - `models.providers`: мапа користувацьких провайдерів із ключами-ідентифікаторами провайдера. + - Безпечне редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відхиляє руйнівні заміни, якщо ви не передасте `--replace`. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). - - `models.providers.*.apiKey`: облікові дані провайдера (бажано через SecretRef/підстановку змінних середовища). + - `models.providers.*.apiKey`: облікові дані провайдера (переважно SecretRef/підстановка env). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). - - `models.providers.*.contextWindow`: нативне вікно контексту за замовчуванням для моделей цього провайдера, коли запис моделі не задає `contextWindow`. - - `models.providers.*.contextTokens`: ефективне обмеження контексту часу виконання за замовчуванням для моделей цього провайдера, коли запис моделі не задає `contextTokens`. - - `models.providers.*.maxTokens`: обмеження вихідних токенів за замовчуванням для моделей цього провайдера, коли запис моделі не задає `maxTokens`. - - `models.providers.*.timeoutSeconds`: необов’язковий час очікування HTTP-запиту моделі для провайдера в секундах, включно з підключенням, заголовками, тілом і загальним перериванням запиту. - - `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (за замовчуванням: `true`). + - `models.providers.*.contextWindow`: рідне вікно контексту за замовчуванням для моделей цього провайдера, якщо запис моделі не задає `contextWindow`. + - `models.providers.*.contextTokens`: ефективне обмеження контексту середовища виконання за замовчуванням для моделей цього провайдера, якщо запис моделі не задає `contextTokens`. + - `models.providers.*.maxTokens`: обмеження вихідних токенів за замовчуванням для моделей цього провайдера, якщо запис моделі не задає `maxTokens`. + - `models.providers.*.timeoutSeconds`: необов’язковий тайм-аут HTTP-запиту моделі для кожного провайдера в секундах, включно з підключенням, заголовками, тілом і повним перериванням запиту. + - `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додає `options.num_ctx` у запити (за замовчуванням: `true`). - `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. - - `models.providers.*.baseUrl`: базова URL-адреса API вищого рівня. - - `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації проксі/орендаря. + - `models.providers.*.baseUrl`: базова URL-адреса API верхнього рівня. + - `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через проксі/тенант. `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделі. - - `request.headers`: додаткові заголовки (зливаються зі стандартними заголовками провайдера). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (із `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (із `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - - `request.tls`: перевизначення TLS для прямих підключень. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS розв’язується в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явний дозвіл оператора для довірених самостійно розміщених кінцевих точок, сумісних з OpenAI). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. За замовчуванням `false`. + - `request.headers`: додаткові заголовки (зливаються зі стандартними для провайдера). Значення підтримують SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (із `token`), `"header"` (із `headerName`, `value`, необов’язковим `prefix`). + - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (із `url`). Обидва режими підтримують необов’язковий підоб’єкт `tls`. + - `request.tls`: перевизначення TLS для прямих підключень. Поля: `ca`, `cert`, `key`, `passphrase` (усі підтримують SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: коли значення `true`, дозволяє HTTPS до `baseUrl`, якщо DNS розв’язується в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явне вмикання оператором для довірених самостійно розміщених кінцевих точок, сумісних з OpenAI). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. За замовчуванням `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. - - `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. Це перевизначає `contextWindow` на рівні провайдера для цієї моделі. - - `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту часу виконання. Це перевизначає `contextTokens` на рівні провайдера; використовуйте, коли потрібен менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі; `openclaw models list` показує обидва значення, коли вони відрізняються. - - `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw під час виконання примусово встановлює це значення в `false`. Порожній/пропущений `baseUrl` зберігає стандартну поведінку OpenAI. - - `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для чат-ендпойнтів OpenAI-compatible, що підтримують лише рядки. Коли `true`, OpenClaw згортає масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. + - `models.providers.*.models.*.contextWindow`: метадані рідного вікна контексту моделі. Це перевизначає `contextWindow` рівня провайдера для цієї моделі. + - `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту середовища виконання. Це перевизначає `contextTokens` рівня провайдера; використовуйте, коли потрібен менший ефективний бюджет контексту, ніж рідний `contextWindow` моделі; `openclaw models list` показує обидва значення, коли вони відрізняються. + - `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім нерідним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час виконання. Порожній/відсутній `baseUrl` зберігає стандартну поведінку OpenAI. + - `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для чат-ендпоінтів, сумісних з OpenAI і підтримують лише рядки. Коли значення `true`, OpenClaw перетворює масиви `messages[].content`, що містять лише текст, на звичайні рядки перед надсиланням запиту. - `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автовиявлення Bedrock. @@ -483,7 +483,7 @@ OpenClaw використовує вбудований каталог модел - Вбудований плагін провайдера `cerebras` можна налаштувати через `openclaw onboard --auth-choice cerebras-api-key`. Явну конфігурацію провайдера використовуйте лише тоді, коли потрібно перевизначити стандартні значення. + Вбудований плагін провайдера `cerebras` може налаштувати це через `openclaw onboard --auth-choice cerebras-api-key`. Використовуйте явну конфігурацію провайдера лише для перевизначення стандартних значень. ```json5 { @@ -517,7 +517,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. + Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -537,7 +537,7 @@ OpenClaw використовує вбудований каталог модел - Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте розміщені моделі злитими для резервного використання. + Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте злиті хостовані моделі як резервний варіант. ```json5 @@ -574,7 +574,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей за замовчуванням містить лише M2.7. На шляху потокової передачі, сумісному з Anthropic, OpenClaw за замовчуванням вимикає thinking MiniMax, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. + Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. За замовчуванням каталог моделей містить лише M2.7. На шляху потокової передачі, сумісному з Anthropic, OpenClaw за замовчуванням вимикає thinking MiniMax, якщо ви явно не встановите `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -611,9 +611,9 @@ OpenClaw використовує вбудований каталог модел } ``` - Для китайської кінцевої точки: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. + Для кінцевої точки в Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. - Нативні кінцеві точки Moonshot оголошують сумісність потокового використання на спільному транспорті `openai-completions`, і OpenClaw орієнтується на можливості кінцевої точки, а не лише на ідентифікатор вбудованого провайдера. + Власні кінцеві точки Moonshot рекламують сумісність використання потокової передачі на спільному транспорті `openai-completions`, і OpenClaw визначає це за можливостями кінцевої точки, а не лише за вбудованим ідентифікатором провайдера. @@ -680,7 +680,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. + Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` є допустимими псевдонімами. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальна кінцева точка: `https://api.z.ai/api/paas/v4` - Кінцева точка для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4` diff --git a/docs/uk/nodes/audio.md b/docs/uk/nodes/audio.md index d97fb2229..3b225ff83 100644 --- a/docs/uk/nodes/audio.md +++ b/docs/uk/nodes/audio.md @@ -1,52 +1,52 @@ --- read_when: - Зміна транскрибування аудіо або обробки медіа -summary: Як вхідні аудіо- та голосові повідомлення завантажуються, транскрибуються та додаються до відповідей -title: Аудіо- та голосові повідомлення +summary: Як вхідні аудіоповідомлення/голосові нотатки завантажуються, транскрибуються та вставляються у відповіді +title: Аудіо та голосові нотатки x-i18n: - generated_at: "2026-04-27T07:08:22Z" + generated_at: "2026-04-27T11:10:51Z" model: gpt-5.4 provider: openai - source_hash: d2795f306a0095e2355b39cb600698d02076aba5a64ad5ba2a22f7752adbe5db + source_hash: bd987f4e7475b5c4e46fad9cf44385111ad229f12e4554a16b8f0fa91f7e9d8c source_path: nodes/audio.md workflow: 15 --- -# Аудіо / голосові повідомлення (2026-01-17) +# Аудіо / голосові нотатки (2026-01-17) ## Що працює -- **Розуміння медіа (аудіо)**: якщо розуміння аудіо увімкнене (або визначається автоматично), OpenClaw: - 1. Знаходить перше вкладення з аудіо (локальний шлях або URL) і за потреби завантажує його. +- **Розуміння медіа (аудіо)**: Якщо розуміння аудіо ввімкнене (або автоматично визначене), OpenClaw: + 1. Знаходить перше аудіовкладення (локальний шлях або URL) і завантажує його, якщо потрібно. 2. Застосовує `maxBytes` перед надсиланням до кожного запису моделі. - 3. Запускає перший відповідний запис моделі за порядком (провайдер або CLI). - 4. Якщо це завершується помилкою або пропуском (розмір/тайм-аут), пробує наступний запис. + 3. Запускає перший придатний запис моделі за порядком (провайдер або CLI). + 4. Якщо це завершується помилкою або пропускається (розмір/тайм-аут), пробує наступний запис. 5. У разі успіху замінює `Body` блоком `[Audio]` і встановлює `{{Transcript}}`. -- **Розбір команд**: коли транскрибування успішне, `CommandBody`/`RawBody` встановлюються в транскрипт, тож slash-команди продовжують працювати. -- **Докладне логування**: у `--verbose` ми логуємо, коли запускається транскрибування і коли воно замінює тіло повідомлення. +- **Розбір команд**: Коли транскрибування успішне, `CommandBody`/`RawBody` встановлюються в текст транскрипту, щоб slash-команди й далі працювали. +- **Докладне журналювання**: У `--verbose` ми логуємо, коли запускається транскрибування і коли воно замінює тіло повідомлення. ## Автовизначення (типово) Якщо ви **не налаштовуєте моделі** і `tools.media.audio.enabled` **не** встановлено в `false`, -OpenClaw автоматично визначає в такому порядку і зупиняється на першому робочому варіанті: +OpenClaw автоматично визначає в такому порядку й зупиняється на першому робочому варіанті: 1. **Активна модель відповіді**, якщо її провайдер підтримує розуміння аудіо. 2. **Локальні CLI** (якщо встановлені) - `sherpa-onnx-offline` (потребує `SHERPA_ONNX_MODEL_DIR` з encoder/decoder/joiner/tokens) - - `whisper-cli` (із `whisper-cpp`; використовує `WHISPER_CPP_MODEL` або вбудовану tiny-модель) + - `whisper-cli` (з `whisper-cpp`; використовує `WHISPER_CPP_MODEL` або вбудовану tiny-модель) - `whisper` (Python CLI; автоматично завантажує моделі) 3. **Gemini CLI** (`gemini`) з використанням `read_many_files` 4. **Авторизація провайдера** - Спочатку пробуються налаштовані записи `models.providers.*`, які підтримують аудіо - - Вбудований резервний порядок: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral + - Порядок вбудованих запасних варіантів: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral Щоб вимкнути автовизначення, встановіть `tools.media.audio.enabled: false`. -Щоб налаштувати вручну, встановіть `tools.media.audio.models`. -Примітка: виявлення бінарних файлів є best-effort на macOS/Linux/Windows; переконайтеся, що CLI доступний у `PATH` (ми розгортаємо `~`), або задайте явну CLI-модель із повним шляхом до команди. +Щоб налаштувати вручну, задайте `tools.media.audio.models`. +Примітка: виявлення бінарних файлів виконується в режимі best-effort на macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну CLI-модель з повним шляхом до команди. ## Приклади конфігурації -### Провайдер + резервний CLI (OpenAI + Whisper CLI) +### Провайдер + запасний CLI-варіант (OpenAI + Whisper CLI) ```json5 { @@ -70,7 +70,7 @@ OpenClaw автоматично визначає в такому порядку } ``` -### Лише провайдер із обмеженням за scope +### Лише провайдер із керуванням областю дії ```json5 { @@ -134,7 +134,7 @@ OpenClaw автоматично визначає в такому порядку } ``` -### Надсилати транскрипт у чат (опціонально) +### Надсилати транскрипт назад у чат (за бажанням) ```json5 { @@ -142,7 +142,7 @@ OpenClaw автоматично визначає в такому порядку media: { audio: { enabled: true, - echoTranscript: true, // типове значення — false + echoTranscript: true, // типово false echoFormat: '📝 "{transcript}"', // необов’язково, підтримує {transcript} models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }], }, @@ -151,71 +151,72 @@ OpenClaw автоматично визначає в такому порядку } ``` -## Примітки й обмеження +## Примітки та обмеження -- Авторизація провайдера дотримується стандартного порядку авторизації моделей (профілі авторизації, змінні середовища, `models.providers.*.apiKey`). -- Деталі налаштування Groq: [Groq](/uk/providers/groq). -- Deepgram використовує `DEEPGRAM_API_KEY`, коли застосовується `provider: "deepgram"`. -- Деталі налаштування Deepgram: [Deepgram (транскрибування аудіо)](/uk/providers/deepgram). -- Деталі налаштування Mistral: [Mistral](/uk/providers/mistral). -- SenseAudio використовує `SENSEAUDIO_API_KEY`, коли застосовується `provider: "senseaudio"`. -- Деталі налаштування SenseAudio: [SenseAudio](/uk/providers/senseaudio). +- Авторизація провайдера виконується за стандартним порядком авторизації моделей (профілі авторизації, змінні середовища, `models.providers.*.apiKey`). +- Докладніше про налаштування Groq: [Groq](/uk/providers/groq). +- Deepgram підхоплює `DEEPGRAM_API_KEY`, коли використовується `provider: "deepgram"`. +- Докладніше про налаштування Deepgram: [Deepgram (транскрибування аудіо)](/uk/providers/deepgram). +- Докладніше про налаштування Mistral: [Mistral](/uk/providers/mistral). +- SenseAudio підхоплює `SENSEAUDIO_API_KEY`, коли використовується `provider: "senseaudio"`. +- Докладніше про налаштування SenseAudio: [SenseAudio](/uk/providers/senseaudio). - Провайдери аудіо можуть перевизначати `baseUrl`, `headers` і `providerOptions` через `tools.media.audio`. -- Типове обмеження розміру — 20MB (`tools.media.audio.maxBytes`). Завелике аудіо пропускається для цієї моделі, і пробується наступний запис. -- Крихітні/порожні аудіофайли менш ніж 1024 байти пропускаються ще до транскрибування через провайдера/CLI. -- Типове значення `maxChars` для аудіо **не встановлено** (повний транскрипт). Встановіть `tools.media.audio.maxChars` або `maxChars` для окремого запису, щоб обрізати вивід. -- Типове значення OpenAI за замовчуванням — `gpt-4o-mini-transcribe`; установіть `model: "gpt-4o-transcribe"` для вищої точності. -- Використовуйте `tools.media.audio.attachments`, щоб обробляти кілька голосових повідомлень (`mode: "all"` + `maxAttachments`). +- Типове обмеження розміру — 20 МБ (`tools.media.audio.maxBytes`). Аудіо, що перевищує розмір, пропускається для цієї моделі, і пробується наступний запис. +- Дуже малі/порожні аудіофайли менше ніж 1024 байти пропускаються до транскрибування провайдером/CLI. +- Типове значення `maxChars` для аудіо **не задане** (повний транскрипт). Задайте `tools.media.audio.maxChars` або `maxChars` для окремого запису, щоб обрізати результат. +- Типове значення OpenAI — `gpt-4o-mini-transcribe`; задайте `model: "gpt-4o-transcribe"` для вищої точності. +- Використовуйте `tools.media.audio.attachments` для обробки кількох голосових нотаток (`mode: "all"` + `maxAttachments`). - Транскрипт доступний у шаблонах як `{{Transcript}}`. - `tools.media.audio.echoTranscript` типово вимкнено; увімкніть його, щоб надсилати підтвердження транскрипту назад у вихідний чат перед обробкою агентом. -- `tools.media.audio.echoFormat` налаштовує текст такого підтвердження (placeholder: `{transcript}`). -- Вивід CLI в stdout обмежено (5MB); робіть вивід CLI лаконічним. +- `tools.media.audio.echoFormat` налаштовує текст такого відлуння (заповнювач: `{transcript}`). +- Вивід CLI в stdout обмежено (5 МБ); робіть вивід CLI лаконічним. +- `args` для CLI мають використовувати `{{MediaPath}}` для локального шляху до аудіофайлу. Застарілі заповнювачі `{input}` зі старіших конфігурацій `audio.transcription.command` приймаються як сумісний псевдонім і мігрують до `{{MediaPath}}`. ### Підтримка проксі через змінні середовища -Транскрибування аудіо через провайдера підтримує стандартні змінні середовища для вихідного проксі: +Транскрибування аудіо через провайдера враховує стандартні змінні середовища для вихідного проксі: - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -Якщо змінні середовища проксі не встановлені, використовується прямий вихід. Якщо конфігурація проксі некоректна, OpenClaw логує попередження і повертається до прямого отримання. +Якщо змінні середовища проксі не задані, використовується прямий вихід у мережу. Якщо конфігурація проксі некоректна, OpenClaw логує попередження і повертається до прямого отримання. ## Виявлення згадок у групах -Коли для групового чату встановлено `requireMention: true`, OpenClaw тепер транскрибує аудіо **до** перевірки згадок. Це дає змогу обробляти голосові повідомлення, навіть якщо згадки містяться в них. +Коли для групового чату встановлено `requireMention: true`, OpenClaw тепер транскрибує аудіо **до** перевірки згадок. Це дає змогу обробляти голосові нотатки, навіть якщо вони містять згадки. **Як це працює:** -1. Якщо голосове повідомлення не має текстового тіла, а для групи потрібні згадки, OpenClaw виконує «попереднє» транскрибування. -2. Транскрипт перевіряється на шаблони згадок (наприклад, `@BotName`, emoji-тригери). +1. Якщо голосове повідомлення не має текстового тіла і для групи потрібні згадки, OpenClaw виконує "попереднє" транскрибування. +2. Транскрипт перевіряється на шаблони згадок (наприклад, `@BotName`, тригери-емодзі). 3. Якщо згадку знайдено, повідомлення проходить через повний конвеєр відповіді. -4. Транскрипт використовується для виявлення згадок, щоб голосові повідомлення могли пройти перевірку на згадку. +4. Транскрипт використовується для виявлення згадок, щоб голосові нотатки могли пройти перевірку на згадку. **Резервна поведінка:** - Якщо транскрибування під час попередньої перевірки завершується помилкою (тайм-аут, помилка API тощо), повідомлення обробляється на основі виявлення згадок лише в тексті. - Це гарантує, що змішані повідомлення (текст + аудіо) ніколи не буде помилково відкинуто. -**Опціональне вимкнення для окремої Telegram group/topic:** +**Вимкнення для окремої Telegram-групи/теми:** -- Установіть `channels.telegram.groups..disableAudioPreflight: true`, щоб пропустити попередню перевірку згадок у транскрипті для цієї групи. -- Установіть `channels.telegram.groups..topics..disableAudioPreflight`, щоб перевизначити поведінку для окремої теми (`true` — пропустити, `false` — примусово увімкнути). -- Типове значення — `false` (попередня перевірка ввімкнена, коли виконуються умови перевірки згадок). +- Встановіть `channels.telegram.groups..disableAudioPreflight: true`, щоб пропустити перевірки згадок у попередньому транскрипті для цієї групи. +- Встановіть `channels.telegram.groups..topics..disableAudioPreflight`, щоб перевизначати для окремої теми (`true` — пропустити, `false` — примусово ввімкнути). +- Типове значення — `false` (попереднє транскрибування ввімкнене, коли збігаються умови перевірки згадок). -**Приклад:** користувач надсилає голосове повідомлення з текстом «Hey @Claude, what's the weather?» у Telegram group з `requireMention: true`. Голосове повідомлення транскрибується, згадка виявляється, і агент відповідає. +**Приклад:** Користувач надсилає голосову нотатку зі словами "Привіт @Claude, яка погода?" у групі Telegram з `requireMention: true`. Голосову нотатку транскрибують, виявляють згадку, і агент відповідає. -## Поширені нюанси +## Підводні камені -- Правила scope використовують принцип «перший збіг перемагає». `chatType` нормалізується до `direct`, `group` або `room`. -- Переконайтеся, що ваш CLI завершується з кодом 0 і виводить звичайний текст; JSON потрібно обробити, наприклад, через `jq -r .text`. -- Для `parakeet-mlx`, якщо ви передаєте `--output-dir`, OpenClaw читає `/.txt`, коли `--output-format` має значення `txt` (або не вказано); формати виводу, відмінні від `txt`, повертаються до розбору stdout. -- Встановлюйте розумні тайм-аути (`timeoutSeconds`, типово 60 с), щоб не блокувати чергу відповідей. -- Попереднє транскрибування обробляє лише **перше** аудіовкладення для виявлення згадок. Додаткові аудіо обробляються під час основної фази розуміння медіа. +- Для правил області дії використовується принцип first-match wins. `chatType` нормалізується до `direct`, `group` або `room`. +- Переконайтеся, що ваш CLI завершується з кодом 0 і виводить звичайний текст; JSON треба обробити через `jq -r .text`. +- Для `parakeet-mlx`, якщо ви передаєте `--output-dir`, OpenClaw читає `/.txt`, коли `--output-format` має значення `txt` (або не вказано); для форматів виводу, відмінних від `txt`, використовується резервний розбір stdout. +- Тримайте тайм-аути розумними (`timeoutSeconds`, типово 60 с), щоб не блокувати чергу відповідей. +- Попереднє транскрибування обробляє лише **перше** аудіовкладення для виявлення згадок. Додаткове аудіо обробляється під час основної фази розуміння медіа. ## Пов’язане - [Розуміння медіа](/uk/nodes/media-understanding) - [Режим розмови](/uk/nodes/talk) -- [Активація голосом](/uk/nodes/voicewake) +- [Голосове пробудження](/uk/nodes/voicewake)