chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
b9bc11a3a2
commit
b8c9ec50b1
@ -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. **Хуки робочої папки**: `<workspace>/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути)
|
||||
2. **Хуки плагінів**: хуки, що постачаються всередині встановлених плагінів
|
||||
3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих областей). Додаткові директорії з `hooks.internal.load.extraDirs` мають такий самий пріоритет.
|
||||
4. **Хуки робочої області**: `<workspace>/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути)
|
||||
|
||||
Хуки робочої папки можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою.
|
||||
Хуки робочої області можуть додавати нові імена хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою.
|
||||
|
||||
Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовані. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable <name>`, встановіть пакет хуків або задайте `hooks.internal.enabled=true`, щоб дозволити їх. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові директорії хуків і застарілі обробники вмикають широке виявлення.
|
||||
Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовано. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable <name>`, установіть пак хука або задайте `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 <path-or-spec>
|
||||
```
|
||||
|
||||
Npm-специфікації підтримуються лише для реєстру (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються.
|
||||
Специфікації npm підтримують лише реєстр (назва пакета + необовʼязкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються.
|
||||
|
||||
## Вбудовані хуки
|
||||
|
||||
| Хук | Події | Що робить |
|
||||
| -------------------- | ----------------------------- | ------------------------------------------------------ |
|
||||
| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `<workspace>/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` | Зберігає контекст сесії в `<workspace>/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 <hook-name>
|
||||
|
||||
<a id="session-memory"></a>
|
||||
|
||||
### Деталі session-memory
|
||||
### Докладніше про session-memory
|
||||
|
||||
Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає його в `<workspace>/memory/YYYY-MM-DD-slug.md`, використовуючи локальну дату хоста. Потрібно, щоб був налаштований `workspace.dir`.
|
||||
Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає в `<workspace>/memory/YYYY-MM-DD-slug.md`, використовуючи локальну дату хоста. Потрібно, щоб було налаштовано `workspace.dir`.
|
||||
|
||||
<a id="bootstrap-extra-files"></a>
|
||||
|
||||
### Конфігурація bootstrap-extra-files
|
||||
### Налаштування bootstrap-extra-files
|
||||
|
||||
```json
|
||||
{
|
||||
@ -198,28 +202,28 @@ openclaw hooks enable <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
Шляхи обчислюються відносно робочої папки. Завантажуються лише розпізнані базові назви 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`).
|
||||
|
||||
<a id="command-logger"></a>
|
||||
|
||||
### Деталі command-logger
|
||||
### Докладніше про command-logger
|
||||
|
||||
Логує кожну slash-команду в `~/.openclaw/logs/commands.log`.
|
||||
|
||||
<a id="boot-md"></a>
|
||||
|
||||
### Деталі 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 <hook-name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки повинні використовувати систему на основі виявлення.
|
||||
Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення.
|
||||
</Note>
|
||||
|
||||
## Довідник CLI
|
||||
|
||||
```bash
|
||||
# Показати всі хуки (додайте --eligible, --verbose або --json)
|
||||
# Перелічити всі хуки (додайте --eligible, --verbose або --json)
|
||||
openclaw hooks list
|
||||
|
||||
# Показати детальну інформацію про хук
|
||||
openclaw hooks info <hook-name>
|
||||
|
||||
# Показати зведення відповідності
|
||||
# Показати зведення щодо придатності
|
||||
openclaw hooks check
|
||||
|
||||
# Увімкнути/вимкнути
|
||||
@ -289,27 +293,27 @@ openclaw hooks enable <hook-name>
|
||||
openclaw hooks disable <hook-name>
|
||||
```
|
||||
|
||||
## Найкращі практики
|
||||
## Рекомендовані практики
|
||||
|
||||
- **Робіть обробники швидкими.** Хуки виконуються під час обробки команд. Запускайте важку роботу у фоновому режимі через `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)
|
||||
|
||||
@ -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`:
|
||||
|
||||
<Note>
|
||||
Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно вказані профілі зберігаються).
|
||||
Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно задані профілі зберігаються).
|
||||
</Note>
|
||||
|
||||
| Профіль | Містить |
|
||||
| Профіль | Включає |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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:
|
||||
```
|
||||
|
||||
<ParamField path="historySize" type="number">
|
||||
Максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів.
|
||||
Максимальна історія викликів інструментів, що зберігається для аналізу циклів.
|
||||
</ParamField>
|
||||
<ParamField path="warningThreshold" type="number">
|
||||
Поріг повторюваного шаблону без прогресу для попереджень.
|
||||
@ -152,7 +152,7 @@ x-i18n:
|
||||
Вищий поріг повторення для блокування критичних циклів.
|
||||
</ParamField>
|
||||
<ParamField path="globalCircuitBreakerThreshold" type="number">
|
||||
Поріг жорсткої зупинки для будь-якої послідовності без прогресу.
|
||||
Поріг жорсткої зупинки для будь-якого виконання без прогресу.
|
||||
</ParamField>
|
||||
<ParamField path="detectors.genericRepeat" type="boolean">
|
||||
Попереджати про повторні виклики того самого інструмента з тими самими аргументами.
|
||||
@ -165,7 +165,7 @@ x-i18n:
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не пройде.
|
||||
Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить.
|
||||
</Warning>
|
||||
|
||||
### `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:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поля запису медіамоделі">
|
||||
**Запис провайдера** (`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` (застарілий шлях пробудження сесії запитувача/доставки моделлю).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -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"`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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:
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Нотатки щодо вкладень">
|
||||
- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє.
|
||||
- Файли матеріалізуються в дочірньому робочому просторі за шляхом `.openclaw/attachments/<uuid>/` із `.manifest.json`.
|
||||
- Вміст вкладень автоматично редагується в збереженні транскрипту.
|
||||
- Входи Base64 перевіряються суворими перевірками алфавіту/заповнення та захистом від розміру до декодування.
|
||||
- Права доступу до файлів: `0700` для директорій і `0600` для файлів.
|
||||
- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
|
||||
<Accordion title="Примітки щодо вкладень">
|
||||
- Вкладення підтримуються лише для `runtime: "subagent"`. Середовище ACP їх відхиляє.
|
||||
- Файли матеріалізуються в дочірньому робочому просторі в `.openclaw/attachments/<uuid>/` із `.manifest.json`.
|
||||
- Вміст вкладень автоматично редагується під час збереження транскрипту.
|
||||
- Входи base64 перевіряються суворими перевірками алфавіту/заповнення та захистом від розміру до декодування.
|
||||
- Права доступу до файлів: `0700` для каталогів і `0600` для файлів.
|
||||
- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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 використовує вбудований каталог модел
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Пріоритет автентифікації та злиття">
|
||||
- Використовуйте `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` зберігає явне обмеження часу виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі.
|
||||
<Accordion title="Автентифікація та пріоритет злиття">
|
||||
- Використовуйте `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`.
|
||||
- Збереження маркерів є авторитетним від джерела: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів під час виконання.
|
||||
- Збереження маркерів є джерельно-авторитетним: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів середовища виконання.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -435,38 +435,38 @@ OpenClaw використовує вбудований каталог модел
|
||||
<AccordionGroup>
|
||||
<Accordion title="Каталог верхнього рівня">
|
||||
- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`).
|
||||
- `models.providers`: мапа користувацьких провайдерів верхнього рівня за ідентифікатором провайдера.
|
||||
- Безпечне редагування: використовуйте `openclaw config set models.providers.<id> '<json>' --strict-json --merge` або `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` для додаткових оновлень. `config set` відмовляє в руйнівних замінах, якщо ви не передасте `--replace`.
|
||||
- `models.providers`: мапа користувацьких провайдерів із ключами-ідентифікаторами провайдера.
|
||||
- Безпечне редагування: використовуйте `openclaw config set models.providers.<id> '<json>' --strict-json --merge` або `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` для додаткових оновлень. `config set` відхиляє руйнівні заміни, якщо ви не передасте `--replace`.
|
||||
</Accordion>
|
||||
<Accordion title="Підключення провайдера та автентифікація">
|
||||
- `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`: додаткові статичні заголовки для маршрутизації через проксі/тенант.
|
||||
</Accordion>
|
||||
<Accordion title="Перевизначення транспорту запитів">
|
||||
`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`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Записи каталогу моделей">
|
||||
- `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`, що містять лише текст, на звичайні рядки перед надсиланням запиту.
|
||||
</Accordion>
|
||||
<Accordion title="Виявлення Amazon Bedrock">
|
||||
- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автовиявлення Bedrock.
|
||||
@ -483,7 +483,7 @@ OpenClaw використовує вбудований каталог модел
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
|
||||
Вбудований плагін провайдера `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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kimi Coding">
|
||||
@ -537,7 +537,7 @@ OpenClaw використовує вбудований каталог модел
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Локальні моделі (LM Studio)">
|
||||
Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте розміщені моделі злитими для резервного використання.
|
||||
Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте злиті хостовані моделі як резервний варіант.
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax M2.7 (напряму)">
|
||||
```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`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot AI (Kimi)">
|
||||
@ -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 визначає це за можливостями кінцевої точки, а не лише за вбудованим ідентифікатором провайдера.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode">
|
||||
@ -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`
|
||||
|
||||
@ -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.<chatId>.disableAudioPreflight: true`, щоб пропустити попередню перевірку згадок у транскрипті для цієї групи.
|
||||
- Установіть `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`, щоб перевизначити поведінку для окремої теми (`true` — пропустити, `false` — примусово увімкнути).
|
||||
- Типове значення — `false` (попередня перевірка ввімкнена, коли виконуються умови перевірки згадок).
|
||||
- Встановіть `channels.telegram.groups.<chatId>.disableAudioPreflight: true`, щоб пропустити перевірки згадок у попередньому транскрипті для цієї групи.
|
||||
- Встановіть `channels.telegram.groups.<chatId>.topics.<threadId>.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 читає `<output-dir>/<media-basename>.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 читає `<output-dir>/<media-basename>.txt`, коли `--output-format` має значення `txt` (або не вказано); для форматів виводу, відмінних від `txt`, використовується резервний розбір stdout.
|
||||
- Тримайте тайм-аути розумними (`timeoutSeconds`, типово 60 с), щоб не блокувати чергу відповідей.
|
||||
- Попереднє транскрибування обробляє лише **перше** аудіовкладення для виявлення згадок. Додаткове аудіо обробляється під час основної фази розуміння медіа.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Розуміння медіа](/uk/nodes/media-understanding)
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Активація голосом](/uk/nodes/voicewake)
|
||||
- [Голосове пробудження](/uk/nodes/voicewake)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user